AgentWorkshop.Work (AgentWorkshop v0.3.0)

Copy Markdown View Source

Work board for agent coordination.

A structured task tracker where work items flow through a lifecycle. Agents poll for work matching their role, claim it, and advance it through states. Dependencies between items handle ordering.

Work item lifecycle

new → ready → claimed → in_progress → done
                                     → failed
                   ↑
             blocked (unmet dependency)
             cancelled

Usage from IEx

import AgentWorkshop.Workshop

# Add work
work(:cache, "Implement LRU cache",
  type: :code, spec: "LRU with 1000 entries and TTL")
work(:cache_review, "Review cache implementation",
  type: :review, depends_on: [:cache])
work(:cache_tests, "Write cache tests",
  type: :test, depends_on: [:cache])

# Browse
board()                    # full board
board(status: :ready)      # items ready to pick up
board(type: :code)         # only code tasks

# Work on items
claim(:cache, :impl)      # agent claims the task
start_work(:cache)        # mark in progress
complete(:cache)          # mark done, unblocks dependents
fail(:cache, "tests broke")

Agent polling

Agents check the board for work matching their type:

every(:coder, "Check board(type: :code, status: :ready) and work on one item",
  interval: :timer.minutes(2))

Summary

Types

t()

Functions

add(id, title, opts \\ [])

Add a work item to the board.

cancel(id)

Cancel a work item.

claim(id, agent_name)

Claim a work item for an agent.

clear()

Clear all work items.

complete(id, result \\ nil)

Mark a work item as done. Unblocks dependents.

fail(id, error \\ nil)

Mark a work item as failed.

get(id)

Get a work item by ID.

list(filters \\ [])

List work items, optionally filtered.

remove(id)

Remove a work item from the board entirely.

start_work(id)

Mark a work item as in progress.

summary()

Summary counts by status.

Types

t()

@type t() :: %AgentWorkshop.Work{
  claimed_at: DateTime.t() | nil,
  claimed_by: atom() | nil,
  completed_at: DateTime.t() | nil,
  created_at: DateTime.t(),
  depends_on: [atom()],
  error: String.t() | nil,
  id: atom(),
  metadata: map(),
  priority: non_neg_integer(),
  result: String.t() | nil,
  spec: String.t() | nil,
  started_at: DateTime.t() | nil,
  status: atom(),
  title: String.t(),
  type: atom()
}

Functions

add(id, title, opts \\ [])

@spec add(atom(), String.t(), keyword()) :: :ok

Add a work item to the board.

cancel(id)

@spec cancel(atom()) :: :ok | {:error, term()}

Cancel a work item.

claim(id, agent_name)

@spec claim(atom(), atom()) :: :ok | {:error, term()}

Claim a work item for an agent.

Uses atomic ETS take-and-reinsert to prevent race conditions when multiple board workers poll simultaneously.

clear()

@spec clear() :: :ok

Clear all work items.

complete(id, result \\ nil)

@spec complete(atom(), String.t() | nil) :: :ok | {:error, term()}

Mark a work item as done. Unblocks dependents.

fail(id, error \\ nil)

@spec fail(atom(), String.t() | nil) :: :ok | {:error, term()}

Mark a work item as failed.

get(id)

@spec get(atom()) :: t() | nil

Get a work item by ID.

list(filters \\ [])

@spec list(keyword()) :: [t()]

List work items, optionally filtered.

remove(id)

@spec remove(atom()) :: :ok

Remove a work item from the board entirely.

start_work(id)

@spec start_work(atom()) :: :ok | {:error, term()}

Mark a work item as in progress.

summary()

@spec summary() :: map()

Summary counts by status.