Start, refresh, and return

Before you start

These are the calls your agent makes, in the tools' own names and fields. BLOM's note and tool descriptions tell your agent the same when it connects, so you seldom need to spell them out. Read them to follow its work, or to connect another agent.

• Every change, an export included, takes a new requestId, a UUID.
• Keep each write's requestId and exact input until its outcome is known. Sent again, the same call returns the first result, with receipt.replayed true, and changes nothing more. The same requestId with other input is refused, with idempotency_conflict.
• Use the input schemas discovery returns: a tool refuses a field it doesn't list. Each tool's description ends with an example of its arguments.
• Read BLOM's primer with blom_read_primer before the first task.

Start

1. Find work

   Read the next actions waiting on the agent with blom_read_queue, each with its claim state, or the work list by priority and rank with blom_read_work_list. Or start from a task ID you were given. To record new work, capture a task with blom_capture_task.

2. Export the task's context

   Call blom_export_context with mode: "initial" and the taskId. Read its completeness.complete, and each manifest part's status and reason. While nextCursor isn't null, call it again with mode: "page" and that cursor, under a new requestId. An incomplete export stays incomplete: get what's missing before relying on it.

3. Claim the step

   Call blom_claim with the taskId, the nextActionId, and expected: { task, action } set to the export's task.taskRevision and nextAction.revision. On a Job, scope names the target items the work touches.

{
      "requestId": "0198f0c2-7c00-7000-8000-00000000a001",
      "taskId": "0198f0c2-7c00-7000-8000-00000000b001",
      "nextActionId": "0198f0c2-7c00-7000-8000-00000000c001",
      "expected": { "task": "taskRevision as read", "action": "next action revision as read" }
    }

A claim holds a lease: 30 minutes for an agent, unless the task's process says otherwise. Only an Active claim is permission to work. A claim may be Waiting behind another, or need the agent to acknowledge an overlap first, and a Waiting claim isn't permission.

Claiming a Job assigns it to the agent, and takes it over at once from anyone who holds it. A report someone else holds is refused, with held, until their claim is Stale. Next actions and claims has the people's side.

Refresh

1. Refresh the context

   Call blom_export_context with mode: "refresh", the taskId, and the last export's baselineId and contextVersion. Apply its content, and drop the parts removedPartIds names. A deliveryKind of fallback replaces the whole view.

2. Renew the claim

   Before the lease ends, call blom_renew_claim with the claimId, expected: { task, claim }, and a short note on progress.

   If someone takes the Job over, or reassigns it, the agent's claim ends, and its next call on it is refused with claim_ended. Stop work on the step, and read the task again.

3. Or give the step back

   To stop unfinished, call blom_release_claim with a reason. The next action stays current and returns to the queue, and a Job assigned to the agent is unassigned.

Renewing never revives a Stale claim. Take it back with blom_claim and mode: "resume", naming it in priorClaimId. A claim someone else took over has ended, so stop work on it.

Return

1. Complete the step, if it's finished

   Call blom_complete with the outcomeId of one of the next action's outcomes. Add a note, a reference to what was done, such as a pull request, and a suggestion for the next action, or leave the next action blank. On a Release step, name the environment the work reached with environment. Completing ends the claim.

2. Return a closure

   Call blom_return_closure with a sessionName and what the session did: what changed and why, its artifacts, the checks and their results, the evidence, its assumptions and blockers, and the remaining work. Its lists are explicit: an empty list means none.

Not finished? Return a closure alone. Never complete a step just to close a session.

{
      "requestId": "0198f0c2-7c00-7000-8000-00000000a002",
      "taskId": "0198f0c2-7c00-7000-8000-00000000b001",
      "sessionName": "invite-expiry-build, first session",
      "reportedClaimId": "0198f0c2-7c00-7000-8000-00000000d001",
      "changes": [
        { "description": "Invitations expire after 7 days.", "why": "The brief's desired outcome.", "classification": "completed" }
      ],
      "artifacts": [],
      "checks": [
        { "name": "Unit tests", "result": "passed", "reason": null, "links": [] },
        { "name": "Browser tests", "result": "notRun", "reason": "No browser was available in this session.", "links": [] }
      ],
      "evidence": [],
      "assumptions": [],
      "blockers": [],
      "remainingWork": ["Review the change."],
      "foundTaskIds": [],
      "contextReferences": [],
      "nextActorId": null
    }

A check that wasn't run says why. Failed checks, checks not run, and incomplete context are reported as they are.

The agent can report its own model use once, with tokenUse on the completion or in the closure, never both. Token use shows where it goes. People read closures in the task's Handoffs section.

Related