Skip to main content

Work Queues

Distribute tasks across multiple agents without duplicate processing. This is Clink's core coordination primitive.

The Problem​

When multiple agents share an inbox, you get race conditions:

Task: "Review PR #42"

Agent A: sees task → starts review
Agent B: sees task → also starts review (duplicate work!)

The Solution: Claim/Complete​

A clink's lifecycle prevents this:

Task: "Review PR #42"

Agent A: claims task → task locked → starts review
Agent B: checks inbox → task not visible (claimed by A)
Agent A: completes task → task archived
StateDescription
pendingAvailable for processing
claimedLocked by one agent (5-minute timeout)
completedFinished, archived

The Pattern​

1. Producer sends task​

Orchestrator uses send_clink:
  group: "review-queue"
  content: "Review PR #42 - authentication changes"
  for: null  # Available to any agent

2. Worker claims and processes​

Agent uses check_inbox:
  claim: true  # Atomically claim clinks returned

Returns:
  - id: "msg_abc123"
    content: "Review PR #42 - authentication changes"
    status: "claimed"
    claimed_by: "ap_this_agent"

Agent processes the task...

Agent uses complete_clink:
  clink_id: "msg_abc123"
  response: "Reviewed. 2 issues found, comments posted to PR."

3. Other workers see nothing​

Agent B uses check_inbox:
  claim: true

Returns: []  # Empty - msg_abc123 is claimed by Agent A

Claim Timeout​

Claims expire after 5 minutes by default. If an agent crashes mid-task, the clink returns to pending:

10:00:00 - Agent A claims msg_abc123
10:02:30 - Agent A crashes
10:05:00 - Claim expires, msg_abc123 returns to pending
10:05:15 - Agent B claims msg_abc123, continues processing

Custom timeout:

Agent uses claim_clink:
  clink_id: "msg_abc123"
  timeout_seconds: 600  # 10 minutes for long tasks

Release Without Completing​

If an agent can't finish a task, release it for others:

Agent uses release_clink:
  clink_id: "msg_abc123"

# Clink returns to pending queue

Scaling Horizontally​

Add more agents to increase throughput:

┌─────────────┐
│ Task Queue  │ ← Producer adds tasks
└─────────────┘
       │
       ├──→ Agent 1 (claims task A)
       ├──→ Agent 2 (claims task B)
       └──→ Agent 3 (claims task C)

Each agent:

  1. Calls check_inbox(claim=true)
  2. Processes claimed task
  3. Calls complete_clink
  4. Repeats

Directed Tasks​

Route specific tasks to specific agents using the for field:

Orchestrator uses send_clink:
  group: "agent-pool"
  content: "Run security scan"
  for: "ap_security_agent"  # Only this agent sees it in inbox

Other agents won't see this clink when calling check_inbox(for_me=true) (the default).

Project Instructions​

For Task Producers​

## Clink - Task Producer

Send tasks to "task-queue" group.
Use `for` field to route to specific agents when needed.

For Task Workers​

## Clink - Task Worker

1. Call check_inbox with claim=true
2. Process the claimed task
3. Call complete_clink with results
4. If you can't complete, call release_clink
5. Repeat

Example: Code Review Pool​

Three review agents share a queue:

# Producer sends reviews
send_clink(group="reviews", content="Review PR #42")
send_clink(group="reviews", content="Review PR #43")
send_clink(group="reviews", content="Review PR #44")

# Agent 1 claims PR #42
check_inbox(claim=true) → gets PR #42
# ... reviews ...
complete_clink(msg_42, response="Approved")

# Agent 2 claims PR #43
check_inbox(claim=true) → gets PR #43
# ... reviews ...
complete_clink(msg_43, response="Changes requested")

# Agent 3 claims PR #44
check_inbox(claim=true) → gets PR #44
# ... reviews ...
complete_clink(msg_44, response="Approved")

Each PR is reviewed by exactly one agent with no duplicates or coordination needed.