@mikode13/harness 4.0.1 → 5.1.0

package/README.md

@@ -39,9 +39,11 @@ chat loop itself never knows the difference.
   captured `session_id`, so the provider keeps the context.
 - **The model API path**: `LLMAgent` calls the OpenAI Responses API or the
   Anthropic Messages API and keeps the conversation itself, in a form that can move
-  between providers. It runs its own tool loop over the tools it is given; the
-  harness ships three that only read the repository (list, search, read), bounded
-  by `.gitignore`.
+  between providers. It runs its own tool loop over the tools it is given. The
+  harness ships tools that read the repository (list, search, read), bounded by
+  `.gitignore`, and `createFileTools`, which also change files in each provider's
+  native format, every change recorded so it can be undone, and run the commands you
+  configure, such as the tests, recording what each one changed too.
 - **`OrchestratorAgent`**: coordinates a planner, an executor, and a reviewer
   (each an injected `Agent`) in a plan → execute → review loop. The reviewer's
   decision is a Zod-validated structured `{decision, feedback}`, not free text —
@@ -112,6 +114,9 @@ internal modules through the `imports` field of its `package.json`, so a TypeScr
 needs `moduleResolution` set to `node16`, `nodenext` or `bundler`; the legacy `node10`
 resolution cannot read that field.
 
+It supports macOS and Linux. Windows is not supported for now: the tools that write files,
+undo a run and run commands are built and tested on macOS and Linux only.
+
 An agent is built by a factory, then driven. The only output the package produces
 on its own is diagnostic warnings on stderr, from a default logger that both
 factories let you replace through their `logger` option:
@@ -148,10 +153,75 @@ releases, so render the ones you know and ignore the rest. Swapping the agent fo
 reviewer workflow, changes nothing else in the snippet above.
 `createOrchestrator({ provider: 'anthropic' })` runs every role on one provider, for
 example when the other one is out of quota.
+
+The optional `agent` field on an event identifies the orchestrator role that produced
+it (`planner`, `executor`, or `reviewer`). The optional `summary` on a `tool` event
+is narration only: it describes the model's call and is not the tool result. A failed
+configured command may also carry its optional `exitCode`; its output and changes
+still arrive in the tool result. A role label is applied by the orchestrator,
+including retries and later rounds, so a nested agent cannot accidentally attribute
+its events to another role. Consumers should continue to handle events without these
+optional fields.
 `systemPrompts: { planner, executor, reviewer }` replaces a role's instructions;
 a role left out keeps the harness's own, and the reviewer must still answer with
 the JSON decision described on the option.
 
+### Validating factory options
+
+The provider-aware guards validate command-line strings before a factory is built. Use the
+catalog for help text rather than copying the accepted values; choose the catalog and guards for
+the path you are using:
+
+```ts
+import {
+	agentModels,
+	agentReasoningEfforts,
+	createAgent,
+	createLLMAgent,
+	isAgentProvider,
+	isLLMModelOf,
+	isLLMReasoningEffortOf,
+	isModelOf,
+	isReasoningEffortOf,
+	llmModels,
+	llmReasoningEfforts,
+} from '@mikode13/harness';
+
+const providerInput: string = process.argv[2] ?? '';
+const modelInput: string = process.argv[3] ?? '';
+const effortInput: string = process.argv[4] ?? '';
+const useModelApi = false;
+
+if (!isAgentProvider(providerInput)) throw new Error('Unknown provider');
+
+if (useModelApi) {
+	if (
+		!isLLMModelOf(providerInput, modelInput) ||
+		!isLLMReasoningEffortOf(providerInput, effortInput)
+	) {
+		throw new Error(
+			`Expected model ${llmModels[providerInput].join(', ')} and effort ${llmReasoningEfforts[providerInput].join(', ')}`,
+		);
+	}
+	createLLMAgent(providerInput, {
+		model: modelInput,
+		reasoningEffort: effortInput,
+		systemPrompt: 'Be concise.',
+	});
+} else {
+	if (!isModelOf(providerInput, modelInput) || !isReasoningEffortOf(providerInput, effortInput)) {
+		throw new Error(
+			`Expected model ${agentModels[providerInput].join(', ')} and effort ${agentReasoningEfforts[providerInput].join(', ')}`,
+		);
+	}
+	createAgent(providerInput, { model: modelInput, reasoningEffort: effortInput });
+}
+```
+
+These guards describe the provider-wide catalogs. A client can still impose a model-specific
+constraint, such as Claude Haiku accepting no reasoning effort, and the factory's client or
+engine validation remains the final boundary for values that bypass the guards.
+
 Every agent a factory returns already retries recoverable failures. A model or
 reasoning effort the chosen provider does not support throws
 `InvalidAgentConfigError` when the agent is built. Building a Codex agent throws
@@ -164,24 +234,26 @@ The two paths authenticate differently:
 
 - `createAgent` and `createOrchestrator` use the Agent SDKs, which use the login of
   the Codex CLI and of Claude Code, so a run counts against that subscription.
-- `createLLMAgent` and the planner and reviewer of `createLLMOrchestrator` call the
-  model APIs, which bill per token and need the key of each provider they use in
+- `createLLMAgent` and every role of `createLLMOrchestrator`, the executor included, call
+  the model APIs, which bill per token and need the key of each provider they use in
   the environment: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or both for the
   orchestrator's default roles. A missing OpenAI key fails when the agent is built; a missing
   Anthropic key fails its first run.
 
 The Claude Agent SDK
 [authenticates with `ANTHROPIC_API_KEY`](https://code.claude.com/docs/en/agent-sdk) whenever
-it is set, so with that key in the environment a Claude agent from `createAgent`, or the executor of
-`createLLMOrchestrator({ provider: 'anthropic' })`, bills the key instead of the
-subscription.
+it is set, so with that key in the environment a Claude agent from `createAgent` or `createOrchestrator`
+bills the key instead of the subscription.
 
 ### Agents that own their conversation
 
 `createLLMAgent` takes a system prompt and the tools the model may call, and
 returns the same `Agent`. `defineTool` builds a tool from a Zod 4 schema; a field the
 model may leave out is `.nullable()`, not optional, because both APIs call tools in
-strict mode:
+strict mode. An optional `summarize` function receives the same input after Zod
+validation and supplies the tool's short progress narration. It is called once per
+model call; its output is never sent to the provider, and a throwing summarizer
+ends the run as an `UnrecoverableError` before the tool is prepared or executed:
 
 ```ts
 import {
@@ -197,6 +269,7 @@ const now = defineTool({
 	description: 'The current time, in ISO 8601.',
 	input: z.object({}),
 	risk: 'safe',
+	summarize: () => 'current time',
 	execute: async () => new Date().toISOString(),
 });
 
@@ -236,9 +309,171 @@ neither run nor remembered. Its `key` option decides what counts as the same cal
 such as the tool and its path. The memory lives as long as the approver you created,
 so create one per session, per user or per run.
 
-`createLLMOrchestrator()`
-takes the same options as `createOrchestrator()` and returns a promise; its executor
-still runs on an Agent SDK, because the harness's own tools cannot change files.
+### Agents that change files
+
+`createFileTools` gives an agent the file tools of its provider, over the folders you
+declare, each `read` or `write`:
+
+- **OpenAI** gets `listFiles`, `searchText`, `readFile` and its native `apply_patch`.
+- **Anthropic** gets `listFiles`, `searchText`, its native text editor (whose `view`
+  reads) and `delete_file`.
+
+Give the agent the same `workspace`, so it follows what the history undoes:
+
+```ts
+import { createFileTools, createLLMAgent, type WorkspaceOptions } from '@mikode13/harness';
+
+const workspace: WorkspaceOptions = {
+	roots: [
+		{ path: process.cwd(), access: 'write' },
+		{ path: '/srv/standards', access: 'read' },
+	],
+};
+const agent = createLLMAgent('openai', {
+	systemPrompt: 'You fix bugs, with a test for each.',
+	tools: await createFileTools('openai', workspace),
+	workspace,
+});
+```
+
+Every tool goes through one access policy:
+
+- it refuses a path outside the roots;
+- it refuses a file `.gitignore` excludes;
+- it refuses git's metadata, the history itself, and a secret such as `.env`. Add more
+  secrets with `secrets.protect`, or open exact files with `secrets.allow`.
+
+A change happens only in a `write` root, and only from a version of the file the agent
+read: editing a file it never read is `READ_REQUIRED`, and editing one that changed since
+is `STALE_FILE`. Every change is recorded before it is made, so the history can undo the
+run.
+
+With `workspace`, the agent's system prompt is followed by the roots and how to name a file
+in them. After the user undoes runs, the agent's next run starts from its conversation as it
+was then, with a note on what was undone and why. By default that note carries a summary
+from the provider's cheap model, Claude Haiku or `gpt-5.6-luna`, billed with the run;
+`summarizeUndone: false` keeps to the undone prompts. A run that changed a file names its
+run in `AgentResponse.runId`. Progress reports each change as a unified `diff` on the tool's
+`completed` event.
+
+`createLLMOrchestrator()` takes the options of `createOrchestrator()` plus `workspace`,
+`maxSteps`, `commands` and `summarizeUndone`, 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
+  changes as far as each may read them;
+- 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.
+
+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
+or per role, with no upper bound:
+
+```ts
+createLLMOrchestrator({ workspace, maxSteps: { executor: 120 } });
+```
+
+A run also stops sooner when five answers in a row ask for exactly the same tool calls,
+which means the model is stuck. `createLLMAgent` takes one number, 65 by default.
+
+Without `workspace` it works on the current directory, read only. One run of the
+orchestrator is one run of the history, every round included.
+
+### Running the project's commands
+
+With `commands`, `createFileTools` and `createLLMOrchestrator` add `runCommand`, which runs
+one of the commands you configure, by name. Nothing goes through a shell, and the model
+fills only the parameters a command declares:
+
+```ts
+const tools = await createFileTools('openai', workspace, {
+	commands: {
+		test: {
+			description: 'Runs the tests. Give the test files to run only those.',
+			executable: 'pnpm',
+			args: ['vitest', 'run', '--', { type: 'paths', name: 'files', description: 'Test files' }],
+		},
+		format: { description: 'Formats the repository', executable: 'pnpm', args: ['format'] },
+	},
+});
+```
+
+- **Parameters:** `paths` inside the roots that the agent may read; a `choice` among the
+  values you list; or `text` that matches your pattern and never starts with `-`.
+- **Approval:** every call asks the approver, which sees the exact program, arguments and
+  folder in `request.command`. `autoApprove` skips it.
+- **Roles:** in `createLLMOrchestrator`, a command goes to the executor, or to the roles its
+  `roles` lists, such as `['planner', 'executor']` for one that reads an issue. Whoever runs it,
+  its files are captured around it. `createFileTools` offers every command.
+- **Environment:** a command inherits only `PATH`, `HOME`, `TMPDIR`, `USER`, `SHELL`, `LANG`
+  and `LC_*`, plus its own `env`. The provider keys never reach it.
+- **Limits:** 10 minutes, then its whole process group is stopped (`timeoutMs`). The model
+  reads the last 16 KB of its output (`outputBytes`).
+- **History:** the files of the `write` roots are captured before each command and compared
+  after it. What it changed is recorded in the history, so `undo` takes it back.
+  - Not covered: what `.gitignore` excludes (`node_modules`, build output), secrets, files
+    outside the roots, the network and remote services.
+  - A timeout or a cancellation is never reported as a finished command.
+- **Not on Windows yet.**
+
+A command is trusted execution, not a sandbox. A test runs the repository's code, including
+code the model just wrote, with everything your account can reach. The secret rules of the
+file tools do not apply to it, so a command can print a secret into the model's context.
+Configure only commands you would run yourself on that repository.
+
+### Going back through what an agent wrote
+
+The harness's write tools record every run that changes files, outside the repository,
+under the platform's state directory. `createHistory` reads that record and moves the
+workspace through it:
+
+```ts
+import { createHistory, historyStart } from '@mikode13/harness';
+
+const history = await createHistory({ root: process.cwd() });
+const { runId } = await agent.run('Rename the helper.', { signal: controller.signal });
+
+if (runId) console.log(await history.changes(runId)); // a git-style diff
+await history.undo({ reason: 'keep the old name' });
+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.
+
+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
+then not `complete`. The reason is kept with the move.
+
+A move can be tied to where the workspace is. Pass `from`, a run or `historyStart`, and
+the move happens only if the workspace is still there; otherwise it fails with
+`WorkspaceMovedError` and changes nothing. Pass it when you showed the user what a move
+will do, so a run that ends while they answer cannot make it do something else:
+
+```ts
+const { head } = await history.list();
+// … show the user what undoing `head` does, and wait for a yes …
+await history.undo({ from: head ?? historyStart, reason });
+```
+
+A consumer branches on five errors: `WorkspaceBusyError` while a run or another move
+holds the workspace, `WorkspaceMovedError` when it is not at `from`,
+`NothingToMoveError` with nothing to undo or redo,
+`UnknownRunError` for a run the workspace never had, and `HistoryExpiredError` for one
+retention took. The history keeps 25 runs per workspace. Older runs are chained into
+the next, so `historyStart` always restores the original state. For a chained run,
+the error's `keptIn` names the run that now holds its changes, and that run's
+`absorbed` in `list()` names it.
+
+The history is not version control. It holds only what the harness's own tools wrote:
+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.
 
 ## Tests
 
@@ -258,19 +493,66 @@ pnpm run dev
 ```
 
 The agents work on the repository root, which is the directory the script runs in.
-`pnpm run dev --llm` plans and reviews on the model APIs instead, through
+`pnpm run dev --llm` runs all three roles on the model APIs instead, through
 `createLLMOrchestrator`, and needs the API keys in the environment (see
 [Authentication](#authentication)).
 
 Type your prompt at `>`. Press Ctrl+C while idle at the prompt to exit; pressing
 it while an agent is running cancels only that turn and returns to the prompt.
 
+A line that starts with `/` is a command for the CLI, not a prompt. Four commands
+move through the [history of what the agents wrote](#going-back-through-what-an-agent-wrote),
+without the model:
+
+- `/history` shows the tree of runs and marks where the workspace is.
+  `/history --files` adds the files each run changed.
+- `/undo` goes back to the run before the current one.
+- `/redo` goes forward again.
+- `/goto <run | start>` goes to a run, named by its id or its last six characters, or
+  to `start`, before any run.
+
+Each move says what it will do and changes nothing until you answer `y`. It then
+asks why, and records the reason, if you give one, with the move. A move that left
+files as they were, because they changed since, names them. With `--llm` the executor
+writes to the current directory through the harness's tools, so its runs are in that
+history. The Agent SDK path changes files through its own tools, which the history does not
+record.
+
 The CLI asks in the terminal before a destructive tool call runs: yes, always for
-that tool until the CLI exits, or no with an optional reason for the model. No
-agent it builds asks yet, because the harness's own tools only read and
-`autoApprove` is on.
+that tool until the CLI exits, or no with an optional reason for the model. With
+piped input nobody can answer, so such a call is denied: a line written for a later
+question never approves one. Piped lines answer the prompt and the history commands in
+order. With `--llm`, the executor asks before a destructive change, such as one that would
+make `.gitignore` hide less.
+
+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`. It lives outside every repository, so neither a cloned repository
+nor the agent decides what runs, or for how long:
+
+```json
+{
+	"/Users/me/code/app": {
+		"commands": {
+			"test": { "description": "Runs the tests", "executable": "pnpm", "args": ["test"] }
+		},
+		"maxSteps": { "executor": 120 }
+	}
+}
+```
 
-`cli/cli.ts` currently enables `autoApprove` for its trusted backend agents.
+The CLI shows each command as the line it will run before asking, and "always" allows
+that command again, not every command. Tool calls finish as one dimmed line with an
+icon, role, tool name, summary and duration; a failed configured command includes
+`exit N` beside its duration, while a command event also includes its exit code.
+A denied call is marked `denied`. Messages remain normal text under a bold role
+heading. Reasoning is dim italic and complete by default; pass
+`--thinking-headings` to show only Markdown bold headings as `∴ …`. A tool start
+updates the spinner rather than printing a second line, and cancelling a turn clears
+its pending spinner state.
+
+`cli/cli.ts` currently enables `autoApprove` for its Agent SDK agents, not for `--llm`.
 This maps to each provider's permission-bypass mode and grants those processes
 unrestricted command access. Keep it disabled when the host may receive untrusted
 prompts, or provide an approval workflow from the entry point.

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

@@ -14,9 +14,18 @@ export interface AgentResponse {
     tokens?: Tokens;
     /** Wall-clock seconds the consumer waited for the run, retries and every role included. */
     duration: number;
+    /**
+     * The run the workspace's history recorded, when this run wrote through the harness's write
+     * tools. Absent for a run that wrote nothing, and from the Agent SDK engines, whose changes
+     * the history does not record.
+     */
+    runId?: string;
 }
 export type Callback = (item: ProgressEvent) => void;
-/** What a run needs besides its prompt. Decorators pass it on whole, so a new field reaches every agent. */
+/**
+ * What a run needs besides its prompt. RetryingAgent and InstructedAgent pass it on whole;
+ * OrchestratorAgent copies its own enumerable fields and replaces only `onProgress` per role.
+ */
 export interface RunOptions {
     /** Cancels the run, which then rejects with the signal's `AbortError`. */
     signal: AbortSignal;
@@ -40,48 +49,70 @@ export type ProgressEvent = {
     type: 'command';
     command: string;
     exitCode?: number;
+    agent?: ProgressAgent;
 } | {
     type: 'reasoning';
     message: string;
+    agent?: ProgressAgent;
 } | {
     type: 'search';
     query: string;
+    agent?: ProgressAgent;
 } | {
     type: 'fileChange';
     changes: {
         path: string;
         kind: 'add' | 'update' | 'delete';
     }[];
+    agent?: ProgressAgent;
 } | {
     type: 'mcpTool';
     server: string;
     tool: string;
     status: string;
+    agent?: ProgressAgent;
 } | {
     type: 'agentMessage';
     message: string;
+    agent?: ProgressAgent;
 }
 /** `id` pairs a call's end with its start when one step calls the same tool more than once. */
  | {
     type: 'tool';
     id: string;
     name: string;
+    agent?: ProgressAgent;
+    /** A short, tool-owned description of the call. Narration only. */
+    summary?: string;
+    /** The exit code of a configured command that ended with an error. Narration only. */
+    exitCode?: number;
     /**
      * `in_progress` only once the call is about to run, after any approval. `denied` when
      * it never ran because no one allowed it, with no `in_progress` before it.
      */
     status: 'in_progress' | 'completed' | 'error' | 'denied';
+    /**
+     * On `completed`, for a call that changed a file through the harness's write tools: the
+     * change as a unified diff, for the person watching. Narration only; the run's whole
+     * record is the history's `changes`.
+     */
+    diff?: string;
 } | {
     type: 'todoList';
     items: {
         text: string;
         completed: boolean;
     }[];
+    agent?: ProgressAgent;
 } | {
     type: 'turnStarted';
+    agent?: ProgressAgent;
 } | {
     type: 'turnEnded';
+    agent?: ProgressAgent;
 };
+/** A role in the fixed planner → executor → reviewer workflow. */
+export type ProgressAgent = 'planner' | 'executor' | 'reviewer';
 /**
  * The contract every engine (CodexAgent, ClaudeAgent, future providers) and every
  * decorator (RetryingAgent, OrchestratorAgent) is built against.

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

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/agent/domain/agent.ts"],"names":[],"mappings":"AAmCA,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';\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}\n\nexport type Callback = (item: ProgressEvent) => void;\n\n/** What a run needs besides its prompt. Decorators pass it on whole, so a new field reaches every agent. */\nexport interface RunOptions {\n\t/** Cancels the run, which then rejects with the signal's `AbortError`. */\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.\n\t */\n\tapprove?: Approver | 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 }\n\t| { type: 'reasoning'; message: string }\n\t| { type: 'search'; query: string }\n\t| { type: 'fileChange'; changes: { path: string; kind: 'add' | 'update' | 'delete' }[] }\n\t| { type: 'mcpTool'; server: string; tool: string; status: string }\n\t| { type: 'agentMessage'; message: string }\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\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.\n\t\t\t */\n\t\t\tstatus: 'in_progress' | 'completed' | 'error' | 'denied';\n\t  }\n\t| { type: 'todoList'; items: { text: string; completed: boolean }[] }\n\t| { type: 'turnStarted' }\n\t| { type: 'turnEnded' };\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` 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":"AA4CA,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';\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. RetryingAgent and InstructedAgent pass it on whole;\n * OrchestratorAgent copies its own enumerable fields and replaces only `onProgress` per role.\n */\nexport interface RunOptions {\n\t/** Cancels the run, which then rejects with the signal's `AbortError`. */\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.\n\t */\n\tapprove?: Approver | 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 * `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.\n\t\t\t */\n\t\t\tstatus: 'in_progress' | 'completed' | 'error' | 'denied';\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\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` 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

@@ -5,12 +5,21 @@
  * - `destructive` loses something, as with overwriting or deleting a file.
  */
 export type ToolRisk = 'safe' | 'mutating' | 'destructive';
+/** A program a tool call will run, exactly as it will run: no shell reads it. */
+export interface CommandLine {
+    executable: string;
+    args: string[];
+    /** Where it runs, as a real path. */
+    cwd: string;
+}
 /** A tool call waiting for someone to allow it. */
 export interface ApprovalRequest {
     tool: string;
     /** What the model sent, unvalidated: the tool validates it only if the call is allowed. */
     input: unknown;
     risk: ToolRisk;
+    /** For a call that runs a configured command: the program, worked out from the input. */
+    command?: CommandLine;
 }
 /** 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":"AAmCA;;;;;GAKG;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 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}\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.\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":"AA6CA;;;;;GAKG;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.\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/runContext.d.ts

@@ -0,0 +1,31 @@
+import type { RunOptions } from './agent.ts';
+export type RunEnd = 'completed' | 'failed' | 'cancelled';
+/**
+ * What one top-level run shares with every agent and tool inside it, across all its roles,
+ * rounds and retries, such as the record of what it wrote. Whatever a tool starts for the run
+ * registers how to end it, and the agent that created the context ends it with the run.
+ *
+ * Internal: it travels in `RunOptions` under a symbol, so decorators, which pass the options on
+ * whole, carry it without knowing it exists, and no consumer can see or set it.
+ */
+export declare class RunContext {
+    private readonly finishers;
+    /**
+     * 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.
+     */
+    readonly historyRun: {
+        runId?: string;
+    };
+    /** Ends something the run started, when the run ends. */
+    onFinish(finisher: (end: RunEnd) => Promise<void>): void;
+    /**
+     * Ends everything registered, all of it even when one fails, and then throws the first
+     * failure.
+     */
+    finish(end: RunEnd): Promise<void>;
+}
+/** The context of the run these options belong to, if an outer agent created one. */
+export declare function runContextOf(options: RunOptions): RunContext | undefined;
+/** The same options, carrying `context` for every agent the run reaches. */
+export declare function withRunContext(options: RunOptions, context: RunContext): RunOptions;

package/dist/agent/domain/runContext.js

@@ -0,0 +1,47 @@
+/**
+ * What one top-level run shares with every agent and tool inside it, across all its roles,
+ * rounds and retries, such as the record of what it wrote. Whatever a tool starts for the run
+ * registers how to end it, and the agent that created the context ends it with the run.
+ *
+ * Internal: it travels in `RunOptions` under a symbol, so decorators, which pass the options on
+ * whole, carry it without knowing it exists, and no consumer can see or set it.
+ */
+export class RunContext {
+    finishers = [];
+    /**
+     * 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 = {};
+    /** Ends something the run started, when the run ends. */
+    onFinish(finisher) {
+        this.finishers.push(finisher);
+    }
+    /**
+     * Ends everything registered, all of it even when one fails, and then throws the first
+     * failure.
+     */
+    async finish(end) {
+        const failures = [];
+        for (const finisher of this.finishers.splice(0)) {
+            try {
+                await finisher(end);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length > 0)
+            throw failures[0];
+    }
+}
+const runContextKey = Symbol('mikode-harness.runContext');
+/** The context of the run these options belong to, if an outer agent created one. */
+export function runContextOf(options) {
+    return options[runContextKey];
+}
+/** The same options, carrying `context` for every agent the run reaches. */
+export function withRunContext(options, context) {
+    return { ...options, [runContextKey]: context };
+}
+//# sourceMappingURL=runContext.js.map

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

@@ -0,0 +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","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"]}