@mikode13/harness 11.0.0 → 11.1.0

package/README.md

@@ -446,6 +446,54 @@ it to correct. An asker that throws, or does not answer each question with some
 ends the run with an `UnrecoverableError`. The Agent SDK engines ignore `ask`, and
 `createLLMOrchestrator` passes it to every role.
 
+### One run at a time, and what the user sends meanwhile
+
+An agent continues one conversation, so it takes one run at a time: a `run()` that starts
+while another run on the same agent works rejects with `RunInProgressError`, an
+`UnrecoverableError`, and changes nothing. Queue what the user sends meanwhile, and run it
+once the run in progress ends. For one chat, keep one agent; for another chat, create another.
+
+A message the user wants read at once goes to the run in progress through an `Inbox`:
+
+```ts
+import { Inbox } from '@mikode13/harness';
+
+const inbox = new Inbox();
+const running = agent.run('Add the export button', { signal, inbox });
+// Later, while it works:
+inbox.send('Make it a dropdown too');
+await running;
+// What the run did not keep, such as a message sent after its final answer, is the next turn's.
+const unread = inbox.close();
+```
+
+`createLLMAgent` reads what was sent once the step in progress ends, without cutting a model
+call or a tool, as a message from the user. It also reads it while it waits for agents working
+in the background, so the model can reconsider at once. The Agent SDK engines, the
+orchestrators and the workflows never read it, so `close()` returns everything sent to them. Neither does a
+run's last step, which has no step left to answer it. A run that fails before it is kept gives
+back what it read: a retried attempt reads it again, or `close()` returns it.
+
+### Sessions
+
+Every run belongs to a session. Name it in `RunOptions.session`, such as your API's session
+id with a name to show; without one, the run belongs to the agent's own session, which the
+harness makes for each agent with an id a person can read, such as `smart-hawk-4821`.
+`AgentResponse.session` returns the session the run belonged to, so a consumer that builds
+its agent again passes it back to stay in the same session:
+
+```ts
+const first = await agent.run('Add the export button', { signal });
+// Later, maybe with an agent built again:
+await other.run('Make it a dropdown too', { signal, session: first.session });
+```
+
+An agent another agent started belongs to the outer run's session, and a workflow makes a
+new one for each run that names none. A session without a `name`, or with a blank one, is shown by its `id`. Each
+run that writes records its session in the workspace's history, as `HistoryRun.session`, so
+a host can say whose change an undo takes back. It is the harness's session, not a
+provider's, which stays inside its engine.
+
 ### Agents that change files
 
 `createFileTools` gives an agent the file tools of its provider, over the folders you
@@ -475,6 +523,11 @@ const agent = createLLMAgent('openai', {
 });
 ```
 
+`workspace` gives no tools: it tells the agent where it works and has it follow the
+history. An agent given a workspace and no tools at all is refused with an
+`InvalidAgentConfigError`; one with only tools of your own is built, and one with neither
+works from its prompt alone.
+
 Every tool goes through one access policy:
 
 - it refuses a path outside the roots;
@@ -699,12 +752,13 @@ await history.redo();
 await history.goTo(historyStart); // as it was before the agent's first run
 ```
 
-`list()` gives every run kept, oldest first, with its parent, status and the files it
-changed, and the run the workspace is at (`head`), absent at the start. Runs form a tree:
-going back and writing again starts a new branch, and `goTo` reaches the old one. `redo`
-returns towards where the workspace was most recently. A run's `runId` is in its
-`AgentResponse` when it changed a file, and a run that failed or was cancelled after
-writing is still listed, with that status. A run that changed nothing is not kept.
+`list()` gives every run kept, oldest first, with its parent, status, the files it changed
+and the session it came from, and the run the workspace is at (`head`), absent at the
+start. Runs form a tree: going back and writing again starts a new branch, and `goTo`
+reaches the old one. `redo` returns towards where the workspace was most recently. A
+run's `runId` is in its `AgentResponse` when it changed a file, and a run that failed or
+was cancelled after writing is still listed, with that status. A run that changed nothing
+is not kept.
 
 A move writes a file only if it still holds what the history expects. A file you
 changed since is left as it is and named in the move's `conflicts`, and the move is
@@ -736,6 +790,84 @@ The history is not version control. It holds only what the harness's own tools w
 not your edits, not other programs', and not the Agent SDK engines' changes. The lock
 keeps a second harness run out, but not an editor.
 
+### Working apart in a worktree
+
+Runs that only read never hold the workspace, so several chats can read and plan in one
+folder at once. Only one run at a time writes there. For runs that write side by side,
+give each its own git worktree: a folder of its own, with a history of its own.
+
+```ts
+import { createFileTools, createWorktree, type WorkspaceOptions } from '@mikode13/harness';
+
+const { path } = await createWorktree({
+	repository: process.cwd(),
+	branch: 'feat/export-button',
+	from: 'main',
+});
+const workspace: WorkspaceOptions = { roots: [{ path, access: 'write' }] };
+const agent = createLLMAgent('openai', {
+	systemPrompt: 'You build the export button, with a test for it.',
+	tools: await createFileTools('openai', workspace),
+	workspace,
+});
+```
+
+The worktree checks out `branch`, a new branch started at `from`. Without `path` it goes
+beside the repository's main folder, in `../<repository>-worktrees/<branch>`, with any
+`/` in the branch made a `-`. It fails with an `UnrecoverableError` when the branch
+exists or is not a valid name, `from` names no commit, or the folder exists and is not
+empty. A failure leaves no branch or folder of its own behind.
+
+Worktrees need git 2.36 or later, the first whose `worktree list` can name a folder whose
+path holds a newline. With an older git, `createWorktree` fails with an
+`UnrecoverableError`, and `removeWorktree: true` fails with an `InvalidAgentConfigError`
+when the tools are created; both name the version found.
+
+The harness never removes a worktree. An agent given `removeWorktree: true`, in
+`createFileTools` or `createLLMOrchestrator` for its executor, can remove one when the
+user asks. It removes the folder and every file in it, never the branch, which keeps
+its commits. Each call asks the approver, and the request's `worktree` says what is
+lost: `uncommitted` counts the files with changes no commit has, `ignored` the paths
+`.gitignore` excludes, such as `.env` or `node_modules`, a folder once, and
+`commitsOnlyHere` the commits only a detached HEAD holds. An ignored folder is never
+looked into, so what is written in it while the user is asked goes too: when `ignored`
+is not zero, say so in the question. The tool's answer tells the model the same. The
+tool refuses the repository's main folder, a worktree the agent works in, and a locked
+one. Once approved, it claims the worktree, so no harness run starts writing in it,
+and removes nothing while a run may write there, from the worktree, a folder inside it
+or a second root, or if the worktree changed while the user was asked: the model then
+calls it again, and the user is asked anew.
+
+### Rules for runs that share a folder
+
+The harness coordinates its own runs on one folder by these rules. Each refusal says which
+rule stopped it, worded so the model can tell the user why it cannot go on.
+
+1. **An agent takes one run at a time.** A second `run()` on a busy agent rejects with
+   `RunInProgressError`. Queue the message, or send it to the run in progress through
+   its `Inbox`.
+2. **Reading never waits.** Any number of runs read and plan in one folder at once.
+3. **One run at a time writes to a workspace.** A run holds its workspace from its first
+   write until it ends, and so does an undo, a redo or a `goTo`. Meanwhile another run's
+   write is refused and the model is told why, and a move rejects with
+   `WorkspaceBusyError`. For runs that write side by side, give each its own worktree.
+4. **No worktree is removed while a harness run may write in it,** from the worktree, from
+   a folder inside it, or through a second root, and no run starts writing in a worktree
+   being removed. An undo or redo protects every file it writes, wherever it is, even
+   when the history was opened by its first root alone.
+5. **In one run, every set of tools that writes to one history may write only where the
+   first set may.** A run claims the folders of the tools that wrote first; tools built
+   apart, with another `write` root, are refused, and the model is told why. Give every
+   set the same `write` roots, or build the widest first.
+6. **What is removed is what was approved.** If a worktree changed while the user was
+   asked, nothing is removed, and the user is asked again. The inside of a folder
+   `.gitignore` excludes whole is not watched (rule 7).
+7. **The harness sees only its own runs** that keep their history in the same state
+   directory. An editor, a terminal, another program, an Agent SDK engine or a history
+   kept elsewhere is not held back by any of these rules, and the inside of an ignored
+   folder is never looked into. Writing by hand in a folder an agent is writing in can
+   overwrite either side; keeping them apart is up to whoever does it.
+
 ## Tests
 
 `pnpm test` runs the unit suite against deterministic fakes; it never contacts a

package/dist/agent/domain/agent.d.ts

@@ -1,6 +1,8 @@
 import type { Tokens } from '#src/shared/domain/tokens';
 import type { Approver } from './approval.ts';
+import type { Inbox } from './inbox.ts';
 import type { Asker } from './question.ts';
+import type { Session } from '#src/shared/domain/session';
 /**
  * How a run ended when it did not fail. Every token a run spends travels with its end: here
  * when it finishes, in `RecoverableError.tokens` or `UnrecoverableError.tokens` when it fails.
@@ -21,13 +23,19 @@ export interface AgentResponse {
      * the history does not record.
      */
     runId?: string;
+    /**
+     * The session the run belonged to: the one `RunOptions.session` gave, or the agent's own,
+     * which the harness creates for each agent. Pass it to later runs, on this agent or one built
+     * again, to keep them in the same session. Every agent the harness builds sets it.
+     */
+    session?: Session;
 }
 export type Callback = (item: ProgressEvent) => void;
 /**
  * What a run needs besides its prompt. InstructedAgent passes it on whole. OrchestratorAgent
- * copies its own enumerable fields and replaces only `onProgress` per role; RetryingAgent does
- * the same for a run with `ask`, replacing only `ask`. A field must therefore be an own
- * enumerable one to reach every agent.
+ * copies its own enumerable fields, replaces `onProgress` per role and drops `inbox`;
+ * RetryingAgent does the same for a run with `ask`, replacing only `ask`. A field must therefore
+ * be an own enumerable one to reach every agent.
  */
 export interface RunOptions {
     /**
@@ -51,6 +59,19 @@ export interface RunOptions {
      * its answer.
      */
     ask?: Asker | undefined;
+    /**
+     * Messages sent to the run while it works. A model-backed agent reads them once the step in
+     * progress ends, as a message from the user, and wakes for them while it waits for agents in
+     * the background. The Agent SDK engines, the orchestrators and the workflows ignore it, so
+     * `Inbox.close` returns everything sent to them.
+     */
+    inbox?: Inbox | undefined;
+    /**
+     * The session this run belongs to, such as the API's, recorded with each run that writes.
+     * Without it, the run belongs to the agent's own session, the same for each of its runs, which
+     * `AgentResponse.session` returns. An agent another agent started belongs to the outer run's.
+     */
+    session?: Session | undefined;
 }
 /** The `onProgress` of a run that gave none. */
 export declare const ignoreProgress: Callback;

package/dist/agent/domain/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/agent/domain/agent.ts"],"names":[],"mappings":"AA0DA,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAa,GAAG,EAAE,CAAC,SAAS,CAAC","sourcesContent":["import type { Tokens } from '#src/shared/domain/tokens';\nimport type { Approver } from './approval.ts';\nimport type { Asker } from './question.ts';\n\n/**\n * How a run ended when it did not fail. Every token a run spends travels with its end: here\n * when it finishes, in `RecoverableError.tokens` or `UnrecoverableError.tokens` when it fails.\n */\nexport interface AgentResponse {\n\t/** The final text. Empty when the run produced none, for example a turn that only edited files. */\n\tresponse: string;\n\t/**\n\t * Missing when any call in the run completed without reporting usage, which is not the same\n\t * as zero: a partial sum would look complete.\n\t */\n\ttokens?: Tokens;\n\t/** Wall-clock seconds the consumer waited for the run, retries and every role included. */\n\tduration: number;\n\t/**\n\t * The run the workspace's history recorded, when this run wrote through the harness's write\n\t * tools. Absent for a run that wrote nothing, and from the Agent SDK engines, whose changes\n\t * the history does not record.\n\t */\n\trunId?: string;\n}\n\nexport type Callback = (item: ProgressEvent) => void;\n\n/**\n * What a run needs besides its prompt. InstructedAgent passes it on whole. OrchestratorAgent\n * copies its own enumerable fields and replaces only `onProgress` per role; RetryingAgent does\n * the same for a run with `ask`, replacing only `ask`. A field must therefore be an own\n * enumerable one to reach every agent.\n */\nexport interface RunOptions {\n\t/**\n\t * Cancels the run, which then rejects with the signal's reason: an `AbortError`, or a\n\t * `TimeoutError` from `AbortSignal.timeout`. `isAbortError` recognizes both.\n\t */\n\tsignal: AbortSignal;\n\t/** Receives the run's live activity. Without it, the run is silent. */\n\tonProgress?: Callback | undefined;\n\t/**\n\t * Asked before a model-backed agent runs a `destructive` tool call. Without it, such a call\n\t * is denied. An agent built with `autoApprove` never asks, and the Agent SDK engines ignore\n\t * it: their own permission systems decide. Agents a delegation runs at once may call it before\n\t * an earlier call has its answer.\n\t */\n\tapprove?: Approver | undefined;\n\t/**\n\t * Answers what a model-backed agent asks the user, through its `askUser` tool, when a\n\t * decision is the user's to make. Without it the agent has no such tool. The Agent SDK\n\t * engines ignore it. Agents a delegation runs at once may call it before an earlier call has\n\t * its answer.\n\t */\n\task?: Asker | undefined;\n}\n\n/** The `onProgress` of a run that gave none. */\nexport const ignoreProgress: Callback = () => undefined;\n\n/**\n * Live activity during a run, for narration only: the result travels in `AgentResponse`.\n * New event types can arrive in a minor release, so render the types you know and ignore\n * the rest instead of switching over them exhaustively with a `never` check.\n */\nexport type ProgressEvent =\n\t| { type: 'command'; command: string; exitCode?: number; agent?: ProgressAgent }\n\t| { type: 'reasoning'; message: string; agent?: ProgressAgent }\n\t| { type: 'search'; query: string; agent?: ProgressAgent }\n\t| {\n\t\t\ttype: 'fileChange';\n\t\t\tchanges: { path: string; kind: 'add' | 'update' | 'delete' }[];\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t| { type: 'mcpTool'; server: string; tool: string; status: string; agent?: ProgressAgent }\n\t| { type: 'agentMessage'; message: string; agent?: ProgressAgent }\n\t/** `id` pairs a call's end with its start when one step calls the same tool more than once. */\n\t| {\n\t\t\ttype: 'tool';\n\t\t\tid: string;\n\t\t\tname: string;\n\t\t\tagent?: ProgressAgent;\n\t\t\t/** A short, tool-owned description of the call. Narration only. */\n\t\t\tsummary?: string;\n\t\t\t/** The exit code of a configured command that ended with an error. Narration only. */\n\t\t\texitCode?: number;\n\t\t\t/**\n\t\t\t * On `error`, for an agent on the model APIs: what the model was told went wrong, such\n\t\t\t * as a patch that did not apply or a failed command's output. Narration only.\n\t\t\t */\n\t\t\terror?: string;\n\t\t\t/**\n\t\t\t * `in_progress` only once the call is about to run, after any approval. `denied` when\n\t\t\t * it never ran because no one allowed it, with no `in_progress` before it. `sent` when\n\t\t\t * it sent subagents to work in the background, such as an `explore` call: they go on\n\t\t\t * after it, as `subagent` events, until a `subagentEnded` for each.\n\t\t\t */\n\t\t\tstatus: 'in_progress' | 'completed' | 'error' | 'denied' | 'sent';\n\t\t\t/**\n\t\t\t * On `completed`, for a call that changed a file through the harness's write tools: the\n\t\t\t * change as a unified diff, for the person watching. Narration only; the run's whole\n\t\t\t * record is the history's `changes`.\n\t\t\t */\n\t\t\tdiff?: string;\n\t  }\n\t| { type: 'todoList'; items: { text: string; completed: boolean }[]; agent?: ProgressAgent }\n\t| { type: 'turnStarted'; agent?: ProgressAgent }\n\t| { type: 'turnEnded'; agent?: ProgressAgent }\n\t/**\n\t * One billed call to the model by an agent on the model APIs, including one the model\n\t * stopped early or the client turned into an error: what the call sent and what it cost.\n\t * Narration only: the run's total is `AgentResponse.tokens`, or the failure's `tokens`.\n\t */\n\t| {\n\t\t\ttype: 'step';\n\t\t\t/** 1 for the first call of the run. */\n\t\t\tstep: number;\n\t\t\t/** Missing when the provider did not report this call's usage. */\n\t\t\ttokens?: Tokens;\n\t\t\tcontext: StepContext;\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t/**\n\t * A workflow's stage asks its agent for an answer; `attempt` is 2 or more when the previous\n\t * answer was invalid. Stages run one at a time, so the events that follow, until the next\n\t * workflow event, are this stage's agent's.\n\t */\n\t| { type: 'workflowStage'; stage: string; attempt: number; agent?: ProgressAgent }\n\t/** The transition a stage's valid answer selected, and the stage it leads to. */\n\t| {\n\t\t\ttype: 'workflowTransition';\n\t\t\tstage: string;\n\t\t\ttransition: 'go' | 'stop' | 'complete';\n\t\t\t/** Absent after `stop` or `complete`. */\n\t\t\tnextStage?: string;\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t/**\n\t * An event of a subagent that a tool call started: one of the explorers an `explore` call\n\t * sends, or the agent a tool from `agentAsTool` delegates to. `callId` is the `id` of that\n\t * call's `tool` events, and `subagent` numbers its subagents from 1, so the events of agents\n\t * running in parallel stay apart. Subagents work in the background: the call's own `tool`\n\t * event ends with `status: 'sent'`, and each subagent's events keep arriving after it, until\n\t * its `subagentEnded`, whether it answered, failed or was stopped. A subagent's own subagents\n\t * arrive as `subagent` events inside this one's `event`.\n\t */\n\t| {\n\t\t\ttype: 'subagent';\n\t\t\tcallId: string;\n\t\t\tsubagent: number;\n\t\t\t/** Which agent it is: `explorer`, or the name of the tool that delegates to it. */\n\t\t\tname: string;\n\t\t\t/** What the subagent was asked. */\n\t\t\ttask: string;\n\t\t\tevent: ProgressEvent;\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t/**\n\t * A subagent that a call with `status: 'sent'` sent has ended: it `answered`, it `failed` and\n\t * its answer says why, or it was `stopped` because the run ended. `callId`, `subagent` and\n\t * `name` are those of its `subagent` events. Narration only: its answer reaches the model that\n\t * sent it, not the consumer.\n\t */\n\t| {\n\t\t\ttype: 'subagentEnded';\n\t\t\tcallId: string;\n\t\t\tsubagent: number;\n\t\t\tname: string;\n\t\t\toutcome: 'answered' | 'failed' | 'stopped';\n\t\t\tagent?: ProgressAgent;\n\t  };\n\n/**\n * What one call to the model sent, in characters by where it came from: an estimate of size\n * for finding what fills a context, not a token count.\n */\nexport interface StepContext {\n\t/** The system prompt. */\n\tinstructions: number;\n\t/** The tool definitions. */\n\ttools: number;\n\t/**\n\t * The text of the user's prompts and the model's answers, and the provider's summary of the\n\t * turns before it once it has compacted them: only what the call sent.\n\t */\n\tmessages: number;\n\t/** Reasoning the model produced earlier and is sent back: its provider's own signed or encrypted blocks. */\n\treasoning: number;\n\t/** The input of every tool call so far. */\n\ttoolCalls: number;\n\t/** Every tool result so far, by tool, largest first. */\n\ttoolResults: { tool: string; characters: number; calls: number }[];\n\t/** The largest single results, each with its call's summary when the tool gives one. */\n\tlargestResults: { tool: string; characters: number; summary?: string }[];\n}\n\n/** A role in the fixed planner → executor → reviewer workflow. */\nexport type ProgressAgent = 'planner' | 'executor' | 'reviewer';\n\n/**\n * The contract every engine (CodexAgent, ClaudeAgent, future providers) and every\n * decorator (RetryingAgent, OrchestratorAgent) is built against.\n *\n * Implementers MUST only ever reject with `RecoverableError` or `UnrecoverableError`\n * (see src/shared/domain/errors.ts) — never a raw SDK error, a plain `Error`, or anything else leaked\n * unclassified. Every consumer of `Agent` (RetryingAgent's retry decision,\n * OrchestratorAgent's failure handling) `instanceof`-checks against those two types to\n * decide what to do next; a leaked, unclassified error bypasses that decision\n * entirely — it gets retried when it shouldn't be, or crashes a run that a retry\n * would have recovered. Wrap every call into the underlying SDK so nothing escapes\n * unclassified, including failures the SDK itself doesn't model as a domain error\n * (network errors, malformed responses, etc.); `classifyProviderFailure` does this.\n *\n * Cancellation is the one exception: an `AbortError`, or the `TimeoutError` of\n * `AbortSignal.timeout`, must propagate unchanged, because\n * consumers check for it before either error type.\n */\nexport interface Agent {\n\trun(prompt: string, options: RunOptions): Promise<AgentResponse>;\n}\n"]}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/agent/domain/agent.ts"],"names":[],"mappings":"AA+EA,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAa,GAAG,EAAE,CAAC,SAAS,CAAC","sourcesContent":["import type { Tokens } from '#src/shared/domain/tokens';\nimport type { Approver } from './approval.ts';\nimport type { Inbox } from './inbox.ts';\nimport type { Asker } from './question.ts';\nimport type { Session } from '#src/shared/domain/session';\n\n/**\n * How a run ended when it did not fail. Every token a run spends travels with its end: here\n * when it finishes, in `RecoverableError.tokens` or `UnrecoverableError.tokens` when it fails.\n */\nexport interface AgentResponse {\n\t/** The final text. Empty when the run produced none, for example a turn that only edited files. */\n\tresponse: string;\n\t/**\n\t * Missing when any call in the run completed without reporting usage, which is not the same\n\t * as zero: a partial sum would look complete.\n\t */\n\ttokens?: Tokens;\n\t/** Wall-clock seconds the consumer waited for the run, retries and every role included. */\n\tduration: number;\n\t/**\n\t * The run the workspace's history recorded, when this run wrote through the harness's write\n\t * tools. Absent for a run that wrote nothing, and from the Agent SDK engines, whose changes\n\t * the history does not record.\n\t */\n\trunId?: string;\n\t/**\n\t * The session the run belonged to: the one `RunOptions.session` gave, or the agent's own,\n\t * which the harness creates for each agent. Pass it to later runs, on this agent or one built\n\t * again, to keep them in the same session. Every agent the harness builds sets it.\n\t */\n\tsession?: Session;\n}\n\nexport type Callback = (item: ProgressEvent) => void;\n\n/**\n * What a run needs besides its prompt. InstructedAgent passes it on whole. OrchestratorAgent\n * copies its own enumerable fields, replaces `onProgress` per role and drops `inbox`;\n * RetryingAgent does the same for a run with `ask`, replacing only `ask`. A field must therefore\n * be an own enumerable one to reach every agent.\n */\nexport interface RunOptions {\n\t/**\n\t * Cancels the run, which then rejects with the signal's reason: an `AbortError`, or a\n\t * `TimeoutError` from `AbortSignal.timeout`. `isAbortError` recognizes both.\n\t */\n\tsignal: AbortSignal;\n\t/** Receives the run's live activity. Without it, the run is silent. */\n\tonProgress?: Callback | undefined;\n\t/**\n\t * Asked before a model-backed agent runs a `destructive` tool call. Without it, such a call\n\t * is denied. An agent built with `autoApprove` never asks, and the Agent SDK engines ignore\n\t * it: their own permission systems decide. Agents a delegation runs at once may call it before\n\t * an earlier call has its answer.\n\t */\n\tapprove?: Approver | undefined;\n\t/**\n\t * Answers what a model-backed agent asks the user, through its `askUser` tool, when a\n\t * decision is the user's to make. Without it the agent has no such tool. The Agent SDK\n\t * engines ignore it. Agents a delegation runs at once may call it before an earlier call has\n\t * its answer.\n\t */\n\task?: Asker | undefined;\n\t/**\n\t * Messages sent to the run while it works. A model-backed agent reads them once the step in\n\t * progress ends, as a message from the user, and wakes for them while it waits for agents in\n\t * the background. The Agent SDK engines, the orchestrators and the workflows ignore it, so\n\t * `Inbox.close` returns everything sent to them.\n\t */\n\tinbox?: Inbox | undefined;\n\t/**\n\t * The session this run belongs to, such as the API's, recorded with each run that writes.\n\t * Without it, the run belongs to the agent's own session, the same for each of its runs, which\n\t * `AgentResponse.session` returns. An agent another agent started belongs to the outer run's.\n\t */\n\tsession?: Session | undefined;\n}\n\n/** The `onProgress` of a run that gave none. */\nexport const ignoreProgress: Callback = () => undefined;\n\n/**\n * Live activity during a run, for narration only: the result travels in `AgentResponse`.\n * New event types can arrive in a minor release, so render the types you know and ignore\n * the rest instead of switching over them exhaustively with a `never` check.\n */\nexport type ProgressEvent =\n\t| { type: 'command'; command: string; exitCode?: number; agent?: ProgressAgent }\n\t| { type: 'reasoning'; message: string; agent?: ProgressAgent }\n\t| { type: 'search'; query: string; agent?: ProgressAgent }\n\t| {\n\t\t\ttype: 'fileChange';\n\t\t\tchanges: { path: string; kind: 'add' | 'update' | 'delete' }[];\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t| { type: 'mcpTool'; server: string; tool: string; status: string; agent?: ProgressAgent }\n\t| { type: 'agentMessage'; message: string; agent?: ProgressAgent }\n\t/** `id` pairs a call's end with its start when one step calls the same tool more than once. */\n\t| {\n\t\t\ttype: 'tool';\n\t\t\tid: string;\n\t\t\tname: string;\n\t\t\tagent?: ProgressAgent;\n\t\t\t/** A short, tool-owned description of the call. Narration only. */\n\t\t\tsummary?: string;\n\t\t\t/** The exit code of a configured command that ended with an error. Narration only. */\n\t\t\texitCode?: number;\n\t\t\t/**\n\t\t\t * On `error`, for an agent on the model APIs: what the model was told went wrong, such\n\t\t\t * as a patch that did not apply or a failed command's output. Narration only.\n\t\t\t */\n\t\t\terror?: string;\n\t\t\t/**\n\t\t\t * `in_progress` only once the call is about to run, after any approval. `denied` when\n\t\t\t * it never ran because no one allowed it, with no `in_progress` before it. `sent` when\n\t\t\t * it sent subagents to work in the background, such as an `explore` call: they go on\n\t\t\t * after it, as `subagent` events, until a `subagentEnded` for each.\n\t\t\t */\n\t\t\tstatus: 'in_progress' | 'completed' | 'error' | 'denied' | 'sent';\n\t\t\t/**\n\t\t\t * On `completed`, for a call that changed a file through the harness's write tools: the\n\t\t\t * change as a unified diff, for the person watching. Narration only; the run's whole\n\t\t\t * record is the history's `changes`.\n\t\t\t */\n\t\t\tdiff?: string;\n\t  }\n\t| { type: 'todoList'; items: { text: string; completed: boolean }[]; agent?: ProgressAgent }\n\t| { type: 'turnStarted'; agent?: ProgressAgent }\n\t| { type: 'turnEnded'; agent?: ProgressAgent }\n\t/**\n\t * One billed call to the model by an agent on the model APIs, including one the model\n\t * stopped early or the client turned into an error: what the call sent and what it cost.\n\t * Narration only: the run's total is `AgentResponse.tokens`, or the failure's `tokens`.\n\t */\n\t| {\n\t\t\ttype: 'step';\n\t\t\t/** 1 for the first call of the run. */\n\t\t\tstep: number;\n\t\t\t/** Missing when the provider did not report this call's usage. */\n\t\t\ttokens?: Tokens;\n\t\t\tcontext: StepContext;\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t/**\n\t * A workflow's stage asks its agent for an answer; `attempt` is 2 or more when the previous\n\t * answer was invalid. Stages run one at a time, so the events that follow, until the next\n\t * workflow event, are this stage's agent's.\n\t */\n\t| { type: 'workflowStage'; stage: string; attempt: number; agent?: ProgressAgent }\n\t/** The transition a stage's valid answer selected, and the stage it leads to. */\n\t| {\n\t\t\ttype: 'workflowTransition';\n\t\t\tstage: string;\n\t\t\ttransition: 'go' | 'stop' | 'complete';\n\t\t\t/** Absent after `stop` or `complete`. */\n\t\t\tnextStage?: string;\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t/**\n\t * An event of a subagent that a tool call started: one of the explorers an `explore` call\n\t * sends, or the agent a tool from `agentAsTool` delegates to. `callId` is the `id` of that\n\t * call's `tool` events, and `subagent` numbers its subagents from 1, so the events of agents\n\t * running in parallel stay apart. Subagents work in the background: the call's own `tool`\n\t * event ends with `status: 'sent'`, and each subagent's events keep arriving after it, until\n\t * its `subagentEnded`, whether it answered, failed or was stopped. A subagent's own subagents\n\t * arrive as `subagent` events inside this one's `event`.\n\t */\n\t| {\n\t\t\ttype: 'subagent';\n\t\t\tcallId: string;\n\t\t\tsubagent: number;\n\t\t\t/** Which agent it is: `explorer`, or the name of the tool that delegates to it. */\n\t\t\tname: string;\n\t\t\t/** What the subagent was asked. */\n\t\t\ttask: string;\n\t\t\tevent: ProgressEvent;\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t/**\n\t * A subagent that a call with `status: 'sent'` sent has ended: it `answered`, it `failed` and\n\t * its answer says why, or it was `stopped` because the run ended. `callId`, `subagent` and\n\t * `name` are those of its `subagent` events. Narration only: its answer reaches the model that\n\t * sent it, not the consumer.\n\t */\n\t| {\n\t\t\ttype: 'subagentEnded';\n\t\t\tcallId: string;\n\t\t\tsubagent: number;\n\t\t\tname: string;\n\t\t\toutcome: 'answered' | 'failed' | 'stopped';\n\t\t\tagent?: ProgressAgent;\n\t  };\n\n/**\n * What one call to the model sent, in characters by where it came from: an estimate of size\n * for finding what fills a context, not a token count.\n */\nexport interface StepContext {\n\t/** The system prompt. */\n\tinstructions: number;\n\t/** The tool definitions. */\n\ttools: number;\n\t/**\n\t * The text of the user's prompts and the model's answers, and the provider's summary of the\n\t * turns before it once it has compacted them: only what the call sent.\n\t */\n\tmessages: number;\n\t/** Reasoning the model produced earlier and is sent back: its provider's own signed or encrypted blocks. */\n\treasoning: number;\n\t/** The input of every tool call so far. */\n\ttoolCalls: number;\n\t/** Every tool result so far, by tool, largest first. */\n\ttoolResults: { tool: string; characters: number; calls: number }[];\n\t/** The largest single results, each with its call's summary when the tool gives one. */\n\tlargestResults: { tool: string; characters: number; summary?: string }[];\n}\n\n/** A role in the fixed planner → executor → reviewer workflow. */\nexport type ProgressAgent = 'planner' | 'executor' | 'reviewer';\n\n/**\n * The contract every engine (CodexAgent, ClaudeAgent, future providers) and every\n * decorator (RetryingAgent, OrchestratorAgent) is built against.\n *\n * Implementers MUST only ever reject with `RecoverableError` or `UnrecoverableError`\n * (see src/shared/domain/errors.ts) — never a raw SDK error, a plain `Error`, or anything else leaked\n * unclassified. Every consumer of `Agent` (RetryingAgent's retry decision,\n * OrchestratorAgent's failure handling) `instanceof`-checks against those two types to\n * decide what to do next; a leaked, unclassified error bypasses that decision\n * entirely — it gets retried when it shouldn't be, or crashes a run that a retry\n * would have recovered. Wrap every call into the underlying SDK so nothing escapes\n * unclassified, including failures the SDK itself doesn't model as a domain error\n * (network errors, malformed responses, etc.); `classifyProviderFailure` does this.\n *\n * Cancellation is the one exception: an `AbortError`, or the `TimeoutError` of\n * `AbortSignal.timeout`, must propagate unchanged, because\n * consumers check for it before either error type.\n */\nexport interface Agent {\n\trun(prompt: string, options: RunOptions): Promise<AgentResponse>;\n}\n"]}

package/dist/agent/domain/approval.d.ts

@@ -12,6 +12,24 @@ export interface CommandLine {
     /** Where it runs, as a real path. */
     cwd: string;
 }
+/** A worktree a tool call will remove, and what is lost with it. */
+export interface WorktreeRemoval {
+    /** Its folder, as a real path. */
+    path: string;
+    /** The branch it has checked out, which stays with its commits; absent when detached. */
+    branch?: string;
+    /** How many files hold changes no commit has, untracked ones included: they are lost. */
+    uncommitted: number;
+    /**
+     * How many paths `.gitignore` excludes, such as `.env` or `node_modules`, a folder excluded
+     * whole counting once: they are lost too. Such a folder is never looked into, so what is
+     * written in it while the user is asked goes with it unannounced; a host's question says so
+     * when there are any.
+     */
+    ignored: number;
+    /** With a detached HEAD, how many of its commits no branch, tag or remote holds: lost too. */
+    commitsOnlyHere: number;
+}
 /** A tool call waiting for someone to allow it. */
 export interface ApprovalRequest {
     tool: string;
@@ -20,6 +38,8 @@ export interface ApprovalRequest {
     risk: ToolRisk;
     /** For a call that runs a configured command: the program, worked out from the input. */
     command?: CommandLine;
+    /** For a call that removes a worktree: which one, and what is lost with it. */
+    worktree?: WorktreeRemoval;
 }
 /** A denial's `reason` reaches the model, so it can try something else. */
 export type ApprovalDecision = {

package/dist/agent/domain/approval.js.map

@@ -1 +1 @@
-{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../../src/agent/domain/approval.ts"],"names":[],"mappings":"AA6CA;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAChC,GAGyD,EACzD,EAAE,GAAG,GAAG,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,KAAqD,EAAE;IAEtF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE;QAChC,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;QACxB,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAE/C,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1C,0FAA0F;QAC1F,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,8FAA8F;QAC9F,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,CAAC,QAAQ;YAAE,OAAO,QAAQ,CAAC;QACxC,IAAI,YAAY,CAAC,MAAM,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1C,OAAO,QAAQ,CAAC;IACjB,CAAC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe;IAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACnD,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAkD,CAAC;IAChF,IAAI,OAAO,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,QAAQ;QACd,CAAC,CAAC,EAAE,QAAQ,EAAE;QACd,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AAC1E,CAAC;AAED,SAAS,YAAY,CAAC,MAAe;IACpC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAgC,CAAC;IACtD,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC7D,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,QAAQ,KAAK,IAAI,CAAC;AAC1B,CAAC","sourcesContent":["/**\n * How much one tool call can hurt, judged by the tool from that call's input:\n * - `safe` changes nothing, as with a read.\n * - `mutating` makes a change git can undo, as with creating a file.\n * - `destructive` loses something, as with overwriting or deleting a file.\n */\nexport type ToolRisk = 'safe' | 'mutating' | 'destructive';\n\n/** A program a tool call will run, exactly as it will run: no shell reads it. */\nexport interface CommandLine {\n\texecutable: string;\n\targs: string[];\n\t/** Where it runs, as a real path. */\n\tcwd: string;\n}\n\n/** A tool call waiting for someone to allow it. */\nexport interface ApprovalRequest {\n\ttool: string;\n\t/** What the model sent, unvalidated: the tool validates it only if the call is allowed. */\n\tinput: unknown;\n\trisk: ToolRisk;\n\t/** For a call that runs a configured command: the program, worked out from the input. */\n\tcommand?: CommandLine;\n}\n\n/** A denial's `reason` reaches the model, so it can try something else. */\nexport type ApprovalDecision =\n\t{ approved: true } | { approved: false; reason?: string | undefined };\n\n/**\n * Decides one tool call at a time. A consumer that wants \"don't ask again\" remembers its own\n * answers, so the harness keeps no session state. A throw ends the run as an\n * `UnrecoverableError`.\n */\nexport type Approver = (\n\trequest: ApprovalRequest,\n\tsignal: AbortSignal,\n) => ApprovalDecision | Promise<ApprovalDecision>;\n\n/** What `rememberApprovals` asks for: `remember` allows the same call again without asking. */\nexport type RememberableDecision =\n\t| { approved: true; remember?: boolean | undefined }\n\t| { approved: false; reason?: string | undefined };\n\n/**\n * Wraps `ask` so a call the user allowed with `remember` is not asked about again. `key` decides\n * what counts as the same call; it defaults to the tool's name, so \"always\" allows every\n * destructive call to that tool. The memory lives in the returned approver, so its lifetime is\n * the consumer's choice: one per session, one per user, or one per run. Calls made at once are\n * each asked; a call that waits its turn in front of it finds an \"always\" given meanwhile.\n */\nexport function rememberApprovals(\n\task: (\n\t\trequest: ApprovalRequest,\n\t\tsignal: AbortSignal,\n\t) => RememberableDecision | Promise<RememberableDecision>,\n\t{ key = request => request.tool }: { key?: (request: ApprovalRequest) => string } = {},\n): Approver {\n\tconst allowed = new Set<string>();\n\n\treturn async (request, signal) => {\n\t\tconst id = key(request);\n\t\tif (allowed.has(id)) return { approved: true };\n\n\t\tconst answer = await ask(request, signal);\n\t\t// The agent discards an answer that arrives after a cancellation, so it must not be kept.\n\t\tsignal.throwIfAborted();\n\t\t// Read before keeping anything: a truthy `'false'` would otherwise be allowed and remembered.\n\t\tconst decision = readDecision(answer);\n\t\tif (!decision.approved) return decision;\n\t\tif (readRemember(answer)) allowed.add(id);\n\t\treturn decision;\n\t};\n}\n\n/**\n * Reads an approver's answer without trusting its type, since a JavaScript consumer can return\n * anything: only an `approved` that is a boolean decides, and anything else throws.\n */\nexport function readDecision(answer: unknown): ApprovalDecision {\n\tif (typeof answer !== 'object' || answer === null) {\n\t\tthrow new TypeError('The approver answered without a decision');\n\t}\n\tconst { approved, reason } = answer as { approved?: unknown; reason?: unknown };\n\tif (typeof approved !== 'boolean') {\n\t\tthrow new TypeError('The approver answered without a boolean `approved`');\n\t}\n\n\treturn approved\n\t\t? { approved }\n\t\t: { approved, reason: typeof reason === 'string' ? reason : undefined };\n}\n\nfunction readRemember(answer: unknown): boolean {\n\tconst { remember } = answer as { remember?: unknown };\n\tif (remember !== undefined && typeof remember !== 'boolean') {\n\t\tthrow new TypeError('The approver answered without a boolean `remember`');\n\t}\n\treturn remember === true;\n}\n"]}
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../../src/agent/domain/approval.ts"],"names":[],"mappings":"AAkEA;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAChC,GAGyD,EACzD,EAAE,GAAG,GAAG,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,KAAqD,EAAE;IAEtF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE;QAChC,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;QACxB,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAE/C,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1C,0FAA0F;QAC1F,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,8FAA8F;QAC9F,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,CAAC,QAAQ;YAAE,OAAO,QAAQ,CAAC;QACxC,IAAI,YAAY,CAAC,MAAM,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1C,OAAO,QAAQ,CAAC;IACjB,CAAC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe;IAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACnD,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAkD,CAAC;IAChF,IAAI,OAAO,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,QAAQ;QACd,CAAC,CAAC,EAAE,QAAQ,EAAE;QACd,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AAC1E,CAAC;AAED,SAAS,YAAY,CAAC,MAAe;IACpC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAgC,CAAC;IACtD,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC7D,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,QAAQ,KAAK,IAAI,CAAC;AAC1B,CAAC","sourcesContent":["/**\n * How much one tool call can hurt, judged by the tool from that call's input:\n * - `safe` changes nothing, as with a read.\n * - `mutating` makes a change git can undo, as with creating a file.\n * - `destructive` loses something, as with overwriting or deleting a file.\n */\nexport type ToolRisk = 'safe' | 'mutating' | 'destructive';\n\n/** A program a tool call will run, exactly as it will run: no shell reads it. */\nexport interface CommandLine {\n\texecutable: string;\n\targs: string[];\n\t/** Where it runs, as a real path. */\n\tcwd: string;\n}\n\n/** A worktree a tool call will remove, and what is lost with it. */\nexport interface WorktreeRemoval {\n\t/** Its folder, as a real path. */\n\tpath: string;\n\t/** The branch it has checked out, which stays with its commits; absent when detached. */\n\tbranch?: string;\n\t/** How many files hold changes no commit has, untracked ones included: they are lost. */\n\tuncommitted: number;\n\t/**\n\t * How many paths `.gitignore` excludes, such as `.env` or `node_modules`, a folder excluded\n\t * whole counting once: they are lost too. Such a folder is never looked into, so what is\n\t * written in it while the user is asked goes with it unannounced; a host's question says so\n\t * when there are any.\n\t */\n\tignored: number;\n\t/** With a detached HEAD, how many of its commits no branch, tag or remote holds: lost too. */\n\tcommitsOnlyHere: number;\n}\n\n/** A tool call waiting for someone to allow it. */\nexport interface ApprovalRequest {\n\ttool: string;\n\t/** What the model sent, unvalidated: the tool validates it only if the call is allowed. */\n\tinput: unknown;\n\trisk: ToolRisk;\n\t/** For a call that runs a configured command: the program, worked out from the input. */\n\tcommand?: CommandLine;\n\t/** For a call that removes a worktree: which one, and what is lost with it. */\n\tworktree?: WorktreeRemoval;\n}\n\n/** A denial's `reason` reaches the model, so it can try something else. */\nexport type ApprovalDecision =\n\t{ approved: true } | { approved: false; reason?: string | undefined };\n\n/**\n * Decides one tool call at a time. A consumer that wants \"don't ask again\" remembers its own\n * answers, so the harness keeps no session state. A throw ends the run as an\n * `UnrecoverableError`.\n */\nexport type Approver = (\n\trequest: ApprovalRequest,\n\tsignal: AbortSignal,\n) => ApprovalDecision | Promise<ApprovalDecision>;\n\n/** What `rememberApprovals` asks for: `remember` allows the same call again without asking. */\nexport type RememberableDecision =\n\t| { approved: true; remember?: boolean | undefined }\n\t| { approved: false; reason?: string | undefined };\n\n/**\n * Wraps `ask` so a call the user allowed with `remember` is not asked about again. `key` decides\n * what counts as the same call; it defaults to the tool's name, so \"always\" allows every\n * destructive call to that tool. The memory lives in the returned approver, so its lifetime is\n * the consumer's choice: one per session, one per user, or one per run. Calls made at once are\n * each asked; a call that waits its turn in front of it finds an \"always\" given meanwhile.\n */\nexport function rememberApprovals(\n\task: (\n\t\trequest: ApprovalRequest,\n\t\tsignal: AbortSignal,\n\t) => RememberableDecision | Promise<RememberableDecision>,\n\t{ key = request => request.tool }: { key?: (request: ApprovalRequest) => string } = {},\n): Approver {\n\tconst allowed = new Set<string>();\n\n\treturn async (request, signal) => {\n\t\tconst id = key(request);\n\t\tif (allowed.has(id)) return { approved: true };\n\n\t\tconst answer = await ask(request, signal);\n\t\t// The agent discards an answer that arrives after a cancellation, so it must not be kept.\n\t\tsignal.throwIfAborted();\n\t\t// Read before keeping anything: a truthy `'false'` would otherwise be allowed and remembered.\n\t\tconst decision = readDecision(answer);\n\t\tif (!decision.approved) return decision;\n\t\tif (readRemember(answer)) allowed.add(id);\n\t\treturn decision;\n\t};\n}\n\n/**\n * Reads an approver's answer without trusting its type, since a JavaScript consumer can return\n * anything: only an `approved` that is a boolean decides, and anything else throws.\n */\nexport function readDecision(answer: unknown): ApprovalDecision {\n\tif (typeof answer !== 'object' || answer === null) {\n\t\tthrow new TypeError('The approver answered without a decision');\n\t}\n\tconst { approved, reason } = answer as { approved?: unknown; reason?: unknown };\n\tif (typeof approved !== 'boolean') {\n\t\tthrow new TypeError('The approver answered without a boolean `approved`');\n\t}\n\n\treturn approved\n\t\t? { approved }\n\t\t: { approved, reason: typeof reason === 'string' ? reason : undefined };\n}\n\nfunction readRemember(answer: unknown): boolean {\n\tconst { remember } = answer as { remember?: unknown };\n\tif (remember !== undefined && typeof remember !== 'boolean') {\n\t\tthrow new TypeError('The approver answered without a boolean `remember`');\n\t}\n\treturn remember === true;\n}\n"]}

package/dist/agent/domain/inbox.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Messages a consumer sends to a run while it works, such as what the user typed meanwhile and
+ * asked to have read at once. A model-backed agent reads them once the step in progress ends,
+ * and wakes for them while it waits for the agents it sent to work in the background. The Agent
+ * SDK engines, the orchestrators and the workflows never read them.
+ *
+ * One inbox belongs to one run: create it for the run, pass it in `RunOptions`, and close it
+ * once the run ends.
+ */
+export declare class Inbox {
+    constructor();
+    /**
+     * Sends a message to the run. False once the inbox is closed, whatever the text: no run will
+     * read it.
+     *
+     * @throws {RangeError} when the inbox is open and `text` holds nothing but whitespace, which a
+     * provider may refuse.
+     */
+    send(text: string): boolean;
+    /**
+     * Closes the inbox, and returns every message the run did not keep, in the order they were
+     * sent: those it never read, such as one sent after its final answer, and those it read in an
+     * attempt that failed. They belong to the next run.
+     */
+    close(): string[];
+}
+/** How a run reads its inbox. Internal. */
+export interface InboxReader {
+    /** Takes every message waiting, in the order they were sent. */
+    take(): string[];
+    /** Gives back messages a run read but did not keep, ahead of any sent since. */
+    giveBack(messages: readonly string[]): void;
+    /** Calls `listener` for each message sent, until the returned function is called. */
+    onMessage(listener: () => void): () => void;
+}
+/**
+ * How a run reads `inbox`, which comes untyped from a consumer's options.
+ *
+ * @throws {UnrecoverableError} for anything that is not an `Inbox` of this package, such as a
+ * plain object, or one made by another copy of the package.
+ */
+export declare function readerOf(inbox: unknown): InboxReader;

package/dist/agent/domain/inbox.js

@@ -0,0 +1,81 @@
+import { UnrecoverableError } from '#src/shared/domain/errors';
+/**
+ * Messages a consumer sends to a run while it works, such as what the user typed meanwhile and
+ * asked to have read at once. A model-backed agent reads them once the step in progress ends,
+ * and wakes for them while it waits for the agents it sent to work in the background. The Agent
+ * SDK engines, the orchestrators and the workflows never read them.
+ *
+ * One inbox belongs to one run: create it for the run, pass it in `RunOptions`, and close it
+ * once the run ends.
+ */
+export class Inbox {
+    constructor() {
+        states.set(this, { waiting: [], closed: false, listeners: new Set() });
+    }
+    /**
+     * Sends a message to the run. False once the inbox is closed, whatever the text: no run will
+     * read it.
+     *
+     * @throws {RangeError} when the inbox is open and `text` holds nothing but whitespace, which a
+     * provider may refuse.
+     */
+    send(text) {
+        const state = stateOf(this);
+        if (state.closed)
+            return false;
+        if (text.trim() === '')
+            throw new RangeError('A message to a run needs some text');
+        state.waiting.push(text);
+        for (const listener of state.listeners)
+            listener();
+        return true;
+    }
+    /**
+     * Closes the inbox, and returns every message the run did not keep, in the order they were
+     * sent: those it never read, such as one sent after its final answer, and those it read in an
+     * attempt that failed. They belong to the next run.
+     */
+    close() {
+        const state = stateOf(this);
+        state.closed = true;
+        state.listeners.clear();
+        return state.waiting.splice(0);
+    }
+}
+// Kept apart from the class, so a consumer sees only `send` and `close`.
+const states = new WeakMap();
+function stateOf(inbox) {
+    const state = states.get(inbox);
+    if (!state)
+        throw new TypeError('Not an Inbox');
+    return state;
+}
+/**
+ * How a run reads `inbox`, which comes untyped from a consumer's options.
+ *
+ * @throws {UnrecoverableError} for anything that is not an `Inbox` of this package, such as a
+ * plain object, or one made by another copy of the package.
+ */
+export function readerOf(inbox) {
+    const state = typeof inbox === 'object' && inbox !== null ? states.get(inbox) : undefined;
+    if (!state) {
+        throw new UnrecoverableError('The run was given an inbox that is not an Inbox', {
+            cause: 'RunOptions.inbox, when given, is an Inbox this package made.',
+        });
+    }
+    return {
+        take: () => state.waiting.splice(0),
+        giveBack: messages => {
+            state.waiting.unshift(...messages);
+        },
+        onMessage: listener => {
+            if (state.closed)
+                return () => undefined;
+            state.listeners.add(listener);
+            return () => {
+                state.listeners.delete(listener);
+            };
+        },
+    };
+}
+//# sourceMappingURL=inbox.js.map

package/dist/agent/domain/inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.js","sourceRoot":"","sources":["../../../src/agent/domain/inbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,OAAO,KAAK;IACjB;QACC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,IAAY;QAChB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,KAAK,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC/B,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,MAAM,IAAI,UAAU,CAAC,oCAAoC,CAAC,CAAC;QACnF,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,SAAS;YAAE,QAAQ,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;OAIG;IACH,KAAK;QACJ,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5B,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;QACpB,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;CACD;AAQD,yEAAyE;AACzE,MAAM,MAAM,GAAG,IAAI,OAAO,EAAqB,CAAC;AAEhD,SAAS,OAAO,CAAC,KAAY;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,SAAS,CAAC,cAAc,CAAC,CAAC;IAChD,OAAO,KAAK,CAAC;AACd,CAAC;AAYD;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACtC,MAAM,KAAK,GACV,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAc,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtF,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,MAAM,IAAI,kBAAkB,CAAC,iDAAiD,EAAE;YAC/E,KAAK,EAAE,8DAA8D;SACrE,CAAC,CAAC;IACJ,CAAC;IACD,OAAO;QACN,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACnC,QAAQ,EAAE,QAAQ,CAAC,EAAE;YACpB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;QACpC,CAAC;QACD,SAAS,EAAE,QAAQ,CAAC,EAAE;YACrB,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;YACzC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC9B,OAAO,GAAG,EAAE;gBACX,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAClC,CAAC,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import { UnrecoverableError } from '#src/shared/domain/errors';\n\n/**\n * Messages a consumer sends to a run while it works, such as what the user typed meanwhile and\n * asked to have read at once. A model-backed agent reads them once the step in progress ends,\n * and wakes for them while it waits for the agents it sent to work in the background. The Agent\n * SDK engines, the orchestrators and the workflows never read them.\n *\n * One inbox belongs to one run: create it for the run, pass it in `RunOptions`, and close it\n * once the run ends.\n */\nexport class Inbox {\n\tconstructor() {\n\t\tstates.set(this, { waiting: [], closed: false, listeners: new Set() });\n\t}\n\n\t/**\n\t * Sends a message to the run. False once the inbox is closed, whatever the text: no run will\n\t * read it.\n\t *\n\t * @throws {RangeError} when the inbox is open and `text` holds nothing but whitespace, which a\n\t * provider may refuse.\n\t */\n\tsend(text: string): boolean {\n\t\tconst state = stateOf(this);\n\t\tif (state.closed) return false;\n\t\tif (text.trim() === '') throw new RangeError('A message to a run needs some text');\n\t\tstate.waiting.push(text);\n\t\tfor (const listener of state.listeners) listener();\n\t\treturn true;\n\t}\n\n\t/**\n\t * Closes the inbox, and returns every message the run did not keep, in the order they were\n\t * sent: those it never read, such as one sent after its final answer, and those it read in an\n\t * attempt that failed. They belong to the next run.\n\t */\n\tclose(): string[] {\n\t\tconst state = stateOf(this);\n\t\tstate.closed = true;\n\t\tstate.listeners.clear();\n\t\treturn state.waiting.splice(0);\n\t}\n}\n\ninterface InboxState {\n\twaiting: string[];\n\tclosed: boolean;\n\tlisteners: Set<() => void>;\n}\n\n// Kept apart from the class, so a consumer sees only `send` and `close`.\nconst states = new WeakMap<Inbox, InboxState>();\n\nfunction stateOf(inbox: Inbox): InboxState {\n\tconst state = states.get(inbox);\n\tif (!state) throw new TypeError('Not an Inbox');\n\treturn state;\n}\n\n/** How a run reads its inbox. Internal. */\nexport interface InboxReader {\n\t/** Takes every message waiting, in the order they were sent. */\n\ttake(): string[];\n\t/** Gives back messages a run read but did not keep, ahead of any sent since. */\n\tgiveBack(messages: readonly string[]): void;\n\t/** Calls `listener` for each message sent, until the returned function is called. */\n\tonMessage(listener: () => void): () => void;\n}\n\n/**\n * How a run reads `inbox`, which comes untyped from a consumer's options.\n *\n * @throws {UnrecoverableError} for anything that is not an `Inbox` of this package, such as a\n * plain object, or one made by another copy of the package.\n */\nexport function readerOf(inbox: unknown): InboxReader {\n\tconst state =\n\t\ttypeof inbox === 'object' && inbox !== null ? states.get(inbox as Inbox) : undefined;\n\tif (!state) {\n\t\tthrow new UnrecoverableError('The run was given an inbox that is not an Inbox', {\n\t\t\tcause: 'RunOptions.inbox, when given, is an Inbox this package made.',\n\t\t});\n\t}\n\treturn {\n\t\ttake: () => state.waiting.splice(0),\n\t\tgiveBack: messages => {\n\t\t\tstate.waiting.unshift(...messages);\n\t\t},\n\t\tonMessage: listener => {\n\t\t\tif (state.closed) return () => undefined;\n\t\t\tstate.listeners.add(listener);\n\t\t\treturn () => {\n\t\t\t\tstate.listeners.delete(listener);\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/agent/domain/oneRunAtATime.d.ts

@@ -0,0 +1,17 @@
+import { UnrecoverableError } from '#src/shared/domain/errors';
+type Options = ConstructorParameters<typeof UnrecoverableError>[1];
+/**
+ * A run started on an agent instance while another run on it works. An instance continues one
+ * conversation, so two runs at once would each continue it from the same point, and one would
+ * silently drop the other.
+ */
+export declare class RunInProgressError extends UnrecoverableError {
+    constructor(message?: string, options?: Options);
+}
+/** Lets an agent instance work on one run at a time, and rejects a run that starts meanwhile. */
+export declare class OneRunAtATime {
+    private running;
+    /** Runs `work`, unless a run is already in progress. */
+    run<T>(work: () => Promise<T>): Promise<T>;
+}
+export {};

package/dist/agent/domain/oneRunAtATime.js

@@ -0,0 +1,32 @@
+import { UnrecoverableError } from '#src/shared/domain/errors';
+/**
+ * A run started on an agent instance while another run on it works. An instance continues one
+ * conversation, so two runs at once would each continue it from the same point, and one would
+ * silently drop the other.
+ */
+export class RunInProgressError extends UnrecoverableError {
+    // The parameters keep the shape `withSpentTokens` copies a classified failure with.
+    constructor(message = 'The agent already has a run in progress', options = {
+        cause: 'An agent instance continues one conversation, one run at a time. Wait for the run in progress to end, or send the message to it through its inbox.',
+    }) {
+        super(message, options);
+        this.name = 'RunInProgressError';
+    }
+}
+/** Lets an agent instance work on one run at a time, and rejects a run that starts meanwhile. */
+export class OneRunAtATime {
+    running = false;
+    /** Runs `work`, unless a run is already in progress. */
+    async run(work) {
+        if (this.running)
+            throw new RunInProgressError();
+        this.running = true;
+        try {
+            return await work();
+        }
+        finally {
+            this.running = false;
+        }
+    }
+}
+//# sourceMappingURL=oneRunAtATime.js.map

package/dist/agent/domain/oneRunAtATime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oneRunAtATime.js","sourceRoot":"","sources":["../../../src/agent/domain/oneRunAtATime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAI/D;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,kBAAkB;IACzD,oFAAoF;IACpF,YACC,OAAO,GAAG,yCAAyC,EACnD,UAAmB;QAClB,KAAK,EACJ,oJAAoJ;KACrJ;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IAClC,CAAC;CACD;AAED,iGAAiG;AACjG,MAAM,OAAO,aAAa;IACjB,OAAO,GAAG,KAAK,CAAC;IAExB,wDAAwD;IACxD,KAAK,CAAC,GAAG,CAAI,IAAsB;QAClC,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC;YACJ,OAAO,MAAM,IAAI,EAAE,CAAC;QACrB,CAAC;gBAAS,CAAC;YACV,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACtB,CAAC;IACF,CAAC;CACD","sourcesContent":["import { UnrecoverableError } from '#src/shared/domain/errors';\n\ntype Options = ConstructorParameters<typeof UnrecoverableError>[1];\n\n/**\n * A run started on an agent instance while another run on it works. An instance continues one\n * conversation, so two runs at once would each continue it from the same point, and one would\n * silently drop the other.\n */\nexport class RunInProgressError extends UnrecoverableError {\n\t// The parameters keep the shape `withSpentTokens` copies a classified failure with.\n\tconstructor(\n\t\tmessage = 'The agent already has a run in progress',\n\t\toptions: Options = {\n\t\t\tcause:\n\t\t\t\t'An agent instance continues one conversation, one run at a time. Wait for the run in progress to end, or send the message to it through its inbox.',\n\t\t},\n\t) {\n\t\tsuper(message, options);\n\t\tthis.name = 'RunInProgressError';\n\t}\n}\n\n/** Lets an agent instance work on one run at a time, and rejects a run that starts meanwhile. */\nexport class OneRunAtATime {\n\tprivate running = false;\n\n\t/** Runs `work`, unless a run is already in progress. */\n\tasync run<T>(work: () => Promise<T>): Promise<T> {\n\t\tif (this.running) throw new RunInProgressError();\n\t\tthis.running = true;\n\t\ttry {\n\t\t\treturn await work();\n\t\t} finally {\n\t\t\tthis.running = false;\n\t\t}\n\t}\n}\n"]}

package/dist/agent/domain/runContext.d.ts

@@ -1,4 +1,5 @@
 import type { RunOptions } from './agent.ts';
+import type { Session } from '#src/shared/domain/session';
 export type RunEnd = 'completed' | 'failed' | 'cancelled';
 /**
  * What one top-level run shares with every agent and tool inside it, across all its roles,
@@ -10,6 +11,8 @@ export type RunEnd = 'completed' | 'failed' | 'cancelled';
  */
 export declare class RunContext {
     private readonly finishers;
+    /** The session the run belongs to, which every agent inside it answers with. */
+    readonly session: Session;
     /**
      * The run the workspace's history recorded for this run, once it first wrote. The object is
      * shared, not copied: a turn recorded before the first write still learns its run.
@@ -17,6 +20,7 @@ export declare class RunContext {
     readonly historyRun: {
         runId?: string;
     };
+    constructor(session: Session);
     /** Ends something the run started, when the run ends. */
     onFinish(finisher: (end: RunEnd) => Promise<void>): void;
     /**

package/dist/agent/domain/runContext.js

@@ -8,11 +8,16 @@
  */
 export class RunContext {
     finishers = [];
+    /** The session the run belongs to, which every agent inside it answers with. */
+    session;
     /**
      * The run the workspace's history recorded for this run, once it first wrote. The object is
      * shared, not copied: a turn recorded before the first write still learns its run.
      */
     historyRun = {};
+    constructor(session) {
+        this.session = session;
+    }
     /** Ends something the run started, when the run ends. */
     onFinish(finisher) {
         this.finishers.push(finisher);

package/dist/agent/domain/runContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"runContext.js","sourceRoot":"","sources":["../../../src/agent/domain/runContext.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,MAAM,OAAO,UAAU;IACL,SAAS,GAAuC,EAAE,CAAC;IAEpE;;;OAGG;IACM,UAAU,GAAuB,EAAE,CAAC;IAE7C,yDAAyD;IACzD,QAAQ,CAAC,QAAwC;QAChD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW;QACvB,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC;gBACJ,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACF,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;CACD;AAED,MAAM,aAAa,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAM1D,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,OAAmB;IAC/C,OAAQ,OAAgC,CAAC,aAAa,CAAC,CAAC;AACzD,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,cAAc,CAAC,OAAmB,EAAE,OAAmB;IACtE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,aAAa,CAAC,EAAE,OAAO,EAA0B,CAAC;AACzE,CAAC;AAgBD,MAAM,aAAa,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAM1D,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAAC,OAAmB;IAC/C,OAAQ,OAA+B,CAAC,aAAa,CAAC,CAAC;AACxD,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,cAAc,CAAC,OAAmB,EAAE,UAAsB;IACzE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,aAAa,CAAC,EAAE,UAAU,EAAyB,CAAC;AAC3E,CAAC","sourcesContent":["import type { RunOptions } from './agent.ts';\n\nexport type RunEnd = 'completed' | 'failed' | 'cancelled';\n\n/**\n * What one top-level run shares with every agent and tool inside it, across all its roles,\n * rounds and retries, such as the record of what it wrote. Whatever a tool starts for the run\n * registers how to end it, and the agent that created the context ends it with the run.\n *\n * Internal: it travels in `RunOptions` under a symbol, so decorators, which pass the options on\n * whole, carry it without knowing it exists, and no consumer can see or set it.\n */\nexport class RunContext {\n\tprivate readonly finishers: ((end: RunEnd) => Promise<void>)[] = [];\n\n\t/**\n\t * The run the workspace's history recorded for this run, once it first wrote. The object is\n\t * shared, not copied: a turn recorded before the first write still learns its run.\n\t */\n\treadonly historyRun: { runId?: string } = {};\n\n\t/** Ends something the run started, when the run ends. */\n\tonFinish(finisher: (end: RunEnd) => Promise<void>): void {\n\t\tthis.finishers.push(finisher);\n\t}\n\n\t/**\n\t * Ends everything registered, all of it even when one fails, and then throws the first\n\t * failure.\n\t */\n\tasync finish(end: RunEnd): Promise<void> {\n\t\tconst failures: unknown[] = [];\n\t\tfor (const finisher of this.finishers.splice(0)) {\n\t\t\ttry {\n\t\t\t\tawait finisher(end);\n\t\t\t} catch (error) {\n\t\t\t\tfailures.push(error);\n\t\t\t}\n\t\t}\n\t\tif (failures.length > 0) throw failures[0];\n\t}\n}\n\nconst runContextKey = Symbol('mikode-harness.runContext');\n\ninterface ContextualRunOptions extends RunOptions {\n\t[runContextKey]?: RunContext;\n}\n\n/** The context of the run these options belong to, if an outer agent created one. */\nexport function runContextOf(options: RunOptions): RunContext | undefined {\n\treturn (options as ContextualRunOptions)[runContextKey];\n}\n\n/** The same options, carrying `context` for every agent the run reaches. */\nexport function withRunContext(options: RunOptions, context: RunContext): RunOptions {\n\treturn { ...options, [runContextKey]: context } as ContextualRunOptions;\n}\n\n/**\n * Where an agent another agent's tool started runs: the call that started it, and how many\n * delegations deep it is, 1 for an agent the top-level agent started.\n */\nexport interface Delegation {\n\t/** The name of the tool that started it, such as `explore` or a specialist's. */\n\treadonly tool: string;\n\t/** The `id` of that call's `tool` events. */\n\treadonly callId: string;\n\t/** Which of the agents that call started, from 1. */\n\treadonly subagent: number;\n\treadonly depth: number;\n}\n\nconst delegationKey = Symbol('mikode-harness.delegation');\n\ninterface DelegatedRunOptions extends RunOptions {\n\t[delegationKey]?: Delegation;\n}\n\n/** The call that started the agent these options reach, if another agent's tool did. */\nexport function delegationOf(options: RunOptions): Delegation | undefined {\n\treturn (options as DelegatedRunOptions)[delegationKey];\n}\n\n/** The same options, for an agent `delegation` started. */\nexport function withDelegation(options: RunOptions, delegation: Delegation): RunOptions {\n\treturn { ...options, [delegationKey]: delegation } as DelegatedRunOptions;\n}\n"]}
+{"version":3,"file":"runContext.js","sourceRoot":"","sources":["../../../src/agent/domain/runContext.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,MAAM,OAAO,UAAU;IACL,SAAS,GAAuC,EAAE,CAAC;IAEpE,gFAAgF;IACvE,OAAO,CAAU;IAE1B;;;OAGG;IACM,UAAU,GAAuB,EAAE,CAAC;IAE7C,YAAY,OAAgB;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;IAED,yDAAyD;IACzD,QAAQ,CAAC,QAAwC;QAChD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW;QACvB,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC;gBACJ,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACF,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;CACD;AAED,MAAM,aAAa,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAM1D,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,OAAmB;IAC/C,OAAQ,OAAgC,CAAC,aAAa,CAAC,CAAC;AACzD,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,cAAc,CAAC,OAAmB,EAAE,OAAmB;IACtE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,aAAa,CAAC,EAAE,OAAO,EAA0B,CAAC;AACzE,CAAC;AAgBD,MAAM,aAAa,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAM1D,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAAC,OAAmB;IAC/C,OAAQ,OAA+B,CAAC,aAAa,CAAC,CAAC;AACxD,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,cAAc,CAAC,OAAmB,EAAE,UAAsB;IACzE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,aAAa,CAAC,EAAE,UAAU,EAAyB,CAAC;AAC3E,CAAC","sourcesContent":["import type { RunOptions } from './agent.ts';\nimport type { Session } from '#src/shared/domain/session';\n\nexport type RunEnd = 'completed' | 'failed' | 'cancelled';\n\n/**\n * What one top-level run shares with every agent and tool inside it, across all its roles,\n * rounds and retries, such as the record of what it wrote. Whatever a tool starts for the run\n * registers how to end it, and the agent that created the context ends it with the run.\n *\n * Internal: it travels in `RunOptions` under a symbol, so decorators, which pass the options on\n * whole, carry it without knowing it exists, and no consumer can see or set it.\n */\nexport class RunContext {\n\tprivate readonly finishers: ((end: RunEnd) => Promise<void>)[] = [];\n\n\t/** The session the run belongs to, which every agent inside it answers with. */\n\treadonly session: Session;\n\n\t/**\n\t * The run the workspace's history recorded for this run, once it first wrote. The object is\n\t * shared, not copied: a turn recorded before the first write still learns its run.\n\t */\n\treadonly historyRun: { runId?: string } = {};\n\n\tconstructor(session: Session) {\n\t\tthis.session = session;\n\t}\n\n\t/** Ends something the run started, when the run ends. */\n\tonFinish(finisher: (end: RunEnd) => Promise<void>): void {\n\t\tthis.finishers.push(finisher);\n\t}\n\n\t/**\n\t * Ends everything registered, all of it even when one fails, and then throws the first\n\t * failure.\n\t */\n\tasync finish(end: RunEnd): Promise<void> {\n\t\tconst failures: unknown[] = [];\n\t\tfor (const finisher of this.finishers.splice(0)) {\n\t\t\ttry {\n\t\t\t\tawait finisher(end);\n\t\t\t} catch (error) {\n\t\t\t\tfailures.push(error);\n\t\t\t}\n\t\t}\n\t\tif (failures.length > 0) throw failures[0];\n\t}\n}\n\nconst runContextKey = Symbol('mikode-harness.runContext');\n\ninterface ContextualRunOptions extends RunOptions {\n\t[runContextKey]?: RunContext;\n}\n\n/** The context of the run these options belong to, if an outer agent created one. */\nexport function runContextOf(options: RunOptions): RunContext | undefined {\n\treturn (options as ContextualRunOptions)[runContextKey];\n}\n\n/** The same options, carrying `context` for every agent the run reaches. */\nexport function withRunContext(options: RunOptions, context: RunContext): RunOptions {\n\treturn { ...options, [runContextKey]: context } as ContextualRunOptions;\n}\n\n/**\n * Where an agent another agent's tool started runs: the call that started it, and how many\n * delegations deep it is, 1 for an agent the top-level agent started.\n */\nexport interface Delegation {\n\t/** The name of the tool that started it, such as `explore` or a specialist's. */\n\treadonly tool: string;\n\t/** The `id` of that call's `tool` events. */\n\treadonly callId: string;\n\t/** Which of the agents that call started, from 1. */\n\treadonly subagent: number;\n\treadonly depth: number;\n}\n\nconst delegationKey = Symbol('mikode-harness.delegation');\n\ninterface DelegatedRunOptions extends RunOptions {\n\t[delegationKey]?: Delegation;\n}\n\n/** The call that started the agent these options reach, if another agent's tool did. */\nexport function delegationOf(options: RunOptions): Delegation | undefined {\n\treturn (options as DelegatedRunOptions)[delegationKey];\n}\n\n/** The same options, for an agent `delegation` started. */\nexport function withDelegation(options: RunOptions, delegation: Delegation): RunOptions {\n\treturn { ...options, [delegationKey]: delegation } as DelegatedRunOptions;\n}\n"]}

package/dist/agent/domain/session.d.ts

@@ -0,0 +1,15 @@
+import type { RunOptions } from './agent.ts';
+import type { Session } from '#src/shared/domain/session';
+/**
+ * A session of its own, for an agent the consumer gave none: its id, such as `smart-hawk-4821`,
+ * is easier to read and say than a UUID, and unlikely to repeat in one workspace's history.
+ */
+export declare function newSession(): Session;
+/**
+ * The session a run belongs to: the outer run's, for an agent another agent started, or the one
+ * its options name. Absent when neither gives one, and the agent uses its own.
+ *
+ * @throws {UnrecoverableError} when the options name a session that is not an object, has no
+ * id, or has a name that is not text.
+ */
+export declare function sessionOf(options: RunOptions): Session | undefined;