|
| 1 | +/** |
| 2 | + * The one Agent configuration an invocation resolves, and the two things a |
| 3 | + * host does with it (specs/acp-client-spec.md §Command-line configuration). |
| 4 | + * |
| 5 | + * `xmd run` and `xmd prompt` take the same Agent, permission and provider |
| 6 | + * options, so they resolve them once, here, rather than each reading the flags |
| 7 | + * again. What they do with the result differs, and deliberately: a run installs |
| 8 | + * the registered provider into the Agent Api so a document may reach it, while |
| 9 | + * prompt generation holds a provider handle of its own and installs no document |
| 10 | + * components, no root provider and no foreground launcher — it needs turns, not |
| 11 | + * authority. |
| 12 | + * |
| 13 | + * `agent-config.ts` stays the pure flag-to-permission mapping. This module is |
| 14 | + * where the environment, the provider registry and the host's own machine |
| 15 | + * session assembly enter. |
| 16 | + */ |
| 17 | + |
| 18 | +import { |
| 19 | + Agent, |
| 20 | + installAgentComponents, |
| 21 | + installPermissionMode, |
| 22 | + registerAgentProvider, |
| 23 | +} from "@executablemd/core"; |
| 24 | +import type { AgentProviderFactory, PermissionMode } from "@executablemd/core"; |
| 25 | +import { installForegroundLauncher, env as readEnv } from "@executablemd/runtime"; |
| 26 | +import { createAcpxProvider, DEFAULT_AGENT_NAME, useAcpxProvider } from "@executablemd/acp"; |
| 27 | +import type { AcpxProvider, AcpxProviderDependencies } from "@executablemd/acp"; |
| 28 | +import { Err, Ok } from "effection"; |
| 29 | +import type { Operation, Result } from "effection"; |
| 30 | + |
| 31 | +import { resolveAgentConfig } from "./agent-config.ts"; |
| 32 | +import type { AgentFlags } from "./agent-config.ts"; |
| 33 | +import type { MachineSessionAssembly } from "./session-coordinator.ts"; |
| 34 | + |
| 35 | +/** Everything one invocation settled about agents, resolved exactly once. */ |
| 36 | +export interface AgentStack { |
| 37 | + /** The provider name the caller selected, already known to be registered. */ |
| 38 | + provider: string; |
| 39 | + /** The agent every consumer defaults to, environment fallback applied. */ |
| 40 | + defaultAgent: string; |
| 41 | + permissionMode: PermissionMode; |
| 42 | + /** What this host states about machine-wide agent sessions, if anything. */ |
| 43 | + sessions?: MachineSessionAssembly; |
| 44 | +} |
| 45 | + |
| 46 | +/** |
| 47 | + * Read the command line, the environment and the host's assembly into one |
| 48 | + * configuration. |
| 49 | + * |
| 50 | + * A failure comes back as a `Result` rather than as a printed line and an exit, |
| 51 | + * so the same resolution serves a command that runs a document and one that |
| 52 | + * generates one first. |
| 53 | + */ |
| 54 | +export function* resolveAgentStack( |
| 55 | + flags: AgentFlags, |
| 56 | + sessions: MachineSessionAssembly | undefined, |
| 57 | +): Operation<Result<AgentStack>> { |
| 58 | + const config = resolveAgentConfig(flags); |
| 59 | + if ("error" in config) { |
| 60 | + return Err(new Error(config.error)); |
| 61 | + } |
| 62 | + if (flags.agentProvider !== "acpx") { |
| 63 | + return Err(new Error(`Unknown agent provider "${flags.agentProvider}"`)); |
| 64 | + } |
| 65 | + const defaultAgent = |
| 66 | + config.defaultAgent ?? (yield* readEnv("DEFAULT_AGENT_NAME")) ?? DEFAULT_AGENT_NAME; |
| 67 | + return Ok({ |
| 68 | + provider: flags.agentProvider, |
| 69 | + defaultAgent, |
| 70 | + permissionMode: config.permissionMode, |
| 71 | + ...(sessions === undefined ? {} : { sessions }), |
| 72 | + }); |
| 73 | +} |
| 74 | + |
| 75 | +/** |
| 76 | + * What this host built, if it built anything. |
| 77 | + * |
| 78 | + * Each piece reaches the provider directly rather than through a context: who |
| 79 | + * owns a session and which build it belongs to are security decisions, and ones |
| 80 | + * a document could replace are not ones. The two advertised sets are stated by |
| 81 | + * the host, not inherited. |
| 82 | + */ |
| 83 | +export function hostAcpDependencies( |
| 84 | + sessions: MachineSessionAssembly | undefined, |
| 85 | +): AcpxProviderDependencies { |
| 86 | + if (sessions === undefined) { |
| 87 | + return {}; |
| 88 | + } |
| 89 | + return { |
| 90 | + ...(sessions.coordinator ? { coordinator: sessions.coordinator } : {}), |
| 91 | + ...(sessions.routeStore ? { routeStore: sessions.routeStore } : {}), |
| 92 | + ...(sessions.executableObserver ? { executableObserver: sessions.executableObserver } : {}), |
| 93 | + advertiseNativeLaunch: sessions.advertiseNativeLaunch, |
| 94 | + advertiseClientNativeAttachment: sessions.advertiseClientNativeAttachment, |
| 95 | + }; |
| 96 | +} |
| 97 | + |
| 98 | +/** |
| 99 | + * Install the agent stack a document runs under: the registration, the |
| 100 | + * components with the resolved root provider, the permission mode, and the |
| 101 | + * terminal this command has to give away. |
| 102 | + * |
| 103 | + * Nothing starts an agent — the provider validates availability on first use. |
| 104 | + */ |
| 105 | +export function* installRunAgentStack(stack: AgentStack): Operation<void> { |
| 106 | + const acpx = createAcpxProvider(hostAcpDependencies(stack.sessions)); |
| 107 | + yield* registerAgentProvider("acpx", acpx); |
| 108 | + |
| 109 | + // The trusted host selects its own root provider by name. Document-level |
| 110 | + // selection goes through the installation protocol; this is the host saying |
| 111 | + // what it configured, which no document is composing around. |
| 112 | + const providers: Record<string, AgentProviderFactory> = { acpx }; |
| 113 | + const factory = providers[stack.provider]; |
| 114 | + const { defaultAgent, permissionMode } = stack; |
| 115 | + yield* installAgentComponents({ |
| 116 | + defaultAgent, |
| 117 | + permissionMode, |
| 118 | + rootProvider: { factory, options: { defaultAgent, permissionMode } }, |
| 119 | + }); |
| 120 | + yield* installPermissionMode(permissionMode); |
| 121 | + // `xmd run` is the one command that has a terminal to give away. Help, |
| 122 | + // document inspection and `xmd test` install no launcher, so a document that |
| 123 | + // reaches <Session.Launch> under any of them refuses instead of spawning. |
| 124 | + yield* installForegroundLauncher(); |
| 125 | +} |
| 126 | + |
| 127 | +/** |
| 128 | + * A provider that can run turns, and nothing else. |
| 129 | + * |
| 130 | + * `xmd prompt` writes a document before one exists, so there is nothing to |
| 131 | + * install components into and no launch for anyone to authorize. It takes the |
| 132 | + * provider's operations directly and answers only the one Agent operation the |
| 133 | + * provider itself performs — resolving the agent a session and a turn belong |
| 134 | + * to. Everything else on the Agent Api stays at its base behavior, so a launch |
| 135 | + * or a document prompt reaching this scope is refused rather than served. |
| 136 | + * |
| 137 | + * The permission policy is installed first, so it encloses the provider state's |
| 138 | + * own scope and answers the native permission requests generation raises with |
| 139 | + * the same `--approve-all`, `--approve-reads` or `--deny-all` choice a run uses. |
| 140 | + * |
| 141 | + * `instructions` become the fresh session's system prompt. They reach ACPX |
| 142 | + * through `newSessionOptions`, which it applies when it creates a session and |
| 143 | + * ignores when it reuses a record. |
| 144 | + */ |
| 145 | +export function* useGeneratorAgent( |
| 146 | + stack: AgentStack, |
| 147 | + instructions: string, |
| 148 | + dependencies?: AcpxProviderDependencies, |
| 149 | +): Operation<AcpxProvider> { |
| 150 | + yield* installPermissionMode(stack.permissionMode); |
| 151 | + |
| 152 | + let provider: AcpxProvider | undefined; |
| 153 | + yield* Agent.around( |
| 154 | + { |
| 155 | + *agent([name], _next) { |
| 156 | + if (provider === undefined) { |
| 157 | + throw new Error("the generator agent provider is not established yet"); |
| 158 | + } |
| 159 | + return yield* provider.agent(name); |
| 160 | + }, |
| 161 | + }, |
| 162 | + { at: "min" }, |
| 163 | + ); |
| 164 | + |
| 165 | + provider = yield* useAcpxProvider( |
| 166 | + { defaultAgent: stack.defaultAgent, permissionMode: stack.permissionMode }, |
| 167 | + { |
| 168 | + ...hostAcpDependencies(stack.sessions), |
| 169 | + ...dependencies, |
| 170 | + newSessionOptions: { systemPrompt: instructions }, |
| 171 | + }, |
| 172 | + ); |
| 173 | + return provider; |
| 174 | +} |
0 commit comments