Skip to content

Commit 23b2587

Browse files
authored
✨ Make a fresh <Session> a pending placement (#648) (#656)
* ✨ Make a fresh <Session> a pending placement (#648) A `<Session>` used to establish. It took ownership, published `acp-first`, built a runtime, created a backend session and asserted an identity for it — all before anything had asked for a conversation. That is why a `<Session.Launch>` nested inside a `<Session>` could not work: the enclosing element had already settled how the session was constructed, so the launch inside it was refused for naming a session that had just been created out from under it. It is also why a run could retain a conversation nothing ever had: `ensureSession()` returning is not a backend accepting a turn. A fresh `<Session>` now places. It validates the agent and where the session will live, pins the exact `Session` value, and does nothing else — no route, no runtime, no ensure, no record, no turn. The first consuming operation chooses the immutable construction route: a first subscribed `<Prompt>` publishes `acp-first` and constructs through ACP, and a first `<Session.Launch>` constructs client-native. An established placement keeps its eager validation exactly as before. An ACP-first session becomes a conversation when the backend accepts its first turn, and only the adapter can say when that happened. Both embedded adapters now report it on one exact versioned key, `executablemd.session-materialization/v1`, as `{"state":"accepted"}` in the update metadata of a standard ACP `session_info_update` — Codex when `turn/start` returns a turn, Claude when the SDK reports that exact queued command dispatched. Nothing else promotes a session: not a returning ensure, a first text delta, a synthesized `started`, a terminal result, a checkpoint token, an error code or a diagnostic. The vendored ACPX runtime gains a third behavioral patch to carry it. An ensure asking for deferred materialization persists a provisional record — the key is occupied, the serialized `agentSessionId` is absent — and holds the identity `session/new` returned privately, so the record is occupancy rather than an assertion. The acceptance marker is consumed rather than published: it reaches no event stream, no conversation and no checkpoint. On acceptance the runtime promotes a copy of the record, saves it through the store's own atomic operation, adopts it in memory only after that save returns, and then resolves `AcpRuntimeTurn.materialized`. Promotion is serialized against live-checkpoint writes, so a promotion that failed is not later overwritten by finalization as though it had succeeded. The durable order is therefore route, provisional non-asserting record, backend acceptance, asserting record, host mapping, and only then the events the turn produced. A first turn nobody accepted leaves the route standing, the record non-asserting, no workflow row, no identity on the value the document holds, and that same pending value ready to retry — which creates fresh backend state rather than resuming the arrangement no backend took. Acceptance, not successful terminal text, is the boundary: a turn that failed after being accepted leaves the session established. The pre-commit window is unchanged and now sits one step later: the provider's assertion is saved before the host is asked to retain anything, so an interruption between them leaves exactly one canonical assertion for the next attachment to reconcile and commit. Provider provenance is now the exact object rather than the key inside it. A structural copy, a value from another provider copy or a torn-down scope, and a value used with a different resolved agent are each refused before any provider work — and the value a `<Session>` pinned is the one every nested `<Prompt>` receives. A first prompt enters its session's FIFO before any route, ensure or runtime for that placement, and re-reads the placement once the queue grants, so two concurrent first prompts perform one backend creation and the waiter continues what its predecessor established. Both adapter snapshots are rebuilt from new commits on their existing upstream pull request branches, and the test agent reports acceptance too — an agent that never sent the marker would leave every session it serves unestablished. * 🐛 Serialize concurrent prompts, and report acceptance from every turn Two settled contracts the previous commit broke. **Concurrent prompts on one advertised session.** Ownership was acquired before the session's queue, and the coordinator refuses contention rather than queueing it. That is right for a native UI holding the session for hours and wrong for the next turn of a conversation this provider is already having: a second subscription got `AgentSessionBusy` instead of running as the second turn. The queue comes first now, and each prompt takes and gives back ownership in its turn. What still refuses is what genuinely competes. Another provider state, another process and another kind of operation share no queue with this one, so they all still meet the coordinator. A launch no longer takes the queue at all: a launch is only ever performed for an advertised agent, so its acquisition is already that session's exclusion, and holding the queue as well is what would have put a prompt behind a native UI — the thing NL12 exists to prevent. It refuses instead, and the coordinator is what refuses it. `NO12` is the regression: an advertised adapter and a real coordinator, the first turn held open while the second subscribes, proving two sequential grants both granted, one materializing ensure, two turns in submission order, and one retained identity in the provider's own store. It fails on the previous ordering. **Codex commands that start a turn.** The marker was published where a prompt reaches the App Server through `turn/start` and nowhere else, so `/review`, `/goal <objective>` and `/goal resume` accepted turns and reported nothing. All three funnel through the adapter's command turn-started callback, which now reports it and awaits publication; a command that starts no turn never reaches it and still reports none. The upstream commit is `fadc0a690e96c276629be8a34be980d35e821637` on the same pull-request branch, with its own regressions, and the tarball, generated snapshot, manifest and provenance are refreshed from it. `EA8` proves it against the real embedded adapter: the fake App Server answers `review/start` on a review thread of its own, and the adapter reports exactly one acceptance for the session the command was sent on. It fails on the previous tarball. Neither fix adds an inference anywhere. Acceptance is still one exact marker from the adapter, and the provider still waits for it. * ✅ Order NO12 on barriers rather than on durations Two of NO12's claims were timed rather than observed. It polled the fake until a turn appeared, and then waited a fixed five milliseconds before asserting that the second subscription had not run — which is a claim about what has *not* happened, and a duration can only ever make that likely. Three signals replace them. The fake runtime says when a turn has actually started, which is what "the first turn is in flight" means. The second task says when it is about to subscribe, immediately after constructing the stream, which chose nothing and started nothing. And the provider's own agent resolution says when that subscription is running — the point after which the only thing ahead of it is the session's queue. Only then does it assert the held state, and it asserts one more thing than before: one ensure. A second subscription past the queue would have ensured, so counting them is what makes "waiting" different from "not started yet". `startedTurns(count)` on the fake runtime is the first of those signals, built the way the workflow fake's already is. Nothing else changes; the released sequence is asserted exactly as it was. * ✅ Signal NO12 from the placement the provider is about to queue behind The "this subscription is running" barrier was the provider's agent resolution, which is several suspensions short of the queue: between it and `turns.slot` lies the whole outer placement. So the held-state assertions were made while the second subscription might still have been resolving where its session lives, and what they observed was as much "not there yet" as "waiting". The signal is the completion of that placement now, which is the step immediately before the provider enters the queue. It comes from `withSessionRoute` — the provider's own dependency, supplied the way a host supplies it — rather than from anything added to production for a test to hold on to. `withSessionRoute` wraps two things per subscription, and only placements *complete* while the first turn is held: the first subscription's second call encloses its whole turn, which is still open. So the second completion is the second subscription's placement, and the test asserts that identification rather than leaving it to be inferred. The wrapper suspends once before it signals, so nothing here rests on placement being synchronous — a scheduler that hands control back at a yield has already done so by the time the waiting task is released, and the signalling task runs on into the queue before that task resumes. Restoring ownership-before-queue fails this in both shapes, with the forced suspension and without it, and fails it on the claim that matters: the second subscription comes back `AgentSessionBusy` instead of `undefined`. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent a6e8bb7 commit 23b2587

36 files changed

Lines changed: 7130 additions & 5048 deletions

‎architecture.md‎

Lines changed: 22 additions & 6 deletions
Large diffs are not rendered by default.

‎packages/acp/mod.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ export type {
6767
AcpRuntimeEnsureInput,
6868
AcpRuntimeEvent,
6969
AcpRuntimeHandle,
70+
AcpRuntimeMaterialization,
7071
AcpRuntimeOptions,
7172
AcpRuntimeTurn,
7273
AcpRuntimeTurnInput,

‎packages/acp/src/provider.ts‎

Lines changed: 349 additions & 41 deletions
Large diffs are not rendered by default.

‎packages/acp/src/session-key.ts‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,19 @@ export interface SessionCandidate {
3131
cwd: string;
3232
}
3333

34+
/**
35+
* One candidate, and whether a session already lives there.
36+
*
37+
* `pending` means this key names where a session will be, and nothing has
38+
* constructed one yet. `established` means a durable record already stands
39+
* behind it — including a record written before deferred materialization
40+
* existed, which carries no marker and asserted its identity when it was
41+
* created.
42+
*/
43+
export interface SessionPlacement extends SessionCandidate {
44+
state: "pending" | "established";
45+
}
46+
3447
function digest(value: string): string {
3548
return createHash("sha256").update(value).digest("hex").slice(0, 16);
3649
}
@@ -82,13 +95,17 @@ export function* sessionCandidates(
8295
* Select where a session lives: the nearest candidate whose ACPX record
8396
* exists for the same agent command and directory, or the exact
8497
* contextual cwd when none does.
98+
*
99+
* A record still marked pending is occupancy rather than a conversation — its
100+
* first turn was never accepted — so the placement it answers with is pending
101+
* too, and the next operation constructs rather than continues.
85102
*/
86103
export function* resolveSessionPlacement(
87104
store: AcpSessionStore,
88105
agentCommand: string,
89106
cwdPath: string,
90107
name?: string,
91-
): Operation<SessionCandidate> {
108+
): Operation<SessionPlacement> {
92109
const candidates = yield* sessionCandidates(agentCommand, cwdPath, name);
93110
for (const candidate of candidates) {
94111
const record = yield* until(store.load(candidate.sessionKey));
@@ -97,8 +114,11 @@ export function* resolveSessionPlacement(
97114
record.agentCommand === agentCommand &&
98115
resolve(record.cwd) === resolve(candidate.cwd)
99116
) {
100-
return candidate;
117+
return {
118+
...candidate,
119+
state: record.sessionMaterialization?.state === "pending" ? "pending" : "established",
120+
};
101121
}
102122
}
103-
return candidates[0]!;
123+
return { ...candidates[0]!, state: "pending" };
104124
}

‎packages/acp/tests/acceptance.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,7 @@ describe("Tier WAP — same-named sibling Sessions", () => {
135135
return {
136136
sessionKey: `placed:${context.sessionIdentity ?? "none"}`,
137137
cwd: "/placed",
138+
state: "pending",
138139
};
139140
},
140141
},
@@ -221,6 +222,7 @@ describe("Tier WAP — same-named sibling Sessions", () => {
221222
return {
222223
sessionKey: `placed:${context.sessionIdentity ?? "none"}`,
223224
cwd: "/placed",
225+
state: "pending",
224226
};
225227
},
226228
},

0 commit comments

Comments
 (0)