@mikode13/harness 4.0.0 → 5.0.0

package/dist/factory/infrastructure/agentFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentFactory.js","sourceRoot":"","sources":["../../../src/factory/infrastructure/agentFactory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,sDAAsD,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,oDAAoD,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAClF,OAAO,EACN,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,GACpB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mEAAmE,CAAC;AAC9G,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAErD,OAAO,EAAE,MAAM,EAAE,MAAM,mCAAmC,CAAC;AAC3D,OAAO,EACN,cAAc,GAKd,MAAM,YAAY,CAAC;AAEpB,MAAM,UAAU,eAAe,CAAC,KAAa;IAC5C,OAAO,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC;AAaD,MAAM,aAAa,GAAG;IACrB,SAAS,EAAE,MAAM;IACjB,MAAM,EAAE,aAAa;CACgC,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAC1B,QAAuB,EACvB,EAAE,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,MAAM,EAAE,KAAyB,EAAE;IAEvF,IAAI,MAAa,CAAC;IAElB,QAAQ,QAAQ,EAAE,CAAC;QAClB,KAAK,WAAW;YACf,MAAM,GAAG,IAAI,WAAW,CAAC;gBACxB,KAAK,EAAE,KAAK,IAAI,aAAa,CAAC,SAAS;gBACvC,eAAe;gBACf,WAAW;gBACX,MAAM;aACN,CAAC,CAAC;YACH,MAAM;QACP,KAAK,QAAQ;YACZ,MAAM,GAAG,IAAI,UAAU,CAAC;gBACvB,KAAK,EAAE,KAAK,IAAI,aAAa,CAAC,MAAM;gBACpC,eAAe;gBACf,WAAW;gBACX,MAAM;aACN,CAAC,CAAC;YACH,MAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,+DAA+D;YAC/D,MAAM,eAAe,GAAU,QAAQ,CAAC;YACxC,MAAM,IAAI,uBAAuB,CAChC,IAAI,MAAM,CAAC,eAAe,CAAC,gDAAgD,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtG,CAAC;QACH,CAAC;IACF,CAAC;IAED,OAAO,IAAI,aAAa,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AACrD,CAAC;AAQD,8FAA8F;AAC9F,4FAA4F;AAC5F,MAAM,iBAAiB,GAAG;IACzB,OAAO,EAAE;QACR,OAAO,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,EAAE;QAC9E,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,OAAO,EAAE;QACjF,QAAQ,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE;KAC3E;IACD,SAAS,EAAE;QACV,OAAO,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE;QAC1E,QAAQ,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE;QAC9E,QAAQ,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE;KAC3E;IACD,MAAM,EAAE;QACP,OAAO,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,EAAE;QAC9E,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,OAAO,EAAE;QACjF,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,EAAE;KAC/E;CAID,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CACnC,QAAmC;IAEnC,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,uBAAuB,CAChC,IAAI,MAAM,CAAC,QAAQ,CAAC,gDAAgD,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC/F,CAAC;IACH,CAAC;IAED,OAAO,iBAAiB,CAAC,QAAQ,IAAI,SAAS,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAClC,QAAQ,EACR,WAAW,EACX,aAAa,GAAG,EAAE,EAClB,MAAM,GAAG,IAAI,MAAM,EAAE,MACS,EAAE;IAChC,MAAM,KAAK,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,EAAQ,EAAE,YAAoB,EAAE,EAAE,CACrF,IAAI,eAAe,CAAC;QACnB,KAAK,EAAE,WAAW,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;QAC7E,YAAY;KACZ,CAAC,CAAC;IAEJ,OAAO,IAAI,iBAAiB,CAAC;QAC5B,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,IAAI,mBAAmB,CAAC;QACnF,aAAa,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,IAAI,oBAAoB,CAAC;QACvF,aAAa,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,IAAI,oBAAoB,CAAC;QACvF,yBAAyB,EAAE,IAAI,yBAAyB,EAAE;QAC1D,MAAM;KACN,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import type { Agent } from '#src/agent/domain/agent';\nimport { InvalidAgentConfigError } from '#src/shared/domain/errors';\nimport { ClaudeAgent } from '#src/engines/claude/infrastructure/model/claudeAgent';\nimport { CodexAgent } from '#src/engines/codex/infrastructure/model/codexAgent';\nimport { InstructedAgent } from '#src/orchestration/domain/model/instructedAgent';\nimport {\n\texecutorInstructions,\n\tOrchestratorAgent,\n\tplannerInstructions,\n\treviewerInstructions,\n} from '#src/orchestration/domain/model/orchestratorAgent';\nimport { ReviewerDecisionValidator } from '#src/orchestration/infrastructure/model/reviewerDecisionValidator';\nimport { RetryingAgent } from '#src/retry/domain/model/retryingAgent';\nimport { isOneOf } from '#src/shared/domain/isOneOf';\nimport type { ILogger } from '#src/shared/domain/logger';\nimport { Logger } from '#src/shared/infrastructure/logger';\nimport {\n\tagentProviders,\n\ttype AgentModel,\n\ttype AgentProvider,\n\ttype CreateOrchestratorOptions,\n\ttype ReasoningEffort,\n} from './types.ts';\n\nexport function isAgentProvider(value: string): value is AgentProvider {\n\treturn isOneOf(agentProviders, value);\n}\n\nexport interface CreateAgentOptions {\n\t/** Defaults to `'opus'` on Anthropic and `'gpt-5.6-sol'` on OpenAI. */\n\tmodel?: AgentModel;\n\t/** Defaults to `'high'`. */\n\treasoningEffort?: ReasoningEffort;\n\t/** Maps to the provider's permission-bypass mode. Defaults to `false`. */\n\tautoApprove?: boolean;\n\t/** Defaults to warnings on stderr. */\n\tlogger?: ILogger;\n}\n\nconst defaultModels = {\n\tanthropic: 'opus',\n\topenai: 'gpt-5.6-sol',\n} as const satisfies Record<AgentProvider, AgentModel>;\n\n/**\n * Builds the agent for a provider on its Agent SDK — Claude Code for Anthropic, Codex for\n * OpenAI — already wrapped in the harness's retry policy.\n *\n * @throws {InvalidAgentConfigError} for an unknown provider, or a model or reasoning effort\n * the provider does not support.\n * @throws {UnrecoverableError} when Codex cannot be set up, for example because its CLI binary\n * is missing.\n */\nexport function createAgent(\n\tprovider: AgentProvider,\n\t{ model, reasoningEffort, autoApprove, logger = new Logger() }: CreateAgentOptions = {},\n): Agent {\n\tlet engine: Agent;\n\n\tswitch (provider) {\n\t\tcase 'anthropic':\n\t\t\tengine = new ClaudeAgent({\n\t\t\t\tmodel: model ?? defaultModels.anthropic,\n\t\t\t\treasoningEffort,\n\t\t\t\tautoApprove,\n\t\t\t\tlogger,\n\t\t\t});\n\t\t\tbreak;\n\t\tcase 'openai':\n\t\t\tengine = new CodexAgent({\n\t\t\t\tmodel: model ?? defaultModels.openai,\n\t\t\t\treasoningEffort,\n\t\t\t\tautoApprove,\n\t\t\t\tlogger,\n\t\t\t});\n\t\t\tbreak;\n\t\tdefault: {\n\t\t\t// Reachable from untyped input that skipped `isAgentProvider`.\n\t\t\tconst unknownProvider: never = provider;\n\t\t\tthrow new InvalidAgentConfigError(\n\t\t\t\t`\"${String(unknownProvider)}\" is not an agent provider; expected one of: ${agentProviders.join(', ')}`,\n\t\t\t);\n\t\t}\n\t}\n\n\treturn new RetryingAgent({ inner: engine, logger });\n}\n\nexport interface Role {\n\tprovider: AgentProvider;\n\tmodel: AgentModel;\n\treasoningEffort: ReasoningEffort;\n}\n\n// A stronger model plans and reviews; a cheaper one executes the plan. Every model and effort\n// here is one both the Agent SDKs and the model APIs accept, so either path can run a role.\nconst orchestratorRoles = {\n\tdefault: {\n\t\tplanner: { provider: 'openai', model: 'gpt-5.6-sol', reasoningEffort: 'high' },\n\t\texecutor: { provider: 'openai', model: 'gpt-5.6-luna', reasoningEffort: 'xhigh' },\n\t\treviewer: { provider: 'anthropic', model: 'opus', reasoningEffort: 'high' },\n\t},\n\tanthropic: {\n\t\tplanner: { provider: 'anthropic', model: 'opus', reasoningEffort: 'high' },\n\t\texecutor: { provider: 'anthropic', model: 'sonnet', reasoningEffort: 'xhigh' },\n\t\treviewer: { provider: 'anthropic', model: 'opus', reasoningEffort: 'high' },\n\t},\n\topenai: {\n\t\tplanner: { provider: 'openai', model: 'gpt-5.6-sol', reasoningEffort: 'high' },\n\t\texecutor: { provider: 'openai', model: 'gpt-5.6-luna', reasoningEffort: 'xhigh' },\n\t\treviewer: { provider: 'openai', model: 'gpt-5.6-sol', reasoningEffort: 'high' },\n\t},\n} as const satisfies Record<\n\tAgentProvider | 'default',\n\tRecord<'planner' | 'executor' | 'reviewer', Role>\n>;\n\n/**\n * The roles for `provider`, or the default mix without one.\n *\n * @throws {InvalidAgentConfigError} for an unknown provider.\n */\nexport function orchestratorRolesFor(\n\tprovider: AgentProvider | undefined,\n): Record<'planner' | 'executor' | 'reviewer', Role> {\n\tif (provider !== undefined && !isAgentProvider(provider)) {\n\t\tthrow new InvalidAgentConfigError(\n\t\t\t`\"${String(provider)}\" is not an agent provider; expected one of: ${agentProviders.join(', ')}`,\n\t\t);\n\t}\n\n\treturn orchestratorRoles[provider ?? 'default'];\n}\n\n/**\n * Builds the planner → executor → reviewer workflow, each role an agent from `createAgent`.\n *\n * @throws {InvalidAgentConfigError} for an unknown provider.\n * @throws {UnrecoverableError} when an OpenAI role cannot be set up, for example because the\n * Codex CLI binary is missing.\n */\nexport function createOrchestrator({\n\tprovider,\n\tautoApprove,\n\tsystemPrompts = {},\n\tlogger = new Logger(),\n}: CreateOrchestratorOptions = {}): Agent {\n\tconst roles = orchestratorRolesFor(provider);\n\tconst agentFor = ({ provider, model, reasoningEffort }: Role, instructions: string) =>\n\t\tnew InstructedAgent({\n\t\t\tinner: createAgent(provider, { model, reasoningEffort, autoApprove, logger }),\n\t\t\tinstructions,\n\t\t});\n\n\treturn new OrchestratorAgent({\n\t\tplannerAgent: agentFor(roles.planner, systemPrompts.planner ?? plannerInstructions),\n\t\texecutorAgent: agentFor(roles.executor, systemPrompts.executor ?? executorInstructions),\n\t\treviewerAgent: agentFor(roles.reviewer, systemPrompts.reviewer ?? reviewerInstructions),\n\t\treviewerDecisionValidator: new ReviewerDecisionValidator(),\n\t\tlogger,\n\t});\n}\n"]}
+{"version":3,"file":"agentFactory.js","sourceRoot":"","sources":["../../../src/factory/infrastructure/agentFactory.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Agent } from '#src/agent/domain/agent';\nimport { InvalidAgentConfigError } from '#src/shared/domain/errors';\nimport {\n\tClaudeAgent,\n\tclaudeModels,\n\tclaudeReasoningEfforts,\n} from '#src/engines/claude/infrastructure/model/claudeAgent';\nimport {\n\tCodexAgent,\n\tcodexModels,\n\tcodexReasoningEfforts,\n} from '#src/engines/codex/infrastructure/model/codexAgent';\nimport { InstructedAgent } from '#src/orchestration/domain/model/instructedAgent';\nimport {\n\texecutorInstructions,\n\tOrchestratorAgent,\n\tplannerInstructions,\n\treviewerInstructions,\n} from '#src/orchestration/domain/model/orchestratorAgent';\nimport { ReviewerDecisionValidator } from '#src/orchestration/infrastructure/model/reviewerDecisionValidator';\nimport { RetryingAgent } from '#src/retry/domain/model/retryingAgent';\nimport { isOneOf } from '#src/shared/domain/isOneOf';\nimport type { ILogger } from '#src/shared/domain/logger';\nimport { Logger } from '#src/shared/infrastructure/logger';\nimport {\n\tagentProviders,\n\ttype AgentModel,\n\ttype AgentProvider,\n\ttype CreateOrchestratorOptions,\n\ttype ReasoningEffort,\n} from './types.ts';\n\nexport function isAgentProvider(value: string): value is AgentProvider {\n\treturn isOneOf(agentProviders, value);\n}\n\n/** The models each provider's Agent SDK accepts. */\nexport const agentModels = {\n\tanthropic: claudeModels,\n\topenai: codexModels,\n} as const satisfies Readonly<Record<AgentProvider, readonly AgentModel[]>>;\n\n/** The reasoning efforts each provider's Agent SDK accepts. */\nexport const agentReasoningEfforts = {\n\tanthropic: claudeReasoningEfforts,\n\topenai: codexReasoningEfforts,\n} as const satisfies Readonly<Record<AgentProvider, readonly ReasoningEffort[]>>;\n\n/** Narrows a model to one accepted by the selected provider's Agent SDK. */\nexport function isModelOf<Provider extends AgentProvider>(\n\tprovider: Provider,\n\tvalue: string,\n): value is (typeof agentModels)[Provider][number] {\n\treturn isOneOf(agentModels[provider], value);\n}\n\n/** Narrows a reasoning effort to one accepted by the selected provider's Agent SDK. */\nexport function isReasoningEffortOf<Provider extends AgentProvider>(\n\tprovider: Provider,\n\tvalue: string,\n): value is (typeof agentReasoningEfforts)[Provider][number] {\n\treturn isOneOf(agentReasoningEfforts[provider], value);\n}\n\nexport interface CreateAgentOptions {\n\t/** Defaults to `'opus'` on Anthropic and `'gpt-5.6-sol'` on OpenAI. */\n\tmodel?: AgentModel;\n\t/** Defaults to `'high'`. */\n\treasoningEffort?: ReasoningEffort;\n\t/** Maps to the provider's permission-bypass mode. Defaults to `false`. */\n\tautoApprove?: boolean;\n\t/** Defaults to warnings on stderr. */\n\tlogger?: ILogger;\n}\n\nconst defaultModels = {\n\tanthropic: 'opus',\n\topenai: 'gpt-5.6-sol',\n} as const satisfies Record<AgentProvider, AgentModel>;\n\n/**\n * Builds the agent for a provider on its Agent SDK — Claude Code for Anthropic, Codex for\n * OpenAI — already wrapped in the harness's retry policy.\n *\n * @throws {InvalidAgentConfigError} for an unknown provider, or a model or reasoning effort\n * the provider does not support.\n * @throws {UnrecoverableError} when Codex cannot be set up, for example because its CLI binary\n * is missing.\n */\nexport function createAgent(\n\tprovider: AgentProvider,\n\t{ model, reasoningEffort, autoApprove, logger = new Logger() }: CreateAgentOptions = {},\n): Agent {\n\tlet engine: Agent;\n\n\tswitch (provider) {\n\t\tcase 'anthropic':\n\t\t\tengine = new ClaudeAgent({\n\t\t\t\tmodel: model ?? defaultModels.anthropic,\n\t\t\t\treasoningEffort,\n\t\t\t\tautoApprove,\n\t\t\t\tlogger,\n\t\t\t});\n\t\t\tbreak;\n\t\tcase 'openai':\n\t\t\tengine = new CodexAgent({\n\t\t\t\tmodel: model ?? defaultModels.openai,\n\t\t\t\treasoningEffort,\n\t\t\t\tautoApprove,\n\t\t\t\tlogger,\n\t\t\t});\n\t\t\tbreak;\n\t\tdefault: {\n\t\t\t// Reachable from untyped input that skipped `isAgentProvider`.\n\t\t\tconst unknownProvider: never = provider;\n\t\t\tthrow new InvalidAgentConfigError(\n\t\t\t\t`\"${String(unknownProvider)}\" is not an agent provider; expected one of: ${agentProviders.join(', ')}`,\n\t\t\t);\n\t\t}\n\t}\n\n\treturn new RetryingAgent({ inner: engine, logger });\n}\n\nexport interface Role {\n\tprovider: AgentProvider;\n\tmodel: AgentModel;\n\treasoningEffort: ReasoningEffort;\n}\n\n// A stronger model plans and reviews; a cheaper one executes the plan. Every model and effort\n// here is one both the Agent SDKs and the model APIs accept, so either path can run a role.\nconst orchestratorRoles = {\n\tdefault: {\n\t\tplanner: { provider: 'openai', model: 'gpt-5.6-sol', reasoningEffort: 'high' },\n\t\texecutor: { provider: 'openai', model: 'gpt-5.6-luna', reasoningEffort: 'xhigh' },\n\t\treviewer: { provider: 'anthropic', model: 'opus', reasoningEffort: 'high' },\n\t},\n\tanthropic: {\n\t\tplanner: { provider: 'anthropic', model: 'opus', reasoningEffort: 'high' },\n\t\texecutor: { provider: 'anthropic', model: 'sonnet', reasoningEffort: 'xhigh' },\n\t\treviewer: { provider: 'anthropic', model: 'opus', reasoningEffort: 'high' },\n\t},\n\topenai: {\n\t\tplanner: { provider: 'openai', model: 'gpt-5.6-sol', reasoningEffort: 'high' },\n\t\texecutor: { provider: 'openai', model: 'gpt-5.6-luna', reasoningEffort: 'xhigh' },\n\t\treviewer: { provider: 'openai', model: 'gpt-5.6-sol', reasoningEffort: 'high' },\n\t},\n} as const satisfies Record<\n\tAgentProvider | 'default',\n\tRecord<'planner' | 'executor' | 'reviewer', Role>\n>;\n\n/**\n * The roles for `provider`, or the default mix without one.\n *\n * @throws {InvalidAgentConfigError} for an unknown provider.\n */\nexport function orchestratorRolesFor(\n\tprovider: AgentProvider | undefined,\n): Record<'planner' | 'executor' | 'reviewer', Role> {\n\tif (provider !== undefined && !isAgentProvider(provider)) {\n\t\tthrow new InvalidAgentConfigError(\n\t\t\t`\"${String(provider)}\" is not an agent provider; expected one of: ${agentProviders.join(', ')}`,\n\t\t);\n\t}\n\n\treturn orchestratorRoles[provider ?? 'default'];\n}\n\n/**\n * Builds the planner → executor → reviewer workflow, each role an agent from `createAgent`.\n *\n * @throws {InvalidAgentConfigError} for an unknown provider.\n * @throws {UnrecoverableError} when an OpenAI role cannot be set up, for example because the\n * Codex CLI binary is missing.\n */\nexport function createOrchestrator({\n\tprovider,\n\tautoApprove,\n\tsystemPrompts = {},\n\tlogger = new Logger(),\n}: CreateOrchestratorOptions = {}): Agent {\n\tconst roles = orchestratorRolesFor(provider);\n\tconst agentFor = ({ provider, model, reasoningEffort }: Role, instructions: string) =>\n\t\tnew InstructedAgent({\n\t\t\tinner: createAgent(provider, { model, reasoningEffort, autoApprove, logger }),\n\t\t\tinstructions,\n\t\t});\n\n\treturn new OrchestratorAgent({\n\t\tplannerAgent: agentFor(roles.planner, systemPrompts.planner ?? plannerInstructions),\n\t\texecutorAgent: agentFor(roles.executor, systemPrompts.executor ?? executorInstructions),\n\t\treviewerAgent: agentFor(roles.reviewer, systemPrompts.reviewer ?? reviewerInstructions),\n\t\treviewerDecisionValidator: new ReviewerDecisionValidator(),\n\t\tlogger,\n\t});\n}\n"]}

package/dist/factory/infrastructure/agentLLMFactory.d.ts

@@ -1,7 +1,23 @@
 import type { Agent } from '#src/agent/domain/agent';
 import type { ILogger } from '#src/shared/domain/logger';
+import { type CommandRole, type Commands } from '#src/tools/domain/commands';
 import type { Tool } from '#src/tools/domain/tool';
+import { type FileTool, type WorkspaceOptions } from '#src/tools/infrastructure/fileTools';
 import { type AgentModel, type AgentProvider, type CreateOrchestratorOptions, type ReasoningEffort } from './types.ts';
+/** The models each provider's model API accepts. */
+export declare const llmModels: {
+    readonly anthropic: readonly ["opus", "fable", "sonnet", "haiku"];
+    readonly openai: readonly ["gpt-6-astra", "gpt-5.6-sol", "gpt-5.6-luna", "gpt-5.6-terra"];
+};
+/** The reasoning efforts each provider's model API accepts. */
+export declare const llmReasoningEfforts: {
+    readonly anthropic: readonly ["low", "medium", "high", "xhigh", "max"];
+    readonly openai: readonly ["low", "medium", "high", "xhigh", "max"];
+};
+/** Narrows a model to one accepted by the selected provider's model API. */
+export declare function isLLMModelOf<Provider extends AgentProvider>(provider: Provider, value: string): value is (typeof llmModels)[Provider][number];
+/** Narrows a reasoning effort to one accepted by the selected provider's model API. */
+export declare function isLLMReasoningEffortOf<Provider extends AgentProvider>(provider: Provider, value: string): value is (typeof llmReasoningEfforts)[Provider][number];
 export interface CreateLLMAgentOptions {
     /**
      * Defaults to `'sonnet'` on Anthropic and `'gpt-5.6-luna'` on OpenAI. The provider's client
@@ -12,8 +28,26 @@ export interface CreateLLMAgentOptions {
     reasoningEffort?: ReasoningEffort;
     /** Sent as the model's instructions on every call. */
     systemPrompt: string;
-    /** The tools the model may call. Defaults to none. */
-    tools?: Tool[];
+    /** The tools the model may call: the consumer's own, and those of `createFileTools`. Defaults to none. */
+    tools?: (Tool | FileTool)[];
+    /**
+     * The folders the agent works on, the same as given to `createFileTools`. With it, the agent
+     * follows the workspace's history: after the user undoes runs, its next run starts from the
+     * conversation as it was, and is told what was undone. The system prompt is followed by the
+     * roots and how to name a file in them.
+     */
+    workspace?: WorkspaceOptions;
+    /**
+     * With `workspace`, a summary of what was undone, from the provider's cheap model, in place
+     * of the undone prompts. That is Claude Haiku without thinking, or `gpt-5.6-luna` at high
+     * effort, and the call is billed with the run's tokens. Defaults to `true`.
+     */
+    summarizeUndone?: boolean;
+    /**
+     * How many calls to the model one run may make before it fails. Defaults to 65, with no upper
+     * bound. A run that asks for exactly the same tool calls 5 times in a row fails before that.
+     */
+    maxSteps?: number;
     /**
      * Runs every tool call without asking, `destructive` ones included, for CI where no one can
      * answer. Without it, a `destructive` call goes to the run's `approve`, or is denied.
@@ -22,6 +56,35 @@ export interface CreateLLMAgentOptions {
     /** Defaults to warnings on stderr. */
     logger?: ILogger;
 }
+/** A limit per role of `createLLMOrchestrator`; a role left out keeps its default. */
+export type RoleSteps = Partial<Record<OrchestratorRole, number>>;
+type OrchestratorRole = CommandRole;
+export interface CreateLLMOrchestratorOptions extends CreateOrchestratorOptions {
+    /**
+     * The folders the agents work on. The executor changes files only in a `write` root, every
+     * change recorded in the workspace's history. Defaults to the current working directory,
+     * read only.
+     */
+    workspace?: WorkspaceOptions;
+    /**
+     * How many calls to the model one run of each role may make: one number for every role, or a
+     * number per role. Defaults to 80 for the executor and 65 for the planner and the reviewer,
+     * with no upper bound. A run that asks for exactly the same tool calls 5 times in a row fails
+     * before its limit.
+     */
+    maxSteps?: number | RoleSteps;
+    /**
+     * Commands the roles may run, such as the project's tests, through `runCommand`. Each goes to
+     * the roles its `roles` names, the executor by default. See `createFileTools`. Each needs a
+     * `write` root to run in.
+     */
+    commands?: Commands;
+    /**
+     * A summary of what the user undid, from the planner's provider's cheap model, for every
+     * role. See `CreateLLMAgentOptions.summarizeUndone`. Defaults to `true`.
+     */
+    summarizeUndone?: boolean;
+}
 /**
  * Builds an agent whose conversation MiKode owns, on a provider's model API, already wrapped in
  * the harness's retry policy. It needs the provider's API key and bills per token, where
@@ -34,18 +97,60 @@ export interface CreateLLMAgentOptions {
  * `OPENAI_API_KEY` is missing. The Anthropic SDK resolves credentials lazily, so a missing
  * `ANTHROPIC_API_KEY` fails the first run instead, with an `UnrecoverableError`.
  */
-export declare function createLLMAgent(provider: AgentProvider, { model, reasoningEffort, systemPrompt, tools, autoApprove, logger, }: CreateLLMAgentOptions): Agent;
+export declare function createLLMAgent(provider: AgentProvider, { model, reasoningEffort, systemPrompt, tools, workspace, summarizeUndone, maxSteps, autoApprove, logger, }: CreateLLMAgentOptions): Agent;
+/**
+ * The file tools for an agent from `createLLMAgent` on `provider`, over `workspace`, in the
+ * provider's own format:
+ *
+ * - OpenAI: `listFiles`, `searchText`, `readFile` and its native `apply_patch`;
+ * - Anthropic: `listFiles`, `searchText`, its native text editor, whose `view` reads, and
+ *   `delete_file`.
+ *
+ * Every one goes through the workspace's access policy: a path outside the roots, a secret,
+ * a file `.gitignore` excludes or the harness protects is refused. A change is made only in a
+ * `write` root, only from a version the agent read, and is recorded in the workspace's history,
+ * so it can be undone. Without a `write` root the tools only read. Give the agent the same
+ * `workspace`, so it follows what the history undoes.
+ *
+ * With `commands`, they include `runCommand`, which runs one of them by name, with only the
+ * parameters it declares and never through a shell. Each run asks the approver, showing the
+ * program exactly as it will run, and gets a small environment without the provider keys. The
+ * files of the `write` roots are captured before it and compared after, so what it changed is
+ * in the history too. It is trusted execution, not a sandbox: a command can reach whatever
+ * this user can. Not supported on Windows yet.
+ *
+ * @throws {InvalidAgentConfigError} for an unknown provider, a workspace with no root, or an
+ * invalid command, including one whose `cwd` is not in a `write` root, or any on Windows.
+ * @throws {UnrecoverableError} when no program can read the first root.
+ */
+export declare function createFileTools(provider: AgentProvider, workspace: WorkspaceOptions, { logger, commands }?: {
+    logger?: ILogger;
+    commands?: Commands;
+}): Promise<FileTool[]>;
 /**
- * Builds the planner → executor → reviewer workflow with the planner and reviewer on the model
- * APIs, from `createLLMAgent`, each holding its role's instructions, or `systemPrompts`, as its
- * system prompt, with the read-only repository tools for the current working directory. The
- * executor stays on its Agent SDK, from `createAgent`, until an agent of ours can change files;
- * `autoApprove` reaches only it. Asynchronous because finding the program that reads the
- * repository is.
- *
- * @throws {InvalidAgentConfigError} for an unknown provider.
+ * Builds the planner → executor → reviewer workflow with every role on the model APIs, each
+ * holding its role's instructions, or `systemPrompts`, as its system prompt, followed by the
+ * workspace's roots.
+ *
+ * - The planner and the reviewer read: `listFiles`, `searchText`, `readFile`, and
+ *   `showChanges`, the current task's changes as far as each may read them.
+ * - The executor gets its provider's file tools (see `createFileTools`), and changes files only
+ *   in a `write` root; `autoApprove` reaches only it.
+ * - Each role has its own step limit: `maxSteps`, 80 for the executor and 65 for the others by
+ *   default.
+ * - Each role gets `runCommand` with the `commands` whose `roles` name it, the executor by
+ *   default. A command asks the approver in any role, and its files are captured around it.
+ * - The executor is told to finish only once the tests and checks pass, and the reviewer that
+ *   they passed, when the executor has a command; without one, both are told the tests were
+ *   not run, and the reviewer judges from the code whether they would pass.
+ *
+ * One run of the orchestrator is one run of the workspace's history, every round and retry
+ * included, and its `AgentResponse` names it. Every role follows what the user undoes.
+ * Asynchronous because opening the workspace is.
+ *
+ * @throws {InvalidAgentConfigError} for an unknown provider, or a workspace with no root.
  * @throws {UnrecoverableError} when a role cannot be set up, for example because
- * `OPENAI_API_KEY` or the Codex CLI binary is missing, or when no program can read the
- * repository.
+ * `OPENAI_API_KEY` is missing, or when no program can read the repository.
  */
-export declare function createLLMOrchestrator({ provider, autoApprove, systemPrompts, logger, }?: CreateOrchestratorOptions): Promise<Agent>;
+export declare function createLLMOrchestrator({ provider, autoApprove, systemPrompts, workspace, maxSteps, commands, summarizeUndone, logger, }?: CreateLLMOrchestratorOptions): Promise<Agent>;
+export {};

package/dist/factory/infrastructure/agentLLMFactory.js

@@ -1,98 +1,325 @@
-import { InvalidAgentConfigError } from '#src/shared/domain/errors';
+import { resolve } from 'node:path';
 import { LLMAgent } from '#src/engines/domain/model/llmAgent';
-import { ClaudeLLMClient } from '#src/llm/infrastructure/claudeLLMClient';
-import { OpenAILLMClient } from '#src/llm/infrastructure/openAILLMClient';
-import { InstructedAgent } from '#src/orchestration/domain/model/instructedAgent';
-import { executorInstructions, OrchestratorAgent, plannerInstructions, reviewerInstructions, } from '#src/orchestration/domain/model/orchestratorAgent';
+import { ClaudeLLMClient, claudeLLMModels, claudeLLMReasoningEfforts, } from '#src/llm/infrastructure/claudeLLMClient';
+import { OpenAILLMClient, openAIModels, openAIReasoningEfforts, } from '#src/llm/infrastructure/openAILLMClient';
+import { executorInstructions, executorInstructionsWithoutCommands, OrchestratorAgent, plannerInstructions, reviewerInstructions, reviewerInstructionsWithoutCommands, } from '#src/orchestration/domain/model/orchestratorAgent';
 import { ReviewerDecisionValidator } from '#src/orchestration/infrastructure/model/reviewerDecisionValidator';
 import { RetryingAgent } from '#src/retry/domain/model/retryingAgent';
+import { InvalidAgentConfigError } from '#src/shared/domain/errors';
+import { isOneOf } from '#src/shared/domain/isOneOf';
 import { Logger } from '#src/shared/infrastructure/logger';
-import { createWorkspace } from '#src/tools/infrastructure/createWorkspace';
+import { commandsFor, validateCommands, } from '#src/tools/domain/commands';
+import { commandToolFor, fileToolsFor, openStore, openWorkspace, stateDirectoryOf, } from '#src/tools/infrastructure/fileTools';
+import { createShowChangesTool } from '#src/tools/infrastructure/showChangesTool';
+import { createTrackedReadFile } from '#src/tools/infrastructure/trackedReadFile';
 import { createWorkspaceTools } from '#src/tools/infrastructure/workspaceTools';
-import { createAgent, orchestratorRolesFor } from "./agentFactory.js";
+import { isAgentProvider, orchestratorRolesFor } from "./agentFactory.js";
 import { agentProviders, } from "./types.js";
-const defaultLLMAgentModels = {
-    anthropic: 'sonnet',
-    openai: 'gpt-5.6-luna',
+/** The models each provider's model API accepts. */
+export const llmModels = {
+    anthropic: claudeLLMModels,
+    openai: openAIModels,
+};
+/** The reasoning efforts each provider's model API accepts. */
+export const llmReasoningEfforts = {
+    anthropic: claudeLLMReasoningEfforts,
+    openai: openAIReasoningEfforts,
+};
+/** Narrows a model to one accepted by the selected provider's model API. */
+export function isLLMModelOf(provider, value) {
+    return isOneOf(llmModels[provider], value);
+}
+/** Narrows a reasoning effort to one accepted by the selected provider's model API. */
+export function isLLMReasoningEffortOf(provider, value) {
+    return isOneOf(llmReasoningEfforts[provider], value);
+}
+// The executor reads, edits and checks, so it needs more calls than the roles that only read.
+const defaultRoleSteps = {
+    planner: 65,
+    executor: 80,
+    reviewer: 65,
 };
 /**
- * Builds an agent whose conversation MiKode owns, on a provider's model API, already wrapped in
- * the harness's retry policy. It needs the provider's API key and bills per token, where
- * `createAgent` uses the Agent SDK's login. Each tool judges the risk of each call; a
- * `destructive` one runs only when the run's `approve` allows it, or with `autoApprove`.
+ * Each role's step limit, from one number for all of them or a number per role.
  *
- * @throws {InvalidAgentConfigError} for an unknown provider, a model or reasoning effort its
- * client does not support, or two tools that share a name.
- * @throws {UnrecoverableError} when the client cannot be set up, for example because
- * `OPENAI_API_KEY` is missing. The Anthropic SDK resolves credentials lazily, so a missing
- * `ANTHROPIC_API_KEY` fails the first run instead, with an `UnrecoverableError`.
+ * @throws {InvalidAgentConfigError} for a value that is neither, and for a role that does not
+ * exist, which is a typo that would otherwise leave that role on its default without a word.
  */
-export function createLLMAgent(provider, { model, reasoningEffort, systemPrompt, tools, autoApprove, logger = new Logger(), }) {
-    let llmClient;
+function stepsPerRole(maxSteps) {
+    if (maxSteps === undefined)
+        return defaultRoleSteps;
+    if (typeof maxSteps === 'number') {
+        return { planner: maxSteps, executor: maxSteps, reviewer: maxSteps };
+    }
+    // Untyped input, such as the CLI's configuration file, can hold `null` or a list here.
+    if (typeof maxSteps !== 'object' || maxSteps === null || Array.isArray(maxSteps)) {
+        throw new InvalidAgentConfigError('maxSteps must be a number or an object of steps per role, such as { "executor": 120 }');
+    }
+    const unknown = Object.keys(maxSteps).filter(role => !(role in defaultRoleSteps));
+    if (unknown.length > 0) {
+        throw new InvalidAgentConfigError(`maxSteps names roles that do not exist: ${unknown.join(', ')}; expected planner, executor or reviewer`);
+    }
+    // A role given as `undefined`, which untyped input can do, keeps its default.
+    const given = Object.entries(maxSteps).filter(([, steps]) => steps !== undefined);
+    return { ...defaultRoleSteps, ...Object.fromEntries(given) };
+}
+const defaultLLMAgentModels = {
+    anthropic: 'sonnet',
+    openai: 'gpt-5.6-luna',
+};
+function unknownProvider(provider) {
+    return new InvalidAgentConfigError(`"${String(provider)}" is not an agent provider; expected one of: ${agentProviders.join(', ')}`);
+}
+function llmClientFor(provider, { model, reasoningEffort, systemPrompt, logger, }) {
     switch (provider) {
         case 'anthropic':
-            llmClient = new ClaudeLLMClient({
+            return new ClaudeLLMClient({
                 model: model ?? defaultLLMAgentModels.anthropic,
                 reasoningEffort,
                 systemPrompt,
                 logger,
             });
-            break;
         case 'openai':
-            llmClient = new OpenAILLMClient({
+            return new OpenAILLMClient({
                 model: model ?? defaultLLMAgentModels.openai,
                 reasoningEffort,
                 systemPrompt,
                 logger,
             });
-            break;
-        default: {
+        default:
             // Reachable from untyped input.
-            const unknownProvider = provider;
-            throw new InvalidAgentConfigError(`"${String(unknownProvider)}" is not an agent provider; expected one of: ${agentProviders.join(', ')}`);
-        }
+            throw unknownProvider(provider);
+    }
+}
+/** The provider's cheap model, for the summary of what was undone. */
+function summarizerFor(provider, logger) {
+    return provider === 'anthropic'
+        ? new ClaudeLLMClient({ model: 'haiku', systemPrompt: '', logger })
+        : new OpenAILLMClient({
+            model: 'gpt-5.6-luna',
+            reasoningEffort: 'high',
+            systemPrompt: '',
+            logger,
+        });
+}
+/**
+ * The workspace's history, opened on first use, so a factory that builds an agent stays
+ * synchronous. Every agent and every file tool of one workspace reads the same files on disk.
+ */
+function historyOf(workspace) {
+    // Checked now: an agent with no root to follow is a setup error, not a first-run one.
+    if (workspace.roots.length === 0) {
+        throw new InvalidAgentConfigError('A workspace needs at least one root');
     }
+    let store;
+    const open = () => {
+        store ??= stateDirectoryOf(workspace)
+            .then(directory => openStore(workspace, directory))
+            .catch((error) => {
+            // Not kept: the next run tries again, as one whose disk was full for a moment.
+            store = undefined;
+            throw error;
+        });
+        return store;
+    };
+    return {
+        listRuns: async () => (await open()).listRuns(),
+        listRevisions: async () => (await open()).listRevisions(),
+        readRun: async (runId) => (await open()).readRun(runId),
+    };
+}
+/**
+ * What the model is told about the workspace after its instructions: the roots, which it may
+ * change, and how to name a file. A host path in an error sends the model looking for it, so
+ * the real root is given here once.
+ */
+function workspaceGuidance(roots) {
+    const [first, ...others] = roots.map(root => ({ ...root, path: resolve(root.path) }));
+    if (!first)
+        return '';
+    const described = [first, ...others].map(({ path, access }) => `- ${path}${access === 'write' ? '' : ' (read only)'}`);
+    return [
+        'The workspace:',
+        ...described,
+        `Name a file by its path relative to ${first.path}, such as src/index.ts, and a file in another folder of the workspace by its full path. Read a file before you change it.`,
+    ].join('\n');
+}
+function withGuidance(systemPrompt, guidance) {
+    return guidance === '' ? systemPrompt : `${systemPrompt}\n\n${guidance}`;
+}
+/** An `LLMAgent` on `provider`, wrapped in the harness's retry policy. */
+function buildLLMAgent(provider, { model, reasoningEffort, systemPrompt, tools, history, summarizer, maxSteps, autoApprove, logger, }) {
+    const llmClient = llmClientFor(provider, { model, reasoningEffort, systemPrompt, logger });
     // LLMAgent records nothing from a failed call, so the original prompt is the whole story.
     return new RetryingAgent({
-        inner: new LLMAgent({ llmClient, tools, autoApprove }),
+        inner: new LLMAgent({
+            llmClient,
+            tools,
+            autoApprove,
+            logger,
+            ...(history ? { history } : {}),
+            ...(summarizer ? { summarizer } : {}),
+            ...(maxSteps === undefined ? {} : { maxSteps }),
+        }),
         logger,
         noteFailures: false,
     });
 }
-// Sent on every call after the role's instructions, so it stays short: it only says how to find
-// one's way around the repository without reading all of it.
-const repositoryGuidance = 'Paths are relative to the repository root. Start with AGENTS.md and the architecture document it links to learn where things live, then read only the files your task needs.';
 /**
- * Builds the planner → executor → reviewer workflow with the planner and reviewer on the model
- * APIs, from `createLLMAgent`, each holding its role's instructions, or `systemPrompts`, as its
- * system prompt, with the read-only repository tools for the current working directory. The
- * executor stays on its Agent SDK, from `createAgent`, until an agent of ours can change files;
- * `autoApprove` reaches only it. Asynchronous because finding the program that reads the
- * repository is.
+ * Builds an agent whose conversation MiKode owns, on a provider's model API, already wrapped in
+ * the harness's retry policy. It needs the provider's API key and bills per token, where
+ * `createAgent` uses the Agent SDK's login. Each tool judges the risk of each call; a
+ * `destructive` one runs only when the run's `approve` allows it, or with `autoApprove`.
+ *
+ * @throws {InvalidAgentConfigError} for an unknown provider, a model or reasoning effort its
+ * client does not support, or two tools that share a name.
+ * @throws {UnrecoverableError} when the client cannot be set up, for example because
+ * `OPENAI_API_KEY` is missing. The Anthropic SDK resolves credentials lazily, so a missing
+ * `ANTHROPIC_API_KEY` fails the first run instead, with an `UnrecoverableError`.
+ */
+export function createLLMAgent(provider, { model, reasoningEffort, systemPrompt, tools = [], workspace, summarizeUndone = true, maxSteps, autoApprove, logger = new Logger(), }) {
+    return buildLLMAgent(provider, {
+        model,
+        reasoningEffort,
+        systemPrompt: workspace
+            ? withGuidance(systemPrompt, workspaceGuidance(workspace.roots))
+            : systemPrompt,
+        // A file tool is a harness tool under its public name.
+        tools: tools,
+        ...(workspace ? { history: historyOf(workspace) } : {}),
+        ...(workspace && summarizeUndone ? { summarizer: summarizerFor(provider, logger) } : {}),
+        maxSteps,
+        autoApprove,
+        logger,
+    });
+}
+/**
+ * The file tools for an agent from `createLLMAgent` on `provider`, over `workspace`, in the
+ * provider's own format:
+ *
+ * - OpenAI: `listFiles`, `searchText`, `readFile` and its native `apply_patch`;
+ * - Anthropic: `listFiles`, `searchText`, its native text editor, whose `view` reads, and
+ *   `delete_file`.
+ *
+ * Every one goes through the workspace's access policy: a path outside the roots, a secret,
+ * a file `.gitignore` excludes or the harness protects is refused. A change is made only in a
+ * `write` root, only from a version the agent read, and is recorded in the workspace's history,
+ * so it can be undone. Without a `write` root the tools only read. Give the agent the same
+ * `workspace`, so it follows what the history undoes.
+ *
+ * With `commands`, they include `runCommand`, which runs one of them by name, with only the
+ * parameters it declares and never through a shell. Each run asks the approver, showing the
+ * program exactly as it will run, and gets a small environment without the provider keys. The
+ * files of the `write` roots are captured before it and compared after, so what it changed is
+ * in the history too. It is trusted execution, not a sandbox: a command can reach whatever
+ * this user can. Not supported on Windows yet.
  *
- * @throws {InvalidAgentConfigError} for an unknown provider.
+ * @throws {InvalidAgentConfigError} for an unknown provider, a workspace with no root, or an
+ * invalid command, including one whose `cwd` is not in a `write` root, or any on Windows.
+ * @throws {UnrecoverableError} when no program can read the first root.
+ */
+export async function createFileTools(provider, workspace, { logger = new Logger(), commands } = {}) {
+    // Reachable from untyped input.
+    if (!isAgentProvider(provider))
+        throw unknownProvider(provider);
+    if (commands !== undefined)
+        validateCommands(commands);
+    const opened = await openWorkspace(workspace, logger);
+    return (await executorTools(provider, opened, commands));
+}
+/** The executor's file tools, and `runCommand` when there are commands. */
+async function executorTools(provider, workspace, commands) {
+    const tools = fileToolsFor(provider, workspace);
+    // Every command may belong to other roles, leaving none for this one.
+    if (commands === undefined || Object.keys(commands).length === 0)
+        return tools;
+    return [...tools, await commandToolFor(workspace, commands)];
+}
+/**
+ * What the planner and the reviewer read with: no edits, the current task's changes, and the
+ * commands given to their role.
+ */
+async function readingTools(workspace, role, commands) {
+    const { read, policy, store } = workspace;
+    const finding = createWorkspaceTools(read).filter(tool => tool.name !== 'readFile');
+    const tools = [
+        ...finding,
+        createTrackedReadFile(policy),
+        createShowChangesTool({ store, policy }),
+    ];
+    const own = commands && commandsFor(commands, role);
+    if (!own || Object.keys(own).length === 0)
+        return tools;
+    return [...tools, await commandToolFor(workspace, own)];
+}
+// Sent after the workspace's roots, so it stays short: it only says how to find one's way
+// around the repository without reading all of it.
+const repositoryGuidance = 'Start with AGENTS.md and the architecture document it links to learn where things live, then read only the files your task needs. When you know you need several files, or several searches, ask for all of them in one answer rather than one at a time: each answer is a step, and steps are limited.';
+/**
+ * Builds the planner → executor → reviewer workflow with every role on the model APIs, each
+ * holding its role's instructions, or `systemPrompts`, as its system prompt, followed by the
+ * workspace's roots.
+ *
+ * - The planner and the reviewer read: `listFiles`, `searchText`, `readFile`, and
+ *   `showChanges`, the current task's changes as far as each may read them.
+ * - The executor gets its provider's file tools (see `createFileTools`), and changes files only
+ *   in a `write` root; `autoApprove` reaches only it.
+ * - Each role has its own step limit: `maxSteps`, 80 for the executor and 65 for the others by
+ *   default.
+ * - Each role gets `runCommand` with the `commands` whose `roles` name it, the executor by
+ *   default. A command asks the approver in any role, and its files are captured around it.
+ * - The executor is told to finish only once the tests and checks pass, and the reviewer that
+ *   they passed, when the executor has a command; without one, both are told the tests were
+ *   not run, and the reviewer judges from the code whether they would pass.
+ *
+ * One run of the orchestrator is one run of the workspace's history, every round and retry
+ * included, and its `AgentResponse` names it. Every role follows what the user undoes.
+ * Asynchronous because opening the workspace is.
+ *
+ * @throws {InvalidAgentConfigError} for an unknown provider, or a workspace with no root.
  * @throws {UnrecoverableError} when a role cannot be set up, for example because
- * `OPENAI_API_KEY` or the Codex CLI binary is missing, or when no program can read the
- * repository.
+ * `OPENAI_API_KEY` is missing, or when no program can read the repository.
  */
-export async function createLLMOrchestrator({ provider, autoApprove, systemPrompts = {}, logger = new Logger(), } = {}) {
+export async function createLLMOrchestrator({ provider, autoApprove, systemPrompts = {}, workspace = { roots: [{ path: process.cwd(), access: 'read' }] }, maxSteps, commands, summarizeUndone = true, logger = new Logger(), } = {}) {
     const roles = orchestratorRolesFor(provider);
-    const tools = createWorkspaceTools(await createWorkspace({ root: process.cwd(), logger }));
-    const llmAgentFor = ({ provider, model, reasoningEffort }, systemPrompt) => createLLMAgent(provider, { model, reasoningEffort, systemPrompt, tools, logger });
-    // A caller's own prompt replaces the whole of ours, guidance included.
-    const withGuidance = (instructions) => `${instructions}\n\n${repositoryGuidance}`;
+    const steps = stepsPerRole(maxSteps);
+    const opened = await openWorkspace(workspace, logger);
+    const guidance = workspaceGuidance(workspace.roots);
+    const summarizer = summarizeUndone ? summarizerFor(roles.planner.provider, logger) : undefined;
+    const shared = { history: opened.store, ...(summarizer ? { summarizer } : {}), logger };
+    // A caller's own prompt replaces our instructions and guidance, not the workspace: the model
+    // needs the roots to name a file, as `createLLMAgent` gives them.
+    const prompt = (own, instructions) => own === undefined
+        ? withGuidance(instructions, `${guidance}\n${repositoryGuidance}`)
+        : withGuidance(own, guidance);
+    // Every command, checked once, before any role takes its share.
+    if (commands !== undefined)
+        validateCommands(commands);
+    const reader = async ({ provider, model, reasoningEffort }, role, systemPrompt) => buildLLMAgent(provider, {
+        model,
+        reasoningEffort,
+        systemPrompt,
+        tools: await readingTools(opened, role, commands),
+        maxSteps: steps[role],
+        ...shared,
+    });
+    const { executor } = roles;
+    const executorToolset = await executorTools(executor.provider, opened, commands && commandsFor(commands, 'executor'));
+    // The executor and the reviewer are told whether the tests were run, which only an executor
+    // with a command can do.
+    const executorRuns = executorToolset.some(tool => tool.name === 'runCommand');
     return new OrchestratorAgent({
-        plannerAgent: llmAgentFor(roles.planner, systemPrompts.planner ?? withGuidance(plannerInstructions)),
-        executorAgent: new InstructedAgent({
-            inner: createAgent(roles.executor.provider, {
-                model: roles.executor.model,
-                reasoningEffort: roles.executor.reasoningEffort,
-                autoApprove,
-                logger,
-            }),
-            instructions: systemPrompts.executor ?? executorInstructions,
+        plannerAgent: await reader(roles.planner, 'planner', prompt(systemPrompts.planner, plannerInstructions)),
+        executorAgent: buildLLMAgent(executor.provider, {
+            model: executor.model,
+            reasoningEffort: executor.reasoningEffort,
+            systemPrompt: prompt(systemPrompts.executor, executorRuns ? executorInstructions : executorInstructionsWithoutCommands),
+            tools: executorToolset,
+            maxSteps: steps.executor,
+            autoApprove,
+            ...shared,
         }),
-        reviewerAgent: llmAgentFor(roles.reviewer, systemPrompts.reviewer ?? withGuidance(reviewerInstructions)),
+        reviewerAgent: await reader(roles.reviewer, 'reviewer', prompt(systemPrompts.reviewer, executorRuns ? reviewerInstructions : reviewerInstructionsWithoutCommands)),
         reviewerDecisionValidator: new ReviewerDecisionValidator(),
         logger,
     });