@mikode13/harness 11.1.0 → 11.2.0

package/README.md

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

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

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

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

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

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

@@ -45,6 +45,11 @@ export interface Delegation {
     /** Which of the agents that call started, from 1. */
     readonly subagent: number;
     readonly depth: number;
+    /**
+     * The folders it may write in, as real paths, so it never writes more than the agents that
+     * delegated to it: empty when it may write nowhere, absent when none set a limit.
+     */
+    readonly writeCeiling?: readonly string[];
 }
 /** The call that started the agent these options reach, if another agent's tool did. */
 export declare function delegationOf(options: RunOptions): Delegation | undefined;

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

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

package/dist/engines/domain/model/compactor.d.ts

@@ -0,0 +1,40 @@
+import type { ContextTriage } from '#src/llm/domain/contextTriage';
+/**
+ * How an `LLMAgent` keeps its context within the model: the conversation always keeps every part,
+ * and only the context sent to the model is compacted. Internal: the harness's compactors are the
+ * only ones.
+ *
+ * The provider's compactor hands its threshold to the client, and the provider compacts inside
+ * the call that passes it, answering with its own summary first.
+ */
+export interface ProviderCompactor {
+    readonly by: 'provider';
+    /**
+     * The tokens of context at which the provider compacts it, or `undefined` when compaction is
+     * off. A context that no longer fits the model is compacted once all the same.
+     */
+    readonly at: number | undefined;
+}
+/**
+ * The harness's compactor: once the context passes `at`, before the next call, the agent's own
+ * model summarizes it, and what is kept follows the summary word for word. Without a `triage`,
+ * the recent compactor keeps the run's prompt and the run's last `keptSteps` answers of the
+ * model, each with its tool results.
+ */
+export interface RecentCompactor {
+    readonly by: 'harness';
+    /** As `ProviderCompactor.at`. */
+    readonly at: number | undefined;
+    readonly keptSteps: number;
+    /**
+     * Jev's: it keeps the run's prompt, the model's last answer with its tool results, and each
+     * earlier tool result the triage scores `keptScore` or more, with its call. When the triage
+     * fails, the recent compactor chooses instead.
+     */
+    readonly triage?: ContextTriage;
+}
+export type Compactor = ProviderCompactor | RecentCompactor;
+/** The provider's compactor, off: only a context that no longer fits is compacted. */
+export declare const compactionOff: Compactor;
+/** How many answers of the model, with their tool results, the recent compactor keeps. */
+export declare const recentKeptSteps = 10;

package/dist/engines/domain/model/compactor.js

@@ -0,0 +1,5 @@
+/** The provider's compactor, off: only a context that no longer fits is compacted. */
+export const compactionOff = { by: 'provider', at: undefined };
+/** How many answers of the model, with their tool results, the recent compactor keeps. */
+export const recentKeptSteps = 10;
+//# sourceMappingURL=compactor.js.map

package/dist/engines/domain/model/compactor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactor.js","sourceRoot":"","sources":["../../../../src/engines/domain/model/compactor.ts"],"names":[],"mappings":"AAwCA,sFAAsF;AACtF,MAAM,CAAC,MAAM,aAAa,GAAc,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;AAE1E,0FAA0F;AAC1F,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC","sourcesContent":["import type { ContextTriage } from '#src/llm/domain/contextTriage';\n\n/**\n * How an `LLMAgent` keeps its context within the model: the conversation always keeps every part,\n * and only the context sent to the model is compacted. Internal: the harness's compactors are the\n * only ones.\n *\n * The provider's compactor hands its threshold to the client, and the provider compacts inside\n * the call that passes it, answering with its own summary first.\n */\nexport interface ProviderCompactor {\n\treadonly by: 'provider';\n\t/**\n\t * The tokens of context at which the provider compacts it, or `undefined` when compaction is\n\t * off. A context that no longer fits the model is compacted once all the same.\n\t */\n\treadonly at: number | undefined;\n}\n\n/**\n * The harness's compactor: once the context passes `at`, before the next call, the agent's own\n * model summarizes it, and what is kept follows the summary word for word. Without a `triage`,\n * the recent compactor keeps the run's prompt and the run's last `keptSteps` answers of the\n * model, each with its tool results.\n */\nexport interface RecentCompactor {\n\treadonly by: 'harness';\n\t/** As `ProviderCompactor.at`. */\n\treadonly at: number | undefined;\n\treadonly keptSteps: number;\n\t/**\n\t * Jev's: it keeps the run's prompt, the model's last answer with its tool results, and each\n\t * earlier tool result the triage scores `keptScore` or more, with its call. When the triage\n\t * fails, the recent compactor chooses instead.\n\t */\n\treadonly triage?: ContextTriage;\n}\n\nexport type Compactor = ProviderCompactor | RecentCompactor;\n\n/** The provider's compactor, off: only a context that no longer fits is compacted. */\nexport const compactionOff: Compactor = { by: 'provider', at: undefined };\n\n/** How many answers of the model, with their tool results, the recent compactor keeps. */\nexport const recentKeptSteps = 10;\n"]}

package/dist/engines/domain/model/llmAgent.d.ts

@@ -1,9 +1,10 @@
 import { type Agent, type AgentResponse, type RunOptions } from '#src/agent/domain/agent';
 import type { LLMClient } from '#src/llm/domain/llm';
-import type { Message } from '#src/llm/domain/message';
+import { type Message } from '#src/llm/domain/message';
 import type { TranscriptCallback } from '#src/agent/domain/transcript';
 import { type AgentTool } from '#src/tools/domain/preparedCall';
 import type { ILogger } from '#src/shared/domain/logger';
+import { type Compactor } from './compactor.ts';
 import { type HistoryReader } from './historyFollower.ts';
 /**
  * An agent whose conversation is owned by MiKode: every run sends the whole context to a
@@ -24,11 +25,14 @@ export declare class LLMAgent implements Agent {
     private readonly history;
     private readonly summarizer;
     private readonly onTranscript;
+    private readonly writeRoots;
+    private readonly compactor;
+    private contextTokens;
     private seenRevision;
     private readonly reads;
     private readonly runs;
     private readonly session;
-    constructor({ llmClient, messages, tools, maxSteps, autoApprove, logger, history, summarizer, onTranscript, }: {
+    constructor({ llmClient, messages, tools, maxSteps, autoApprove, logger, history, summarizer, onTranscript, writeRoots, compactor, }: {
         llmClient: LLMClient;
         messages?: Message[];
         tools?: AgentTool[];
@@ -51,6 +55,13 @@ export declare class LLMAgent implements Agent {
         summarizer?: LLMClient;
         /** Receives what the model saw in each run, once the run ended. */
         onTranscript?: TranscriptCallback;
+        /**
+         * The `write` roots of the agent's workspace: an agent it delegates to writes only within
+         * them. Empty when it only reads; without it, it sets no limit of its own.
+         */
+        writeRoots?: readonly string[];
+        /** How the context is compacted. Defaults to off: only a context that no longer fits is. */
+        compactor?: Compactor;
     });
     private followHistory;
     /**
@@ -59,6 +70,41 @@ export declare class LLMAgent implements Agent {
      */
     private summarizeUndone;
     private warnSummaryFailed;
+    private warnContextOutgrown;
+    private warnTriageFailed;
+    private warnCompactionFailed;
+    /**
+     * Warns that a summary the model was called for failed. A logger that throws ends the run,
+     * carrying what that call spent, which the run has not counted yet.
+     */
+    private warnSummaryCallFailed;
+    /**
+     * Has the agent's own model summarize the context before the harness compactor's cut, and
+     * records the summary in the run, with what it keeps word for word. With a triage, Jev chooses
+     * what is kept; when it fails, which it logs, the recent cut does. `compacted` is false when
+     * the model had answered too few times, which costs no call, when Jev kept every answer
+     * whole, unless the context no longer fits, or when the summary failed as `summarize` says.
+     */
+    private compactHarness;
+    /**
+     * Where the harness compactor cuts `context`, and what it keeps, as the summary request says
+     * it. `triaged` when Jev was asked and answered.
+     */
+    private harnessCut;
+    private recentChoice;
+    /**
+     * Has the agent's own model summarize what `cut` does not keep, and records the summary in the
+     * run. Once the threshold passed, the model reads `context`, the context as it was last sent,
+     * from its provider's cache; once the context no longer fit, it reads what it summarizes as
+     * text. `compacted` is false when the model wrote no summary or the provider failed in
+     * passing, which it logs; any other failure is thrown. The summary's usage is the run's either
+     * way.
+     *
+     * @param kept what `cut` keeps, as the summary request tells the model.
+     * @param endsRun whether a failure ends the run, which throws why instead of logging it: the
+     * run's context no longer fits. `outgrown` alone may be this call's own fallback.
+     */
+    private summarize;
     private llmCall;
     private narrateStep;
     /**