@tshu-w/pi-agents 0.1.1 → 0.2.0

package/docs/PROGRAM.md

@@ -25,7 +25,7 @@ target is an ID or a unique ID prefix.
 Agents created with `agent()` belong to the Program: it gets their results
 from `send()`, without `wait` or notifications, and only it can abort
 them. Each of these Agents and the Agents under it see only one another,
-and no other Agent sees them. The user sees them in `/tasks` and `/agents`,
+and no other Agent sees them. The user sees them in the task panel and `/tasks`,
 and can talk to them or interrupt them in the viewer; an interrupted input
 makes its `send()` throw. When the Program ends, their unfinished inputs end
 as `aborted`, and the Agents go offline for good, from the bottom up.
@@ -45,7 +45,8 @@ A Program is `running` until it ends in one of three ways:
 - `stop` stops a running Program.
 
 When a background Program ends and its caller is not waiting for it, the
-caller gets a notification, as in SPEC §5.
+caller gets a notification, as in SPEC §5. A steer input ends `wait` early,
+as in SPEC §5.
 
 ## 3. Program API
 
@@ -54,39 +55,23 @@ can use is checked at each call. If a Program fails or is stopped, the
 error or stop reason follows its output. Its `store()` writes are kept
 only if it completes.
 
-A Program also creates Agents with `agent()`:
-
-```ts
-agent(options?: {
-  name?: string;
-  cwd?: string;
-  context?: "fresh" | "fork";
-  model?: string;
-  thinkingLevel?: string;
-}): AgentHandle
-
-interface AgentHandle {
-  readonly id: string;
-  readonly name: string;
-  send(message: string, options?: {
-    deliverAs?: "followUp" | "steer" | "write";
-    schema?: JsonSchema;
-  }): Promise<unknown>;
-  abort(): Promise<void>;
-}
-```
-
-`agent()` creates an idle Agent. Options work like `agent` `spawn`; an
-omitted name is generated, unique within the Program. `send()` sends a
-message and returns its result. `abort()` works like `agent` `abort`.
-It gets its tools as if the caller had spawned it.
+A Program also creates idle Agents with `agent()`, typed in the Agent API
+(§6). Options work like `agent` `spawn`; an omitted name is generated,
+unique within the Program. `send()` sends a message and returns its result.
+`abort()` works like `agent` `abort`. The Agent gets its tools as if the caller had spawned it.
 
 A result is the Agent's answer. If the input fails or is aborted, the
 result throws an Error. A write returns `undefined` once accepted.
 
 With `schema`, the Agent must call `submit_result` with a value that
 matches the schema, and the result is that value. If it does not, the
-input fails. `send()` throws if `schema` is used without `followUp`.
+input fails.
+
+With `timeout`, an input that has not ended within that many seconds of
+`send()`, including time queued for a slot, is aborted; the Agent's queued
+inputs are unaffected. The result throws a timeout Error.
+
+`send()` throws if `schema` or `timeout` is used without `followUp`.
 
 ## 4. Lifecycle
 
@@ -94,8 +79,7 @@ When a Program ends, it cancels its unfinished tool calls and aborts its
 Agents' unfinished inputs, and waits for its Agents to go offline. It
 returns its result after cleanup. Work not stopped within the cleanup
 timeout is abandoned and may keep running; the Program's result and `stop`
-report it as an error.
-Stopping a Program does not undo completed tool calls.
+report it as an error, and the Program's state is unchanged.
 
 When the caller goes offline, its running Programs stop. Their results
 remain available when the caller is loaded again.
@@ -153,11 +137,13 @@ interface SendOptions {
   deliverAs?: "followUp" | "steer" | "write";
   /** `followUp` only. The Agent must submit a value matching it. */
   schema?: JsonSchema;
+  /** `followUp` only. Seconds before the input is aborted. Default: none. */
+  timeout?: number;
 }
 interface AgentHandle {
   readonly id: string;
   readonly name: string;
-  /** Resolves with the answer, or with the submitted value when `schema` is set; a write resolves with undefined once accepted. Throws if the input fails or is aborted. */
+  /** Resolves with the answer, or with the submitted value when `schema` is set; a write resolves with undefined once accepted. Throws if the input fails, is aborted, or times out. */
   send(message: string, options?: SendOptions): Promise<unknown>;
   /** Aborts the Agent's current turn and queued inputs; the Agent stays usable. */
   abort(): Promise<void>;
@@ -202,6 +188,8 @@ In these formats, `<id>` is the Program's short ID.
 
 `run` in the foreground returns the Program result, as an error if the
 Program failed or was stopped.
+A Program result lists its `send()` calls with its tool calls, and names the
+calls still running when the script returned, which were cancelled.
 
 `run` in the background:
 
@@ -220,6 +208,8 @@ timeout:
 Still running: <id>, ...
 ```
 
+When a steer input ended the wait, the line of SPEC §6 follows.
+
 A single completed result, with nothing running, is returned alone. When
 there are no results or running Programs:
 
@@ -253,7 +243,7 @@ Program <id> has already ended.
 ```
 
 When some of the Program's work does not stop within the timeout, `stop`
-fails with:
+fails with the following; only restarting Pi stops it.
 
 ```text
 Program <id> did not stop within the timeout and may still be running.
@@ -300,10 +290,17 @@ Program <id> <outcome>.
 ## 7. Human interface
 
 The task panel (SPEC §7) lists running background Programs.
+`/tasks` opens a background Program in the task viewer (SPEC §7).
+
+`/program <path> [args]` runs the script in a file as a foreground Program of
+the current Agent, with the text after the path as the global `args`. Esc
+stops it. Like a `!` command, it and its result join the context without
+starting a turn. With `pi -p`, the result is printed, and Pi exits with
+status 1 if the run fails.
 
 ## 8. Configuration
 
-`program` is inactive by default, like `codemode`; enable it with `"defaultTools": ["+program"]` or `--tools`.
+`program` is inactive by default, like `codemode`; enable it with `"defaultTools": ["+program"]` or `--tools`. `/program` does not need it.
 MCP treats `program` as `codemode`: it activates `program` when its servers need a script tool and neither is active, unless `autoEnableCodemode` is false, and a Program waits for the MCP servers its code names.
 When both `program` and `codemode` are active, Pi warns once per Session, since they do a similar job.
 `codemode.mode` decides how the tool list is presented, as for `codemode`.

package/docs/SPEC.md

@@ -4,7 +4,7 @@ Pi Agents lets Agents in Pi discover, message, and wait for each other.
 Programs built on these operations are specified in PROGRAM.md.
 
 Terms follow Pi's
-[Pico5 specification](https://github.com/earendil-works/pi/blob/main/packages/durable/docs/pico-v5.md).
+[Pi Durable specification](https://github.com/earendil-works/pi/blob/main/packages/durable/docs/spec.md).
 
 ## 1. Semantic model
 
@@ -45,6 +45,11 @@ An input to an Agent with a turn in progress is either answered by the current t
 A write is added at the recipient's next tool boundary, or at once if it is
 idle. A write can go to several Agents at once.
 
+When the user of a root Agent clears its queued messages, messages from other
+Agents stay queued. After an Agent's turn is stopped, messages from other
+Agents, notifications included, become writes until its next input from its
+user or owner.
+
 ### 2.3 wait
 
 `wait` returns results of inputs sent to owned Agents. It can target
@@ -52,8 +57,8 @@ specific Agents and take a timeout.
 
 ### 2.4 list
 
-`list` returns visible Agents with their ID, name, working directory, and
-state.
+`list` returns visible Agents with their ID, name, working directory,
+state, and latest request: the last user message or input it received.
 
 ### 2.5 abort
 
@@ -71,7 +76,7 @@ stays `idle`.
 if needed. Acceptance does not mean the recipient has handled it; a message
 not yet handled is lost if the recipient exits.
 
-An input to an offline Agent wakes it. A write never wakes an Agent.
+An input to an offline Agent wakes it; a write to one is rejected.
 
 Owned Agents run independently of their owner's turns. When their owner
 goes offline, they go offline too, from the bottom of the tree up, and their
@@ -101,7 +106,7 @@ continuing, ahead of inputs that have not started.
 
 An input is outstanding from acceptance until its turn ends or it is
 withdrawn. `maxOutstanding` (default 8) limits outstanding inputs; an input
-beyond it is rejected. `maxConcurrent` cannot exceed `maxOutstanding`.
+beyond it is rejected. Notifications (§5) do not count.
 
 ## 5. Results and notifications
 
@@ -111,11 +116,12 @@ withdrawn. Its result is the answer or the error. Only inputs from the
 owner have results; the recipient replies to other senders with `send`.
 
 `wait` returns unread results in order and marks them read. On timeout, it
-returns the results so far and names the Agents still pending. It can also
-return read results again.
+returns the results so far and names the Agents still pending. A steer input
+to the waiting Agent, from any sender, ends `wait` the same way; a write does
+not. It can also return read results again.
 
 When an input ends and its owner is not waiting for that Agent, the owner
-receives a notification, unless the owner aborted it. The notification is an input delivered as `steer`,
+receives a notification, unless the owner aborted it. The notification is an input delivered as `steer` (a write after the owner's turn is stopped, §2.2),
 and it names the Agent and how the input ended. It does not include the
 result; the owner reads the result with `wait`.
 
@@ -214,6 +220,13 @@ write:           { ids }
 Still pending: <name> (<id>), ...
 ```
 
+When a steer input ended the wait, a line follows:
+
+```text
+Still pending: <name> (<id>), ...
+Stopped waiting for a new message. Wait again to keep waiting.
+```
+
 A result returned again through `history` adds `history="true"`. A single
 unread completed result, with nothing pending, is returned as the answer
 alone. When there are no results or pending inputs:
@@ -225,18 +238,19 @@ No results.
 Details:
 
 ```text
-{ results: [{ id, name, state, history, result? }], pending: [id] }
+{ results: [{ id, name, state, history, result? }], pending: [id], interrupted? }
 ```
 
-`state` is the input outcome (§5); `history` marks a previously read result.
+`state` is the input outcome (§5); `history` marks a previously read result;
+`interrupted` is `true` when a steer input ended the wait.
 
-`list` returns one entry per Agent. With a query, entries are ordered by
-their most recent match. When a summary or user message matches, the entry
-shows the latest matching excerpt and its time:
+`list` returns one entry per Agent, followed by its latest request, if any,
+and its time. With a query, entries are ordered by their most recent match,
+and a matching summary or user message shows its latest excerpt instead:
 
 ```text
 <name> (<id>)  <state>  <cwd>
-  YYYY-MM-DD HH:MM  …<matching excerpt>…
+  YYYY-MM-DD HH:MM  <latest request or matching excerpt>
 ```
 
 When more entries remain:
@@ -304,6 +318,13 @@ Input rejected: <N> inputs have not ended. Wait for results or abort an Agent.
 <name> (<id>) is not owned by the caller.
 ```
 
+When an aborted turn does not stop within the timeout (§3), `abort` fails
+with the following; only restarting Pi stops it.
+
+```text
+Agent <name> (<id>) did not stop within the timeout and may still be running.
+```
+
 truncation:
 
 Text beyond Pi's output limits is truncated with Pi's native notice, and
@@ -350,43 +371,59 @@ asking for a reply:
 
 A panel above the editor shows the current Agent's live work:
 
-    Tasks (<N> live, /tasks to hide)
-      Agent <name> (<id>)  <state>  <N> pending
-        Agent <name> (<id>)  <state>
-      Program <id>  running
-        Agent <name> (<id>)  <state>
+    Tasks (<N> live, /tasks to view)
+      Agent <name> (<id>)  <state>  <time>  <cost>  <N> pending
+        Agent <name> (<id>)  <state>  <time>  <cost>
+      Program <id>  running  <time>  <cost>
+        Agent <name> (<id>)  <state>  <time>  <cost>
       +<N> more
 
 The live work is the owned Agents that are not `idle`, and the running
 background Programs with their Agents that are not `idle`. The rows list
 them as a tree in the order they started, each
 under its owner and each Program under its caller, with the owners needed to
-keep the tree. Rows that do not fit are counted in the last row.
+keep the tree. Rows that do not fit are counted in the last row. The time is
+how long the Agent's current turn or the Program has run, and the cost what the
+replies in that turn have cost, or for a Program, those of all the Agents under
+it. When a reply has no price, the cost is the input and output tokens instead,
+like `7.3M tok`.
+
+The panel updates as states change, and its times each second. It is shown
+while it has a row.
+`/tasks panel` hides or shows it.
+
+### Queued messages
+
+Messages from other Agents that wait in the Session's queue, as during a turn,
+are listed above the editor, below the user's queued messages, until the
+Session takes them in:
 
-The panel updates as states change and is shown while it has a row.
-`/tasks` hides or shows it.
+    Steering: [<sender>] <body>
+    Write: [<sender>] <body>
+    Follow-up: [<sender>] <body>
 
-### Agent viewer
+### Task viewer
 
-`/agents` lists the Agents in the current Agent's tree, including Programs'
-Agents, those not `idle` first and newest first within each group, with their state
-and latest activity, and opens the selected one in a viewer. An Agent not owned
-by the current Agent is named with its owners up to it, as
-`<name> ‹ <owner> ‹ …`, where a Program is `Program <id>`. The viewer shows the
-Agent's conversation and updates while it works; the current Session keeps
-running behind it.
+`/tasks` lists the Agents in the current Agent's tree, including its Programs'
+Agents, and its background Programs, live ones first and newest first, with
+their state and latest activity, and opens the selected one in a viewer. An
+Agent not owned by the current Agent is named with its owners, as
+`<name> ‹ <owner> ‹ …`, where a Program is `Program <id>`. The viewer follows
+an Agent's conversation, or a Program as it shows in the foreground, while the
+current Session keeps running.
 
-Text entered in the viewer is the user's input to that Agent and is sent as
-in Pi's editor.
+Text entered in an Agent's viewer is the user's input to it, sent as in Pi's
+editor; a Program takes no input.
 
-`app.interrupt` stops the Agent's current turn, as `abort` does.
-`app.clear` clears the input, and closes the viewer when the input is empty.
+`app.interrupt` stops an Agent's current turn, as `abort` does, or a Program,
+as `stop` does. `app.clear` clears the input, and closes the viewer when the
+input is empty.
 
 ### Workbench
 
 `pd agents` opens the workbench, which lists every root Session on this
-machine and lets the user open and message them. Interactive Sessions keep
-running after their terminal closes. See [WORKBENCH.md](WORKBENCH.md).
+machine and lets the user open and message them. Sessions started with `pd`
+keep running after their terminal closes. See [HOSTS.md](HOSTS.md).
 
 ## 8. Configuration
 
@@ -417,11 +454,11 @@ in its owner's process.
 
 A delivered message enters the recipient's current branch. An offline root
 Agent is started in a host, detached, with its saved working directory and
-model and the current configuration (WORKBENCH §4).
+model and the current configuration (HOSTS §4).
 If a root process cannot finish cleanup within a grace period on exit, it is
 forcibly terminated.
 Before shutting down an idle Session, another extension can emit
 `busy:query` on `pi.events` with `{ busy: false }`; it is set to `true`
 while the tree has live work.
-One runtime uses a Session at a time. If a Session is occupied at interactive
-startup, its lock error stays visible until the user dismisses it, then Pi exits.
+One runtime uses a Session at a time. If a Session is occupied at startup, Pi
+reports it and exits.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tshu-w/pi-agents",
-  "version": "0.1.1",
-  "description": "Multi-agent runtime for Pi: async agents, programmatic delegation, inter-agent messaging, and a workbench for your Sessions",
+  "version": "0.2.0",
+  "description": "Multi-agent runtime for Pi: persistent async agents, dynamic workflows, and inter-agent messaging",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -19,11 +19,13 @@
     "docs"
   ],
   "keywords": [
-    "pi-package",
-    "pi-extension",
-    "pi-coding-agent",
     "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
     "multi-agent",
+    "async-agents",
+    "dynamic-workflows",
     "rlm"
   ],
   "pi": {

package/src/agents/agents.ts

@@ -18,6 +18,8 @@ import { fileURLToPath } from "node:url";
 import {
 	customMessage,
 	deliver,
+	addProgramSpend,
+	addSpend,
 	label,
 	messageText,
 	MESSAGE_TYPE,
@@ -32,6 +34,7 @@ import {
 	type AgentState,
 	type Delivery,
 	type Entry,
+	type Spend,
 	type TreeMetadata,
 } from "./registry.ts";
 
@@ -121,8 +124,8 @@ function lastAnswer(session: AgentSession, before: number): { outcome: Outcome;
 	return { outcome: "completed", result: text };
 }
 
-/** Takes this extension's messages left in the agent queues after a run settles. */
-function takeQueued(agent: AgentSession["agent"]) {
+/** Takes this extension's messages out of the agent queues. */
+export function takeQueued(agent: AgentSession["agent"]) {
 	// peekQueuedMessages returns one message in one-at-a-time mode; read the queues whole.
 	const queues = agent as unknown as Record<"steeringQueue" | "followUpQueue", { messages: QueuedMessage[] }>;
 	const steering = queues.steeringQueue.messages.slice();
@@ -135,6 +138,19 @@ function takeQueued(agent: AgentSession["agent"]) {
 	return [...steering, ...followUps].filter(ours);
 }
 
+/** Whether a steer, which this turn must take in before its next model call, waits in the agent's queue; a write does not count. */
+export function steerQueued(agent: AgentSession["agent"] | undefined): boolean {
+	if (!agent) return false;
+	const queue = (agent as unknown as { steeringQueue: { messages: QueuedMessage[] } }).steeringQueue.messages;
+	return queue.some((message) => !(message.role === "custom" && message.customType === MESSAGE_TYPE
+		&& (message as { details?: { delivery?: string } }).details?.delivery === "write"));
+}
+
+// Pi does not report steers queued by extensions, so a wait checks the queue this often.
+export const STEER_POLL_MS = 250;
+
+export const WAIT_INTERRUPTED = "Stopped waiting for a new message. Wait again to keep waiting.";
+
 export interface Deferred {
 	promise: Promise<void>;
 	resolve(): void;
@@ -187,7 +203,7 @@ function ended(input: InputRecord): boolean {
 
 interface Input {
 	text: string;
-	/** The user's input from the Agent viewer. */
+	/** The user's input from the task viewer. */
 	user?: boolean;
 	record?: InputRecord;
 	permit?: symbol;
@@ -208,6 +224,10 @@ interface Turn {
 	started: boolean;
 	/** Whether the turn holds a scheduler slot. */
 	slot: boolean;
+	/** When the turn got its slot, in milliseconds. */
+	since?: number;
+	/** What the turn's replies have cost. */
+	spent: Spend;
 	finished: boolean;
 	done: Deferred;
 }
@@ -226,6 +246,8 @@ interface Owned {
 	loading?: Promise<AgentSession>;
 	prepared?: Prepared;
 	waiters: number;
+	/** Its turn was stopped: messages from other Agents become writes until its owner's or user's next input. */
+	stopped?: boolean;
 }
 
 export interface SpawnRequest {
@@ -246,6 +268,8 @@ export interface WaitResult {
 export interface WaitOutcome {
 	results: WaitResult[];
 	pending: AgentRecord[];
+	/** A steer ended the wait. */
+	interrupted?: boolean;
 }
 
 /** The Agents owned by one loaded Agent. */
@@ -287,11 +311,11 @@ export class Agents {
 		return [...this.agents.values()].some((agent) => agent.turn !== undefined || agent.queue.length > 0);
 	}
 
-	/** An owned Agent's state, and its inputs pending behind its current or next turn. */
-	counts(id: string): { state: AgentState; pending: number } | undefined {
+	/** An owned Agent's state, its inputs pending behind its current or next turn, when its turn got a slot, and what the turn has cost. */
+	counts(id: string): { state: AgentState; pending: number; since?: number; spent?: Spend } | undefined {
 		const agent = this.agents.get(id);
 		if (!agent) return undefined;
-		return { state: this.state(agent), pending: agent.queue.length };
+		return { state: this.state(agent), pending: agent.queue.length, since: agent.turn?.since, spent: agent.turn?.spent };
 	}
 
 	private state(agent: Owned): AgentState {
@@ -393,14 +417,25 @@ export class Agents {
 	/**
 	 * Sends an input from the owner and resolves when it ends. With a schema, the Agent must call
 	 * `submit_result` with a matching value, which becomes the input's `value`; `text` tells it so.
+	 * An input not ended within `timeoutMs` is aborted alone, and `timedOut` is set.
 	 */
-	async request(id: string, text: string, delivery: "followUp" | "steer", schema?: unknown): Promise<InputRecord> {
+	async request(id: string, text: string, delivery: "followUp" | "steer", schema?: unknown, timeoutMs?: number): Promise<{ record: InputRecord; timedOut: boolean }> {
 		const agent = this.agent(id);
 		const input: Input = { text, permit: this.reserve(), record: this.newRecord(agent), done: deferred() };
 		if (schema !== undefined) input.schema = schema;
 		this.add(agent, input, delivery);
-		await input.done!.promise;
-		return input.record!;
+		let stopping: Promise<void> | undefined;
+		const timer = timeoutMs === undefined ? undefined : setTimeout(() => {
+			stopping = this.cancel(agent, input);
+			stopping.catch(() => {});
+		}, timeoutMs);
+		try {
+			await input.done!.promise;
+		} finally {
+			clearTimeout(timer);
+		}
+		await stopping;
+		return { record: input.record!, timedOut: stopping !== undefined && input.record!.state === "aborted" };
 	}
 
 	/** Records a value from `submit_result` for the Agent's current input with a schema. */
@@ -416,6 +451,7 @@ export class Agents {
 
 	accept(id: string, text: string, delivery: Delivery, options: { fromOwner: boolean; notification: boolean }): { queued: boolean } {
 		const agent = this.agent(id);
+		if (agent.stopped && !options.fromOwner) delivery = "write";
 		if (delivery === "write") {
 			this.write(agent, text);
 			return { queued: false };
@@ -426,7 +462,7 @@ export class Agents {
 		return { queued: this.add(agent, input, delivery) };
 	}
 
-	async wait(targets: Owned[] | undefined, history: number, timeoutSeconds: number, signal?: AbortSignal): Promise<WaitOutcome> {
+	async wait(targets: Owned[] | undefined, history: number, timeoutSeconds: number, signal?: AbortSignal, steered?: () => boolean): Promise<WaitOutcome> {
 		const selected = targets ?? [...this.agents.values()].filter((agent) =>
 			this.pending(agent) || agent.record.inputs.some((input) => ended(input) && !input.read));
 		const unique = [...new Set(selected)];
@@ -438,13 +474,18 @@ export class Agents {
 		const suspended = blocking && this.self.ownerId !== undefined && scheduler.suspend(this.self.rootId, this.self.id);
 		if (blocking) this.markWaiting(1);
 		let returned = false;
+		let interrupted = false;
 		try {
 			const deadline = Date.now() + timeoutSeconds * 1000;
 			while (unique.some((agent) => this.pending(agent))) {
 				const remaining = deadline - Date.now();
 				if (remaining <= 0) break;
+				if (steered?.()) {
+					interrupted = true;
+					break;
+				}
 				signal?.throwIfAborted();
-				await waitForChange(this.change.promise, remaining, signal);
+				await waitForChange(this.change.promise, steered ? Math.min(remaining, STEER_POLL_MS) : remaining, signal);
 			}
 			signal?.throwIfAborted();
 			const results: WaitResult[] = [];
@@ -455,7 +496,7 @@ export class Agents {
 				}
 			}
 			returned = true;
-			return { results, pending: unique.filter((agent) => this.pending(agent)).map((agent) => agent.record) };
+			return { results, pending: unique.filter((agent) => this.pending(agent)).map((agent) => agent.record), ...(interrupted && { interrupted }) };
 		} finally {
 			if (blocking) this.markWaiting(-1);
 			if (suspended) await scheduler.resume(this.self.rootId, this.self.id, this.limits.maxConcurrent, signal);
@@ -494,22 +535,38 @@ export class Agents {
 		if (silent) for (const input of [...agent.queue, ...(turn?.inputs ?? [])]) input.silent = true;
 		for (const input of agent.queue.splice(0)) this.end(agent, input, "aborted", "");
 		this.changed();
-		if (turn) {
-			turn.abort.abort();
-			const stopping = (async () => {
-				if (turn.started && agent.session) {
-					agent.session.abortCompaction();
-					agent.session.abortRetry();
-					await agent.session.abort();
-				}
-				await turn.done.promise;
-			})();
-			if (!await settlesBy(stopping, deadline)) {
-				this.finish(agent, turn, { outcome: "aborted", result: "" });
-				throw new Error(`Agent ${label(agent.record, this.ids())} did not stop within the timeout and may still be running.`);
+		if (turn) await this.stop(agent, turn, deadline);
+		return true;
+	}
+
+	/** Ends one input as aborted: withdraws it if queued, or else stops its turn, as `abort` does. */
+	private async cancel(agent: Owned, input: Input): Promise<void> {
+		const index = agent.queue.indexOf(input);
+		if (index !== -1) {
+			agent.queue.splice(index, 1);
+			this.end(agent, input, "aborted", "");
+			this.changed();
+		} else if (agent.turn?.inputs.includes(input)) {
+			await this.stop(agent, agent.turn, Date.now() + SHUTDOWN_TIMEOUT_MS);
+		}
+	}
+
+	/** Stops a turn; one that has not stopped by `deadline` is abandoned: its inputs end as aborted, and this throws. */
+	private async stop(agent: Owned, turn: Turn, deadline: number): Promise<void> {
+		agent.stopped = true;
+		turn.abort.abort();
+		const stopping = (async () => {
+			if (turn.started && agent.session) {
+				agent.session.abortCompaction();
+				agent.session.abortRetry();
+				await agent.session.abort();
 			}
+			await turn.done.promise;
+		})();
+		if (!await settlesBy(stopping, deadline)) {
+			this.finish(agent, turn, { outcome: "aborted", result: "" });
+			throw new Error(`Agent ${label(agent.record, this.ids())} did not stop within the timeout and may still be running.`);
 		}
-		return true;
 	}
 
 	restore(ctx: ExtensionContext): void {
@@ -539,9 +596,7 @@ export class Agents {
 		const deadline = Date.now() + SHUTDOWN_TIMEOUT_MS;
 		const agents = [...this.agents.values()];
 		const aborted = await Promise.allSettled(agents.map((agent) => this.abort(agent, { deadline })));
-		const closed = await Promise.allSettled(agents.map(async (agent) => {
-			const session = agent.session ?? await agent.loading?.catch(() => undefined);
-			if (!session) return;
+		const close = async (agent: Owned, session: AgentSession) => {
 			try {
 				if (!await settlesBy(session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" }), deadline)) {
 					throw new Error(`Agent ${label(agent.record, this.ids())} did not shut down within the timeout and may still be running.`);
@@ -550,6 +605,16 @@ export class Agents {
 				session.dispose();
 				agent.session = undefined;
 			}
+		};
+		const closed = await Promise.allSettled(agents.map(async (agent) => {
+			const loading = agent.loading;
+			if (!agent.session && loading && !await settlesBy(loading, deadline)) {
+				// A Session that loads after the timeout is closed once it does.
+				void loading.then((late) => close(agent, late).catch(() => {}), () => {});
+				throw new Error(`Agent ${label(agent.record, this.ids())} did not shut down within the timeout and may still be running.`);
+			}
+			const session = agent.session ?? await loading?.catch(() => undefined);
+			if (session) await close(agent, session);
 		}));
 		const errors = [...aborted, ...closed].flatMap((result) => result.status === "rejected" ? [result.reason] : []);
 		if (errors.length > 0) throw new Error(errors.map((error) => error instanceof Error ? error.message : String(error)).join("\n"));
@@ -584,6 +649,8 @@ export class Agents {
 
 	/** A steer joins the current turn; other inputs queue. Returns whether the input waits for a slot. */
 	private add(agent: Owned, input: Input, delivery: "followUp" | "steer"): boolean {
+		// While stopped, other senders' messages become writes, so this is the owner's or user's next input.
+		agent.stopped = false;
 		if (delivery !== "steer" || !agent.turn) return this.enqueue(agent, input);
 		this.join(agent, agent.turn, input);
 		return false;
@@ -606,7 +673,7 @@ export class Agents {
 		if (agent.turn || this.closing) return;
 		const head = agent.queue.shift();
 		if (!head) return;
-		const turn: Turn = { inputs: [head], pending: [], abort: new AbortController(), started: false, slot: false, finished: false, done: deferred() };
+		const turn: Turn = { inputs: [head], pending: [], abort: new AbortController(), started: false, slot: false, spent: { cost: 0, tokens: 0, unpriced: false }, finished: false, done: deferred() };
 		agent.turn = turn;
 		void this.runTurn(agent, turn);
 	}
@@ -616,6 +683,7 @@ export class Agents {
 		try {
 			await scheduler.acquireQueued(this.self.rootId, agent.record.id, this.limits.maxConcurrent, turn.abort.signal);
 			turn.slot = true;
+			turn.since = Date.now();
 			const session = await this.load(agent);
 			turn.abort.signal.throwIfAborted();
 			const before = session.getSessionStats().assistantMessages;
@@ -877,6 +945,11 @@ export class Agents {
 			finally { session.dispose(); }
 			throw error;
 		}
+		session.subscribe((event) => {
+			if (event.type !== "message_end" || event.message.role !== "assistant") return;
+			if (agent.turn) addSpend(agent.turn.spent, event.message.usage);
+			addProgramSpend(this.self.id, event.message.usage);
+		});
 		return session;
 	}
 }