@mikode13/harness 4.0.0 → 5.0.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:
@@ -152,6 +157,62 @@ example when the other one is out of quota.
 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,17 +225,16 @@ 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
 
@@ -224,18 +284,183 @@ await agent.run('Tidy the docs folder.', {
 
 With no `approve`, a `destructive` call is denied. A denial is not a failure: the
 model receives it, with the reason when there is one, and carries on. Progress
-reports the call with `status: 'denied'`.
+reports the call with `status: 'denied'`. An approver that throws, or answers
+anything but a boolean `approved`, ends the run with an `UnrecoverableError`, unless
+the run was cancelled, and the call never runs.
 
 The harness keeps no state between runs, so "don't ask again" belongs to your
 approver. `rememberApprovals(ask)` builds one: when `ask` answers
 `{ approved: true, remember: true }`, later calls to that tool are allowed without
-asking. Its `key` option decides what counts as the same call, 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.
+asking. An answer whose `approved` or `remember` is not a boolean throws, so it is
+neither run nor remembered. Its `key` option decides what counts as the same call,
+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.
+
+### 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`.
 
-`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.
+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
 
@@ -255,19 +480,59 @@ 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 }
+	}
+}
+```
+
+The CLI shows each command as the line it will run before asking, and "always" allows
+that command again, not every command.
 
-`cli/cli.ts` currently enables `autoApprove` for its trusted backend agents.
+`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,6 +14,12 @@ 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. */
@@ -71,6 +77,12 @@ export type ProgressEvent = {
      * 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: {

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":"AAyCA,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/** 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\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 }[] }\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"]}

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 = {
@@ -42,3 +51,8 @@ export type RememberableDecision = {
 export declare function rememberApprovals(ask: (request: ApprovalRequest, signal: AbortSignal) => RememberableDecision | Promise<RememberableDecision>, { key }?: {
     key?: (request: ApprovalRequest) => string;
 }): Approver;
+/**
+ * Reads an approver's answer without trusting its type, since a JavaScript consumer can return
+ * anything: only an `approved` that is a boolean decides, and anything else throws.
+ */
+export declare function readDecision(answer: unknown): ApprovalDecision;

package/dist/agent/domain/approval.js

@@ -10,14 +10,39 @@ export function rememberApprovals(ask, { key = request => request.tool } = {}) {
         const id = key(request);
         if (allowed.has(id))
             return { approved: true };
-        const decision = await ask(request, signal);
+        const answer = await ask(request, signal);
         // The agent discards an answer that arrives after a cancellation, so it must not be kept.
         signal.throwIfAborted();
+        // Read before keeping anything: a truthy `'false'` would otherwise be allowed and remembered.
+        const decision = readDecision(answer);
         if (!decision.approved)
             return decision;
-        if (decision.remember)
+        if (readRemember(answer))
             allowed.add(id);
-        return { approved: true };
+        return decision;
     };
 }
+/**
+ * Reads an approver's answer without trusting its type, since a JavaScript consumer can return
+ * anything: only an `approved` that is a boolean decides, and anything else throws.
+ */
+export function readDecision(answer) {
+    if (typeof answer !== 'object' || answer === null) {
+        throw new TypeError('The approver answered without a decision');
+    }
+    const { approved, reason } = answer;
+    if (typeof approved !== 'boolean') {
+        throw new TypeError('The approver answered without a boolean `approved`');
+    }
+    return approved
+        ? { approved }
+        : { approved, reason: typeof reason === 'string' ? reason : undefined };
+}
+function readRemember(answer) {
+    const { remember } = answer;
+    if (remember !== undefined && typeof remember !== 'boolean') {
+        throw new TypeError('The approver answered without a boolean `remember`');
+    }
+    return remember === true;
+}
 //# sourceMappingURL=approval.js.map

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,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC5C,0FAA0F;QAC1F,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,IAAI,CAAC,QAAQ,CAAC,QAAQ;YAAE,OAAO,QAAQ,CAAC;QACxC,IAAI,QAAQ,CAAC,QAAQ;YAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC,CAAC;AACH,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 decision = 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\tif (!decision.approved) return decision;\n\t\tif (decision.remember) allowed.add(id);\n\t\treturn { approved: true };\n\t};\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"]}

package/dist/diff/domain/unifiedDiff.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Line diffs in the unified format, with Myers' algorithm. This module imports nothing, so it can
+ * move to a package of its own unchanged.
+ */
+export interface LineDiffOptions {
+    /** Unchanged lines shown around each change. Defaults to 3, as in git. */
+    context?: number;
+    /**
+     * The most lines two texts may differ by before the diff stops looking for the smallest
+     * change and shows the differing middle as removed, then added. Memory grows with its square.
+     */
+    maxDistance?: number;
+}
+/**
+ * The hunks that turn `before` into `after`, each with its `@@` header, or `''` when the texts
+ * are equal. Lines are compared whole, a `\r` included, and a last line without a newline
+ * differs from the same line with one, as git shows it.
+ */
+export declare function unifiedDiff(before: string, after: string, options?: LineDiffOptions): string;