@av-pi-studio/client 0.0.93 → 0.0.94

package/dist/agent-ui-controller.d.ts

@@ -0,0 +1,39 @@
+import type { AgentUiResponse } from "@av-pi-studio/protocol";
+import { type AgentUiEffect, type AgentUiState } from "./agent-ui-state.js";
+import { type AgentUiRespondResult, type PiStudioClient } from "./pistudio-client.js";
+/**
+ * Impure wiring layer that drives task-002's reducer from task-001's SDK
+ * (`swe/features/extension-ui-client-sdk.md` § Controller). Owns the three things a consumer would
+ * otherwise get wrong: subscribe-then-list rehydration ordering, automatic re-sync on reconnect
+ * (never left to the consumer — `disconnected` is a one-way door in the reducer without it), and
+ * `agent_removed` pruning on agent archive/delete.
+ *
+ * **Rehydration is subscribe-then-list, merge is "replace, discard, apply".** The two `agent_ui_*`
+ * subscriptions attach before the first `listAgentUi()` call, queueing whatever arrives while it is
+ * in flight. When the snapshot lands: dispatch `snapshot` (wholesale replace), **discard** every
+ * queued dialog/surface event (already reflected in the snapshot — the socket is one ordered stream
+ * and the daemon composed the snapshot from state that postdates them), and **apply** every queued
+ * transient exactly once (nothing retains a transient, so it is genuinely new).
+ *
+ * **Pruning rides `agent_archived`/`agent_deleted`, never `onAgentUpdate`.** Verified against
+ * `agent-manager.ts`: `archiveAgent`/`deleteAgent` call `broadcastArchived`/`broadcastDeleted`
+ * exclusively and never the `agent_update`-emitting path, so a pruner wired to `onAgentUpdate` would
+ * silently never fire — dialogs would still clear (the daemon broadcasts `agent_ui_resolved` for
+ * those), so only surfaces would leak, invisibly, after every archive.
+ */
+export interface AgentUiController {
+    getState(): AgentUiState;
+    /** Fires on every committed transition; `effects` are the effects of that transition only. */
+    subscribe(listener: (state: AgentUiState, effects: AgentUiEffect[]) => void): () => void;
+    respond(uiRequestId: string, response: AgentUiResponse): Promise<AgentUiRespondResult>;
+    /** Escape hatch; reconnect already triggers this internally — never required in normal operation. */
+    resync(): Promise<void>;
+    dispose(): void;
+}
+export interface AgentUiControllerOptions {
+    /** Reported once per unknown fire-and-forget method for the controller's lifetime. Falls back to
+     *  `console.warn` when omitted. */
+    onUnknownMethod?: (method: string) => void;
+}
+export declare function createAgentUiController(client: PiStudioClient, opts?: AgentUiControllerOptions): AgentUiController;
+//# sourceMappingURL=agent-ui-controller.d.ts.map

package/dist/agent-ui-controller.js

@@ -0,0 +1,157 @@
+import { initialAgentUiState, reduce, } from "./agent-ui-state.js";
+import { isAgentArchived, isAgentDeleted, } from "./pistudio-client.js";
+/** Predicate ladder mirrored from the reducer, used ONLY to decide whether a queued event is
+ *  discarded (dialog/surface — already reflected in the snapshot that supersedes it) or replayed
+ *  (transient — genuinely new). Never a method list. */
+function classifyUiRequest(event) {
+    if (event.expectsResponse)
+        return "dialog";
+    if (event.surfaceKey !== undefined)
+        return "surface";
+    return "transient";
+}
+export function createAgentUiController(client, opts = {}) {
+    let state = initialAgentUiState;
+    const listeners = new Set();
+    const reportedUnknownMethods = new Set();
+    let disposed = false;
+    /** True while a `listAgentUi()` call is in flight; the two `agent_ui_*` subscriptions queue
+     *  instead of committing while this is true. */
+    let queueing = false;
+    let queue = [];
+    /** Bumped at the start of every `resync()` attempt. A response whose generation no longer matches
+     *  the latest one was superseded and commits nothing — "last write wins", by start order, not by
+     *  response arrival order (responses are not guaranteed to resolve in the order they were sent). */
+    let generation = 0;
+    function commit(action) {
+        if (disposed)
+            return;
+        const result = reduce(state, action);
+        state = result.state;
+        if (action.type === "ui_request" &&
+            classifyUiRequest(action.event) === "transient" &&
+            result.effects.length === 0) {
+            reportUnknownMethod(action.event.method);
+        }
+        for (const listener of listeners)
+            listener(state, result.effects);
+    }
+    function reportUnknownMethod(method) {
+        if (reportedUnknownMethods.has(method))
+            return;
+        reportedUnknownMethods.add(method);
+        if (opts.onUnknownMethod)
+            opts.onUnknownMethod(method);
+        else
+            console.warn(`agent-ui-controller: unknown extension-UI method "${method}"`);
+    }
+    async function resync() {
+        if (disposed)
+            return;
+        // Capability gating: stays inert, no RPC — an ungated call earns an rpc_error from an older
+        // daemon. Re-checked on every call (including every reconnect), because the daemon on the
+        // other end may have been upgraded since the last check.
+        if (!client.extensionUiAvailable())
+            return;
+        const myGeneration = ++generation;
+        // Only reset the window when transitioning from "not queueing" — an overlapping resync joins
+        // the existing window instead of dropping whatever it already collected, so a superseded
+        // resync never causes a queued transient to be silently lost.
+        if (!queueing) {
+            queueing = true;
+            queue = [];
+        }
+        let snapshot;
+        try {
+            snapshot = await client.listAgentUi();
+        }
+        catch (err) {
+            if (disposed || myGeneration !== generation)
+                return; // superseded: the newer resync owns the window
+            queueing = false;
+            queue = [];
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`agent-ui-controller: failed to sync extension UI state: ${message}`);
+            return;
+        }
+        if (disposed || myGeneration !== generation)
+            return; // superseded: do not commit, do not touch the queue
+        queueing = false;
+        const drained = queue;
+        queue = [];
+        commit({ type: "snapshot", pending: snapshot.pending, surfaces: snapshot.surfaces });
+        for (const action of drained) {
+            if (action.type === "ui_request" && classifyUiRequest(action.event) === "transient") {
+                commit(action);
+            }
+            // Every other queued action (dialog/surface ui_request, every ui_resolved) is already
+            // reflected in the snapshot just committed above — discarded, never replayed.
+        }
+    }
+    const unsubscribeRequest = client.onAgentUiRequest((event, meta) => {
+        const action = { type: "ui_request", event, meta };
+        if (queueing)
+            queue.push(action);
+        else
+            commit(action);
+    });
+    const unsubscribeResolved = client.onAgentUiResolved((event) => {
+        const action = { type: "ui_resolved", event };
+        if (queueing)
+            queue.push(action);
+        else
+            commit(action);
+    });
+    const unsubscribePrune = client.connection.onSessionMessage((msg) => {
+        if (isAgentArchived(msg) || isAgentDeleted(msg)) {
+            commit({ type: "agent_removed", agentId: msg.agentId });
+        }
+    });
+    const unsubscribeState = client.connection.onStateChange((connState) => {
+        if (connState === "closed" || connState === "closing") {
+            commit({ type: "disconnected" });
+        }
+        else if (connState === "open") {
+            void resync();
+        }
+        // "idle"/"connecting" carry no actionable transition here.
+    });
+    // Kick off the first sync immediately if the daemon is already connected and capable — the
+    // common case, since a controller is normally constructed against an already-open client. If
+    // the client is not yet open, `extensionUiAvailable()` is false here (no features known yet) and
+    // this is a no-op; the eventual real "open" transition above triggers the one-and-only initial
+    // sync, so there is no risk of a duplicate initial snapshot either way.
+    void resync();
+    /** Dispatches `respond_sent` before the RPC (so a spinner can render immediately), then
+     *  `respond_failed` only on a domain failure — `ui_resolved` is what actually clears `submitting`
+     *  on success, never this function. Never throws on a domain outcome; `AgentUiRespondResult`
+     *  stays the contract task-001 established. */
+    async function respond(uiRequestId, response) {
+        commit({ type: "respond_sent", requestId: uiRequestId, response });
+        const result = await client.respondToUi(uiRequestId, response);
+        if (!result.ok)
+            commit({ type: "respond_failed", requestId: uiRequestId });
+        return result;
+    }
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        respond,
+        resync,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            unsubscribeRequest();
+            unsubscribeResolved();
+            unsubscribePrune();
+            unsubscribeState();
+            listeners.clear();
+            queue = [];
+        },
+    };
+}
+//# sourceMappingURL=agent-ui-controller.js.map

package/dist/agent-ui-state.d.ts

@@ -0,0 +1,161 @@
+import type { AgentUiPendingRequest, AgentUiRequest, AgentUiResolved, AgentUiResponse, AgentUiSurface } from "@av-pi-studio/protocol";
+import type { AgentUiEventMeta } from "./pistudio-client.js";
+/**
+ * Framework-free extension-UI state machine (`swe/features/extension-ui-client-sdk.md` § Pure
+ * state module). No DOM, no timers, no I/O, no logging — every transition returns a **new** state
+ * plus a list of effects to perform, never performs them itself. This is the module that makes the
+ * sibling rendering scope component work over an already-tested machine.
+ *
+ * **Routing is by wire predicate, never by a `method` table** (mirrors the server-side adapter,
+ * `packages/server/src/agent/agent-ui/agent-ui-service.ts`, which is equally payload-blind):
+ *
+ * ```
+ * expectsResponse        → dialog            (select, confirm, input, editor)
+ * surfaceKey && removed  → delete surface
+ * surfaceKey             → upsert surface    (setStatus, setWidget, setTitle)
+ * otherwise              → transient effect  (notify, set_editor_text)
+ * ```
+ *
+ * `method` is inspected only *within* the transient category, to pick which effect to build — the
+ * one place the routing rule permits it. An unknown fire-and-forget method therefore produces
+ * **zero** effects; that absence is deliberately the caller's "unknown method" signal, not a stored
+ * flag on any entry (a flag would require the exact known-methods table this module refuses to
+ * keep).
+ *
+ * **Timeouts are displayed, never acted on.** Pi auto-resolves its own timed dialogs and states the
+ * client does not need to track them. `remainingMs` is a pure function of `(entry, now)`; no action
+ * or code path here dismisses, expires, or mutates an entry — only a `ui_resolved` action removes
+ * one from `pending` (moving it to `resolved`, see below).
+ *
+ * **`method` is also inspected once more, on resolution — a storage rule, not routing.** A
+ * `select`/`confirm` answer is retained on the resolved entry for display (`answer`, below); an
+ * `input`/`editor` answer, or any unrecognised method's, never is. Those two methods resolve to free
+ * text the user typed, and an extension asking for a secret (an API token, say) is an expected,
+ * documented case — so the value must be unrepresentable in this module's state, not merely
+ * convention-excluded from rendering. See `answerFromResponse` below.
+ */
+export interface AgentUiPendingEntry {
+    requestId: string;
+    agentId: string;
+    method: string;
+    payload: Record<string, unknown>;
+    timeoutMs?: number;
+    /** As received off the wire — epoch ms or ISO string. Normalised only inside `remainingMs`. */
+    createdAt: number | string;
+    /** Local clock reading, live events only — absent for a snapshot-recovered entry. */
+    receivedAt?: number;
+    answerable: boolean;
+    /** A `respond` from this client is in flight. Never an optimistic resolution — the entry stays in
+     *  `pending` until a real `ui_resolved` arrives; `respond_failed` clears this if the RPC itself
+     *  reports failure (e.g. lost the first-answer-wins race). */
+    submitting?: boolean;
+    /** What this client submitted, `select`/`confirm` only — see the module header. Carried onto the
+     *  resolved entry's `answer` once `ui_resolved` arrives. */
+    submittedAnswer?: AgentUiAnswer;
+}
+export interface AgentUiSurfaceEntry {
+    agentId: string;
+    surfaceKey: string;
+    method: string;
+    payload: Record<string, unknown>;
+    updatedAt: number | string;
+}
+/** Retained on a resolved dialog only for `select`/`confirm` — see the module header. */
+export interface AgentUiAnswer {
+    value?: string;
+    confirmed?: boolean;
+}
+/** A dialog that is no longer answerable, kept for display only. Page-lifetime state: it survives a
+ *  reconnect (the daemon has no resolved history to re-serve — `snapshot` passes this through
+ *  untouched) and dies with the tab. */
+export interface AgentUiResolvedEntry {
+    requestId: string;
+    agentId: string;
+    method: string;
+    payload: Record<string, unknown>;
+    /** The ORIGINAL `createdAt` from when the dialog was pending, so a card keeps its slot in a list
+     *  merged with `pendingForAgent` when it resolves — no `resolvedAt` field exists. */
+    createdAt: number | string;
+    /** Verbatim from `agent_ui_resolved` — an open string, never relabeled, never enumerated. */
+    reason: string;
+    /** Present only when THIS client answered a `select`/`confirm` — see the module header. */
+    answer?: AgentUiAnswer;
+}
+export interface AgentUiState {
+    /** Keyed by `requestId` — daemon-minted, unique across every agent. */
+    pending: Record<string, AgentUiPendingEntry>;
+    /** Keyed by `surfaceMapKey(agentId, surfaceKey)` — a `surfaceKey` is unique only within an agent. */
+    surfaces: Record<string, AgentUiSurfaceEntry>;
+    /** Keyed by `requestId`, same as `pending`. Bounded per agent — see `RESOLVED_HISTORY_LIMIT`. */
+    resolved: Record<string, AgentUiResolvedEntry>;
+}
+export declare const initialAgentUiState: AgentUiState;
+/** Per-agent cap on retained resolved dialogs. Page-lifetime state, but a chatty extension over a
+ *  long session must not grow it without limit. */
+export declare const RESOLVED_HISTORY_LIMIT = 50;
+export type AgentUiAction = {
+    type: "ui_request";
+    event: AgentUiRequest;
+    meta: AgentUiEventMeta;
+} | {
+    type: "ui_resolved";
+    event: AgentUiResolved;
+} | {
+    type: "snapshot";
+    pending: AgentUiPendingRequest[];
+    surfaces: AgentUiSurface[];
+} | {
+    type: "disconnected";
+} | {
+    type: "agent_removed";
+    agentId: string;
+} | {
+    type: "respond_sent";
+    requestId: string;
+    response: AgentUiResponse;
+} | {
+    type: "respond_failed";
+    requestId: string;
+};
+export type AgentUiEffect = {
+    type: "replace_composer_text";
+    agentId: string;
+    text: string;
+} | {
+    type: "notify";
+    agentId: string;
+    message: string;
+    level: string;
+};
+/**
+ * Unambiguous composite key: `agentId` is a UUID, so `\u0000` (no UUID contains it) is a safe
+ * separator. `agentId`/`surfaceKey` are also stored verbatim on the entry, so nothing ever needs to
+ * parse this key back apart.
+ */
+export declare function surfaceMapKey(agentId: string, surfaceKey: string): string;
+export declare function reduce(state: AgentUiState, action: AgentUiAction): {
+    state: AgentUiState;
+    effects: AgentUiEffect[];
+};
+/** Every pending dialog for one agent, oldest first (`createdAt`, `requestId` tie-break) — stable
+ *  so a list cannot jitter between renders. */
+export declare function pendingForAgent(state: AgentUiState, agentId: string): AgentUiPendingEntry[];
+/** Pending-dialog count per agent — the attention-badge derivation, so badging is a subscription
+ *  rather than UI logic. An agent with zero pending is **absent** from the map, never present at `0`. */
+export declare function pendingByAgent(state: AgentUiState): Record<string, number>;
+/** Every retained surface for one agent, oldest-updated first (`updatedAt`, `surfaceKey` tie-break). */
+export declare function surfacesForAgent(state: AgentUiState, agentId: string): AgentUiSurfaceEntry[];
+/** Every resolved dialog for one agent, oldest first (`createdAt`, `requestId` tie-break) — the same
+ *  ordering key and comparator as `pendingForAgent`, so merging both lists by that key keeps a
+ *  card's index stable across resolution (no per-card `resolvedAt`, and no clock reads here). */
+export declare function resolvedForAgent(state: AgentUiState, agentId: string): AgentUiResolvedEntry[];
+/**
+ * Time left before Pi auto-resolves this dialog, or `null` when it is untimed (a human may take
+ * hours). A **legibility affordance only** — nothing in this module or its callers may act on the
+ * result (dismiss, expire, resend); only a real `ui_resolved` event ever removes an entry. Anchors
+ * on the local `receivedAt` when available; a snapshot-recovered entry has none, so it falls back to
+ * the daemon's `createdAt` and accepts the residual cross-host clock skew — acceptable for a rough
+ * countdown display, which is the only thing this value drives. Clamped at `0`, never negative.
+ */
+export declare function remainingMs(entry: AgentUiPendingEntry, now: number): number | null;
+//# sourceMappingURL=agent-ui-state.d.ts.map

package/dist/agent-ui-state.js

@@ -0,0 +1,284 @@
+export const initialAgentUiState = { pending: {}, surfaces: {}, resolved: {} };
+/** Per-agent cap on retained resolved dialogs. Page-lifetime state, but a chatty extension over a
+ *  long session must not grow it without limit. */
+export const RESOLVED_HISTORY_LIMIT = 50;
+/**
+ * Unambiguous composite key: `agentId` is a UUID, so `\u0000` (no UUID contains it) is a safe
+ * separator. `agentId`/`surfaceKey` are also stored verbatim on the entry, so nothing ever needs to
+ * parse this key back apart.
+ */
+export function surfaceMapKey(agentId, surfaceKey) {
+    return `${agentId}\u0000${surfaceKey}`;
+}
+/** Epoch ms or ISO string → epoch ms, for ordering/countdown arithmetic only. */
+function normalizeTimestamp(value) {
+    return typeof value === "number" ? value : Date.parse(value);
+}
+// ─── Reducer ──────────────────────────────────────────────────────────────────
+export function reduce(state, action) {
+    switch (action.type) {
+        case "ui_request":
+            return reduceUiRequest(state, action.event, action.meta);
+        case "ui_resolved":
+            return { state: reduceUiResolved(state, action.event), effects: [] };
+        case "snapshot":
+            return {
+                state: buildSnapshotState(action.pending, action.surfaces, state.resolved),
+                effects: [],
+            };
+        case "disconnected":
+            return { state: markAllUnanswerable(state), effects: [] };
+        case "agent_removed":
+            return { state: dropAgent(state, action.agentId), effects: [] };
+        case "respond_sent":
+            return { state: applyRespondSent(state, action.requestId, action.response), effects: [] };
+        case "respond_failed":
+            return { state: applyRespondFailed(state, action.requestId), effects: [] };
+    }
+}
+function reduceUiRequest(state, event, meta) {
+    // Dialog: expectsResponse wins the ladder regardless of any other field.
+    if (event.expectsResponse) {
+        const entry = {
+            requestId: event.requestId,
+            agentId: event.agentId,
+            method: event.method,
+            payload: event.payload,
+            timeoutMs: event.timeoutMs,
+            createdAt: event.createdAt,
+            receivedAt: meta.receivedAt,
+            answerable: true,
+        };
+        return {
+            state: { ...state, pending: { ...state.pending, [event.requestId]: entry } },
+            effects: [],
+        };
+    }
+    // Surface clear/upsert.
+    if (event.surfaceKey !== undefined) {
+        const key = surfaceMapKey(event.agentId, event.surfaceKey);
+        if (event.removed) {
+            if (!(key in state.surfaces))
+                return { state, effects: [] }; // never-seen key: no-op, not an error
+            const surfaces = { ...state.surfaces };
+            delete surfaces[key];
+            return { state: { ...state, surfaces }, effects: [] };
+        }
+        const entry = {
+            agentId: event.agentId,
+            surfaceKey: event.surfaceKey,
+            method: event.method,
+            payload: event.payload,
+            updatedAt: event.createdAt,
+        };
+        // Last-write-wins on (agentId, surfaceKey) — never deduped by requestId, which is fresh per upsert.
+        return { state: { ...state, surfaces: { ...state.surfaces, [key]: entry } }, effects: [] };
+    }
+    // Transient: no state change, effects built from `method` — the one place this module reads it
+    // for routing purposes, and only to pick an effect shape within this already-decided category.
+    return { state, effects: buildTransientEffects(event) };
+}
+function buildTransientEffects(event) {
+    switch (event.method) {
+        case "set_editor_text": {
+            // Always replace — matches Pi's own semantics (`pasteToEditor` delegates to `setEditorText`
+            // with no paste handling), and is the predictable behavior for extension authors.
+            const text = typeof event.payload.text === "string" ? event.payload.text : "";
+            return [{ type: "replace_composer_text", agentId: event.agentId, text }];
+        }
+        case "notify": {
+            const message = typeof event.payload.message === "string" ? event.payload.message : "";
+            // Forwarded verbatim — never collapsed onto today's ToastVariant, which has no "warning".
+            const level = typeof event.payload.level === "string" ? event.payload.level : "info";
+            return [{ type: "notify", agentId: event.agentId, message, level }];
+        }
+        default:
+            // Unrecognised fire-and-forget method: zero effects IS the "unknown method" signal — the
+            // caller (task-003) reports it, this module stays silent and stateless about it.
+            return [];
+    }
+}
+/**
+ * Retention rule for a resolved dialog's answer (module header). `select`/`confirm` responses are
+ * kept for display; `input`/`editor` (and any unrecognised method) resolve to free text or secrets
+ * and are never retained — the value must be unrepresentable in state, not merely unrendered. This
+ * is the only place besides `buildTransientEffects` that this module inspects `method`, and only to
+ * enforce this exclusion, never to route.
+ */
+function answerFromResponse(method, response) {
+    if (method !== "select" && method !== "confirm")
+        return undefined;
+    return { value: response.value, confirmed: response.confirmed };
+}
+function reduceUiResolved(state, event) {
+    // Unknown requestId: ordered delivery on a single socket makes "resolved before its own
+    // snapshot/create arrived" unconstructible, so this is a plain no-op — no tombstone bookkeeping.
+    const pendingEntry = state.pending[event.requestId];
+    if (!pendingEntry)
+        return state;
+    const pending = { ...state.pending };
+    delete pending[event.requestId];
+    const resolvedEntry = {
+        requestId: pendingEntry.requestId,
+        agentId: pendingEntry.agentId,
+        method: pendingEntry.method,
+        payload: pendingEntry.payload,
+        createdAt: pendingEntry.createdAt,
+        reason: event.reason,
+    };
+    if (pendingEntry.submittedAnswer !== undefined)
+        resolvedEntry.answer = pendingEntry.submittedAnswer;
+    return { ...state, pending, resolved: addResolvedEntry(state.resolved, resolvedEntry) };
+}
+/** Inserts `entry`, then evicts that agent's oldest resolved entries (by the same
+ *  `createdAt`/`requestId` ordering the selectors use) past `RESOLVED_HISTORY_LIMIT`. Other agents'
+ *  entries are never touched by one agent's eviction. */
+function addResolvedEntry(resolved, entry) {
+    const next = { ...resolved, [entry.requestId]: entry };
+    const forAgent = Object.values(next)
+        .filter((e) => e.agentId === entry.agentId)
+        .toSorted((a, b) => compareByTimeThenId(a.createdAt, a.requestId, b.createdAt, b.requestId));
+    const evictCount = forAgent.length - RESOLVED_HISTORY_LIMIT;
+    if (evictCount <= 0)
+        return next;
+    for (const evicted of forAgent.slice(0, evictCount))
+        delete next[evicted.requestId];
+    return next;
+}
+function buildSnapshotState(pendingList, surfaceList, resolved) {
+    // Wholesale replacement for `pending`/`surfaces`, never a merge: the daemon composes this response
+    // from state that postdates every broadcast already delivered on this (single, ordered) socket, so
+    // it is authoritative. Every rebuilt pending entry resets `answerable: true` and carries no
+    // `receivedAt`/`submitting`/`submittedAnswer` — it was not observed locally, it was recovered, and
+    // a dropped socket invalidates any respond that had been in flight. `resolved` is passed through
+    // untouched instead: `agent_ui_list_response` carries no resolved history for the daemon to
+    // re-serve, so replacing it here would wipe every collapsed card on reconnect.
+    const pending = {};
+    for (const p of pendingList) {
+        pending[p.requestId] = {
+            requestId: p.requestId,
+            agentId: p.agentId,
+            method: p.method,
+            payload: p.payload,
+            timeoutMs: p.timeoutMs,
+            createdAt: p.createdAt,
+            answerable: true,
+        };
+    }
+    const surfaces = {};
+    for (const s of surfaceList) {
+        surfaces[surfaceMapKey(s.agentId, s.surfaceKey)] = {
+            agentId: s.agentId,
+            surfaceKey: s.surfaceKey,
+            method: s.method,
+            payload: s.payload,
+            updatedAt: s.updatedAt,
+        };
+    }
+    return { pending, surfaces, resolved };
+}
+function markAllUnanswerable(state) {
+    const pending = {};
+    for (const [id, entry] of Object.entries(state.pending)) {
+        pending[id] = { ...entry, answerable: false };
+    }
+    // Nothing removed — only a later `snapshot` action round-trips `answerable` back to `true`.
+    return { ...state, pending };
+}
+function dropAgent(state, agentId) {
+    const pending = {};
+    for (const [id, entry] of Object.entries(state.pending)) {
+        if (entry.agentId !== agentId)
+            pending[id] = entry;
+    }
+    const surfaces = {};
+    for (const [key, entry] of Object.entries(state.surfaces)) {
+        if (entry.agentId !== agentId)
+            surfaces[key] = entry;
+    }
+    const resolved = {};
+    for (const [id, entry] of Object.entries(state.resolved)) {
+        if (entry.agentId !== agentId)
+            resolved[id] = entry;
+    }
+    return { pending, surfaces, resolved };
+}
+function applyRespondSent(state, requestId, response) {
+    const entry = state.pending[requestId];
+    if (!entry)
+        return state; // unknown id: nothing to mark in flight
+    const submittedAnswer = answerFromResponse(entry.method, response);
+    const next = { ...entry, submitting: true };
+    if (submittedAnswer !== undefined)
+        next.submittedAnswer = submittedAnswer;
+    return { ...state, pending: { ...state.pending, [requestId]: next } };
+}
+function applyRespondFailed(state, requestId) {
+    const entry = state.pending[requestId];
+    if (!entry)
+        return state; // no longer pending (already resolved, or never was) — no-op
+    // Rebuilt explicitly, not spread-and-delete: this is what stops a lost first-answer-wins race
+    // from leaving a spinner running forever, since a `not_found` response is followed by no
+    // broadcast to this client.
+    const next = {
+        requestId: entry.requestId,
+        agentId: entry.agentId,
+        method: entry.method,
+        payload: entry.payload,
+        timeoutMs: entry.timeoutMs,
+        createdAt: entry.createdAt,
+        receivedAt: entry.receivedAt,
+        answerable: entry.answerable,
+    };
+    return { ...state, pending: { ...state.pending, [requestId]: next } };
+}
+// ─── Selectors ────────────────────────────────────────────────────────────────
+function compareByTimeThenId(aTime, aId, bTime, bId) {
+    const diff = normalizeTimestamp(aTime) - normalizeTimestamp(bTime);
+    return diff !== 0 ? diff : aId.localeCompare(bId);
+}
+/** Every pending dialog for one agent, oldest first (`createdAt`, `requestId` tie-break) — stable
+ *  so a list cannot jitter between renders. */
+export function pendingForAgent(state, agentId) {
+    return Object.values(state.pending)
+        .filter((entry) => entry.agentId === agentId)
+        .toSorted((a, b) => compareByTimeThenId(a.createdAt, a.requestId, b.createdAt, b.requestId));
+}
+/** Pending-dialog count per agent — the attention-badge derivation, so badging is a subscription
+ *  rather than UI logic. An agent with zero pending is **absent** from the map, never present at `0`. */
+export function pendingByAgent(state) {
+    const counts = {};
+    for (const entry of Object.values(state.pending)) {
+        counts[entry.agentId] = (counts[entry.agentId] ?? 0) + 1;
+    }
+    return counts;
+}
+/** Every retained surface for one agent, oldest-updated first (`updatedAt`, `surfaceKey` tie-break). */
+export function surfacesForAgent(state, agentId) {
+    return Object.values(state.surfaces)
+        .filter((entry) => entry.agentId === agentId)
+        .toSorted((a, b) => compareByTimeThenId(a.updatedAt, a.surfaceKey, b.updatedAt, b.surfaceKey));
+}
+/** Every resolved dialog for one agent, oldest first (`createdAt`, `requestId` tie-break) — the same
+ *  ordering key and comparator as `pendingForAgent`, so merging both lists by that key keeps a
+ *  card's index stable across resolution (no per-card `resolvedAt`, and no clock reads here). */
+export function resolvedForAgent(state, agentId) {
+    return Object.values(state.resolved)
+        .filter((entry) => entry.agentId === agentId)
+        .toSorted((a, b) => compareByTimeThenId(a.createdAt, a.requestId, b.createdAt, b.requestId));
+}
+/**
+ * Time left before Pi auto-resolves this dialog, or `null` when it is untimed (a human may take
+ * hours). A **legibility affordance only** — nothing in this module or its callers may act on the
+ * result (dismiss, expire, resend); only a real `ui_resolved` event ever removes an entry. Anchors
+ * on the local `receivedAt` when available; a snapshot-recovered entry has none, so it falls back to
+ * the daemon's `createdAt` and accepts the residual cross-host clock skew — acceptable for a rough
+ * countdown display, which is the only thing this value drives. Clamped at `0`, never negative.
+ */
+export function remainingMs(entry, now) {
+    if (entry.timeoutMs === undefined)
+        return null;
+    const anchor = entry.receivedAt ?? normalizeTimestamp(entry.createdAt);
+    return Math.max(0, entry.timeoutMs - (now - anchor));
+}
+//# sourceMappingURL=agent-ui-state.js.map

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export * from "./relay-transport.js";
 export * from "./pairing.js";
 export * from "./daemon-client.js";
 export * from "./pistudio-client.js";
+export * from "./agent-ui-state.js";
+export * from "./agent-ui-controller.js";
 export * from "./terminal-stream-router.js";
 export * from "./file-transfer-client.js";
 export * from "./reconnect.js";

package/dist/index.js

@@ -13,6 +13,10 @@ export * from "./pairing.js";
 export * from "./daemon-client.js";
 // High-level PiStudioClient SDK facade + handles.
 export * from "./pistudio-client.js";
+// Extension-UI pure state module (reducer/selectors, sprint-067).
+export * from "./agent-ui-state.js";
+// Extension-UI controller (subscribe-then-list, reconnect resync, agent pruning, sprint-067).
+export * from "./agent-ui-controller.js";
 // Terminal-stream router (binary frame demux per slot).
 export * from "./terminal-stream-router.js";
 // File-transfer client (binary download frame demux + assembly).

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, ProviderAuthInfo, ProviderAuthType, 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.
@@ -278,6 +278,63 @@ 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`. */
@@ -344,11 +401,49 @@ export declare class PiStudioClient {
     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 cancels the whole flow. */
+     *  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

@@ -29,6 +29,52 @@ class PromptCancelledError extends Error {
         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;
@@ -248,7 +294,11 @@ export class PiStudioClient {
     }
     /** 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 cancels the whole flow. */
+     *  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`,
@@ -297,6 +347,7 @@ export class PiStudioClient {
                     .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,
@@ -314,6 +365,61 @@ export class PiStudioClient {
             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

package/dist/test-support/scripted-daemon.js

@@ -0,0 +1,235 @@
+import { DaemonClient } from "../daemon-client.js";
+import { PiStudioClient } from "../pistudio-client.js";
+export function makeScriptedDaemon(opts) {
+    const sent = [];
+    let agentSeq = 0;
+    const features = opts?.features ?? { providersSnapshot: true, providerAuth: true };
+    const transport = {
+        onMessage: null,
+        onClose: null,
+        onError: null,
+        isOpen: true,
+        connect: () => Promise.resolve(),
+        sendBinary: () => { },
+        close: () => { },
+        sendText: (data) => {
+            const frame = JSON.parse(data);
+            if (frame.type === "hello") {
+                queueMicrotask(() => transport.onMessage?.(JSON.stringify({
+                    type: "status",
+                    payload: {
+                        status: "server_info",
+                        serverId: "srv-mock",
+                        capabilities: {},
+                        features,
+                    },
+                })));
+                return;
+            }
+            if (frame.type === "session") {
+                const msg = frame.message;
+                sent.push(msg);
+                respond(msg);
+            }
+        },
+    };
+    function reply(message) {
+        queueMicrotask(() => transport.onMessage?.(JSON.stringify({ type: "session", message })));
+    }
+    function respond(msg) {
+        const requestId = msg.requestId;
+        // The `provider_auth_*` family is driven manually by each test via `fake.push()` — real
+        // flows are ordering-sensitive (buffering-before-response, prompt races), so an automatic
+        // reply here would hide exactly the bugs those tests exist to catch.
+        if (typeof msg.type === "string" && msg.type.startsWith("provider_auth_")) {
+            return;
+        }
+        switch (msg.type) {
+            case "agent_ui_respond_request":
+            case "agent_ui_list_request":
+                // Driven manually by each test via `fake.push()` — the ok/error mix (and, for
+                // agent_ui_list_request, the exact moment the reply lands relative to other pushed
+                // events) is exactly what the acceptance criteria differentiate on; an automatic reply
+                // would hide it.
+                return;
+            case "create_agent_request": {
+                const agentId = `agent-${++agentSeq}`;
+                reply({ type: "create_agent_response", requestId, payload: { agentId } });
+                // Simulate a streamed turn for the new agent.
+                if (msg.initialPrompt) {
+                    reply({
+                        type: "agent_stream",
+                        agentId,
+                        event: { kind: "turn_started" },
+                    });
+                    reply({
+                        type: "agent_stream",
+                        agentId,
+                        event: { kind: "assistant_message", text: "hello from mock" },
+                    });
+                    reply({ type: "agent_stream", agentId, event: { kind: "turn_completed" } });
+                    reply({ type: "agent_update", agentId, status: "idle" });
+                }
+                return;
+            }
+            case "fetch_agent_timeline_request": {
+                reply({
+                    type: "fetch_agent_timeline_response",
+                    requestId,
+                    payload: {
+                        agentId: msg.agentId,
+                        items: [{ kind: "assistant_message", text: "hello from mock" }],
+                        startCursor: "c0",
+                        endCursor: "c1",
+                        hasOlder: false,
+                        hasNewer: false,
+                        seqStart: 1,
+                        seqEnd: 1,
+                    },
+                });
+                return;
+            }
+            case "update_agent": {
+                reply({ type: "update_agent_response", requestId, payload: { ok: true } });
+                reply({
+                    type: "agent_update",
+                    agentId: msg.agentId,
+                    title: msg.title,
+                });
+                return;
+            }
+            case "agent_session_stats_request": {
+                reply({
+                    type: "agent_session_stats_response",
+                    requestId,
+                    payload: { sessionId: "s1", totalMessages: 3 },
+                });
+                return;
+            }
+            case "agent_compact_request": {
+                reply({
+                    type: "agent_compact_response",
+                    requestId,
+                    payload: { summary: "compacted", tokensBefore: 1000 },
+                });
+                return;
+            }
+            case "agent_list_commands_request": {
+                reply({
+                    type: "agent_list_commands_response",
+                    requestId,
+                    payload: {
+                        commands: [
+                            {
+                                name: "fix-tests",
+                                description: "Fix failing tests",
+                                source: "prompt",
+                                scope: "project",
+                                path: "/w/.pi/agent/prompts/fix-tests.md",
+                            },
+                            { name: "skill:brave-search", source: "skill", scope: "user" },
+                        ],
+                    },
+                });
+                return;
+            }
+            case "list_provider_models": {
+                reply({
+                    type: "list_provider_models_response",
+                    requestId,
+                    payload: { models: [{ id: "m1" }, { id: "m2" }] },
+                });
+                return;
+            }
+            case "list_provider_modes": {
+                reply({
+                    type: "list_provider_modes_response",
+                    requestId,
+                    payload: { modes: [{ id: "plan" }, { id: "default" }] },
+                });
+                return;
+            }
+            case "providers.snapshot.refresh.request": {
+                reply({
+                    type: "providers.snapshot.refresh.response",
+                    requestId,
+                    payload: { refreshed: true },
+                });
+                return;
+            }
+            case "resolve_default_model": {
+                reply({
+                    type: "resolve_default_model_response",
+                    requestId,
+                    provider: msg.provider,
+                    model: "claude-sonnet-5",
+                    modelProvider: "anthropic",
+                });
+                return;
+            }
+            case "extension_packs_list_request": {
+                // Flat fields on the message — the real wire schema (packages/protocol/src/messages.ts)
+                // has no `payload` wrapper for this pair, unlike several older RPCs above.
+                reply({
+                    type: "extension_packs_list_response",
+                    requestId,
+                    autoSync: true,
+                    selected: ["swe"],
+                    packs: [
+                        { id: "core", title: "Core", description: "Always-on core pack", packages: [] },
+                        { id: "swe", title: "Software Engineering", description: "SWE tools", packages: [] },
+                    ],
+                });
+                return;
+            }
+            case "extension_packs_set_request": {
+                const packs = msg.packs;
+                if (packs?.includes("unknown")) {
+                    reply({
+                        type: "extension_packs_set_response",
+                        requestId,
+                        autoSync: true,
+                        selected: ["swe"],
+                        packs: [],
+                        ok: false,
+                        error: "unknown pack: unknown",
+                    });
+                    return;
+                }
+                reply({
+                    type: "extension_packs_set_response",
+                    requestId,
+                    autoSync: true,
+                    selected: packs ?? ["swe"],
+                    packs: [],
+                    ok: true,
+                    report: { at: new Date().toISOString(), outcome: "ok", installed: [], failures: [] },
+                });
+                return;
+            }
+            default:
+                reply({ type: `${String(msg.type)}_response`, requestId, payload: { ok: true } });
+        }
+    }
+    return {
+        transport,
+        sent,
+        features,
+        push: (sessionMessage) => reply(sessionMessage),
+        drop: (reason = "test drop") => transport.onClose?.(1006, reason),
+    };
+}
+/** Builds a connected `PiStudioClient` over `makeScriptedDaemon`. */
+export async function makeFacade(opts) {
+    const fake = makeScriptedDaemon(opts);
+    const daemon = new DaemonClient({
+        url: "ws://mock/ws",
+        clientId: "c1",
+        clientType: "cli",
+        transport: fake.transport,
+        rpcTimeoutMs: 1000,
+    });
+    await daemon.connect();
+    return { client: new PiStudioClient(daemon), daemon, fake };
+}
+//# sourceMappingURL=scripted-daemon.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@av-pi-studio/client",
-  "version": "0.0.93",
+  "version": "0.0.94",
   "files": [
     "dist",
     "!dist/**/*.map",
@@ -20,7 +20,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@av-pi-studio/protocol": "^0.0.93",
-    "@av-pi-studio/relay": "^0.0.93"
+    "@av-pi-studio/protocol": "^0.0.94",
+    "@av-pi-studio/relay": "^0.0.94"
   }
 }