@av-pi-studio/client 0.0.92 → 0.0.94

package/dist/pistudio-client.d.ts

@@ -1,4 +1,4 @@
-import type { AgentCloneResponse, AgentCompactResponse, AgentCycleModelResponse, AgentExportHtmlResponse, AgentForkMessagesResponse, AgentForkResponse, AgentLastAssistantTextResponse, AgentListCommandsResponse, AgentNewSessionResponse, AgentSessionStatsResponse, AgentSetModelResponse, AgentSetSessionNameResponse, AgentStreamEvent, AgentSwitchSessionResponse, CreateAgentRequest, ExtensionPacksListResponse, ExtensionPacksSetResponse, FetchAgentTimelineResponse, SessionMessage, TimelineDirection } from "@av-pi-studio/protocol";
+import type { AgentCloneResponse, AgentCompactResponse, AgentCycleModelResponse, AgentExportHtmlResponse, AgentForkMessagesResponse, AgentForkResponse, AgentLastAssistantTextResponse, AgentListCommandsResponse, AgentNewSessionResponse, AgentSessionStatsResponse, AgentSetModelResponse, AgentSetSessionNameResponse, AgentStreamEvent, AgentSwitchSessionResponse, AgentUiPendingRequest, AgentUiRequest, AgentUiResolved, AgentUiResponse, AgentUiSurface, CreateAgentRequest, ExtensionPacksListResponse, ExtensionPacksSetResponse, FetchAgentTimelineResponse, ProviderAuthInfo, ProviderAuthType, SessionMessage, TimelineDirection } from "@av-pi-studio/protocol";
 import type { DaemonClient } from "./daemon-client.js";
 /**
  * High-level `PiStudioClient` SDK facade over the low-level `DaemonClient` driver.
@@ -169,8 +169,176 @@ export interface PiStudioProviderActions {
     /** Trigger an explicit provider snapshot refresh (no hidden revalidation). */
     refreshSnapshot(): Promise<unknown>;
 }
+/**
+ * The five `provider_auth_*` request/response pairs have real protocol schemas (sprint-055), but the
+ * per-flow progress push does **not** — it rides `sessionMessageBaseSchema`'s passthrough fallback,
+ * the established convention for this family (see `swe/features/provider-auth-rpc.md`
+ * § Registration style, and `checkout_status_update` / `file_changed` before it). So the push's
+ * shape is narrowed here with a local interface + type guard, mirroring how `TimelineHandle`
+ * narrows `agent_stream`.
+ */
+export interface ProviderAuthFlowEventPush {
+    type: "provider_auth_flow_event";
+    flowId: string;
+    event: {
+        kind: string;
+    } & Record<string, unknown>;
+}
+/** Narrows an inbound session message to the `provider_auth_flow_event` push. */
+export declare function isProviderAuthFlowEvent(message: unknown): message is ProviderAuthFlowEventPush;
+/** One question Pi's auth engine asks mid-flow. `promptKind` decides the input control; a `select`
+ *  carries its own option list. Answering means resolving `ProviderAuthCallbacks.prompt`. */
+export interface ProviderAuthPromptUi {
+    promptId: string;
+    promptKind: "text" | "secret" | "select" | "manual_code";
+    message: string;
+    placeholder?: string;
+    options?: readonly {
+        id: string;
+        label: string;
+        description?: string;
+    }[];
+    /**
+     * Aborts when this specific prompt is cancelled out of band — Pi races a `manual_code` prompt
+     * against its own OAuth callback server, so the callback winning cancels the question while the
+     * flow carries on. A view MUST drop the input when this fires (and keep the rest of the flow's
+     * presentation): the promise it returned from `prompt` is discarded by the SDK, so nothing else
+     * tells it the question is gone. Also aborts when the flow itself ends.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * The `notify()`-sourced events the daemon forwards verbatim. Carries no secret by construction —
+ * a prompt *value* travels only in the `provider_auth_respond_request` payload, never in an event.
+ * Unknown future kinds still reach `onEvent` (append-only wire rule), so a view must tolerate them.
+ */
+export type ProviderAuthNotifyEvent = {
+    kind: "info";
+    message: string;
+    links?: readonly {
+        url: string;
+        label?: string;
+    }[];
+} | {
+    kind: "auth_url";
+    url: string;
+    instructions?: string;
+} | {
+    kind: "device_code";
+    userCode: string;
+    verificationUri: string;
+    intervalSeconds?: number;
+    expiresInSeconds?: number;
+} | {
+    kind: "progress";
+    message: string;
+};
+/**
+ * Every event a login-flow view reduces over: the daemon's notify events plus the three the SDK
+ * driver consumes itself (`prompt` is delivered through `callbacks.prompt`, `prompt_cancelled`
+ * rejects that pending prompt, `done` settles `loginProvider`). A view re-dispatches those three
+ * into its own reducer from the callback/promise boundary.
+ */
+export type ProviderAuthFlowUiEvent = ProviderAuthNotifyEvent | ({
+    kind: "prompt";
+} & ProviderAuthPromptUi) | {
+    kind: "prompt_cancelled";
+    promptId: string;
+} | {
+    kind: "done";
+    ok: boolean;
+    error?: string;
+};
+export interface ProviderAuthCallbacks {
+    /**
+     * Ask the user for a value. Resolve with the answer; **reject to cancel the whole flow**.
+     * The returned promise is also rejected by the SDK when the daemon cancels the prompt
+     * out-of-band (an OAuth callback won the race) or the flow otherwise ends — a view should treat
+     * a rejection as "stop showing this input", not as an error to report.
+     */
+    prompt(prompt: ProviderAuthPromptUi): Promise<string>;
+    /** Presentation/progress events. Never carries a secret. */
+    onEvent?(event: ProviderAuthNotifyEvent): void;
+}
+export interface ProviderAuthLoginOptions {
+    /** Abort to cancel the flow server-side. The promise still settles from the terminal `done`. */
+    signal?: AbortSignal;
+}
+/** How a login flow ended. `error` is a daemon-sanitized reason, never a credential. */
+export interface ProviderAuthLoginResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * A domain failure reported *in a response payload* rather than as an `rpc_error`. This family
+ * puts domain errors in payloads by design (`swe/features/provider-auth-rpc.md`), so a caller that
+ * only catches `RpcError` would silently read an empty provider list as "nothing configured".
+ */
+export declare class ProviderAuthError extends Error {
+    readonly operation: "list" | "logout";
+    constructor(message: string, operation: "list" | "logout");
+}
+/**
+ * Local-clock anchor stamped when the SDK receives the push. Deliberately **not** shaped like
+ * `AgentStreamEventMeta` (daemon `timestamp`/`seq`, line 49): the daemon may run on another host,
+ * and this family's whole timeout-display story (`extension-ui-client-sdk.md` § Timeout display)
+ * depends on the client noticing that its own clock and the daemon's `createdAt` may be skewed —
+ * reusing the stream shape here would bake that skew in silently.
+ */
+export interface AgentUiEventMeta {
+    receivedAt: number;
+}
+/**
+ * `respondToUi`'s outcome. `not_found` is the **normal** result of a multi-client broadcast race
+ * (another client answered first) — it is returned, not thrown, so a caller cannot ignore it
+ * without a type error, but also is not forced into a `try`/`catch` around the happy path. Compare
+ * `AgentUiError` below, which is used for `listAgentUi`'s genuinely-exceptional failure instead.
+ */
+export type AgentUiRespondResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "not_found" | "unsupported" | string;
+};
+/**
+ * A domain failure reported *in a response payload* rather than as an `rpc_error` — same hazard
+ * `ProviderAuthError` (line 313) guards against. Unlike `AgentUiRespondResult` above, a failed
+ * snapshot is genuinely exceptional, so this one throws.
+ */
+export declare class AgentUiError extends Error {
+    readonly operation: "list";
+    constructor(message: string, operation: "list");
+}
+/** Narrows an inbound session message to the `agent_ui_request` broadcast. */
+export declare function isAgentUiRequest(message: unknown): message is AgentUiRequest;
+/** Narrows an inbound session message to the `agent_ui_resolved` broadcast. */
+export declare function isAgentUiResolved(message: unknown): message is AgentUiResolved;
+/** The `agent_archived` lifecycle push (`messages.ts`'s `agentArchivedSchema`). */
+export interface AgentArchivedMessage {
+    type: "agent_archived";
+    agentId: string;
+    archivedAt?: string;
+}
+/** The `agent_deleted` lifecycle push (`messages.ts`'s `agentDeletedSchema`). */
+export interface AgentDeletedMessage {
+    type: "agent_deleted";
+    agentId: string;
+}
+/**
+ * Narrows an inbound session message to `agent_archived`. **Not** part of the `agent_ui_*` family —
+ * exported so a controller (task-003) can prune retained extension-UI state on archive/delete.
+ * Deliberately **not** `onAgentUpdate` (line 418): `AgentManager.archiveAgent`/`deleteAgent` call
+ * `broadcastArchived`/`broadcastDeleted` exclusively and never the `agent_update`-emitting
+ * `broadcast(record)` path, so `onAgentUpdate` (which filters `type === "agent_update"`) can never
+ * see an archive or delete.
+ */
+export declare function isAgentArchived(message: unknown): message is AgentArchivedMessage;
+/** Narrows an inbound session message to `agent_deleted`. See `isAgentArchived`. */
+export declare function isAgentDeleted(message: unknown): message is AgentDeletedMessage;
 export declare class PiStudioClient {
     private readonly daemon;
+    /** Exactly one login flow per client instance, per `swe/features/provider-auth-rpc.md`. */
+    private activeProviderAuthFlow;
     constructor(daemon: DaemonClient);
     get connection(): DaemonClient;
     /**
@@ -209,6 +377,73 @@ export declare class PiStudioClient {
     onAgentUpdate(handler: PiStudioAgentUpdateHandler): () => void;
     /** Subscribe to ALL `workspace_update` events (any workspace). */
     onWorkspaceUpdate(handler: PiStudioWorkspaceUpdateHandler): () => void;
+    /** True iff the daemon advertised the `providerAuth` capability in `server_info.features`. */
+    hasProviderAuthCapability(): boolean;
+    /** Every provider's login capability + current state. */
+    listProviderAuth(): Promise<ProviderAuthInfo[]>;
+    /** Clear a provider's stored credential. `stillConfigured` flags a surviving ambient one
+     *  (e.g. an env var) — the provider may still show as configured after this resolves. */
+    logoutProvider(provider: string): Promise<{
+        stillConfigured?: boolean;
+    }>;
+    /**
+     * Drive one remote provider login end to end. `callbacks` answers Pi's questions and observes
+     * presentation events; the returned promise settles only once — from the flow's terminal `done`
+     * event, an immediate login rejection, or a lost connection — never left hanging.
+     *
+     * Only one flow may run per client instance; a second concurrent call rejects locally without
+     * sending a second `provider_auth_login_request`.
+     */
+    loginProvider(provider: string, authType: ProviderAuthType, callbacks: ProviderAuthCallbacks, opts?: ProviderAuthLoginOptions): Promise<ProviderAuthLoginResult>;
+    /** Route one inbound flow-event push: buffer until `flowId` is known, drop stale/unknown flows,
+     *  else dispatch by `kind`. */
+    private routeProviderAuthEvent;
+    private dispatchProviderAuthEvent;
+    /** Ask the caller for a value, racing its answer against an out-of-band `prompt_cancelled`
+     *  (an OAuth callback can win first). Never lets an unanswered promise dangle: a caller refusal
+     *  or a failed `respond` RPC settles the whole flow as `connection_lost` — a best-effort
+     *  server-side cancel is fired alongside, but the flow's OWN promise does not wait on it (that
+     *  RPC is just as unreachable as the one that failed, so awaiting it left the dialog stuck
+     *  forever — the live defect this comment now documents, sprint-065/task-007).
+     */
+    private handleProviderAuthPrompt;
+    /** The single place a flow ends. Idempotent — whichever path (a `done` event, a lost connection,
+     *  an immediate login rejection) settles it first wins; releases every subscription exactly once. */
+    private settleProviderAuthFlow;
+    /**
+     * Subscribe to every `agent_ui_request` broadcast (any agent) — a new dialog, a fire-and-forget
+     * UI event, or a surface upsert/clear. `meta.receivedAt` is stamped here, not forwarded from the
+     * wire (see `AgentUiEventMeta`).
+     */
+    onAgentUiRequest(handler: (event: AgentUiRequest, meta: AgentUiEventMeta) => void): () => void;
+    /** Subscribe to every `agent_ui_resolved` broadcast (any agent) — a dialog is no longer
+     *  answerable (answered elsewhere, cancelled, timed out, or the agent was swept). */
+    onAgentUiResolved(handler: (event: AgentUiResolved) => void): () => void;
+    /**
+     * Answer a pending extension-UI dialog. `uiRequestId` is the dialog's id (`AgentUiRequest.requestId`
+     * off the wire) — **not** the RPC's own `requestId`, which `daemon.request` stamps separately; do
+     * not collapse the two. Resolves `{ ok: false, reason }` rather than throwing when the daemon
+     * reports a domain failure — `reason` forwards the daemon's string verbatim (open, not
+     * relabelled: `not_found` covers answered-elsewhere, a bogus id, and an already-swept agent
+     * alike). A transport-level `RpcError` still rejects; that is not a domain outcome.
+     */
+    respondToUi(uiRequestId: string, response: AgentUiResponse): Promise<AgentUiRespondResult>;
+    /**
+     * Reconnect catch-up snapshot: every pending dialog and retained surface, for one agent or all.
+     * Throws `AgentUiError` on a failed snapshot — unlike `respondToUi`, this has no benign failure
+     * mode to return instead of throw.
+     */
+    listAgentUi(agentId?: string): Promise<{
+        pending: AgentUiPendingRequest[];
+        surfaces: AgentUiSurface[];
+    }>;
+    /**
+     * True iff the daemon advertised the `extensionUi` capability in `server_info.features`. **Not**
+     * named `supportsExtensionUi()` — that name is already the *provider* capability flag
+     * (`protocol/src/provider-manifest.ts`, "this provider forwards UI events"), a different question
+     * from "does this daemon speak the `agent_ui_*` RPC family at all".
+     */
+    extensionUiAvailable(): boolean;
 }
 /** Convenience re-export of the import operation (not agent-scoped). */
 export declare function importAgentSession(daemon: DaemonClient, args: {

package/dist/pistudio-client.js

@@ -1,6 +1,85 @@
+/** Narrows an inbound session message to the `provider_auth_flow_event` push. */
+export function isProviderAuthFlowEvent(message) {
+    const m = message;
+    if (!m || m.type !== "provider_auth_flow_event" || typeof m.flowId !== "string")
+        return false;
+    const event = m.event;
+    return typeof event === "object" && event !== null && typeof event.kind === "string";
+}
+/**
+ * A domain failure reported *in a response payload* rather than as an `rpc_error`. This family
+ * puts domain errors in payloads by design (`swe/features/provider-auth-rpc.md`), so a caller that
+ * only catches `RpcError` would silently read an empty provider list as "nothing configured".
+ */
+export class ProviderAuthError extends Error {
+    operation;
+    constructor(message, operation) {
+        super(message);
+        this.operation = operation;
+        this.name = "ProviderAuthError";
+    }
+}
+/** Rejection used for a prompt the daemon cancelled out-of-band — distinguishes "the user refused"
+ *  (cancel the flow) from "this question is moot now" (let the flow continue). */
+class PromptCancelledError extends Error {
+    promptId;
+    constructor(promptId) {
+        super("prompt_cancelled");
+        this.promptId = promptId;
+        this.name = "PromptCancelledError";
+    }
+}
+/**
+ * A domain failure reported *in a response payload* rather than as an `rpc_error` — same hazard
+ * `ProviderAuthError` (line 313) guards against. Unlike `AgentUiRespondResult` above, a failed
+ * snapshot is genuinely exceptional, so this one throws.
+ */
+export class AgentUiError extends Error {
+    operation;
+    constructor(message, operation) {
+        super(message);
+        this.operation = operation;
+        this.name = "AgentUiError";
+    }
+}
+/** Narrows an inbound session message to the `agent_ui_request` broadcast. */
+export function isAgentUiRequest(message) {
+    const m = message;
+    return (!!m &&
+        m.type === "agent_ui_request" &&
+        typeof m.requestId === "string" &&
+        typeof m.agentId === "string");
+}
+/** Narrows an inbound session message to the `agent_ui_resolved` broadcast. */
+export function isAgentUiResolved(message) {
+    const m = message;
+    return (!!m &&
+        m.type === "agent_ui_resolved" &&
+        typeof m.requestId === "string" &&
+        typeof m.agentId === "string");
+}
+/**
+ * Narrows an inbound session message to `agent_archived`. **Not** part of the `agent_ui_*` family —
+ * exported so a controller (task-003) can prune retained extension-UI state on archive/delete.
+ * Deliberately **not** `onAgentUpdate` (line 418): `AgentManager.archiveAgent`/`deleteAgent` call
+ * `broadcastArchived`/`broadcastDeleted` exclusively and never the `agent_update`-emitting
+ * `broadcast(record)` path, so `onAgentUpdate` (which filters `type === "agent_update"`) can never
+ * see an archive or delete.
+ */
+export function isAgentArchived(message) {
+    const m = message;
+    return !!m && m.type === "agent_archived" && typeof m.agentId === "string";
+}
+/** Narrows an inbound session message to `agent_deleted`. See `isAgentArchived`. */
+export function isAgentDeleted(message) {
+    const m = message;
+    return !!m && m.type === "agent_deleted" && typeof m.agentId === "string";
+}
 // ─── Facade implementation ──────────────────────────────────────────────────────
 export class PiStudioClient {
     daemon;
+    /** Exactly one login flow per client instance, per `swe/features/provider-auth-rpc.md`. */
+    activeProviderAuthFlow = null;
     constructor(daemon) {
         this.daemon = daemon;
     }
@@ -63,6 +142,284 @@ export class PiStudioClient {
             }
         });
     }
+    // ─── Provider auth ──────────────────────────────────────────────────────────
+    /** True iff the daemon advertised the `providerAuth` capability in `server_info.features`. */
+    hasProviderAuthCapability() {
+        return this.daemon.hasFeature("providerAuth");
+    }
+    /** Every provider's login capability + current state. */
+    async listProviderAuth() {
+        const payload = await this.daemon.request("provider_auth_list_request", {});
+        if (!payload.ok) {
+            throw new ProviderAuthError(payload.error ?? "failed to list provider auth state", "list");
+        }
+        return payload.providers;
+    }
+    /** Clear a provider's stored credential. `stillConfigured` flags a surviving ambient one
+     *  (e.g. an env var) — the provider may still show as configured after this resolves. */
+    async logoutProvider(provider) {
+        const payload = await this.daemon.request("provider_auth_logout_request", { provider });
+        if (!payload.ok) {
+            throw new ProviderAuthError(payload.error ?? "failed to log out", "logout");
+        }
+        return { stillConfigured: payload.stillConfigured };
+    }
+    /**
+     * Drive one remote provider login end to end. `callbacks` answers Pi's questions and observes
+     * presentation events; the returned promise settles only once — from the flow's terminal `done`
+     * event, an immediate login rejection, or a lost connection — never left hanging.
+     *
+     * Only one flow may run per client instance; a second concurrent call rejects locally without
+     * sending a second `provider_auth_login_request`.
+     */
+    async loginProvider(provider, authType, callbacks, opts) {
+        if (this.activeProviderAuthFlow) {
+            throw new Error("a provider-auth login is already in progress for this client");
+        }
+        let settleResult;
+        const resultPromise = new Promise((resolve) => {
+            settleResult = resolve;
+        });
+        const flow = {
+            flowId: null,
+            buffered: [],
+            pendingPrompt: null,
+            cancelRequested: opts?.signal?.aborted ?? false,
+            terminal: false,
+            settle: settleResult,
+            unsubscribe: null,
+        };
+        this.activeProviderAuthFlow = flow;
+        // Subscribe BEFORE sending the login request: the daemon starts Pi's flow the moment it
+        // handles the RPC, so a `prompt`/`auth_url` can legitimately arrive before this request's own
+        // response does. Subscribing after the await would silently drop it and hang the dialog.
+        const unsubMessages = this.daemon.onSessionMessage((message) => {
+            if (isProviderAuthFlowEvent(message))
+                this.routeProviderAuthEvent(flow, message, callbacks);
+        });
+        const unsubState = this.daemon.onStateChange((state) => {
+            if (state === "closed") {
+                this.settleProviderAuthFlow(flow, { ok: false, error: "connection_lost" });
+            }
+        });
+        let onAbort = null;
+        if (opts?.signal) {
+            const signal = opts.signal;
+            onAbort = () => {
+                flow.cancelRequested = true;
+                if (flow.flowId && !flow.terminal) {
+                    this.daemon
+                        .request("provider_auth_cancel_request", { flowId: flow.flowId })
+                        .catch(() => { });
+                }
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            flow.unsubscribe = () => {
+                unsubMessages();
+                unsubState();
+                signal.removeEventListener("abort", onAbort);
+            };
+        }
+        else {
+            flow.unsubscribe = () => {
+                unsubMessages();
+                unsubState();
+            };
+        }
+        try {
+            const response = await this.daemon.request("provider_auth_login_request", { provider, authType });
+            if (flow.terminal)
+                return resultPromise;
+            if (!response.ok || !response.flowId) {
+                this.settleProviderAuthFlow(flow, { ok: false, error: response.error });
+                return resultPromise;
+            }
+            flow.flowId = response.flowId;
+            const buffered = flow.buffered;
+            flow.buffered = [];
+            for (const message of buffered) {
+                if (message.flowId === flow.flowId) {
+                    this.dispatchProviderAuthEvent(flow, message.event, callbacks);
+                }
+            }
+            if (flow.cancelRequested && !flow.terminal) {
+                this.daemon
+                    .request("provider_auth_cancel_request", { flowId: flow.flowId })
+                    .catch(() => { });
+            }
+        }
+        catch {
+            if (!flow.terminal) {
+                this.settleProviderAuthFlow(flow, { ok: false, error: "connection_lost" });
+            }
+        }
+        return resultPromise;
+    }
+    /** Route one inbound flow-event push: buffer until `flowId` is known, drop stale/unknown flows,
+     *  else dispatch by `kind`. */
+    routeProviderAuthEvent(flow, message, callbacks) {
+        if (flow.terminal)
+            return;
+        if (flow.flowId === null) {
+            flow.buffered.push(message);
+            return;
+        }
+        if (message.flowId !== flow.flowId)
+            return;
+        this.dispatchProviderAuthEvent(flow, message.event, callbacks);
+    }
+    dispatchProviderAuthEvent(flow, event, callbacks) {
+        switch (event.kind) {
+            case "done":
+                this.settleProviderAuthFlow(flow, {
+                    ok: Boolean(event.ok),
+                    error: typeof event.error === "string" ? event.error : undefined,
+                });
+                return;
+            case "prompt_cancelled": {
+                const promptId = event.promptId;
+                if (flow.pendingPrompt && flow.pendingPrompt.promptId === promptId) {
+                    flow.pendingPrompt.reject(new PromptCancelledError(promptId));
+                    flow.pendingPrompt = null;
+                }
+                return;
+            }
+            case "prompt":
+                void this.handleProviderAuthPrompt(flow, event, callbacks);
+                return;
+            default:
+                callbacks.onEvent?.(event);
+                return;
+        }
+    }
+    /** Ask the caller for a value, racing its answer against an out-of-band `prompt_cancelled`
+     *  (an OAuth callback can win first). Never lets an unanswered promise dangle: a caller refusal
+     *  or a failed `respond` RPC settles the whole flow as `connection_lost` — a best-effort
+     *  server-side cancel is fired alongside, but the flow's OWN promise does not wait on it (that
+     *  RPC is just as unreachable as the one that failed, so awaiting it left the dialog stuck
+     *  forever — the live defect this comment now documents, sprint-065/task-007).
+     */
+    async handleProviderAuthPrompt(flow, event, callbacks) {
+        // Aborted when this prompt is cancelled out of band (or the flow ends). The view cannot learn
+        // that any other way: `prompt_cancelled` is consumed here rather than forwarded to `onEvent`,
+        // and the promise the view returned is simply discarded by the race below — so without this
+        // signal a `manual_code` input stays on screen after the OAuth callback already won.
+        const cancelledController = new AbortController();
+        const prompt = {
+            promptId: event.promptId,
+            promptKind: event.promptKind,
+            message: event.message,
+            placeholder: event.placeholder,
+            options: event.options,
+            signal: cancelledController.signal,
+        };
+        let rejectCancelled;
+        const cancelled = new Promise((_resolve, reject) => {
+            rejectCancelled = reject;
+        });
+        cancelled.catch(() => { });
+        flow.pendingPrompt = {
+            promptId: prompt.promptId,
+            reject: (error) => {
+                cancelledController.abort();
+                rejectCancelled(error);
+            },
+        };
+        const answered = callbacks.prompt(prompt);
+        answered.catch(() => { });
+        try {
+            const value = await Promise.race([answered, cancelled]);
+            if (flow.terminal)
+                return;
+            flow.pendingPrompt = null;
+            await this.daemon.request("provider_auth_respond_request", {
+                flowId: flow.flowId,
+                promptId: prompt.promptId,
+                value,
+            });
+        }
+        catch (err) {
+            flow.pendingPrompt = null;
+            if (flow.terminal || err instanceof PromptCancelledError)
+                return;
+            if (flow.flowId) {
+                this.daemon
+                    .request("provider_auth_cancel_request", { flowId: flow.flowId })
+                    .catch(() => { });
+            }
+            this.settleProviderAuthFlow(flow, { ok: false, error: "connection_lost" });
+        }
+    }
+    /** The single place a flow ends. Idempotent — whichever path (a `done` event, a lost connection,
+     *  an immediate login rejection) settles it first wins; releases every subscription exactly once. */
+    settleProviderAuthFlow(flow, result) {
+        if (flow.terminal)
+            return;
+        flow.terminal = true;
+        if (flow.pendingPrompt) {
+            flow.pendingPrompt.reject(new Error("provider-auth: flow ended"));
+            flow.pendingPrompt = null;
+        }
+        flow.unsubscribe?.();
+        if (this.activeProviderAuthFlow === flow)
+            this.activeProviderAuthFlow = null;
+        flow.settle(result);
+    }
+    // ─── Extension UI (agent_ui_*, sprint-066) ─────────────────────────────────
+    /**
+     * Subscribe to every `agent_ui_request` broadcast (any agent) — a new dialog, a fire-and-forget
+     * UI event, or a surface upsert/clear. `meta.receivedAt` is stamped here, not forwarded from the
+     * wire (see `AgentUiEventMeta`).
+     */
+    onAgentUiRequest(handler) {
+        return this.daemon.onSessionMessage((msg) => {
+            if (isAgentUiRequest(msg))
+                handler(msg, { receivedAt: Date.now() });
+        });
+    }
+    /** Subscribe to every `agent_ui_resolved` broadcast (any agent) — a dialog is no longer
+     *  answerable (answered elsewhere, cancelled, timed out, or the agent was swept). */
+    onAgentUiResolved(handler) {
+        return this.daemon.onSessionMessage((msg) => {
+            if (isAgentUiResolved(msg))
+                handler(msg);
+        });
+    }
+    /**
+     * Answer a pending extension-UI dialog. `uiRequestId` is the dialog's id (`AgentUiRequest.requestId`
+     * off the wire) — **not** the RPC's own `requestId`, which `daemon.request` stamps separately; do
+     * not collapse the two. Resolves `{ ok: false, reason }` rather than throwing when the daemon
+     * reports a domain failure — `reason` forwards the daemon's string verbatim (open, not
+     * relabelled: `not_found` covers answered-elsewhere, a bogus id, and an already-swept agent
+     * alike). A transport-level `RpcError` still rejects; that is not a domain outcome.
+     */
+    async respondToUi(uiRequestId, response) {
+        const payload = await this.daemon.request("agent_ui_respond_request", { uiRequestId, response });
+        if (!payload.ok)
+            return { ok: false, reason: payload.error ?? "unknown" };
+        return { ok: true };
+    }
+    /**
+     * Reconnect catch-up snapshot: every pending dialog and retained surface, for one agent or all.
+     * Throws `AgentUiError` on a failed snapshot — unlike `respondToUi`, this has no benign failure
+     * mode to return instead of throw.
+     */
+    async listAgentUi(agentId) {
+        const payload = await this.daemon.request("agent_ui_list_request", agentId ? { agentId } : {});
+        if (!payload.ok) {
+            throw new AgentUiError(payload.error ?? "failed to list extension UI state", "list");
+        }
+        return { pending: payload.pending ?? [], surfaces: payload.surfaces ?? [] };
+    }
+    /**
+     * True iff the daemon advertised the `extensionUi` capability in `server_info.features`. **Not**
+     * named `supportsExtensionUi()` — that name is already the *provider* capability flag
+     * (`protocol/src/provider-manifest.ts`, "this provider forwards UI events"), a different question
+     * from "does this daemon speak the `agent_ui_*` RPC family at all".
+     */
+    extensionUiAvailable() {
+        return this.daemon.hasFeature("extensionUi");
+    }
 }
 // ─── Handle classes ──────────────────────────────────────────────────────────────
 class TimelineHandle {

package/dist/test-support/scripted-daemon.d.ts

@@ -0,0 +1,34 @@
+import { DaemonClient } from "../daemon-client.js";
+import { PiStudioClient } from "../pistudio-client.js";
+import type { Transport } from "../transport.js";
+/**
+ * Scripted in-memory daemon transport, shared across `pistudio-client.test.ts` (sprint-055+) and
+ * `agent-ui-controller.test.ts` (sprint-067/task-003). Speaks just enough of the protocol for the
+ * facade/controller tests: completes the handshake, echoes responses correlated by `requestId`,
+ * and can push broadcasts or drop the connection on command.
+ *
+ * `features` is the **live** object read on every `hello` — mutate it in place
+ * (`fake.features.extensionUi = true`) before calling `daemon.connect()` again to simulate a
+ * reconnect where the daemon-advertised capability set changed.
+ */
+export interface ScriptedDaemon {
+    transport: Transport;
+    sent: Array<Record<string, unknown>>;
+    features: Record<string, boolean>;
+    push: (sessionMessage: Record<string, unknown>) => void;
+    /** Simulate the socket dying mid-session (distinct from a clean RPC response). */
+    drop: (reason?: string) => void;
+}
+export declare function makeScriptedDaemon(opts?: {
+    features?: Record<string, boolean>;
+}): ScriptedDaemon;
+export interface ScriptedFacade {
+    client: PiStudioClient;
+    daemon: DaemonClient;
+    fake: ScriptedDaemon;
+}
+/** Builds a connected `PiStudioClient` over `makeScriptedDaemon`. */
+export declare function makeFacade(opts?: {
+    features?: Record<string, boolean>;
+}): Promise<ScriptedFacade>;
+//# sourceMappingURL=scripted-daemon.d.ts.map