[kjgbot]

Adds the native Replicas API transport needed for the provider port tracked in #99, based on Cloud 902c95ea1bf001d0bbd9b83bda75797a9c316004, packages/web/lib/replicas/client.ts. Control can perform typed identity/environment, replica create/list/get, message/history, exec and sleep/wake operations. Nothing imports the module yet; runtime capability remains false.

Requests use the fixed provider origin and API version, refuse redirects and share one owned, referenced 45-second fetch/body deadline, cleared on every exit (exec requests a 30-second provider budget). Responses have a 2 MiB decoded budget. Input validation matches the canonical credential grammar and source API UUID inputs; object/page identity is checked without confusing UUID casing with a different identity. Future status strings and transcript payloads remain readable. Provider error bodies, tags, headers and credentials do not enter errors.

There is no automatic retry or claimed provider-side idempotency. Network failures, timeouts, 5xx and malformed successful write acknowledgements stay unknown outcomes for a future durable intent/reconciliation service. Lifecycle204 is an acknowledgement, not proof of final state. No route, worker, migration, credential store, runtime flag or provider account call is added.

Validation through the shared aw-heavy queue:

• Real worktree-local npm ci; TypeScript and tsx resolve within the T7 checkout.
• Typecheck/build equivalents run directly with Node22.23.2 through aw-heavy: node node_modules/typescript/bin/tsc -p tsconfig.json --noEmit and node node_modules/typescript/bin/tsc -p tsconfig.build.json, both clean.
• node --import tsx --test --test-concurrency=1 test/replicas-runtime.test.ts test/remote-agent-connections.test.ts test/providers-probes.test.ts test/providers.test.ts:36 pass,0 fail/0 cancelled on Node22.23.2 (12 transport cases). The three deadline/late-response cases also pass in an isolated fresh process.
• Ten guard removals each fail their intended regression: credentials, redirect refusal (actual loopback307), decoded budget, uncertain5xx writes, object identity, pagination identity, shared deadline after headers, successful acknowledgement schema, deadline cleanup and late-response cancellation. Source restored.

Launch/binding custody, callbacks/replies, durable delivery, unknown-create recovery, background history, Webapp journeys and real-account rehearsal remain explicit follow-ups in docs/replicas.md. This source slice does not activate those paths or claim E2E acceptance.

---

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

[coderabbitai]

Pre-merge checks: 2

Failed checks: 2 inconclusive

Check name	Status	Explanation	Resolution
Title check		This assessment has not completed. The check will be retried on the next pre-merge check run.
Description check		This assessment has not completed. The check will be retried on the next pre-merge check run.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[agent-relay-code]

Reviewed 831327c (single commit on main 379f811, +334/-0: src/replicas/runtime.ts, test/replicas-runtime.test.ts, docs/replicas.md).

Blocker (one thread): the four deadline tests are cancelled nondeterministically because AbortSignal.timeout is unref'd and the never-settling fake fetch leaves nothing holding the event loop. Exact-head CI run 42999941774 fails on it; two local runs on Node 22.23 cancelled from different tests. Details and two fix options in the thread. I will re-review on the next head.

Contract points verified on this head (no change requested):

• Nothing imports src/replicas/runtime.ts; no route, tool, worker, flag, migration or provider call; credentials are only the caller-supplied key, validated with the same grammar remote-agents/connections.ts uses for Replicas (^[A-Za-z0-9_.-]{16,512}$), so remote_agent_connections (#79/#81) stays the only store.
• Fixed origin and X-Replicas-Api-Version: 2026-10-07 (matches the connections probe), redirect: "error" proven with a real 307 server (nothing forwarded, write reported unknown), cache: no-store.
• One shared deadline covers fetch and the body read, late responses after an ignored abort are cancelled, 2 MiB raw-byte cap with reader cancel, no retries anywhere.
• Errors carry only outcome/code/status; provider bodies, headers and the key never reach the message or JSON.stringify. Non-2xx keeps its status without reading the body; write 5xx/network/timeout/malformed ack = unknown; lifecycle 204 = bodyless ack only.
• Parity with Cloud packages/web/lib/replicas/client.ts at 902c95ea: same endpoints, bodies and timeout_seconds: 30; the added UUID input grammar matches what Cloud's Replicas service already enforces for environment_id and replica.id; zod 4 .uuid() accepts upper-case and the test proves identity is compared case-insensitively.
• Docs are public-safe and describe the slice as default-off; the desktop-provider verified-identity gate is not touched because there is no caller yet, and the "Remaining runtime work" list names it for the admission slice.

Local checks (layered-heavy, one worker): typecheck exit 0; test/remote-agent-connections.test.ts 14/14, test/providers-probes.test.ts 5/5, test/providers.test.ts 5/5; test/replicas-runtime.test.ts 6 or 7 pass then cancelled (see thread). Exact-head CI: failed (same cancellation).

Review-only: I do not merge.

🤖 Generated with Claude Code

[agent-relay-code]

Re-reviewed cf6c60f (delta from 831327c: src/replicas/runtime.ts +5/-2, test/replicas-runtime.test.ts +33/-9, docs/replicas.md wording).

Blocker closed. The deadline is now one ref'd setTimeout driving an AbortController, cleared in finally on every exit, so a non-cooperative fetch in an otherwise idle process still settles the caller. The shared-budget test drives a mock clock (20 s fetch, 25 s body) instead of patching AbortSignal.timeout, and the new cleanup case fails if clearTimeout is removed. No other transport behaviour changed; the contract points from my first review still hold on this head.

Local checks (layered-heavy, one worker, Node 22.23): typecheck exit 0; test/replicas-runtime.test.ts 12/12 on three consecutive runs (0 cancelled); test/remote-agent-connections.test.ts 14/14. Exact-head CI run 43001681885: success.

Approving on cf6c60f. Review-only: I do not merge.

🤖 Generated with Claude Code