@platless/axom-cli 0.1.0

package/dist/workstation/acp/adoption.js

@@ -0,0 +1,396 @@
+/**
+ * "Adoption" — a user picking up a native agent session that already exists on this machine and
+ * having its history replayed into Axom's timeline. Two ACP methods, both **optional on the
+ * agent** and gated by `AcpConnection.capabilities` (Task 3): {@link listNativeSessions} calls
+ * `session/list`, gated on `capabilities.list`; {@link replayNativeSession} calls `session/load`,
+ * gated on `capabilities.loadSession`. Both degrade to "nothing to show" rather than an error when
+ * unsupported — see the doc comment on each for why, and the deleted `bridges/types.ts`'s
+ * `AgentBridge.listNativeSessions`/`BridgeSession.backfill` KDoc for the contract this carries
+ * forward verbatim ("the directory hides the grouping, not an error").
+ *
+ * ## `session/resume` is deliberately NOT used here — read this before "fixing" it back
+ *
+ * The plan text that spawned this task says "`session/resume(replayFrom)`". Both do not exist in
+ * `@agentclientprotocol/sdk@1.4.0`'s stable v1 entry point: `ResumeSessionRequest` has no
+ * `replayFrom` field (that name only appears under `@agentclientprotocol/sdk/experimental/v2`,
+ * which Global Constraint 1 forbids importing), and — more fundamentally — `resumeSession`'s own
+ * doc comment in `dist/acp.d.ts` says it "Resumes an existing session **without** replaying the
+ * message history (**unlike** `session/load`)". `session/load` (`loadSession`, gated by the
+ * top-level `AgentCapabilities.loadSession: boolean`, not `sessionCapabilities`) is the ACP v1
+ * method whose own doc comment says the agent should "Stream the entire conversation history back
+ * to the client via notifications" — i.e. it is the actual replay mechanism this file needs.
+ * `session/resume` exists for a client that already has a session's history cached elsewhere and
+ * wants to keep working without paying for a redundant replay; Axom has never seen an adopted
+ * session's history before, so that case never applies here.
+ *
+ * Verified both target adapters actually support the method this file calls: `claude-agent-acp`
+ * 0.70.0 and `codex-acp` 1.6.2 both declare `agentCapabilities.loadSession: true` and both
+ * implement `session/load` (`.superpowers/research/acp-sdk-registry.md`, "VERIFIED" section).
+ *
+ * ## Observing the replayed `session/update` notifications
+ *
+ * Unlike `session/new` (Task 4's `AcpSession`, built on the SDK's `ClientContext.buildSession(...)`
+ * convenience wrapper), the SDK has no `SessionBuilder`-equivalent helper for `session/load` — the
+ * only public, supported way to see raw `session/update` notifications outside of that helper is a
+ * `ClientApp`-level `onNotification(methods.client.session.update, ...)` handler (the pattern the
+ * SDK's own `acp.test.js` uses throughout for exactly this). That has to be registered before
+ * `ClientApp.connect()` copies its handler table (`acpClient.ts`'s `ConnectAgentOptions.configure`
+ * doc comment; `permission.ts`'s file doc comment says the same for `session/request_permission`).
+ * {@link createReplayCapture}/{@link ReplayCapture.register} exist for that: a caller passes
+ * `capture.register` into `connectAgent`'s `configure` hook — composable with `permission.ts`'s
+ * `registerPermissionHandlers` in the same hook, since `configure` is one function a caller can do
+ * several registrations inside of — and later, once the connection exists, passes the *same*
+ * `capture` into {@link replayNativeSession}. The registered handler sees *every* `session/update`
+ * notification on the connection, not just the one being replayed (verified against
+ * `SessionUpdateRouter.handleMessage`, which always returns `Handled.no(message)` — it never consumes
+ * the message, so dispatch keeps walking the handler chain to whatever else is registered, including
+ * the SDK's own internal `session/new`-scoped router for a live `AcpSession` on the *same* connection).
+ * That is exactly the axis review found this file getting wrong in fix round 1: a stray comment here
+ * used to say this "never interferes with a live `AcpSession` on some other connection" — true, but
+ * irrelevant, since the real conflict is a live `AcpSession` on the *same* connection (the shape a
+ * caller composing this with `registerPermissionHandlers` in one `configure` hook produces routinely).
+ * Without gating, the handler above would buffer *every* session's updates forever — only
+ * {@link ReplayCapture.take} ever releases a buffered entry, and it is only ever called for the one
+ * `sessionId` being replayed, so any other session's notifications arriving on this connection (most
+ * concretely: a live `AcpSession` opened on the same connection right after adoption, which Task 8
+ * needs) would accumulate unbounded for the life of the connection. {@link ReplayCapture.arm} exists
+ * to close that: the handler now only buffers a `sessionId` that has been armed, {@link
+ * replayNativeSession} arms its target *before* sending `session/load`, and `take()` disarms on its
+ * way out — so the buffer's upper bound is whatever is currently being replayed, never every session
+ * this connection has ever seen an update for.
+ *
+ * ## Replay goes through the same mapping and folding the live path uses — reimplemented, not shared
+ *
+ * {@link replayNativeSession} maps every replayed `SessionUpdate` through the exact same
+ * `mapSessionUpdate` (`sessionUpdateMapper.ts`) the live path (`AcpSession`) uses, and every mapped
+ * event through the same `validateWireEvent` (`validate.ts`) outbound check — so it can never
+ * emit anything the server can't decode, and (per `mapSessionUpdate`'s own contract) can never emit
+ * `final_result`. What it does NOT reuse is `AcpSession`'s own `agent_message` synthesis /
+ * synthesis: that lives in `AcpSession` as push-based, event-sink-driven instance state (see its
+ * class doc comment), a different execution shape than this file's pull-based `AsyncGenerator` over
+ * an already-complete update list. Task 4's report flagged this by name: "the replay path needs its
+ * own equivalent folding and message-completion logic — do not assume the live path's state machine
+ * is doing it for you." {@link foldReplayEvents} is that equivalent, reimplemented as a single pass
+ * over a finished array instead of instance fields mutated across live callbacks.
+ *
+ * **The `user_message` half of that duplication is gone.** This file used to carry its own copy of
+ * `AcpSession.foldUserMessageChunk`, and the two had already drifted: replay flushed a buffered user
+ * message on *any* intervening event, the live path only on a different `messageId` or turn end, so
+ * the same transcript produced a different number of cards depending on which path replayed it.
+ * Phase 7 moved the fold to `CoworkEngine`, which already buffered `agent_message_chunk` by exactly
+ * the ACP rule that covers all three chunk kinds (`ContentChunk`, `types.gen.d.ts:3456`).
+ * `user_message_chunk` now passes through here untouched, and `ExternalAgentEventApplier`'s
+ * `onBackfillDone` is what closes the last buffered message.
+ */
+import { methods } from '@agentclientprotocol/sdk';
+import { validateWireEvent } from './validate.js';
+import { mapSessionUpdate, SessionMapperState } from './sessionUpdateMapper.js';
+/** `NativeSessionInfo.title` is truncated to this many characters — mirrors the deleted `claudeCode/adoption.ts`'s display-safety guard (`TITLE_MAX_LENGTH`). */
+const TITLE_MAX_LENGTH = 80;
+/** `SessionInfo.updatedAt` is an ISO 8601 string or `null`/absent; missing or unparseable sorts as oldest (0) rather than throwing. */
+function parseUpdatedAt(value) {
+    if (!value)
+        return 0;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+/**
+ * List an agent's native sessions scoped to `query.cwd`, newest first.
+ *
+ * When the agent doesn't advertise `sessionCapabilities.list` (`connection.capabilities.list`),
+ * this returns an empty result **without ever calling `session/list`** — matching the deleted
+ * `AgentBridge.listNativeSessions?`'s contract verbatim ("the directory hides the grouping, not an
+ * error"). Not calling the method at all (rather than calling it and treating any error as "empty")
+ * matters because "honour the advertised capability, not the router" (Task 3/5's own rule) cuts both
+ * ways: `codex-acp` routes `session/fork` without declaring it, so a client that called unadvertised
+ * methods anyway would be relying on exactly the coupling that rule exists to rule out.
+ */
+export async function listNativeSessions(connection, query) {
+    if (!connection.capabilities.list)
+        return { sessions: [] };
+    const response = await connection.connection.agent.request(methods.agent.session.list, {
+        ...(query.cwd ? { cwd: query.cwd } : {}),
+        ...(query.cursor ? { cursor: query.cursor } : {}),
+    });
+    const sessions = response.sessions
+        .map((info) => ({
+        nativeSessionId: info.sessionId,
+        title: (info.title ?? '').slice(0, TITLE_MAX_LENGTH),
+        updatedAtEpochMs: parseUpdatedAt(info.updatedAt),
+        cwd: info.cwd,
+    }))
+        .sort((a, b) => b.updatedAtEpochMs - a.updatedAtEpochMs);
+    return response.nextCursor != null ? { sessions, nextCursor: response.nextCursor } : { sessions };
+}
+export function createReplayCapture() {
+    const armed = new Set();
+    const buffered = new Map();
+    const listeners = new Map();
+    return {
+        register(app) {
+            app.onNotification(methods.client.session.update, (ctx) => {
+                // Armed wins over listening: while a session/load replay is in flight, its history must land
+                // in the buffer rather than in a live session's read loop — see `listen`'s doc comment.
+                if (armed.has(ctx.params.sessionId)) {
+                    const list = buffered.get(ctx.params.sessionId) ?? [];
+                    list.push(ctx.params.update);
+                    buffered.set(ctx.params.sessionId, list);
+                    return;
+                }
+                // Neither armed nor listened to: dropped, so this handler cannot accumulate every session
+                // the connection has ever seen an update for (see the file doc comment).
+                listeners.get(ctx.params.sessionId)?.(ctx.params.update);
+            });
+        },
+        arm(sessionId) {
+            armed.add(sessionId);
+        },
+        take(sessionId) {
+            armed.delete(sessionId);
+            const list = buffered.get(sessionId) ?? [];
+            buffered.delete(sessionId);
+            return list;
+        },
+        count(sessionId) {
+            return buffered.get(sessionId)?.length ?? 0;
+        },
+        listen(sessionId, sink) {
+            listeners.set(sessionId, sink);
+            return () => {
+                // Only clear our own entry: a later listen() for the same sessionId may already have
+                // replaced it, and unsubscribing then would silence the session that is actually running.
+                if (listeners.get(sessionId) === sink)
+                    listeners.delete(sessionId);
+            };
+        },
+    };
+}
+/** `payload[key]` narrowed to `string`, or `null` — same helper `acpSession.ts` uses for the identical reason (`payload` is `Record<string, unknown>` by construction). */
+function stringField(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' ? value : null;
+}
+/**
+ * Map a completed list of replayed `SessionUpdate`s to wire events, applying the same
+ * message-completion synthesis {@link AcpSession} applies to the live stream — see the file doc
+ * comment for why this is a reimplementation, not a shared call, and `acpSession.ts`'s
+ * `trackMessageBoundary`/`flushMessageCompleted` for the rule being mirrored:
+ *
+ * - `agent_message` is synthesized whenever the streaming `agent_message_chunk`/`agent_thought_chunk`
+ *   `messageId` changes, and once more at the very end of the list (there is no live "turn end"
+ *   signal to hang this off during replay — a whole adopted session's history has no `PromptResponse`
+ *   in it at all — so "end of the replayed list" is this function's equivalent of `AcpSession.finishTurn`'s
+ *   unconditional turn-end flush).
+ * - A `user_message_chunk` still forces that synthesis: a user turn beginning means whatever the
+ *   assistant was streaming has necessarily already ended. The chunk itself is emitted verbatim —
+ *   folding it is the server's job now (see the file doc comment).
+ *
+ * Exported directly (not just through {@link replayNativeSession}) so its synthesis behavior can be
+ * pinned by unit tests with no process spawning involved — the process-spawning tests are reserved
+ * for what only a real subprocess can prove (capability gating, the actual RPC shape, ordering
+ * against the real `session/load` response).
+ */
+export function foldReplayEvents(updates) {
+    const events = [];
+    // Fresh per replay, not shared with the live session that may follow: this call reconstructs one
+    // adopted session's history from its own `tool_call`s, and a registry carried in from elsewhere
+    // could name a call this history never created.
+    const mapperState = new SessionMapperState();
+    let sawMessageContent = false;
+    let currentMessageId = null;
+    function flushMessageCompleted() {
+        if (!sawMessageContent)
+            return;
+        events.push({ eventName: 'agent_message', payload: { messageId: currentMessageId ?? 'replay' } });
+        sawMessageContent = false;
+        currentMessageId = null;
+    }
+    for (const update of updates) {
+        for (const event of mapSessionUpdate(update, mapperState)) {
+            if (event.eventName === 'user_message_chunk') {
+                // A user turn beginning means whatever the assistant was streaming has necessarily already
+                // ended — flush it first, mirroring AcpSession.finishTurn's ordering at a live turn
+                // boundary (just the mirror image here, since replay sees the *next* user turn rather than
+                // an explicit turn-end signal). The chunk itself then goes through verbatim: the fold that
+                // used to live here is the server's now.
+                flushMessageCompleted();
+                events.push(event);
+                continue;
+            }
+            if (event.eventName === 'agent_message_chunk' || event.eventName === 'agent_thought_chunk') {
+                const messageId = stringField(event.payload, 'messageId');
+                if (sawMessageContent && messageId !== null && currentMessageId !== null && messageId !== currentMessageId) {
+                    flushMessageCompleted();
+                }
+                sawMessageContent = true;
+                if (messageId !== null)
+                    currentMessageId = messageId;
+            }
+            events.push(event);
+        }
+    }
+    flushMessageCompleted();
+    return events;
+}
+/**
+ * Wait until the `session/update` notifications an agent sent *before* answering a request have
+ * actually been **dispatched**, which is **not** implied by that request having responded.
+ *
+ * The SDK handles the two message kinds on different schedules (`jsonrpc.js`'s
+ * `receiveWireMessage`): a response is applied **synchronously** via `handleResponse` the moment the
+ * reader pulls it off the stream, while a notification is handed to `processIncomingMessage`, which
+ * is *not* awaited by the read loop and which awaits each registered handler in turn. So even though
+ * the agent writes every `session/update` before its response — and the reader therefore reads them
+ * first — the response's `await` can resume before a single one of our handlers has run. Measured
+ * directly on both request paths that have this shape:
+ *
+ * - `session/load` ({@link replayNativeSession}): the order observed was `response`, then the
+ *   updates, so `take()` on the spot returned a partial history, or none at all.
+ * - `session/prompt` (`acpSession.ts`'s `AcpSession.attach`): the turn's terminal `stop` message was
+ *   enqueued **ahead of** the tail of the same turn's deltas — `agent_message` and the
+ *   `TurnResult` landing mid-stream, with the remaining text arriving as orphans after the item the
+ *   server had already closed.
+ *
+ * The difference between "works" and "reorders" is nothing but how many handlers happen to be
+ * registered on the connection — which is why the same code looked correct until the manager wired
+ * permission handlers onto the same `ClientApp`.
+ *
+ * The one guarantee that survives is ordering *into* the dispatcher: by the time the response is
+ * applied, every preceding notification's dispatch has been **started**. This waits for a macrotask
+ * boundary, which drains a chain of synchronous handlers' microtask continuations, and keeps waiting
+ * while `count()` is still growing.
+ *
+ * ## This is a heuristic. It is bounded **and** it truncates — three ways, all measured
+ *
+ * Nothing enforces the premise it rests on, so read these as live failure modes rather than as
+ * theoretical corners:
+ *
+ * | Condition | Measured outcome |
+ * |---|---|
+ * | Any handler on the chain awaits a **macrotask** (even `setTimeout(…, 0)`) | 6 updates → **0** replayed |
+ * | The agent answers **before** it has finished streaming | 6 updates → **4** replayed |
+ * | The stream outlasts `maxRounds` | 3000 updates → **2086** replayed |
+ *
+ * The first is why "every handler on this chain is synchronous" is a **prerequisite**, and why it is
+ * written down at the place that actually establishes it — `acpAgents.ts`'s `AcpAgents.open`
+ * `configure` hook, the one site where handlers get registered — rather than only here. A function
+ * cannot enforce a property of a registration it never sees.
+ *
+ * The second is outside this function's reach entirely: an agent that responds mid-stream has broken
+ * the ordering guarantee this is built on, and no amount of waiting recovers it.
+ *
+ * The third is `maxRounds`, the backstop against an agent that keeps streaming forever — a wait with
+ * no exit would hang the whole open. It is reachable in practice, so hitting it is **logged** rather
+ * than returned quietly: that diagnostic is the whole line between "bounded degradation" and
+ * "invisible data loss", and it is the only one of the three this function can see happening to
+ * itself.
+ *
+ * `count` is supplied by the caller rather than read off a `ReplayCapture` because the two callers
+ * count different things: the replay path counts buffered updates for one armed `sessionId`, the
+ * live path counts updates delivered into an attached session's queue.
+ */
+export async function settleUpdates(sessionId, count, maxRounds = 10) {
+    let previous = -1;
+    for (let round = 0; round < maxRounds; round += 1) {
+        const before = count();
+        // setImmediate, not setTimeout(0): it runs in the check phase, after the poll phase has drained
+        // whatever the transport already had readable, so one turn covers both the microtasks and any
+        // further messages sitting in the socket buffer.
+        await new Promise((resolve) => setImmediate(resolve));
+        const after = count();
+        if (after === before && after === previous)
+            return;
+        previous = before;
+    }
+    // Falling out of the loop is not "settled" — it is "gave up while the agent was still streaming".
+    // Whatever arrives from here on may be reordered against the turn/replay boundary this call was
+    // holding, or dropped outright. Never silent: a session that quietly loses the tail of its history
+    // is indistinguishable from an agent that had no history to give.
+    console.error(`[acp] session/update stream for '${sessionId}' was still growing after ${maxRounds} settle rounds ` +
+        `(${count()} updates so far) — continuing anyway; later updates may be reordered or lost.`);
+}
+/**
+ * Replay one native session's history as wire events via `session/load` — see the file doc comment
+ * for why `session/load`, not `session/resume`.
+ *
+ * When the agent doesn't advertise `agentCapabilities.loadSession` (`connection.capabilities.loadSession`),
+ * this yields nothing **without ever calling `session/load`** — same "hidden grouping, not an error"
+ * contract as {@link listNativeSessions}, applied to the capability that actually gates replay.
+ *
+ * Every yielded event has already gone through {@link foldReplayEvents} (same mapping the live path
+ * uses, plus the same `agent_message` synthesis) and `validateWireEvent` (same outbound check the live path's
+ * `permission_request` events go through) — an event that fails validation is dropped with a
+ * diagnostic, never thrown, matching `validate.ts`'s own "drop + diagnostic, never an
+ * exception" design. `mapSessionUpdate` never produces `final_result` (Task 4's contract, unchanged
+ * here since this function adds no new event-producing path of its own) and `foldReplayEvents` adds
+ * no new event names beyond what `mapSessionUpdate` and this file's own `agent_message` synthesis
+ * already produce — both already appear in the server's understood vocabulary
+ * (`sessionUpdateMapper.test.ts`'s `SERVER_UNDERSTOOD_EVENT_NAMES`), so nothing here needs to extend
+ * it.
+ *
+ * ## `session/load` also activates the session, not just replays it — and Task 8 relies on that
+ *
+ * The `session/load` request below sends `mcpServers: []`. That is not incidental — `session/load`
+ * is not a read-only "give me the history" call: per its own spec, the agent restores this
+ * `sessionId` as its **current** session, the same way `session/new` would, just with history
+ * attached instead of starting empty.
+ *
+ * Task 8 resolved the fork this once handed forward: **Axom keeps prompting on
+ * `params.nativeSessionId`, the session `session/load` just activated**, rather than opening a fresh
+ * `session/new` and treating the replay as read-only history. `agentSessions.ts` receives a
+ * `nativeSessionId` on reconnect as well as on adoption (the server persists it and hands it back),
+ * so "open a new session and replay read-only" would silently drop the agent's own context on every
+ * single reconnect — a regression against the deleted Claude Code bridge, which really did resume.
+ * `AcpSession.attach` (`acpSession.ts`) is what that costs: the SDK's `ActiveSession` has a private
+ * constructor reachable only through `SessionBuilder.start()`, i.e. only through `session/new`, so
+ * driving an already-loaded `sessionId` means hand-building the same small `DrivenSession` surface
+ * around raw `session/prompt` / `session/cancel` requests and {@link ReplayCapture.listen}.
+ *
+ * `mcpServers: []` is consistent with the other path rather than a shortfall of this one:
+ * `AcpSession.open`'s `buildSession(cwd).start()` attaches no MCP servers either (`OpenSessionOptions`
+ * carries only `cwd`), because Axom does not configure MCP servers for external agents at all.
+ */
+export async function* replayNativeSession(connection, capture, params) {
+    if (!connection.capabilities.loadSession)
+        return;
+    // Arm before requesting — the agent may start sending session/update notifications for this
+    // sessionId as soon as it receives the request, and the capture's handler drops anything for a
+    // sessionId that isn't armed yet (see ReplayCapture.arm's doc comment).
+    capture.arm(params.nativeSessionId);
+    // The transport diverts updates for a session it does not know is handled here, because the SDK's
+    // router would otherwise drop them on the floor. During a replay this capture *is* the handler,
+    // so the claim has to be made explicitly — and withdrawn in the same `finally` that disarms.
+    const unmarkSession = connection.markSessionKnown(params.nativeSessionId);
+    let updates;
+    try {
+        const response = await connection.connection.agent.request(methods.agent.session.load, {
+            sessionId: params.nativeSessionId,
+            cwd: params.cwd,
+            mcpServers: [],
+        });
+        params.onLoaded?.(response);
+        // The response resolving is NOT the end of the replay — see {@link settleUpdates} for the SDK
+        // scheduling that makes `take()` on the spot return a partial history.
+        await settleUpdates(params.nativeSessionId, () => capture.count(params.nativeSessionId));
+    }
+    finally {
+        unmarkSession();
+        // In a `finally` because `arm()` has no other exit. A rejected `session/load` — a stale id the
+        // agent has since deleted, the case `AcpAgents.startSession` catches and falls back from — used
+        // to throw straight past `take()`, leaving the id armed and whatever had already been buffered
+        // for it held until the connection died. That contradicts this file's own claim that "the
+        // buffer's upper bound is whatever is currently being replayed": the fallback opens a *different*
+        // session id, so nothing would ever come back to take this one. `take()` is both halves at once
+        // (release the buffer, disarm), which is why the failure path calls the same function the
+        // success path does rather than a disarm of its own.
+        updates = capture.take(params.nativeSessionId);
+    }
+    for (const event of foldReplayEvents(updates)) {
+        const rejection = validateWireEvent(event);
+        if (rejection) {
+            console.error(`[acp] dropping a replayed event that fails validateWireEvent: ${rejection.reason} (session ${params.nativeSessionId})`);
+            continue;
+        }
+        yield event;
+    }
+}

package/dist/workstation/acp/auth.js

@@ -0,0 +1,80 @@
+/**
+ * ACP authentication: `authenticate({ methodId })`.
+ *
+ * The method is `authenticate`, **not** `auth/login` — that spelling appears nowhere in
+ * `@agentclientprotocol/sdk@1.4.0`; the spec draft this plan started from said otherwise and has
+ * been corrected (see the plan's "已核实的 SDK 事实").
+ *
+ * `methodId` must come from the agent's own advertised `authMethods` (surfaced on `AcpConnection` by
+ * Task 3): the ACP spec's `AuthMethodTerminal` doc comment says the client "MUST NOT pass this
+ * method to `authenticate`" — a terminal method carries its own `args`/`env` for a TUI the client
+ * would have to run as a *separate interactive process*, not a JSON-RPC round trip. So
+ * {@link AcpAuth.authenticate} refuses two shapes of bad input before ever writing to the wire: a
+ * `methodId` the agent never advertised, and one it advertised as `type: 'terminal'`.
+ *
+ * ## No authentication *state* lives here, deliberately
+ *
+ * There is no registry-sourced auth state (the plan's "已核实的 registry 事实" confirms the registry
+ * carries no auth fields at all) and ACP v1 has no "am I authenticated?" query. The only positive
+ * evidence anywhere in this client is a session an agent accepted, which `acpAgents.ts` records as
+ * `AuthObservation.authenticated?: true` — **true or absent, never `false`**.
+ *
+ * This class used to keep a local flag alongside that: it started `false`, documented as "unknown /
+ * not-yet-authenticated is treated the same as not authenticated", and flipped on `authenticate()`.
+ * That sentence is the exact conflation the rest of this branch exists to prevent —
+ * `ExternalAgentAuthState` has two members and neither of them is "not authenticated",
+ * `ExternalAgentAuthBadge` renders only those two, and a banned-word scan keeps the phrasing out of
+ * the UI. An agent already holding a good long-lived credential on disk read `false` there, so
+ * anyone who ever wired it to the roster would have shown that user a "sign in again" prompt
+ * indistinguishable from a real one. Nothing read it, so it is gone rather than reworded, together
+ * with `canLogout`/`logout()` — whose only effect beyond one RPC was flipping that same flag.
+ *
+ * `logout` itself is still visible where it is a fact rather than a state: `acpClient.ts` reduces
+ * `agentCapabilities.auth.logout != null` onto `AcpConnection.capabilities.logout`, which is where
+ * a future caller with an actual use for it should start.
+ */
+import { methods } from '@agentclientprotocol/sdk';
+/** `methodId` does not match any entry in `AcpConnection.authMethods` — the agent never advertised it. */
+export class AuthMethodNotAdvertisedError extends Error {
+}
+/**
+ * `methodId` names a real advertised method, but its `type` is `'terminal'`. ACP requires the client
+ * to run those as a separate interactive process, never to pass them to `authenticate`.
+ */
+export class TerminalAuthMethodError extends Error {
+}
+function describeAdvertised(connection) {
+    return connection.authMethods.length > 0 ? connection.authMethods.map((method) => method.id).join(', ') : '(none)';
+}
+/**
+ * The `authenticate` operation for one `AcpConnection`, and the two refusals that guard it. Holds no
+ * authentication state — see the file doc comment for why there is none to hold.
+ */
+export class AcpAuth {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /** The agent's advertised authentication methods, unchanged from `AcpConnection.authMethods`. */
+    get authMethods() {
+        return this.connection.authMethods;
+    }
+    /**
+     * Sends `authenticate({ methodId })` to the agent, after refusing two shapes of bad input the
+     * agent could not have asked for: a `methodId` it never advertised in `initialize`, and one it
+     * advertised as a terminal method (which ACP forbids passing here at all). Neither refusal talks
+     * to the agent — see `auth.test.ts` for how that is pinned (a sink file the fake agent only writes
+     * once it actually receives the request).
+     */
+    async authenticate(methodId) {
+        const method = this.connection.authMethods.find((candidate) => candidate.id === methodId);
+        if (!method) {
+            throw new AuthMethodNotAdvertisedError(`Agent did not advertise auth method '${methodId}'. Advertised methods: ${describeAdvertised(this.connection)}.`);
+        }
+        if (method.type === 'terminal') {
+            throw new TerminalAuthMethodError(`Auth method '${methodId}' is a terminal method; ACP requires the client run it as a separate ` +
+                'interactive process instead of passing it to authenticate().');
+        }
+        await this.connection.connection.agent.request(methods.agent.authenticate, { methodId });
+    }
+}

package/dist/workstation/acp/authUrlSniffer.js

@@ -0,0 +1,52 @@
+/**
+ * Catches a login URL an agent prints to stderr instead of delivering through
+ * `elicitation/create` — see this task's brief, spec §6.2. Measured on a real machine: with the
+ * client already declaring `elicitation.url` (`acpClient.ts`'s `clientCapabilities`), antigravity's
+ * `authenticate(oauth-personal)` sends no `elicitation/create` at all. It prints
+ * `"Open the following link to authenticate the ACP server: https://…"` to stderr and then blocks
+ * on a `localhost` callback. ACP does not require an agent to hand a URL to the client through
+ * elicitation, so this is a gap in the protocol, not a shortcut a particular agent took — and it
+ * means the elicitation channel alone leaves that agent's sign-in doing nothing when clicked.
+ *
+ * Global Constraint (this task's brief): the criterion may not name a vendor. No hostname, no
+ * domain, no agent id may appear here — a later mechanical scan checks the test suite for registry
+ * agent id literals. So the match is purely on the *shape* of the line: an absolute `https://` URL,
+ * plus wording that invites the reader to open it. Both conditions are required — an ordinary log
+ * line that happens to contain a URL (a settings path, a status report) must not match just because
+ * it has one, and a line that talks about opening something without ever naming a URL has nothing
+ * to hand out.
+ */
+/** Case-insensitive: the same verbs a login prompt actually uses to invite the click. */
+const INVITATION_WORDS = /\b(?:open|visit|authenticate)\b/i;
+/** An absolute `https://` URL, taken up to (not including) the next whitespace — never the prose around it. */
+const ABSOLUTE_URL = /https:\/\/\S+/;
+/**
+ * ANSI CSI escape sequences (`ESC [ <params> <final-letter>`, e.g. an SGR colour code like
+ * `\x1b[33m`). Stripped before matching anything else: `\bopen\b` finds no word boundary between
+ * the "33" and the "m" in `…\x1b[33mOpen…` — the escape sequence's own trailing letter reads as
+ * though it were fused onto the next word, so a coloured line misses entirely rather than
+ * partially. Most agents run non-interactively (no TTY) and suppress colour on their own, but not
+ * all of them do, and this is a silent total miss rather than a degraded match.
+ */
+// eslint-disable-next-line no-control-regex -- matching the literal ESC (0x1b) control character is the point
+const ANSI_ESCAPE = /\x1b\[[0-9;]*[A-Za-z]/g;
+/** Punctuation prose wraps a URL in (`<…>`, a trailing `.`, a comment in `(…)`) — never part of the URL itself. */
+const TRAILING_DECORATION = /[)\]>'".,]+$/;
+function stripAnsi(line) {
+    return line.replace(ANSI_ESCAPE, '');
+}
+/**
+ * Returns the URL if `line` both invites the reader to open something and contains an absolute
+ * `https://` URL, `undefined` otherwise. Takes only the URL itself, not surrounding prose on either
+ * side — including punctuation prose glues directly onto the end of it (`<https://x.test/a>.`
+ * yields `https://x.test/a`, not `https://x.test/a>.`).
+ */
+export function sniffAuthUrl(line) {
+    const clean = stripAnsi(line);
+    if (!INVITATION_WORDS.test(clean))
+        return undefined;
+    const match = ABSOLUTE_URL.exec(clean);
+    if (!match)
+        return undefined;
+    return match[0].replace(TRAILING_DECORATION, '');
+}