Skip to content

Commit 8c2cd59

Browse files
committed
🔀 Overlay the embedded adapters on ACPX's registry instead of replacing it
The workflow profile installed a registry closed to codex and claude, so a run that named any other agent was refused. Carrying a patched Codex adapter is not a reason to withdraw Gemini, and the closure also restated every non-embedded agent's retained identity — a compatibility break in return for nothing. The registry is now an overlay. codex and claude resolve to their exact embedded snapshots and never fall through: a snapshot that cannot verify, materialize or launch refuses the agent rather than becoming the published adapter that names no turn. Every other agent resolves through the same ACPX registry, to the same command, as before. Preparation is conditional on the same predicate, so a non-embedded selection reaches no capture, verification, materialization or fallback path. The retained compatibility identity follows it: the stable provider/package/version/snapshot identity for an embedded provider, and the resolved command — unchanged from the base branch — for everything else. Evidence is Gemini, an ACPX built-in this build carries nothing for. WAL13 runs it to completion, retains its ordinary Prompt events, retains zero checkpoints and proves the embedded machinery was never asked about it. WAL14 replays it whole and resumes it interrupted, restoring the stored Prompt without asking again. WAL15 pins its retained identity to `gemini --acp`. WAL16 refuses a broken codex snapshot before any Prompt and leaves Gemini working under the same broken snapshots. AM3/AM3b are the registry itself. Spec §8.6 now describes a qualified Codex/Claude override rather than a closed registry, and says that a missing checkpoint changes nothing about a successful Prompt.
1 parent ec56dd4 commit 8c2cd59

7 files changed

Lines changed: 468 additions & 53 deletions

File tree

‎packages/acp/embedded-adapters.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,9 @@
1818

1919
export {
2020
AdapterSnapshotError,
21+
carriesEmbeddedAdapter,
2122
createEmbeddedAdapters,
2223
embeddedAdapterIdentities,
23-
embeddedAdapterRegistry,
24+
overlaidAdapterRegistry,
2425
} from "./src/adapter-snapshots.ts";
2526
export type { EmbeddedAdapters, EmbeddedAdapterSnapshot } from "./src/adapter-snapshots.ts";

‎packages/acp/src/adapter-snapshots.ts‎

Lines changed: 37 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@
7979
import { ensureDir, exists, readTextFile, rm, writeTextFile } from "@effectionx/fs";
8080
import { readdir, readFile, rename as renamePath, rm as rmPath, writeFile } from "node:fs/promises";
8181
import { exec, useQuietProcessOutput } from "@executablemd/runtime";
82+
import { createAgentRegistry } from "./acpx-runtime.ts";
8283
import type { AcpAgentRegistry } from "./acpx-runtime.ts";
8384
import { ensure, type Operation, scoped, sleep } from "effection";
8485
import { Buffer } from "node:buffer";
@@ -662,25 +663,49 @@ export function createEmbeddedAdapters(
662663
}
663664

664665
/**
665-
* An agent registry serving only this host's embedded adapters.
666+
* ACPX's own agent registry, with this host's embedded adapters over the top.
666667
*
667-
* Deliberately closed. ACPX's own registry knows a dozen agent names and
668-
* resolves each to whatever `npx` would fetch; a run that fell through to one
669-
* of those would be talking to an adapter that names no turn, and would find
670-
* out by retaining nothing. An agent this host carries no snapshot for is
671-
* refused here instead.
668+
* An overlay, not a replacement. The two providers this build carries a patched
669+
* snapshot for resolve to that snapshot, because only it names the turn it just
670+
* completed. Every other agent resolves exactly as it did before any of this
671+
* existed — ACPX's registry, ACPX's command — because nothing about carrying a
672+
* Codex adapter is a reason to stop a run from using Gemini.
672673
*
673-
* `resolve` answers without touching the disk. The command is the snapshot's
674-
* digest, so it is settled by the bytes this build carries — which is what lets
675-
* a session key be derived from it before anything has been materialized.
674+
* A closed registry was the wrong shape for the same reason. It made "this
675+
* build has no Codex snapshot problem to solve for Gemini" into "this build
676+
* refuses Gemini", which is a much larger claim than the one being made, and it
677+
* would have changed the retained identity of agents the checkpoint work has
678+
* nothing to say about.
679+
*
680+
* The overlay is *qualified*: an embedded provider never falls through. A
681+
* snapshot that cannot be verified or materialized refuses the agent, and does
682+
* not quietly become the published adapter that names no turn — finding out by
683+
* retaining nothing is the failure this exists to remove.
684+
*
685+
* `resolve` answers without touching the disk on both paths. The embedded
686+
* command is the snapshot's digest beneath a known root, so it is settled by
687+
* the bytes this build carries, which is what lets a session key be derived
688+
* before anything has been materialized.
676689
*/
677-
export function embeddedAdapterRegistry(adapters: EmbeddedAdapters): AcpAgentRegistry {
690+
export function overlaidAdapterRegistry(
691+
adapters: EmbeddedAdapters,
692+
baseline: AcpAgentRegistry = createAgentRegistry(),
693+
): AcpAgentRegistry {
694+
const embedded = new Set(adapters.providers);
678695
return {
679-
resolve: (agentName: string) => adapters.command(agentName),
680-
list: () => [...adapters.providers],
696+
resolve: (agentName: string) =>
697+
embedded.has(agentName) ? adapters.command(agentName) : baseline.resolve(agentName),
698+
// Both, deduplicated: the embedded providers are ACPX names this build
699+
// resolves differently, not names it adds.
700+
list: () => [...new Set([...baseline.list(), ...adapters.providers])],
681701
};
682702
}
683703

704+
/** Whether this build carries an embedded adapter for `agentName`. */
705+
export function carriesEmbeddedAdapter(adapters: EmbeddedAdapters, agentName: string): boolean {
706+
return adapters.providers.includes(agentName);
707+
}
708+
684709
/** Every embedded snapshot's identity, for provenance checks and diagnostics. */
685710
export function embeddedAdapterIdentities(): readonly EmbeddedAdapterSnapshot[] {
686711
return EMBEDDED_ADAPTER_SNAPSHOTS;

‎packages/acp/tests/adapter-materialization.test.ts‎

Lines changed: 61 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,13 @@ import { mkdtemp, readdir } from "node:fs/promises";
2020
import { tmpdir } from "node:os";
2121
import { join } from "node:path";
2222
import process from "node:process";
23+
import { createAgentRegistry } from "../src/acpx-runtime.ts";
24+
import type { EmbeddedAdapters } from "../src/adapter-snapshots.ts";
2325
import {
2426
AdapterSnapshotError,
2527
createEmbeddedAdapters,
2628
embeddedAdapterIdentities,
27-
embeddedAdapterRegistry,
29+
overlaidAdapterRegistry,
2830
} from "../src/adapter-snapshots.ts";
2931
import { cp, readFile, writeFile } from "node:fs/promises";
3032
import { hostname } from "node:os";
@@ -119,18 +121,65 @@ describe("Tier AM — embedded adapter materialization", () => {
119121
expect(materialized).toBeInstanceOf(AdapterSnapshotError);
120122
});
121123

122-
it("AM3: the closed registry lists exactly the embedded providers", function* () {
124+
it("AM3: the overlay resolves the two embedded providers and delegates the rest", function* () {
123125
const root = yield* useRoot();
124-
const registry = embeddedAdapterRegistry(createEmbeddedAdapters(root));
125-
126-
expect(registry.list().sort()).toEqual(["claude", "codex"]);
127-
// Not a fall-through to ACPX's own registry, which knows a dozen names and
128-
// resolves each to whatever `npx` would fetch.
129-
expect(
130-
yield* refusal(function* () {
131-
return registry.resolve("openclaw");
132-
}),
133-
).toBeInstanceOf(AdapterSnapshotError);
126+
const adapters = createEmbeddedAdapters(root);
127+
const baseline = createAgentRegistry();
128+
const registry = overlaidAdapterRegistry(adapters, baseline);
129+
130+
// The two this build patches resolve to the snapshot, because only it names
131+
// the turn a Prompt completed.
132+
for (const provider of ["codex", "claude"]) {
133+
expect(registry.resolve(provider)).toBe(adapters.command(provider));
134+
expect(registry.resolve(provider)).not.toBe(baseline.resolve(provider));
135+
}
136+
137+
// Everything else is ACPX's, byte for byte. Carrying a Codex adapter is not
138+
// a reason for a run to stop being able to use Gemini, and a registry that
139+
// refused one would be making a far larger claim than this work needs.
140+
expect(registry.resolve("gemini")).toBe(baseline.resolve("gemini"));
141+
// Names, not a new namespace: every built-in is still listed, and the
142+
// embedded two are among them rather than instead of them.
143+
const listed = registry.list();
144+
for (const name of baseline.list()) {
145+
expect(listed).toContain(name);
146+
}
147+
expect(listed).toContain("codex");
148+
expect(listed).toContain("claude");
149+
expect(listed.length).toBe(new Set(listed).size);
150+
});
151+
152+
it("AM3b: a broken embedded snapshot refuses rather than falling back", function* () {
153+
const root = yield* useRoot();
154+
const baseline = createAgentRegistry();
155+
// Carries the two names, and cannot produce either. Exactly the state a
156+
// corrupt or unverifiable snapshot leaves: the override still owns the
157+
// agent, so the only honest answer is a refusal.
158+
const broken: EmbeddedAdapters = {
159+
providers: ["codex", "claude"],
160+
identity: (provider) => `xmd-embedded-adapter:${provider}:[email protected]`,
161+
executablePath: () => {
162+
throw new AdapterSnapshotError("this snapshot cannot be verified");
163+
},
164+
command: () => {
165+
throw new AdapterSnapshotError("this snapshot cannot be verified");
166+
},
167+
// deno-lint-ignore require-yield
168+
*materialize(): Operation<void> {
169+
throw new AdapterSnapshotError("this snapshot cannot be verified");
170+
},
171+
};
172+
const registry = overlaidAdapterRegistry(broken, baseline);
173+
174+
// Refused, and not silently answered with the published adapter — which
175+
// would complete every Prompt, retain nothing, and say nothing about why.
176+
const refused = yield* refusal(function* () {
177+
return registry.resolve("codex");
178+
});
179+
expect(refused).toBeInstanceOf(AdapterSnapshotError);
180+
// And the refusal is local to the override: a non-embedded agent still
181+
// resolves, so one broken snapshot does not take the registry with it.
182+
expect(registry.resolve("gemini")).toBe(baseline.resolve("gemini"));
134183
});
135184

136185
it("AM4: an abandoned tree is replaced rather than adopted or wedged", function* () {

‎packages/cli/src/workflow-agent.ts‎

Lines changed: 39 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,9 @@ import type {
7777
// A separate entrypoint because the embedded adapters are temporary (#636) and
7878
// must not become part of the package's stable surface.
7979
import {
80+
carriesEmbeddedAdapter,
8081
createEmbeddedAdapters,
81-
embeddedAdapterRegistry,
82+
overlaidAdapterRegistry,
8283
} from "@executablemd/acp/embedded-adapters";
8384
import type { EmbeddedAdapters } from "@executablemd/acp/embedded-adapters";
8485
import {
@@ -252,17 +253,30 @@ function sessionPolicy(
252253
/**
253254
* What this run retains about which agent a session belongs to.
254255
*
255-
* The adapter's stable identity — provider, package, version and snapshot
256-
* digest — never the command that launches it. That command names a directory
257-
* beneath this host's materialization root, and retaining it would make where
258-
* this machine put a file part of the session's identity and of every artifact
259-
* sealed from the run: the same snapshot on another host would compare as a
260-
* different agent.
256+
* For an embedded provider: the adapter's stable identity — provider,
257+
* package, version and snapshot digest — never the command that launches it.
258+
* That command names a directory beneath this host's materialization root,
259+
* and retaining it would make where this machine put a file part of the
260+
* session's identity and of every artifact sealed from the run, so the same
261+
* snapshot on another host would compare as a different agent.
262+
*
263+
* For every other agent: the resolved command, exactly as this profile
264+
* retained it before any adapter was embedded. Its identity is not this
265+
* host's to restate, and rewriting it would make sessions retained by an
266+
* earlier run of the same workflow compare as a different agent — a
267+
* compatibility break in return for nothing, since a Gemini session has no
268+
* snapshot for the alternative to name.
261269
*/
262-
function identityOf(context: { agentName: string; sessionIdentity: string }) {
270+
function identityOf(context: {
271+
agentName: string;
272+
agentCommand: string;
273+
sessionIdentity: string;
274+
}) {
263275
return {
264276
provider: PROVIDER,
265-
agentCommand: adapters.identity(context.agentName),
277+
agentCommand: carriesEmbeddedAdapter(adapters, context.agentName)
278+
? adapters.identity(context.agentName)
279+
: context.agentCommand,
266280
sessionIdentity: context.sessionIdentity,
267281
};
268282
}
@@ -291,6 +305,7 @@ function sessionPolicy(
291305
}
292306
const identity = identityOf({
293307
agentName: context.agentName,
308+
agentCommand: context.agentCommand,
294309
sessionIdentity: context.sessionIdentity,
295310
});
296311
const sessionKey = agentSessionKey(identity);
@@ -381,14 +396,25 @@ export function* useWorkflowAgentProfile(options: WorkflowAgentProfileOptions):
381396

382397
const factory: AgentProviderFactory = createAcpxProvider({
383398
sessionStore: store,
384-
// Closed, and this host's own: an agent it carries no snapshot for is
385-
// refused rather than resolved to whatever `npx` would fetch.
386-
agentRegistry: embeddedAdapterRegistry(adapters),
399+
// ACPX's own registry with this build's two patched snapshots over the top.
400+
// Codex and Claude resolve to the adapter that names its turns; every other
401+
// agent resolves to the command it always did.
402+
agentRegistry: overlaidAdapterRegistry(adapters),
387403
// At the first point the provider would run that command, which is its
388404
// availability probe — earlier than a `<Session>` placement, and earlier
389405
// than any turn. A snapshot that cannot prove itself refuses the agent here
390406
// rather than surfacing later as an adapter that would not start.
391-
prepareAgent: (agentName) => adapters.materialize(agentName),
407+
//
408+
// Asked only about an agent this build actually carries. An agent ACPX
409+
// resolves is already a command on this machine, so there is nothing to put
410+
// on disk for it, and reaching into the snapshots to find that out would
411+
// make every run pay for a mechanism that has nothing to say about it.
412+
*prepareAgent(agentName): Operation<void> {
413+
if (!carriesEmbeddedAdapter(adapters, agentName)) {
414+
return;
415+
}
416+
yield* adapters.materialize(agentName);
417+
},
392418
...(options.createRuntime === undefined ? {} : { createRuntime: options.createRuntime }),
393419
// ACP-only, stated rather than inherited. A workflow session belongs to a
394420
// run, not to this machine: it is named by a row in the run's own database,
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# A run whose agent this build carries no snapshot for
2+
3+
Everything about carrying a patched Codex adapter is about Codex. This document
4+
asks Gemini two questions, which is a thing a workflow was always allowed to do,
5+
and the point of it is that carrying an adapter for somebody else changed
6+
nothing here.
7+
8+
Two Prompts rather than one, so that an interrupted attempt leaves a committed
9+
turn behind it and the resume has something to restore rather than something to
10+
repeat.
11+
12+
<Agent name="gemini">
13+
<Session name="review">
14+
15+
<Prompt as="first">
16+
Reply with one sentence about the release.
17+
</Prompt>
18+
19+
<Prompt as="second">
20+
Given what you just said, reply with one more sentence.
21+
</Prompt>
22+
23+
</Session>
24+
</Agent>
25+
26+
<Output>
27+
The agent said:
28+
29+
{first}
30+
31+
{second}
32+
</Output>

0 commit comments

Comments
 (0)