@mikode13/harness 5.3.0 → 5.4.0

package/README.md

@@ -309,6 +309,24 @@ neither run nor remembered. Its `key` option decides what counts as the same cal
 such as the tool and its path. The memory lives as long as the approver you created,
 so create one per session, per user or per run.
 
+A run given `ask` also lets the agent ask its user, through its own `askUser` tool,
+what is theirs to decide: the shape of a public API, a new dependency, behaviour the
+request does not ask for, or a choice with real trade-offs. The model sends one to
+four questions, each with two to four options, and `ask` answers each one in order,
+with the label of an option or with the user's own words:
+
+```ts
+await agent.run('Add a cache to the client.', {
+	signal: controller.signal,
+	ask: async questions => Promise.all(questions.map(question => askYourUser(question))),
+});
+```
+
+Without `ask` the agent has no such tool. Questions the model wrote wrong go back to
+it to correct. An asker that throws, or does not answer each question with some text,
+ends the run with an `UnrecoverableError`. The Agent SDK engines ignore `ask`, and
+`createLLMOrchestrator` passes it to every role.
+
 ### Agents that change files
 
 `createFileTools` gives an agent the file tools of its provider, over the folders you
@@ -523,7 +541,10 @@ 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.
+make `.gitignore` hide less. With `--llm`, any role can also ask you a question: the CLI
+numbers its options, and you answer with a number, several separated by commas where it
+allows more than one, or in your own words. With piped input nobody answers, and the model
+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

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

@@ -1,5 +1,6 @@
 import type { Tokens } from '#src/shared/domain/tokens';
 import type { Approver } from './approval.ts';
+import type { Asker } from './question.ts';
 /**
  * How a run ended when it did not fail. Every token a run spends travels with its end: here
  * when it finishes, in `RecoverableError.tokens` or `UnrecoverableError.tokens` when it fails.
@@ -23,8 +24,10 @@ export interface AgentResponse {
 }
 export type Callback = (item: ProgressEvent) => void;
 /**
- * What a run needs besides its prompt. RetryingAgent and InstructedAgent pass it on whole;
- * OrchestratorAgent copies its own enumerable fields and replaces only `onProgress` per role.
+ * What a run needs besides its prompt. InstructedAgent passes it on whole. OrchestratorAgent
+ * copies its own enumerable fields and replaces only `onProgress` per role; RetryingAgent does
+ * the same for a run with `ask`, replacing only `ask`. A field must therefore be an own
+ * enumerable one to reach every agent.
  */
 export interface RunOptions {
     /** Cancels the run, which then rejects with the signal's `AbortError`. */
@@ -37,6 +40,12 @@ export interface RunOptions {
      * it: their own permission systems decide.
      */
     approve?: Approver | undefined;
+    /**
+     * Answers what a model-backed agent asks the user, through its `askUser` tool, when a
+     * decision is the user's to make. Without it the agent has no such tool. The Agent SDK
+     * engines ignore it.
+     */
+    ask?: Asker | undefined;
 }
 /** The `onProgress` of a run that gave none. */
 export declare const ignoreProgress: Callback;

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

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/agent/domain/agent.ts"],"names":[],"mappings":"AA4CA,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAa,GAAG,EAAE,CAAC,SAAS,CAAC","sourcesContent":["import type { Tokens } from '#src/shared/domain/tokens';\nimport type { Approver } from './approval.ts';\n\n/**\n * How a run ended when it did not fail. Every token a run spends travels with its end: here\n * when it finishes, in `RecoverableError.tokens` or `UnrecoverableError.tokens` when it fails.\n */\nexport interface AgentResponse {\n\t/** The final text. Empty when the run produced none, for example a turn that only edited files. */\n\tresponse: string;\n\t/**\n\t * Missing when any call in the run completed without reporting usage, which is not the same\n\t * as zero: a partial sum would look complete.\n\t */\n\ttokens?: Tokens;\n\t/** Wall-clock seconds the consumer waited for the run, retries and every role included. */\n\tduration: number;\n\t/**\n\t * The run the workspace's history recorded, when this run wrote through the harness's write\n\t * tools. Absent for a run that wrote nothing, and from the Agent SDK engines, whose changes\n\t * the history does not record.\n\t */\n\trunId?: string;\n}\n\nexport type Callback = (item: ProgressEvent) => void;\n\n/**\n * What a run needs besides its prompt. RetryingAgent and InstructedAgent pass it on whole;\n * OrchestratorAgent copies its own enumerable fields and replaces only `onProgress` per role.\n */\nexport interface RunOptions {\n\t/** Cancels the run, which then rejects with the signal's `AbortError`. */\n\tsignal: AbortSignal;\n\t/** Receives the run's live activity. Without it, the run is silent. */\n\tonProgress?: Callback | undefined;\n\t/**\n\t * Asked before a model-backed agent runs a `destructive` tool call. Without it, such a call\n\t * is denied. An agent built with `autoApprove` never asks, and the Agent SDK engines ignore\n\t * it: their own permission systems decide.\n\t */\n\tapprove?: Approver | undefined;\n}\n\n/** The `onProgress` of a run that gave none. */\nexport const ignoreProgress: Callback = () => undefined;\n\n/**\n * Live activity during a run, for narration only: the result travels in `AgentResponse`.\n * New event types can arrive in a minor release, so render the types you know and ignore\n * the rest instead of switching over them exhaustively with a `never` check.\n */\nexport type ProgressEvent =\n\t| { type: 'command'; command: string; exitCode?: number; agent?: ProgressAgent }\n\t| { type: 'reasoning'; message: string; agent?: ProgressAgent }\n\t| { type: 'search'; query: string; agent?: ProgressAgent }\n\t| {\n\t\t\ttype: 'fileChange';\n\t\t\tchanges: { path: string; kind: 'add' | 'update' | 'delete' }[];\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t| { type: 'mcpTool'; server: string; tool: string; status: string; agent?: ProgressAgent }\n\t| { type: 'agentMessage'; message: string; agent?: ProgressAgent }\n\t/** `id` pairs a call's end with its start when one step calls the same tool more than once. */\n\t| {\n\t\t\ttype: 'tool';\n\t\t\tid: string;\n\t\t\tname: string;\n\t\t\tagent?: ProgressAgent;\n\t\t\t/** A short, tool-owned description of the call. Narration only. */\n\t\t\tsummary?: string;\n\t\t\t/** The exit code of a configured command that ended with an error. Narration only. */\n\t\t\texitCode?: number;\n\t\t\t/**\n\t\t\t * `in_progress` only once the call is about to run, after any approval. `denied` when\n\t\t\t * it never ran because no one allowed it, with no `in_progress` before it.\n\t\t\t */\n\t\t\tstatus: 'in_progress' | 'completed' | 'error' | 'denied';\n\t\t\t/**\n\t\t\t * On `completed`, for a call that changed a file through the harness's write tools: the\n\t\t\t * change as a unified diff, for the person watching. Narration only; the run's whole\n\t\t\t * record is the history's `changes`.\n\t\t\t */\n\t\t\tdiff?: string;\n\t  }\n\t| { type: 'todoList'; items: { text: string; completed: boolean }[]; agent?: ProgressAgent }\n\t| { type: 'turnStarted'; agent?: ProgressAgent }\n\t| { type: 'turnEnded'; agent?: ProgressAgent }\n\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\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/** The text of the user's prompts and the model's answers. */\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` 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":"AAqDA,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAa,GAAG,EAAE,CAAC,SAAS,CAAC","sourcesContent":["import type { Tokens } from '#src/shared/domain/tokens';\nimport type { Approver } from './approval.ts';\nimport type { Asker } from './question.ts';\n\n/**\n * How a run ended when it did not fail. Every token a run spends travels with its end: here\n * when it finishes, in `RecoverableError.tokens` or `UnrecoverableError.tokens` when it fails.\n */\nexport interface AgentResponse {\n\t/** The final text. Empty when the run produced none, for example a turn that only edited files. */\n\tresponse: string;\n\t/**\n\t * Missing when any call in the run completed without reporting usage, which is not the same\n\t * as zero: a partial sum would look complete.\n\t */\n\ttokens?: Tokens;\n\t/** Wall-clock seconds the consumer waited for the run, retries and every role included. */\n\tduration: number;\n\t/**\n\t * The run the workspace's history recorded, when this run wrote through the harness's write\n\t * tools. Absent for a run that wrote nothing, and from the Agent SDK engines, whose changes\n\t * the history does not record.\n\t */\n\trunId?: string;\n}\n\nexport type Callback = (item: ProgressEvent) => void;\n\n/**\n * What a run needs besides its prompt. InstructedAgent passes it on whole. OrchestratorAgent\n * copies its own enumerable fields and replaces only `onProgress` per role; RetryingAgent does\n * the same for a run with `ask`, replacing only `ask`. A field must therefore be an own\n * enumerable one to reach every agent.\n */\nexport interface RunOptions {\n\t/** 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\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.\n\t */\n\task?: Asker | undefined;\n}\n\n/** The `onProgress` of a run that gave none. */\nexport const ignoreProgress: Callback = () => undefined;\n\n/**\n * Live activity during a run, for narration only: the result travels in `AgentResponse`.\n * New event types can arrive in a minor release, so render the types you know and ignore\n * the rest instead of switching over them exhaustively with a `never` check.\n */\nexport type ProgressEvent =\n\t| { type: 'command'; command: string; exitCode?: number; agent?: ProgressAgent }\n\t| { type: 'reasoning'; message: string; agent?: ProgressAgent }\n\t| { type: 'search'; query: string; agent?: ProgressAgent }\n\t| {\n\t\t\ttype: 'fileChange';\n\t\t\tchanges: { path: string; kind: 'add' | 'update' | 'delete' }[];\n\t\t\tagent?: ProgressAgent;\n\t  }\n\t| { type: 'mcpTool'; server: string; tool: string; status: string; agent?: ProgressAgent }\n\t| { type: 'agentMessage'; message: string; agent?: ProgressAgent }\n\t/** `id` pairs a call's end with its start when one step calls the same tool more than once. */\n\t| {\n\t\t\ttype: 'tool';\n\t\t\tid: string;\n\t\t\tname: string;\n\t\t\tagent?: ProgressAgent;\n\t\t\t/** A short, tool-owned description of the call. Narration only. */\n\t\t\tsummary?: string;\n\t\t\t/** The exit code of a configured command that ended with an error. Narration only. */\n\t\t\texitCode?: number;\n\t\t\t/**\n\t\t\t * `in_progress` only once the call is about to run, after any approval. `denied` when\n\t\t\t * it never ran because no one allowed it, with no `in_progress` before it.\n\t\t\t */\n\t\t\tstatus: 'in_progress' | 'completed' | 'error' | 'denied';\n\t\t\t/**\n\t\t\t * On `completed`, for a call that changed a file through the harness's write tools: the\n\t\t\t * change as a unified diff, for the person watching. Narration only; the run's whole\n\t\t\t * record is the history's `changes`.\n\t\t\t */\n\t\t\tdiff?: string;\n\t  }\n\t| { type: 'todoList'; items: { text: string; completed: boolean }[]; agent?: ProgressAgent }\n\t| { type: 'turnStarted'; agent?: ProgressAgent }\n\t| { type: 'turnEnded'; agent?: ProgressAgent }\n\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\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/** The text of the user's prompts and the model's answers. */\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` 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/question.d.ts

@@ -0,0 +1,35 @@
+/** One choice the model offers for a question. */
+export interface QuestionOption {
+    label: string;
+    description: string;
+}
+/** A decision the model leaves to the user, with the choices it sees. */
+export interface UserQuestion {
+    question: string;
+    /** Two to four. The user may always answer in their own words instead. */
+    options: QuestionOption[];
+    /** Whether more than one option may be chosen. */
+    multiSelect: boolean;
+}
+/**
+ * Answers the questions a model-backed agent asks, one answer per question and in order: the
+ * label of each option chosen, or the user's own words. A throw ends the run as an
+ * `UnrecoverableError`, as a failing approver does.
+ */
+export type Asker = (questions: UserQuestion[], signal: AbortSignal) => string[] | Promise<string[]>;
+/** What one run's user answered, as `rememberAnswers` keeps it. */
+export interface AnsweredQuestion {
+    question: string;
+    answer: string;
+}
+/**
+ * Wraps `ask` so a question asked again with the same words gets the answer the user already
+ * gave, and only the others are asked. `answered` holds every answer, in the order given. The
+ * memory lives as long as the returned asker: one per run, so a retry never asks again.
+ */
+export declare function rememberAnswers(ask: Asker): {
+    ask: Asker;
+    answered: AnsweredQuestion[];
+};
+/** The user's earlier answers, for a prompt that must not ask them again. */
+export declare function describeAnswered(answered: AnsweredQuestion[]): string;

package/dist/agent/domain/question.js

@@ -0,0 +1,35 @@
+/**
+ * Wraps `ask` so a question asked again with the same words gets the answer the user already
+ * gave, and only the others are asked. `answered` holds every answer, in the order given. The
+ * memory lives as long as the returned asker: one per run, so a retry never asks again.
+ */
+export function rememberAnswers(ask) {
+    const answered = [];
+    const known = new Map();
+    return {
+        answered,
+        ask: async (questions, signal) => {
+            const unknown = questions.filter(({ question }) => !known.has(question));
+            const fresh = unknown.length > 0 ? await ask(unknown, signal) : [];
+            // The agent checks the asker's answers; a short or odd list is its to refuse.
+            if (!Array.isArray(fresh))
+                return fresh;
+            for (const [index, { question }] of unknown.entries()) {
+                const answer = fresh[index];
+                if (typeof answer !== 'string')
+                    return fresh;
+                known.set(question, answer);
+                answered.push({ question, answer });
+            }
+            return questions.map(({ question }) => known.get(question) ?? '');
+        },
+    };
+}
+/** The user's earlier answers, for a prompt that must not ask them again. */
+export function describeAnswered(answered) {
+    return [
+        'The user already answered these questions in an earlier attempt; do not ask them again:',
+        ...answered.map(({ question, answer }, index) => `${String(index + 1)}. ${question}\n   ${answer}`),
+    ].join('\n');
+}
+//# sourceMappingURL=question.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"question.js","sourceRoot":"","sources":["../../../src/agent/domain/question.ts"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAU;IACzC,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAExC,OAAO;QACN,QAAQ;QACR,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE;YAChC,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;YACzE,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,8EAA8E;YAC9E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACxC,KAAK,MAAM,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;gBACvD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC5B,IAAI,OAAO,MAAM,KAAK,QAAQ;oBAAE,OAAO,KAAK,CAAC;gBAC7C,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YACrC,CAAC;YACD,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACnE,CAAC;KACD,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAAC,QAA4B;IAC5D,OAAO;QACN,yFAAyF;QACzF,GAAG,QAAQ,CAAC,GAAG,CACd,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,QAAQ,QAAQ,MAAM,EAAE,CAClF;KACD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC","sourcesContent":["/** One choice the model offers for a question. */\nexport interface QuestionOption {\n\tlabel: string;\n\tdescription: string;\n}\n\n/** A decision the model leaves to the user, with the choices it sees. */\nexport interface UserQuestion {\n\tquestion: string;\n\t/** Two to four. The user may always answer in their own words instead. */\n\toptions: QuestionOption[];\n\t/** Whether more than one option may be chosen. */\n\tmultiSelect: boolean;\n}\n\n/**\n * Answers the questions a model-backed agent asks, one answer per question and in order: the\n * label of each option chosen, or the user's own words. A throw ends the run as an\n * `UnrecoverableError`, as a failing approver does.\n */\nexport type Asker = (\n\tquestions: UserQuestion[],\n\tsignal: AbortSignal,\n) => string[] | Promise<string[]>;\n\n/** What one run's user answered, as `rememberAnswers` keeps it. */\nexport interface AnsweredQuestion {\n\tquestion: string;\n\tanswer: string;\n}\n\n/**\n * Wraps `ask` so a question asked again with the same words gets the answer the user already\n * gave, and only the others are asked. `answered` holds every answer, in the order given. The\n * memory lives as long as the returned asker: one per run, so a retry never asks again.\n */\nexport function rememberAnswers(ask: Asker): { ask: Asker; answered: AnsweredQuestion[] } {\n\tconst answered: AnsweredQuestion[] = [];\n\tconst known = new Map<string, string>();\n\n\treturn {\n\t\tanswered,\n\t\task: async (questions, signal) => {\n\t\t\tconst unknown = questions.filter(({ question }) => !known.has(question));\n\t\t\tconst fresh = unknown.length > 0 ? await ask(unknown, signal) : [];\n\t\t\t// The agent checks the asker's answers; a short or odd list is its to refuse.\n\t\t\tif (!Array.isArray(fresh)) return fresh;\n\t\t\tfor (const [index, { question }] of unknown.entries()) {\n\t\t\t\tconst answer = fresh[index];\n\t\t\t\tif (typeof answer !== 'string') return fresh;\n\t\t\t\tknown.set(question, answer);\n\t\t\t\tanswered.push({ question, answer });\n\t\t\t}\n\t\t\treturn questions.map(({ question }) => known.get(question) ?? '');\n\t\t},\n\t};\n}\n\n/** The user's earlier answers, for a prompt that must not ask them again. */\nexport function describeAnswered(answered: AnsweredQuestion[]): string {\n\treturn [\n\t\t'The user already answered these questions in an earlier attempt; do not ask them again:',\n\t\t...answered.map(\n\t\t\t({ question, answer }, index) => `${String(index + 1)}. ${question}\\n   ${answer}`,\n\t\t),\n\t].join('\\n');\n}\n"]}

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

@@ -0,0 +1,14 @@
+import type { UserQuestion } from '#src/agent/domain/question';
+import type { ToolDefinition } from '#src/llm/domain/tool';
+export declare const askUserName = "askUser";
+export declare const askUserDefinition: ToolDefinition;
+/** The questions in a call's input, or why they cannot be asked, which the model reads. */
+export declare function readQuestions(input: unknown): UserQuestion[] | string;
+/**
+ * The asker's answers, one non-empty string per question, or nothing: an asker is host code, so
+ * an answer of any other shape is its bug, not the model's.
+ */
+export declare function readAnswers(answers: unknown, questions: UserQuestion[]): string[] | undefined;
+/** What the model reads back: each question with its answer. */
+export declare function describeAnswers(questions: UserQuestion[], answers: string[]): string;
+export declare function summarizeQuestions(questions: UserQuestion[]): string;

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

@@ -0,0 +1,107 @@
+export const askUserName = 'askUser';
+const maxQuestions = 4;
+const minOptions = 2;
+const maxOptions = 4;
+// Strict mode allows no length bounds, so the counts live in the description and in `readQuestions`.
+export const askUserDefinition = {
+    name: askUserName,
+    description: [
+        'Asks the user to decide something that is theirs to decide, and waits for the answer.',
+        'Ask before you build on a choice, not after. The user decides: the shape of a public API or of anything other code depends on; a new dependency; behaviour the request does not ask for; and any choice between options with real trade-offs.',
+        'Do not ask what the repository, the request or a reasonable default already answers; find it out instead.',
+        `Ask everything you need in one call: 1 to ${String(maxQuestions)} questions, each with ${String(minOptions)} to ${String(maxOptions)} options. Say in each option's description what choosing it means. The user may answer in their own words instead.`,
+    ].join(' '),
+    inputSchema: {
+        type: 'object',
+        properties: {
+            questions: {
+                type: 'array',
+                description: `1 to ${String(maxQuestions)} questions.`,
+                items: {
+                    type: 'object',
+                    properties: {
+                        question: { type: 'string', description: 'The whole question, ending with "?".' },
+                        options: {
+                            type: 'array',
+                            description: `${String(minOptions)} to ${String(maxOptions)} choices.`,
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    label: { type: 'string', description: 'A few words.' },
+                                    description: {
+                                        type: 'string',
+                                        description: 'What choosing it means, and what it costs.',
+                                    },
+                                },
+                                required: ['label', 'description'],
+                                additionalProperties: false,
+                            },
+                        },
+                        multiSelect: {
+                            type: 'boolean',
+                            description: 'Whether more than one option may be chosen.',
+                        },
+                    },
+                    required: ['question', 'options', 'multiSelect'],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ['questions'],
+        additionalProperties: false,
+    },
+};
+/** The questions in a call's input, or why they cannot be asked, which the model reads. */
+export function readQuestions(input) {
+    const questions = isRecord(input) ? input.questions : undefined;
+    if (!Array.isArray(questions) || questions.length === 0 || questions.length > maxQuestions) {
+        return `Ask 1 to ${String(maxQuestions)} questions.`;
+    }
+    const read = [];
+    for (const [index, question] of questions.entries()) {
+        const at = `Question ${String(index + 1)}`;
+        if (!isRecord(question) || !isText(question.question))
+            return `${at} has no text.`;
+        const { options, multiSelect } = question;
+        if (!Array.isArray(options) || options.length < minOptions || options.length > maxOptions) {
+            return `${at} needs ${String(minOptions)} to ${String(maxOptions)} options.`;
+        }
+        if (typeof multiSelect !== 'boolean')
+            return `${at} must say whether it is multiSelect.`;
+        const choices = [];
+        for (const option of options) {
+            if (!isRecord(option) || !isText(option.label) || typeof option.description !== 'string') {
+                return `Every option of ${at.toLowerCase()} needs a label and a description.`;
+            }
+            choices.push({ label: option.label, description: option.description });
+        }
+        read.push({ question: question.question, options: choices, multiSelect });
+    }
+    return read;
+}
+/**
+ * The asker's answers, one non-empty string per question, or nothing: an asker is host code, so
+ * an answer of any other shape is its bug, not the model's.
+ */
+export function readAnswers(answers, questions) {
+    if (!Array.isArray(answers) || answers.length !== questions.length)
+        return undefined;
+    return answers.every(isText) ? answers : undefined;
+}
+/** What the model reads back: each question with its answer. */
+export function describeAnswers(questions, answers) {
+    return [
+        'The user answered:',
+        ...questions.map(({ question }, index) => `${String(index + 1)}. ${question}\n   ${answers[index] ?? ''}`),
+    ].join('\n');
+}
+export function summarizeQuestions(questions) {
+    return questions.length === 1 ? '1 question' : `${String(questions.length)} questions`;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isText(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+//# sourceMappingURL=askUser.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"askUser.js","sourceRoot":"","sources":["../../../../src/engines/domain/model/askUser.ts"],"names":[],"mappings":"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","sourcesContent":["import type { UserQuestion } from '#src/agent/domain/question';\nimport type { ToolDefinition } from '#src/llm/domain/tool';\n\nexport const askUserName = 'askUser';\n\nconst maxQuestions = 4;\nconst minOptions = 2;\nconst maxOptions = 4;\n\n// Strict mode allows no length bounds, so the counts live in the description and in `readQuestions`.\nexport const askUserDefinition: ToolDefinition = {\n\tname: askUserName,\n\tdescription: [\n\t\t'Asks the user to decide something that is theirs to decide, and waits for the answer.',\n\t\t'Ask before you build on a choice, not after. The user decides: the shape of a public API or of anything other code depends on; a new dependency; behaviour the request does not ask for; and any choice between options with real trade-offs.',\n\t\t'Do not ask what the repository, the request or a reasonable default already answers; find it out instead.',\n\t\t`Ask everything you need in one call: 1 to ${String(maxQuestions)} questions, each with ${String(minOptions)} to ${String(maxOptions)} options. Say in each option's description what choosing it means. The user may answer in their own words instead.`,\n\t].join(' '),\n\tinputSchema: {\n\t\ttype: 'object',\n\t\tproperties: {\n\t\t\tquestions: {\n\t\t\t\ttype: 'array',\n\t\t\t\tdescription: `1 to ${String(maxQuestions)} questions.`,\n\t\t\t\titems: {\n\t\t\t\t\ttype: 'object',\n\t\t\t\t\tproperties: {\n\t\t\t\t\t\tquestion: { type: 'string', description: 'The whole question, ending with \"?\".' },\n\t\t\t\t\t\toptions: {\n\t\t\t\t\t\t\ttype: 'array',\n\t\t\t\t\t\t\tdescription: `${String(minOptions)} to ${String(maxOptions)} choices.`,\n\t\t\t\t\t\t\titems: {\n\t\t\t\t\t\t\t\ttype: 'object',\n\t\t\t\t\t\t\t\tproperties: {\n\t\t\t\t\t\t\t\t\tlabel: { type: 'string', description: 'A few words.' },\n\t\t\t\t\t\t\t\t\tdescription: {\n\t\t\t\t\t\t\t\t\t\ttype: 'string',\n\t\t\t\t\t\t\t\t\t\tdescription: 'What choosing it means, and what it costs.',\n\t\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\trequired: ['label', 'description'],\n\t\t\t\t\t\t\t\tadditionalProperties: false,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t\tmultiSelect: {\n\t\t\t\t\t\t\ttype: 'boolean',\n\t\t\t\t\t\t\tdescription: 'Whether more than one option may be chosen.',\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t\trequired: ['question', 'options', 'multiSelect'],\n\t\t\t\t\tadditionalProperties: false,\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t\trequired: ['questions'],\n\t\tadditionalProperties: false,\n\t},\n};\n\n/** The questions in a call's input, or why they cannot be asked, which the model reads. */\nexport function readQuestions(input: unknown): UserQuestion[] | string {\n\tconst questions = isRecord(input) ? input.questions : undefined;\n\tif (!Array.isArray(questions) || questions.length === 0 || questions.length > maxQuestions) {\n\t\treturn `Ask 1 to ${String(maxQuestions)} questions.`;\n\t}\n\tconst read: UserQuestion[] = [];\n\tfor (const [index, question] of questions.entries()) {\n\t\tconst at = `Question ${String(index + 1)}`;\n\t\tif (!isRecord(question) || !isText(question.question)) return `${at} has no text.`;\n\t\tconst { options, multiSelect } = question;\n\t\tif (!Array.isArray(options) || options.length < minOptions || options.length > maxOptions) {\n\t\t\treturn `${at} needs ${String(minOptions)} to ${String(maxOptions)} options.`;\n\t\t}\n\t\tif (typeof multiSelect !== 'boolean') return `${at} must say whether it is multiSelect.`;\n\t\tconst choices = [];\n\t\tfor (const option of options) {\n\t\t\tif (!isRecord(option) || !isText(option.label) || typeof option.description !== 'string') {\n\t\t\t\treturn `Every option of ${at.toLowerCase()} needs a label and a description.`;\n\t\t\t}\n\t\t\tchoices.push({ label: option.label, description: option.description });\n\t\t}\n\t\tread.push({ question: question.question, options: choices, multiSelect });\n\t}\n\treturn read;\n}\n\n/**\n * The asker's answers, one non-empty string per question, or nothing: an asker is host code, so\n * an answer of any other shape is its bug, not the model's.\n */\nexport function readAnswers(answers: unknown, questions: UserQuestion[]): string[] | undefined {\n\tif (!Array.isArray(answers) || answers.length !== questions.length) return undefined;\n\treturn answers.every(isText) ? answers : undefined;\n}\n\n/** What the model reads back: each question with its answer. */\nexport function describeAnswers(questions: UserQuestion[], answers: string[]): string {\n\treturn [\n\t\t'The user answered:',\n\t\t...questions.map(\n\t\t\t({ question }, index) => `${String(index + 1)}. ${question}\\n   ${answers[index] ?? ''}`,\n\t\t),\n\t].join('\\n');\n}\n\nexport function summarizeQuestions(questions: UserQuestion[]): string {\n\treturn questions.length === 1 ? '1 question' : `${String(questions.length)} questions`;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isText(value: unknown): value is string {\n\treturn typeof value === 'string' && value.trim() !== '';\n}\n"]}

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

@@ -67,6 +67,11 @@ export declare class LLMAgent implements Agent {
      * escapes, whatever error the tool turned it into.
      */
     private runTool;
+    /**
+     * Asks the user through the run's `ask`. Questions the model wrote wrong go back to it, to
+     * correct; an asker that fails or answers wrongly is host code, and ends the run.
+     */
+    private askUser;
     /** One at a time and in order, so their effects and their narration never interleave. */
     private runTools;
     /**

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

@@ -11,6 +11,7 @@ import { InvalidToolInputError } from '#src/tools/domain/tool';
 import { isAbortError } from '#src/shared/domain/isAbortError';
 import { addTokens } from '#src/shared/domain/tokens';
 import { measureContext } from "./stepContext.js";
+import { askUserDefinition, askUserName, describeAnswers, readAnswers, readQuestions, summarizeQuestions, } from "./askUser.js";
 import { followHistory, transcriptOf, undoNote, } from "./historyFollower.js";
 function describePart(part) {
     switch (part.type) {
@@ -115,6 +116,9 @@ export class LLMAgent {
             // The model calls tools by name, so a second one with the same name could never run.
             throw new InvalidAgentConfigError('Two tools share a name; each name must be unique');
         }
+        if (this.tools.has(askUserName)) {
+            throw new InvalidAgentConfigError(`"${askUserName}" is the agent's own tool for a run given \`ask\`; name the tool otherwise`);
+        }
         // The client only describes the tools to the model; running them stays with the agent.
         this.toolDefinitions = tools.map(tool => {
             const definition = {
@@ -183,12 +187,12 @@ export class LLMAgent {
             this.logger?.warn(`The summary of the undone turns failed: ${why}`);
         }, classifyHostFailure, 'LLM agent logger failed');
     }
-    async llmCall(runMessages, after, { signal, step, callback }) {
+    async llmCall(runMessages, after, { signal, step, callback, tools, }) {
         // Sent as a copy, so what the run records is what the agent built, whatever the client does.
         const context = [...this.conversation.contextAfter(after), ...structuredClone(runMessages)];
         let response;
         try {
-            response = await this.llmClient.send({ context, tools: this.toolDefinitions }, signal);
+            response = await this.llmClient.send({ context, tools }, signal);
         }
         catch (error) {
             const failure = classifyProviderFailure(error, 'The LLM call failed');
@@ -197,7 +201,7 @@ export class LLMAgent {
             if ((failure instanceof RecoverableError || failure instanceof UnrecoverableError) &&
                 (failure.tokens !== undefined || failure.usageUnreported)) {
                 try {
-                    this.narrateStep(step, failure.tokens, context, callback);
+                    this.narrateStep(step, failure.tokens, { context, tools }, callback);
                 }
                 catch (hostFailure) {
                     // The callback's failure ends the run, and must carry this call's tokens too.
@@ -216,8 +220,8 @@ export class LLMAgent {
             context: measureContext({
                 instructions: this.llmClient.systemPrompt,
                 providerDataSource: this.llmClient.providerDataSource,
-                tools: this.toolDefinitions,
-                context: sent,
+                tools: sent.tools,
+                context: sent.context,
                 summarize: call => this.callSummaries.get(call.id),
             }),
         }, callback);
@@ -266,9 +270,11 @@ export class LLMAgent {
      * result, so the model can correct itself. Only a cancellation, or a failing approver,
      * escapes, whatever error the tool turned it into.
      */
-    async runTool(call, { signal, onProgress: callback = ignoreProgress, approve }, effects, toolCall) {
+    async runTool(call, { signal, onProgress: callback = ignoreProgress, approve, ask }, effects, toolCall) {
         const result = { type: 'toolResult', callId: call.id, name: call.name };
         signal.throwIfAborted();
+        if (call.name === askUserName && ask)
+            return this.askUser(call, ask, signal, callback);
         const tool = this.tools.get(call.name);
         if (!tool) {
             return {
@@ -358,6 +364,42 @@ export class LLMAgent {
             };
         }
     }
+    /**
+     * Asks the user through the run's `ask`. Questions the model wrote wrong go back to it, to
+     * correct; an asker that fails or answers wrongly is host code, and ends the run.
+     */
+    async askUser(call, ask, signal, callback) {
+        const result = { type: 'toolResult', callId: call.id, name: call.name };
+        const questions = readQuestions(call.input);
+        if (typeof questions === 'string') {
+            return { result: { ...result, output: questions, isError: true }, denied: false };
+        }
+        const summary = summarizeQuestions(questions);
+        this.callSummaries.set(call.id, summary);
+        emit({ type: 'tool', id: call.id, name: call.name, status: 'in_progress', summary }, callback);
+        signal.throwIfAborted();
+        let answers;
+        try {
+            answers = await ask(questions, signal);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            throw classifyHostFailure(error, 'The asker failed');
+        }
+        // An answer that arrives after a cancellation is not given to the model.
+        signal.throwIfAborted();
+        const read = readAnswers(answers, questions);
+        if (!read) {
+            throw new UnrecoverableError('The asker failed', {
+                cause: `It must answer each of the ${String(questions.length)} questions with some text, in order.`,
+            });
+        }
+        return {
+            result: { ...result, output: describeAnswers(questions, read), isError: false },
+            denied: false,
+            summary,
+        };
+    }
     /** One at a time and in order, so their effects and their narration never interleave. */
     async runTools(calls, options, effects, toolCall) {
         const { signal, onProgress: callback = ignoreProgress } = options;
@@ -474,17 +516,22 @@ export class LLMAgent {
             // After following the history, which may have made every earlier read stale.
             const reads = this.reads.begin();
             const repeats = new RepeatedCalls();
+            // The agent's own `askUser` exists only for a run someone can answer.
+            const tools = options.ask
+                ? [...this.toolDefinitions, askUserDefinition]
+                : this.toolDefinitions;
             for (let step = 1; step <= this.maxSteps; step++) {
                 const { response, context: sent } = await this.llmCall(runMessages, after, {
                     signal,
                     step,
                     callback,
+                    tools,
                 });
                 tokens = addTokens(tokens, response.usage);
                 unreported ||= !response.usage;
                 // After the tokens are counted, so a throwing callback still reports them, and for an
                 // unusable answer too: the call was sent, and billed.
-                this.narrateStep(step, response.usage, sent, callback);
+                this.narrateStep(step, response.usage, { context: sent, tools }, callback);
                 if (response.stopReason !== 'completed') {
                     // Its tokens are already counted with the run's, which the failure carries.
                     throw new UnrecoverableError('The LLM stopped before completing its answer', {

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

@@ -1 +1 @@
-{"version":3,"file":"llmAgent.js","sourceRoot":"","sources":["../../../../src/engines/domain/model/llmAgent.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ApprovalDecision,\n\ttype ApprovalRequest,\n\ttype Approver,\n\treadDecision,\n} from '#src/agent/domain/approval';\nimport {\n\ttype Agent,\n\ttype AgentResponse,\n\ttype Callback,\n\ttype ProgressEvent,\n\ttype RunOptions,\n\tignoreProgress,\n} from '#src/agent/domain/agent';\nimport {\n\ttype RunEnd,\n\tRunContext,\n\trunContextOf,\n\twithRunContext,\n} from '#src/agent/domain/runContext';\nimport {\n\tInvalidAgentConfigError,\n\tRecoverableError,\n\tUnrecoverableError,\n\twithSpentTokens,\n} from '#src/shared/domain/errors';\nimport {\n\tclassifyHostFailure,\n\tclassifyLocalFailure,\n\tclassifyProviderFailure,\n\tdescribeFailure,\n\ttreatErrors,\n} from '#src/shared/domain/providerFailure';\nimport { Conversation } from '#src/llm/domain/conversation';\nimport type { LLMClient, LLMResponse } from '#src/llm/domain/llm';\nimport type { Message, MessagePart, ToolCallPart, ToolResultPart } from '#src/llm/domain/message';\nimport { asNative, nativeOf, type ToolDefinition } from '#src/llm/domain/tool';\nimport {\n\ttype AgentTool,\n\ttype PreparedCall,\n\tprepareCall,\n\tToolExecutionError,\n} from '#src/tools/domain/preparedCall';\nimport { ReadRegistry, type ToolCallContext } from '#src/tools/domain/readRegistry';\nimport { InvalidToolInputError } from '#src/tools/domain/tool';\nimport { isAbortError } from '#src/shared/domain/isAbortError';\nimport type { ILogger } from '#src/shared/domain/logger';\nimport { addTokens, type Tokens } from '#src/shared/domain/tokens';\nimport { measureContext } from './stepContext.ts';\nimport {\n\ttype Followed,\n\tfollowHistory,\n\ttype HistoryReader,\n\ttranscriptOf,\n\tundoNote,\n} from './historyFollower.ts';\n\nfunction describePart(part: MessagePart): ProgressEvent | undefined {\n\tswitch (part.type) {\n\t\tcase 'text':\n\t\t\treturn { type: 'agentMessage', message: part.text };\n\t\tcase 'reasoning':\n\t\t\treturn { type: 'reasoning', message: part.text };\n\t\tcase 'toolCall':\n\t\t\treturn { type: 'tool', id: part.id, name: part.name, status: 'in_progress' };\n\t\tcase 'toolResult':\n\t\t\treturn {\n\t\t\t\ttype: 'tool',\n\t\t\t\tid: part.callId,\n\t\t\t\tname: part.name,\n\t\t\t\tstatus: part.isError ? 'error' : 'completed',\n\t\t\t};\n\t\tcase 'providerData':\n\t\t\t// Opaque by design: its readable side, if any, arrives as a reasoning part.\n\t\t\treturn undefined;\n\t}\n}\n\n/**\n * Whether a run reached a tool's `execute`. A missing tool or a denied call never does, so it\n * has no effect a retry could repeat.\n */\ninterface RunEffects {\n\ttoolRan: boolean;\n}\n\nfunction narrate(part: MessagePart, callback: Callback, summary?: string, exitCode?: number): void {\n\tconst event = describePart(part);\n\tif (!event) return;\n\tif (event.type === 'tool') {\n\t\tif (summary !== undefined) event.summary = summary;\n\t\tif (exitCode !== undefined) event.exitCode = exitCode;\n\t}\n\temit(event, callback);\n}\n\nfunction emit(event: ProgressEvent, callback: Callback): void {\n\ttreatErrors(\n\t\t() => {\n\t\t\tcallback(event);\n\t\t},\n\t\tclassifyHostFailure,\n\t\t'LLM agent progress callback failed',\n\t);\n}\n\n/** `value` with the keys of every object sorted, so equal inputs serialize alike. */\nfunction canonical(value: unknown): unknown {\n\tif (Array.isArray(value)) return value.map(canonical);\n\tif (typeof value !== 'object' || value === null) return value;\n\treturn Object.fromEntries(\n\t\tObject.entries(value)\n\t\t\t.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n\t\t\t.map(([key, inner]) => [key, canonical(inner)]),\n\t);\n}\n\n// A model that asks for exactly the same calls this many times in a row is stuck: it already\n// has what they return, and running them again changes nothing.\nconst maxRepeatedSteps = 5;\n\n/** How many steps in a row have asked for exactly the same tool calls, with the same input. */\nclass RepeatedCalls {\n\tprivate last: string | undefined;\n\tprivate times = 0;\n\n\tcount(calls: readonly ToolCallPart[]): number {\n\t\t// Keys sorted at every level: the same input with its properties in another order is the\n\t\t// same call. Arrays, and the order of the calls, keep theirs.\n\t\tconst key = JSON.stringify(calls.map(call => [call.name, canonical(call.input)]));\n\t\tthis.times = key === this.last ? this.times + 1 : 1;\n\t\tthis.last = key;\n\t\treturn this.times;\n\t}\n}\n\n/**\n * An agent whose conversation is owned by MiKode: every run sends the whole context to a\n * stateless `LLMClient`. Within a run the model may call the agent's tools; the agent runs them\n * and sends their results back until the model answers without calling one. Turn boundaries\n * are the consumer's to emit, as with the other engines; this agent only narrates what the\n * model produced and what its tools did.\n */\nexport class LLMAgent implements Agent {\n\tprivate readonly llmClient: LLMClient;\n\tprivate readonly conversation: Conversation;\n\tprivate readonly tools: Map<string, AgentTool>;\n\tprivate readonly toolDefinitions: ToolDefinition[];\n\t// Each call's summary, as its tool gave it when the call ran, so measuring a step that\n\t// resends the call never runs a consumer's summarizer again.\n\tprivate readonly callSummaries = new Map<string, string>();\n\tprivate readonly maxSteps: number;\n\tprivate readonly autoApprove: boolean;\n\tprivate readonly logger: ILogger | undefined;\n\tprivate readonly history: HistoryReader | undefined;\n\tprivate readonly summarizer: LLMClient | undefined;\n\t// The latest move through the history this conversation has followed.\n\tprivate seenRevision = 0;\n\t// What this conversation has seen of each file, so an edit starts from a version it read.\n\tprivate readonly reads = new ReadRegistry();\n\n\tconstructor({\n\t\tllmClient,\n\t\tmessages,\n\t\ttools = [],\n\t\tmaxSteps = 65,\n\t\tautoApprove = false,\n\t\tlogger,\n\t\thistory,\n\t\tsummarizer,\n\t}: {\n\t\tllmClient: LLMClient;\n\t\tmessages?: Message[];\n\t\ttools?: AgentTool[];\n\t\t/** How many calls to the model one run may make before it fails. Defaults to 65. */\n\t\tmaxSteps?: number;\n\t\t/** Runs every tool call without asking, `destructive` ones included. Meant for CI. */\n\t\tautoApprove?: boolean;\n\t\t/** Where a failure the agent absorbs is reported. The factories always pass one. */\n\t\tlogger?: ILogger;\n\t\t/**\n\t\t * The history of the workspace this agent writes to. With it, each run first follows the\n\t\t * moves the user made through that history: the conversation goes back with the\n\t\t * workspace, and the model is told what was undone.\n\t\t */\n\t\thistory?: HistoryReader;\n\t\t/**\n\t\t * A cheap model that summarizes what the undone turns tried and what went wrong. Without\n\t\t * one, the model is told what those turns asked, word for word.\n\t\t */\n\t\tsummarizer?: LLMClient;\n\t}) {\n\t\tif (!Number.isInteger(maxSteps) || maxSteps < 1) {\n\t\t\tthrow new InvalidAgentConfigError(\n\t\t\t\t`maxSteps must be a positive integer; got ${String(maxSteps)}`,\n\t\t\t);\n\t\t}\n\n\t\tthis.llmClient = llmClient;\n\t\tthis.conversation = new Conversation(messages);\n\t\tthis.maxSteps = maxSteps;\n\t\tthis.autoApprove = autoApprove;\n\t\tthis.logger = logger;\n\t\tthis.history = history;\n\t\tthis.summarizer = summarizer;\n\t\tthis.tools = new Map(tools.map(tool => [tool.name, tool]));\n\t\tif (this.tools.size !== tools.length) {\n\t\t\t// The model calls tools by name, so a second one with the same name could never run.\n\t\t\tthrow new InvalidAgentConfigError('Two tools share a name; each name must be unique');\n\t\t}\n\t\t// The client only describes the tools to the model; running them stays with the agent.\n\t\tthis.toolDefinitions = tools.map(tool => {\n\t\t\tconst definition = {\n\t\t\t\tname: tool.name,\n\t\t\t\tdescription: tool.description,\n\t\t\t\tinputSchema: tool.inputSchema,\n\t\t\t};\n\t\t\tconst native = nativeOf(tool);\n\t\t\tif (native === undefined) return definition;\n\t\t\t// Checked now, not on the first call: an agent its client cannot serve is a setup error.\n\t\t\tif (llmClient.supportsNative?.(native) !== true) {\n\t\t\t\tthrow new InvalidAgentConfigError(\n\t\t\t\t\t`The tool \"${tool.name}\" is the native \"${native}\" tool, which this model client cannot declare`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn asNative(definition, native);\n\t\t});\n\t}\n\n\tprivate async followHistory(history: HistoryReader): Promise<Followed> {\n\t\ttry {\n\t\t\treturn await followHistory(this.conversation, history, this.seenRevision);\n\t\t} catch (error) {\n\t\t\tthrow classifyLocalFailure(error, 'The workspace history could not be read');\n\t\t}\n\t}\n\n\t/**\n\t * Asks the summarizer what the undone turns tried and what went wrong. A summary is a help,\n\t * not a need: one that fails is reported and the plain note is used instead.\n\t */\n\tprivate async summarizeUndone(\n\t\tfollowed: Followed,\n\t\tsignal: AbortSignal,\n\t): Promise<{ text?: string; usage?: Tokens; called: boolean }> {\n\t\tif (!this.summarizer) return { called: false };\n\t\tconst reasons = followed.revisions.flatMap(revision =>\n\t\t\trevision.reason ? [revision.reason] : [],\n\t\t);\n\t\tconst prompt = [\n\t\t\t'The user undid the work in the conversation below and moved the workspace back to before it.',\n\t\t\treasons.length > 0 ? `Their reason: ${reasons.map(reason => `«${reason}»`).join(' ')}` : '',\n\t\t\t'In at most five short lines, say what was tried, why it went wrong or why the user went back, and what could be done better. Plain text, no preamble.',\n\t\t\t'',\n\t\t\ttranscriptOf(this.conversation, followed.undone),\n\t\t].join('\\n');\n\n\t\tlet response: LLMResponse;\n\t\ttry {\n\t\t\tresponse = await this.summarizer.send(\n\t\t\t\t{ context: [{ role: 'user', content: [{ type: 'text', text: prompt }] }], tools: [] },\n\t\t\t\tsignal,\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tif (isAbortError(error)) throw error;\n\t\t\tthis.warnSummaryFailed(describeFailure(error));\n\t\t\treturn { called: true };\n\t\t}\n\n\t\tconst usage = response.usage ? { usage: response.usage } : {};\n\t\t// A refused or cut summary is not one: the model would read it as what was tried.\n\t\tif (response.stopReason !== 'completed') {\n\t\t\tthis.warnSummaryFailed(`the model stopped with \"${response.stopReason}\"`);\n\t\t\treturn { ...usage, called: true };\n\t\t}\n\t\tconst text = response.message.content\n\t\t\t.filter(part => part.type === 'text')\n\t\t\t.map(part => part.text)\n\t\t\t.join('\\n')\n\t\t\t.trim();\n\t\treturn { ...(text ? { text } : {}), ...usage, called: true };\n\t}\n\n\tprivate warnSummaryFailed(why: string): void {\n\t\ttreatErrors(\n\t\t\t() => {\n\t\t\t\tthis.logger?.warn(`The summary of the undone turns failed: ${why}`);\n\t\t\t},\n\t\t\tclassifyHostFailure,\n\t\t\t'LLM agent logger failed',\n\t\t);\n\t}\n\n\tprivate async llmCall(\n\t\trunMessages: Message[],\n\t\tafter: number | undefined,\n\t\t{ signal, step, callback }: { signal: AbortSignal; step: number; callback: Callback },\n\t): Promise<{ response: LLMResponse; context: Message[] }> {\n\t\t// Sent as a copy, so what the run records is what the agent built, whatever the client does.\n\t\tconst context = [...this.conversation.contextAfter(after), ...structuredClone(runMessages)];\n\t\tlet response: LLMResponse;\n\t\ttry {\n\t\t\tresponse = await this.llmClient.send({ context, tools: this.toolDefinitions }, signal);\n\t\t} catch (error) {\n\t\t\tconst failure = classifyProviderFailure(error, 'The LLM call failed');\n\t\t\t// A client turns some answers into errors, such as a stop at the context window. The\n\t\t\t// call was billed, and the failure carries what it spent: it is still a step.\n\t\t\tif (\n\t\t\t\t(failure instanceof RecoverableError || failure instanceof UnrecoverableError) &&\n\t\t\t\t(failure.tokens !== undefined || failure.usageUnreported)\n\t\t\t) {\n\t\t\t\ttry {\n\t\t\t\t\tthis.narrateStep(step, failure.tokens, context, callback);\n\t\t\t\t} catch (hostFailure) {\n\t\t\t\t\t// The callback's failure ends the run, and must carry this call's tokens too.\n\t\t\t\t\tthrow withSpentTokens(hostFailure, failure.tokens, failure.usageUnreported);\n\t\t\t\t}\n\t\t\t}\n\t\t\tthrow failure;\n\t\t}\n\n\t\treturn { response, context };\n\t}\n\n\tprivate narrateStep(\n\t\tstep: number,\n\t\ttokens: Tokens | undefined,\n\t\tsent: Message[],\n\t\tcallback: Callback,\n\t) {\n\t\temit(\n\t\t\t{\n\t\t\t\ttype: 'step',\n\t\t\t\tstep,\n\t\t\t\t...(tokens ? { tokens } : {}),\n\t\t\t\tcontext: measureContext({\n\t\t\t\t\tinstructions: this.llmClient.systemPrompt,\n\t\t\t\t\tproviderDataSource: this.llmClient.providerDataSource,\n\t\t\t\t\ttools: this.toolDefinitions,\n\t\t\t\t\tcontext: sent,\n\t\t\t\t\tsummarize: call => this.callSummaries.get(call.id),\n\t\t\t\t}),\n\t\t\t},\n\t\t\tcallback,\n\t\t);\n\t}\n\n\t/**\n\t * Undefined when the call may run; otherwise why it may not, which the model receives in its\n\t * place. Only a `destructive` call is asked about: git can undo a `mutating` one. A throwing\n\t * approver ends the run, as any host callback does.\n\t */\n\tprivate async denial(\n\t\tcall: ToolCallPart,\n\t\t{ risk, command }: PreparedCall,\n\t\tsignal: AbortSignal,\n\t\tapprove: Approver | undefined,\n\t): Promise<string | undefined> {\n\t\tif (this.autoApprove || risk !== 'destructive') return undefined;\n\n\t\tconst retry = 'Do not retry the same call; choose another way, or ask the user.';\n\t\tif (!approve) {\n\t\t\treturn `The call to \"${call.name}\" was denied: it is destructive, and no one was asked to allow it. ${retry}`;\n\t\t}\n\n\t\tlet decision: ApprovalDecision;\n\t\ttry {\n\t\t\t// A copy, so what runs and what the conversation keeps is exactly what was approved.\n\t\t\tconst input: unknown = structuredClone(call.input);\n\t\t\t// Read inside the boundary: an untyped approver can answer anything, and a bad answer\n\t\t\t// is its failure, which must carry the run's tokens like any other.\n\t\t\tconst request: ApprovalRequest = {\n\t\t\t\ttool: call.name,\n\t\t\t\tinput,\n\t\t\t\trisk,\n\t\t\t\t// A copy too: the approver must not be able to change what runs.\n\t\t\t\t...(command ? { command: structuredClone(command) } : {}),\n\t\t\t};\n\t\t\tdecision = readDecision(await approve(request, signal));\n\t\t} catch (error) {\n\t\t\t// An approver that gives up on a cancellation, whatever it throws, did not fail.\n\t\t\tsignal.throwIfAborted();\n\t\t\tthrow classifyHostFailure(error, 'The tool call approver failed');\n\t\t}\n\t\t// The user may cancel the run while they are being asked.\n\t\tsignal.throwIfAborted();\n\t\tif (decision.approved) return undefined;\n\n\t\tconst reason = decision.reason ? ` Their reason: ${decision.reason}` : '';\n\t\treturn `The user denied the call to \"${call.name}\".${reason} ${retry}`;\n\t}\n\n\t/**\n\t * Always answers the call: a missing tool, a denied call or a failing one becomes an error\n\t * result, so the model can correct itself. Only a cancellation, or a failing approver,\n\t * escapes, whatever error the tool turned it into.\n\t */\n\tprivate async runTool(\n\t\tcall: ToolCallPart,\n\t\t{ signal, onProgress: callback = ignoreProgress, approve }: RunOptions,\n\t\teffects: RunEffects,\n\t\ttoolCall: ToolCallContext,\n\t): Promise<{\n\t\tresult: ToolResultPart;\n\t\tdenied: boolean;\n\t\tdiff?: string;\n\t\tsummary?: string;\n\t\texitCode?: number;\n\t}> {\n\t\tconst result = { type: 'toolResult' as const, callId: call.id, name: call.name };\n\t\tsignal.throwIfAborted();\n\t\tconst tool = this.tools.get(call.name);\n\t\tif (!tool) {\n\t\t\treturn {\n\t\t\t\tresult: {\n\t\t\t\t\t...result,\n\t\t\t\t\toutput: `There is no tool named \"${call.name}\". Available tools: ${[...this.tools.keys()].join(', ') || 'none'}.`,\n\t\t\t\t\tisError: true,\n\t\t\t\t},\n\t\t\t\tdenied: false,\n\t\t\t};\n\t\t}\n\n\t\tlet summary: string | undefined;\n\t\ttry {\n\t\t\t// This is deliberately before preparation and approval. A consumer-supplied\n\t\t\t// summarizer is host code, and a failed one must never leave an ambiguous call that\n\t\t\t// could be replayed by RetryingAgent.\n\t\t\tsummary = tool.summarize?.(call.input);\n\t\t\tif (summary !== undefined) this.callSummaries.set(call.id, summary);\n\t\t} catch (error) {\n\t\t\tsignal.throwIfAborted();\n\t\t\tif (error instanceof InvalidToolInputError) {\n\t\t\t\treturn {\n\t\t\t\t\tresult: { ...result, output: describeFailure(error), isError: true },\n\t\t\t\t\tdenied: false,\n\t\t\t\t};\n\t\t\t}\n\t\t\tthrow classifyHostFailure(error, 'The tool call summarizer failed');\n\t\t}\n\n\t\tlet prepared: PreparedCall;\n\t\ttry {\n\t\t\tprepared = await prepareCall(tool, call.input, signal, toolCall);\n\t\t} catch (error) {\n\t\t\tsignal.throwIfAborted();\n\t\t\t// A call that cannot be prepared, or whose tool cannot judge it, does not run; the\n\t\t\t// model reads why, such as a refused path, and can correct itself.\n\t\t\treturn {\n\t\t\t\tresult: { ...result, output: describeFailure(error), isError: true },\n\t\t\t\tdenied: false,\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t};\n\t\t}\n\n\t\t// Preparing may have finished after a cancellation it did not notice; nobody is asked to\n\t\t// approve a call in a run that has already stopped.\n\t\tsignal.throwIfAborted();\n\t\tconst denial = await this.denial(call, prepared, signal, approve);\n\t\tif (denial !== undefined) {\n\t\t\treturn {\n\t\t\t\tresult: { ...result, output: denial, isError: true },\n\t\t\t\tdenied: true,\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t};\n\t\t}\n\n\t\t// Deciding took at least one await, and the run may have been cancelled meanwhile.\n\t\tsignal.throwIfAborted();\n\t\t// Announced only once it will run: a missing, failing-to-judge or denied call never is.\n\t\temit(\n\t\t\t{\n\t\t\t\ttype: 'tool',\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tstatus: 'in_progress',\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t},\n\t\t\tcallback,\n\t\t);\n\t\t// Checked again at the last moment: the consumer may cancel on the announcement itself.\n\t\tsignal.throwIfAborted();\n\t\t// Set before `execute`, so a tool that fails halfway still counts: it may have had effects.\n\t\teffects.toolRan = true;\n\t\ttry {\n\t\t\treturn {\n\t\t\t\tresult: { ...result, output: await prepared.run(signal), isError: false },\n\t\t\t\tdenied: false,\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t\t...(prepared.diff === undefined ? {} : { diff: prepared.diff }),\n\t\t\t};\n\t\t} catch (error) {\n\t\t\tsignal.throwIfAborted();\n\t\t\treturn {\n\t\t\t\tresult: { ...result, output: describeFailure(error), isError: true },\n\t\t\t\tdenied: false,\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t\t...(error instanceof ToolExecutionError && error.exitCode !== undefined\n\t\t\t\t\t? { exitCode: error.exitCode }\n\t\t\t\t\t: {}),\n\t\t\t};\n\t\t}\n\t}\n\n\t/** One at a time and in order, so their effects and their narration never interleave. */\n\tprivate async runTools(\n\t\tcalls: ToolCallPart[],\n\t\toptions: RunOptions,\n\t\teffects: RunEffects,\n\t\ttoolCall: ToolCallContext,\n\t): Promise<Message> {\n\t\tconst { signal, onProgress: callback = ignoreProgress } = options;\n\t\tconst results: MessagePart[] = [];\n\t\tfor (const call of calls) {\n\t\t\t// A call before this one may have ignored the cancellation; this one must not start,\n\t\t\t// nor be announced as running.\n\t\t\tsignal.throwIfAborted();\n\t\t\t// `runTool` announces the call only once it is allowed to run, so a consumer never\n\t\t\t// shows a call as running early, nor while the user is still being asked.\n\t\t\tconst { result, denied, diff, summary, exitCode } = await this.runTool(\n\t\t\t\tcall,\n\t\t\t\toptions,\n\t\t\t\teffects,\n\t\t\t\ttoolCall,\n\t\t\t);\n\t\t\tif (denied) {\n\t\t\t\temit(\n\t\t\t\t\t{\n\t\t\t\t\t\ttype: 'tool',\n\t\t\t\t\t\tid: call.id,\n\t\t\t\t\t\tname: call.name,\n\t\t\t\t\t\tstatus: 'denied',\n\t\t\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t\t\t},\n\t\t\t\t\tcallback,\n\t\t\t\t);\n\t\t\t}\n\t\t\t// The diff of a change it made, for the person watching; only once it was made.\n\t\t\telse if (diff !== undefined) {\n\t\t\t\temit(\n\t\t\t\t\t{\n\t\t\t\t\t\ttype: 'tool',\n\t\t\t\t\t\tid: call.id,\n\t\t\t\t\t\tname: call.name,\n\t\t\t\t\t\tstatus: 'completed',\n\t\t\t\t\t\tdiff,\n\t\t\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t\t\t},\n\t\t\t\t\tcallback,\n\t\t\t\t);\n\t\t\t} else narrate(result, callback, summary, exitCode);\n\t\t\tresults.push(result);\n\t\t}\n\n\t\treturn { role: 'tool', content: results };\n\t}\n\n\t/**\n\t * Runs inside the context of the run that reached it, or in one of its own that it ends with\n\t * the run: completed, failed or cancelled. Only a run that owns its context names the history\n\t * run it recorded, since the run is over only when that context ends.\n\t */\n\tasync run(prompt: string, options: RunOptions): Promise<AgentResponse> {\n\t\tconst inherited = runContextOf(options);\n\t\tif (inherited) return this.runSteps(prompt, options, inherited);\n\n\t\tconst context = new RunContext();\n\t\tlet end: RunEnd = 'failed';\n\t\tlet response: AgentResponse;\n\t\ttry {\n\t\t\tresponse = await this.runSteps(prompt, withRunContext(options, context), context);\n\t\t\tend = 'completed';\n\t\t} catch (error) {\n\t\t\tif (isAbortError(error)) end = 'cancelled';\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tawait this.finishContext(context, end);\n\t\t}\n\t\t// Read once the run ended: a run that changed nothing left the history then.\n\t\tconst { runId } = context.historyRun;\n\t\treturn runId ? { ...response, runId } : response;\n\t}\n\n\t/**\n\t * What the run started ends here, but its result stands: the changes it recorded are already\n\t * on disk, so a record that could not be closed is reported, not turned into a failure.\n\t */\n\tprivate async finishContext(context: RunContext, end: RunEnd): Promise<void> {\n\t\ttry {\n\t\t\tawait context.finish(end);\n\t\t} catch (error) {\n\t\t\ttreatErrors(\n\t\t\t\t() => {\n\t\t\t\t\tthis.logger?.warn(`The run could not close its records: ${describeFailure(error)}`);\n\t\t\t\t},\n\t\t\t\tclassifyHostFailure,\n\t\t\t\t'LLM agent logger failed',\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate async runSteps(\n\t\tprompt: string,\n\t\toptions: RunOptions,\n\t\tcontext: RunContext,\n\t): Promise<AgentResponse> {\n\t\tconst { signal, onProgress: callback = ignoreProgress } = options;\n\t\tconst start = Date.now();\n\t\tconst runMessages: Message[] = [{ role: 'user', content: [{ type: 'text', text: prompt }] }];\n\t\tlet tokens: Tokens | undefined;\n\t\t// Once one call went unreported the run's total is unknown, however many report later.\n\t\tlet unreported = false;\n\t\t// Per run, not per instance: what one run executed says nothing about another.\n\t\tconst effects: RunEffects = { toolRan: false };\n\t\t// The turn this one follows: the last recorded, unless the workspace moved since.\n\t\tlet after = this.conversation.currentTurn;\n\t\tlet followed: Followed | undefined;\n\n\t\ttry {\n\t\t\tif (this.history) {\n\t\t\t\tfollowed = await this.followHistory(this.history);\n\t\t\t\tafter = followed.turn;\n\t\t\t\t// The files may no longer hold what the conversation saw of them.\n\t\t\t\tif (followed.revisions.length > 0) this.reads.clear();\n\t\t\t\tif (followed.undone.length > 0) {\n\t\t\t\t\tconst summary = await this.summarizeUndone(followed, signal);\n\t\t\t\t\ttokens = addTokens(tokens, summary.usage);\n\t\t\t\t\tunreported ||= summary.called && !summary.usage;\n\t\t\t\t\tconst note = await undoNote({\n\t\t\t\t\t\tconversation: this.conversation,\n\t\t\t\t\t\thistory: this.history,\n\t\t\t\t\t\tfollowed,\n\t\t\t\t\t\t...(summary.text ? { summary: summary.text } : {}),\n\t\t\t\t\t}).catch((error: unknown) => {\n\t\t\t\t\t\tthrow classifyLocalFailure(error, 'The workspace history could not be read');\n\t\t\t\t\t});\n\t\t\t\t\trunMessages[0]?.content.unshift({ type: 'text', text: note });\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// After following the history, which may have made every earlier read stale.\n\t\t\tconst reads = this.reads.begin();\n\t\t\tconst repeats = new RepeatedCalls();\n\t\t\tfor (let step = 1; step <= this.maxSteps; step++) {\n\t\t\t\tconst { response, context: sent } = await this.llmCall(runMessages, after, {\n\t\t\t\t\tsignal,\n\t\t\t\t\tstep,\n\t\t\t\t\tcallback,\n\t\t\t\t});\n\t\t\t\ttokens = addTokens(tokens, response.usage);\n\t\t\t\tunreported ||= !response.usage;\n\t\t\t\t// After the tokens are counted, so a throwing callback still reports them, and for an\n\t\t\t\t// unusable answer too: the call was sent, and billed.\n\t\t\t\tthis.narrateStep(step, response.usage, sent, callback);\n\t\t\t\tif (response.stopReason !== 'completed') {\n\t\t\t\t\t// Its tokens are already counted with the run's, which the failure carries.\n\t\t\t\t\tthrow new UnrecoverableError('The LLM stopped before completing its answer', {\n\t\t\t\t\t\tcause: `The model stopped with \"${response.stopReason}\".`,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\trunMessages.push(response.message);\n\n\t\t\t\t// Tool calls are narrated as they start, in `runTools`, and never if they do not run.\n\t\t\t\tfor (const part of response.message.content) {\n\t\t\t\t\tif (part.type !== 'toolCall') narrate(part, callback);\n\t\t\t\t}\n\n\t\t\t\tconst calls = response.message.content.filter(part => part.type === 'toolCall');\n\t\t\t\tif (calls.length === 0) {\n\t\t\t\t\t// Recorded only now, so a failed run leaves no tool call without its result, and a\n\t\t\t\t\t// note about what was undone is given again to the next run.\n\t\t\t\t\tthis.conversation.addRunAfter(after, runMessages, context.historyRun);\n\t\t\t\t\t// With the turns that read them, and only then: a failed run is not remembered.\n\t\t\t\t\treads.commit();\n\t\t\t\t\tif (followed) this.seenRevision = followed.latestRevision;\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\t// Only the final answer: text from earlier steps was narrated as it came.\n\t\t\t\t\t\tresponse: response.message.content\n\t\t\t\t\t\t\t.filter(part => part.type === 'text')\n\t\t\t\t\t\t\t.map(part => part.text)\n\t\t\t\t\t\t\t.join('\\n'),\n\t\t\t\t\t\ttokens: unreported ? undefined : tokens,\n\t\t\t\t\t\tduration: (Date.now() - start) / 1000,\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\t// Before running them again: the model has already seen what they return.\n\t\t\t\tif (repeats.count(calls) >= maxRepeatedSteps) {\n\t\t\t\t\tthrow new UnrecoverableError('The LLM repeated the same tool calls', {\n\t\t\t\t\t\tcause: `The model asked for the same tool calls ${String(maxRepeatedSteps)} times in a row.`,\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\t// On the last step no call is left to send the results to, so the tools do not run.\n\t\t\t\tif (step < this.maxSteps) {\n\t\t\t\t\trunMessages.push(await this.runTools(calls, options, effects, { run: context, reads }));\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tthrow new UnrecoverableError('The LLM did not finish within its step limit', {\n\t\t\t\tcause: `The model was still calling tools after ${String(this.maxSteps)} steps.`,\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tlet failure = error;\n\t\t\tif (effects.toolRan && error instanceof RecoverableError) {\n\t\t\t\t// RetryingAgent would run the whole prompt again, and with it every tool this run\n\t\t\t\t// already executed, so a failure after one ran must not invite a retry.\n\t\t\t\tconst unrecoverable = new UnrecoverableError(error.message, {\n\t\t\t\t\tcause: error.cause,\n\t\t\t\t\ttokens: error.tokens,\n\t\t\t\t\tusageUnreported: error.usageUnreported,\n\t\t\t\t});\n\t\t\t\tunrecoverable.stack = error.stack;\n\t\t\t\tfailure = unrecoverable;\n\t\t\t}\n\n\t\t\t// The run spent the tokens of every step before the one that failed.\n\t\t\tthrow withSpentTokens(failure, tokens, unreported);\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"llmAgent.js","sourceRoot":"","sources":["../../../../src/engines/domain/model/llmAgent.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ApprovalDecision,\n\ttype ApprovalRequest,\n\ttype Approver,\n\treadDecision,\n} from '#src/agent/domain/approval';\nimport {\n\ttype Agent,\n\ttype AgentResponse,\n\ttype Callback,\n\ttype ProgressEvent,\n\ttype RunOptions,\n\tignoreProgress,\n} from '#src/agent/domain/agent';\nimport {\n\ttype RunEnd,\n\tRunContext,\n\trunContextOf,\n\twithRunContext,\n} from '#src/agent/domain/runContext';\nimport {\n\tInvalidAgentConfigError,\n\tRecoverableError,\n\tUnrecoverableError,\n\twithSpentTokens,\n} from '#src/shared/domain/errors';\nimport {\n\tclassifyHostFailure,\n\tclassifyLocalFailure,\n\tclassifyProviderFailure,\n\tdescribeFailure,\n\ttreatErrors,\n} from '#src/shared/domain/providerFailure';\nimport { Conversation } from '#src/llm/domain/conversation';\nimport type { LLMClient, LLMResponse } from '#src/llm/domain/llm';\nimport type { Message, MessagePart, ToolCallPart, ToolResultPart } from '#src/llm/domain/message';\nimport { asNative, nativeOf, type ToolDefinition } from '#src/llm/domain/tool';\nimport type { Asker } from '#src/agent/domain/question';\nimport {\n\ttype AgentTool,\n\ttype PreparedCall,\n\tprepareCall,\n\tToolExecutionError,\n} from '#src/tools/domain/preparedCall';\nimport { ReadRegistry, type ToolCallContext } from '#src/tools/domain/readRegistry';\nimport { InvalidToolInputError } from '#src/tools/domain/tool';\nimport { isAbortError } from '#src/shared/domain/isAbortError';\nimport type { ILogger } from '#src/shared/domain/logger';\nimport { addTokens, type Tokens } from '#src/shared/domain/tokens';\nimport { measureContext } from './stepContext.ts';\nimport {\n\taskUserDefinition,\n\taskUserName,\n\tdescribeAnswers,\n\treadAnswers,\n\treadQuestions,\n\tsummarizeQuestions,\n} from './askUser.ts';\nimport {\n\ttype Followed,\n\tfollowHistory,\n\ttype HistoryReader,\n\ttranscriptOf,\n\tundoNote,\n} from './historyFollower.ts';\n\nfunction describePart(part: MessagePart): ProgressEvent | undefined {\n\tswitch (part.type) {\n\t\tcase 'text':\n\t\t\treturn { type: 'agentMessage', message: part.text };\n\t\tcase 'reasoning':\n\t\t\treturn { type: 'reasoning', message: part.text };\n\t\tcase 'toolCall':\n\t\t\treturn { type: 'tool', id: part.id, name: part.name, status: 'in_progress' };\n\t\tcase 'toolResult':\n\t\t\treturn {\n\t\t\t\ttype: 'tool',\n\t\t\t\tid: part.callId,\n\t\t\t\tname: part.name,\n\t\t\t\tstatus: part.isError ? 'error' : 'completed',\n\t\t\t};\n\t\tcase 'providerData':\n\t\t\t// Opaque by design: its readable side, if any, arrives as a reasoning part.\n\t\t\treturn undefined;\n\t}\n}\n\n/**\n * Whether a run reached a tool's `execute`. A missing tool or a denied call never does, so it\n * has no effect a retry could repeat.\n */\ninterface RunEffects {\n\ttoolRan: boolean;\n}\n\nfunction narrate(part: MessagePart, callback: Callback, summary?: string, exitCode?: number): void {\n\tconst event = describePart(part);\n\tif (!event) return;\n\tif (event.type === 'tool') {\n\t\tif (summary !== undefined) event.summary = summary;\n\t\tif (exitCode !== undefined) event.exitCode = exitCode;\n\t}\n\temit(event, callback);\n}\n\nfunction emit(event: ProgressEvent, callback: Callback): void {\n\ttreatErrors(\n\t\t() => {\n\t\t\tcallback(event);\n\t\t},\n\t\tclassifyHostFailure,\n\t\t'LLM agent progress callback failed',\n\t);\n}\n\n/** `value` with the keys of every object sorted, so equal inputs serialize alike. */\nfunction canonical(value: unknown): unknown {\n\tif (Array.isArray(value)) return value.map(canonical);\n\tif (typeof value !== 'object' || value === null) return value;\n\treturn Object.fromEntries(\n\t\tObject.entries(value)\n\t\t\t.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n\t\t\t.map(([key, inner]) => [key, canonical(inner)]),\n\t);\n}\n\n// A model that asks for exactly the same calls this many times in a row is stuck: it already\n// has what they return, and running them again changes nothing.\nconst maxRepeatedSteps = 5;\n\n/** How many steps in a row have asked for exactly the same tool calls, with the same input. */\nclass RepeatedCalls {\n\tprivate last: string | undefined;\n\tprivate times = 0;\n\n\tcount(calls: readonly ToolCallPart[]): number {\n\t\t// Keys sorted at every level: the same input with its properties in another order is the\n\t\t// same call. Arrays, and the order of the calls, keep theirs.\n\t\tconst key = JSON.stringify(calls.map(call => [call.name, canonical(call.input)]));\n\t\tthis.times = key === this.last ? this.times + 1 : 1;\n\t\tthis.last = key;\n\t\treturn this.times;\n\t}\n}\n\n/**\n * An agent whose conversation is owned by MiKode: every run sends the whole context to a\n * stateless `LLMClient`. Within a run the model may call the agent's tools; the agent runs them\n * and sends their results back until the model answers without calling one. Turn boundaries\n * are the consumer's to emit, as with the other engines; this agent only narrates what the\n * model produced and what its tools did.\n */\nexport class LLMAgent implements Agent {\n\tprivate readonly llmClient: LLMClient;\n\tprivate readonly conversation: Conversation;\n\tprivate readonly tools: Map<string, AgentTool>;\n\tprivate readonly toolDefinitions: ToolDefinition[];\n\t// Each call's summary, as its tool gave it when the call ran, so measuring a step that\n\t// resends the call never runs a consumer's summarizer again.\n\tprivate readonly callSummaries = new Map<string, string>();\n\tprivate readonly maxSteps: number;\n\tprivate readonly autoApprove: boolean;\n\tprivate readonly logger: ILogger | undefined;\n\tprivate readonly history: HistoryReader | undefined;\n\tprivate readonly summarizer: LLMClient | undefined;\n\t// The latest move through the history this conversation has followed.\n\tprivate seenRevision = 0;\n\t// What this conversation has seen of each file, so an edit starts from a version it read.\n\tprivate readonly reads = new ReadRegistry();\n\n\tconstructor({\n\t\tllmClient,\n\t\tmessages,\n\t\ttools = [],\n\t\tmaxSteps = 65,\n\t\tautoApprove = false,\n\t\tlogger,\n\t\thistory,\n\t\tsummarizer,\n\t}: {\n\t\tllmClient: LLMClient;\n\t\tmessages?: Message[];\n\t\ttools?: AgentTool[];\n\t\t/** How many calls to the model one run may make before it fails. Defaults to 65. */\n\t\tmaxSteps?: number;\n\t\t/** Runs every tool call without asking, `destructive` ones included. Meant for CI. */\n\t\tautoApprove?: boolean;\n\t\t/** Where a failure the agent absorbs is reported. The factories always pass one. */\n\t\tlogger?: ILogger;\n\t\t/**\n\t\t * The history of the workspace this agent writes to. With it, each run first follows the\n\t\t * moves the user made through that history: the conversation goes back with the\n\t\t * workspace, and the model is told what was undone.\n\t\t */\n\t\thistory?: HistoryReader;\n\t\t/**\n\t\t * A cheap model that summarizes what the undone turns tried and what went wrong. Without\n\t\t * one, the model is told what those turns asked, word for word.\n\t\t */\n\t\tsummarizer?: LLMClient;\n\t}) {\n\t\tif (!Number.isInteger(maxSteps) || maxSteps < 1) {\n\t\t\tthrow new InvalidAgentConfigError(\n\t\t\t\t`maxSteps must be a positive integer; got ${String(maxSteps)}`,\n\t\t\t);\n\t\t}\n\n\t\tthis.llmClient = llmClient;\n\t\tthis.conversation = new Conversation(messages);\n\t\tthis.maxSteps = maxSteps;\n\t\tthis.autoApprove = autoApprove;\n\t\tthis.logger = logger;\n\t\tthis.history = history;\n\t\tthis.summarizer = summarizer;\n\t\tthis.tools = new Map(tools.map(tool => [tool.name, tool]));\n\t\tif (this.tools.size !== tools.length) {\n\t\t\t// The model calls tools by name, so a second one with the same name could never run.\n\t\t\tthrow new InvalidAgentConfigError('Two tools share a name; each name must be unique');\n\t\t}\n\t\tif (this.tools.has(askUserName)) {\n\t\t\tthrow new InvalidAgentConfigError(\n\t\t\t\t`\"${askUserName}\" is the agent's own tool for a run given \\`ask\\`; name the tool otherwise`,\n\t\t\t);\n\t\t}\n\t\t// The client only describes the tools to the model; running them stays with the agent.\n\t\tthis.toolDefinitions = tools.map(tool => {\n\t\t\tconst definition = {\n\t\t\t\tname: tool.name,\n\t\t\t\tdescription: tool.description,\n\t\t\t\tinputSchema: tool.inputSchema,\n\t\t\t};\n\t\t\tconst native = nativeOf(tool);\n\t\t\tif (native === undefined) return definition;\n\t\t\t// Checked now, not on the first call: an agent its client cannot serve is a setup error.\n\t\t\tif (llmClient.supportsNative?.(native) !== true) {\n\t\t\t\tthrow new InvalidAgentConfigError(\n\t\t\t\t\t`The tool \"${tool.name}\" is the native \"${native}\" tool, which this model client cannot declare`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn asNative(definition, native);\n\t\t});\n\t}\n\n\tprivate async followHistory(history: HistoryReader): Promise<Followed> {\n\t\ttry {\n\t\t\treturn await followHistory(this.conversation, history, this.seenRevision);\n\t\t} catch (error) {\n\t\t\tthrow classifyLocalFailure(error, 'The workspace history could not be read');\n\t\t}\n\t}\n\n\t/**\n\t * Asks the summarizer what the undone turns tried and what went wrong. A summary is a help,\n\t * not a need: one that fails is reported and the plain note is used instead.\n\t */\n\tprivate async summarizeUndone(\n\t\tfollowed: Followed,\n\t\tsignal: AbortSignal,\n\t): Promise<{ text?: string; usage?: Tokens; called: boolean }> {\n\t\tif (!this.summarizer) return { called: false };\n\t\tconst reasons = followed.revisions.flatMap(revision =>\n\t\t\trevision.reason ? [revision.reason] : [],\n\t\t);\n\t\tconst prompt = [\n\t\t\t'The user undid the work in the conversation below and moved the workspace back to before it.',\n\t\t\treasons.length > 0 ? `Their reason: ${reasons.map(reason => `«${reason}»`).join(' ')}` : '',\n\t\t\t'In at most five short lines, say what was tried, why it went wrong or why the user went back, and what could be done better. Plain text, no preamble.',\n\t\t\t'',\n\t\t\ttranscriptOf(this.conversation, followed.undone),\n\t\t].join('\\n');\n\n\t\tlet response: LLMResponse;\n\t\ttry {\n\t\t\tresponse = await this.summarizer.send(\n\t\t\t\t{ context: [{ role: 'user', content: [{ type: 'text', text: prompt }] }], tools: [] },\n\t\t\t\tsignal,\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tif (isAbortError(error)) throw error;\n\t\t\tthis.warnSummaryFailed(describeFailure(error));\n\t\t\treturn { called: true };\n\t\t}\n\n\t\tconst usage = response.usage ? { usage: response.usage } : {};\n\t\t// A refused or cut summary is not one: the model would read it as what was tried.\n\t\tif (response.stopReason !== 'completed') {\n\t\t\tthis.warnSummaryFailed(`the model stopped with \"${response.stopReason}\"`);\n\t\t\treturn { ...usage, called: true };\n\t\t}\n\t\tconst text = response.message.content\n\t\t\t.filter(part => part.type === 'text')\n\t\t\t.map(part => part.text)\n\t\t\t.join('\\n')\n\t\t\t.trim();\n\t\treturn { ...(text ? { text } : {}), ...usage, called: true };\n\t}\n\n\tprivate warnSummaryFailed(why: string): void {\n\t\ttreatErrors(\n\t\t\t() => {\n\t\t\t\tthis.logger?.warn(`The summary of the undone turns failed: ${why}`);\n\t\t\t},\n\t\t\tclassifyHostFailure,\n\t\t\t'LLM agent logger failed',\n\t\t);\n\t}\n\n\tprivate async llmCall(\n\t\trunMessages: Message[],\n\t\tafter: number | undefined,\n\t\t{\n\t\t\tsignal,\n\t\t\tstep,\n\t\t\tcallback,\n\t\t\ttools,\n\t\t}: { signal: AbortSignal; step: number; callback: Callback; tools: ToolDefinition[] },\n\t): Promise<{ response: LLMResponse; context: Message[] }> {\n\t\t// Sent as a copy, so what the run records is what the agent built, whatever the client does.\n\t\tconst context = [...this.conversation.contextAfter(after), ...structuredClone(runMessages)];\n\t\tlet response: LLMResponse;\n\t\ttry {\n\t\t\tresponse = await this.llmClient.send({ context, tools }, signal);\n\t\t} catch (error) {\n\t\t\tconst failure = classifyProviderFailure(error, 'The LLM call failed');\n\t\t\t// A client turns some answers into errors, such as a stop at the context window. The\n\t\t\t// call was billed, and the failure carries what it spent: it is still a step.\n\t\t\tif (\n\t\t\t\t(failure instanceof RecoverableError || failure instanceof UnrecoverableError) &&\n\t\t\t\t(failure.tokens !== undefined || failure.usageUnreported)\n\t\t\t) {\n\t\t\t\ttry {\n\t\t\t\t\tthis.narrateStep(step, failure.tokens, { context, tools }, callback);\n\t\t\t\t} catch (hostFailure) {\n\t\t\t\t\t// The callback's failure ends the run, and must carry this call's tokens too.\n\t\t\t\t\tthrow withSpentTokens(hostFailure, failure.tokens, failure.usageUnreported);\n\t\t\t\t}\n\t\t\t}\n\t\t\tthrow failure;\n\t\t}\n\n\t\treturn { response, context };\n\t}\n\n\tprivate narrateStep(\n\t\tstep: number,\n\t\ttokens: Tokens | undefined,\n\t\tsent: { context: Message[]; tools: ToolDefinition[] },\n\t\tcallback: Callback,\n\t) {\n\t\temit(\n\t\t\t{\n\t\t\t\ttype: 'step',\n\t\t\t\tstep,\n\t\t\t\t...(tokens ? { tokens } : {}),\n\t\t\t\tcontext: measureContext({\n\t\t\t\t\tinstructions: this.llmClient.systemPrompt,\n\t\t\t\t\tproviderDataSource: this.llmClient.providerDataSource,\n\t\t\t\t\ttools: sent.tools,\n\t\t\t\t\tcontext: sent.context,\n\t\t\t\t\tsummarize: call => this.callSummaries.get(call.id),\n\t\t\t\t}),\n\t\t\t},\n\t\t\tcallback,\n\t\t);\n\t}\n\n\t/**\n\t * Undefined when the call may run; otherwise why it may not, which the model receives in its\n\t * place. Only a `destructive` call is asked about: git can undo a `mutating` one. A throwing\n\t * approver ends the run, as any host callback does.\n\t */\n\tprivate async denial(\n\t\tcall: ToolCallPart,\n\t\t{ risk, command }: PreparedCall,\n\t\tsignal: AbortSignal,\n\t\tapprove: Approver | undefined,\n\t): Promise<string | undefined> {\n\t\tif (this.autoApprove || risk !== 'destructive') return undefined;\n\n\t\tconst retry = 'Do not retry the same call; choose another way, or ask the user.';\n\t\tif (!approve) {\n\t\t\treturn `The call to \"${call.name}\" was denied: it is destructive, and no one was asked to allow it. ${retry}`;\n\t\t}\n\n\t\tlet decision: ApprovalDecision;\n\t\ttry {\n\t\t\t// A copy, so what runs and what the conversation keeps is exactly what was approved.\n\t\t\tconst input: unknown = structuredClone(call.input);\n\t\t\t// Read inside the boundary: an untyped approver can answer anything, and a bad answer\n\t\t\t// is its failure, which must carry the run's tokens like any other.\n\t\t\tconst request: ApprovalRequest = {\n\t\t\t\ttool: call.name,\n\t\t\t\tinput,\n\t\t\t\trisk,\n\t\t\t\t// A copy too: the approver must not be able to change what runs.\n\t\t\t\t...(command ? { command: structuredClone(command) } : {}),\n\t\t\t};\n\t\t\tdecision = readDecision(await approve(request, signal));\n\t\t} catch (error) {\n\t\t\t// An approver that gives up on a cancellation, whatever it throws, did not fail.\n\t\t\tsignal.throwIfAborted();\n\t\t\tthrow classifyHostFailure(error, 'The tool call approver failed');\n\t\t}\n\t\t// The user may cancel the run while they are being asked.\n\t\tsignal.throwIfAborted();\n\t\tif (decision.approved) return undefined;\n\n\t\tconst reason = decision.reason ? ` Their reason: ${decision.reason}` : '';\n\t\treturn `The user denied the call to \"${call.name}\".${reason} ${retry}`;\n\t}\n\n\t/**\n\t * Always answers the call: a missing tool, a denied call or a failing one becomes an error\n\t * result, so the model can correct itself. Only a cancellation, or a failing approver,\n\t * escapes, whatever error the tool turned it into.\n\t */\n\tprivate async runTool(\n\t\tcall: ToolCallPart,\n\t\t{ signal, onProgress: callback = ignoreProgress, approve, ask }: RunOptions,\n\t\teffects: RunEffects,\n\t\ttoolCall: ToolCallContext,\n\t): Promise<{\n\t\tresult: ToolResultPart;\n\t\tdenied: boolean;\n\t\tdiff?: string;\n\t\tsummary?: string;\n\t\texitCode?: number;\n\t}> {\n\t\tconst result = { type: 'toolResult' as const, callId: call.id, name: call.name };\n\t\tsignal.throwIfAborted();\n\t\tif (call.name === askUserName && ask) return this.askUser(call, ask, signal, callback);\n\t\tconst tool = this.tools.get(call.name);\n\t\tif (!tool) {\n\t\t\treturn {\n\t\t\t\tresult: {\n\t\t\t\t\t...result,\n\t\t\t\t\toutput: `There is no tool named \"${call.name}\". Available tools: ${[...this.tools.keys()].join(', ') || 'none'}.`,\n\t\t\t\t\tisError: true,\n\t\t\t\t},\n\t\t\t\tdenied: false,\n\t\t\t};\n\t\t}\n\n\t\tlet summary: string | undefined;\n\t\ttry {\n\t\t\t// This is deliberately before preparation and approval. A consumer-supplied\n\t\t\t// summarizer is host code, and a failed one must never leave an ambiguous call that\n\t\t\t// could be replayed by RetryingAgent.\n\t\t\tsummary = tool.summarize?.(call.input);\n\t\t\tif (summary !== undefined) this.callSummaries.set(call.id, summary);\n\t\t} catch (error) {\n\t\t\tsignal.throwIfAborted();\n\t\t\tif (error instanceof InvalidToolInputError) {\n\t\t\t\treturn {\n\t\t\t\t\tresult: { ...result, output: describeFailure(error), isError: true },\n\t\t\t\t\tdenied: false,\n\t\t\t\t};\n\t\t\t}\n\t\t\tthrow classifyHostFailure(error, 'The tool call summarizer failed');\n\t\t}\n\n\t\tlet prepared: PreparedCall;\n\t\ttry {\n\t\t\tprepared = await prepareCall(tool, call.input, signal, toolCall);\n\t\t} catch (error) {\n\t\t\tsignal.throwIfAborted();\n\t\t\t// A call that cannot be prepared, or whose tool cannot judge it, does not run; the\n\t\t\t// model reads why, such as a refused path, and can correct itself.\n\t\t\treturn {\n\t\t\t\tresult: { ...result, output: describeFailure(error), isError: true },\n\t\t\t\tdenied: false,\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t};\n\t\t}\n\n\t\t// Preparing may have finished after a cancellation it did not notice; nobody is asked to\n\t\t// approve a call in a run that has already stopped.\n\t\tsignal.throwIfAborted();\n\t\tconst denial = await this.denial(call, prepared, signal, approve);\n\t\tif (denial !== undefined) {\n\t\t\treturn {\n\t\t\t\tresult: { ...result, output: denial, isError: true },\n\t\t\t\tdenied: true,\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t};\n\t\t}\n\n\t\t// Deciding took at least one await, and the run may have been cancelled meanwhile.\n\t\tsignal.throwIfAborted();\n\t\t// Announced only once it will run: a missing, failing-to-judge or denied call never is.\n\t\temit(\n\t\t\t{\n\t\t\t\ttype: 'tool',\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tstatus: 'in_progress',\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t},\n\t\t\tcallback,\n\t\t);\n\t\t// Checked again at the last moment: the consumer may cancel on the announcement itself.\n\t\tsignal.throwIfAborted();\n\t\t// Set before `execute`, so a tool that fails halfway still counts: it may have had effects.\n\t\teffects.toolRan = true;\n\t\ttry {\n\t\t\treturn {\n\t\t\t\tresult: { ...result, output: await prepared.run(signal), isError: false },\n\t\t\t\tdenied: false,\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t\t...(prepared.diff === undefined ? {} : { diff: prepared.diff }),\n\t\t\t};\n\t\t} catch (error) {\n\t\t\tsignal.throwIfAborted();\n\t\t\treturn {\n\t\t\t\tresult: { ...result, output: describeFailure(error), isError: true },\n\t\t\t\tdenied: false,\n\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t\t...(error instanceof ToolExecutionError && error.exitCode !== undefined\n\t\t\t\t\t? { exitCode: error.exitCode }\n\t\t\t\t\t: {}),\n\t\t\t};\n\t\t}\n\t}\n\n\t/**\n\t * Asks the user through the run's `ask`. Questions the model wrote wrong go back to it, to\n\t * correct; an asker that fails or answers wrongly is host code, and ends the run.\n\t */\n\tprivate async askUser(\n\t\tcall: ToolCallPart,\n\t\task: Asker,\n\t\tsignal: AbortSignal,\n\t\tcallback: Callback,\n\t): Promise<{ result: ToolResultPart; denied: boolean; summary?: string }> {\n\t\tconst result = { type: 'toolResult' as const, callId: call.id, name: call.name };\n\t\tconst questions = readQuestions(call.input);\n\t\tif (typeof questions === 'string') {\n\t\t\treturn { result: { ...result, output: questions, isError: true }, denied: false };\n\t\t}\n\t\tconst summary = summarizeQuestions(questions);\n\t\tthis.callSummaries.set(call.id, summary);\n\t\temit({ type: 'tool', id: call.id, name: call.name, status: 'in_progress', summary }, callback);\n\t\tsignal.throwIfAborted();\n\n\t\tlet answers: unknown;\n\t\ttry {\n\t\t\tanswers = await ask(questions, signal);\n\t\t} catch (error) {\n\t\t\tsignal.throwIfAborted();\n\t\t\tthrow classifyHostFailure(error, 'The asker failed');\n\t\t}\n\t\t// An answer that arrives after a cancellation is not given to the model.\n\t\tsignal.throwIfAborted();\n\t\tconst read = readAnswers(answers, questions);\n\t\tif (!read) {\n\t\t\tthrow new UnrecoverableError('The asker failed', {\n\t\t\t\tcause: `It must answer each of the ${String(questions.length)} questions with some text, in order.`,\n\t\t\t});\n\t\t}\n\t\treturn {\n\t\t\tresult: { ...result, output: describeAnswers(questions, read), isError: false },\n\t\t\tdenied: false,\n\t\t\tsummary,\n\t\t};\n\t}\n\n\t/** One at a time and in order, so their effects and their narration never interleave. */\n\tprivate async runTools(\n\t\tcalls: ToolCallPart[],\n\t\toptions: RunOptions,\n\t\teffects: RunEffects,\n\t\ttoolCall: ToolCallContext,\n\t): Promise<Message> {\n\t\tconst { signal, onProgress: callback = ignoreProgress } = options;\n\t\tconst results: MessagePart[] = [];\n\t\tfor (const call of calls) {\n\t\t\t// A call before this one may have ignored the cancellation; this one must not start,\n\t\t\t// nor be announced as running.\n\t\t\tsignal.throwIfAborted();\n\t\t\t// `runTool` announces the call only once it is allowed to run, so a consumer never\n\t\t\t// shows a call as running early, nor while the user is still being asked.\n\t\t\tconst { result, denied, diff, summary, exitCode } = await this.runTool(\n\t\t\t\tcall,\n\t\t\t\toptions,\n\t\t\t\teffects,\n\t\t\t\ttoolCall,\n\t\t\t);\n\t\t\tif (denied) {\n\t\t\t\temit(\n\t\t\t\t\t{\n\t\t\t\t\t\ttype: 'tool',\n\t\t\t\t\t\tid: call.id,\n\t\t\t\t\t\tname: call.name,\n\t\t\t\t\t\tstatus: 'denied',\n\t\t\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t\t\t},\n\t\t\t\t\tcallback,\n\t\t\t\t);\n\t\t\t}\n\t\t\t// The diff of a change it made, for the person watching; only once it was made.\n\t\t\telse if (diff !== undefined) {\n\t\t\t\temit(\n\t\t\t\t\t{\n\t\t\t\t\t\ttype: 'tool',\n\t\t\t\t\t\tid: call.id,\n\t\t\t\t\t\tname: call.name,\n\t\t\t\t\t\tstatus: 'completed',\n\t\t\t\t\t\tdiff,\n\t\t\t\t\t\t...(summary === undefined ? {} : { summary }),\n\t\t\t\t\t},\n\t\t\t\t\tcallback,\n\t\t\t\t);\n\t\t\t} else narrate(result, callback, summary, exitCode);\n\t\t\tresults.push(result);\n\t\t}\n\n\t\treturn { role: 'tool', content: results };\n\t}\n\n\t/**\n\t * Runs inside the context of the run that reached it, or in one of its own that it ends with\n\t * the run: completed, failed or cancelled. Only a run that owns its context names the history\n\t * run it recorded, since the run is over only when that context ends.\n\t */\n\tasync run(prompt: string, options: RunOptions): Promise<AgentResponse> {\n\t\tconst inherited = runContextOf(options);\n\t\tif (inherited) return this.runSteps(prompt, options, inherited);\n\n\t\tconst context = new RunContext();\n\t\tlet end: RunEnd = 'failed';\n\t\tlet response: AgentResponse;\n\t\ttry {\n\t\t\tresponse = await this.runSteps(prompt, withRunContext(options, context), context);\n\t\t\tend = 'completed';\n\t\t} catch (error) {\n\t\t\tif (isAbortError(error)) end = 'cancelled';\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tawait this.finishContext(context, end);\n\t\t}\n\t\t// Read once the run ended: a run that changed nothing left the history then.\n\t\tconst { runId } = context.historyRun;\n\t\treturn runId ? { ...response, runId } : response;\n\t}\n\n\t/**\n\t * What the run started ends here, but its result stands: the changes it recorded are already\n\t * on disk, so a record that could not be closed is reported, not turned into a failure.\n\t */\n\tprivate async finishContext(context: RunContext, end: RunEnd): Promise<void> {\n\t\ttry {\n\t\t\tawait context.finish(end);\n\t\t} catch (error) {\n\t\t\ttreatErrors(\n\t\t\t\t() => {\n\t\t\t\t\tthis.logger?.warn(`The run could not close its records: ${describeFailure(error)}`);\n\t\t\t\t},\n\t\t\t\tclassifyHostFailure,\n\t\t\t\t'LLM agent logger failed',\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate async runSteps(\n\t\tprompt: string,\n\t\toptions: RunOptions,\n\t\tcontext: RunContext,\n\t): Promise<AgentResponse> {\n\t\tconst { signal, onProgress: callback = ignoreProgress } = options;\n\t\tconst start = Date.now();\n\t\tconst runMessages: Message[] = [{ role: 'user', content: [{ type: 'text', text: prompt }] }];\n\t\tlet tokens: Tokens | undefined;\n\t\t// Once one call went unreported the run's total is unknown, however many report later.\n\t\tlet unreported = false;\n\t\t// Per run, not per instance: what one run executed says nothing about another.\n\t\tconst effects: RunEffects = { toolRan: false };\n\t\t// The turn this one follows: the last recorded, unless the workspace moved since.\n\t\tlet after = this.conversation.currentTurn;\n\t\tlet followed: Followed | undefined;\n\n\t\ttry {\n\t\t\tif (this.history) {\n\t\t\t\tfollowed = await this.followHistory(this.history);\n\t\t\t\tafter = followed.turn;\n\t\t\t\t// The files may no longer hold what the conversation saw of them.\n\t\t\t\tif (followed.revisions.length > 0) this.reads.clear();\n\t\t\t\tif (followed.undone.length > 0) {\n\t\t\t\t\tconst summary = await this.summarizeUndone(followed, signal);\n\t\t\t\t\ttokens = addTokens(tokens, summary.usage);\n\t\t\t\t\tunreported ||= summary.called && !summary.usage;\n\t\t\t\t\tconst note = await undoNote({\n\t\t\t\t\t\tconversation: this.conversation,\n\t\t\t\t\t\thistory: this.history,\n\t\t\t\t\t\tfollowed,\n\t\t\t\t\t\t...(summary.text ? { summary: summary.text } : {}),\n\t\t\t\t\t}).catch((error: unknown) => {\n\t\t\t\t\t\tthrow classifyLocalFailure(error, 'The workspace history could not be read');\n\t\t\t\t\t});\n\t\t\t\t\trunMessages[0]?.content.unshift({ type: 'text', text: note });\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// After following the history, which may have made every earlier read stale.\n\t\t\tconst reads = this.reads.begin();\n\t\t\tconst repeats = new RepeatedCalls();\n\t\t\t// The agent's own `askUser` exists only for a run someone can answer.\n\t\t\tconst tools = options.ask\n\t\t\t\t? [...this.toolDefinitions, askUserDefinition]\n\t\t\t\t: this.toolDefinitions;\n\t\t\tfor (let step = 1; step <= this.maxSteps; step++) {\n\t\t\t\tconst { response, context: sent } = await this.llmCall(runMessages, after, {\n\t\t\t\t\tsignal,\n\t\t\t\t\tstep,\n\t\t\t\t\tcallback,\n\t\t\t\t\ttools,\n\t\t\t\t});\n\t\t\t\ttokens = addTokens(tokens, response.usage);\n\t\t\t\tunreported ||= !response.usage;\n\t\t\t\t// After the tokens are counted, so a throwing callback still reports them, and for an\n\t\t\t\t// unusable answer too: the call was sent, and billed.\n\t\t\t\tthis.narrateStep(step, response.usage, { context: sent, tools }, callback);\n\t\t\t\tif (response.stopReason !== 'completed') {\n\t\t\t\t\t// Its tokens are already counted with the run's, which the failure carries.\n\t\t\t\t\tthrow new UnrecoverableError('The LLM stopped before completing its answer', {\n\t\t\t\t\t\tcause: `The model stopped with \"${response.stopReason}\".`,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\trunMessages.push(response.message);\n\n\t\t\t\t// Tool calls are narrated as they start, in `runTools`, and never if they do not run.\n\t\t\t\tfor (const part of response.message.content) {\n\t\t\t\t\tif (part.type !== 'toolCall') narrate(part, callback);\n\t\t\t\t}\n\n\t\t\t\tconst calls = response.message.content.filter(part => part.type === 'toolCall');\n\t\t\t\tif (calls.length === 0) {\n\t\t\t\t\t// Recorded only now, so a failed run leaves no tool call without its result, and a\n\t\t\t\t\t// note about what was undone is given again to the next run.\n\t\t\t\t\tthis.conversation.addRunAfter(after, runMessages, context.historyRun);\n\t\t\t\t\t// With the turns that read them, and only then: a failed run is not remembered.\n\t\t\t\t\treads.commit();\n\t\t\t\t\tif (followed) this.seenRevision = followed.latestRevision;\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\t// Only the final answer: text from earlier steps was narrated as it came.\n\t\t\t\t\t\tresponse: response.message.content\n\t\t\t\t\t\t\t.filter(part => part.type === 'text')\n\t\t\t\t\t\t\t.map(part => part.text)\n\t\t\t\t\t\t\t.join('\\n'),\n\t\t\t\t\t\ttokens: unreported ? undefined : tokens,\n\t\t\t\t\t\tduration: (Date.now() - start) / 1000,\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\t// Before running them again: the model has already seen what they return.\n\t\t\t\tif (repeats.count(calls) >= maxRepeatedSteps) {\n\t\t\t\t\tthrow new UnrecoverableError('The LLM repeated the same tool calls', {\n\t\t\t\t\t\tcause: `The model asked for the same tool calls ${String(maxRepeatedSteps)} times in a row.`,\n\t\t\t\t\t});\n\t\t\t\t}\n\n\t\t\t\t// On the last step no call is left to send the results to, so the tools do not run.\n\t\t\t\tif (step < this.maxSteps) {\n\t\t\t\t\trunMessages.push(await this.runTools(calls, options, effects, { run: context, reads }));\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tthrow new UnrecoverableError('The LLM did not finish within its step limit', {\n\t\t\t\tcause: `The model was still calling tools after ${String(this.maxSteps)} steps.`,\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tlet failure = error;\n\t\t\tif (effects.toolRan && error instanceof RecoverableError) {\n\t\t\t\t// RetryingAgent would run the whole prompt again, and with it every tool this run\n\t\t\t\t// already executed, so a failure after one ran must not invite a retry.\n\t\t\t\tconst unrecoverable = new UnrecoverableError(error.message, {\n\t\t\t\t\tcause: error.cause,\n\t\t\t\t\ttokens: error.tokens,\n\t\t\t\t\tusageUnreported: error.usageUnreported,\n\t\t\t\t});\n\t\t\t\tunrecoverable.stack = error.stack;\n\t\t\t\tfailure = unrecoverable;\n\t\t\t}\n\n\t\t\t// The run spent the tokens of every step before the one that failed.\n\t\t\tthrow withSpentTokens(failure, tokens, unreported);\n\t\t}\n\t}\n}\n"]}

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { InvalidAgentConfigError, RecoverableError, UnrecoverableError, } from '
 export { isAbortError } from './shared/domain/isAbortError.ts';
 export type { Tokens } from './shared/domain/tokens.ts';
 export { rememberApprovals, type ApprovalDecision, type ApprovalRequest, type Approver, type CommandLine, type RememberableDecision, type ToolRisk, } from './agent/domain/approval.ts';
+export type { Asker, QuestionOption, UserQuestion } from './agent/domain/question.ts';
 export type { JSONSchema, ToolDefinition } from './llm/domain/tool.ts';
 export type { Tool, ToolSummarizer } from './tools/domain/tool.ts';
 export type { TextMatch, Workspace } from './tools/domain/workspace.ts';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,SAAS,EACT,mBAAmB,GAEnB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACN,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,EACtB,SAAS,EACT,mBAAmB,GAInB,MAAM,6CAA6C,CAAC;AAWrD,OAAO,EACN,cAAc,GAKd,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAQN,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACN,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,GAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAE/D,OAAO,EACN,iBAAiB,GAOjB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,4CAA4C,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GAGnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC","sourcesContent":["export type { ILogger } from './shared/domain/logger.ts';\nexport {\n\tcreateAgent,\n\tcreateOrchestrator,\n\tagentModels,\n\tagentReasoningEfforts,\n\tisAgentProvider,\n\tisModelOf,\n\tisReasoningEffortOf,\n\ttype CreateAgentOptions,\n} from './factory/infrastructure/agentFactory.ts';\nexport {\n\tcreateFileTools,\n\tcreateLLMAgent,\n\tcreateLLMOrchestrator,\n\tisLLMModelOf,\n\tisLLMReasoningEffortOf,\n\tllmModels,\n\tllmReasoningEfforts,\n\ttype CreateLLMAgentOptions,\n\ttype CreateLLMOrchestratorOptions,\n\ttype RoleSteps,\n} from './factory/infrastructure/agentLLMFactory.ts';\nexport type { FileTool, WorkspaceOptions } from './tools/infrastructure/fileTools.ts';\nexport type { WorkspaceRoot } from './tools/domain/accessPolicy.ts';\nexport type {\n\tCommandArgument,\n\tCommandDefinition,\n\tCommandParameter,\n\tCommandRole,\n\tCommands,\n} from './tools/domain/commands.ts';\nexport type { SecretRules } from './tools/infrastructure/rootsAccessPolicy.ts';\nexport {\n\tagentProviders,\n\ttype AgentModel,\n\ttype AgentProvider,\n\ttype CreateOrchestratorOptions,\n\ttype ReasoningEffort,\n} from './factory/infrastructure/types.ts';\nexport {\n\ttype Agent,\n\ttype AgentResponse,\n\ttype Callback,\n\ttype ProgressAgent,\n\ttype ProgressEvent,\n\ttype StepContext,\n\ttype RunOptions,\n} from './agent/domain/agent.ts';\nexport {\n\tInvalidAgentConfigError,\n\tRecoverableError,\n\tUnrecoverableError,\n} from './shared/domain/errors.ts';\nexport { isAbortError } from './shared/domain/isAbortError.ts';\nexport type { Tokens } from './shared/domain/tokens.ts';\nexport {\n\trememberApprovals,\n\ttype ApprovalDecision,\n\ttype ApprovalRequest,\n\ttype Approver,\n\ttype CommandLine,\n\ttype RememberableDecision,\n\ttype ToolRisk,\n} from './agent/domain/approval.ts';\nexport type { JSONSchema, ToolDefinition } from './llm/domain/tool.ts';\nexport type { Tool, ToolSummarizer } from './tools/domain/tool.ts';\nexport type { TextMatch, Workspace } from './tools/domain/workspace.ts';\nexport { defineTool } from './tools/infrastructure/defineTool.ts';\nexport { createWorkspace } from './tools/infrastructure/createWorkspace.ts';\nexport { createWorkspaceTools } from './tools/infrastructure/workspaceTools.ts';\nexport { createHistory } from './recovery/infrastructure/createHistory.ts';\nexport type { History, HistoryRun, Move } from './recovery/domain/history.ts';\nexport {\n\thistoryStart,\n\tNothingToMoveError,\n\tWorkspaceBusyError,\n\tWorkspaceMovedError,\n\ttype MoveOptions,\n\ttype RunStatus,\n} from './recovery/domain/recoveryStore.ts';\nexport { HistoryExpiredError, UnknownRunError } from './recovery/domain/runTree.ts';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,SAAS,EACT,mBAAmB,GAEnB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACN,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,EACtB,SAAS,EACT,mBAAmB,GAInB,MAAM,6CAA6C,CAAC;AAWrD,OAAO,EACN,cAAc,GAKd,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAQN,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACN,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,GAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAE/D,OAAO,EACN,iBAAiB,GAOjB,MAAM,4BAA4B,CAAC;AAKpC,OAAO,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,4CAA4C,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GAGnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC","sourcesContent":["export type { ILogger } from './shared/domain/logger.ts';\nexport {\n\tcreateAgent,\n\tcreateOrchestrator,\n\tagentModels,\n\tagentReasoningEfforts,\n\tisAgentProvider,\n\tisModelOf,\n\tisReasoningEffortOf,\n\ttype CreateAgentOptions,\n} from './factory/infrastructure/agentFactory.ts';\nexport {\n\tcreateFileTools,\n\tcreateLLMAgent,\n\tcreateLLMOrchestrator,\n\tisLLMModelOf,\n\tisLLMReasoningEffortOf,\n\tllmModels,\n\tllmReasoningEfforts,\n\ttype CreateLLMAgentOptions,\n\ttype CreateLLMOrchestratorOptions,\n\ttype RoleSteps,\n} from './factory/infrastructure/agentLLMFactory.ts';\nexport type { FileTool, WorkspaceOptions } from './tools/infrastructure/fileTools.ts';\nexport type { WorkspaceRoot } from './tools/domain/accessPolicy.ts';\nexport type {\n\tCommandArgument,\n\tCommandDefinition,\n\tCommandParameter,\n\tCommandRole,\n\tCommands,\n} from './tools/domain/commands.ts';\nexport type { SecretRules } from './tools/infrastructure/rootsAccessPolicy.ts';\nexport {\n\tagentProviders,\n\ttype AgentModel,\n\ttype AgentProvider,\n\ttype CreateOrchestratorOptions,\n\ttype ReasoningEffort,\n} from './factory/infrastructure/types.ts';\nexport {\n\ttype Agent,\n\ttype AgentResponse,\n\ttype Callback,\n\ttype ProgressAgent,\n\ttype ProgressEvent,\n\ttype StepContext,\n\ttype RunOptions,\n} from './agent/domain/agent.ts';\nexport {\n\tInvalidAgentConfigError,\n\tRecoverableError,\n\tUnrecoverableError,\n} from './shared/domain/errors.ts';\nexport { isAbortError } from './shared/domain/isAbortError.ts';\nexport type { Tokens } from './shared/domain/tokens.ts';\nexport {\n\trememberApprovals,\n\ttype ApprovalDecision,\n\ttype ApprovalRequest,\n\ttype Approver,\n\ttype CommandLine,\n\ttype RememberableDecision,\n\ttype ToolRisk,\n} from './agent/domain/approval.ts';\nexport type { Asker, QuestionOption, UserQuestion } from './agent/domain/question.ts';\nexport type { JSONSchema, ToolDefinition } from './llm/domain/tool.ts';\nexport type { Tool, ToolSummarizer } from './tools/domain/tool.ts';\nexport type { TextMatch, Workspace } from './tools/domain/workspace.ts';\nexport { defineTool } from './tools/infrastructure/defineTool.ts';\nexport { createWorkspace } from './tools/infrastructure/createWorkspace.ts';\nexport { createWorkspaceTools } from './tools/infrastructure/workspaceTools.ts';\nexport { createHistory } from './recovery/infrastructure/createHistory.ts';\nexport type { History, HistoryRun, Move } from './recovery/domain/history.ts';\nexport {\n\thistoryStart,\n\tNothingToMoveError,\n\tWorkspaceBusyError,\n\tWorkspaceMovedError,\n\ttype MoveOptions,\n\ttype RunStatus,\n} from './recovery/domain/recoveryStore.ts';\nexport { HistoryExpiredError, UnknownRunError } from './recovery/domain/runTree.ts';\n"]}

package/dist/retry/domain/model/retryingAgent.js

@@ -1,3 +1,4 @@
+import { describeAnswered, rememberAnswers } from '#src/agent/domain/question';
 import { RecoverableError, UnrecoverableError, withSpentTokens } from '#src/shared/domain/errors';
 import { classifyHostFailure, describeFailure, treatErrors, } from '#src/shared/domain/providerFailure';
 import { isAbortError } from '#src/shared/domain/isAbortError';
@@ -23,10 +24,18 @@ export class RetryingAgent {
         let spent;
         // An attempt was answered without usage, so `spent` is only a subtotal.
         let unreported = false;
+        // What the user answered stays answered: a retry neither asks it again nor forgets it.
+        const remembered = options.ask ? rememberAnswers(options.ask) : undefined;
+        const attemptOptions = remembered ? { ...options, ask: remembered.ask } : options;
         for (let attempt = 1;; attempt++) {
             try {
-                const promptToSend = lastPrompt ?? prompt;
-                const response = await this.inner.run(promptToSend, options);
+                const base = lastPrompt ?? prompt;
+                // After an attempt the user answered, the model is told so, or it would ask again
+                // in its own words, which the memory does not recognise.
+                const promptToSend = attempt > 1 && remembered && remembered.answered.length > 0
+                    ? `${base}\n\n${describeAnswered(remembered.answered)}`
+                    : base;
+                const response = await this.inner.run(promptToSend, attemptOptions);
                 return {
                     ...response,
                     // Any call answered without usage makes the whole count unknown, not partial.

package/dist/retry/domain/model/retryingAgent.js.map

@@ -1 +1 @@
-{"version":3,"file":"retryingAgent.js","sourceRoot":"","sources":["../../../../src/retry/domain/model/retryingAgent.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Agent, AgentResponse, RunOptions } from '#src/agent/domain/agent';\nimport { RecoverableError, UnrecoverableError, withSpentTokens } from '#src/shared/domain/errors';\nimport {\n\tclassifyHostFailure,\n\tdescribeFailure,\n\ttreatErrors,\n} from '#src/shared/domain/providerFailure';\nimport { isAbortError } from '#src/shared/domain/isAbortError';\nimport type { ILogger } from '#src/shared/domain/logger';\nimport { addTokens, type Tokens } from '#src/shared/domain/tokens';\n\nexport class RetryingAgent implements Agent {\n\tprivate inner: Agent;\n\tprivate maxAttempts: number;\n\tprivate logger: ILogger;\n\tprivate noteFailures: boolean;\n\n\tconstructor({\n\t\tinner,\n\t\tmaxAttempts = 3,\n\t\tlogger,\n\t\tnoteFailures = true,\n\t}: {\n\t\tinner: Agent;\n\t\tmaxAttempts?: number;\n\t\tlogger: ILogger;\n\t\t/**\n\t\t * Appends the previous failure to the retried prompt, so a provider session that may\n\t\t * remember the failed turn is told what happened. Off for an agent that records nothing\n\t\t * from a failed call, such as `LLMAgent`: there the note would become a permanent user\n\t\t * message resent on every later turn.\n\t\t */\n\t\tnoteFailures?: boolean;\n\t}) {\n\t\tif (!Number.isInteger(maxAttempts) || maxAttempts < 1) {\n\t\t\tthrow new RangeError('maxAttempts must be a positive integer');\n\t\t}\n\n\t\tthis.inner = inner;\n\t\tthis.maxAttempts = maxAttempts;\n\t\tthis.logger = logger;\n\t\tthis.noteFailures = noteFailures;\n\t}\n\n\tasync run(prompt: string, options: RunOptions): Promise<AgentResponse> {\n\t\tconst start = Date.now();\n\t\tlet lastPrompt: string | null = null;\n\t\t// Failed attempts were billed too, so they travel with whichever way the run ends.\n\t\tlet spent: Tokens | undefined;\n\t\t// An attempt was answered without usage, so `spent` is only a subtotal.\n\t\tlet unreported = false;\n\n\t\tfor (let attempt = 1; ; attempt++) {\n\t\t\ttry {\n\t\t\t\tconst promptToSend = lastPrompt ?? prompt;\n\t\t\t\tconst response = await this.inner.run(promptToSend, options);\n\t\t\t\treturn {\n\t\t\t\t\t...response,\n\t\t\t\t\t// Any call answered without usage makes the whole count unknown, not partial.\n\t\t\t\t\ttokens: unreported ? undefined : response.tokens && addTokens(spent, response.tokens),\n\t\t\t\t\t// Every attempt was waited for, not only the last one.\n\t\t\t\t\tduration: (Date.now() - start) / 1000,\n\t\t\t\t};\n\t\t\t} catch (e) {\n\t\t\t\tif (isAbortError(e)) throw e;\n\t\t\t\tif (e instanceof UnrecoverableError) throw withSpentTokens(e, spent, unreported);\n\n\t\t\t\t// Only a failure the agent classified as recoverable earns another call. An\n\t\t\t\t// unclassified one breaks the `Agent` contract, so nothing here knows whether\n\t\t\t\t// replaying it is safe — it may already have written files or run commands.\n\t\t\t\tif (!(e instanceof RecoverableError))\n\t\t\t\t\tthrow new UnrecoverableError('The agent failed without classifying the failure', {\n\t\t\t\t\t\tcause: describeFailure(e),\n\t\t\t\t\t\ttokens: spent,\n\t\t\t\t\t\tusageUnreported: unreported,\n\t\t\t\t\t});\n\n\t\t\t\tspent = addTokens(spent, e.tokens);\n\t\t\t\tunreported ||= e.usageUnreported;\n\n\t\t\t\tif (attempt === this.maxAttempts)\n\t\t\t\t\tthrow new UnrecoverableError('Max attempts exhausted', {\n\t\t\t\t\t\tcause: `Gave up after ${String(this.maxAttempts)} attempts. Last failure: ${e.cause}`,\n\t\t\t\t\t\ttokens: spent,\n\t\t\t\t\t\tusageUnreported: unreported,\n\t\t\t\t\t});\n\n\t\t\t\t// Keeps the original request: an attempt that failed before the provider registered\n\t\t\t\t// the turn left no session that remembers it.\n\t\t\t\tif (this.noteFailures) {\n\t\t\t\t\tlastPrompt = `${prompt}\\n\\nThe previous attempt failed for the following reason: ${e.cause}`;\n\t\t\t\t}\n\t\t\t\ttry {\n\t\t\t\t\ttreatErrors(\n\t\t\t\t\t\t() => {\n\t\t\t\t\t\t\tthis.logger.warn(\n\t\t\t\t\t\t\t\t`Attempt ${String(attempt)}/${String(this.maxAttempts)} failed; retrying`,\n\t\t\t\t\t\t\t\te,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t},\n\t\t\t\t\t\tclassifyHostFailure,\n\t\t\t\t\t\t'RetryingAgent logger failed while reporting a retry',\n\t\t\t\t\t);\n\t\t\t\t} catch (logFailure) {\n\t\t\t\t\t// The attempts already spent their tokens, whatever the logger did.\n\t\t\t\t\tthrow withSpentTokens(logFailure, spent, unreported);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"retryingAgent.js","sourceRoot":"","sources":["../../../../src/retry/domain/model/retryingAgent.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Agent, AgentResponse, RunOptions } from '#src/agent/domain/agent';\nimport { describeAnswered, rememberAnswers } from '#src/agent/domain/question';\nimport { RecoverableError, UnrecoverableError, withSpentTokens } from '#src/shared/domain/errors';\nimport {\n\tclassifyHostFailure,\n\tdescribeFailure,\n\ttreatErrors,\n} from '#src/shared/domain/providerFailure';\nimport { isAbortError } from '#src/shared/domain/isAbortError';\nimport type { ILogger } from '#src/shared/domain/logger';\nimport { addTokens, type Tokens } from '#src/shared/domain/tokens';\n\nexport class RetryingAgent implements Agent {\n\tprivate inner: Agent;\n\tprivate maxAttempts: number;\n\tprivate logger: ILogger;\n\tprivate noteFailures: boolean;\n\n\tconstructor({\n\t\tinner,\n\t\tmaxAttempts = 3,\n\t\tlogger,\n\t\tnoteFailures = true,\n\t}: {\n\t\tinner: Agent;\n\t\tmaxAttempts?: number;\n\t\tlogger: ILogger;\n\t\t/**\n\t\t * Appends the previous failure to the retried prompt, so a provider session that may\n\t\t * remember the failed turn is told what happened. Off for an agent that records nothing\n\t\t * from a failed call, such as `LLMAgent`: there the note would become a permanent user\n\t\t * message resent on every later turn.\n\t\t */\n\t\tnoteFailures?: boolean;\n\t}) {\n\t\tif (!Number.isInteger(maxAttempts) || maxAttempts < 1) {\n\t\t\tthrow new RangeError('maxAttempts must be a positive integer');\n\t\t}\n\n\t\tthis.inner = inner;\n\t\tthis.maxAttempts = maxAttempts;\n\t\tthis.logger = logger;\n\t\tthis.noteFailures = noteFailures;\n\t}\n\n\tasync run(prompt: string, options: RunOptions): Promise<AgentResponse> {\n\t\tconst start = Date.now();\n\t\tlet lastPrompt: string | null = null;\n\t\t// Failed attempts were billed too, so they travel with whichever way the run ends.\n\t\tlet spent: Tokens | undefined;\n\t\t// An attempt was answered without usage, so `spent` is only a subtotal.\n\t\tlet unreported = false;\n\t\t// What the user answered stays answered: a retry neither asks it again nor forgets it.\n\t\tconst remembered = options.ask ? rememberAnswers(options.ask) : undefined;\n\t\tconst attemptOptions = remembered ? { ...options, ask: remembered.ask } : options;\n\n\t\tfor (let attempt = 1; ; attempt++) {\n\t\t\ttry {\n\t\t\t\tconst base = lastPrompt ?? prompt;\n\t\t\t\t// After an attempt the user answered, the model is told so, or it would ask again\n\t\t\t\t// in its own words, which the memory does not recognise.\n\t\t\t\tconst promptToSend =\n\t\t\t\t\tattempt > 1 && remembered && remembered.answered.length > 0\n\t\t\t\t\t\t? `${base}\\n\\n${describeAnswered(remembered.answered)}`\n\t\t\t\t\t\t: base;\n\t\t\t\tconst response = await this.inner.run(promptToSend, attemptOptions);\n\t\t\t\treturn {\n\t\t\t\t\t...response,\n\t\t\t\t\t// Any call answered without usage makes the whole count unknown, not partial.\n\t\t\t\t\ttokens: unreported ? undefined : response.tokens && addTokens(spent, response.tokens),\n\t\t\t\t\t// Every attempt was waited for, not only the last one.\n\t\t\t\t\tduration: (Date.now() - start) / 1000,\n\t\t\t\t};\n\t\t\t} catch (e) {\n\t\t\t\tif (isAbortError(e)) throw e;\n\t\t\t\tif (e instanceof UnrecoverableError) throw withSpentTokens(e, spent, unreported);\n\n\t\t\t\t// Only a failure the agent classified as recoverable earns another call. An\n\t\t\t\t// unclassified one breaks the `Agent` contract, so nothing here knows whether\n\t\t\t\t// replaying it is safe — it may already have written files or run commands.\n\t\t\t\tif (!(e instanceof RecoverableError))\n\t\t\t\t\tthrow new UnrecoverableError('The agent failed without classifying the failure', {\n\t\t\t\t\t\tcause: describeFailure(e),\n\t\t\t\t\t\ttokens: spent,\n\t\t\t\t\t\tusageUnreported: unreported,\n\t\t\t\t\t});\n\n\t\t\t\tspent = addTokens(spent, e.tokens);\n\t\t\t\tunreported ||= e.usageUnreported;\n\n\t\t\t\tif (attempt === this.maxAttempts)\n\t\t\t\t\tthrow new UnrecoverableError('Max attempts exhausted', {\n\t\t\t\t\t\tcause: `Gave up after ${String(this.maxAttempts)} attempts. Last failure: ${e.cause}`,\n\t\t\t\t\t\ttokens: spent,\n\t\t\t\t\t\tusageUnreported: unreported,\n\t\t\t\t\t});\n\n\t\t\t\t// Keeps the original request: an attempt that failed before the provider registered\n\t\t\t\t// the turn left no session that remembers it.\n\t\t\t\tif (this.noteFailures) {\n\t\t\t\t\tlastPrompt = `${prompt}\\n\\nThe previous attempt failed for the following reason: ${e.cause}`;\n\t\t\t\t}\n\t\t\t\ttry {\n\t\t\t\t\ttreatErrors(\n\t\t\t\t\t\t() => {\n\t\t\t\t\t\t\tthis.logger.warn(\n\t\t\t\t\t\t\t\t`Attempt ${String(attempt)}/${String(this.maxAttempts)} failed; retrying`,\n\t\t\t\t\t\t\t\te,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t},\n\t\t\t\t\t\tclassifyHostFailure,\n\t\t\t\t\t\t'RetryingAgent logger failed while reporting a retry',\n\t\t\t\t\t);\n\t\t\t\t} catch (logFailure) {\n\t\t\t\t\t// The attempts already spent their tokens, whatever the logger did.\n\t\t\t\t\tthrow withSpentTokens(logFailure, spent, unreported);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mikode13/harness",
-	"version": "5.3.0",
+	"version": "5.4.0",
 	"description": "Test/agent harness utility",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",