Human-in-the-loop on Mobile

Approve tool calls from an approval sheet, cancel a run mid-stream, and queue prompts safely.

The agent proposes a tool; the phone asks; the user decides.

await controller.decide(approvalId, "allow");
await controller.stop();

Quick Start

1. Answer an approval

   await controller.decide(approvalId, "allow");

   decide resolves only once the engine has recorded the decision, so the UI never shows “Allowed” before the request landed. The moment you tap, the row’s buttons disable themselves, so a double tap on a shaky connection cannot send the same decision twice.

2. Cancel a live run

   await controller.stop();

   The run is cancelled by runId, delivered on the start event. cancelled is announced, never inferred from a stream that ends.

Approval Choices

An approval_request carries approvalId, callId, name, and args.

The decision is sent back with approvalId. callId only says which tool row to attach the prompt to.

Approvals are per turn

The approval table is cleared at the start of every turn and again when setChat() switches conversations, so a new prompt is never confused with an answered one.

An engine may number approvalId per run — the protocol only guarantees uniqueness within a single run. Reusing an id across turns once shadowed the new request behind the previous turn’s answered entry: turn 1’s prompt rendered as sent/allow with dead buttons, still carrying turn 0’s args. A user could be shown rm -rf / as already-allowed because an earlier ls reused the id.

// setChat now also resets the turn itself, not only the approvals table.
turn = initialTurn;
approvals = emptyApprovals;

Without the turn reset, send() publishes the stale turn before the new run starts, so New chat cleared the screen only until the user’s next message — and the previous chat’s pending approval reappeared with live buttons. A prompt to run rm -rf /, abandoned by starting a new chat, came back with live buttons on the next Send, and Allow posted the decision to the engine.

The within-turn rule is unchanged: the same approvalId twice inside one run is still the engine repeating itself — one prompt, not two.

Before the turn reset, New chat cleared only the screen — the stale approval reappeared on the next Send.

Refused decisions stay refused

A decision is sending until the engine confirms it, and only then sent. If the engine refuses the decision, acknowledge never promotes it.

An already-confirmed decision is never un-confirmed by a late failure — a duplicated or delayed failure signal cannot flip an allowed-and-executed rm -rf / back into a live prompt. Pinned by "a decision the engine already CONFIRMED cannot be un-confirmed by a late failure" in core/src/run/approvals.test.ts.

The Two-Approval Case

When two approvals are outstanding, the prompts arrive in the opposite order to their tool rows. Routing by position authorises the wrong command.

Cancellation & Queued Prompts

runId arrives on start and is the only handle cancel accepts.

const stopped = await controller.stop();

stop returns true when it cancelled a live run and false when there was nothing to cancel — including when the engine’s cancel POST returns any non-200 status. Stop cancels the network request too: the controller aborts the same signal it handed to fetch, so a request already in flight is dropped rather than left generating tokens after you tapped the button.

What the controller hands the engine

Every turn the controller assembles a RunRequest and hands it to the engine. Three of its fields are guarantees the user feels directly.

• Attachments make the trip. A photo the user attaches to Send arrives on the engine’s RunRequest.attachments, not dropped. Pinned by "an attachment the user picked reaches the engine" in core/src/run/controller.test.ts.
• Tools are requested, not silently off. The controller sets tools: true on the RunRequest, so a turn that needs a tool can call one. Pinned by "tools are requested, not silently disabled".
• No ticker leaks past a finished turn. The pacing interval that ticks during a run is stopped in finally, so twenty messages do not leak twenty 16 ms timers on the phone. Pinned by "a finished turn leaves no timer running".

The same reader release covers New chat, switching apps, and the phone locking mid-answer: the consumer breaks out of the for await iterator, and the engine’s finally calls await reader.cancel(), so the model stops generating and the socket is released. Before #4579, only the request abort was covered — the response stream leaked and the model kept billing after you left.

stop() captures the run when tapped. It no longer re-reads live after awaiting the engine, so tapping Stop just as the last token lands cannot throw a TypeError that blanks the whole screen when the queue is empty, nor cancel the queued follow-up instead of the finished run.

If you switch apps or lock the phone mid-answer, the run is cancelled — you won’t come back to a burning credit meter.

A user-stopped turn reads as cancelled, not transport

The controller branches in the read-loop’s catch on abort.signal.aborted. If the abort was ours — tapping Stop cancels the engine, aborts the reader, and the underlying fetch errors the body stream — the turn ends cancelled with the grey “Stopped” notice. If the stream dies on its own — socket reset, mid-stream 5xx — the turn ends with a transport error and the red “Connection lost” retry.

// controller.ts — who aborted the stream decides the outcome.
turn = abort.signal.aborted
  ? apply(turn, { type: "cancelled", msgId: turn.msgId ?? "unknown", runId })
  : apply(turn, { type: "error", msgId: turn.msgId ?? "unknown", kind: "transport", message });

The pair is deliberate: hiding a genuine network failure behind a calm “Stopped” removes the retry the user needs; painting a deliberate Stop as “Connection lost” tells a screen reader the wrong thing and offers a Retry button the user didn’t ask for.

Stop is idempotent and race-safe

Stop is safe to call more than once, and two overlapping stops share a single cancel.

A second tap reports true, not a refusal: the controller short-circuits on an already-aborted run instead of asking the engine again. The background → dispose path calls stop() twice by design, so the second call must not read as a failure.

Two stops that overlap — the background handler and the user’s Stop button, say — both receive the same in-flight promise. The engine is asked exactly once, and both callers get the true result. This removes the false “the engine did not accept the stop” notice that once fired for a stop that did happen.

Idempotence never invents a cancellation: stop() still returns false when there was nothing to stop.

A refused stop is retryable

A false from the engine leaves the run alive and does not short-circuit the next tap.

When the engine answers cancel(runId) === false, stop() clears run.cancelling and never calls run.abort.abort(). Two things follow: the reader stays attached to a run the engine says is still running, and aborted stays unset, so the next tap reaches the engine again rather than hitting the idempotence guard.

// controller.ts — abort ONLY when the engine confirms.
const stopped = await deps.engine.cancel(run.runId);
if (stopped) {
  run.abort.abort();          // accepted: idempotent from here
} else {
  run.cancelling = undefined; // refused: retry re-asks the engine
}
return stopped;

A second true reaches the user as silence — stopNotice defines an accepted stop as no notification. A second false shows the refusal again. Before this, the idempotence guard aborted the reader even on a refusal, so the retry short-circuited to true without asking the engine, and the run kept generating and billing while the user was told nothing.

When Stop is refused

The app tells you when a stop did not land, instead of going quiet as though it worked.

When the engine genuinely refuses a stop — controller.stop() returns false because the run was not live, or the underlying stop call rejects — the user sees a notification carrying the stopRefused string (“The engine did not accept the stop. It may still be running.”). A button that quietly confirms a cancellation that never happened is worse than one that reports it could not.

Best Practices

Related