Return launch details from `<Session.Launch>`

[taras]

Story

As someone launching a native coding-agent session from an executable document, I want to capture which session was launched, so I can report or use the durable conversation identity after the native UI exits.

Example

An author captures the launch result when it is useful:

<Session.Launch session="implementor" as="launch">
 Implement the accepted plan.
</Session.Launch>

Native session: {launch.nativeSessionId}

launch.nativeSessionId is the exact identity the native provider asserted for the conversation that was created or resumed.

Capture remains optional for the common interactive form:

<Session.Launch session="implementor">
 Implement the accepted plan.
</Session.Launch>

Current gap

The canonical launchAgentSession() operation already returns a trusted SessionLaunchResult containing the resolved agent, logical XMD session, provider-native session ID, and launcher identity:

interface SessionLaunchResult {
 agent: string;
 session: {
 sessionKey: string;
 cwd: string;
 agentSessionId?: string;
 };
 nativeSessionId: string;
 launcher: string;
}

<Session.Launch> calls that operation but discards its result and returns an empty string. Although generic text-component capture accepts as, the binding therefore contains no useful information, and xmd syntax advertises no capture contract.

Contract

On a successful native launch, <Session.Launch as="launch"> binds the same validated SessionLaunchResult that launchAgentSession() derives from the retained launch phases:

• agent is the resolved public agent name;
• session is the logical XMD session selected for the launch;
• nativeSessionId is the provider-asserted identity of the native conversation;
• launcher is the stable adapter name, such as claude, never an executable path.

The result is data, not authority. Supplying a captured native session ID to another invocation does not select, resume, replace, or take ownership of that conversation. Session continuation continues to use the existing <Session> placement, construction-route, executable-binding, and ownership checks.

as is optional because launching the session is the component's primary action. Without as, the same launch occurs and the component renders nothing. With as, it still renders nothing and binds the structured result after the native UI exits successfully.

A completed replay binds the same launch result from retained evidence without starting another native process. A failed, cancelled, signalled, or nonzero-exit launch produces no successful result and retains its existing failure behavior. Public middleware cannot manufacture a successful result without the provider-authoritative retained phases.

The capture exposes no executable path, argv, environment, private instruction-file path, credentials, terminal bytes, or transcript.

Transcript boundary

This issue does not capture a session transcript. <Session.Launch> hands the terminal directly to the provider's native UI, and native conversation turns need not be mirrored into ACP or XMD state. Transcript capture requires a separate observability, privacy, storage, and replay contract.

Acceptance

• A successful <Session.Launch as="launch"> binds agent, session, nativeSessionId, and launcher from the authoritative launch result.
• nativeSessionId equals the identity asserted by the provider for the conversation that the native UI created or resumed.
• A launch without as retains its existing interactive behavior and renders nothing.
• A captured launch also renders nothing; the result becomes available only through its binding.
• Named, unnamed, provider-returned, and client-allocated session paths return the identity each path authoritatively established.
• Completed replay restores the same captured result without provider contact or another native process.
• A launch failure or cancellation does not bind a successful-looking result.
• Captured fields cannot be replayed as authority to select or take ownership of a session.
• The captured value contains no native terminal output or transcript and no private process or filesystem details.
• xmd validate accepts both captured and unbound forms, and xmd syntax Session.Launch describes as as optional and lists the captured fields.
• architecture.md, specs/acp-client-spec.md, specs/native-agent-session-launch-spec.md, and the component return contract in specs/executable-mdx-spec.md describe the result and optional capture boundary.

Evidence

Run the focused component, native-provider, CLI, replay, and syntax suites:

deno task test packages/core/tests/agent-session-launch.test.ts packages/acp/tests/native-launch.test.ts packages/cli/tests/session-launch-cli.test.ts packages/cli/tests/agent-session-coordinator.test.ts packages/cli/tests/syntax-cli.test.ts

The regression evidence covers successful capture, optional capture, both identity-provenance paths, failure, replay without relaunch, unforgeability, and exclusion of transcript and private process details.

Related

• Launch a deterministically prepared Agent session in its native UI #517 introduced native session launch and its authoritative SessionLaunchResult.
• Make as optional for <Git.Commit> #751 establishes optional capture for components whose primary outcome is an effect.