appduct 0.9.0

package/dist/output.js

@@ -0,0 +1,342 @@
+import pc from "picocolors";
+import { formatAgentWebSocketUrl } from "@appduct/shared";
+import { renderQrToTerminal } from "./qr-terminal.js";
+const indentJson = (value) => {
+    return JSON.stringify(value, null, 2);
+};
+const renderMetaLines = (meta) => {
+    if (!meta) {
+        return [];
+    }
+    return [
+        "Meta",
+        `  Command: ${meta.command}`,
+        `  Timestamp: ${meta.timestamp}`,
+        ...(typeof meta.duration_ms === "number" ? [`  Duration: ${meta.duration_ms} ms`] : []),
+    ];
+};
+const formatScalar = (value) => {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (value === null || value === undefined) {
+        return "null";
+    }
+    return indentJson(value);
+};
+const renderFields = (title, fields) => {
+    const visibleFields = fields.filter(([, value]) => value !== undefined);
+    if (visibleFields.length === 0) {
+        return [];
+    }
+    const width = Math.max(...visibleFields.map(([label]) => label.length));
+    return [
+        title,
+        ...visibleFields.map(([label, value]) => `  ${label.padEnd(width)}  ${formatScalar(value)}`),
+    ];
+};
+/** Humanizes an elapsed duration for `ls`'s "age" column: seconds/minutes/hours/days, coarsest unit
+ * that keeps at least one digit of precision. */
+const formatAge = (fromIso, toIso) => {
+    const elapsedMs = Math.max(0, new Date(toIso).getTime() - new Date(fromIso).getTime());
+    const elapsedSeconds = Math.floor(elapsedMs / 1000);
+    if (elapsedSeconds < 60) {
+        return `${elapsedSeconds}s`;
+    }
+    const elapsedMinutes = Math.floor(elapsedSeconds / 60);
+    if (elapsedMinutes < 60) {
+        return `${elapsedMinutes}m`;
+    }
+    const elapsedHours = Math.floor(elapsedMinutes / 60);
+    if (elapsedHours < 24) {
+        return `${elapsedHours}h`;
+    }
+    return `${Math.floor(elapsedHours / 24)}d`;
+};
+const formatDevice = (device) => {
+    const parts = [device.manufacturer, device.model].filter((part) => Boolean(part));
+    const label = parts.length > 0 ? parts.join(" ") : "unknown device";
+    return device.os ? `${label} (${device.os})` : label;
+};
+const renderLsData = (colors, data, meta) => {
+    if (data.length === 0) {
+        return [colors.dim("Sessions"), "  No Appduct sessions are registered."];
+    }
+    const now = meta?.timestamp ?? new Date().toISOString();
+    const headers = ["Alias", "State", "Device", "Tools", "Age"];
+    const rows = data.map((session) => [
+        session.alias,
+        session.state,
+        formatDevice(session.device),
+        String(session.toolCount),
+        formatAge(session.claimedAt ?? session.createdAt, now),
+    ]);
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index].length)));
+    return [
+        colors.green("Sessions"),
+        `  ${headers.map((header, index) => header.padEnd(widths[index])).join("  ")}`,
+        ...rows.map((row) => `  ${row.map((cell, index) => cell.padEnd(widths[index])).join("  ")}`),
+    ];
+};
+const renderToolSummaryTable = (tools) => {
+    if (tools.length === 0) {
+        return ["Tools", "  No tools registered."];
+    }
+    const nameWidth = Math.max(...tools.map((tool) => tool.name.length), "Name".length);
+    return [
+        "Tools",
+        `  ${"Name".padEnd(nameWidth)}  Description`,
+        ...tools.map((tool) => `  ${tool.name.padEnd(nameWidth)}  ${tool.description}`),
+    ];
+};
+const renderToolDetail = (colors, tool) => {
+    return renderFields(colors.green(`Tool: ${tool.name}`), [
+        ["Description", tool.description],
+        ["Input schema", tool.input_schema],
+        ["Output schema", tool.output_schema],
+        ["Annotations", tool.annotations],
+        // Only rendered for a tool that declares one; `renderFields` drops undefined rows, so a tool
+        // on the daemon's default deadline shows no line at all rather than a misleading "10000".
+        ["Timeout (ms)", tool.timeout_ms],
+    ]);
+};
+const renderToolsData = (colors, data, full) => {
+    if (!Array.isArray(data)) {
+        return renderToolDetail(colors, data);
+    }
+    if (full) {
+        return data.length === 0
+            ? ["Tools", "  No tools registered."]
+            : data.flatMap((tool, index) => [...(index > 0 ? [""] : []), ...renderToolDetail(colors, tool)]);
+    }
+    return [colors.green("Tools"), ...renderToolSummaryTable(data).slice(1)];
+};
+const renderInvokeData = (colors, data) => {
+    return [colors.green("Result"), formatScalar(data)];
+};
+const renderLinkData = (colors, data, qr) => {
+    const lines = [
+        colors.green("Link Created"),
+        ...renderFields("Link", [
+            ["Session", data.sessionId],
+            ["Deep link", data.deepLink],
+            ["Endpoint", formatAgentWebSocketUrl(data.endpoint)],
+            ["Pin", data.pin],
+            ["Expires", new Date(data.expiresAt * 1000).toISOString()],
+            ["Delivered", data.delivered ? `yes (${data.target})` : undefined],
+        ]),
+    ];
+    if (qr) {
+        lines.push("", "QR", renderQrToTerminal(data.deepLink));
+    }
+    return lines;
+};
+const renderRevokeData = (colors, _data) => {
+    return [colors.green("Session Revoked")];
+};
+const renderKeygenData = (colors, data) => {
+    return [
+        colors.green("Key Ready"),
+        ...renderFields("Key", [
+            ["Path", data.path],
+            ["Fingerprint", data.pin],
+        ]),
+    ];
+};
+const renderInitData = (colors, data) => {
+    const snippet = JSON.stringify({ mcpServers: { appduct: data.mcpServerEntry } }, null, 2);
+    return [
+        colors.green(data.changed ? "Project Initialized" : "Project Already Initialized"),
+        ...renderFields("Config", [
+            ["Path", data.path],
+            ["Scheme", data.scheme],
+            ["Source", data.source],
+            // Only present for a scheme discovery read off a static project file (app.json, or one of
+            // the native Android/iOS probes) — names the exact file/key, not just which platform.
+            ["Read from", data.origin],
+            ["Written", data.changed ? (data.created ? "created" : "updated") : "unchanged"],
+        ]),
+        ...(data.note === undefined ? [] : ["", colors.yellow(`Note: ${data.note}`)]),
+        "",
+        "MCP server entry",
+        ...snippet.split("\n").map((line) => `  ${line}`),
+        "",
+        "Next",
+        ...data.nextSteps.map((step, index) => `  ${index + 1}. ${step}`),
+    ];
+};
+const renderDaemonRunData = (colors, data) => {
+    return [
+        colors.green("Daemon Running"),
+        ...renderFields("Daemon", [
+            ["PID", data.daemon.pid],
+            ["State dir", data.daemon.state_dir],
+            ["Socket", data.daemon.socket_path],
+        ]),
+    ];
+};
+const renderDaemonStartData = (colors, data) => {
+    return [
+        colors.green("Daemon Started"),
+        ...renderFields("Daemon", [
+            ["PID", data.daemon.pid],
+            ["WSS port", data.daemon.wss_port],
+            ["Started at", data.daemon.started_at],
+        ]),
+    ];
+};
+const renderDaemonStopData = (colors, data) => {
+    return [
+        colors.green("Daemon Stopped"),
+        ...renderFields("Daemon", [["Method", data.daemon.method]]),
+    ];
+};
+/** Human column for a byte count (the machine-readable `bytes` stays exact in `--json`). Binary
+ * units, one decimal above KiB, so a growing `audit/` reads at a glance. */
+const formatByteSize = (bytes) => {
+    const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${unit === 0 ? value : value.toFixed(1)} ${units[unit]}`;
+};
+const renderDaemonStatusData = (colors, data) => {
+    return [
+        colors.green("Daemon Status"),
+        ...renderFields("Daemon", [
+            ["Version", data.daemon.version],
+            ["PID", data.daemon.pid],
+            ["Started at", data.daemon.started_at],
+            ["WSS port", data.daemon.wss_port],
+            ["Pinned keys", data.daemon.pinned_keys.length],
+            ["Sessions", data.daemon.session_count],
+        ]),
+        "",
+        ...renderFields("Policy", [
+            ["Default", data.policy.default],
+            ["Destructive", data.policy.destructive],
+            ["Overrides", data.policy.tools ? Object.keys(data.policy.tools).length : 0],
+        ]),
+        "",
+        // The retention rows drop out entirely against a daemon that predates them (`renderFields`
+        // skips `undefined`), rather than printing "undefined" or an invented zero.
+        ...renderFields("Audit", [
+            ["Path", data.audit.path],
+            ["Retention", data.audit.retention_days === undefined ? undefined : `${data.audit.retention_days} days`],
+            ["Files", data.audit.files],
+            ["Size", data.audit.bytes === undefined ? undefined : formatByteSize(data.audit.bytes)],
+            ["Failed writes", data.audit.failed_writes],
+            ["Failed prunes", data.audit.failed_prunes],
+        ]),
+        // Version drift (issue #30) is the one thing here an operator has to act on, so it goes last
+        // — the line still on screen after the block scrolls — and in yellow, not a quiet field row.
+        ...(data.warning ? ["", colors.yellow(`Warning: ${data.warning}`)] : []),
+    ];
+};
+const renderDoctorData = (colors, data) => {
+    return [
+        data.present ? colors.green("Appduct Present") : colors.yellow("Appduct Absent"),
+        ...renderFields("Artifact", [
+            ["Path", data.artifact],
+            ["Platform", data.platform],
+            ["Format", data.format],
+            ["Present", data.present],
+            ["Signals", data.signals.length > 0 ? data.signals.join(", ") : "none"],
+            ["Assertion", data.assertion ? `${data.assertion.expected} (holds)` : undefined],
+        ]),
+    ];
+};
+const renderSuccessData = (colors, command, data, options, meta) => {
+    switch (command) {
+        case "init":
+            return renderInitData(colors, data);
+        case "keygen":
+            return renderKeygenData(colors, data);
+        case "link":
+            return renderLinkData(colors, data, options.qr);
+        case "ls":
+            return renderLsData(colors, data, meta);
+        case "tools":
+            return renderToolsData(colors, data, options.full);
+        case "invoke":
+            return renderInvokeData(colors, data);
+        case "revoke":
+            return renderRevokeData(colors, data);
+        case "daemon run":
+            return renderDaemonRunData(colors, data);
+        case "daemon start":
+            return renderDaemonStartData(colors, data);
+        case "daemon stop":
+            return renderDaemonStopData(colors, data);
+        case "daemon status":
+            return renderDaemonStatusData(colors, data);
+        case "doctor":
+            return renderDoctorData(colors, data);
+        default:
+            return [colors.green("Command Complete"), indentJson(data)];
+    }
+};
+const renderHumanError = (colors, error, meta) => {
+    return [
+        colors.red("Command Failed"),
+        ...renderFields("Error", [
+            ["Type", error.type],
+            ["Message", error.message],
+            ["Details", error.details],
+        ]),
+        ...(meta ? ["", ...renderMetaLines(meta)] : []),
+    ].join("\n");
+};
+export const renderResult = (result, options) => {
+    if (options.json) {
+        return {
+            stdout: `${indentJson(result)}\n`,
+        };
+    }
+    const colors = pc.createColors(options.color);
+    if (!result.ok) {
+        return {
+            stderr: `${renderHumanError(colors, result.error, result.meta)}\n`,
+        };
+    }
+    const lines = [
+        ...renderSuccessData(colors, options.command, result.data, options, result.meta),
+        "",
+        ...renderMetaLines(result.meta),
+    ].filter((line, index, collection) => {
+        if (line !== "") {
+            return true;
+        }
+        return index > 0 && collection[index - 1] !== "" && index < collection.length - 1;
+    });
+    return {
+        stdout: `${lines.join("\n")}\n`,
+    };
+};
+/** Renders one `appduct events` line: NDJSON under `--json`, a compact human line otherwise. */
+export const renderEventLine = (event, options) => {
+    if (options.json) {
+        return JSON.stringify(event);
+    }
+    const colors = pc.createColors(options.color);
+    const timestamp = new Date(event.ts).toISOString();
+    const target = event.alias ?? event.sessionId;
+    const dataSuffix = event.data === undefined ? "" : ` ${indentJson(event.data)}`;
+    return `${colors.dim(timestamp)} ${colors.green(event.kind)}${target ? ` ${target}` : ""}${dataSuffix}`;
+};
+/** Renders the trailing cursor line for `appduct events --since` (issue #6): NDJSON under
+ * `--json` so a scripted caller can parse the resume point without maxing `seq` over the printed
+ * events (impossible when the response is empty), a human note otherwise. */
+export const renderEventsCursorLine = (cursor, options) => {
+    if (options.json) {
+        return JSON.stringify({ cursor });
+    }
+    const colors = pc.createColors(options.color);
+    return colors.dim(`cursor: ${cursor} (pass --since ${cursor} to resume from here)`);
+};

package/dist/package-version.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The single source of truth for "what version of Appduct is this process running".
+ *
+ * The daemon (`daemon/daemon.ts`), the MCP server (`mcp/server.ts`), the CLI's `--version`
+ * (`cli/create-cli.ts`) and the CLI's daemon version check (`cli/dispatch.ts`) all need the
+ * published package version, and every one of them used to re-read `package.json` itself. They
+ * read it through this module instead so a single mismatch in the relative path can't make one of
+ * them report a different version than the others (issue #30).
+ */
+/**
+ * Test seam (issue #30): when set, the daemon reports this instead of the real package version in
+ * `daemon.status` and the `daemon_started` event, so an integration test can produce a genuine
+ * client/daemon version mismatch without installing two builds. Read only by the daemon — a
+ * *client* must always report the version it truly is, or the check would compare a lie to a lie.
+ *
+ * Honored **only under a test runner** (see {@link isTestRuntime}). A daemon that lied about its
+ * version in production would make every command restart it, forever: the value is inherited by
+ * whatever the shell exported, and the replacement daemon would report the same lie. The RPC
+ * client additionally strips this key from the environment of any daemon it spawns.
+ */
+export declare const DAEMON_VERSION_OVERRIDE_ENV = "APPDUCT_DAEMON_VERSION_OVERRIDE";
+/** The `version` field of this package's `package.json`, read once per process. */
+export declare const getPackageVersion: () => string;
+/**
+ * The version the *daemon* reports over RPC: {@link getPackageVersion}, unless
+ * {@link DAEMON_VERSION_OVERRIDE_ENV} overrides it. Evaluated per call (not cached) so a daemon
+ * started in-process by a test picks up the environment that test set.
+ */
+export declare const getDaemonReportedVersion: (env?: NodeJS.ProcessEnv) => string;
+//# sourceMappingURL=package-version.d.ts.map

package/dist/package-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../src/package-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,oCAAoC,CAAC;AAW7E,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,QAAO,MAGpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,MAO/E,CAAC"}

package/dist/package-version.js

@@ -0,0 +1,47 @@
+/**
+ * The single source of truth for "what version of Appduct is this process running".
+ *
+ * The daemon (`daemon/daemon.ts`), the MCP server (`mcp/server.ts`), the CLI's `--version`
+ * (`cli/create-cli.ts`) and the CLI's daemon version check (`cli/dispatch.ts`) all need the
+ * published package version, and every one of them used to re-read `package.json` itself. They
+ * read it through this module instead so a single mismatch in the relative path can't make one of
+ * them report a different version than the others (issue #30).
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Test seam (issue #30): when set, the daemon reports this instead of the real package version in
+ * `daemon.status` and the `daemon_started` event, so an integration test can produce a genuine
+ * client/daemon version mismatch without installing two builds. Read only by the daemon — a
+ * *client* must always report the version it truly is, or the check would compare a lie to a lie.
+ *
+ * Honored **only under a test runner** (see {@link isTestRuntime}). A daemon that lied about its
+ * version in production would make every command restart it, forever: the value is inherited by
+ * whatever the shell exported, and the replacement daemon would report the same lie. The RPC
+ * client additionally strips this key from the environment of any daemon it spawns.
+ */
+export const DAEMON_VERSION_OVERRIDE_ENV = "APPDUCT_DAEMON_VERSION_OVERRIDE";
+/** True under Vitest, or with an explicit `NODE_ENV=test`. */
+const isTestRuntime = (env) => {
+    return Boolean(env.VITEST) || env.NODE_ENV === "test";
+};
+const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+let cached;
+/** The `version` field of this package's `package.json`, read once per process. */
+export const getPackageVersion = () => {
+    cached ??= JSON.parse(readFileSync(packageJsonPath, "utf8")).version;
+    return cached;
+};
+/**
+ * The version the *daemon* reports over RPC: {@link getPackageVersion}, unless
+ * {@link DAEMON_VERSION_OVERRIDE_ENV} overrides it. Evaluated per call (not cached) so a daemon
+ * started in-process by a test picks up the environment that test set.
+ */
+export const getDaemonReportedVersion = (env = process.env) => {
+    if (!isTestRuntime(env)) {
+        return getPackageVersion();
+    }
+    const override = env[DAEMON_VERSION_OVERRIDE_ENV];
+    return override !== undefined && override.length > 0 ? override : getPackageVersion();
+};

package/dist/qr-terminal.d.ts

@@ -0,0 +1,13 @@
+export type QrTerminalRenderOptions = {
+    /** Quiet zone in modules (default 0). */
+    margin?: number;
+    /**
+     * `toqr` error-correction index: M=0, L=1, H=2, Q=3 (default 1 = L).
+     */
+    ecLevel?: number;
+};
+/**
+ * Renders a QR payload as compact half-block terminal art (two modules per character row).
+ */
+export declare const renderQrToTerminal: (content: string, options?: QrTerminalRenderOptions) => string;
+//# sourceMappingURL=qr-terminal.d.ts.map

package/dist/qr-terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr-terminal.d.ts","sourceRoot":"","sources":["../src/qr-terminal.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,uBAAuB,GAAG;IACpC,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,EACf,UAAU,uBAAuB,KAChC,MAyCF,CAAC"}

package/dist/qr-terminal.js

@@ -0,0 +1,45 @@
+import { toQR } from "toqr";
+const HALF_UPPER = "\u2580"; // ▀
+const HALF_LOWER = "\u2584"; // ▄
+const FULL = "\u2588"; // █
+/**
+ * Renders a QR payload as compact half-block terminal art (two modules per character row).
+ */
+export const renderQrToTerminal = (content, options) => {
+    const margin = options?.margin ?? 0;
+    const ecLevel = options?.ecLevel ?? 1;
+    const modules = toQR(content, ecLevel);
+    const side = Math.sqrt(modules.length);
+    if (!Number.isInteger(side)) {
+        throw new Error("Invalid QR matrix size");
+    }
+    const dim = side + 2 * margin;
+    const isDark = (row, col) => {
+        if (row < margin ||
+            col < margin ||
+            row >= margin + side ||
+            col >= margin + side) {
+            return false;
+        }
+        const mr = row - margin;
+        const mc = col - margin;
+        return modules[mr * side + mc] === 1;
+    };
+    const lines = [];
+    for (let row = 0; row < dim; row += 2) {
+        let line = "";
+        for (let col = 0; col < dim; col++) {
+            const top = isDark(row, col);
+            const bottom = row + 1 < dim ? isDark(row + 1, col) : false;
+            line += top
+                ? bottom
+                    ? FULL
+                    : HALF_UPPER
+                : bottom
+                    ? HALF_LOWER
+                    : " ";
+        }
+        lines.push(line);
+    }
+    return lines.join("\n");
+};

package/dist/rpc/client.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The auto-spawning RPC client library (ARCHITECTURE.md §4, §5) used by the CLI, MCP server, and
+ * tests to talk to `daemon.sock`. On `ENOENT`/`ECONNREFUSED` it takes an exclusive spawn-lock,
+ * spawns `daemon run` detached, polls the socket until ready, then retries the request once.
+ */
+import { type RpcErrorData } from "@appduct/shared";
+export type SpawnContext = {
+    stateDir: string;
+    logFilePath: string;
+};
+/** Spawns `daemon run` detached with stdio redirected to `daemon.log`. Injectable for tests. */
+export type SpawnFn = (args: string[], context: SpawnContext) => void | Promise<void>;
+export declare class DaemonRpcError extends Error {
+    readonly code: number;
+    readonly data?: RpcErrorData | undefined;
+    constructor(code: number, message: string, data?: RpcErrorData | undefined);
+}
+/**
+ * `reason` distinguishes outcomes that look identical to a caller but mean opposite things to the
+ * version-drift restart (issue #30): `"closed"` is the daemon dropping the connection — expected
+ * while it tears itself down — whereas `"timeout"` is a daemon that is very much alive and simply
+ * not answering, which must never be mistaken for "it is gone, spawn another one".
+ */
+export declare class DaemonUnavailableError extends Error {
+    readonly reason: "timeout" | "closed" | "unreachable";
+    constructor(message: string, reason?: "timeout" | "closed" | "unreachable");
+}
+/** What a restart would destroy, as read from one `daemon.status` reply. */
+export type DaemonLiveState = {
+    sessions: number;
+    pendingLinks: number;
+};
+/**
+ * Raised when the daemon this client reached is running a different Appduct version and could
+ * not be replaced (issue #30). The common case is live state a restart would destroy: sessions
+ * (resume tokens are in-daemon memory, so a restart makes the app's resume fail closed with 1008)
+ * or pending links (a deep link or QR code someone is about to scan). The caller is told rather
+ * than silently paying that cost.
+ */
+export declare class DaemonVersionMismatchError extends Error {
+    readonly daemonVersion: string;
+    readonly clientVersion: string;
+    readonly sessionCount: number;
+    readonly pendingLinkCount: number;
+    constructor(daemonVersion: string, clientVersion: string, live: DaemonLiveState, message?: string);
+}
+/**
+ * Raised when the daemon *was* restarted and the daemon now answering still reports a different
+ * version. Retrying would just kill daemon after daemon, so the check stops after one restart and
+ * reports what it actually observed rather than guessing at a cause.
+ */
+export declare class DaemonVersionRestartIneffectiveError extends DaemonVersionMismatchError {
+    constructor(daemonVersion: string, clientVersion: string, live: DaemonLiveState);
+}
+/**
+ * Opt-in daemon/client version check (issue #30). Passed by the CLI dispatcher and the MCP
+ * server's startup stream; deliberately *not* passed by `appduct/client`, whose callers are
+ * test processes that must never have a daemon restarted out from under a live app session.
+ */
+export type VersionCheckOptions = {
+    /** The version this client actually is — always the real package version, never an override. */
+    clientVersion: string;
+    /** Restart even when the daemon has live sessions or pending links (`--daemon-restart`, the
+     * `APPDUCT_DAEMON_RESTART` env var, or `config.json`'s `restartDaemonOnVersionMismatch`). */
+    forceRestart?: boolean;
+    /** Where the "the daemon is newer than this client" notice goes. Defaults to `process.stderr` —
+     * never stdout, which belongs to `--json` output and to the MCP transport's frames. */
+    onWarning?: (message: string) => void;
+};
+/**
+ * True when two version strings name the same version even though the strings differ — `1.2` and
+ * `1.2.0`, or two builds differing only in `+metadata`. Comparing the raw strings would report
+ * drift that does not exist and, worse, print a "the daemon is newer" notice about a daemon that
+ * is exactly this version.
+ */
+export declare const isSameVersion: (a: string, b: string) => boolean;
+export type CallDaemonOptions = {
+    stateDir: string;
+    /** Auto-spawn a daemon on `ENOENT`/`ECONNREFUSED`. Defaults to `true`. */
+    autoSpawn?: boolean;
+    spawn?: SpawnFn;
+    /** Per-request timeout waiting for a response line. Defaults to 10s. */
+    requestTimeoutMs?: number;
+    /** How long to poll the socket for readiness after spawning. Defaults to 5000ms. */
+    spawnWaitTimeoutMs?: number;
+    /** Poll interval while waiting for the socket to become ready. Defaults to 100ms. */
+    spawnPollIntervalMs?: number;
+    /**
+     * When set, the first call from this process to a given daemon socket compares the daemon's
+     * version with {@link VersionCheckOptions.clientVersion} and restarts the daemon when they
+     * differ and doing so is safe. The result is cached per socket path, so this costs one extra
+     * `daemon.status` round-trip per process — not per request.
+     */
+    checkVersion?: VersionCheckOptions;
+};
+/**
+ * True when `error` indicates the daemon is not reachable at all — no listener at the socket
+ * path (`ENOENT`/`ECONNREFUSED`), or a `DaemonUnavailableError` from a request that timed out or
+ * had its connection drop mid-flight. Callers use this to decide whether a fallback (e.g. `daemon
+ * stop`'s SIGTERM-via-pidfile path) applies, as opposed to a `DaemonRpcError` from a daemon that
+ * is very much running but rejected the request.
+ */
+export declare const isDaemonUnreachableError: (error: unknown) => boolean;
+/** Test seam: drops the per-process check cache so each test case starts from a clean slate. */
+export declare const resetDaemonVersionChecks: () => void;
+/**
+ * Runs the version check on its own, without issuing a command RPC — the CLI dispatcher's seam
+ * (issue #30). Pass `autoSpawn: false` (the default here) when the caller does not want a daemon
+ * started just to be checked: nothing listening means nothing to drift from.
+ */
+export declare const ensureDaemonVersionMatches: (options: Omit<CallDaemonOptions, "checkVersion"> & {
+    checkVersion: VersionCheckOptions;
+}) => Promise<void>;
+/** Calls a daemon RPC method, auto-spawning the daemon on a missing/refused connection. */
+export declare const callDaemon: <TResult>(method: string, params: unknown, options: CallDaemonOptions) => Promise<TResult>;
+export type DaemonStream = {
+    /** Sends a request over the persistent connection and awaits its response. `timeoutMs`
+     * overrides this stream's default transport timeout for this call only — needed when a
+     * request's own server-side deadline (e.g. `tools.call`'s `timeoutMs` param) can exceed the
+     * stream's default, so the transport timeout never fires before the server-side one does. */
+    call: <TResult>(method: string, params?: unknown, timeoutMs?: number) => Promise<TResult>;
+    /** Subscribes to server→client `"event"` notifications; returns an unsubscribe function. */
+    onNotification: (callback: (payload: unknown) => void) => () => void;
+    /** Fires once when the underlying socket closes (daemon gone, stop(), etc.); returns an
+     * unsubscribe function. Lets long-lived stream consumers (e.g. `appduct events`) end
+     * gracefully instead of hanging once the connection is no longer usable. */
+    onClose: (callback: () => void) => () => void;
+    close: () => void;
+};
+/**
+ * Opens a persistent connection to the daemon (auto-spawning as needed) for use cases that need
+ * server→client notifications, e.g. `events.subscribe`.
+ */
+export declare const openDaemonStream: (options: Omit<CallDaemonOptions, "requestTimeoutMs"> & {
+    requestTimeoutMs?: number;
+}) => Promise<DaemonStream>;
+//# sourceMappingURL=client.d.ts.map

package/dist/rpc/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/rpc/client.ts"],"names":[],"mappings":"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"}