Support standard ACP agents with explicit session guarantees (#1085)

Author: taras

architecture.md

@@ -3562,7 +3562,11 @@ translation lives entirely in `@executablemd/acp`, and no ACP or ACPX type cross
 A provider-native session identity is the identity an agent asserts for its own durable
 session state, distinct from the logical XMD session key and from the ACP/ACPX record
 identity. Only an asserted one crosses a handoff; XMD never infers that a string a
-native CLI would accept is one.
+native CLI would accept is one. A workflow may retain the distinctly tagged
+`acpx.acpSessionId` loading target when no native assertion exists. An asserted
+`acpx.agentSessionId` takes precedence; changed kind or value refuses
+reattachment. The ACP target never becomes `Session.agentSessionId` or a native
+CLI handoff identity.
 
 #### Inert placement
 
@@ -3588,24 +3592,42 @@ constructed.
 
 #### Materialization
 
-Session materialization is the transition that makes a placement's chosen route and its
-backend history resumable. The runtime is the integrity-pinned ACPX 0.21.1 source
-closure. Its released child environment and response metadata coexist with the
-local explicit-acceptance barrier: `promptStarted` acknowledges transport only.
-Promotion and ordinary checkpoints share the released session owner's writer;
-the asserting copy is saved before memory adopts it, and finalization joins
-promotion before saving. ACP-first materialization happens only when the backend
-reports that it accepted the session's first turn; client-native materialization is the
-native launch's existing retained construction. Nothing else promotes a placement — not
-a returning ensure, a first output, a terminal result, a checkpoint token, an error code
-or a diagnostic.
+An adapter declaring `acceptance: "first-turn-acceptance"` requires explicit
+backend acceptance before a new ACP session exposes events. Codex and Claude
+declare it. The integrity-pinned ACPX 0.21.1 runtime consumes the versioned
+`executablemd.session-materialization/v1` marker. Its `promptStarted` is only
+transport acknowledgement; text and `end_turn` prove no stronger acceptance.
+Promotion shares the session owner's writer: the asserting copy is saved before
+memory adopts it, and finalization joins promotion before saving. Host mapping
+commits after that save and before events. Missing acceptance never selects the
+standard path. Client-native materialization keeps the native launch's retained
+construction.
+
+A standard adapter uses ordinary ACP creation without this barrier. The provider
+saves its record and the host retains its identity before configuration,
+permission routing and turn execution. Events report streamed text and the
+actual terminal outcome. Native identity exists only when the peer asserted it;
+an ACP session id alone proves neither native identity nor durable recovery.
 
 #### Established sessions
 
-An established session is a placement whose immutable construction route and durable
-provider or native identity both already exist, and which is therefore validated
-eagerly: reattached, compared against its retained history, and refused when either is
-missing or names another conversation.
+A retained standard record is existing. Cold continuation loads or resumes the
+exact stored ACP session, or refuses before another prompt. Missing load/resume
+support refuses even an unused record. The released `-32603` recreation remains
+only for a provably never-prompted record; used and uncertain conversations are
+never replaced. Failed attempts may retain their user request and lifecycle
+facts while preserving earlier messages, identity and configuration.
+
+A held conversation's canonical history independently establishes use: a turn
+with nonempty agent output, status other than failed, a stop reason, or a native
+identity counts as used. Its private issuance requires existing construction. If
+provider storage is gone, setup refuses before creation or sending, preserves the history and
+keeps the conversation usable. A history containing only failed-before-answer
+turns retains its creation retry. An outcome-less turn still refuses opening
+and is never resent.
+
+Established strong sessions retain their construction route, asserted native
+identity and executable checks. Their continuation never silently downgrades.
 
 #### Instruction placement
 
@@ -3749,7 +3771,9 @@ path; holding a partition grants work, never permission.
 
 The [local-agent example](examples/agent-certification/README.md) uses ordinary
 Agent/Session/Prompt routing and literal-command registration. Private comparisons
-produce categorical capability evidence; expectations confer no execution,
+report basic authentication, streaming and completion separately from acceptance,
+asserted native identity, durability and cleanup. Missing stronger evidence
+leaves demonstrated basic passes intact. Expectations confer no execution,
 identity or certification. Reports finalize after the existing owner joins.
 Native cleanup remains unverified at the production probe/release boundary,
 so cancellation and durable certification remain non-pass. Successfully joined
@@ -3908,20 +3932,21 @@ identity. Cwd and provider placement are never compatibility inputs. What stays
 beside the run on disk is the provider's own session store and one empty working
 directory per session; both are disposable.
 
-The order is placement, then the backend's acceptance of the session's first
-turn, then the provider's canonical, tagged assertion of a durable identity,
-then the mapping commit — and only then is anything that first turn produced
-exposed to the document.
+Strong adapters order placement, explicit first-turn acceptance, asserting
+provider save, tagged native assertion and mapping commit before events.
+Standard adapters order placement, ACP creation and provider save, tagged ACP
+loading-target mapping, configuration and permission routing, then turn and
+events. Native assertion takes precedence when available. Neither path derives
+stronger acceptance from transport acknowledgement or output.
 
 Placement is inert. A `<Session>` says where a session will live and which agent
 it is compatible with; it creates no provider session, contacts no backend and
-writes no row. The session comes into existence when the first subscribed
-`<Prompt>` starts a turn the backend accepts, through the one handle that
-ensured it, and acceptance is reported by the adapter rather than inferred from
-what the turn then produced.
+writes no row. The first subscribed `<Prompt>` constructs it through the handle that ensured
+it. Strong construction additionally waits for the adapter's explicit acceptance
+rather than inferring acceptance from what the turn produced.
 
 Occupancy of a key in the provider's own store is not an assertion: it says
-something is there, not what conversation it is. A record the provider holds for
+something is there, not what conversation it is. A pending strong record the provider holds for
 a first turn nobody accepted is exactly that — occupancy — so it asserts nothing,
 no mapping is committed for it, and the next attempt creates rather than
 resumes.
@@ -9575,7 +9600,7 @@ Status is measured against main.
 | Agent session portability evidence in an XMD artifact | classifies every logical Agent session that contributed a retained Prompt as portable — with ordered provider checkpoint tokens and an opaque Agent session bundle — or as explicitly unavailable, as two content kinds inside the existing version-1 manifest and identity [Invariant](#portable-xmd-artifacts); [Interface and evidence](specs/xmd-artifact-spec.md#25-agent-session-portability-evidence). | specified by `specs/xmd-artifact-spec.md` §2.5; the closed union, both content kinds and the complete post-identity profile verifier are built on the #621 stack, Deno provider only. Provider bundle capture, Agent-aware export, intrinsic Agent-aware inspection and artifact-backed fork are unbuilt |
 | historical authored source | retains an authored durable operation's normalized `SourcePosition` beside its identity, and history parses it or refuses the entry [Invariant](#read-only-lifecycle-inspection); [Interface and evidence](specs/workflow-workspace-spec.md#42-history). | built on the #367 stack |
 | history fork | creates a new run from one compatible checkpoint and retained Workspace root, under a new immutable definition and normalized props [Invariant](#retained-effects-and-history-forks); [Interface and evidence](specs/workflow-workspace-spec.md#11-history-forks). | built on the #368 stack, Deno provider only |
-| workflow Agent session | Uses inert placement and authenticated first-turn mapping under the run-owned no-native-tool profile. [Session mapping](#agent-permissions-and-generated-xmd). | built on the #302 stack, with the explicit ACP-only selection from #561; the portable proof that an adapter honours an empty tool set is tracked by #496 and does not widen the ceiling |
+| workflow Agent session | Uses inert placement and capability-specific identity mapping under the run-owned no-native-tool profile. [Session mapping](#agent-permissions-and-generated-xmd). | built on the #302 stack, with the explicit ACP-only selection from #561; the portable proof that an adapter honours an empty tool set is tracked by #496 and does not widen the ceiling |
 | generated-XMD admission | Preflights and retains one generated fragment under the exact selected identities and forms. [Admission and continuation](#agent-permissions-and-generated-xmd). | built on the #369 stack, continuation basis amended by #589, and the host's contribution narrowed to `Component.generated` by this stack; core owns the mechanics and no host wrapper remains |
 | `<Evaluate>` | Runs untrusted fragment text or paired-produced text under the host's captured generated selection; whole-fragment admission, local data expressions and ordinary rendered output remain distinct from provider permission. [Admission and captured implementations](#agent-permissions-and-generated-xmd). | built on the #302 stack, extended by #369, and narrowed to a name-and-form selection by this stack |
 | generated mutation proposals | Admits filesystem change proposals through the host's generated selection and ordinary component transactions. [Invariant](#agent-permissions-and-generated-xmd); [Interface and evidence](specs/workflow-workspace-spec.md#mutation-proposal-admission). | Built on #369/#567, with persistent directory creation added by #643; legacy Dir grants refuse, and Git/process/credential/external-write classes remain excluded. |

examples/agent-certification/README.md

@@ -24,15 +24,15 @@ has 30 seconds and the outer work deadline has 600 seconds. Expiry ends admissio
 the actual owner still joins. No uncertain turn is retried.
 
 The runner computes setup dependencies before provider work. Continuity,
-separation, reconnect and resume require one accepted A seed. Only selected
+separation, reconnect and resume require one completed A seed. Only selected
 continuity adds A's second turn; separation adds independent B. Cancellation
 needs no marker scenario. Selecting reconnect or resume authorizes their seed
 setup, even when the setup capability rows are unselected.
 
 The checked-in initial document keeps one provider and A Session alive for the
 seed and recall, then tests B. Reconnect opens a new same-process invocation.
 Cancellation owns a separate document; its five-second interval begins at actual
-accepted start and structured cancellation joins that document. Resume uses one
+transport-confirmed start and structured cancellation joins that document. Resume uses one
 separate CLI invocation and ordinary retained A history. Its private comparison
 file is neither provider history nor continuation authority.
 
@@ -55,7 +55,7 @@ Ordinary CI exercises controlled agents without credentials or model calls.
 
 ## Read the report
 
-The current JSON format is closed and unversioned. Each of eleven capability rows
+The current JSON format is closed and unversioned. Each of thirteen capability rows
 records selected and expected flags, an outcome, a fixed reason and bounded facts.
 `pass`, `failure`, `unsupported` and `not_run` are distinct. An absent selector is
 unsupported; a selection the target Session does not apply is a failure. Omitted
@@ -64,7 +64,12 @@ model/effort settings supply no explicit-selection evidence.
 `complete=false` includes missing provenance and selected evidence blocked by
 prerequisites. A measured unsupported capability is a non-pass. Overall success
 requires complete evidence and all selected/expected capabilities passing.
-Durable certification additionally requires continuity, separation, reconnect,
+Acceptance and native identity are separate rows: a standard command can pass
+basic authentication, streaming and completion while acceptance is
+`unsupported/acceptance-unavailable` and identity is unsupported. An actual native
+assertion can pass identity independently. Only a strong-declared adapter's gated
+started event proves acceptance; marker-like output from a literal command does
+not. Durable certification additionally requires acceptance, identity, continuity, separation, reconnect,
 separate-invocation resume and verified cleanup. Native cleanup remains
 `not_run/cleanup-unverified` after a successful owner join; actual observed cleanup
 failure is failure. Correct stop attribution alone cannot pass cancellation.
@@ -90,8 +95,10 @@ xmd run /checkout/examples/agent-certification/orchestrate.md --include /checkou
 
 This is a separate explicitly requested model call, outside the qualification
 suite. Ordinary name/cwd retention is not workflow Session-site identity.
-The existing backend first-turn acceptance barrier remains mandatory; an
-unpatched adapter can be refused even after producing output.
+A literal command uses standard ACP without the private acceptance barrier.
+Sequential prompts share the live Session; later reopening loads the exact ACP
+identity if supported and refuses otherwise. Interrupted requests are never
+automatically resent. Strong-declared adapters retain their acceptance barrier.
 
 Kimi's selected live scope uses `kimi acp`, provider-default model and effort,
 and no retries. A later useful live run requires changed-source review, exact fingerprints and
@@ -100,7 +107,7 @@ retained invocation evidence only; it establishes no capability battery. Gemini
 configuration syntax, not availability or certification evidence. This delivery
 authorizes zero Gemini live calls and installs no agent.
 
-The terminal matrix always lists all eleven capabilities with selected/expected flags,
+The terminal matrix always lists all thirteen capabilities with selected/expected flags,
 outcomes and fixed reasons, plus observed Prompt/cancellation counts and overall
 flags. Failure preserves earlier independent rows and a meaningful nonzero status.
 Private markers, replies, Session identities and child fragments remain local.

examples/agent-certification/observe.ts

@@ -1,3 +1,4 @@
+import { nativeAdapterFor } from "@executablemd/acp";
 import { Agent, Component, configurationOf, sessionOf } from "@executablemd/core";
 import type { AgentPromptEvent } from "@executablemd/core";
 import { scoped, Err, Ok, useScope, spawn, sleep } from "effection";
@@ -7,6 +8,7 @@ import {
   recordConfigurationFailure,
   recordConfigurationSuccess,
   recordTurn,
+  recordSessionEvidence,
 } from "./report.ts";
 import type { Report } from "./report.ts";
 
@@ -39,6 +41,12 @@ export function* observeQualification(
                   recordTurn(report, { accepted, completed, deltas }, !accepted);
                 } else if (event.value.type === "started") {
                   accepted = true;
+                  recordSessionEvidence(
+                    report,
+                    nativeAdapterFor(event.value.agent)?.acceptance === "first-turn-acceptance",
+                    (sessionOf(event.value.session) ?? event.value.session).agentSessionId !==
+                      undefined,
+                  );
                   report.counts.prompts++;
                   recordConfigurationSuccess(report, configurationOf(event.value.session));
                 } else if (event.value.type === "text_delta") {

examples/agent-certification/report.ts

@@ -2,6 +2,8 @@ import type { SessionConfiguration } from "@executablemd/core";
 import { z } from "zod";
 
 export const capability = z.enum([
+  "acceptance",
+  "identity",
   "authentication",
   "streaming",
   "completion",
@@ -33,6 +35,7 @@ const reason = z.enum([
   "agent-unavailable",
   "authentication-refused",
   "acceptance-unavailable",
+  "identity-unavailable",
   "selector-unavailable",
   "configuration-mismatch",
   "marker-mismatch",
@@ -92,6 +95,8 @@ export const reportSchema = z.strictObject({
   }),
   exitState: z.enum(["settled", "failed", "interrupted"]),
   capabilities: z.strictObject({
+    acceptance: rowSchema,
+    identity: rowSchema,
     authentication: rowSchema,
     streaming: rowSchema,
     completion: rowSchema,
@@ -143,6 +148,8 @@ export function initialReport(config: Configuration): Report {
     counts: { prompts: 0, cancellationRequests: 0 },
     exitState: "settled",
     capabilities: {
+      acceptance: initialRow(config, "acceptance"),
+      identity: initialRow(config, "identity"),
       authentication: initialRow(config, "authentication"),
       streaming: initialRow(config, "streaming"),
       completion: initialRow(config, "completion"),
@@ -331,6 +338,8 @@ export function finalizeReport(input: Report): Report {
   report.durableSessionCertified =
     report.selectedCapabilitiesPassed &&
     [
+      report.capabilities.acceptance,
+      report.capabilities.identity,
       report.capabilities.continuity,
       report.capabilities.separation,
       report.capabilities.reconnect,
@@ -339,3 +348,20 @@ export function finalizeReport(input: Report): Report {
     ].every((row) => row.outcome === "pass");
   return reportSchema.parse(report);
 }
+
+export function recordSessionEvidence(report: Report, strong: boolean, native: boolean): void {
+  for (const [name, passed, unavailable] of [
+    ["acceptance", strong, "acceptance-unavailable"],
+    ["identity", native, "identity-unavailable"],
+  ] satisfies [
+    "acceptance" | "identity",
+    boolean,
+    "acceptance-unavailable" | "identity-unavailable",
+  ][]) {
+    const row = report.capabilities[name];
+    if (row.selected && row.outcome !== "pass") {
+      row.outcome = passed ? "pass" : "unsupported";
+      row.reason = passed ? "completed" : unavailable;
+    }
+  }
+}

examples/agent-certification/stage-runner.ts

@@ -66,6 +66,8 @@ function schedule(state: QualificationState) {
   const selected = (name: keyof Report["capabilities"]) => state.report.capabilities[name].selected;
   const seed =
     [
+      "acceptance",
+      "identity",
       "authentication",
       "streaming",
       "completion",

packages/acp/src/acpx-runtime.ts

@@ -2,7 +2,7 @@
  * The ACP runtime this package executes.
  *
  * The released 0.21.1 source closure retains the explicit backend-acceptance
- * barrier required by session creation. Its transport acknowledgement does not
+ * barrier used by strong-declared session creation. Its transport acknowledgement does not
  * establish a durable conversation. See `../vendor/acpx/PROVENANCE.md`.
  */
 // @ts-types="../vendor/acpx/generated/runtime.d.ts"