appduct 0.9.0

package/dist/mcp/daemon-tools.js

@@ -0,0 +1,29 @@
+/**
+ * Fetches the effective (possibly namespaced) MCP tool list live from the daemon
+ * (ARCHITECTURE.md §9): `sessions.list` for the live sessions, then `tools.list` per session.
+ * There is no caching here — every `tools/list` request and every list-changed check re-fetches,
+ * since the daemon's session/registry state is the single source of truth and can change between
+ * any two calls.
+ */
+import { RPC_METHODS, } from "@appduct/shared";
+import { DaemonRpcError } from "../rpc/client.js";
+import { buildNamespacedTools } from "./tool-namespace.js";
+export const fetchEffectiveTools = async (call) => {
+    const sessions = await call(RPC_METHODS.sessionsList);
+    const toolsByAlias = new Map();
+    for (const session of sessions) {
+        try {
+            toolsByAlias.set(session.alias, await call(RPC_METHODS.toolsList, { selector: session.alias }));
+        }
+        catch (error) {
+            // The session can transition (revoke/expire) between `sessions.list` and this per-session
+            // `tools.list` call; treat it as having no tools rather than failing the whole listing.
+            if (error instanceof DaemonRpcError) {
+                toolsByAlias.set(session.alias, []);
+                continue;
+            }
+            throw error;
+        }
+    }
+    return buildNamespacedTools(sessions, toolsByAlias);
+};

package/dist/mcp/events-tool.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The built-in `appduct_events` / `appduct_wait_for_event` MCP tools (issue #6): a pull
+ * surface over the daemon's `app_event` plumbing (`postEvent()` on the app side, `events.since`'s
+ * per-session retention buffer on the daemon side — see `daemon/event-bus.ts`). MCP is
+ * request/response, so an agent otherwise has no way to observe anything the app pushes.
+ *
+ * `appduct_wait_for_event` drains the retained buffer for an already-arrived match before
+ * falling back to a live wait, exactly to avoid the race `appduct_wait_for_session` doesn't
+ * have to worry about (a session is either claimed or it isn't, but an `app_event` can easily fire
+ * between "the agent decides to wait" and "the wait subscription lands"). The live notification
+ * listener is registered *before* the `events.since` drain call is even sent — not merely before
+ * it resolves — because the daemon's response to that call and a subsequent `notify()` for a new
+ * event can arrive in the same socket chunk; `rpc/client.ts` fans a chunk's notification lines out
+ * to whatever listeners exist at the moment it's processed, so a listener added only after `await
+ * stream.call(eventsSince, …)` returns can miss an event that was already in that same chunk.
+ * Arrivals before the drain has been merged into the backlog are buffered, then merged in
+ * (deduped by `seq`) before falling through to the live phase — see `handleWaitForEventTool` below.
+ */
+import { type EventsSinceResult } from "@appduct/shared";
+import { type SpawnFn } from "../rpc/client.js";
+import type { DaemonCall } from "./daemon-tools.js";
+export declare const EVENTS_TOOL_NAME = "appduct_events";
+export declare const WAIT_FOR_EVENT_TOOL_NAME = "appduct_wait_for_event";
+/** Server-side cap on `timeoutMs` (issue #6's "Cap timeoutMs server-side below the idle window
+ * rather than trusting the caller") — a pure function so the cap's boundary behavior is
+ * unit-testable without spinning up a daemon or actually waiting out either bound. */
+export declare const clampWaitForEventTimeoutMs: (requestedMs: number | undefined) => number;
+export declare const EVENTS_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_events";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly selector: {
+                readonly type: "string";
+            };
+            readonly since: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+            readonly kinds: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                    readonly enum: readonly ["daemon_started", "link_created", "link_expired", "session_claimed", "session_suspended", "session_resumed", "session_revoked", "session_expired", "tools_changed", "app_event", "tool_call_started", "tool_call_progress", "tool_call_finished"];
+                };
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly exclusiveMinimum: 0;
+            };
+        };
+        readonly additionalProperties: false;
+    };
+};
+export declare const WAIT_FOR_EVENT_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_wait_for_event";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly selector: {
+                readonly type: "string";
+            };
+            readonly name: {
+                readonly type: "string";
+            };
+            readonly match: {
+                readonly type: "object";
+                readonly additionalProperties: {
+                    readonly type: readonly ["string", "number", "boolean", "null"];
+                };
+            };
+            readonly since: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+            readonly timeoutMs: {
+                readonly type: "number";
+                readonly exclusiveMinimum: 0;
+            };
+        };
+        readonly required: readonly ["name"];
+        readonly additionalProperties: false;
+    };
+};
+export type EventsToolDeps = {
+    call: DaemonCall;
+};
+export declare const handleEventsTool: (rawArgs: unknown, deps: EventsToolDeps) => Promise<EventsSinceResult>;
+export type WaitForEventToolDeps = {
+    stateDir: string;
+    spawn?: SpawnFn;
+    /** Present only when the incoming `tools/call` carried a progress token; used to emit periodic
+     * "still waiting" progress notifications during a live wait. */
+    progress?: {
+        token: string | number;
+        sendNotification: (notification: unknown) => Promise<void>;
+    };
+};
+export type WaitForEventToolResult = {
+    sessionId: string;
+    alias?: string;
+    name: string;
+    payload: unknown;
+    /** Unix ms. */
+    ts: number;
+    seq: number;
+};
+export declare const handleWaitForEventTool: (rawArgs: unknown, deps: WaitForEventToolDeps) => Promise<WaitForEventToolResult>;
+//# sourceMappingURL=events-tool.d.ts.map

package/dist/mcp/events-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-tool.d.ts","sourceRoot":"","sources":["../../src/mcp/events-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AACjD,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AAcjE;;sFAEsF;AACtF,eAAO,MAAM,0BAA0B,GAAI,aAAa,MAAM,GAAG,SAAS,KAAG,MAE5E,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoBzB,CAAC;AAEX,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BjC,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,UAAU,CAAC;CAClB,CAAC;AA0GF,eAAO,MAAM,gBAAgB,GAAU,SAAS,OAAO,EAAE,MAAM,cAAc,KAAG,OAAO,CAAC,iBAAiB,CASxG,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;oEACgE;IAChE,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,gBAAgB,EAAE,CAAC,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC5D,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe;IACf,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAYF,eAAO,MAAM,sBAAsB,GACjC,SAAS,OAAO,EAChB,MAAM,oBAAoB,KACzB,OAAO,CAAC,sBAAsB,CA6LhC,CAAC"}

package/dist/mcp/events-tool.js

@@ -0,0 +1,322 @@
+/**
+ * The built-in `appduct_events` / `appduct_wait_for_event` MCP tools (issue #6): a pull
+ * surface over the daemon's `app_event` plumbing (`postEvent()` on the app side, `events.since`'s
+ * per-session retention buffer on the daemon side — see `daemon/event-bus.ts`). MCP is
+ * request/response, so an agent otherwise has no way to observe anything the app pushes.
+ *
+ * `appduct_wait_for_event` drains the retained buffer for an already-arrived match before
+ * falling back to a live wait, exactly to avoid the race `appduct_wait_for_session` doesn't
+ * have to worry about (a session is either claimed or it isn't, but an `app_event` can easily fire
+ * between "the agent decides to wait" and "the wait subscription lands"). The live notification
+ * listener is registered *before* the `events.since` drain call is even sent — not merely before
+ * it resolves — because the daemon's response to that call and a subsequent `notify()` for a new
+ * event can arrive in the same socket chunk; `rpc/client.ts` fans a chunk's notification lines out
+ * to whatever listeners exist at the moment it's processed, so a listener added only after `await
+ * stream.call(eventsSince, …)` returns can miss an event that was already in that same chunk.
+ * Arrivals before the drain has been merged into the backlog are buffered, then merged in
+ * (deduped by `seq`) before falling through to the live phase — see `handleWaitForEventTool` below.
+ */
+import { RPC_METHODS, EVENT_KINDS, } from "@appduct/shared";
+import { openDaemonStream } from "../rpc/client.js";
+import { McpBuiltinToolError } from "./connect-tool.js";
+export const EVENTS_TOOL_NAME = "appduct_events";
+export const WAIT_FOR_EVENT_TOOL_NAME = "appduct_wait_for_event";
+const DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS = 120_000;
+/** Kept safely under the 30-minute idle window a stdio MCP server gets before Claude Code aborts a
+ * tool call that has sent neither a response nor a progress notification (issue #6's "Constraint on
+ * the blocking wait tool") — with margin for RPC round-trip and scheduling delay. */
+const MAX_WAIT_FOR_EVENT_TIMEOUT_MS = 25 * 60 * 1000;
+/** How often a progress notification is emitted during a live wait, when the caller supplied a
+ * progress token — informational only (the timeout cap above is what actually keeps the call
+ * within the idle window), but it gives a caller watching progress something to show. */
+const WAIT_FOR_EVENT_PROGRESS_INTERVAL_MS = 60_000;
+const KNOWN_EVENT_KINDS = new Set(EVENT_KINDS);
+/** Server-side cap on `timeoutMs` (issue #6's "Cap timeoutMs server-side below the idle window
+ * rather than trusting the caller") — a pure function so the cap's boundary behavior is
+ * unit-testable without spinning up a daemon or actually waiting out either bound. */
+export const clampWaitForEventTimeoutMs = (requestedMs) => {
+    return Math.min(requestedMs ?? DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS, MAX_WAIT_FOR_EVENT_TIMEOUT_MS);
+};
+export const EVENTS_TOOL_DESCRIPTOR = {
+    name: EVENTS_TOOL_NAME,
+    description: "Drain events retained in the daemon's per-session ring buffer since a cursor — the pull " +
+        "counterpart to a live subscription, for checking what happened after calling a tool or " +
+        "triggering app behavior. With no selector, targets the sole active/suspended session. " +
+        "Returns { events, cursor }; pass cursor back as since on the next call to avoid re-reading " +
+        "events you've already seen. limit (if given) keeps the OLDEST events in the window and " +
+        "advances cursor only past what was actually returned, so repeated calls page forward through " +
+        "everything retained rather than skipping ahead.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            selector: { type: "string" },
+            since: { type: "integer", minimum: 0 },
+            kinds: { type: "array", items: { type: "string", enum: EVENT_KINDS } },
+            limit: { type: "integer", exclusiveMinimum: 0 },
+        },
+        additionalProperties: false,
+    },
+};
+export const WAIT_FOR_EVENT_TOOL_DESCRIPTOR = {
+    name: WAIT_FOR_EVENT_TOOL_NAME,
+    description: "Wait for the connected app to push an event via postEvent(name, payload) matching name (and, " +
+        "if match is given, every one of its keys strictly-equal — primitives only, not objects/arrays " +
+        "— in the event's payload). Checks already-retained events first, so an event that already " +
+        "fired before this call still resolves immediately; pass since (a cursor from a previous " +
+        "appduct_events/appduct_wait_for_event call) to skip events you've already handled and " +
+        "wait only for a new one — omitting it can return an old match instantly on every call. " +
+        "Requires a claimed session to already exist (use appduct_wait_for_session first if not). " +
+        "Resolves with { sessionId, alias, name, payload, ts, seq }, or rejects with tool_timeout after " +
+        "timeoutMs (default 120000ms, capped server-side at 1500000ms). A call still running after " +
+        "about two minutes moves to a Claude Code background task, so the result may arrive well after " +
+        "this call returns.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            selector: { type: "string" },
+            name: { type: "string" },
+            match: { type: "object", additionalProperties: { type: ["string", "number", "boolean", "null"] } },
+            since: { type: "integer", minimum: 0 },
+            timeoutMs: { type: "number", exclusiveMinimum: 0 },
+        },
+        required: ["name"],
+        additionalProperties: false,
+    },
+};
+const asRecord = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+};
+const asOptionalString = (value, field) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.length === 0) {
+        throw new McpBuiltinToolError("invalid_request", `"${field}" must be a non-empty string.`);
+    }
+    return value;
+};
+/** `since`/`limit` mirror the daemon's own `asEventsSinceParams` (`daemon/daemon.ts`), which
+ * requires integers — accepting e.g. `1.5` here would just round-trip to a `DaemonRpcError`
+ * instead of this tool's own clearer `invalid_request`. */
+const asOptionalNonNegativeInteger = (value, field) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new McpBuiltinToolError("invalid_request", `"${field}" must be a non-negative integer.`);
+    }
+    return value;
+};
+const asOptionalPositiveInteger = (value, field) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new McpBuiltinToolError("invalid_request", `"${field}" must be a positive integer.`);
+    }
+    return value;
+};
+/** `timeoutMs` is not required to be an integer (unlike the daemon's `since`/`limit`) — it's never
+ * forwarded to the daemon verbatim, only used as this process's own `setTimeout` duration. */
+const asOptionalPositiveNumber = (value, field) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new McpBuiltinToolError("invalid_request", `"${field}" must be a positive number.`);
+    }
+    return value;
+};
+const asOptionalEventKinds = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value) || !value.every((kind) => typeof kind === "string" && KNOWN_EVENT_KINDS.has(kind))) {
+        throw new McpBuiltinToolError("invalid_request", '"kinds" must be an array of known event kinds.');
+    }
+    return value;
+};
+const isMatchPrimitive = (value) => {
+    return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+};
+/** `payloadShallowMatches` compares with `===`, so an object/array value here could never equal
+ * anything and would just make the wait time out with no explanation — reject it up front instead. */
+const asOptionalMatch = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new McpBuiltinToolError("invalid_request", '"match" must be a JSON object.');
+    }
+    const record = value;
+    for (const [key, entry] of Object.entries(record)) {
+        if (!isMatchPrimitive(entry)) {
+            throw new McpBuiltinToolError("invalid_request", `"match.${key}" must be a string, number, boolean, or null (objects/arrays can never match).`);
+        }
+    }
+    return record;
+};
+export const handleEventsTool = async (rawArgs, deps) => {
+    const args = asRecord(rawArgs);
+    return deps.call(RPC_METHODS.eventsSince, {
+        selector: asOptionalString(args.selector, "selector"),
+        since: asOptionalNonNegativeInteger(args.since, "since"),
+        kinds: asOptionalEventKinds(args.kinds),
+        limit: asOptionalPositiveInteger(args.limit, "limit"),
+    });
+};
+const payloadShallowMatches = (payload, match) => {
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        return false;
+    }
+    const record = payload;
+    return Object.entries(match).every(([key, value]) => record[key] === value);
+};
+export const handleWaitForEventTool = async (rawArgs, deps) => {
+    const args = asRecord(rawArgs);
+    const selector = asOptionalString(args.selector, "selector");
+    const name = asOptionalString(args.name, "name");
+    if (!name) {
+        throw new McpBuiltinToolError("invalid_request", '"name" must be a non-empty string.');
+    }
+    const match = asOptionalMatch(args.match);
+    const since = asOptionalNonNegativeInteger(args.since, "since");
+    const timeoutMs = clampWaitForEventTimeoutMs(asOptionalPositiveNumber(args.timeoutMs, "timeoutMs"));
+    const stream = await openDaemonStream({ stateDir: deps.stateDir, spawn: deps.spawn });
+    try {
+        // Resolve the selector to one concrete session up front (same shape as
+        // `handleWaitForSessionTool`) so the buffer drain below and the live subscription target the
+        // exact same session — `events.subscribe`'s own `sessionSelector` has no "sole session" default,
+        // so leaving it unresolved here would silently widen the live half of the wait to every session.
+        // A `DaemonRpcError` (no_session/ambiguous_session/unknown_session) propagates unchanged —
+        // `toolErrorContentFromError` (mcp/server.ts) already maps it to its precise `data.type`.
+        const described = await stream.call(RPC_METHODS.sessionsDescribe, { selector });
+        const sessionId = described.sessionId;
+        const alias = described.alias;
+        const toResult = (event) => {
+            if (event.kind !== "app_event" || event.sessionId !== sessionId) {
+                return undefined;
+            }
+            const data = event.data;
+            if (data.name !== name) {
+                return undefined;
+            }
+            if (match && !payloadShallowMatches(data.payload, match)) {
+                return undefined;
+            }
+            return { sessionId, alias, name, payload: data.payload, ts: event.ts, seq: event.seq };
+        };
+        // The notification listener is registered *before* `events.subscribe` is even sent, and starts
+        // buffering into `earlyEvents` rather than resolving anything (`liveHandler` is still null) —
+        // see the module doc comment for why: the `events.since` response and a `notify()` for a
+        // brand-new event can arrive in the same socket chunk, and a listener added only after `await`ing
+        // that response has already missed a notification line from that same chunk.
+        let liveHandler = null;
+        const earlyEvents = [];
+        const unsubscribeNotification = stream.onNotification((payload) => {
+            const event = payload;
+            if (liveHandler) {
+                liveHandler(event);
+            }
+            else {
+                earlyEvents.push(event);
+            }
+        });
+        let unsubscribeClose = () => { };
+        try {
+            await stream.call(RPC_METHODS.eventsSubscribe, { sessionSelector: sessionId, kinds: ["app_event"] });
+            const sinceResult = await stream.call(RPC_METHODS.eventsSince, {
+                selector: sessionId,
+                since,
+                kinds: ["app_event"],
+            });
+            // Merge the retained backlog with whatever arrived on the live channel while the two calls
+            // above were in flight, deduped by `seq` (the same event can legitimately show up in both:
+            // the daemon buffers before it fans out, so a late-drained event and an in-flight live one can
+            // be the same notification). Everything from here to `liveHandler = …` below is synchronous —
+            // no `await` — so nothing can arrive on the socket and be missed in the gap.
+            const seenSeqs = new Set();
+            const backlog = [];
+            for (const event of [...sinceResult.events, ...earlyEvents]) {
+                if (event.sessionId === sessionId && !seenSeqs.has(event.seq)) {
+                    seenSeqs.add(event.seq);
+                    backlog.push(event);
+                }
+            }
+            backlog.sort((a, b) => a.seq - b.seq);
+            for (const event of backlog) {
+                const result = toResult(event);
+                if (result) {
+                    return result;
+                }
+            }
+            // Nothing matched yet: the cursor to resume live from is the last event actually considered
+            // (backlog's own scan already covers everything since.events + earlyEvents jointly saw), or —
+            // if nothing was retained/arrived at all — `events.since`'s own cursor, which (per
+            // `event-bus.ts`'s `since()`) already reflects the session's true high-water mark even when
+            // the `kinds` filter matched nothing.
+            const highestConsideredSeq = backlog.length > 0 ? backlog[backlog.length - 1].seq : sinceResult.cursor;
+            return await new Promise((resolve, reject) => {
+                let settled = false;
+                const settle = (fn) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    clearTimeout(timer);
+                    if (progressTimer) {
+                        clearInterval(progressTimer);
+                    }
+                    liveHandler = null;
+                    fn();
+                };
+                const timer = setTimeout(() => {
+                    settle(() => reject(new McpBuiltinToolError("tool_timeout", `Timed out after ${timeoutMs}ms waiting for event "${name}".`)));
+                }, timeoutMs);
+                const startedAt = Date.now();
+                const progressTimer = deps.progress
+                    ? setInterval(() => {
+                        deps.progress.sendNotification({
+                            method: "notifications/progress",
+                            params: {
+                                progressToken: deps.progress.token,
+                                progress: Date.now() - startedAt,
+                                total: timeoutMs,
+                                message: `Still waiting for event "${name}"...`,
+                            },
+                        }).catch(() => {
+                            // A failed progress notification must never abort the wait itself.
+                        });
+                    }, WAIT_FOR_EVENT_PROGRESS_INTERVAL_MS)
+                    : undefined;
+                unsubscribeClose = stream.onClose(() => {
+                    settle(() => reject(new McpBuiltinToolError("tool_execution_error", `The connection to the Appduct daemon closed while waiting for event "${name}".`)));
+                });
+                // From here on, every notification goes straight to this handler instead of `earlyEvents` —
+                // assigned synchronously (no `await` since the backlog scan above), so nothing is missed.
+                liveHandler = (event) => {
+                    if (settled) {
+                        return;
+                    }
+                    if (event.sessionId === sessionId && event.seq <= highestConsideredSeq) {
+                        return;
+                    }
+                    const result = toResult(event);
+                    if (result) {
+                        settle(() => resolve(result));
+                    }
+                };
+            });
+        }
+        finally {
+            unsubscribeNotification();
+            unsubscribeClose();
+        }
+    }
+    finally {
+        stream.close();
+    }
+};

package/dist/mcp/server.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The `appduct mcp` stdio MCP server (ARCHITECTURE.md §9): a thin proxy that maps the daemon RPC
+ * surface (`rpc/client.ts`, same auto-spawning client the CLI uses) onto MCP's `tools/list`,
+ * `tools/call`, `notifications/tools/list_changed`, progress notifications, and one resource
+ * (`appduct://sessions`). All logging here goes to stderr only — stdout is reserved for the MCP
+ * transport's protocol frames.
+ *
+ * One persistent daemon connection (`stream`) is used for everything except progress-correlated
+ * `tools.call`s, which get their own short-lived connection (see `callProxiedTool` below) so the
+ * `tool_call_started` event that reveals the call's `callId` is unambiguous.
+ *
+ * This is also where both `"prompt"`-policy consent channels live (ARCHITECTURE.md §12):
+ * `resolveToolCallConsent` prefers `elicitation/create` (issue #10, any client that declares the
+ * `elicitation` capability) over the `_meta["anthropic/requiresUserInteraction"]` flag (issue #14,
+ * Claude Code ≥ v2.1.199 only), and the two never arm for the same call — see
+ * `clientSupportsElicitation` and the `tools/list` handler below.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { ExecFn } from "../cli/open-target.js";
+import { type SpawnFn, type VersionCheckOptions } from "../rpc/client.js";
+export declare const SESSIONS_RESOURCE_URI = "appduct://sessions";
+export type CreateMcpServerOptions = {
+    stateDir: string;
+    spawn?: SpawnFn;
+    /**
+     * Daemon/CLI version check (issue #30), applied to the startup stream only — never to the
+     * short-lived progress streams below, which must never restart the daemon out from under a call
+     * that is already in flight. A mismatch that cannot be resolved therefore fails server startup,
+     * with the same message the CLI prints. Drift introduced *after* this server started is out of
+     * scope: nothing re-checks a connection that is already established.
+     */
+    checkVersion?: VersionCheckOptions;
+    /** The scheme composing `appduct_connect`'s deep link, already resolved by `commands/mcp.ts`
+     * against the shared order in `scheme.ts` (`--scheme` > `APPDUCT_SCHEME` > project
+     * `.appduct/config.json` > state `config.json` > `app.json`). May legitimately be undefined —
+     * the server starts either way and only `appduct_connect` needs one. */
+    scheme?: string;
+    /** Every location consulted while resolving {@link scheme}, so `appduct_connect` can name
+     * them when it has to fail. Only meaningful when `scheme` is undefined. */
+    schemeTried?: string[];
+    /** `config.json`'s `iosBundleId`; the default bundle id for `appduct_connect`'s experimental
+     * `ios-device` target (issue #31). */
+    iosBundleId?: string;
+    exec?: ExecFn;
+    env?: NodeJS.ProcessEnv;
+    /** Overrides `ELICITATION_TIMEOUT_MS` (ARCHITECTURE.md §12 / issue #10) — test-only seam so the
+     * timeout branch of `requestElicitationConsent` can be exercised without an actual 10-minute
+     * wait. Every real caller (`cli/mcp-command.ts`) leaves this unset. */
+    elicitationTimeoutMs?: number;
+};
+export type McpServerHandle = {
+    server: Server;
+    connect: (transport: Transport) => Promise<void>;
+    close: () => Promise<void>;
+};
+export declare const createMcpServer: (options: CreateMcpServerOptions) => Promise<McpServerHandle>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAa/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,mBAAmB,EACzB,MAAM,kBAAkB,CAAC;AAwB1B,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AA8Q1D,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC;;;4EAGwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;+EAC2E;IAC3E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;0CACsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;2EAEuE;IACvE,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,SAAS,sBAAsB,KAAG,OAAO,CAAC,eAAe,CAiY9F,CAAC"}