Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -252,11 +252,13 @@ A storage lease belongs to the scope that opened it. The provider owns the under

The workflow executor holds the run’s exclusive executor lock through execution, cleanup, and committed lifecycle settlement. Connection serialization alone does not permit another executor to advance the run.

Native Agent ownership separately protects a logical provider conversation. Construction provenance and executable compatibility do not replace live ownership; release requires evidence that the owner’s work can no longer act.
Native Agent ownership separately protects a logical provider conversation. Construction provenance and executable metadata do not replace live ownership; release requires evidence that the owner’s work can no longer act.

A conversation continues quietly on the executable the current environment selects. The provider must positively confirm the retained native identity before work that requires it. A missing or different assertion refuses without creating a replacement conversation. Executable version and digest do not decide admission. Existing routes and journal history remain unchanged; normal continuation creates no new version-history record.

A released operating-system lock proves a previous local workflow executor is gone. It does not, by itself, prove native Agent backend quiescence or clear an unresolved ownership record.

The [Workflow Workspace specification](specs/workflow-workspace-spec.md) owns executor and storage lifetimes. The [Native Agent session launch specification](specs/native-agent-session-launch-spec.md) owns handoff, build compatibility, and release proof.
The [Workflow Workspace specification](specs/workflow-workspace-spec.md) owns executor and storage lifetimes. The [Native Agent session launch specification](specs/native-agent-session-launch-spec.md) owns handoff, identity confirmation, and release proof; the [ACP client specification](specs/acp-client-spec.md#availability) owns executable selection and continuation.

### Cancellation and attachment

Expand Down
7 changes: 3 additions & 4 deletions packages/acp/src/ClaudeNativeLaunch.test.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,11 +244,9 @@ nothing was said before the first.

The question named neither the sentence nor any file. The answer carried the
opening sentence of `.agents/implementor.md` exactly, which only the prepared
layer could have supplied.
layer could have supplied. The Claude version, platform and architecture the
verdict reports are evidence of what ran, never a condition of passing.

<AssertEquals actual={proof.claudeVersion} expected={"2.1.241 (Claude Code)"} />
<AssertEquals actual={proof.platform} expected={"darwin"} />
<AssertEquals actual={proof.architecture} expected={"arm64"} />
<Assert expr={proof.openingSentenceExact} />

## The resumed session is the same conversation
Expand Down Expand Up @@ -280,6 +278,7 @@ on screen.

## The two commands are the documented ones

Only native UI invocations count here. Availability and ACP subprocesses may also run.
Creation names the session and hands over a private instruction file. Resuming
hands over nothing — a `--session-id` there would be a second conversation, not
a continuation.
Expand Down
48 changes: 24 additions & 24 deletions packages/acp/src/ClaudeNativeToAcp.test.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ would fail this document.
"preparedTextInArgv", "preparedTextInEnvironment",
"modelTurns", "conversationInputByteCount",
"consentInputBytes", "consentSurfaces", "exitControlBytes",
"adapterCommand", "inheritedAgentMarkersRemoved",
"adapterIdentity", "inheritedAgentMarkersRemoved",
"markerStored", "markerRecovered", "markerInReportedEvidence",
"answerSurface", "outcome",
"route", "journal", "arrangement", "observed", "absent",
Expand Down Expand Up @@ -125,7 +125,7 @@ would fail this document.
"consentInputBytes": { "type": "string" },
"consentSurfaces": { "type": "array", "items": { "type": "string" } },
"exitControlBytes": { "type": "string" },
"adapterCommand": { "type": "string" },
"adapterIdentity": { "type": "string" },
"inheritedAgentMarkersRemoved": { "type": "integer" },
"markerStored": { "type": "boolean" },
"markerRecovered": { "type": "boolean" },
Expand Down Expand Up @@ -183,11 +183,10 @@ would fail this document.
"observed": {
"type": "object",
"additionalProperties": false,
"required": ["version", "digestPresent", "matchesRoute"],
"required": ["version", "digestPresent"],
"properties": {
"version": { "type": "string" },
"digestPresent": { "type": "boolean" },
"matchesRoute": { "type": "boolean" }
"digestPresent": { "type": "boolean" }
}
},
"absent": {
Expand Down Expand Up @@ -276,8 +275,6 @@ memory — never in the instruction file, the argument vector, the environment,
session key, or the document the ACP turn ran. The answer produced it behind a
prefix that appears in no earlier turn.

<AssertEquals actual={proof.platform} expected={"darwin"} />
<AssertEquals actual={proof.architecture} expected={"arm64"} />
<Assert expr={proof.markerStored} />
<AssertFalse expr={proof.acpDocumentCarriesMarker} />
<Assert expr={proof.markerRecovered} />
Expand All @@ -297,49 +294,52 @@ the launch, and nothing after it named a second.
<AssertFalse expr={proof.freshFallback} />
<AssertFalse expr={proof.routeConverted} />

## One conversation, one build, four accounts
## One conversation, four accounts

The route, the journal, the ACP client's own arrangement and the identity the
launch reported all name the same conversation — and the build this run would
use is the build the route retained.
launch reported all name the same conversation. A fresh route records how the
session was constructed and nothing about the executable that ran it, so
neither the route nor the journal carries a build. The platform, architecture,
Claude version and digest the verdict reports are evidence of what ran, never
a condition of passing.

<AssertEquals actual={proof.route.schema} expected={"session-route.v2"} />
<AssertEquals actual={proof.route.schema} expected={"session-route.v1"} />
<AssertEquals actual={proof.route.kind} expected={"client-native"} />
<AssertEquals actual={proof.route.provenance} expected={"client-allocated"} />
<AssertEquals actual={proof.route.launcher} expected={"claude"} />
<AssertEquals actual={proof.route.nativeSessionId} expected={proof.nativeSessionId} />
<Assert expr={proof.route.instructionsDigestPresent} />
<Assert expr={proof.route.buildDigestPresent} />
<AssertEquals actual={proof.route.buildVersion} expected={proof.claudeVersion} />
<AssertFalse expr={proof.route.buildDigestPresent} />
<AssertEquals actual={proof.route.buildVersion} expected={""} />
<AssertEquals actual={proof.journal.provider} expected={"acpx"} />
<AssertEquals actual={proof.journal.agent} expected={"claude"} />
<AssertEquals actual={proof.journal.launcher} expected={"claude"} />
<AssertEquals actual={proof.journal.provenance} expected={"client-allocated"} />
<AssertEquals actual={proof.journal.nativeSessionId} expected={proof.nativeSessionId} />
<AssertEquals actual={proof.journal.buildVersion} expected={proof.route.buildVersion} />
<AssertEquals actual={proof.journal.buildVersion} expected={""} />
<AssertEquals actual={proof.journal.firstPhases} expected={["prepared", "detached", "exited"]} />
<AssertEquals actual={proof.journal.failureClasses} expected={[]} />
<Assert expr={proof.arrangement.present} />
<AssertEquals actual={proof.arrangement.agentSessionId} expected={proof.nativeSessionId} />
<Assert expr={proof.observed.digestPresent} />
<Assert expr={proof.observed.matchesRoute} />

## The adapter the attachment was proven against

ACPX resolves adapters through a semver range of its own. A capability that
depends on how an adapter handles resume identity cannot be left to that range,
so this binding names one — and the name is live, reaching no durable record.
The binary's carried adapter supplies both the command used to address the route
and this path-free snapshot identity. The native UI count covers create and
resume invocations. Availability probes and ACP subprocesses have separate argv.

<AssertEquals
actual={proof.adapterCommand}
expected={"npx -y @agentclientprotocol/claude-agent-acp@0.70.0"}
actual={proof.adapterIdentity}
expected={"xmd-embedded-adapter:claude:@agentclientprotocol/claude-agent-acp@0.70.0+7bb5296c72adb4268f8dc9ed484b53fd2aa6b1b16ab30868d7b8dfb63501257e"}
/>

## An identity nobody ever had is refused before a turn

The independent case. A bound route naming a fresh random conversation, in a
directory of its own, with no provider arrangement beside it: the prompt refuses
rather than starting an empty conversation and answering from it.
The fixture publishes a historical bound V2 route for a fresh random conversation
in its own directory. It reads the record back under the command and key the
binary will use before attempting the prompt. The provider must refuse that
exact missing conversation. ACPX saves each user submission to this key before
sending a model request, so the independent arrangement counts attempted turns.

<Assert expr={proof.absent.ran} />
<AssertEquals actual={proof.absent.failureClass} expected={"identity-unavailable"} />
Expand Down
37 changes: 26 additions & 11 deletions packages/acp/src/ClaudeZeroTurnExit.test.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,13 @@
session and hands you Claude's own interactive UI for it. This document asks the
smallest question about that session's identity: if you leave without saying
anything, does running the same command again put you back in *that*
conversation — or does Claude at least refuse that exact session out loud?
conversation — or is that exact session refused out loud?

XMD confirms the identity it allocated over ACP once the native process has
exited, and again before it resumes one. If Claude kept nothing of a session
nobody spoke in, that confirmation is where the refusal happens: the first
launch records `identity-unavailable`, and the second refuses before starting
any Claude at all.

Silently landing somewhere else is the failure this is looking for. A session
picker, a replacement identity, or a fresh conversation wearing the old name
Expand Down Expand Up @@ -232,9 +238,9 @@ One session identity was chosen by the adapter before any process existed. The
first command created that conversation; the second resumed it. Nothing
translated an ACP or ACPX value into it, and no second candidate was allocated.

<AssertEquals actual={proof.claudeVersion} expected={"2.1.241 (Claude Code)"} />
<AssertEquals actual={proof.platform} expected={"darwin"} />
<AssertEquals actual={proof.architecture} expected={"arm64"} />
The Claude version, platform and architecture the verdict reports are evidence
of what ran, never a condition of passing.

<AssertEquals actual={proof.identityProvenance} expected={"client-allocated"} />
<AssertEquals actual={proof.identityAllocations} expected={1} />
<AssertFalse expr={proof.substitutedIdentity} />
Expand All @@ -251,7 +257,7 @@ section and no other role's.
<Assert expr={proof.implementorMarkerRendered} />
<AssertEquals actual={proof.siblingMarkersRendered} expected={0} />
<AssertEquals actual={proof.firstInvocationChildren} expected={1} />
<AssertEquals actual={proof.secondInvocationChildren} expected={1} />
<Assert expr={proof.secondInvocationChildren === 1 || (proof.secondInvocationChildren === 0 && proof.outcome === "no-session")} />

## Every key sent was terminal control

Expand All @@ -263,17 +269,23 @@ Ctrl-D bytes: one to ask the prompt whether it is there, one to leave.
expr={proof.reentryExitControlBytes === "0404" || proof.outcome === "no-session"}
/>

## The two commands are the documented ones
## The commands are the documented ones

Creation names the session and hands over a private instruction file. Re-entry
resumes that same name and hands over nothing — a `--session-id` there would be
a second conversation, not a continuation.
a second conversation, not a continuation. XMD can refuse during preflight before launching the second UI. A refusal from the UI itself still requires the exact resume command.

<AssertEquals
actual={proof.firstCommand}
expected={["claude", "--session-id", proof.nativeSessionId, "--system-prompt-file", "<private-file>"]}
/>
<If condition={proof.secondInvocationChildren === 1}>
<AssertEquals actual={proof.secondCommand} expected={["claude", "--resume", proof.nativeSessionId]} />
<Else>
<AssertEquals actual={proof.secondCommand} expected={[]} />
<Assert expr={proof.journal.failureClasses.includes("identity-unavailable")} />
</Else>
</If>

## The instruction layer travelled privately

Expand All @@ -300,14 +312,17 @@ process on the machine can read from.
<AssertEquals actual={proof.journal.provenance} expected={"client-allocated"} />
<AssertEquals actual={proof.journal.nativeSessionId} expected={proof.nativeSessionId} />
<Assert expr={proof.journal.instructionsDigestPresent} />
<AssertEquals actual={proof.journal.sessionState} expected={["created", "resumed"]} />
<AssertEquals actual={proof.journal.firstPhases} expected={["prepared", "detached", "exited"]} />
<If condition={proof.outcome === "same-identity"}>
<AssertEquals actual={proof.journal.sessionState} expected={["created", "resumed"]} />
<AssertEquals actual={proof.journal.failureClasses} expected={[]} />
</If>

## Only two answers are accepted

Re-entry reached the identity it was given, or Claude refused that exact
identity and XMD failed closed. A picker, a replacement identity or a fresh
conversation is none of those.
Re-entry reached the identity it was given, or that exact identity was refused —
by XMD's own confirmation or by Claude — and XMD failed closed. A picker, a
replacement identity or a fresh conversation is none of those.

<Assert expr={proof.outcome === "same-identity" || proof.outcome === "no-session"} />

Expand Down
48 changes: 22 additions & 26 deletions packages/acp/src/CodexNativeLaunch.test.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,14 @@ rejoins the same conversation over ACP — from an authored document that has
never seen the marker — and asks for it. Recovering it is what makes the native
UI and the ACP session one conversation rather than two wearing the same name.

Getting there costs one turn nobody asked for. Codex CLI 0.153.2 does not write
a conversation anywhere `codex resume` can find it until a turn has completed in
it, so XMD spends exactly one of its own first: `codex-materialization.v1`,
whose only job is to make the conversation openable. That the operator can then
leave without ever speaking — and come back without buying a second one — is the
subject of `CodexZeroNativeTurnExit.test.md`, so that question can be corrected
without respending the three turns this document is authorized to spend.
Getting there costs one turn nobody asked for. Codex CLI, as first proven at
0.153.2, does not write a conversation anywhere `codex resume` can find it
until a turn has completed in it, so XMD spends exactly one of its own first:
`codex-materialization.v1`, whose only job is to make the conversation
openable. That the operator can then leave without ever speaking — and come
back without buying a second one — is the subject of
`CodexZeroNativeTurnExit.test.md`, so that question can be corrected without
respending the three turns this document is authorized to spend.

## What this costs, and what it touches

Expand All @@ -38,8 +39,10 @@ authored content.
It is opt-in twice over. Without `XMD_CODEX_NATIVE_PROOF=1` the fixture refuses
before starting any Codex process; without a separate
`XMD_CODEX_MODEL_TURNS_AUTHORIZED=3` it refuses before spending a turn. It also
refuses on a machine outside the frozen compatibility tuple below, because the
finding this feature rests on is a fact about one Codex build.
refuses when the carried Codex adapter is not the one named below, because that
adapter is part of XMD's own integration. The installed Codex release, its
digest and the host platform are recorded as evidence of what ran and never
decide whether it passes.

Everything sent besides those three turns is terminal control: Codex's own
directory trust dialog is answered at most once with the choice it pre-selects,
Expand Down Expand Up @@ -278,24 +281,17 @@ that one did.

<Assert expr={proof.ran} />

## The frozen compatibility point
## The carried adapter, and what else ran

The materialization turn exists because of a fact about one Codex build. This
records which one, so a later build that stopped needing it — or started needing
something else — cannot pass as this one.
The adapter is XMD's own integration, so this run names it exactly. The Codex
release, its digest, the platform and the architecture are reported beside it
as evidence of what this run exercised; none is compared with an earlier run.

<AssertEquals actual={proof.platform} expected={"darwin"} />
<AssertEquals actual={proof.architecture} expected={"arm64"} />
<AssertEquals actual={proof.codexVersion} expected={"codex-cli 0.153.2"} />
<AssertEquals
actual={proof.codexDigest}
expected={"195ace4100a634a9df39147f493e730e666b5bd87795f3c9f3251d8542400424"}
/>
<AssertEquals actual={proof.adapterPackage} expected={"@agentclientprotocol/codex-acp"} />
<AssertEquals actual={proof.adapterVersion} expected={"1.6.2"} />
<AssertEquals
actual={proof.adapterDigest}
expected={"3ee22bc6b1649d02fcef80b352516f395fe774e63b459193195a41c42930dd8b"}
expected={"a3f699537970127972635b4596aef40ab8a4caa25a9028861d9ee07bf6c4b1a1"}
/>
<Assert expr={proof.compatibilityTupleFrozen} />

Expand Down Expand Up @@ -399,16 +395,16 @@ inconvenient.

## Route and journal agree

The route names the construction and the Codex build the tuple above froze, and
nothing else: an ACP-first route deliberately records no conversation identity,
launcher or instruction layer, so those are read from the journal instead. A
The route names the construction and nothing else: a fresh ACP-first route
records no conversation identity, launcher, instruction layer or executable
build, so the identity and instructions are read from the journal instead. A
route that had converted to anything but `acp-first` would mean the launch
stopped being the one this document describes.

<AssertEquals actual={proof.route.kind} expected={"acp-first"} />
<AssertEquals actual={proof.route.provider} expected={"acpx"} />
<AssertEquals actual={proof.route.buildVersion} expected={proof.codexVersion} />
<AssertEquals actual={proof.route.buildDigest} expected={proof.codexDigest} />
<AssertEquals actual={proof.route.buildVersion} expected={""} />
<AssertEquals actual={proof.route.buildDigest} expected={""} />
<AssertEquals actual={proof.journal.provider} expected={"acpx"} />
<AssertEquals actual={proof.journal.agent} expected={"codex"} />
<AssertEquals actual={proof.journal.launcher} expected={"codex"} />
Expand Down
Loading
Loading