You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 802b07d
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: architecture.md
+30-10Lines changed: 30 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2847,15 +2847,35 @@ request to act. This preserves provider composition without letting a document
2847
2847
or replacement context mint terminal ownership.
2848
2848
2849
2849
A pane claim grants one interactive terminal at that ordinal, not an Agent
2850
-
session. Core installs a pane-scoped native launcher that closes over the claim.
2851
-
`<Session.Launch>` in that pane consequently reserves, flushes, and launches on
2852
-
the pane terminal instead of competing for the root lease. Launches in
2853
-
different panes may run concurrently; two interactive launches in one pane
2854
-
cannot. Sequential launches in one paired pane remain ordinary composition.
2855
-
The session coordinator is unchanged and independently authoritative, so two
2856
-
panes attempting to own the same logical Agent session still contend and one
2857
-
is refused. The provider starts a self-closing pane's host-configured default
2858
-
shell under the same kind of pane claim.
2850
+
session. Core installs a pane-scoped native launcher that closes over the claim,
2851
+
the composite, and the authored ordinal. `<Session.Launch>` in that pane
2852
+
consequently reserves and flushes the pane, then terminates native-launch
2853
+
routing at this required provider-neutral composite operation:
2854
+
2855
+
```ts
2856
+
launch(
2857
+
ordinal: number,
2858
+
request: NativeLaunchRequest,
2859
+
spawned: () =>void,
2860
+
): Operation<NativeLaunchOutcome>;
2861
+
```
2862
+
2863
+
The ordinal exists only in core's live closure and never enters the native or
2864
+
Agent request. Once nearer native-launch middleware delegates, the pane launcher
2865
+
calls the composite operation instead of the root foreground launcher. Nearer
2866
+
middleware may still observe, wrap, refuse, or short-circuit the request. A
2867
+
composite that cannot execute the pane request refuses explicitly; falling
2868
+
through to the root would put the child on the wrong physical terminal. Root
2869
+
`<Session.Launch>` retains its existing foreground-launch route unchanged.
2870
+
2871
+
Launches in different panes may run concurrently; two interactive launches in
2872
+
one pane cannot. Sequential launches in one paired pane remain ordinary
2873
+
composition. The session coordinator is unchanged and independently
2874
+
authoritative, so two panes attempting to own the same logical Agent session
2875
+
still contend and one is refused. The composite's separate `shell()` operation
2876
+
starts a self-closing pane's host-configured default shell under the same kind
2877
+
of pane claim; it remains separate because its executable is live host policy,
2878
+
not an authored or Agent-provided native launch request.
2859
2879
2860
2880
Each claim also closes over one host-owned readiness latch. The pane-scoped
2861
2881
native launcher acknowledges it from the runtime's successful child-spawn event
@@ -4137,7 +4157,7 @@ Status is measured against main.
4137
4157
| testing harness (`<Execution>`) | runs another document as a real root under a production host profile, authorized by canonical `<Test>` alone: declarations installed before the root import, child output displayed progressively and collected only when asked, journal retention selected independently of observation, and the outcome published by the invocation's own terminal through a request public middleware composes around but cannot answer | built on the #454 stack for `host="run"`; the workflow profile and `<WorkflowRun>` are unbuilt, and a host that offers no workflow profile refuses them |
4138
4158
| nested run-profile Agent and elicitation declarations | lets one `<Execution host="run">` declare one child-scoped `<TestAgent>` scenario set and one non-delegating `<Answers>` matcher set; only frozen test data crosses the harness request, the trusted host constructs both providers inside the isolated child, siblings share no session or provider state, ordinary component shadowing remains in force, and the child journal retains only the selected Prompt and Elicit components' ordinary results | built on the #641 stack |
4139
4159
|`Config` run deadline / exec default / Fetch default / verbosity | three independently owned contextual timeouts, absent unless configured, each read by exactly one consumer, and contextual verbosity — a boolean that is false unless configured, seeded by the command line and overridable for a lexical subtree, bounding nothing and owning no authority | built on this stack |
4140
-
| terminal grid (`<Terminal.Grid>` / `<Terminal>`) | replaces the root foreground terminal with one provider-neutral composite whose statically declared direct panes begin concurrently, stay independently interactive, preserve their final statuses until the reader closes the composite, and tear down completely before document execution continues. A paired pane expands isolated document flow; a self-closing pane runs the host's default shell. The grid owns one foreground-terminal lease, each pane owns a separate pane-terminal lease, and a pane-scoped native launcher lets `<Session.Launch>` use that pane without weakening the independent Agent session coordinator. Core validates the complete row-major layout before provider contact, attaches only after every pane is ready, contains post-attach pane failures until close, and records the ordered provider-neutral outcomes. Completed replay contacts no terminal or Agent provider; partial replay rebuilds a fresh composite, restores completed panes as statuses, and continues incomplete pane effects under their existing durable identities. Provider commands, sockets, process topology and layout identifiers remain live-only inside the provider closure | defined for #717; #726 proves the persistent tmux pane-worker topology and its observable teardown boundary on macOS; structure and layout built in #729, provider-neutral execution and durability in #730, pane-scoped native Agent launch in #731; the controlled non-tmux provider remains the authority for core lifecycle semantics; the tmux provider is built in #732 for the Deno and compiled foreground hosts, whose evidence uses a fake tmux — real tmux behaviour on macOS is #726's; Node and Bun catalog and validate the same grids and install no operational provider |
4160
+
| terminal grid (`<Terminal.Grid>` / `<Terminal>`) | replaces the root foreground terminal with one provider-neutral composite whose statically declared direct panes begin concurrently, stay independently interactive, preserve their final statuses until the reader closes the composite, and tear down completely before document execution continues. A paired pane expands isolated document flow; a self-closing pane runs the host's default shell. The grid owns one foreground-terminal lease, each pane owns a separate pane-terminal lease, and a pane-scoped native launcher lets `<Session.Launch>` use that pane without weakening the independent Agent session coordinator. The launcher terminates at the composite's required provider-neutral pane-execution operation; the authored ordinal stays in core's live closure, and the native request carries no pane identity. Core validates the complete row-major layout before provider contact, attaches only after every pane is ready, contains post-attach pane failures until close, and records the ordered provider-neutral outcomes. Completed replay contacts no terminal or Agent provider; partial replay rebuilds a fresh composite, restores completed panes as statuses, and continues incomplete pane effects under their existing durable identities. Provider commands, sockets, process topology and layout identifiers remain live-only inside the provider closure | defined for #717; #726 proves the persistent tmux pane-worker topology and its observable teardown boundary on macOS; structure and layout built in #729, provider-neutral execution and durability in #730, pane claim admission and native-launch middleware in #731; the required composite pane-execution endpoint is specified after the #732 integration exposed the missing physical route and remains to be implemented; the controlled non-tmux provider remains the authority for core lifecycle semantics; the tmux provider is built in #732 for the Deno and compiled foreground hosts, whose evidence uses a fake tmux — real tmux behaviour on macOS is #726's; Node and Bun catalog and validate the same grids and install no operational provider |
4141
4161
| native session launch (`<Session.Launch>` / `launchAgentSession()`) | prepares one durable coding-agent session from the rendered body of `<Session.Launch>` and hands the provider's native UI the terminal for that exact session, then continues the document after it exits. The body renders completely first and only what it rendered crosses as the instruction layer; the launch performs no model turn; at the root it takes the run's foreground-terminal lease before an agent is resolved, while a launch inside `<Terminal>` takes that pane's lease through its pane-scoped native launcher. A host with no applicable terminal refuses without probing for an installed CLI. A session is constructed once, by one of two mechanisms, and its create-once construction route says which. Where the provider returns the identity, the ACPX provider creates the session, installs the layer at creation, releases ACP ownership before the spawn, and marks its handle stale so a later `<Prompt>` reattaches. Where the adapter names its own sessions, it allocates the identity inside ownership before any process exists, the native process creates the session under that name from a private mode-0600 instruction file, and ACP creates nothing — the instruction text reaches neither argv nor environment, and the file is removed on success, failure and cancellation alike while ownership is still held. Neither route converts into the other, and which one governs is chosen by the first operation that consumes the placement rather than by the `<Session>` that made it: a fresh `<Session>` publishes no route and establishes nothing, so a `<Session.Launch>` nested inside one constructs the session it placed, while a first subscribed `<Prompt>` publishes ACP-first before it ensures and keeps that account even if the turn that follows is never accepted. An established route is validated eagerly by a later `<Session>`, and a launch meeting a published ACP-first route refuses before an identity exists. A `<Session>` or `<Prompt>` meeting a bound client-allocated route attaches under the route's exact identity; a legacy unbound route or an unavailable attachment capability refuses before a turn and creates no substitute conversation. Phases are retained as `agent_session_launch` records under one expansion identity — `prepared` before ownership is released, then `detached`, then `exited` — so a completed replay launches nothing, a replay holding only `prepared` proves the handoff never began and may still create under the retained identity, and one holding `detached` resumes and never falls back. The public route carries an opaque one-use launch request and answers nothing; authority to run and retain a phase is delivered to the installed provider directly, so neither a returned completion nor a rebuilt request authors a launch. Every operation that can act on an advertised session takes exclusive ownership under one natural key first, through a coordinator the host built and passed in; contention refuses instead of queueing, and an owner that never proved it stopped leaves a recovery tombstone. A host that cannot say who owns a session refuses every advertised operation, and one that cannot say how a session was constructed additionally refuses an agent that names its own — before any provider effect. Every private setup or child-creation failure is normalized to `process-creation-failed` with fixed provider-owned text, carrying no path, argv, environment or host message. No launch path discards persistent provider state. A client-allocated session is bound to one executable build: the build is observed inside ownership before an identity is allocated, the binding is published with the V2 route and retained beside the prepared record, the native child runs the exact observed path in place of the launcher name, and every later create, resume, attachment and incomplete replay reobserves and compares before a process, an ensure or a turn. A `<Session>` or `<Prompt>` meeting a bound client-native route attaches to it: it reobserves the build, requires any retained provider arrangement to assert that same conversation, calls ensure with the route identity as `resumeSessionId`, and requires the provider to report that identity before a turn — refusing on missing capability, build drift, missing history or a differing assertion without creating a substitute conversation. ACP runtimes are partitioned by resolved agent command and binding, each handle is closed by the partition that created it, and a bound partition is torn down when its last handle closes. A legacy V1 client-native route keeps exactly the released native-only behavior and never attaches | built on the #517 stack, extended by the #519 and #561 stacks; Deno and the compiled binary assemble the host — coordinator, route store and executable observer — and Node and Bun keep the same advertised names while assembling none of it, so every advertised operation refuses before provider work; `claude` is advertised for native launch after passing the client-allocated gate at Claude Code 2.1.241 on macOS arm64 (#520) and separately for client-native attachment after passing the native-to-ACP marker gate (#561), and Codex remains unadvertised because nothing has run its provider-returned claims against an installed Codex; `Agent.AddDir` is unbuilt |
4142
4162
|`<Fetch>`| performs one XMD-mediated HTTP read through contextual `API.Fetch`, admitting the whole request before transport, and retains the normalized request and the detached response as one `fetch` durable observation; capture decides whether a status is data or a failure, and the trusted host's destination ceiling sits below the component | built on the #456 stack; a generated fragment may name the pinned identity only for a request the trusted host stated exactly, on the #369 stack |
4143
4163
|`API.Files`| routes every document filesystem operation to the installed provider, with no host default and structural failure data. Its mandatory semantic operations include `ensureDirectory`, which recursively creates or adopts one directory and returns Unit; separately loaded copies compose through the stable Api name | built on the #227 stack; directory ensure added by #643|
Copy file name to clipboardExpand all lines: specs/executable-mdx-spec.md
+30Lines changed: 30 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8655,6 +8655,35 @@ acknowledges. The self-closing shell does the same. The latch is absent for a
8655
8655
root launch and appears in no prop, binding, contextual API, public request,
8656
8656
provider return, process result, or durable record.
8657
8657
8658
+
For a paired pane, core closes the pane-scoped native launcher over the
8659
+
composite and that pane's authored ordinal. After claim admission and the pane
8660
+
output flush, delegation reaches the composite's required provider-neutral
8661
+
operation:
8662
+
8663
+
```ts
8664
+
launch(
8665
+
ordinal: number,
8666
+
request: NativeLaunchRequest,
8667
+
spawned: () => void,
8668
+
): Operation<NativeLaunchOutcome>;
8669
+
```
8670
+
8671
+
The request is the exact native command vector, working directory, and
8672
+
environment supplied by the Agent provider. The ordinal stays in core's live
8673
+
closure and enters no native request, Agent request, session key, construction
8674
+
route, durable phase, result, or diagnostic. Native-launch middleware installed
8675
+
nearer the authored launch may observe, wrap, refuse, or short-circuit before it
8676
+
delegates. The pane launcher is the physical-terminal endpoint: it calls the
8677
+
composite operation and never delegates to the root foreground launcher. A
8678
+
provider unable to execute the pane request refuses explicitly instead of
8679
+
falling back to the wrong terminal. A root `<Session.Launch>` keeps the existing
8680
+
root foreground route unchanged.
8681
+
8682
+
The composite invokes `spawned` only for the child's runtime spawn event. Its
8683
+
separate `shell()` operation remains the self-closing-pane path because that
8684
+
operation derives the executable from live host policy rather than accepting an
8685
+
authored or Agent-provided native launch request.
8686
+
8658
8687
When a persistent process owns a pane endpoint, the launcher sends the exact
8659
8688
argv vector, working directory, and environment over the provider's private
8660
8689
authenticated channel to that pane owner. The presentation provider's command
@@ -10798,6 +10827,7 @@ test derives a core result from a provider identifier.
10798
10827
| TG17 | Replay divergence and retained shape | A resolved layout change — `columns` or a `title`, reached through a prop-borne value, because a continuation executes the retained root — refuses before the lease and before provider contact, with zero provider observation. Pane count, order and form cannot differ under a fixed retained root, so they are proved retained and honoured rather than refused: the complete authored structure appears in the record, and a continuation whose supplied file differs in count, order or form opens the retained structure rather than the file's. Retained layout, close kind and pane outcomes contain no provider command, socket, process, session, window or pane identifier, path, argv, environment or terminal bytes |
10799
10828
| TG18 | Provider neutrality | The controlled non-tmux provider passes TG1–TG17 and TG19; the tmux adapter prepares one hidden invocation-private server with authenticated persistent pane workers, transmits exact child creation outside tmux parsing, applies explicit row-major layout, distinguishes visible detach from control loss and server stop, attaches only after runtime spawn readiness, and satisfies TG14 without leaking provider identifiers; Node and Bun validate the same document and refuse before pane start with no provider installed |
10800
10829
| TG19 | Reader close crossed with parent cancellation | A controlled live pane enters a signal-held finalizer after reader close takes effect. Parent cancellation begins while teardown is blocked; releasing the finalizer lets pane and provider teardown complete, retains the pane as `closed` and the grid with its reader-close result, and only then delivers cancellation to the parent. A continuation neither contacts the provider nor enters pane work, does not hang, and proceeds from the retained grid outcome. Provider-resource and following-sibling observations prove both sides of the ordering; no elapsed duration is evidence |
10830
+
| TG20 | Pane-native physical endpoint | A paired pane's native launch passes through nearer launcher middleware and then the required composite operation for its authored ordinal. Production tmux evidence observes the exact argv, cwd, and environment at that pane's authenticated worker while a root-foreground-launcher sentinel is never entered. Distinct pane workers accept concurrent launches. Cancellation settles only after worker-reported child settlement and pane-terminal quiescence. A root launch still enters the root foreground launcher unchanged, and a composite unable to execute a pane launch refuses without fallback |
10801
10831
10802
10832
### Tier CR — Component registration and resolution
0 commit comments