@mikode13/harness 11.0.1 → 11.2.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;
@@ -505,7 +558,8 @@ has no stable shape; read it, but do not build on it. A callback that fails is l
 run stays as it ended.
 
 `createLLMOrchestrator()` takes the options of `createOrchestrator()` plus `workspace`,
-`maxSteps`, `compactAt`, `commands`, `formatter`, `summarizeUndone` and `onTranscript`, and returns a promise. Every role runs on the
+`maxSteps`, `compactAt`, `commands`, `formatter`, `summarizeUndone`, `onTranscript`,
+`removeWorktree` and `agents`, and returns a promise. Every role runs on the
 model APIs:
 
 - the planner and the reviewer read, with a `showChanges` tool that gives the current task's
@@ -519,7 +573,15 @@ model APIs:
   `subagent` events;
 - the executor gets its provider's file tools. `autoApprove` reaches only the executor;
 - each role gets the commands whose `roles` name it; a command names only the executor unless
-  it says otherwise.
+  it says otherwise;
+- each role gets the agents `agents` gives it, from `agentAsTool`, beside its own tools: the
+  planner and the reviewer keep their explorers. They only read, so their agents only read too;
+  the executor's may write within the `write` roots.
+
+```ts
+// Each from agentAsTool, as in "Agents that hand work to other agents" below.
+createLLMOrchestrator({ workspace, agents: { planner: [architect], executor: [commit] } });
+```
 
 Each role's run stops after a number of calls to the model: 80 for the executor and 65 for
 the planner and the reviewer by default. `maxSteps` changes it, as one number for every role
@@ -541,18 +603,39 @@ once, **Stop** ends it, and words of your own reach the model. A run stopped thi
 `ask` to ask, fails with `UnrecoverableError`, and is kept in the conversation with its changes,
 so your next prompt continues from it.
 
-No conversation is compacted unless you ask. `compactAt` is the number of input tokens at
-which the provider compacts it on its side, replacing the turns before that call with its own
-summary, which only its model reads back; the conversation keeps every original turn. The
-call that compacts can lose its cache, as it did on OpenAI, so set it well above what a task
-needs. Like
-`maxSteps`, it is one number for every role or per role, and `createLLMAgent` takes one. On
-Anthropic it must be at least 50,000:
+Each agent's context is compacted once it passes its model's threshold: 450,000 tokens for
+Claude Opus, Fable and Sonnet and GPT astra, sol and terra, and 125,000 for Claude Haiku and
+GPT luna. The provider compacts it on its side, inside the call that passes the threshold,
+replacing the turns before that call with its own summary, which only its model reads back; the
+conversation keeps every original turn. The call that compacts can lose its cache, as it did on
+OpenAI, so keep the threshold well above what a task needs. `compactAt` changes it: like
+`maxSteps`, one number for every role or per role, and `createLLMAgent` takes one; on Anthropic
+it must be at least 50,000. `false` turns compaction off:
 
 ```ts
 createLLMOrchestrator({ workspace, compactAt: { executor: 200_000 } });
 ```
 
+`compaction: 'recent'` has the harness compact it instead, for the agent and for every role:
+before the next call, the agent's own model summarizes the context, reading it from its
+provider's cache, and only the run's prompt and its last 10 answers, each with its tool
+results, are kept word for word after the summary, without their signed reasoning; earlier runs
+are always summarized. The
+conversation still keeps every turn; only what the model is sent starts at the summary.
+
+`compaction: 'jev'` summarizes the same way, but TypeSafe's Jev chooses what is kept: the run's
+prompt, the model's last answer with its tool results, and each earlier tool result Jev judges
+the agent still needs word for word, with its call. Jev is sent the run's prompt, the model's
+last answer and each of those tool results, so what the tools read leaves for TypeSafe. It reads
+its key from `TYPESAFE_API_KEY`;
+without one, or when Jev fails, the recent choice is made instead, and logged.
+
+Either way, a context that no longer fits the model is compacted once and the call tried again;
+in the recent mode the model summarizes a transcript of it. When it still does not fit, the run
+fails with `UnrecoverableError`. A `compaction` event says who compacted, why, and how many
+tokens of context it compacted: after the `step` of the call that compacted, or once the
+harness's summary is written. The summary's tokens count in the run's.
+
 Without `workspace` it works on the current directory, read only. One run of the
 orchestrator is one run of the history, every round included.
 
@@ -588,6 +671,13 @@ The agent works inside the caller's run:
 
 - what it writes is the same run of the history, so one undo reverts both; it keeps its own
   tools' access policy, and edits only what it read itself;
+- it never writes more than the agent that called it: only within the `write` roots of that
+  agent's `workspace`, and nowhere when that workspace only reads. A calling agent with no
+  `workspace`, such as a coordinator that only hands out tasks, sets no limit of its own. Its
+  tools that may write elsewhere, a command included, are refused before anyone is asked, and
+  the model is told why. Where your own `Tool` writes is unknown, so under an agent that only
+  reads, a call your tool judges `mutating` or `destructive` is refused too; under an agent
+  that writes, it writes wherever your tool does;
 - what it spends counts in the caller's `tokens`, a failed attempt included;
 - it asks and is approved through the run's `ask` and `approve`, which agents working at once
   may call before an earlier call has its answer; one person at one terminal needs them queued,
@@ -699,12 +789,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 +827,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
@@ -792,7 +961,8 @@ is told to decide and say what it assumed.
 With `--llm`, the agents can also [run commands](#running-the-projects-commands) you
 configure for the repository, in `~/.config/mikode-harness/config.json` (or under
 `$XDG_CONFIG_HOME`). The file maps each repository's real path to its `commands` and,
-optionally, its `maxSteps`, `compactAt` and [`formatter`](#formatting-what-the-agent-writes). It lives outside every repository, so neither a cloned repository
+optionally, its `maxSteps`, its `compactAt`, or `false` to turn compaction off, its
+`compaction` (`provider`, `recent` or `jev`, as `createLLMOrchestrator` takes them) and [`formatter`](#formatting-what-the-agent-writes). It lives outside every repository, so neither a cloned repository
 nor the agent decides what runs, or for how long:
 
 ```json

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;
@@ -146,6 +167,23 @@ export type ProgressEvent = {
     context: StepContext;
     agent?: ProgressAgent;
 }
+/**
+ * The context an agent on the model APIs sends was compacted: summarized from some point back,
+ * while its conversation keeps every part. `by` is who compacted it, the model's provider or
+ * the harness. `reason` is `threshold` when the context passed the agent's `compactAt`, and
+ * `maxContext` when it no longer fit the model, which compacts it even with compaction off.
+ * `contextTokens` is how many tokens of context were compacted, when known. The provider's
+ * compaction follows the `step` event of the call that compacted, whose tokens include the
+ * compaction's. The harness's is narrated once its summary is written, before the next call's
+ * `step`: the summary call has no `step` of its own, and its tokens are only in the run's.
+ */
+ | {
+    type: 'compaction';
+    by: 'provider' | 'harness';
+    reason: 'threshold' | 'maxContext';
+    contextTokens?: number;
+    agent?: ProgressAgent;
+}
 /**
  * A workflow's stage asks its agent for an answer; `attempt` is 2 or more when the previous
  * answer was invalid. Stages run one at a time, so the events that follow, until the next

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 * The context an agent on the model APIs sends was compacted: summarized from some point back,\n\t * while its conversation keeps every part. `by` is who compacted it, the model's provider or\n\t * the harness. `reason` is `threshold` when the context passed the agent's `compactAt`, and\n\t * `maxContext` when it no longer fit the model, which compacts it even with compaction off.\n\t * `contextTokens` is how many tokens of context were compacted, when known. The provider's\n\t * compaction follows the `step` event of the call that compacted, whose tokens include the\n\t * compaction's. The harness's is narrated once its summary is written, before the next call's\n\t * `step`: the summary call has no `step` of its own, and its tokens are only in the run's.\n\t */\n\t| {\n\t\t\ttype: 'compaction';\n\t\t\tby: 'provider' | 'harness';\n\t\t\treason: 'threshold' | 'maxContext';\n\t\t\tcontextTokens?: number;\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 {};