appduct 0.9.0

package/dist/link.js

@@ -0,0 +1,117 @@
+/**
+ * Shared core of `link.create` + deep-link composition + optional emulator/simulator delivery
+ * (ARCHITECTURE.md §8, §10): mints a pending session via `link.create`, then composes
+ * `<scheme>:///?appduct=<payload>&pin=<spki-pin>` and optionally delivers it to a booted
+ * Android emulator/device or iOS simulator. Used by `commands/link.ts` (`appduct link`) and
+ * `client/bootstrap.ts` (`appduct/client`'s `link()`) so this shape — scheme resolution, the
+ * `pin` query param, the `127.0.0.1` emulator/simulator address override (which the experimental
+ * `ios-device` target deliberately opts out of) — can't drift between the CLI and the programmatic
+ * client.
+ *
+ * The `pin` param is separate from the `appduct` bootstrap blob (opt-in hardening dev-mode) — it
+ * is never part of that binary v2 payload, so old apps that don't know about it simply ignore it.
+ * It carries the daemon's SPKI pin (same value as `daemon.status`'s `pinnedKeys[0]` / `appduct
+ * keygen`'s output) so a debug build with no build-time `cliPins` configured can trust it for this
+ * one connection instead of requiring a native rebuild just to test locally. The pin is standard
+ * (non-URL-safe) base64 (`sha256/<44-char-base64>`, may contain `+`/`/`/`=`), so it is percent-
+ * encoded here; native/JS parsers use `URLSearchParams`, which decodes it back.
+ */
+import { RPC_METHODS } from "@appduct/shared";
+import { deliverToOpenTarget, isOpenTarget, isValidBundleId, invalidBundleIdMessage, isLoopbackAddress, loopbackAddressMessage, usesLoopbackAddress, MISSING_BUNDLE_ID_MESSAGE, OPEN_TARGETS, } from "./cli/open-target.js";
+import { loadConfig } from "./daemon/config.js";
+import { getStateDirPaths } from "./daemon/state-dir.js";
+import { usageError } from "./errors.js";
+import { callDaemon } from "./rpc/client.js";
+import { resolveSchemeOrThrow } from "./scheme.js";
+/** The emulator/simulator fast path forces `127.0.0.1`: the daemon's wss listener already binds
+ * all interfaces, and both delivery mechanisms (adb reverse, the iOS simulator's shared host
+ * network) make the daemon reachable there regardless of the machine's real LAN address. A
+ * physical iOS device (`ios-device`) has no such tunnel, so it keeps the detected LAN address —
+ * see `usesLoopbackAddress`. */
+const OPEN_TARGET_ADDRESS_OVERRIDE = "127.0.0.1";
+/**
+ * The deep-link shape, in one place: `<scheme>:///?appduct=<payload>&pin=<spki-pin>`. Exported
+ * so `mcp/connect-tool.ts` composes byte-identical links rather than a second, drifting copy — the
+ * `pin` param went missing from the MCP side exactly because there were two of these.
+ *
+ * The pin is standard (non-URL-safe) base64 (`sha256/<44 chars>`, possibly containing `+`/`/`/`=`),
+ * so it is percent-encoded; parsers use `URLSearchParams`, which decodes it back. It is appended
+ * *after* the bootstrap blob, so anything reading `appduct=` must stop at the `&`.
+ */
+export const composeDeepLink = (scheme, result) => `${scheme}:///?appduct=${result.deepLinkPayload}&pin=${encodeURIComponent(result.pin)}`;
+/** Throws `usageError`/`AppductCliError` on validation failure — `commands/link.ts` renders
+ * that straight through the CLI's own error path; `client/bootstrap.ts` converts it to a
+ * `AppductError` via `toAppductError` (which already understands `AppductCliError`). */
+export const mintLink = async (options) => {
+    if (options.target !== undefined && !isOpenTarget(options.target)) {
+        throw usageError(`"target" must be one of ${OPEN_TARGETS.map((target) => `"${target}"`).join(", ")} (got "${options.target}").`);
+    }
+    if (options.device !== undefined && options.target === undefined) {
+        throw usageError('"device" only applies alongside a target.');
+    }
+    if (options.bundleId !== undefined && options.target !== "ios-device") {
+        throw usageError('"bundleId" only applies alongside target "ios-device".');
+    }
+    if (options.relaunch !== undefined && options.target !== "ios-device") {
+        throw usageError('"relaunch" only applies alongside target "ios-device".');
+    }
+    const paths = getStateDirPaths(options.stateDir);
+    const config = await loadConfig(paths);
+    const scheme = await resolveSchemeOrThrow({
+        flagScheme: options.scheme,
+        env: options.schemeEnv,
+        cwd: options.cwd,
+        configScheme: config.scheme,
+        stateConfigPath: paths.configPath,
+        stateDirRoot: paths.root,
+    });
+    // `ios-device` needs a bundle id `devicectl` can launch; resolved (and required) *before* the
+    // link is minted so a missing one is a plain usage error rather than a stranded pending session.
+    const bundleId = options.target === "ios-device" ? (options.bundleId ?? config.iosBundleId) : undefined;
+    if (options.target === "ios-device" && !bundleId) {
+        throw usageError(MISSING_BUNDLE_ID_MESSAGE);
+    }
+    if (bundleId !== undefined && !isValidBundleId(bundleId)) {
+        throw usageError(invalidBundleIdMessage(bundleId));
+    }
+    const result = await callDaemon(RPC_METHODS.linkCreate, {
+        ttlSeconds: options.ttlSeconds,
+        addressOverride: options.target && usesLoopbackAddress(options.target) ? OPEN_TARGET_ADDRESS_OVERRIDE : undefined,
+    }, { stateDir: options.stateDir, spawn: options.spawn, autoSpawn: options.autoSpawn });
+    // A physical device is the one target that cannot reach a loopback address, and
+    // `detectAdvertisedAddress` falls back to `127.0.0.1` when it finds no routable interface. Left
+    // unchecked, the link would be delivered happily and then never claimed — a silent hang in
+    // `wait_for_session` with nothing pointing at the cause.
+    if (options.target === "ios-device" && isLoopbackAddress(result.endpoint.address)) {
+        throw usageError(loopbackAddressMessage(result.endpoint.address));
+    }
+    const deepLink = composeDeepLink(scheme, result);
+    if (options.target) {
+        await deliverToOpenTarget({
+            target: options.target,
+            deepLink,
+            wssPort: result.endpoint.port,
+            device: options.device,
+            bundleId,
+            relaunch: options.relaunch,
+            exec: options.exec,
+            env: options.env,
+        });
+        return {
+            sessionId: result.sessionId,
+            deepLink,
+            endpoint: result.endpoint,
+            expiresAt: result.expiresAt,
+            pin: result.pin,
+            delivered: true,
+            target: options.target,
+        };
+    }
+    return {
+        sessionId: result.sessionId,
+        deepLink,
+        endpoint: result.endpoint,
+        expiresAt: result.expiresAt,
+        pin: result.pin,
+    };
+};

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

@@ -0,0 +1,115 @@
+/**
+ * The built-in `appduct_connect` / `appduct_wait_for_session` management tools
+ * (ARCHITECTURE.md §9 scope item 4): let an MCP agent bootstrap a device session without shell
+ * access — mint a link (and, whenever a device can be found, deliver it via the task-07
+ * emulator/simulator fast path), then wait for it to be claimed.
+ *
+ * Delivery is attempted by *default*, not only on request: an agent that omitted `target` used to
+ * get a QR code, which is a flow that cannot complete without a human noticing and scanning it.
+ * The overwhelmingly common case — one booted simulator or emulator, no human watching — now just
+ * works, and the QR path is reserved for when there is genuinely nothing to deliver to (or the
+ * caller asked for it with `target: "none"`), where it carries explicit instructions telling the
+ * agent to show the code and ask.
+ */
+import { type ExecFn, type OpenTarget } from "../cli/open-target.js";
+import { type SpawnFn } from "../rpc/client.js";
+import type { DaemonCall } from "./daemon-tools.js";
+export declare const CONNECT_TOOL_NAME = "appduct_connect";
+export declare const WAIT_FOR_SESSION_TOOL_NAME = "appduct_wait_for_session";
+export declare const CONNECT_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_connect";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly target: {
+                readonly type: "string";
+                readonly enum: readonly ["android", "ios-sim", "ios-device", "none"];
+            };
+            readonly device: {
+                readonly type: "string";
+            };
+            readonly bundleId: {
+                readonly type: "string";
+            };
+            readonly relaunch: {
+                readonly type: "boolean";
+            };
+            readonly ttlSeconds: {
+                readonly type: "number";
+                readonly exclusiveMinimum: 0;
+            };
+        };
+        readonly additionalProperties: false;
+    };
+};
+export declare const WAIT_FOR_SESSION_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_wait_for_session";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly sessionId: {
+                readonly type: "string";
+            };
+            readonly timeoutMs: {
+                readonly type: "number";
+                readonly exclusiveMinimum: 0;
+            };
+        };
+        readonly required: readonly ["sessionId"];
+        readonly additionalProperties: false;
+    };
+};
+/** Errors from the built-in management tools reuse the daemon's wire `ErrorType` union
+ * (`RpcApplicationError`-style: `{ type, message }`) so the MCP server's generic error-content
+ * mapping (see `server.ts`) handles them the same way it handles a proxied device tool's error. */
+export declare class McpBuiltinToolError extends Error {
+    readonly type: "invalid_request" | "tool_timeout" | "tool_execution_error";
+    constructor(type: "invalid_request" | "tool_timeout" | "tool_execution_error", message: string);
+}
+export type ConnectToolDeps = {
+    call: DaemonCall;
+    /** The scheme composing the deep link (`<scheme>:///?appduct=<payload>`), resolved once at
+     * server startup against the shared order in `scheme.ts` — the same one `appduct link` uses,
+     * so an app root with an `app.json` needs no configuration at all. */
+    scheme?: string;
+    /** Every location `scheme.ts` consulted, named in the failure below so an agent can tell its
+     * human exactly where to put a scheme instead of guessing at one global file. */
+    schemeTried?: string[];
+    /** `config.json`'s `iosBundleId`, the default for the experimental `ios-device` target when the
+     * call did not pass `bundleId`. Same source order as `scheme`. */
+    iosBundleId?: string;
+    exec?: ExecFn;
+    env?: NodeJS.ProcessEnv;
+};
+export type ConnectToolResult = {
+    sessionId: string;
+    deepLink: string;
+    expiresAt: number;
+    delivered?: true;
+    target?: OpenTarget;
+    /** The adb serial / simulator udid the link was delivered to, when one was resolved. */
+    device?: string;
+    /** Set when no `target` was given and exactly one device was found and used. */
+    autoDetected?: true;
+    /** Why this call did or did not deliver — the deciding detail an agent needs to explain itself
+     * (or to re-call with an explicit target). */
+    note?: string;
+    /** Present only on the QR path: a scannable QR of the deep link, rendered as text. */
+    qr?: string;
+    /** Present only on the QR path: what the agent must do before waiting. See {@link QR_INSTRUCTIONS}. */
+    instructions?: string;
+};
+export declare const handleConnectTool: (rawArgs: unknown, deps: ConnectToolDeps) => Promise<ConnectToolResult>;
+export type WaitForSessionToolDeps = {
+    stateDir: string;
+    spawn?: SpawnFn;
+};
+export type WaitForSessionToolResult = {
+    sessionId: string;
+    claimed: true;
+    alias: string;
+};
+export declare const handleWaitForSessionTool: (rawArgs: unknown, deps: WaitForSessionToolDeps) => Promise<WaitForSessionToolResult>;
+//# sourceMappingURL=connect-tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connect-tool.d.ts","sourceRoot":"","sources":["../../src/mcp/connect-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,OAAO,EAUL,KAAK,MAAM,EACX,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAKL,KAAK,OAAO,EACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AACnD,eAAO,MAAM,0BAA0B,6BAA6B,CAAC;AA6BrE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;CA2B1B,CAAC;AAEX,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;CAiBnC,CAAC;AAEX;;mGAEmG;AACnG,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,GAAG,sBAAsB;gBAAjE,IAAI,EAAE,iBAAiB,GAAG,cAAc,GAAG,sBAAsB,EAC1E,OAAO,EAAE,MAAM;CAKlB;AA6DD,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB;;0EAEsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;qFACiF;IACjF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;sEACkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,YAAY,CAAC,EAAE,IAAI,CAAC;IACpB;kDAC8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uGAAuG;IACvG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAsEF,eAAO,MAAM,iBAAiB,GAC5B,SAAS,OAAO,EAChB,MAAM,eAAe,KACpB,OAAO,CAAC,iBAAiB,CA4I3B,CAAC;AA6BF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,SAAS,OAAO,EAChB,MAAM,sBAAsB,KAC3B,OAAO,CAAC,wBAAwB,CAiHlC,CAAC"}

package/dist/mcp/connect-tool.js

@@ -0,0 +1,396 @@
+/**
+ * The built-in `appduct_connect` / `appduct_wait_for_session` management tools
+ * (ARCHITECTURE.md §9 scope item 4): let an MCP agent bootstrap a device session without shell
+ * access — mint a link (and, whenever a device can be found, deliver it via the task-07
+ * emulator/simulator fast path), then wait for it to be claimed.
+ *
+ * Delivery is attempted by *default*, not only on request: an agent that omitted `target` used to
+ * get a QR code, which is a flow that cannot complete without a human noticing and scanning it.
+ * The overwhelmingly common case — one booted simulator or emulator, no human watching — now just
+ * works, and the QR path is reserved for when there is genuinely nothing to deliver to (or the
+ * caller asked for it with `target: "none"`), where it carries explicit instructions telling the
+ * agent to show the code and ask.
+ */
+import { RPC_METHODS, } from "@appduct/shared";
+import { deliverToOpenTarget, detectBootedTargets, isOpenTarget, isValidBundleId, invalidBundleIdMessage, isLoopbackAddress, loopbackAddressMessage, usesLoopbackAddress, MISSING_BUNDLE_ID_MESSAGE, } from "../cli/open-target.js";
+import { composeDeepLink } from "../link.js";
+import { renderQrToTerminal } from "../qr-terminal.js";
+import { describeMissingScheme } from "../scheme.js";
+import { openDaemonStream, DaemonRpcError, isDaemonUnreachableError, } from "../rpc/client.js";
+export const CONNECT_TOOL_NAME = "appduct_connect";
+export const WAIT_FOR_SESSION_TOOL_NAME = "appduct_wait_for_session";
+/** The emulator/simulator fast path forces `127.0.0.1` — same reasoning as `cli/link.ts`. The
+ * experimental `ios-device` target is excluded (`usesLoopbackAddress`): a physical iPhone reaches
+ * the daemon only over the LAN. */
+const OPEN_TARGET_ADDRESS_OVERRIDE = "127.0.0.1";
+const DEFAULT_WAIT_TIMEOUT_MS = 120_000;
+/** `target: "none"` — an explicit opt out of delivery, for when the human/QR flow is what is
+ * actually wanted (a physical device on the same network, say). Distinct from omitting `target`,
+ * which now means "figure it out". */
+const NO_TARGET = "none";
+/**
+ * Attached to every QR-path result. Without this an agent reliably minted a link, said nothing
+ * about it, and went straight to `appduct_wait_for_session` — which then blocked for its full
+ * timeout waiting on a scan nobody had been asked to perform.
+ */
+const QR_INSTRUCTIONS = "This link was NOT delivered to a device — a human has to open it. Before calling " +
+    "appduct_wait_for_session: show the user the \"qr\" field verbatim inside a fenced code block " +
+    "(it is pre-rendered terminal art — do not redraw, summarize, or describe it), show \"deepLink\" " +
+    "underneath it for a device that cannot scan, and ask the user to scan it with the target " +
+    "device. Only then call appduct_wait_for_session; it blocks until the device connects and " +
+    "gives no output while it waits, so calling it before you have asked will look like a hang.";
+export const CONNECT_TOOL_DESCRIPTOR = {
+    name: CONNECT_TOOL_NAME,
+    description: "Mint a Appduct session link and get it onto a device. With no \"target\", auto-detects a " +
+        "booted iOS simulator or attached Android device and delivers the link to it, returning " +
+        "{ sessionId, delivered: true, autoDetected: true } — this is the normal agent path and needs " +
+        "no human. Pass target \"android\" or \"ios-sim\" (optionally with \"device\") to choose " +
+        "explicitly, or target \"none\" to force the human flow. Target \"ios-device\" is an " +
+        "experimental, never-auto-detected path that delivers to a paired physical iPhone/iPad via " +
+        "xcrun devicectl; it needs \"bundleId\" (or \"iosBundleId\" in config.json), iOS 17+, Xcode " +
+        "15+, a connected and trusted device with Developer Mode on, a dev-signed build installed, and " +
+        "the phone on the same network as this machine. Pass \"relaunch\": true with it if the app is " +
+        "already running and the delivery does not take. Only when no device is " +
+        "detected (or target is \"none\") does this return a QR code for a human to scan, along with " +
+        "an \"instructions\" field saying what to do with it. Follow up with " +
+        "appduct_wait_for_session to know when the device has connected.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            target: { type: "string", enum: ["android", "ios-sim", "ios-device", NO_TARGET] },
+            device: { type: "string" },
+            bundleId: { type: "string" },
+            relaunch: { type: "boolean" },
+            ttlSeconds: { type: "number", exclusiveMinimum: 0 },
+        },
+        additionalProperties: false,
+    },
+};
+export const WAIT_FOR_SESSION_TOOL_DESCRIPTOR = {
+    name: WAIT_FOR_SESSION_TOOL_NAME,
+    description: "Wait for a session minted by appduct_connect to be claimed by a device. Resolves as soon " +
+        "as the device connects (or immediately if it already has); rejects with tool_timeout if " +
+        "timeoutMs elapses first. If appduct_connect returned a QR instead of delivering the link, " +
+        "show that QR to the user and ask them to scan it before calling this — it produces no output " +
+        "while it waits.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            sessionId: { type: "string" },
+            timeoutMs: { type: "number", exclusiveMinimum: 0 },
+        },
+        required: ["sessionId"],
+        additionalProperties: false,
+    },
+};
+/** Errors from the built-in management tools reuse the daemon's wire `ErrorType` union
+ * (`RpcApplicationError`-style: `{ type, message }`) so the MCP server's generic error-content
+ * mapping (see `server.ts`) handles them the same way it handles a proxied device tool's error. */
+export class McpBuiltinToolError extends Error {
+    type;
+    constructor(type, message) {
+        super(message);
+        this.type = type;
+        this.name = "McpBuiltinToolError";
+    }
+}
+const asRecord = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+};
+const asOptionalConnectTarget = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || !(isOpenTarget(value) || value === NO_TARGET)) {
+        throw new McpBuiltinToolError("invalid_request", '"target" must be "android", "ios-sim", "ios-device", or "none".');
+    }
+    return value;
+};
+const asOptionalNonEmptyString = (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;
+};
+const asOptionalBoolean = (value, field) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "boolean") {
+        throw new McpBuiltinToolError("invalid_request", `"${field}" must be a boolean.`);
+    }
+    return value;
+};
+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;
+};
+/**
+ * Decides where (if anywhere) this link is going, *before* it is minted: the `127.0.0.1` address
+ * override baked into a link depends on whether it is being delivered locally, and that cannot be
+ * revised after `link.create`. A link minted for loopback and then fallen back to a QR code would
+ * be unscannable-in-effect — the address would be wrong for the phone that scanned it.
+ */
+const resolveDelivery = async (requested, device, bundleId, deps) => {
+    if (requested !== undefined && requested !== NO_TARGET) {
+        // `ios-device` is reachable only through this branch: `detectBootedTargets` never returns it,
+        // so a paired iPhone can never be picked up by the auto-detection path below.
+        return {
+            delivery: {
+                target: requested,
+                device,
+                ...(requested === "ios-device" ? { bundleId: bundleId ?? deps.iosBundleId } : {}),
+                label: device ?? requested,
+                autoDetected: false,
+            },
+        };
+    }
+    if (requested === NO_TARGET) {
+        return {
+            note: 'Called with target: "none", so no device delivery was attempted.',
+        };
+    }
+    const detection = await detectBootedTargets({ exec: deps.exec, env: deps.env });
+    if (detection.kind === "single") {
+        return { delivery: { ...detection.detected, autoDetected: true } };
+    }
+    if (detection.kind === "ambiguous") {
+        return {
+            note: 'No "target" was given and several devices are available (' +
+                detection.candidates.map((candidate) => `${candidate.target}: ${candidate.label}`).join("; ") +
+                '), so none was picked automatically. Re-call with "target" and "device" to deliver to one ' +
+                "of them, or use the QR below.",
+        };
+    }
+    return {
+        note: 'No "target" was given and no booted iOS simulator or attached Android device was detected, ' +
+            "so the link could not be delivered automatically. A physical iPhone/iPad is never " +
+            'auto-detected: to deliver to one, re-call with target "ios-device" plus "bundleId" (needs ' +
+            "iOS 17+, Xcode 15+ and a paired, trusted device with Developer Mode on) — otherwise use " +
+            "the QR flow below.",
+    };
+};
+export const handleConnectTool = async (rawArgs, deps) => {
+    const args = asRecord(rawArgs);
+    const requestedTarget = asOptionalConnectTarget(args.target);
+    const device = asOptionalNonEmptyString(args.device, "device");
+    const bundleId = asOptionalNonEmptyString(args.bundleId, "bundleId");
+    const relaunch = asOptionalBoolean(args.relaunch, "relaunch");
+    const ttlSeconds = asOptionalPositiveNumber(args.ttlSeconds, "ttlSeconds");
+    if (device !== undefined && (requestedTarget === undefined || requestedTarget === NO_TARGET)) {
+        throw new McpBuiltinToolError("invalid_request", '"device" requires an explicit "target" of "android", "ios-sim" or "ios-device" — a bare ' +
+            "serial/udid does not say which platform it belongs to.");
+    }
+    if (bundleId !== undefined && requestedTarget !== "ios-device") {
+        throw new McpBuiltinToolError("invalid_request", '"bundleId" only applies with target "ios-device".');
+    }
+    if (relaunch !== undefined && requestedTarget !== "ios-device") {
+        throw new McpBuiltinToolError("invalid_request", '"relaunch" only applies with target "ios-device".');
+    }
+    if (!deps.scheme) {
+        throw new McpBuiltinToolError("invalid_request", describeMissingScheme(deps.schemeTried ?? []));
+    }
+    // Captured after the check so the closures below carry the narrowing (a mutable property does
+    // not stay narrowed across one).
+    const scheme = deps.scheme;
+    const { delivery, note } = await resolveDelivery(requestedTarget, device, bundleId, deps);
+    // Rejected before minting, so a call that cannot possibly deliver does not strand a pending
+    // session behind it.
+    if (delivery?.target === "ios-device" && !delivery.bundleId) {
+        throw new McpBuiltinToolError("invalid_request", MISSING_BUNDLE_ID_MESSAGE);
+    }
+    if (delivery?.bundleId !== undefined && !isValidBundleId(delivery.bundleId)) {
+        throw new McpBuiltinToolError("invalid_request", invalidBundleIdMessage(delivery.bundleId));
+    }
+    // A link's advertised address is fixed at mint time: `127.0.0.1` only when it is being handed to
+    // something that reaches this machine over loopback (an emulator or simulator — not a physical
+    // iPhone, which needs the LAN address). That is why delivery is decided first, and why the QR
+    // fallback below has to mint a *fresh* link rather than reuse a loopback one no phone could reach.
+    const mint = (deliverLocally) => {
+        return deps.call(RPC_METHODS.linkCreate, {
+            ttlSeconds,
+            addressOverride: deliverLocally ? OPEN_TARGET_ADDRESS_OVERRIDE : undefined,
+        });
+    };
+    const asQrResult = (result, qrNote) => {
+        const deepLink = composeDeepLink(scheme, result);
+        return {
+            sessionId: result.sessionId,
+            deepLink,
+            expiresAt: result.expiresAt,
+            ...(qrNote === undefined ? {} : { note: qrNote }),
+            qr: renderQrToTerminal(deepLink),
+            instructions: QR_INSTRUCTIONS,
+        };
+    };
+    if (!delivery) {
+        return asQrResult(await mint(false), note);
+    }
+    const result = await mint(usesLoopbackAddress(delivery.target));
+    // Same guard as `link.ts`: `detectAdvertisedAddress` falls back to `127.0.0.1` when it finds no
+    // routable interface, and such a link points a physical phone at itself. Delivering it would
+    // leave `appduct_wait_for_session` blocking for its whole timeout with nothing to explain why.
+    if (delivery.target === "ios-device" && isLoopbackAddress(result.endpoint.address)) {
+        throw new McpBuiltinToolError("invalid_request", loopbackAddressMessage(result.endpoint.address));
+    }
+    const deepLink = composeDeepLink(scheme, result);
+    try {
+        await deliverToOpenTarget({
+            target: delivery.target,
+            device: delivery.device,
+            bundleId: delivery.bundleId,
+            relaunch,
+            deepLink,
+            wssPort: result.endpoint.port,
+            exec: deps.exec,
+            env: deps.env,
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "Failed to deliver the deep link.";
+        // An explicitly named target that cannot be reached is the caller's problem to see: falling
+        // back would quietly ignore what they asked for.
+        if (!delivery.autoDetected) {
+            throw new McpBuiltinToolError("tool_execution_error", detail);
+        }
+        // An auto-detected one is not. Nobody asked for this device — a simulator that happens to be
+        // booted without the app installed, say — so a failure to reach it must not turn a call that
+        // would previously have returned a usable QR into a hard error. The loopback link just minted
+        // is abandoned (it expires on its own TTL) and a fresh, correctly-addressed one takes its
+        // place.
+        return asQrResult(await mint(false), `Auto-detected ${delivery.target} target ${delivery.label}, but delivering the link to it ` +
+            `failed: ${detail}. Falling back to a QR code — pass an explicit "target" (and "device") ` +
+            "if a different device is the right one.");
+    }
+    return {
+        sessionId: result.sessionId,
+        deepLink,
+        expiresAt: result.expiresAt,
+        delivered: true,
+        target: delivery.target,
+        ...(delivery.device === undefined ? {} : { device: delivery.device }),
+        ...(delivery.autoDetected
+            ? {
+                autoDetected: true,
+                note: `No "target" was given; delivered to the only device found: ${delivery.label}.`,
+            }
+            : {}),
+    };
+};
+/** Socket-level failures that mean the daemon went away mid-wait. `isDaemonUnreachableError`
+ * covers the "never got there" cases (`ENOENT`/`ECONNREFUSED`) and a timed-out request; these are
+ * the "was there, then wasn't" ones, which surface raw from a call that was already in flight. */
+const CONNECTION_LOST_CODES = new Set(["ECONNRESET", "EPIPE"]);
+/** Appends the underlying cause, so an operator reading CI output still gets the syscall detail
+ * even though the sentence in front of it is what the agent acts on. */
+const describeCause = (error) => {
+    return error instanceof Error && error.message.length > 0 ? ` (${error.message})` : "";
+};
+const daemonClosedMessage = (sessionId) => `The connection to the Appduct daemon closed while waiting for session "${sessionId}".`;
+const daemonUnreachableMessage = (sessionId, error) => `The Appduct daemon is unreachable, so session "${sessionId}" cannot be waited on${describeCause(error)}.`;
+const isConnectionLost = (error) => {
+    if (isDaemonUnreachableError(error)) {
+        return true;
+    }
+    const code = error?.code;
+    return typeof code === "string" && CONNECTION_LOST_CODES.has(code);
+};
+export const handleWaitForSessionTool = async (rawArgs, deps) => {
+    const args = asRecord(rawArgs);
+    if (typeof args.sessionId !== "string" || args.sessionId.length === 0) {
+        throw new McpBuiltinToolError("invalid_request", '"sessionId" must be a non-empty string.');
+    }
+    const sessionId = args.sessionId;
+    const timeoutMs = asOptionalPositiveNumber(args.timeoutMs, "timeoutMs") ?? DEFAULT_WAIT_TIMEOUT_MS;
+    let stream;
+    try {
+        stream = await openDaemonStream({ stateDir: deps.stateDir, spawn: deps.spawn });
+    }
+    catch (error) {
+        // The daemon can be on its way out at the exact moment this tool opens its stream, in which
+        // case `connect` fails with ECONNRESET — not the ENOENT/ECONNREFUSED that would mean "not
+        // running" and trigger an auto-spawn. That is the same situation as losing it mid-wait, and
+        // has to read the same way rather than as a bare syscall error against a socket path.
+        if (isConnectionLost(error)) {
+            throw new McpBuiltinToolError("tool_execution_error", daemonUnreachableMessage(sessionId, error));
+        }
+        throw error;
+    }
+    try {
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (fn) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                unsubscribeNotification();
+                unsubscribeClose();
+                fn();
+            };
+            const timer = setTimeout(() => {
+                settle(() => reject(new McpBuiltinToolError("tool_timeout", `Timed out after ${timeoutMs}ms waiting for session "${sessionId}" to be claimed.`)));
+            }, timeoutMs);
+            const connectionLost = () => new McpBuiltinToolError("tool_execution_error", daemonClosedMessage(sessionId));
+            // A daemon that goes away mid-wait must not read as "still waiting" for the rest of the
+            // timeout — the caller has to know the connection is gone, not sit in silence.
+            const unsubscribeClose = stream.onClose(() => {
+                settle(() => reject(connectionLost()));
+            });
+            // Registered *before* `events.subscribe` is sent (not after awaiting it) — a
+            // `session_claimed` notification that arrives in the same TCP chunk as the subscribe
+            // response is dispatched synchronously within that chunk's processing, before an `await`
+            // continuation would get a chance to run; registering first means it is always in place in
+            // time to see it. Same reasoning as `client/bootstrap.ts`.
+            const unsubscribeNotification = stream.onNotification((payload) => {
+                const event = payload;
+                if (event.kind === "session_claimed" && event.sessionId === sessionId) {
+                    settle(() => resolve({ sessionId, claimed: true, alias: event.alias ?? "" }));
+                }
+            });
+            stream
+                .call(RPC_METHODS.eventsSubscribe, { sessionSelector: sessionId, kinds: ["session_claimed"] })
+                .then(async () => {
+                if (settled) {
+                    return;
+                }
+                // Catch-up, once the subscription is definitely in place: the session may have been
+                // claimed before this tool ran at all (an agent polling, or a long gap after
+                // appduct_connect), or in the round trip the subscribe itself took. Either way the
+                // event is already in the past and no amount of waiting will replay it.
+                const existing = await stream.call(RPC_METHODS.sessionsDescribe, {
+                    selector: sessionId,
+                });
+                settle(() => resolve({ sessionId, claimed: true, alias: existing.alias }));
+            })
+                .catch((error) => {
+                // `unknown_session` from the catch-up is the expected "not claimed yet" answer — keep
+                // waiting for the live event. Anything else is a real failure.
+                if (error instanceof DaemonRpcError && error.data?.type === "unknown_session") {
+                    return;
+                }
+                // A daemon dying mid-wait races two routes to get here: `onClose` above, or whichever
+                // call was in flight rejecting with a raw socket error. Same condition, so report it the
+                // same way — which route wins is a platform detail (Linux tends to reset where macOS
+                // closes), and nobody should have to read `connect ECONNRESET <socket path>` to find out
+                // the daemon stopped.
+                settle(() => reject(isConnectionLost(error) ? connectionLost() : error));
+            });
+        });
+    }
+    finally {
+        stream.close();
+    }
+};

package/dist/mcp/daemon-tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { type NamespacedTool } from "./tool-namespace.js";
+/** A method call against the daemon RPC — satisfied by both `callDaemon` (bound to a method+params)
+ * and `DaemonStream.call` from `rpc/client.ts`. */
+export type DaemonCall = <TResult>(method: string, params?: unknown) => Promise<TResult>;
+export declare const fetchEffectiveTools: (call: DaemonCall) => Promise<NamespacedTool[]>;
+//# sourceMappingURL=daemon-tools.d.ts.map

package/dist/mcp/daemon-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-tools.d.ts","sourceRoot":"","sources":["../../src/mcp/daemon-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEhF;mDACmD;AACnD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEzF,eAAO,MAAM,mBAAmB,GAAU,MAAM,UAAU,KAAG,OAAO,CAAC,cAAc,EAAE,CAuBpF,CAAC"}