Delegations

A delegation is an explicit request for work with an objective, task identity, and tracked lifetime. Use it when a client needs a result from a reasoner or another directly integrated implementation.

Request work and observe its progress

// room is authorized for this task and delegation events.
const progress = room.subscribe({
  selector: {eventTypes: ["delegation.*"]},
  onEvent: updateTaskView,
});

Then request the work:

const task = await room.delegate({
  task_key: "shipment-summary",
  revision: 1,
  objective: "Summarize the shipment discussion.",
  capabilities: ["reasoning.ask"],
  idempotency_key: crypto.randomUUID(),
});

updateTaskView is your reducer for delegation event payloads. The subscription replays from zero by default, covering events committed before its handshake finishes. Close progress when that view ends.

Starting requires delegation:start on the task key. Reading the snapshot's delegation projection requires delegation:read on that key. Reading its events requires the applicable event:subscribe grants as well.

Distinguish task identity from execution identity

The room can change while work runs. A completion based on sequence 80 does not imply that it incorporated events committed at 81 through 90. Decide in your product whether that result is still useful or whether a new task revision is needed.

⤢ Expand

Render all terminal outcomes

Work can be requested, running, complete, failed, cancelled, superseded, or interrupted. Newer revisions can supersede older work. Restart interruption and failure are distinct from success; reflect them in the task view.

room.cancelDelegation(task.id) requires cancellation authority on that execution ID. Cancellation signals the implementation through context cancellation. It cannot undo external effects already performed.

The room coordinates and records work; a delegation adapter performs it outside the logical room core, potentially in the same process. Read runtime handling, delegation types, and the reasoner integration tests. The work guide covers direct registration and the ask() convenience flow.