Repository navigation
Commit 5542c92
authored
🚀 Hand a prepared agent session to its native UI (#518)
* 🚀 Hand a prepared agent session to its native UI
`<Session.Launch>` prepares one durable coding-agent session from its rendered
body and gives the provider's own interactive UI the terminal for that exact
session, then continues the document after it exits. Backed by
`Agent.launch(instructions, options)`, whose base handler fails: answering
`prompt()` does not make a provider launch-capable.
The body renders completely first, and only what it rendered crosses as the
instruction layer — the prose around the element stays documentation. The
launch performs no model turn.
Phases are retained as `agent_session_launch` records under one expansion
identity: `prepared` before ACP ownership is released, then `detached`, then
`exited`. Separate records because a launch interrupted between detach and
spawn has to resume the session it already prepared rather than create a
replacement.
Authority for those phases is delivered, never published. The public `launch`
route carries one frozen, one-use request describing the ask and answers
nothing; middleware may inspect it, narrow it through `with()`, refuse it, or
delegate it, and what it returns is discarded. Core hands the provider factory
it installs a separate authority as a closure argument — no context holds one,
no request member carries one, and there is no reader for one. That authority
runs each absent phase once, cross-checks the record against the request that
was routed, retains it before the next live effect, and derives the result. A
rebuilt look-alike, a superseded parent, a foreign request, a repeated
delegation, and a fabricated completion each author nothing.
Which request is live is recorded by the invocation that issued it, never on
the request. Nothing a handler holds points back: the value carries its facts
and `with()`, and `Reflect.ownKeys()` over it finds nothing else. That
distinction is the whole boundary — a symbol-keyed property would have been
readable, copyable, and therefore retargetable by the handler it was meant to
be hidden from. The partition handle keeps its state the same way, in a private
field, so reflection over one finds no state and no launch to reach.
The ACPX provider installs the layer at session creation, refuses an agent
whose native launcher is not advertised or that asserts no provider-native
identity, releases ACP ownership before the spawn, and marks its handle stale
so a later `<Prompt>` reattaches. A changed instruction layer is refused
outright: ACPX fixes the layer when the ACP session is created, and its cached
transcript stays empty across native turns, so nothing here can show that
discarding a session would be safe. No launch path discards persistent
provider state — not even for a session an enclosing `<Session>` established
and nothing has used.
Every operation that can act on an advertised provider-returned session —
establishing it, subscribing a prompt, launching, resuming an incomplete
launch — takes exclusive ownership of it first, under the natural key
`(acpx, agent command, session key)`. The coordinator answering that is built
by the host and passed straight into the provider, because a decision document
middleware could replace is not one. Acquisition never waits: contention
retains `session-busy` before any ACP work. An owner acknowledges quiescence
only once it holds no usable handle, so a handoff that could not release leaves
the record active — and the next owner is told to recover it rather than
inferring safety from a released lock, a pid, or an empty transcript.
Deno and the compiled binary combine a process-local occupancy table, one
non-blocking advisory lock, and an ownership record atomically replaced and
durably flushed under `~/.acpx/xmd-native-sessions/v1`. Node and Bun build
none and fail closed: neither exposes a cross-process advisory lock, and a pid
or heartbeat emulation calls a paused process dead and admits two owners.
`<TestAgent>` installs one ACP provider, lexically, in its own invocation, and
selects a complete per-test partition on every dispatch. Installing is what
makes the provider reachable from the content it serves and what makes that one
closure the only holder of launch authority; partitioning is what keeps one
test's sessions, queues, records and coordinator out of the next. A partition
handle is launch-free and resolves only by live module-private identity, so a
foreign, fabricated, or dismantled one reaches no state at all. It also
installs a controlled launcher for its body, because a scripted agent's native
UI does not exist and the terminal belongs to whoever is running the tests.
The native launcher is its own seam, not `exec`: it takes the run's one
foreground-terminal lease before an agent is resolved, flushes what the
document has produced, inherits the terminal to the child, and reaps a child
that ignores the interrupt by pid — Deno's `ChildProcess.kill()` delivers only
its first signal, so escalation through the handle silently does nothing.
The authored half of the evidence is one executable Markdown document,
`packages/test-agent/src/NativeSessionLaunch.test.md`, run whole: the launch,
the prompt that proves no turn was spent, and the eager-`<Session>` refusal are
written as Markdown rather than assembled from a TypeScript string.
No real adapter is advertised. `claude` and `codex` have command shapes and
contract tests; the opt-in Claude proof shows the ACP adapter creates no
resumable native state and asserts no native identity, so it fails closed.
Refs #517
Claude-Session: https://claude.ai/code/session_01MNztk1fikXUnD2FW4yS6Kr
* 🔒 Keep a session owned when its ACP handle would not close
`releaseHandle()` reported a failed `close()` and then marked the managed entry
stale anyway. Stale is what `holding()` reads, so both callers of the ordinary
release path — `session()` and the prompt ownership finalizer — then saw this
scope holding nothing and acknowledged quiescence. The durable record went idle
for a session ACP had not let go of, and the next owner was handed it.
A close that failed released nothing, so the entry stays live: quiescence is
not acknowledged, the record stays active, and the next owner is refused with
`session-recovery-required`. A successful close is unchanged — stale handle,
idle record, and the session is free. The native-launch detach path already had
this shape, which is why it was not affected.
`NO11` drives both supported call sites with a failing `close()` and proves the
refusal arrives before any ACP work, while the provider scope still reports the
close it could not complete. Its observations are collected inside the scope and
asserted outside it: that scope's teardown raises the cleanup failure, which
replaces anything the body raised, so an assertion written in there passes
whatever happens.
Also repairs two typechecks the frozen focused matrix did not cover and CI
found: `packages/test-agent/tests/provider.test.ts` still built the provider
with the replaced `resolveRoute` seam, and `AG1`/`AG2` still asserted
`AgentProviders.resolve(name)`, which the request-only installation protocol
removed. Both now exercise the surviving contract.
Refs #517
Claude-Session: https://claude.ai/code/session_01MNztk1fikXUnD2FW4yS6Kr
* 🧪 Keep the Deno session-coordinator proof out of the Node and Bun corpus
`packages/runtime/tests/agent-session-coordinator.test.ts` is the Deno adapter's
own proof: it takes a non-blocking advisory lock through `Deno.FsFile.tryLock`
and races it against real Deno children that are killed mid-ownership so a
tombstone survives them. Both the lock primitive and the children are Deno's, so
the file reached for `Deno` directly — which `tsc` cannot resolve and Bun cannot
run.
`test-node` failed its typecheck on four `Deno` references plus two `unknown`
chunks; `test-bun` ran the file and failed all seven Tier CO cases. The
runtime-exclusion mechanism is where a deliberate absence from one runtime is
recorded and reviewed, and this is the shape it already carries for
`workflow-lifecycle-authority.test.ts`, which races the same primitive.
The provider-neutral half of the contract stays on every runtime: owner kinds,
contention, quiescence, the tombstone and the record shape are proven through
`packages/acp/tests/native-launch.test.ts`, and the host difference itself
through `packages/cli/tests/agent-session-coordinator.test.ts`, which runs under
all three.
Delivery only. No source behavior changes, and no file under `packages/`
differs from the reviewed head.
Refs #517
Claude-Session: https://claude.ai/code/session_01MNztk1fikXUnD2FW4yS6Kr
* 📝 Bind the post-launch answer with component capture
`main` retired the reserved `<Capture>` directive in favour of `<Let>` and
component-level capture, leaving `Capture` resolvable only as an ordinary
component name. The authored journey still wrapped its post-launch prompt in the
retired directive, so after the rebase the direct-launch scenario stopped at that
line with `Cannot resolve component: Capture` — before it could prove the launch
spent no turn.
The prompt binds its own rendered answer now. The observation is unchanged: the
scenario holds one scripted stage, the launch does not consume it, and the
prompt that follows still receives `nothing yet`.
Authored acceptance only. No scenario, assertion, authority, coordinator,
provider-partition, reconciliation, specification, or architecture change.
Refs #517
Claude-Session: https://claude.ai/code/session_01MNztk1fikXUnD2FW4yS6Kr
---------
Co-authored-by: Taras Mankovski <[email protected]>1 parent dda464c commit 5542c92
59 files changed
Lines changed: 9066 additions & 257 deletions
File tree
- packages
- acp
- src
- tests
- cli
- src
- tests
- core
- src/agent
- tests
- runtime
- tests
- fixtures
- test-agent
- src
- worker
- tests
- scripts
- specs
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
78 | 78 | | |
79 | 79 | | |
80 | 80 | | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
81 | 92 | | |
82 | 93 | | |
83 | 94 | | |
| |||
2626 | 2637 | | |
2627 | 2638 | | |
2628 | 2639 | | |
| 2640 | + | |
| 2641 | + | |
| 2642 | + | |
| 2643 | + | |
| 2644 | + | |
| 2645 | + | |
| 2646 | + | |
| 2647 | + | |
| 2648 | + | |
| 2649 | + | |
| 2650 | + | |
2629 | 2651 | | |
2630 | 2652 | | |
2631 | 2653 | | |
| |||
2658 | 2680 | | |
2659 | 2681 | | |
2660 | 2682 | | |
| 2683 | + | |
2661 | 2684 | | |
2662 | 2685 | | |
2663 | 2686 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
22 | | - | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
23 | 39 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
0 commit comments