@meistrari/agent-core 0.2.0-experimental.1 → 0.2.0-experimental.3

package/README.md

@@ -91,3 +91,53 @@ the worker disconnects after persistence but before sending its event ACK.
 The former `ConnectionAuthorityStore.projectAppliedCommand` callback has been removed.
 Move that projection into the durable-event transaction; receiving a command does not prove
 that the provider executed it. See `InMemoryRuntimeControlPlane.record` for the test fixture.
+
+## Consumer compatibility
+
+Remy and agent-api both run these adapters. The compatibility target is the union of their
+requirements; [docs/consumer-capability-matrix.md](docs/consumer-capability-matrix.md) records
+each capability, its owner, its regression coverage, and its validation status.
+
+Consumers must install a compatible Zod peer. Use the same exact Zod version in every
+workspace package that depends on agent-core: isolated package managers can otherwise
+instantiate multiple copies of core and break error-constructor identity. Re-export
+`@meistrari/agent-core/errors` rather than redefining its error classes.
+
+Product behavior is injected, never assumed. Both providers accept `instructions`,
+`sessionContext` (text delivered once with a session's first prompt when it has a web URL) and
+`selectedRepositoryContext` (product text published with the selected-repository instructions).
+Without them, core publishes no product text and, with no selected repository, only removes a
+stale managed instruction file.
+
+`ClaudeProvider.create` defaults preserve API-key sessions:
+
+- `auth`: optional credential proxy (base URL, placeholder token, acquisition, failures).
+  Without it the configured environment's credentials authenticate Claude Code unchanged.
+- `skills` and `desktop`: optional generated workspace-skills plugin and desktop MCP servers.
+- `settingSources`: defaults to `['project', 'local']`; `'sdk-default'` omits the SDK option.
+- `hydratePersistedToolOutput`: defaults to `true`.
+- `disallowedTools`: defaults to the interactive tools a headless run cannot serve.
+
+`CodexProvider.create` accepts ChatGPT, API-key, and Amazon Bedrock authentication,
+`resolveInferenceModel`, `pluginsEnabled`, and `browserAuth` (a per-run Browser Use
+credential socket for ChatGPT authentication; off by default).
+
+`AgentRun.notify` and `AgentRun.compactContext` are optional on the interface; the Claude and
+Codex runs implement both. `sendPrompt` accepts `submissionOrder`, defaulting to `in-order`.
+
+The attachment preparation error constructor is public at
+`@meistrari/agent-core/agents/input-attachment.errors` (also exported by `/agents`).
+
+Core owns provider, mapper, attachment, tool-runner, and lifecycle regression tests,
+including suites transferred from Remy. Remy owns its strict event projection, model admission,
+product instructions/tools, and supervisor integration tests. CI type-checks and tests core
+with Remy's Bun 1.3.10 / Claude SDK 0.3.280 and agent-api's Claude SDK 0.3.257 pins.
+
+`bun run test` runs the portable suites. `bun run test:cli` runs the `*.cli.spec.ts` suites
+against the real bundled Claude Code CLI and a fake Messages API. CI runs them on Linux; the
+process lifecycle spec reads `/proc`, so it fails on macOS. Claude Code rejects its
+bypass-permissions mode as root, so run them as a regular user.
+
+Regenerate the experimental Codex wire types with `bun run generate:codex-protocol`.
+The generator pins Codex 0.156.1 and verifies any `CODEX_EXECUTABLE` override before
+using it. Commit generated files with generator changes; CI checks reproducibility.

package/docs/consumer-capability-matrix.md

@@ -0,0 +1,374 @@
+# Consumer capability matrix
+
+agent-core serves two products: **Remy** (background-coding-agent) and **agent-api** (v5 `events-v1`
+runtime, meistrari/agent-api#653). Its compatibility target is the union of both. A consumer migration
+must not narrow a contract the other relies on, and neither a disabled test nor a removed requirement
+counts as compatibility.
+
+Status legend: **unit** — core regression suite passes on the portable runner (`bun run test`);
+**e2e** — loopback worker/supervisor suites (`bun run test:e2e`); **cli** — the real bundled Claude Code
+CLI suites (`bun run test:cli`, run by CI on Linux); **consumer** — the consumer's own suites against an installed preview package;
+**live** — real providers through the consumer's application or provider smokes against the preview
+package, with sandbox checks on freshly built images (see Live validation). A status without a
+qualifier is pending.
+
+## Current-main delta (2026-09-25)
+
+Remy main `9048c4b8` includes #438's provider-confirmed Claude prompt consumption.
+The September 24 preview does **not** include that capability. Its live evidence below
+remains valid only for the recorded source and image; it does not establish parity with
+this newer main.
+
+Core now retains submitted user-input UUIDs until a main response confirms consumption
+and emits `prompt.turn-correlated` once per input. Cancellation/discard does not erase
+possible consumption evidence; refusal and run shutdown clean it up. Child responses
+cannot bind a main prompt. Existing agent-api accepted user-message events, turn command
+IDs, and usage accounting remain intact. The core wire accepts the additive observation;
+Remy's supervisor consumes it internally and persists its existing command correlation.
+
+Transferred coverage: six upstream regression scenarios and two additional assertions
+in the three real-CLI steer/interruption/failure cases. The core-specific test also
+asserts that accepted user-message identity and turn command correlation survive.
+A wire round-trip test preserves event identity, sequence, input and turn IDs.
+Fresh consumer results and remaining gates are recorded below; full parity is not yet certified.
+
+## Validation record retention
+
+Raw run records are excluded from the current source tree. Reviewers can inspect the
+[archived records at the pre-cleanup revision](https://github.com/meistrari/agent-core/tree/5e46674db57d1687514d9f9e34cac97a8c9d4ced/docs/evidence).
+Those records describe only their recorded revisions and images; the qualified results
+and outstanding requirements below take precedence over broader historical claims.
+
+## Current preview evidence (2026-09-25)
+
+Both consumers installed identical `0.2.0-remy-preview.903281e` bytes.
+The subsequent Codex rejected-steer rollback fix is not included in that artifact. Its regression tests and CI validate the source change; both consumers still need a rebuilt preview and fresh-image validation for this fix.
+Validation results and remaining gates are summarized below. Source is `903281e4a1e6be4db3fcabc3a6a55eb8ed2da5b0`;
+SHA-256 is `b9ac25ba6ddb59dc9afeb67b1d135e626ce4ad1d6fab97614654b57490dca30e`.
+
+| Area | Verified on this artifact | Remaining limitation |
+|---|---|---|
+| Core | 1,279 units, four transport loopbacks, both consumer SDK pins, nine green CI gates | Exact npm publication remains required before merge |
+| Remy | Rebase on main `9048c4b8`; 1,137 scoped units and 814 integrations; lint/typecheck/code-smells; API/worker Docker builds | Local head `d9255986` is not yet pushed: Bun 1.3.10 macOS crashes in unchanged MCP malformed Brotli coverage, also reproduced on baseline main. Hooks remain enabled |
+| Remy live | Fresh image `sbi_01M3CNQ5MPTTRET1SE1RZW3NGQ`; both providers pass settings, same-turn steering, persisted later settings, strict invalid-model admission, compaction and prompt ordering; sessions cancelled and sandboxes absent | Codex also passes attachment/RPC, transport reconnect, supervisor SIGKILL recovery and cleanup on image `sbi_01M3CP8QGJNSKEA77K3Z45J2GK` (same commit). Adoption is blocked before creation by unavailable required repository; Claude attachment/recovery, desktop application, notification and credential refresh remain outstanding |
+| agent-api automated | 3,137 units; 31 storage, 52 API, 185 runtime, 111 worker integrations; opt-in legacy PostgreSQL; typecheck/lint/Linux supervisor/Docker | Initial hook timeout and receipt race failures are recorded; unchanged reruns pass. Existing skips and v5 gaps remain |
+| agent-api live | Both providers pass six application scenarios, Vault details, same-turn steer, cancellation, durable usage observations, replay and pause/resume; both pass 24 worker-takeover assertions | Worker loss does not certify supervisor or sandbox loss. Codex model rollups were empty; model-attributed usage is not verified |
+
+The September 24 video and evidence remain historical. They are not evidence for the newer
+runtime. No production deployment occurred. The product-owned v5 gaps below are unchanged.
+
+## Historical preview evidence (2026-09-24)
+
+The September 24 validation artifact was `0.2.0-remy-preview.23e0b69`, packed from committed source
+`23e0b6922bfa069ecfa6ceda602c2fdd862a2236`. Its SHA-256 is
+`473d8afad586428daa38bee718f8abe0ed164ad356b80e034c3588db709d792b`; Remy and agent-api install
+identical bytes. This documentation update does not replace or repack that artifact.
+
+| Consumer | Source / runtime |
+|---|---|
+| Remy | Rebased HEAD `7d5c548569e524106407e9a37fff81ee687a1ae5` on main `326080e1`; application image runtime `7d5c548569e524106407e9a37fff81ee687a1ae5`; Bun 1.3.10, Claude SDK 0.3.280 / CLI 2.1.280, Codex 0.156.1 |
+| agent-api | Runtime `00c325f09981aac138c181aa065c79447c0dcb57`; recovery coverage/evidence `263c69a35573d90d5a398cdf8a7f6caee87be841`; host Bun 1.3.12, Claude SDK 0.3.257 / CLI 2.1.257; snapshot Codex 0.155.0 and separate host coverage on 0.153.4 |
+
+### Verified Remy checks
+
+| Gate | Evidence / scope |
+|---|---|
+| Lint, typecheck, unit and coverage | [CI on rebased `7d5c5485`](https://github.com/meistrari/background-coding-agent/actions/runs/36027233337): all ten jobs pass. Local lint/typecheck and enabled pre-push hooks pass again: 12,187 coverage tests, 0 failures, 117 existing skips; thresholds retained. Prior enabled pre-commit run: 6,230 units |
+| Strict schemas, shared errors and Remy integration | Consumer projection/configuration and supervisor suites remain enabled; agents integration has 13 passing cases, including the real-CLI Browser Use relay |
+| Prompt preservation | 27 evaluation scenarios rendered for each provider (54 dry-run previews); automated instruction/author-context regression tests pass. Full Remy application conversation-context QA remains pending |
+| Host provider lifecycle | Codex 12/12; Claude 9/9 applicable. These are provider smokes, not API-created Remy sessions |
+| Packaging and image infrastructure | Frozen server, worker, development Web and production Web Docker builds pass. Fresh image build through actual local API/worker passes repository/skills, resident supervisor, desktop/native extension, recovery, streaming, pause/resume and cleanup |
+| Native Browser Use component | Pass in a new sandbox: native navigation and title, exactly one trusted application-auth call, authenticated visit, one credential acquisition, no secret event/transcript exposure, no provider auth file and broker cleanup |
+
+The direct-provider Browser Use runner starts the canonical TLS proxy because a fresh unbound
+supervisor has no session bootstrap to start it. It trusts the generated public CA and retains the
+image's backend URL and native-tool assertions. This fixture does not replace the real supervisor
+bootstrap or establish application-session parity.
+
+### Remy application sessions (post-rebase, real local services)
+
+Real Tela and GitHub OAuth completed; Remy displayed **Ready** with GitHub and organization
+access complete. Local Web/API/worker, PostgreSQL and Redis drove fresh E2B sessions from the
+image recorded below, using the unchanged shared preview.
+
+| Gate | Codex | Claude |
+|---|---|---|
+| Browser-created session, first input, tools, interruption and memory-preserving follow-up | Pass | Pass through Remy's credential proxy |
+| Attachment uploaded through Web and exact content returned | Pass | Pass |
+| Native Browser Use, visible heading and main-agent attribution | Pass | Pass |
+| Strict persisted event schema, unique IDs, increasing sequence and identical replay prefix | 105 events pass | 91 events pass |
+| Official application settings smoke: effort changes, same-turn model steering during a tool, later-turn persistence, invalid admission without a new command | Pass | Pass |
+| Official application compaction smoke: timely start, steer admitted while compacting and applied afterward in a distinct turn | Pass; request result `unknown` as required by contract | Pass; request result `completed` |
+| Session cancellation and cleanup | UI session stopped; both API-smoke sandboxes confirmed not found | UI session stopped; both API-smoke sandboxes confirmed not found |
+
+The 60-second [QA video](https://github.com/user-attachments/assets/ee0334b1-9e6f-4262-b2b0-bce114a7e921)
+is a condensed screenshot montage, not continuous recording. It shows Codex interaction milestones
+and Claude's actual persisted conversation after the run. Screenshot labels and content were
+visually checked; unrelated or mismatched captures were excluded.
+
+| Cohort | Codex session | Claude session |
+|---|---|---|
+| Web QA | `ses_01M3A8CBTAF0ETF5J8XS24DZR0` | `ses_01M3A8S3AQA4DQV6G91FFR5R91` |
+| Settings and steering | `ses_01M3A8GEGFTK5XX1K3SQ8FNTPV` | `ses_01M3A8GEGFRTH05QHN5MCBJKPV` |
+| Compaction ordering | `ses_01M3A8JFP3H4HKFFWM6BV3ZW3G` | `ses_01M3A8JFP76TJKRND792DPS5AJ` |
+
+#### Recovery and repository adoption
+
+All images were built from Remy `7d5c5485`; the supervisor binary checksum differs per build.
+
+| Gate | Codex | Claude |
+|---|---|---|
+| Official direct supervisor smoke: control transport restart, command after reconnect, resident supervisor SIGKILL with cursor/bootstrap preservation, reconnect, cancel and cleanup | Pass; provider-session identity was not independently captured | Not covered by that smoke (Codex only) |
+| Supervisor SIGKILL during an open session, then a follow-up recalling a first-turn marker without tools | Pass, `ses_01M3AAWFGSVM4Z0JX8K7HQK9J6`: reconnect 3 s, provider process replaced, exact marker returned; provider-session identity continuity not independently verified | Pass, `ses_01M3AAWGAYEGCWQCFHYK0H1NN0`: reconnect 4 s, provider processes replaced, exact marker returned; provider-session identity continuity not independently verified |
+| Mid-session repository adoption via `select_repository`, then change, commit and push in the adopted repository | Official smoke passes, `ses_01M3AB4V98V99GW30K2BV0BP8T`: central link, baseline, widened provider binding, clean worktree, pushed head `28be5c72` matches remote | Equivalent check passes, `ses_01M3AB6VV19F5H3094WZ88FVCG`: main-actor tool completed, link ready, exact file, clean worktree, pushed head `02bf216a` matches remote |
+
+Adoption used image `sbi_01M3AB0M0948K4PSC5H0C25RCY` containing both repositories.
+`meistrari/background-coding-agent` was enabled locally only for this run and disabled
+afterwards. All sessions were cancelled and their provider sandboxes confirmed deleted.
+
+The settings smoke's own `restartPersistence: skipped` remains unchanged; supervisor restart is
+covered by the separate checks above.
+
+### Verified agent-api behavior and shared-core requirements
+
+| Gate | Evidence / scope |
+|---|---|
+| Core exact-source CI | [All nine jobs pass at `23e0b69`](https://github.com/meistrari/agent-core/actions/runs/36015938172): full units, lint, typecheck, pinned protocol generation, both legacy/wss-v1 loopbacks, real Claude CLI, Linux executable and both consumers' pinned runtimes |
+| Consumer compilation and unit contracts | Lint, typecheck and 3,137 unit tests pass with the identical preview; existing skips remain reported |
+| Real persistence and sockets | 379 integration tests pass: runtime 185, API 52, worker 111, storage 31. The opt-in legacy lightweight PostgreSQL case passes separately; the main invocation reports that case and its hook as two skips |
+| Provider runtime and recovery | 18/19 cases pass first run, covering both providers' replay, restart, steering, cancellation/continuation, takeover and worker SIGKILL, plus Claude in-flight disconnect and controlled-provider E2B WSS pause/resume. The unchanged Claude web-search/usage rerun passes after an initial model refusal; it remains nondeterministic |
+| Fresh application snapshots | Both providers pass 6/6: same-turn steering, cancellation/continuation, exact Vault tool details, ordered SSE replay, real idle pause/resume with provider memory, and durable usage/cleanup. Claude's separate definitive session flow previously passed 6/6 |
+| Actual application worker crash/takeover | Both providers pass 24 assertions each through API-created sessions. SIGKILL targets the tracked production worker process; a new process acquires generation 2 after natural lease expiry. The original turn completes with the same journal/environment, unique ordered history, usage, SSE replay and provider memory on the next turn. No sandbox or supervisor loss is claimed |
+| Docker and Linux artifacts | Frozen install, API/worker bundles and in-container supervisor compilation pass. The existing floating `oven/bun:1.3` Docker base resolves to 1.3.14, separately from the Bun 1.3.12 application snapshots |
+
+### Current image provenance
+
+| Artifact | Identity |
+|---|---|
+| Remy image / E2B template | `sbi_01M3A79VWRHDQD8K5RW12TG4TF` / `4mp56irdn8jde77oqxpq` |
+| Remy image built at / runtime source | `2026-09-24T17:28:02.950Z` / `7d5c548569e524106407e9a37fff81ee687a1ae5` |
+| Remy baked supervisor SHA-256 | `21ff6141d298adc81e8ca12fae9cc4f96ca0fc5993a33db62c005c3981dcca53` |
+| Remy current-image verification sandbox | `iurxpbd94gibg84qy0wcp`; cleaned up; artifact/runtime, skills, desktop/native-host recovery, streaming and pause/resume pass |
+| agent-api template registration | `6ee42da6-6a71-44bb-b344-72753fa90845` |
+| agent-api snapshot supervisor SHA-256 | `c557e5b633a9594b02d5c08bf90c49a0665b7bff37405256959e793055146c6e` |
+| agent-api Claude / Codex snapshots | `bec37a46-3373-4976-8f3a-dc4dc6532068` / `82bb43df-be17-4c70-826f-2a4ee6619dc7` |
+| agent-api Claude / Codex compatibility sessions | `ea2bde0e-a3bf-4403-9c75-55ef2c132759` / `44ddecde-38d3-4943-a46f-2207858ce287` |
+
+The agent-api suites closed their sessions and removed their disposable sandboxes, snapshots and
+local test database. [Remy #422](https://github.com/meistrari/background-coding-agent/pull/422)
+records the additional Docker checksums, historical artifacts and current QA video.
+
+### Application recovery cohorts
+
+The new recovery tests use the same preview bytes and supervisor checksum above. Complete
+machine-readable evidence, runtime versions and tested-source checksums are committed in
+[agent-api recovery evidence](https://github.com/meistrari/agent-api/blob/263c69a35573d90d5a398cdf8a7f6caee87be841/docs/v5-runtime/evidence/agent-core-preview-recovery.json).
+
+| Gate | Template registration | Claude snapshot / session | Codex snapshot / session |
+|---|---|---|---|
+| Actual idle pause/resume | `3a0a27b2-4338-4755-b8f7-3489476ee780` | `415130b8-d3b7-48f9-afb2-d7ba439b74f8` / `f620bb5d-a2fb-4e66-8319-fca4bcffc074` | `27f1e9d8-a6c6-48e4-abd8-2b12744f0a86` / `4bb9214b-9045-4d06-aee5-441390bbc863` |
+| Actual worker SIGKILL/takeover | `0d004306-cc7b-4ae6-b605-40ee84c036e3` | `9b1ff24d-8872-4160-899f-e845e65b2fe7` / `f9489a2f-6ee1-4f36-a432-9aa61a81ad35` | `efd61864-4402-4c4d-a9fb-308477497c45` / `49bebc4f-9165-4392-9353-242b01d5f2e7` |
+
+Pause follows the worker's real 90-second idle policy; GETs do not wake it. Both providers
+recall the first-turn marker after resume and retain all 49 prior events. Takeover kills
+`apps/agent-worker/src/main.ts`, rather than a component composition, through an opt-in Unix
+socket private to the disposable local stack. Its operator reads ownership evidence from the
+isolated database without mutating leases or clocks. The API, supervisor and providers stay real.
+Both cohorts' sandboxes, snapshots and temporary databases were cleaned up. These checks do not
+close the separate Remy application or product-owned v5 gaps.
+
+### Outstanding gates and observed limitations
+
+- Remaining Remy application gates: notification delivery (the official Greptile notification
+  smoke requires a disposable public Slack channel and posts there; authorization pending),
+  credential refresh and Claude subscription respawn, and live failure cases. Passing automated
+  regression tests is not relabeled as live coverage.
+- User input (`ask_user`) is not a live Remy feature on main: the tool is exported but not
+  registered, its provider smoke cases are commented out, and no application route creates
+  `agent.respond-user-input`. Parity keeps it unregistered; the core mechanics are regression
+  covered only.
+- The former Tela callback/GitHub login blocker is resolved through real OAuth. Local GitHub
+  connection required a temporary loopback API public URL to match the nonce cookie; the public
+  tunnel was restored for sandbox services. This does not permanently solve local callback-host
+  configuration, and future reconnection needs the same alignment.
+- After UI cancellation, the sandbox badge remained Running until reload although the canonical
+  database row was already stopped. Reload displayed Stopped for both sessions. This observed UI
+  delay has not been independently reproduced on unchanged main.
+- Claude host transcript lookup initially failed under macOS's default symlinked/sanitized
+  temporary path. The same path encoder exists in the earlier core preview. Using canonical
+  `TMPDIR=/private/tmp` passes all nine applicable cases; the portability defect is not claimed fixed.
+- Remy's first CI attempt on `9d4f42f2` failed an unchanged baseline log-safety test: substring
+  `101` occurred in the random provider-repository fixture ID. The spec matches main byte for byte;
+  its exact structured log assertion passed. The unchanged rerun passes all jobs. No test or
+  assertion was removed, and the unrelated fixture collision remains a source of nondeterminism.
+- All product-owned v5 gaps listed below remain outstanding. Exact core publication and consumer
+  pin replacement must wait for the application gates; clean installs, contracts, builds and
+  fresh-image smokes must then run again on the published artifact before merge. No production
+  deployment is part of this validation.
+
+## Remy prompt and Claude task parity (`a6d939a2`)
+
+Remy's templated prompt and conversation facts remain product-owned. Core adds optional session
+`instructions` (an exact override of the existing composer) and operation `authorContext` (a trusted,
+product-rendered author block). Omitting either preserves the existing agent-api behavior and public
+entrypoints. Remy still owns its surface, requester, participant, and Slack context schema.
+
+| Requirement | Owner | Regression coverage | Validation |
+|---|---|---|---|
+| Forward explicit instructions unchanged on open and resume | core mechanism; Remy composes | Claude and Codex provider tests; existing default-composer tests retained | unit, consumer; fresh image infrastructure verified; Remy application parity pending |
+| Deliver product conversation context without duplicate author blocks or transcript echoes | Remy renderer; core delivery/echo stripping | both command mappers, both run/provider paths, author-context tests | unit, consumer; Remy application parity pending |
+| Background Bash/housekeeping tasks are not subagents; SendMessage resumes keep child identity and reject stale lifecycle frames | core | transferred Remy #430 Claude mapper regressions | unit, consumer; Remy application parity pending |
+
+Current evidence is recorded above for the same preview in both consumers. Historical image/provider
+results at the end retain their original artifact provenance.
+
+## Current-main rebase (2026-09-24)
+
+Remy main `0471118d` adds per-message model/effort changes and nonblocking Claude manual
+compaction. The compatibility update transfers its runtime and regressions to core while
+retaining agent-api's existing flat `model`/`reasoningEffort` command contract, arbitrary model IDs,
+command correlation, usage accounting, credential sources, and transport entrypoints. Remy's
+provider-specific model admission stays in its compatibility adapter. Experimental Codex
+`step_model_switching` is explicitly enabled by Remy; core's default remains disabled.
+
+The Codex protocol generator now pins 0.156.1. Remy's image/model catalog keeps that product's
+0.156.1 pin; agent-api keeps its own runtime pin. Current and historical live-image evidence is
+separated by artifact below; a passing infrastructure smoke does not prove application parity.
+
+| New requirement | Owner | Regression coverage | Validation |
+|---|---|---|---|
+| Model and effort changes carried by accepted prompts, including same-turn steering and next-turn fallback | core; model admission in Remy | Claude/Codex run regression suites, Remy compatibility tests | unit, cli, consumer; host and official Remy application settings smokes pass |
+| Claude compaction returns on acceptance, reports one correlated outcome, and defers steers while compacting | core | `claude-run.regression.test.ts`, `claude-compaction.cli.spec.ts` | CLI and official Remy application compaction/steer-order checks pass |
+| Provider setting controls precede input; failed changes retain accepted settings | core | run regressions and `claude-settings-change.cli.spec.ts` | new CLI checks passed |
+| Opt-in Codex active-turn switching and pinned protocol | core configuration, product chooses runtime | command mapper/provider regressions, generated 0.156.1 protocol | generation CI and host and official Remy Codex application settings smokes pass |
+
+## Provider execution
+
+| Capability | Owner | Implementation | Regression coverage | Status |
+|---|---|---|---|---|
+| Open and resume, input-free startup | core | `claude-provider.ts`, `codex-provider.ts` | `claude-provider.test.ts`, `codex-provider.test.ts` | unit, live (agent-api open/resume both providers; Remy open/input-free startup and supervisor-SIGKILL resume with provider memory, both providers) |
+| Claude initialize handshake before the run is published (30 s deadline) | core | `claude-provider.ts` | `claude-provider.test.ts` | unit |
+| Per-command model selection at idle boundaries | core | `claude-run.ts` (control channel), `codex-run.ts` (`turn/start`), `model-rebinding-run.ts` (Bedrock) | `claude-run.test.ts`, `codex-run.test.ts`, `model-rebinding-run.test.ts` | unit |
+| Steering within the active turn | core | Claude mapper supersession (`mapSteerLifecycle`), Codex `turn/steer` | `claude-run.test.ts` steer matrix, `claude-run.regression.test.ts`, `codex-run.regression.test.ts` | unit, live (agent-api both providers, E2B) |
+| Targeted interruption; stale targets never affect a replacement turn | core | `claude-run.ts`, `codex-run.ts` | `claude-run.test.ts`, `codex-run.regression.test.ts` | unit, live (agent-api and Remy interrupt/continue, both providers; stale-target regression is unit-covered) |
+| Input attachments (native and filesystem fallback) | core | `input-attachment-preparation.ts`, command mappers | `input-attachment-preparation.test.ts`, command mapper tests | unit, live (Remy text upload both providers; other routing/failure cases remain automated) |
+| Runtime tools and actor restrictions | core, tools product-owned | `agent-tool*.ts`, tool mappers | `agent-tool*.test.ts`, tool mapper tests | unit, live (agent-api and Remy shell/native tools, both providers) |
+| Skills (catalog, workspace plugin, Codex roots) | core | `claude-skill-catalog.ts`, `claude-workspace-skills.ts`, `codex-skill-*.ts` | `claude-skill-catalog.test.ts`, `claude-workspace-skills.spec.ts`, `codex-provider.test.ts` | unit |
+| Codex ChatGPT, API-key and Bedrock credentials; refresh | core, credential sources product-owned | `codex-provider.ts`, `codex-run-auth.ts`, `codex-bedrock-session-auth.ts` | `codex-provider.auth.test.ts`, `codex-run-auth.test.ts`, `codex-bedrock-session-auth.test.ts`, `subscription-token-refresh.test.ts` | unit, live (ChatGPT only) |
+| Claude credentials: environment API key or credential proxy | core, proxy product-owned | `claude-provider.ts` (`auth` optional) | `claude-provider.test.ts` | unit, live (agent-api API key and Remy credential proxy; refresh/respawn remains unit-covered) |
+
+## Remy capabilities
+
+| Capability | Owner | Implementation | Regression coverage | Status |
+|---|---|---|---|---|
+| Notifications joined to the active turn (`AgentRun.notify`) | core | `claude-steered-notifications.ts`, Codex notification turns | `claude-run.regression.test.ts`, `claude-steered-notifications.spec.ts`, `codex-run.regression.test.ts`, `claude-notifications.cli.spec.ts` | unit, cli, live (Remy Codex) |
+| Manual context compaction (`AgentRun.compactContext`) | core | synthetic `/compact` (Claude), Codex compaction | `claude-run.regression.test.ts`, `codex-run.regression.test.ts` | unit, live (official Remy compaction/steer ordering, both providers) |
+| Submission ordering (`in-order` default, `bypass` steer) | core policy, Remy selects | `sendPrompt` options | `claude-run.regression.test.ts`, `codex-run.regression.test.ts` | unit, live (official Remy compaction/steer ordering, both providers) |
+| Mid-session repository adoption | core | `addWorkspaceRepositoryRoot`, selected-repository bridges | `codex-provider.test.ts`, `claude-selected-repository-instructions.spec.ts` | unit, live (Remy both providers: adoption, commit and push) |
+| Session context delivered once with the first prompt | core mechanism, text injected | `session-context.ts` (`sessionContext` composer) | `claude-run.regression.test.ts`, `codex-provider.test.ts` | unit |
+| Claude proxy authentication and subscription-type respawn | core mechanism, proxy product-owned | `claude-provider.ts` | `claude-provider.test.ts` | unit |
+| Desktop and Browser Use (Claude MCP servers, Codex credential broker) | core mechanism, servers and turn-metadata relay product-owned | `claude-desktop.ts`, `codex-browser-auth-broker.ts` (`browserAuth` opt-in) | `codex-browser-auth-broker*.spec.ts`, `claude-browser-turn-metadata.{spec,test}.ts`; Remy's `claude-browser-*.cli.spec.ts` run the real CLI through Remy's image relay | unit, consumer, live (Remy both providers) |
+| Native-tool actor attribution | core | `claude-tool-mapper.ts`, `nativeToolActorBridge` | `claude-tool-mapper.test.ts` | unit, live (Remy both providers; main attribution) |
+| Claude process lifecycle (stop waits for CLI exit) | core | `claude-code-process.ts` | `claude-code-process.spec.ts`, `claude-process-lifecycle.cli.spec.ts` (reads `/proc`, Linux only) | unit, cli |
+| Strict event projection and model admission | Remy | Remy compatibility adapter | Remy `core-agent-provider.test.ts` | consumer, live (Remy both providers: strict 196-event projection and invalid model admission) |
+
+## agent-api transport
+
+| Capability | Owner | Implementation | Regression coverage | Status |
+|---|---|---|---|---|
+| Empty `wss-v1` bootstrap; legacy bootstrap with command 1 | core | `supervisor-protocol/bootstrap.ts` | `supervisor/persistence/wss-v1.test.ts` | unit, e2e |
+| Priority and out-of-order delivery, sequence gaps, individual receipts and rejections | core mechanism, selection product-owned | `SessionCommandPump`, journal | `e2e/wss-v1-loopback.test.ts` | e2e |
+| Journal identity pinned at first readiness | core | `runtime.state.sourceId`, `ConnectionAuthorityStore` | `e2e/wss-v1-loopback.test.ts` | e2e |
+| Ownership fencing, reconnect, ACK only after persistence | core | worker-runtime-client, frame processor | `e2e/loopback.test.ts`, `e2e/wss-v1-loopback.test.ts` | e2e, live (agent-api takeover, worker SIGKILL, in-flight disconnect) |
+
+## agent-api extensibility
+
+| Capability | Owner | Implementation | Regression coverage | Status |
+|---|---|---|---|---|
+| Product profiles, command extensions, product events and RPC | core wire, semantics product-owned | `supervisor-protocol/*` | `protocol-superset.test.ts` | unit |
+| Any non-empty model id on the wire; known catalogs for presentation only | core | `protocol/agent-model.ts` | `agent-presentation.test.ts` | unit |
+| Workspace preparation hooks and payload references | core | `WorkspacePreparer`, `agent-overflow.ts` | supervisor suites | unit |
+| Independent service templates | core validation, templates product-owned | `template-onboarding.ts` | `template-onboarding.test.ts` | unit |
+| Instructions, credentials and CLI paths injected per product | core | provider configs | `claude-provider.test.ts`, `codex-provider.auth.test.ts` | unit |
+
+## agent-api event semantics
+
+| Capability | Owner | Implementation | Regression coverage | Status |
+|---|---|---|---|---|
+| Accepted input as a user message carrying its `commandId`; `turn.started.commandId` | core | `claude-run.ts`, Codex prompt correlation | `claude-run.test.ts`, `codex-run.regression.test.ts` | unit, live (agent-api both providers) |
+| Negative Claude receipts settle a pending prompt as delivery unknown | core | `claude-run.ts` | `claude-run.test.ts`, `claude-run.regression.test.ts` | unit |
+| Usage accounting observations (cumulative or increment, per model) | core | event mappers | `usage-accounting.test.ts`, `claude-usage.test.ts` | unit, live (agent-api both providers, including Codex supervisor restart) |
+| Exact tool output, command correlation in durable steps | core | `steps/projector.ts`, event mappers | `steps/projector.test.ts` | unit, live (agent-api Vault detail, both providers) |
+| Bounded payloads with Vault-backed details | core mechanism, upload product-owned | `agent-overflow.ts`, projector upload | `steps/projector.test.ts` | unit, live (agent-api) |
+| Durable replay after reconnect | core | supervisor store, projector journal | `supervisor-store.test.ts`, e2e | unit, e2e, live (agent-api SSE and journal replay, E2B pause and resume) |
+
+## Deliberate behavior changes
+
+Where the two products behaved differently, the adapters now follow one rule. Each change is
+covered by the listed test and must be validated live by the affected consumer.
+
+| Change | Affects | Reason | Coverage |
+|---|---|---|---|
+| A `cancelled` or `discarded` receipt for an unacknowledged Claude prompt rejects it as delivery unknown | Remy (previously waited for run close) | An open session could otherwise hold the command pump indefinitely | `claude-run.test.ts`, `claude-run.regression.test.ts` |
+| An interrupt targeting a stale turn is a no-op | Remy (Codex previously sent it) | A targeted control must never affect a replacement turn | `codex-run.regression.test.ts` |
+| Codex command output is exact, including trailing whitespace | Remy (previously trimmed) | Durable steps preserve provider output byte for byte | `codex-event-mapper.test.ts`, `steps/projector.test.ts` |
+| Event schemas strip unknown fields instead of rejecting them | agent-api | Adopted from Remy's trust-boundary validation | `agent-protocol.test.ts` |
+| New events: `context.updated`, `tool.output.updated`, `context.compaction.request.completed`; Claude `session.skills.updated` | agent-api (durable `agent.*` frames) | Additive observations from Remy's runtime | `agent-event-wrapper.ts`, mapper tests |
+| Claude open waits for the CLI initialize handshake | agent-api | A published or prewarmed run owns a started CLI; startup failures surface at open | `claude-provider.test.ts` |
+| Claude Code runs through `ClaudeCodeProcess`; stop resolves after the CLI exits | agent-api | A resume never overlaps a stopped CLI | `claude-code-process.spec.ts` |
+| Claude native work tools (TaskCreate, TaskGet, TaskList, TaskUpdate) are allowed | agent-api | Claude Code 2.1.263+ omits them from headless preset sessions otherwise | `claude-provider.test.ts` |
+| Steered-notification hooks are registered on every Claude run | agent-api | Required by `notify`; no-ops without pending notifications | `claude-steered-notifications.spec.ts` |
+| Codex threads start with the reasoning effort and summary every turn sends | agent-api | Lets the first turn reuse Codex's prewarmed request | `codex-provider.test.ts` |
+| Codex usage accounting uses one cumulative scope per run (`<threadId>:<run>`), summing each call's `last` usage | agent-api (scope was the thread id with Codex's `total`) | Codex 0.153.4 restarts a resumed thread's `total` at zero while 0.155.0 restores it, so a thread-wide checkpoint undercounted or regressed after a supervisor restart | `usage-accounting.test.ts`; agent-api `real-provider-postgres --provider codex --restart-supervisor` |
+| Codex requires the provider-set main thread id to attribute events | internal | Child-thread events are buffered until spawn correlation | `codex-event-mapper.test.ts` |
+
+## Outstanding product-owned v5 gaps
+
+These are documented in agent-api's `docs/v5-runtime/specification-decisions.md` and are not
+closed by this work: declared inputs and handshake (C08/P06, D04), result selection (D06),
+detached async rendezvous (D07), lightweight journal identity and recovery (D08), billing and
+webhooks (D11/P17, including step-detail upload grants), cost reconciliation (V11), and
+capacity/retention policy (D12). Core's resident supervisor does not yet expose `notify` or
+`compact-context` wire commands; neither consumer requires them from core today. Codex usage observations carry no
+model. Model attribution remains a `pending_model` concern (P17); the September 25 Codex
+application checks observed durable usage events but empty rollups, so they do not verify
+model-attributed totals. Claude observations roll up per model.
+
+## Historical live validation — preview `37f5dfa`
+
+Preview `0.2.0-remy-preview.37f5dfa` (SHA-256 `35a3ea04…`), Codex 0.153.4 on the host and 0.155.0 in
+agent-api images, Claude Code 2.1.280 (Remy) and 2.1.257 (agent-api images).
+
+- **agent-api**, `validate/agent-core-remy-preview`: 19 real-provider smokes (replay, in-flight
+  disconnect, supervisor restart, steer, cancel, cancel then continue, takeover, worker SIGKILL, web
+  search usage, E2B pause and resume) and, on freshly published E2B snapshots, the definitive session
+  flow plus `e2e/v5-core-preview-validation.spec.ts` for a Claude and a Codex agent.
+- **Remy**, meistrari/background-coding-agent#422: 11/11 Codex provider cases and 8/8 applicable
+  Claude provider cases on the host. The fresh-image server/worker smoke also passed on
+  2026-09-24 UTC: pinned CLIs, baked configuration and skills, repository clone, resident
+  supervisor, lazy desktop/stream activation, frozen-browser and native-host recovery, and
+  memory-preserving pause/resume. Its exact verification sandbox was killed afterward.
+  Application sessions for both providers and the Browser Use smoke remain pending.
+
+### Remy fresh-image evidence
+
+| Artifact | Identity |
+|---|---|
+| Consumer source | `ffb9bc9974ac0dff38b7860371c60b245749ca02` |
+| Core preview SHA-256 | `35a3ea045f3ab4547dd01c1c3adaa60de91c77824706f9476c28fbefd2ba7556` |
+| Supervisor SHA-256 | `23b57d2a9063977bbe1dfe8fb476d1a81bbfeae8865ad39733b9739c8ec60637` |
+| Remy image | `sbi_01M38C8125A7WDAP7VSZQ9R0SF` |
+| E2B template / build | `p82p3l92hfjmn4oxmir9` / `6be26d70-8274-4b6f-a726-9edd9f0e87ea` |
+| Verification sandbox (cleaned up) | `ikkkqszp8n6zw4e19cd4y` |
+| Runtime versions | Bun 1.3.10; Codex 0.153.4; Claude Code 2.1.280 |
+
+The local GitHub app is now installed and the test repository enabled. The first application
+smoke stopped at session admission (HTTP 409): the human's GitHub authorization is still
+disconnected. Completing it through the local Web UI is blocked by Tela Auth rejecting
+`http://localhost:3010/auth/callback`; the default port 3000 is occupied by another project.
+These are environment prerequisites, not passing provider-session evidence.
+
+The initial image build also exposed a pre-existing worktree/Compose issue: `/app/.git` was a
+file pointing at an unavailable macOS path. An ignored local Compose override mounts the real
+common Git directory and this worktree's HEAD read-only, allowing the canonical worker to
+compile with the actual consumer SHA. No provider or application contract was changed.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.2.0-experimental.1",
+    "version": "0.2.0-experimental.3",
     "packageManager": "bun@1.3.12",
     "description": "Shared contracts and runtime modules for Tela coding-agent sandboxes: agent protocol, supervisor wire protocol, resident supervisor, worker runtime client, and Claude/Codex harness adapters.",
     "license": "UNLICENSED",
@@ -52,7 +52,10 @@
         "./supervisor": "./src/supervisor/index.ts",
         "./supervisor/provider-factory": "./src/supervisor/provider-factory.ts",
         "./testing": "./src/testing/index.ts",
-        "./worker-runtime-client": "./src/worker-runtime-client/index.ts"
+        "./worker-runtime-client": "./src/worker-runtime-client/index.ts",
+        "./agents/input-attachment.errors": "./src/agents/input-attachment.errors.ts",
+        "./claude/command-mapper": "./src/agents/claude/claude-command-mapper.ts",
+        "./codex/command-mapper": "./src/agents/codex/codex-command-mapper.ts"
     },
     "bin": {
         "agent-core-supervisor": "bin/supervisor.ts"
@@ -64,17 +67,20 @@
         "lint": "eslint .",
         "lint:fix": "eslint . --fix",
         "typecheck": "tsc --noEmit",
-        "test": "bun test src/",
+        "test": "bun test src/ --path-ignore-patterns='**/*.cli.spec.ts'",
         "test:e2e": "bun test --pass-with-no-tests e2e/",
         "build:supervisor": "bun scripts/build-supervisor-executable.ts",
         "provenance": "bun scripts/write-provenance.ts",
-        "build": "bun scripts/write-provenance.ts"
+        "build": "bun scripts/write-provenance.ts",
+        "generate:codex-protocol": "bun scripts/generate-codex-protocol.ts",
+        "test:cli": "bun test cli.spec"
     },
     "peerDependencies": {
-        "@anthropic-ai/claude-agent-sdk": ">=0.3.207 <0.4.0",
+        "@anthropic-ai/claude-agent-sdk": ">=0.3.257 <0.4.0",
         "@anthropic-ai/sdk": "^0.93.0",
         "@modelcontextprotocol/sdk": "^1.29.0",
-        "pg": "^8.16.3"
+        "pg": "^8.16.3",
+        "zod": "^4.1.12"
     },
     "peerDependenciesMeta": {
         "@anthropic-ai/claude-agent-sdk": {
@@ -93,18 +99,19 @@
     "dependencies": {
         "jose": "6.2.11",
         "pino": "^9.7.0",
-        "ulid": "3.0.2",
-        "zod": "^4.1.12"
+        "ulid": "3.0.2"
     },
     "devDependencies": {
         "@antfu/eslint-config": "4.16.2",
-        "@anthropic-ai/claude-agent-sdk": "0.3.224",
+        "@anthropic-ai/claude-agent-sdk": "0.3.280",
         "@anthropic-ai/sdk": "0.93.0",
         "@modelcontextprotocol/sdk": "1.29.0",
         "@types/bun": "1.3.12",
         "@types/pg": "8.23.1",
         "eslint": "^9.30.0",
+        "json-schema-to-typescript": "15.0.4",
         "pg": "8.23.0",
-        "typescript": "5.9.3"
+        "typescript": "5.9.3",
+        "zod": "4.1.13"
     }
 }