[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10,"_11":12},"actionData","errors","root",{"_228":-5,"_231":232,"_233":234},"routes/shell",{"_41":42,"_227":-5,"_228":-5,"_229":230},"routes/repo",{"_34":-7,"_35":36,"_37":38,"_39":40,"_41":42,"_43":32,"_44":32,"_45":32,"_46":32,"_47":32,"_48":32,"_49":50,"_51":50,"_52":32,"_53":-7,"_54":-7,"_55":56,"_57":58,"_59":60,"_61":-5,"_62":63,"_64":65,"_66":67,"_68":69},"routes/repo.blob",{"_13":14,"_15":16,"_17":18,"_19":20,"_21":22,"_23":24,"_25":-5,"_26":27,"_28":29,"_29":30,"_31":32,"_33":14},"ref","main","path","research/2026-09-28-keepcontext-add-an-atomic-harness-adapter-to-chopin-s-hosted-planner-built-direc.md","oid","2af2d1a88c4563affba4e21efaf5a89b7bf50df2","size",38563,"commit","2182c95de44a8f63fd86af1c5874ae0ca298f807","mounts",[],"source","plain",{"_13":14,"_15":16},"kind","text","# Research report: adding an `atomic` Planner harness to Chopin on the Atomic SDK\n\nThe research is done and the design is feasible. I ran a scratch spike against the installed Atomic 0.9.23 and the repo's own model stub, in `/tmp/atomic-spike/` outside the repository. It confirmed the in-process design: `createAgentSession()` with a custom `DefaultResourceLoader`, in-memory session and settings managers, and a `ModelRuntime` using `AuthStorage.inMemory()`. I changed no repository files.\n\nThe SDK does **not** give most of the guarantees by default. The adapter has to set them explicitly and check them itself. Five problems need handling, and each has an SDK option or hook that solves it:\n\n1. **Unknown models fall back silently.** Passing `model: undefined` makes Atomic pick the first available model with no `modelFallbackMessage`. The adapter must look the model up itself and fail the turn.\n2. **An empty system prompt brings in Atomic's coding-assistant prompt.** That text includes an Atomic docs section. The adapter must always force the exact per-turn system prompt.\n3. **`prompt()` does not reject on abort or model error.** It resolves normally; the failure only shows on the last assistant message and `agent.state.errorMessage`.\n4. **A host tool that ignores its abort signal makes `abort()` and `prompt()` hang.** The adapter must settle pending host-tool promises when the turn aborts.\n5. **Large tool results are written to disk.** Results over 50,000 characters are saved to a temp file and the model gets only a preview and a path. Host tools should set `maxResultSizeChars: Infinity`.\n\nNo `bun patch` looks necessary. Every safety need maps to a supported option or extension hook.\n\n## Contract amendments received\n\nNone. No steering or follow-up messages arrived during this stage. The launch objective and acceptance criteria are the whole contract.\n\n## Compatibility posture\n\n`breaking_changes_allowed: false` for the existing `copilot-sdk` and `pi` harnesses. The acceptance criteria say not to regress them. This is an addition to the code-owned `harnesses` map. Existing behaviour that must stay the same:\n\n- `harnessFor` validation for `copilot-sdk` and `pi`.\n- The `harnessContract` suite in `contract.ts`, which the other adapters also run.\n- The `PLANNER_TOOL_NAMES` boundary in `chat/service.ts`.\n- The Pi patch and Pi's result tool.\n\n---\n\n## 1. Codebase facts (verified this session)\n\n### Harness selection — `apps/server/src/harness/harnesses.ts`\n\n- The map is `harnesses = { \"copilot-sdk\": createCopilotSdk, pi: createPiHarness }`. Its `satisfies` type is `(settings: {credentials, limits, auth?}) => HarnessV1` (lines 17-27).\n- The cached singleton is `selected: HarnessV1 & { shutdown(): Promise }` (line 31). `shutdownHarnesses()` calls `selected?.shutdown()` (lines 89-93).\n- `loopback()` accepts `localhost`, `::1`, `[::1]` and `127.x.x.x` (lines 33-37).\n- Pi auth modes are `PI_AUTH_MODES = {auto, openai, anthropic, custom, ai-gateway}` (line 42). `harnessFor` for Pi (lines 54-63) does three things:\n - requires `HARNESS_AUTH`;\n - rejects unknown modes;\n - allows only `ai-gateway` on a non-loopback host.\n- Every other harness goes through the generic rule: an auth value other than `direct` or `ai-gateway` needs loopback (lines 64-66). An `atomic` branch is needed, or `atomic` will silently use the generic rule.\n- `createPiHarness` forwards only `auth` (lines 11-15). The Atomic factory should follow the same pattern; credit `limits` are Copilot-specific.\n\n### Tests to update — `harnesses.test.ts`\n\n- Line 8 pins `Object.keys(harnesses)` to `[\"copilot-sdk\", \"pi\"]`. It must become `[\"copilot-sdk\", \"pi\", \"atomic\"]`, or whatever order registration uses.\n- Add the Atomic auth-mode and loopback matrix in the same style as the Pi tests at lines 28-47.\n\n### Shared contract — `apps/server/src/harness/contract.ts`\n\n`harnessContract(name, createHarness, createSandboxSession?)` has three tests:\n\n1. **Tools boundary** (prompt `\"tools\"`, host tools `first_host` and `second_host`):\n - the turn sees exactly the host tools;\n - `builtinTools` is empty, or `supportsBuiltinToolFiltering` is true with `builtinToolFiltering: {mode:\"allow\", toolNames:[]}`;\n - no non-host `tool-call`/`tool-result` events appear;\n - destroy runs once.\n2. **Structured output** (prompt `\"output\"`, `Output.object({answer: string})`): `result.output` parses and `responseFormat.type === \"json\"` is forwarded.\n3. **Abort** (prompt `\"abort\"`): `abortSignal` is forwarded as the same object; after abort `hasUnfinishedTurn()` is false; destroy is idempotent.\n\nThe suite does **not** test a plain text turn, and it does not force a host-tool round trip. Criterion 6 requires both, so `atomic.contract.test.ts` needs extra cases. Recommendation: script the stub so `\"tools\"` makes a call to `first_host` and then returns text, and add an explicit `\"plain\"` text test. `contract.ts` is shared with `copilot-sdk` and `pi`; changing it risks regressing them.\n\n### Pi reference — `apps/server/src/harness/pi.contract.test.ts` and `pi/model-stub.ts`\n\n- **The stub:**\n - It is an OpenAI-completions SSE server.\n - It is scripted by the last user message and `hasPriorToolResult`, which is true when any message has `role: \"tool\"`.\n - It supports `text`, `tool` and `hold` turns; `hold` closes the response on request abort.\n - It records `prompt`, `system`, `toolNames` and `hasPriorToolResult` for each request.\n- **Pi's extra tests** can be copied almost directly:\n - one model request on a structured turn;\n - no result tool offered on a plain turn;\n - a rogue result-tool call is blocked and kept out of the stream;\n - quoted earlier chat does not enable the tool;\n - host `AGENTS.md` isolation;\n - an unknown model fails with no model request.\n- **Stub caveat (seen in the spike):** `hasPriorToolResult` scans the whole history. An Atomic session keeps multi-turn history, so any later turn in a session that already made a tool call gets `\"Done.\"`. Each contract case uses a fresh `HarnessAgent` session, so that is fine. Multi-turn unit tests need a fresh session per scenario or a stub keyed differently.\n\n### Pi's result-tool approach — `apps/server/src/harness/pi/adapter.ts`\n\n- `piResultToolExtension(state)` (lines 53-80):\n - registers a `Type.Object({}, {additionalProperties:true})` tool that returns `terminate: true`;\n - on `before_agent_start`, adds or removes the tool from the active set based on `state.structured`;\n - on `tool_call`, blocks the tool when the turn is not structured.\n- `runOutputTurn` (lines 106-191):\n - reserves the result tool's name;\n - hides the result tool's parts;\n - in JSON mode drops prose, reasoning and inner `finish-step`s;\n - on `finish`, emits `text-start`/`text-delta`/`text-end` with the JSON and one synthetic `finish-step`;\n - rejects `done` when no result or an invalid result arrived.\n- The extension is typed against Pi's `ExtensionAPI` from `@earendil-works/pi-coding-agent`. Atomic's `ExtensionAPI` has the same members (`registerTool`, `on(\"before_agent_start\")`, `on(\"tool_call\")`, `getActiveTools`, `setActiveTools`) but they are different TypeScript types (`dist/core/extensions/api-types.d.ts:54,71,77,146,150`).\n- Recommendation: write an Atomic-typed twin of the extension, or share only the name, instruction text and stream-suppression helpers. Forcing one generic type over two different overload sets is likely to fight `tsgo`.\n\n### Copilot reference — `apps/server/src/harness/copilot-sdk/adapter.ts`\n\n- **Host tools** (lines 180-212): the handler emits `tool-call`, parks a resolver keyed by `toolCallId`, then on `submitToolResult` emits `tool-result` and throws when `isError` is set.\n- **Terminal result tool** (lines 214-231): it emits the JSON as text.\n- **Fail-closed check** (lines 107-138): `assertHostOnly` compares live tool metadata with exactly the host names and logs `[agent] N tools: …`. AGENTS.md \"Diagnostics\" expects this kind of log.\n- **Abort** (lines 435-447): resolves every pending tool with an error, then settles.\n- **Unsupported methods** (lines 472-476): continue, suspend, detach and stop throw `HarnessCapabilityUnsupportedError`. Criterion 1 requires the Atomic adapter to go further; see §3.\n- **Defaults:** `builtinTools: {}` and `supportsBuiltinToolFiltering: true` (lines 279-280). The Atomic adapter should declare the same.\n\n### How Chopin uses harnesses (subagent report, spot-checked)\n\n- **Planner:** `service.ts:891-901` and `session.ts` open **one HarnessAgent session per chat turn** and destroy it in `finally` (I read `service.ts:1020-1060`).\n- **Workers:**\n - The summary worker runs **several `generate` turns on one worker session** with `output` (I read `document-summary.ts:225-260`).\n - Research workers use `structuredAgent`, which has `output` plus an optional `web_search` host tool (`agents.ts:94-125`).\n - So the Atomic adapter must support multi-turn sessions and a host-tool round trip inside a structured turn.\n- **`translate()`** (`chat/service.ts` ~1156-1272):\n - a `tool-call` outside `PLANNER_TOOL_NAMES` aborts the turn with a boundary failure;\n - `tool-approval-request` aborts;\n - `error` parts are posted to chat.\n- Nothing in Chopin calls `continueStream`, `stop`, `detach` or `doCompact` in production (grep of `apps/server/src`). Continue and stop are required only by the contract.\n- **`config.ts:49-58`:** `DEFAULT_MODEL = \"gpt-6-luna\"`, and `MODEL` is required only for `HARNESS=pi`. In the spike, Atomic's catalog contains `github-copilot/gpt-6-luna`, but a bare `gpt-6-luna` has no provider. Mirroring the Pi rule for `atomic` is my proposal; it is not a contract clause.\n\n### Packages\n\n- The root `package.json` `catalogs.harness` has no `@bastani/atomic`. Add `\"@bastani/atomic\": \"0.9.23\"` there and `\"@bastani/atomic\": \"catalog:harness\"` in `apps/server/package.json`.\n- `bun.lock` has no `@bastani` entries. `node_modules/.bun/@bastani+atomic@0.9.20-alpha.5` is stale, left over from an older branch; the lockfile will be regenerated.\n- `npm view` confirms `latest = 0.9.23`, published 2026-09-27. It depends on `typebox 1.3.27`, while Chopin's catalog pins `1.3.7`. TypeBox's `TSchema` is an empty interface (`typebox/build/type/types/schema.d.mts:1`), so the mismatch should be type-compatible, but that is unverified in `tsgo`.\n- The package is 41 MB unpacked, with heavy dependencies: `embedded-postgres`, `@dbos-inc/dbos-sdk`, `pg`, platform natives for linux-x64/arm64 gnu/musl, darwin and win32. There is no `postinstall`. Expect a noticeably larger Docker image; the `oven/bun` Debian base should use the gnu natives.\n\n### Lint and format\n\n- `.oxlintrc.json` restricts `@github/copilot-sdk` imports to `harness/copilot-sdk/`. A matching restriction for `@bastani/atomic` to `harness/atomic/` would follow convention; that is my proposal, not a requirement.\n- `dprint.json` sets tabs, width 100 and double quotes.\n- `bun run ci` runs `dprint check && oxlint && bun scripts/check-tokens.ts`; the token check only inspects CSS.\n\n### History\n\n- Branch `backup/main-before-atomic-rewind` (commit `49419cf`) holds an earlier Atomic SDK backend, from before the move to the `HarnessAgent` architecture:\n - `apps/server/src/agent/atomic.ts` and `events.ts`;\n - an inert custom `ResourceLoader`, `builtins` all false, an `AMBIENT` tool denylist;\n - `resolveAtomicModel` built on `runtime.getModel`;\n - an `abortEpoch` guard so an abort is not reported as a provider error.\n It is useful prior art, but it was written against 0.9.20-alpha.5 and a Copilot-shaped event bridge.\n- Relevant `User-preference` trailers:\n - \"Prefer an upstream-supported extension point over working around third-party adapter races\" (`a3ab603`);\n - \"Patch pinned dependencies with bun patch when the upstream adapter exposes no option for a needed safety fix\" (`c9d8a9f`);\n - \"Record third-party harness limitations as documented caveats rather than patching dependencies\" (`2c83ef3`).\n- Trailers are formatted as in `0943098` and `45889b6`: `Assistant-model`, `Assistant-workflow`, one `Assistant-verification: : ` per check, and `Co-authored-by: Alex Lavaee `.\n- Comparable harness-adapter durations from the `harness-stack` records: 95m (Pi admit), 92m, 70m, 61m, 30m, 28m (blocked). The median is about 65m over 6 records. Most ran over their estimates.\n\n---\n\n## 2. Atomic SDK 0.9.23 facts\n\nPaths are under `/home/alexlavaee/.bun/install/global/node_modules/@bastani/atomic/dist/`.\n\n### Session assembly — `core/sdk.js`, `core/sdk-types.d.ts`\n\n- **`builtins`:**\n - Shipped packages are on unless a key is explicitly `false` (`sdk-types.d.ts:11-14`).\n - A custom `resourceLoader` is wrapped in `BuiltinResourceLoader`, which adds the shipped packages whatever the loader's `no*` flags say (`sdk.js:161-164`).\n - Intercom is **mandatory**: it is added by `withMandatoryResourceLoader` unless `builtins.intercom === false` (`sdk.js:165-167`, `mandatory-resource-loader.js:11-27`).\n - Spike (\"loose\" mode, with the tools allowlist but default builtins): the active tools stayed limited to the allowlist, but all five builtin extension bundles loaded and ran their startup code, and the run was much slower. So all five keys must be `false`; an allowlist alone is not enough.\n- **Tools** (`sdk.js:238-243`, `agent-session-tool-registry.js:17-37,80-85`):\n - `tools` omitted: the default coding tools are active, plus every extension tool. Spike \"notools\" mode listed read, bash, kill, edit, write, find, search, ask_user_question, todo, workflow, subagent, web_search, code_search, fetch_content, get_search_content, intercom and mcp.\n - `tools: [...]`: only the named tools are even registered, and **both custom and extension tools must be named**. Every registered allowed tool is re-activated whenever the registry refreshes.\n - `noTools: \"all\"` exposes nothing.\n - A custom tool named `intercom` is dropped.\n- **Model:** there is no lookup when `model` is passed. When it is `undefined`, `findInitialModel` silently picks a preferred or first-available model (`sdk.js:182-211`).\n - Spike: `runtime.getModel(\"stub\",\"nope\")` returned `undefined`. Passing that through produced a session on `stub/stub-model` with `modelFallbackMessage: undefined`.\n- **Defaults to override:**\n - `fallbackModels` defaults to `settings.fallbackModels`. `SettingsManager.inMemory` makes that `[]`; pass `fallbackModels: []` explicitly anyway.\n - `agentDir` defaults to `$ATOMIC_CODING_AGENT_DIR` → `$PI_CODING_AGENT_DIR` → `~/.atomic/agent`.\n - Creation always calls `modelRuntime.refresh({allowNetwork:false})`.\n- **`systemPromptTransform`** exists but applies only at construction.\n- **`createStructuredOutputTool`** runs a second `streamSimple` request (`core/tools/structured-output.js:60-71`). Do not use it; criterion 4 forbids it.\n\n### Resource loader — `core/resource-loader-reload.js`, `resource-loader-types.d.ts:113-167`\n\n- The flags `noExtensions`, `noSkills`, `noPromptTemplates`, `noThemes` and `noContextFiles` gate discovery (`reload.js:204-211, 224, 259-261, 276-278, 297-299, 314-322`).\n- `additional*Paths` and CLI paths still load when the flags are set. Leave them empty.\n- `extensionFactories` load even with `noExtensions`.\n- `SYSTEM.md` and `APPEND_SYSTEM.md` are discovered unless `systemPrompt` or `appendSystemPrompt` is given (`reload.js:329-341`). Pass `appendSystemPrompt: []`.\n- **Empty system prompt trap:** `systemPrompt: \"\"` is not nullish, so discovery is skipped, but `buildSystemPromptSections` treats `\"\"` as missing (`system-prompt.js:105-115`). The result is Atomic's default preamble: \"expert coding assistant…\", the tools list, the guidelines, and an \"Atomic documentation\" section.\n - Spike with `SPIKE_SP=\"\"`: \"Atomic documentation\" and \"expert coding assistant\" were both present.\n - HarnessAgent turns with no `instructions`, including all three shared contract cases, hit this unless the adapter forces the prompt.\n- Even with a custom prompt, Atomic adds ``, `` and `` sections (`system-prompt.js:139-141`).\n- **Forcing the prompt:** a `before_agent_start` handler that returns `{systemPrompt}` sets `forceSystemPrompt` (`extensions/runner-events.js:324`). Spike: the model received exactly `\"FORCED-TURN-PROMPT\"` on every turn. This is the upstream-supported hook for per-turn instructions without reloading resources.\n\n### Isolation checked in the spike\n\n- **Setup:** a temporary `HOME` containing `~/.atomic/agent/{AGENTS.md, SYSTEM.md, APPEND_SYSTEM.md, settings.json (defaultTools, fallbackModels), extensions/evil.ts, skills/, prompts/}`, `~/.pi/agent/AGENTS.md` and `~/.agents/skills`. The working directory held `AGENTS.md`, `CLAUDE.md`, `.atomic/extensions`, `.pi/extensions` and `.agents/skills`.\n- **Configuration:** `DefaultResourceLoader` with all `no*` flags, `systemPrompt`, `appendSystemPrompt: []` and one inline factory; `SettingsManager.inMemory`; `SessionManager.inMemory(cwd)`; all five builtins `false`; `tools: [host, RESULT]`.\n- **Results:**\n - The only extension was ``.\n - Active and registered tools were exactly the host tool and the result tool.\n - No marker text reached the system prompt the stub received.\n - **No files were created or modified under the temporary `HOME` or cwd** (`find -newer marker` was empty).\n\n### Events — spike traces\n\n| Scenario | Event sequence |\n| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Plain turn | `agent_start turn_start message_start/end:system message_start/end:user message_start:assistant message_update:text_start/text_delta/text_end message_end:assistant:stop turn_end agent_end agent_settled` |\n| Host tool | `…message_update:toolcall_start/delta/end message_end:assistant:toolUse tool_execution_start:host_a tool_execution_end:host_a message_start/end:toolResult turn_end turn_start …text… agent_end` — two model requests |\n| Terminating tool | one model request; `tool_execution_*:RESULT`, then `agent_end` with no second assistant message; the last message is a `toolResult` |\n| Blocked result tool on a plain turn | `tool_execution_start/end:RESULT:err`, then the model continues — these parts must be kept out of the stream |\n| Hallucinated `bash` | `tool_execution_start/end:bash:err`, \"tool not found\" handled inside Atomic |\n| Abort | `prompt()` **resolved** without throwing; `agent.state.errorMessage = \"Request aborted\"`; last assistant `stopReason: \"aborted\"`; `agent_end` still fires |\n\n- **Abort during a pending host tool:**\n - If `execute` honours `signal`, abort settles in about 200 ms with `errorMessage \"The operation was aborted.\"` and `tool_execution_end:err`.\n - If `execute` ignores `signal`, **`abort()` and `prompt()` hang** (killed by a 20 s timeout).\n- **Other facts:**\n - `AgentToolResult` has no `isError`. A throw from `execute` becomes `isError`.\n - `tool_call` handler errors **block** execution, which fails closed (`agent-session-tool-hooks.js:13-33`).\n - `before_agent_start` handler errors are only reported through `emitError` and **do not fail the turn** (`extensions/runner.js:655`). Fail-closed checks therefore belong in the adapter, not in a throwing hook.\n- **Other prompt paths:**\n - `prompt()` runs `/…` text as an extension command, and expands skill and template syntax, unless `expandPromptTemplates: false` (`agent-session-prompt.js:93-103, 143-147`). Pass `false`.\n - Missing auth throws before any request (`agent-session-prompt.js:187-200`).\n- **Oversized results:** results over `DEFAULT_MAX_RESULT_SIZE_CHARS = 50_000` (`core/tools/tool-limits.js:17`) are persisted to a session temp directory. An in-memory `SessionManager` has an empty session dir, so the OS temp dir is used. The model then receives a preview and a path it cannot read (`agent-session-tool-hooks.js:69`, `tools/oversized-tool-result.js:276-313`). Setting `maxResultSizeChars: Infinity` on host `ToolDefinition`s opts out.\n\n### Settings defaults that matter (`core/settings-manager-basic-accessors.js`)\n\n| Setting | Default | Effect |\n| ------------------------ | ----------------- | --------------------------------------------- |\n| `compaction.enabled` | `true` | Extra summarization model calls |\n| `retry.enabled` | `true`, 3 retries | Automatic retries |\n| `cacheWarming` | `\"streaming\"` | Extra cache-refresh requests to the provider |\n| `sessionSummary.enabled` | `true` | Skipped in SDK \"print\" mode, per the subagent |\n\nSuggested in-memory settings: `{ compaction: {enabled:false}, cacheWarming: \"off\", sessionSummary: {enabled:false} }`, plus explicit `fallbackModels: []`. Keeping `retry` on is a judgement call.\n\n### Auth — `core/model-runtime.js:86-117`, `core/auth-storage*.js`, `@bastani/pi-ai/dist/env-api-keys.js`\n\n- `ModelRuntime.create({ credentials?, authPath?, modelsPath?: string|null, refreshOnCreate?, allowModelNetwork? })` has no `providers` option. Register custom providers with `runtime.registerProvider(id, {baseUrl, apiKey, api:\"openai-completions\", models:[…]})`; this worked in the spike.\n- **Default credentials** are file-backed and layered: `~/.atomic/agent/auth.json` and `~/.pi/agent/auth.json`. `FileAuthStorageBackend.withLock` makes the parent directory. OAuth and key updates write `auth.json` atomically (`auth-storage.js:30-122`, `auth-storage-backends.js:20-80`). `readStoredCredential` also goes through `withLock`.\n- **`AuthStorage.inMemory(data)`** never touches disk. `modelsPath: null` avoids `models.json` and `models-store.json`.\n- **Environment keys still resolve with in-memory credentials.** Spike with `ANTHROPIC_API_KEY=dummy` and `AI_GATEWAY_API_KEY=dummy2`: `hasConfiguredAuth(\"anthropic\")` and `(\"vercel-ai-gateway\")` were true; without them both were false.\n- pi-ai also treats ambient **AWS profile/IAM** credentials (for `amazon-bedrock`) and **gcloud ADC** at `~/.config/gcloud/…` (for `google-vertex`) as configured auth. Those are host-logged-in cloud credentials even in an \"env-only\" mode.\n- `ReadOnlyAuthStorage` exists (`auth-storage.js:123`) but is **not exported** from the package root. `getAgentConfigPaths` and `AuthStorage` are exported (`index.d.ts:14,16`).\n- The Harness auth vocabulary is `HarnessV1Authentication = 'auto' | 'ai-gateway' | C | Record` (`@ai-sdk/harness/src/v1/harness-authentication.ts:15-24`).\n\n---\n\n## 3. Implementation guidance\n\nThese are proposals. Where the contract does not fix a choice, it is marked **(decision)**.\n\n### Files\n\n- `apps/server/src/harness/atomic/adapter.ts`: `createAtomicAdapter(settings)` returning `HarnessV1 & { shutdown(): Promise }`, with `harnessId: \"atomic\"`, `builtinTools: {}` and `supportsBuiltinToolFiltering: true`.\n- An optional `apps/server/src/harness/atomic/auth.ts` for mode handling.\n- `apps/server/src/harness/atomic/adapter.test.ts`.\n- `apps/server/src/harness/atomic.contract.test.ts`, importing `../pi/model-stub` or `./pi/model-stub`.\n- `harnesses.ts`: `atomic: createAtomicHarness`, forwarding only `auth`, plus an `atomic` branch in `harnessFor`. Also update `harnesses.test.ts`.\n- `package.json` catalog and `apps/server/package.json`; regenerate `bun.lock`.\n- Optional: `config.ts` and `config.test.ts` to require `MODEL` for `atomic`; an `.oxlintrc.json` import restriction.\n\n### Session creation\n\n- Create the Atomic session lazily on the first turn, or in `doStart`. Each HarnessV1 session owns one `AgentSession`.\n- Options:\n - `cwd`: a fresh `mkdtemp` directory removed in `doDestroy`. Do not use the sandbox's virtual `sessionWorkDir` or `process.cwd()`.\n - `agentDir`: that same empty temp directory.\n - `modelRuntime`: built per the auth mode.\n - `model`: the resolved model; `thinkingLevel: \"off\"` or a setting **(decision)**.\n - `fallbackModels: []`.\n - `sessionManager: SessionManager.inMemory(cwd)`; `settingsManager: SettingsManager.inMemory({...})` per §2.\n - `builtins: { workflows:false, subagents:false, mcp:false, \"web-access\":false, intercom:false }`.\n - `tools: [...hostNames, RESULT_TOOL]`.\n - `customTools`: host tools defined with `defineTool`, `Type.Unsafe(spec.inputSchema ?? {type:\"object\"})` and `maxResultSizeChars: Infinity`.\n- The loader is `new DefaultResourceLoader({ cwd, agentDir, settingsManager: SettingsManager.inMemory({}), noExtensions, noSkills, noPromptTemplates, noThemes, noContextFiles: true, systemPrompt: , appendSystemPrompt: [], extensionFactories: [resultToolExtension(state)] })`.\n- **Rebuild or refuse** **(decision):** if a later turn changes the host tool set, the session must be rebuilt, because only allowlisted tools are registered. Pi rebuilds on a tool-signature change; Copilot uses a fresh session per turn. Model changes can use `session.setModel` after checking.\n\n### Fail-closed checks\n\nBefore every `prompt()`, and throw before any model request if a check fails:\n\n- `created.extensionsResult.extensions` must be exactly the one inline factory.\n- The names from `session.getAllTools()` must equal `host ∪ {RESULT}`.\n- After `setActiveToolsByName(expected)`, `getActiveToolNames()` must equal `expected`, where `expected = structured ? [...host, RESULT] : host`.\n- `session.model` must match the requested provider and id.\n- Log `[agent] N tools: …` like Copilot does.\n\nDuring the turn: treat `tool_execution_start` for a name outside `host ∪ {RESULT}` as a boundary event. **(decision):** either abort with an `error` part, or let Atomic's \"tool not found\" stand and never emit it. The spike shows Atomic already refuses unknown names without running anything, and emitting it would make `chat/service.ts` abort the turn anyway.\n\n### Per-turn prompt and structured output\n\n- The result extension, following `piResultToolExtension`, uses `on(\"before_agent_start\")` to:\n 1. `setActiveTools(expected)`;\n 2. return `{ systemPrompt: }`.\n- `on(\"tool_call\")` blocks `RESULT` unless `state.structured`.\n- The adapter sets `state.structured` from `turn.responseFormat?.type === \"json\"`, never from prompt text. It reserves the `RESULT` name against host tools, as Pi and Copilot do.\n- `RESULT.execute(id, params)` captures `params` in adapter state and returns `terminate: true`.\n- On `agent_end`, if a result was captured, emit `text-start`/`text-delta(JSON.stringify(params))`/`text-end`, then `finish-step` and `finish`. If not, reject `done` with \"Atomic turn ended without a structured result.\"\n- In JSON mode, drop prose and reasoning, as both existing adapters do.\n- The spike confirmed one model request for a structured turn. Keep the Pi-style result-tool schema, `Type.Object({}, {additionalProperties:true})` with the schema written into the instruction, or use `Type.Unsafe(responseFormat.schema)` with a rebuild when the schema changes **(decision)**. Either way HarnessAgent validates host-side.\n- Workers need a `web_search` round trip inside a structured turn to keep working. The name `web_search` no longer collides with anything once `web-access` is off.\n\n### Stream translation (only what `translate()` and HarnessAgent consume)\n\n- `message_update` with `text_start`/`text_delta`/`text_end` on assistant messages maps to `text-start`/`text-delta`/`text-end` with a stable id per content block. `thinking_*` maps to `reasoning-*` (optional). Ignore `system`, `user` and `toolResult` messages.\n- **Host tool round trip:** inside `execute`:\n 1. emit `tool-call {toolCallId, toolName, input: JSON.stringify(params)}`;\n 2. park a resolver, and race it against `signal`, **mandatory** per the spike;\n 3. on `submitToolResult`, emit `tool-result {…, result, isError}`;\n 4. return `{content:[{type:\"text\", text: serialize(output)}]}`, or throw when `isError`.\n Never emit parts for `RESULT` or for blocked or unknown tools.\n- At the end of `prompt()`, inspect the last assistant message:\n - `stopReason: \"aborted\"`, or the abort signal is set: settle quietly or with an abort error. The HarnessAgent `settleFailure` path turns it into an `abort` part, and `hasUnfinishedTurn` is false.\n - `stopReason: \"error\"` or `agent.state.errorMessage` set: emit an `error` part and reject `done`.\n - Otherwise emit `finish-step` and `finish` with `stop`. Usage can come from the assistant message's `usage` or be zeroed as Copilot does.\n - `prompt()` preflight throws, such as missing auth, reject `done`.\n- **Abort:**\n - `turn.abortSignal` calls `session.abort()`;\n - settle every pending resolver with an error;\n - bound the wait as Copilot's `bounded()` does;\n - ignore late `submitToolResult` calls.\n\n### Remaining lifecycle\n\n- **`doContinueTurn`:** the in-process equivalent of Pi's live-turn path (§4): if a turn is active, re-point `emit` and return the live control. Otherwise **(decision)**: throw `HarnessCapabilityUnsupportedError`, or run `session.agent.continue()`. `agent` is reachable, but `continue()` is not part of the public session surface.\n- **`doStop` / `doDetach`:** tear down and return `{type:\"resume-session\", harnessId:\"atomic\", specificationVersion:\"harness-v1\", data:{}}`, with `isResume: false`. The in-memory session cannot resume across processes, so document that as a caveat.\n- **`doSuspendTurn`:** a lossy `continue-turn` or unsupported **(decision)**.\n- **`doCompact`:** unsupported, since compaction is off.\n- **`doDestroy`:** idempotent — abort, settle pending tools, `session.dispose()`, remove the temp dir.\n- **`shutdown()`:** dispose live sessions or no-op. There is no global Atomic runtime unless one shared `ModelRuntime` is kept.\n- **`skills`:** Chopin always passes `[]`. Rejecting non-empty skills keeps the \"no skills\" guarantee explicit **(decision)**.\n\n### `HARNESS_AUTH` for `atomic` (decision; evidence above)\n\nProposal, following the Pi pattern and the `HarnessV1Authentication` vocabulary. `HARNESS_AUTH` is required; unknown values are refused.\n\n| Mode | Credentials | Allowed bind |\n| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| `auto` | A snapshot of the host Atomic login loaded into `AuthStorage.inMemory(...)` — not the file-backed store, so a refresh cannot write to disk — plus environment keys | Loopback only |\n| `ai-gateway` | `AuthStorage.inMemory()`, `modelsPath: null`, `AI_GATEWAY_API_KEY`; resolved models should be restricted to provider `vercel-ai-gateway`, because other env keys and ambient AWS/GCP credentials would otherwise be picked up | Any |\n| env-key mode (optional, e.g. `direct`) | In-memory credentials with named provider environment keys | Any only if `amazon-bedrock`/`google-vertex` ambient credentials are refused; otherwise loopback |\n\n- Reading the host login snapshot without writes means reading the JSON from `getAgentConfigPaths(\"auth.json\")` yourself. `AuthStorage.create` and `readStoredCredential` go through `withLock`: that makes a directory and a lock file but writes no credentials.\n- Refresh-token rotation that stays in memory may invalidate the host CLI's stored refresh token. Record that as a caveat.\n- `api_key` entries using `!command` run a shell command when resolved. Caveat for `auto`.\n\n### Model resolution (criterion 3)\n\n- Take `turn.model`, falling back to an adapter `settings.model` for tests.\n- Require `provider/id` and call `runtime.getModel(provider, id)`. If it is missing, throw `Atomic does not recognize model ` **before** any request, matching Pi's wording.\n- Never pass `undefined` to `createAgentSession`, because that is exactly the silent fallback.\n- When no model is given at all: fail **(decision)**. The contract suite needs the stub adapter to set a default model.\n\n---\n\n## 4. Testing and verification\n\n### `atomic.contract.test.ts`\n\n- Stub script:\n - `\"tools\"` → a call to `first_host`, then `\"Done.\"`;\n - `\"output\"`/`\"rogue\"` → a call to `RESULT` with `{\"answer\":\"yes\"}`;\n - `\"abort\"` → hold;\n - anything else → text.\n- Adapter setup: `auth` set to an isolated in-memory configuration, plus a registered `stub` provider (`apiKey:\"stub-key\"`, `api:\"openai-completions\"`) and `model: \"stub/stub-model\"`.\n- Cases:\n - `harnessContract(\"atomic\", …, createJustBashNetworkSandboxSession)`;\n - a plain text turn;\n - a host round trip, asserting two requests with `hasPriorToolResult` `[false, true]` and `tool-call`/`tool-result` for `first_host`;\n - one request for a structured turn, with `RESULT` offered;\n - `RESULT` not offered on a plain turn;\n - rogue `RESULT` blocked and hidden;\n - quoted instruction text does not enable `RESULT`;\n - host `AGENTS.md`, `SYSTEM.md`, `APPEND_SYSTEM.md` and skills stay out of the `system` the stub saw, using a temporary cwd or `HOME` and agent dir;\n - an unknown model rejects with zero stub requests;\n - the tool boundary: the active and registered tool names equal the host tools, and the system prompt contains no \"Atomic documentation\" or \"expert coding assistant\" text on a turn without instructions;\n - abort during a pending host tool completes.\n\n### `atomic/adapter.test.ts`\n\nUnit tests in the style of `pi/adapter.test.ts`, using a fake extension API or a fake session:\n\n- result-tool state switching;\n- the stream-suppression helper;\n- `done` rejections: no result, invalid result, error `stopReason`;\n- the reserved result-tool name;\n- the auth-mode and settings mapping.\n\n### `harnesses.test.ts`\n\n- the map keys include `atomic`;\n- missing, unknown and loopback cases for each Atomic mode.\n\n### Gates\n\nRun in this order, recording one `Assistant-verification` line per command:\n\n1. `bun run fix`, then inspect the diff;\n2. `bun test`, with `bun test apps/server/src/harness` first for speed;\n3. `bun run types`;\n4. `bun run ci`.\n\nPast records show about 1,566 passing tests plus 2 PostgreSQL skips as the baseline. E2E is not required, but the Docker job in CI will pick up the larger dependency tree; `docker build` locally is optional.\n\n---\n\n## 5. Documentation to update\n\n- **`docs/hosted-agent.md`:**\n - lines 13-19: the harness list;\n - lines 21-36: ownership — under `atomic`, the owner supplies only the GitHub token and model access comes from `HARNESS_AUTH`;\n - lines 46-67: runtime isolation — builtins off, inert loader, forced system prompt, fail-closed tool check;\n - the code map near line 209.\n- **`docs/self-hosting.md`:**\n - lines 56-122, \"Choose and trust a harness\": the Atomic auth modes and loopback rule, `MODEL` as `provider/id`, the result tool, caveats;\n - line 131 onward: prerequisites;\n - the environment table rows for `MODEL`, `HARNESS`, `HARNESS_AUTH` and `SERVER_HOST`;\n - the sample environment and startup checks.\n- **Also:** `.env.example` lines 5-17, `docs/architecture.md` (lines 6, 36, 56, 112-124, 473-477 name \"Copilot or Pi\"), and `README.md` lines 73-84 and 104.\n- **AGENTS.md** does not list harnesses by name. The \"Harness and Planner\" failure traps (lines 280-299) should gain an Atomic entry: the empty-prompt preamble, abort-signal hangs, and `prompt()` resolving on abort.\n\n**Atomic caveats to document:**\n\n- the silent model fallback, which the adapter guards;\n- the default coding-agent preamble when no prompt is given;\n- the mandatory Intercom unless disabled;\n- the 50 KB tool-result spill to temp files;\n- environment and ambient cloud credentials are read even in isolated mode;\n- `auto` refresh stays in memory and can rotate the host token;\n- no resume across processes;\n- no Copilot-style per-session credit limit, so workers' `maxAiCredits` is ignored;\n- the package size;\n- `typebox` 1.3.7 vs 1.3.27.\n\n## 6. Open items and limits\n\n- I did not verify `tsgo` compatibility of Chopin's `typebox` 1.3.7 schemas with Atomic's `ToolDefinition`, or that `bun install` resolves 0.9.23 cleanly in this workspace.\n- I did not trace the exact OAuth refresh call site that writes `auth.json` in the file-backed mode.\n- I did not observe how HarnessAgent reacts to a `tool-call` emitted from inside `execute` while other parallel calls in the same batch are pending. Atomic schedules \"shared\" tool calls concurrently; add a test with two host calls in one message.\n- I did not test `session.agent.continue()` for `doContinueTurn`.\n- I did not write the research-codebase skill's `research/docs/` file, to keep the repository untouched for the implementation commit. This message is the artifact.\n","editable",false,"branch","documentNavigation","repo","githubnext/chopin","repoId","7d1a8ac3-35b0-4dea-85d4-06a980f3bada","ownerId","org:89615882","site","nexthub","private","admin","settings","maintainer","triage","starred","stars",0,"watchers","watching","pinned","notify","views",[183,184,185,186,187,188,189,190,191,192,193,194,195],"navigation",{"_55":56,"_139":140,"_141":142,"_143":144,"_145":146,"_147":148,"_149":150},"sources",[],"viewer","meta",{"_131":132,"_133":134,"_135":136,"_43":32,"_137":14,"_138":32,"_49":50,"_51":50},"branches",[74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,14,127,128,129,130],"tags",[70,71,72,73],"cloneUrl","https://git.nexthub.sh/githubnext/chopin.git","color-controls-slice-1","color-controls-slice-2","color-controls-slice-3","color-controls-slice-4","Krzysztof-Cieslak-patch-1","Krzysztof-Cieslak-patch-2","Maggie/app-preview-toolkit","Maggie/ci-playwright-install-timeout","Maggie/collaborative-visual-decision","Maggie/design-audit","Maggie/generic-visual-decision-runtime","Maggie/impeccable-chopin-metadata","Maggie/jev-chat-product","Maggie/jev-composed-assessment","Maggie/native-document-layouts","Maggie/openui-composition-product","Maggie/openui-composition-trial","Maggie/planner-visual-authoring","Maggie/planner-visual-requests","Maggie/visual-selection-eval","artifacts/pr-419-live-preview-20261009","automation/pr-maintenance-state","automation/use-effect/callout-disabled-picker-8cf9e49ba5c09471","automation/use-effect/collaboration-options-ref-4e3a5a08a879a5ae","automation/use-effect/room-workspace-effective-access-a57d40866c71bed0","chore/bun-1.4.2","color-controls","color-controls-plan","comments","design-pr-assets","design/archived-decisions-badge","design/channel-route-remount","design/chat-decision-entry","design/conversation-analysis-markers","design/decision-evidence","design/settled-line-icon","dev/integration","diagram-step-controls","feat/liveapp-frontend-pilot","feat/local-experiments","feat/local-launcher-tracer","fix/autolink-mdx-crash","github-pills/2-pills","github-pills/3-hover-card","maggie/app-preview-toolkit","maggie/ci-playwright-install-timeout","maggie/collaborative-visual-decision","maggie/design-audit","maggie/generic-visual-decision-runtime","maggie/impeccable-chopin-metadata","maggie/jev-composed-assessment","maggie/native-document-layouts","maggie/openui-composition-product","maggie/openui-composition-trial","maggie/planner-visual-authoring","maggie/planner-visual-requests","maggie/visual-selection-eval","plain-text-fence-chrome","tokens/09-copy","wireframes/2-renderer","wireframes/3-planner","description","Let's compose rich plans together","owner","githubnext","section","","head","empty","pins",[165,166,167],"documents",{"_160":161,"_162":163},"code",{"_156":157,"_158":159},"automations",{"_153":154,"_155":-5},"delivery",{"_151":50,"_152":-5},"tag","04zvKQ8QOrDUF8TO1Ovz0Zy8_TT","releases","applications","workflows",3,"deployments","commits",1000,"changes",13,"counts",{"_164":163},"total",11,"issue",{"_168":158,"_170":181,"_15":158,"_172":182,"_53":174,"_175":32,"_176":174,"_177":159},{"_168":178,"_170":179,"_15":178,"_172":180,"_53":174,"_175":32,"_176":174,"_177":50},{"_168":169,"_170":171,"_15":169,"_172":173,"_53":174,"_175":32,"_176":174,"_177":163},"id","issues","name","Issues","filters",{},true,"saved","pinnable","count","tasks","Tasks",{},"Changes",{},{"_168":158,"_170":181,"_15":158,"_172":226,"_53":174,"_175":32,"_176":174},{"_168":178,"_170":179,"_15":178,"_172":225,"_53":174,"_175":32,"_176":174},{"_168":169,"_170":171,"_15":169,"_172":224,"_53":174,"_175":32,"_176":174},{"_168":221,"_170":222,"_15":221,"_172":223,"_53":32,"_175":32,"_176":174},{"_168":218,"_170":219,"_15":218,"_172":220,"_53":32,"_175":32,"_176":174},{"_168":153,"_170":216,"_15":145,"_172":217,"_53":32,"_175":32,"_176":174},{"_168":155,"_170":213,"_15":214,"_172":215,"_53":32,"_175":32,"_176":174},{"_168":151,"_170":211,"_15":151,"_172":212,"_53":32,"_175":32,"_176":174},{"_168":207,"_170":208,"_15":209,"_172":210,"_53":32,"_175":32,"_176":174},{"_168":141,"_170":205,"_15":141,"_172":206,"_53":32,"_175":32,"_176":32},{"_168":202,"_170":203,"_15":202,"_172":204,"_53":32,"_175":32,"_176":32},{"_168":199,"_170":200,"_15":199,"_172":201,"_53":32,"_175":32,"_176":32},{"_168":196,"_170":197,"_15":196,"_172":198,"_53":32,"_175":32,"_176":32},"decisions","Decisions",{},"changelog","Changelog",{},"roadmap","Roadmap",{},"Documents",{},"activity","Activity","insights",{},"Releases",{},"Deployments","automations/deployments",{},"Workflows",{},"discussions","Discussions",{},"goals","Goals",{},{},{},{},"groups","user","agents",[],"now",1794434636032,"sidebar","expanded"]