@av-pi-studio/server 0.0.93 → 0.0.94

package/dist/agent/agent-manager.d.ts

@@ -1,5 +1,6 @@
 import type { AgentStatus } from "@av-pi-studio/protocol";
 import type { AgentRecord } from "../persistence/entity-schemas.js";
+import type { Logger } from "../logging/logger.js";
 import type { AgentSession } from "./provider-contract.js";
 /**
  * AgentManager — the single source of truth for agent lifecycle state
@@ -48,6 +49,13 @@ export interface AgentManagerDeps {
     deleteAgent?: (cwd: string, id: string) => Promise<boolean>;
     /** Loop service hook: recover `running` loops as `stopped` with an interruption log entry. */
     onRecoverLoops?: () => Promise<void> | void;
+    /** Session-attach hook (features/extension-ui-rpc.md § New/changed files) — invoked at the end of
+     *  `attachSession()`, the single choke point every spawn/resume/import path already funnels
+     *  through (`agent-service.ts:104`, `:228`). A throwing hook is logged and never prevents the
+     *  session from being attached. Optional: existing constructions that pass none behave exactly
+     *  as before. */
+    onSessionAttached?: (agentId: string, session: AgentSession) => void;
+    logger?: Logger;
     now?: () => string;
 }
 export declare class AgentManager {

package/dist/agent/agent-manager.js

@@ -82,8 +82,17 @@ export class AgentManager {
     }
     attachSession(id, session) {
         const managed = this.agents.get(id);
-        if (managed)
-            managed.session = session;
+        if (!managed)
+            return;
+        managed.session = session;
+        if (!this.deps.onSessionAttached)
+            return;
+        try {
+            this.deps.onSessionAttached(id, session);
+        }
+        catch (err) {
+            this.deps.logger?.warn({ agentId: id, err: err instanceof Error ? err.message : String(err) }, "agent-manager: onSessionAttached hook failed");
+        }
     }
     /**
      * Snapshot and persist the live session's resume handle (e.g. Pi's on-disk JSONL session file)

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

@@ -0,0 +1,20 @@
+import type { Logger } from "../../logging/logger.js";
+import type { HandlerRegistry } from "../../ws/router.js";
+import type { AgentUiService } from "./agent-ui-service.js";
+/**
+ * Wires the two `agent_ui_*` RPCs (swe/features/extension-ui-rpc.md § Public contract) onto
+ * `AgentUiService`. Modelled directly on `registerFileWatchHandlers`/`registerProviderAuthHandlers`:
+ * a thin adapter that stamps no policy of its own — ownership, first-wins resolution, and every
+ * error code already live in the service (task-003). Never throws for a domain failure
+ * (`not_found`/`unsupported` travel in `payload`); `requestId` is stamped by the router, not here.
+ *
+ * Registered in **both** bootstraps (task-004's deviation from the production-only
+ * `provider_auth`/`file_watch` families) — the mock provider is this family's designated producer,
+ * so the dev daemon must be able to drive it end to end.
+ */
+export interface AgentUiRpcDeps {
+    service: AgentUiService;
+    logger?: Logger;
+}
+export declare function registerAgentUiHandlers(registry: HandlerRegistry, deps: AgentUiRpcDeps): void;
+//# sourceMappingURL=agent-ui-rpc.d.ts.map

package/dist/agent/agent-ui/agent-ui-rpc.js

@@ -0,0 +1,24 @@
+export function registerAgentUiHandlers(registry, deps) {
+    const { service } = deps;
+    registry.register("agent_ui_respond_request", (ctx) => {
+        const uiRequestId = String(ctx.message.uiRequestId ?? "");
+        const response = (ctx.message.response ?? {});
+        const result = service.respond(uiRequestId, response);
+        return {
+            type: "agent_ui_respond_response",
+            payload: result.error ? { ok: result.ok, error: result.error } : { ok: result.ok },
+        };
+    });
+    registry.register("agent_ui_list_request", (ctx) => {
+        const agentId = typeof ctx.message.agentId === "string" ? ctx.message.agentId : undefined;
+        return {
+            type: "agent_ui_list_response",
+            payload: {
+                ok: true,
+                pending: service.listPending(agentId),
+                surfaces: service.listSurfaces(agentId),
+            },
+        };
+    });
+}
+//# sourceMappingURL=agent-ui-rpc.js.map

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

@@ -0,0 +1,55 @@
+import type { AgentUiPendingRequest, AgentUiSurface } from "@av-pi-studio/protocol";
+import type { Logger } from "../../logging/logger.js";
+import type { Session } from "../../ws/session.js";
+import type { AgentSession, ProviderUiResponse } from "../provider-contract.js";
+export interface AgentUiServiceDeps {
+    broadcast: (sessions: Iterable<Session>, message: unknown) => void;
+    getActiveSessions: () => Iterable<Session>;
+    logger?: Logger;
+    /** Timer seams so tests use fake timers instead of wall-clock waits. */
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+}
+export declare class AgentUiService {
+    private readonly broadcastFn;
+    private readonly getActiveSessions;
+    private readonly logger;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly pending;
+    private readonly surfaces;
+    private readonly channels;
+    private readonly loggedUnknownMethods;
+    constructor(deps: AgentUiServiceDeps);
+    /**
+     * `AgentManager.onSessionAttached` hook (task-004 wires the call site; nothing calls this yet).
+     * Sweeps first — a forced respawn (`spawnOrResumeSession` always spawns fresh) leaves undead
+     * dialogs whose provider ids belong to a dead process, so any prior pending/surfaces/channel for
+     * this agent are cancelled as `"aborted"` before the new session's channel is ever subscribed.
+     */
+    attach(agentId: string, session: AgentSession): void;
+    /** First-answer-wins. Unknown/already-resolved/fire-and-forget ids all report `not_found` — a
+     *  fire-and-forget request was never inserted into `pending` in the first place. */
+    respond(uiRequestId: string, response: ProviderUiResponse): {
+        ok: boolean;
+        error?: string;
+    };
+    listPending(agentId?: string): AgentUiPendingRequest[];
+    listSurfaces(agentId?: string): AgentUiSurface[];
+    /**
+     * Session-terminal only (archive / delete / re-attach) — NEVER called on interrupt. For each
+     * pending entry: best-effort cancel toward **the entry's own captured session** (never a freshly
+     * attached one — on the attach-path sweep the new session never issued those provider ids),
+     * broadcast the resolution, then drop the agent's pending entries, surfaces, and — critically —
+     * call the stored channel `Unsubscribe` before dropping it, so a post-sweep emission from a dying
+     * session cannot re-create a surface for an agent that no longer has a live channel.
+     */
+    sweep(agentId: string, reason: string): void;
+    private onProviderRequest;
+    /** Pi's own timeout elapsed — Pi already auto-resolved the dialog on its side (docs/rpc.md: "the
+     *  client does not need to track timeouts"). Deliberately does NOT call `respondToUi`: answering
+     *  again would target an id Pi has already dropped. */
+    private expire;
+    private broadcastResolved;
+}
+//# sourceMappingURL=agent-ui-service.d.ts.map

package/dist/agent/agent-ui/agent-ui-service.js

@@ -0,0 +1,237 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Correlates the provider UI channel into the daemon's wire family
+ * (features/extension-ui-rpc.md § Behavior & algorithms — the pseudocode there is normative). The
+ * only stateful piece of the bridge, and deliberately **payload-blind**: every Pi-specific decision
+ * (which methods block, surface-key namespacing, clear-by-omission, envelope stamping) was already
+ * made by the adapter (task-002); this service does no `method` string comparison beyond the
+ * unknown-method diagnostic log.
+ *
+ * Four behaviors here each prevent a concrete defect — see the task's own "Context / why":
+ *  - **Wire ids are daemon-minted, never the provider's.** `ProviderUiRequest.requestId` is only
+ *    promised unique per-process; keying a daemon-global map by it would let one agent's dialog
+ *    shadow another's. `pending` is keyed by a minted UUID; providers never see it.
+ *  - **Interrupt touches nothing.** Dialogs are not turn-scoped (`pi-background-tasks` raises
+ *    questions outside any turn) and surfaces are agent-lifetime state. `sweep` runs ONLY on
+ *    session-terminal events (archive/delete/re-attach) — nothing else cancels.
+ *  - **Expiry never answers.** Pi auto-resolves its own timed dialogs; the mirrored timer here
+ *    exists solely so clients dismiss in step. Sending a second response would target a dead id.
+ *  - **Resolution broadcasts unconditionally.** A `respondToUi` throw (dead stdin after a crash)
+ *    still broadcasts from `finally` — otherwise every other client keeps a ghost dialog that no
+ *    longer appears in `agent_ui_list_response`.
+ */
+/** Extension UI method vocabulary as documented (rpc.md § Extension UI Protocol), used ONLY to
+ *  decide whether an incoming method is diagnosable-as-unknown for the info log below — the single
+ *  sanctioned exception to "no method string comparison" in this service. Duplicated here rather
+ *  than imported from the Pi adapter: this service must stay provider-agnostic (never import
+ *  `providers/pi/*` per root AGENTS.md § Key invariants #3), so this list is deliberately a
+ *  diagnostics-only echo, not a source of behavior. */
+const KNOWN_METHODS = new Set([
+    "select",
+    "confirm",
+    "input",
+    "editor",
+    "notify",
+    "setStatus",
+    "setWidget",
+    "setTitle",
+    "set_editor_text",
+]);
+export class AgentUiService {
+    broadcastFn;
+    getActiveSessions;
+    logger;
+    setTimer;
+    clearTimer;
+    pending = new Map();
+    surfaces = new Map();
+    channels = new Map();
+    loggedUnknownMethods = new Set();
+    constructor(deps) {
+        this.broadcastFn = deps.broadcast;
+        this.getActiveSessions = deps.getActiveSessions;
+        this.logger = deps.logger;
+        this.setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = deps.clearTimer ?? ((handle) => clearTimeout(handle));
+    }
+    /**
+     * `AgentManager.onSessionAttached` hook (task-004 wires the call site; nothing calls this yet).
+     * Sweeps first — a forced respawn (`spawnOrResumeSession` always spawns fresh) leaves undead
+     * dialogs whose provider ids belong to a dead process, so any prior pending/surfaces/channel for
+     * this agent are cancelled as `"aborted"` before the new session's channel is ever subscribed.
+     */
+    attach(agentId, session) {
+        this.sweep(agentId, "aborted");
+        if (!session.onUiRequest)
+            return; // provider opted out; nothing to do, no error
+        const unsubscribe = session.onUiRequest((req) => this.onProviderRequest(agentId, session, req));
+        this.channels.set(agentId, unsubscribe);
+    }
+    /** First-answer-wins. Unknown/already-resolved/fire-and-forget ids all report `not_found` — a
+     *  fire-and-forget request was never inserted into `pending` in the first place. */
+    respond(uiRequestId, response) {
+        const entry = this.pending.get(uiRequestId);
+        if (!entry)
+            return { ok: false, error: "not_found" };
+        if (!entry.session.respondToUi)
+            return { ok: false, error: "unsupported" };
+        this.pending.delete(uiRequestId);
+        if (entry.timer)
+            this.clearTimer(entry.timer);
+        try {
+            entry.session.respondToUi(entry.providerRequestId, response);
+        }
+        catch (err) {
+            // The answer was still accepted (first-wins already consumed it) — swallow + log so the
+            // resolution broadcast below still fires; otherwise every other client keeps a ghost dialog.
+            this.logger?.warn({
+                agentId: entry.agentId,
+                requestId: uiRequestId,
+                method: entry.method,
+                err: errorMessage(err),
+            }, "agent-ui: respondToUi failed");
+        }
+        finally {
+            this.broadcastResolved(uiRequestId, entry.agentId, "answered");
+        }
+        return { ok: true };
+    }
+    listPending(agentId) {
+        const result = [];
+        for (const [wireId, entry] of this.pending) {
+            if (agentId !== undefined && entry.agentId !== agentId)
+                continue;
+            result.push({
+                requestId: wireId,
+                agentId: entry.agentId,
+                method: entry.method,
+                expectsResponse: true,
+                payload: entry.payload,
+                ...(entry.surfaceKey !== undefined ? { surfaceKey: entry.surfaceKey } : {}),
+                ...(entry.timeoutMs !== undefined ? { timeoutMs: entry.timeoutMs } : {}),
+                createdAt: entry.createdAt,
+            });
+        }
+        return result;
+    }
+    listSurfaces(agentId) {
+        if (agentId !== undefined)
+            return [...(this.surfaces.get(agentId)?.values() ?? [])];
+        const result = [];
+        for (const agentSurfaces of this.surfaces.values())
+            result.push(...agentSurfaces.values());
+        return result;
+    }
+    /**
+     * Session-terminal only (archive / delete / re-attach) — NEVER called on interrupt. For each
+     * pending entry: best-effort cancel toward **the entry's own captured session** (never a freshly
+     * attached one — on the attach-path sweep the new session never issued those provider ids),
+     * broadcast the resolution, then drop the agent's pending entries, surfaces, and — critically —
+     * call the stored channel `Unsubscribe` before dropping it, so a post-sweep emission from a dying
+     * session cannot re-create a surface for an agent that no longer has a live channel.
+     */
+    sweep(agentId, reason) {
+        for (const [wireId, entry] of this.pending) {
+            if (entry.agentId !== agentId)
+                continue;
+            this.pending.delete(wireId);
+            if (entry.timer)
+                this.clearTimer(entry.timer);
+            if (entry.session.respondToUi) {
+                try {
+                    entry.session.respondToUi(entry.providerRequestId, { cancelled: true });
+                }
+                catch (err) {
+                    this.logger?.warn({ agentId, requestId: wireId, method: entry.method, err: errorMessage(err) }, "agent-ui: sweep respondToUi failed");
+                }
+            }
+            this.broadcastResolved(wireId, agentId, reason);
+        }
+        this.surfaces.delete(agentId);
+        const unsubscribe = this.channels.get(agentId);
+        if (unsubscribe) {
+            unsubscribe();
+            this.channels.delete(agentId);
+        }
+    }
+    onProviderRequest(agentId, session, req) {
+        const now = Date.now();
+        if (req.surfaceKey !== undefined) {
+            let agentSurfaces = this.surfaces.get(agentId);
+            if (!agentSurfaces) {
+                agentSurfaces = new Map();
+                this.surfaces.set(agentId, agentSurfaces);
+            }
+            if (req.removed) {
+                agentSurfaces.delete(req.surfaceKey);
+            }
+            else {
+                agentSurfaces.set(req.surfaceKey, {
+                    agentId,
+                    method: req.method,
+                    surfaceKey: req.surfaceKey,
+                    payload: req.payload,
+                    updatedAt: now,
+                });
+            }
+        }
+        if (!KNOWN_METHODS.has(req.method)) {
+            const key = `${agentId}:${req.method}`;
+            if (!this.loggedUnknownMethods.has(key)) {
+                this.loggedUnknownMethods.add(key);
+                this.logger?.info({ agentId, method: req.method }, "agent-ui: unknown extension UI method");
+            }
+        }
+        const wireId = randomUUID();
+        if (req.expectsResponse) {
+            const entry = {
+                agentId,
+                providerRequestId: req.requestId,
+                session,
+                method: req.method,
+                payload: req.payload,
+                createdAt: now,
+                ...(req.surfaceKey !== undefined ? { surfaceKey: req.surfaceKey } : {}),
+                ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
+            };
+            if (req.timeoutMs)
+                entry.timer = this.setTimer(() => this.expire(wireId), req.timeoutMs);
+            this.pending.set(wireId, entry);
+        }
+        this.broadcastFn(this.getActiveSessions(), {
+            type: "session",
+            message: {
+                type: "agent_ui_request",
+                requestId: wireId,
+                agentId,
+                method: req.method,
+                expectsResponse: req.expectsResponse,
+                payload: req.payload,
+                ...(req.surfaceKey !== undefined ? { surfaceKey: req.surfaceKey } : {}),
+                ...(req.removed ? { removed: true } : {}),
+                ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
+                createdAt: now,
+            },
+        });
+    }
+    /** Pi's own timeout elapsed — Pi already auto-resolved the dialog on its side (docs/rpc.md: "the
+     *  client does not need to track timeouts"). Deliberately does NOT call `respondToUi`: answering
+     *  again would target an id Pi has already dropped. */
+    expire(wireId) {
+        const entry = this.pending.get(wireId);
+        if (!entry)
+            return;
+        this.pending.delete(wireId);
+        this.broadcastResolved(wireId, entry.agentId, "timeout");
+    }
+    broadcastResolved(uiRequestId, agentId, reason) {
+        this.broadcastFn(this.getActiveSessions(), {
+            type: "session",
+            message: { type: "agent_ui_resolved", requestId: uiRequestId, agentId, reason },
+        });
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=agent-ui-service.js.map

package/dist/agent/mcp-server.d.ts

@@ -1,12 +1,34 @@
 import { z } from "zod";
+import type { AgentUiPendingRequest, AgentUiResponse } from "@av-pi-studio/protocol";
 /**
- * Daemon MCP server (features/mcp-server.md). Hosts orchestration tools at `/mcp/agents` so agents
- * can control other agents + the daemon. The tool set mirrors the WS/CLI control plane. When
- * `daemon.mcp.injectIntoAgents` is enabled, a per-agent `--mcp-config` is generated for Pi (adapter
- * OAuth disabled); user/project MCP files are never touched.
+ * Daemon MCP tool registry (features/mcp-server.md). Defines the orchestration tools that are
+ * *intended* to be hosted at `/mcp/agents` so agents can control other agents + the daemon, and
+ * mirrors the WS/CLI control plane. Owns the tool registry, `create_agent` semantics, and
+ * injection-config generation, all injectable for tests.
  *
- * The transport (HTTP server) is wired in bootstrap; this module owns the tool registry, the
- * `create_agent` semantics, and the injection-config generation, all injectable for tests.
+ * NOT REACHABLE AT RUNTIME. Nothing in this repo constructs an `McpServer` outside
+ * `mcp-server.test.ts`. Specifically missing:
+ *   - no HTTP route serving `MCP_ENDPOINT_PATH` in either bootstrap;
+ *   - no `McpBackend` implementation anywhere in production code;
+ *   - no `daemon.mcp` config section (`enabled`/`injectIntoAgents` are read from deps only);
+ *   - `buildPiArgs` accepts `mcpConfigPath`, but all three Pi spawn sites pass only
+ *     `appendSystemPrompt`, so no agent is ever handed a `--mcp-config`.
+ * Sprint-010/task-001 built this registry and deferred the transport as "a bootstrap step"; that
+ * step was never taken. Consequence: every tool here is dormant — including
+ * `list_pending_permissions`/`respond_to_permission` (sprint-010) and
+ * `list_pending_ui_requests`/`respond_to_ui_request` (sprint-066/task-005) — and the
+ * agent-to-agent orchestration in `features/subagents.md` has never run.
+ *
+ * Two things a future wiring task must handle, neither of which is a simple hookup:
+ *   1. `callTool()` is a plain dispatcher, NOT an MCP protocol implementation. A real endpoint
+ *      needs JSON-RPC plus the `initialize`/`tools/list`/`tools/call` handshake over streamable
+ *      HTTP or SSE. That layer does not exist here.
+ *   2. `injectionConfig()` hardcodes `auth: false, oauth: false`, but the daemon's HTTP server is
+ *      built with `authenticate: (req) => auth.authenticateHttp(req)` (bootstrap.ts) and production
+ *      binds `0.0.0.0:6767` by default. Serving these tools unauthenticated would expose
+ *      `create_agent`/`kill_agent`/`send_agent_prompt` to the network. Bind the route to loopback
+ *      or carry a token in the injected config — the two existing code paths contradict each other
+ *      today only because neither runs.
  */
 export declare const MCP_ENDPOINT_PATH = "/mcp/agents";
 export declare const MCP_SERVER_KEY = "pi-studio-agents";
@@ -60,6 +82,15 @@ export interface McpBackend {
     respondToPermission(requestId: string, response: unknown): {
         resolved: boolean;
     };
+    /** Extension UI (features/extension-ui-rpc.md § MCP mirror) — closes the deadlock where an
+     *  orchestrating agent can't answer a child's extension questionnaire. Mirrors the permission
+     *  pair's shape; its own error vocabulary ("unknown_ui_request"/"unsupported") is intentionally
+     *  distinct — see the tool registration below for why. */
+    listPendingUiRequests(agentId?: string): AgentUiPendingRequest[];
+    respondToUiRequest(requestId: string, response: AgentUiResponse): {
+        resolved: boolean;
+        error?: string;
+    };
     listProviders(): unknown;
     inspectProvider?(providerId: string): unknown;
     listModels(providerId: string): unknown;

package/dist/agent/mcp-server.js

@@ -3,13 +3,34 @@ import { join } from "node:path";
 import { z } from "zod";
 import { PARENT_AGENT_ID_LABEL } from "./agent-manager.js";
 /**
- * Daemon MCP server (features/mcp-server.md). Hosts orchestration tools at `/mcp/agents` so agents
- * can control other agents + the daemon. The tool set mirrors the WS/CLI control plane. When
- * `daemon.mcp.injectIntoAgents` is enabled, a per-agent `--mcp-config` is generated for Pi (adapter
- * OAuth disabled); user/project MCP files are never touched.
+ * Daemon MCP tool registry (features/mcp-server.md). Defines the orchestration tools that are
+ * *intended* to be hosted at `/mcp/agents` so agents can control other agents + the daemon, and
+ * mirrors the WS/CLI control plane. Owns the tool registry, `create_agent` semantics, and
+ * injection-config generation, all injectable for tests.
  *
- * The transport (HTTP server) is wired in bootstrap; this module owns the tool registry, the
- * `create_agent` semantics, and the injection-config generation, all injectable for tests.
+ * NOT REACHABLE AT RUNTIME. Nothing in this repo constructs an `McpServer` outside
+ * `mcp-server.test.ts`. Specifically missing:
+ *   - no HTTP route serving `MCP_ENDPOINT_PATH` in either bootstrap;
+ *   - no `McpBackend` implementation anywhere in production code;
+ *   - no `daemon.mcp` config section (`enabled`/`injectIntoAgents` are read from deps only);
+ *   - `buildPiArgs` accepts `mcpConfigPath`, but all three Pi spawn sites pass only
+ *     `appendSystemPrompt`, so no agent is ever handed a `--mcp-config`.
+ * Sprint-010/task-001 built this registry and deferred the transport as "a bootstrap step"; that
+ * step was never taken. Consequence: every tool here is dormant — including
+ * `list_pending_permissions`/`respond_to_permission` (sprint-010) and
+ * `list_pending_ui_requests`/`respond_to_ui_request` (sprint-066/task-005) — and the
+ * agent-to-agent orchestration in `features/subagents.md` has never run.
+ *
+ * Two things a future wiring task must handle, neither of which is a simple hookup:
+ *   1. `callTool()` is a plain dispatcher, NOT an MCP protocol implementation. A real endpoint
+ *      needs JSON-RPC plus the `initialize`/`tools/list`/`tools/call` handshake over streamable
+ *      HTTP or SSE. That layer does not exist here.
+ *   2. `injectionConfig()` hardcodes `auth: false, oauth: false`, but the daemon's HTTP server is
+ *      built with `authenticate: (req) => auth.authenticateHttp(req)` (bootstrap.ts) and production
+ *      binds `0.0.0.0:6767` by default. Serving these tools unauthenticated would expose
+ *      `create_agent`/`kill_agent`/`send_agent_prompt` to the network. Bind the route to loopback
+ *      or carry a token in the injected config — the two existing code paths contradict each other
+ *      today only because neither runs.
  */
 export const MCP_ENDPOINT_PATH = "/mcp/agents";
 export const MCP_SERVER_KEY = "pi-studio-agents";
@@ -145,6 +166,22 @@ export class McpServer {
             const result = b.respondToPermission(args.requestId, args.response);
             return result.resolved ? { ok: true } : { ok: false, error: "unknown_permission" };
         });
+        // Extension UI (features/extension-ui-rpc.md § MCP mirror). Error vocabulary intentionally
+        // differs from `respond_to_permission`'s `unknown_permission`/the WS side's `not_found`: a
+        // `resolved:false` with no `error` (never happens for this backend) and an `unsupported`
+        // result are distinct outcomes a caller must not conflate with "unknown" — collapsing a live
+        // dialog on a provider without `respondToUi` into `unknown_ui_request` would report it as
+        // gone when it is actually still answerable over WS by a human.
+        this.registerTool("list_pending_ui_requests", z.object({ agentId: z.string().optional() }), (args) => ({ ok: true, requests: b.listPendingUiRequests(args.agentId) }));
+        this.registerTool("respond_to_ui_request", z.object({ requestId: z.string(), response: z.unknown() }), (args) => {
+            const result = b.respondToUiRequest(args.requestId, args.response);
+            if (result.resolved)
+                return { ok: true };
+            return {
+                ok: false,
+                error: result.error === "unsupported" ? "unsupported" : "unknown_ui_request",
+            };
+        });
         // Providers / models.
         this.registerTool("list_providers", z.object({}).passthrough(), () => ({
             ok: true,

package/dist/agent/provider-contract.d.ts

@@ -109,6 +109,31 @@ export interface PendingPermission {
     toolName?: string;
     detail?: unknown;
 }
+/**
+ * A provider UI request translated onto the generic channel (features/extension-ui-rpc.md § Provider
+ * contract extension). All Pi-specific knowledge (which methods block, surface-key namespacing,
+ * clear-by-omission, timeout field name) lives in the adapter that produces this — the daemon layers
+ * above never interpret `payload` or know `method`'s vocabulary.
+ */
+export interface ProviderUiRequest {
+    /** Provider-scoped id (Pi's `id`). NEVER use this as a daemon-global map key — two agents may
+     *  reuse the same provider id independently; the daemon mints its own wire id per request. */
+    requestId: string;
+    method: string;
+    expectsResponse: boolean;
+    payload: Record<string, unknown>;
+    /** Present only for retained (last-value-wins) surfaces; already namespaced by the adapter. */
+    surfaceKey?: string;
+    /** True ⇒ this update clears the surface at `surfaceKey` rather than setting it. */
+    removed?: boolean;
+    timeoutMs?: number;
+}
+/** The answer forwarded back to the provider for a dialog method. */
+export interface ProviderUiResponse {
+    value?: string;
+    confirmed?: boolean;
+    cancelled?: boolean;
+}
 /** Context passed when launching/resuming a session (cwd, env, logger, …). */
 export interface LaunchContext {
     cwd?: string;
@@ -211,6 +236,10 @@ export interface AgentSession {
     cycleModel?(): Promise<AgentCycleModelResult>;
     /** `/copy` — mirrors Pi RPC `get_last_assistant_text`. */
     getLastAssistantText?(): Promise<string | null>;
+    /** Subscribe to provider-emitted UI dialogs and fire-and-forget events. */
+    onUiRequest?(cb: (req: ProviderUiRequest) => void): Unsubscribe;
+    /** Answer a dialog by its provider-scoped `requestId` (never the daemon's minted wire id). */
+    respondToUi?(providerRequestId: string, response: ProviderUiResponse): void;
 }
 /** A provider client: creates/resumes sessions and exposes discovery. */
 export interface AgentClient {