Operator control workflows

Use Kestrel's operator controls when work is already running or waiting for human input. Three API calls support that workflow:

• operator.inbox
• operator.thread
• operator.control

The CLI and Kestrel One build their run controls on these calls. Use them when you need to inspect or steer an existing thread instead of starting the task again.

The control loop

read inbox -> open thread -> apply control action -> inspect operator.controlled event

Use that loop when a run is blocked, a child thread needs attention, or the next step needs human direction.

SDK example

import { KestrelClient } from "@kestrel-agents/sdk/runner";
 
const client = new KestrelClient({
  target: {
    kind: "remote",
    baseUrl: process.env.KESTREL_RUNNER_SERVICE_URL!,
    authToken: process.env.KESTREL_RUNNER_SERVICE_TOKEN!,
  },
});
 
const context = {
  actor: {
    actorId: "user-123",
    actorType: "operator",
    displayName: "Taylor Example",
    tenantId: "acme",
  },
  tenantId: "acme",
};
 
const inbox = await client.getOperatorInbox({ sessionId: "reference-session-001" }, context);
const view = await client.getOperatorThread("thread-main", context);
 
const controlled = await client.controlOperator(
  {
    action: "retry",
    threadId: "thread-main",
    message: "Retry after refreshing evidence.",
  },
  context,
);

Common actions

Available operator actions include:

Invalid actions fail deterministically. The protocol tests explicitly verify that an unsupported operator.control action returns runner.error.

Workflow: blocked thread to resolution

The operator workflow is usually:

1. read operator.inbox for the affected session
2. open operator.thread to see blocker, focus, or checkpoint state
3. decide whether the narrowest safe action is retry, steer, stop, or focus_thread
4. apply the control action
5. inspect the resulting operator.controlled event before deciding on a second intervention

That sequence is what keeps operator work attached to the same durable thread instead of creating a fresh disconnected run every time the workflow hesitates.

CLI workflow

In the CLI, use these commands:

/stop [message]
/steer <message>
/retry [reason]
/focus <threadId>
/approve [message]
/reject [message]
/reply <message>

That CLI flow maps onto the same protocol. The CLI is not inventing local state here. It is a thin operator cockpit over the runner.

Kestrel One workflow

Kestrel One provides the same controls through /api/kchat/control. It can:

• read operator.inbox
• load operator.thread
• submit operator.control
• inspect task.graph
• read or update project.snapshot
• request project.review

This gives browser users the same run controls as the CLI alongside run details and artifacts.

For task graphs, project snapshots, and reviews, continue to Review and state workflows.

What to inspect before you control a thread

1. read the operator inbox for the affected session
2. inspect the thread view and the next action or blocker
3. confirm whether a child thread or fan-in checkpoint is involved
4. pick the narrowest control action that moves the workflow forward

Continue the original work

If a run blocks on evidence, operator control can steer the existing thread instead of creating a disconnected replacement run.

Continue with operator state

• CLI
• Kestrel One
• Review and state workflows
• @kestrel-agents/sdk