appduct 0.9.0

package/dist/cli/runner.d.ts

@@ -0,0 +1,35 @@
+import type { CliResult } from "./result-types.js";
+import { type RenderOptions } from "../output.js";
+import { type Clock, type CliIoWriters } from "./types.js";
+/**
+ * Long-lived command result shape shared by any CLI command that keeps a process alive
+ * until completion/cancellation (e.g. a foreground daemon run). Not tied to any specific
+ * command's data type.
+ */
+type HostedCommandResult = {
+    result: CliResult<unknown>;
+    completion: Promise<void>;
+    stop: () => void;
+};
+/**
+ * Minimal reporter contract for {@link executeHostedCommand}: an optional live-rendering
+ * reporter that receives lifecycle events and must be disposed once the hosted command
+ * completes. `kind: "plain"` reporters render their own bootstrap output instead of the
+ * default `renderResult` output.
+ */
+export type HostedCommandReporter = {
+    kind: "interactive" | "plain";
+    onEvent: (event: unknown) => void | Promise<void>;
+    dispose: () => void;
+};
+export declare const executeCommand: (command: string, handler: () => CliResult<unknown> | Promise<CliResult<unknown>>, options: CliIoWriters & Pick<RenderOptions, "json" | "color"> & Partial<Pick<RenderOptions, "qr" | "full">> & {
+    clock: Clock;
+}) => Promise<number>;
+export declare const executeHostedCommand: (command: string, handler: () => Promise<HostedCommandResult>, options: CliIoWriters & {
+    json: boolean;
+    color: boolean;
+    clock: Clock;
+    reporter?: HostedCommandReporter;
+}) => Promise<number>;
+export {};
+//# sourceMappingURL=runner.d.ts.map

package/dist/cli/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/cli/runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGnD,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAqB,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;GAIG;AACH,KAAK,mBAAmB,GAAG;IACzB,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;IAC9B,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAeF,eAAO,MAAM,cAAc,GACzB,SAAS,MAAM,EACf,SAAS,MAAM,SAAS,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EAC/D,SAAS,YAAY,GACnB,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,GACrC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,MAAM,CAAC,CAAC,GAAG;IAC5C,KAAK,EAAE,KAAK,CAAC;CACd,KACF,OAAO,CAAC,MAAM,CAkChB,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,MAAM,EACf,SAAS,MAAM,OAAO,CAAC,mBAAmB,CAAC,EAC3C,SAAS,YAAY,GAAG;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC,KACA,OAAO,CAAC,MAAM,CAoFhB,CAAC"}

package/dist/cli/runner.js

@@ -0,0 +1,111 @@
+import { getExitCodeForError, toCliError } from "../errors.js";
+import { renderResult } from "../output.js";
+import { createCommandMeta } from "./types.js";
+const writeRenderedOutput = (rendered, writers) => {
+    if (rendered.stdout) {
+        writers.stdout.write(rendered.stdout);
+    }
+    if (rendered.stderr) {
+        writers.stderr.write(rendered.stderr);
+    }
+};
+export const executeCommand = async (command, handler, options) => {
+    const startedAt = options.clock.now();
+    const renderOptions = {
+        command,
+        json: options.json,
+        color: options.color,
+        qr: options.qr,
+        full: options.full,
+    };
+    try {
+        const result = await handler();
+        const finishedAt = options.clock.now();
+        const withMeta = {
+            ...result,
+            meta: createCommandMeta(command, startedAt, finishedAt),
+        };
+        writeRenderedOutput(renderResult(withMeta, renderOptions), options);
+        return 0;
+    }
+    catch (error) {
+        const finishedAt = options.clock.now();
+        const cliError = toCliError(error);
+        const result = {
+            ok: false,
+            error: cliError,
+            meta: createCommandMeta(command, startedAt, finishedAt),
+        };
+        writeRenderedOutput(renderResult(result, renderOptions), options);
+        return getExitCodeForError(error);
+    }
+};
+export const executeHostedCommand = async (command, handler, options) => {
+    const startedAt = options.clock.now();
+    let renderedSuccess = false;
+    try {
+        const hosted = await handler();
+        const finishedAt = options.clock.now();
+        const withMeta = {
+            ...hosted.result,
+            meta: createCommandMeta(command, startedAt, finishedAt),
+        };
+        // A live reporter (e.g. `events`'s streaming NDJSON/human lines) renders its own output as it
+        // goes; only the absence of a reporter (or an explicit "plain" one) falls back to the default
+        // one-shot `renderResult` bootstrap rendering.
+        const liveReporter = options.reporter;
+        const shouldRenderBootstrap = !liveReporter || liveReporter.kind === "plain";
+        if (shouldRenderBootstrap) {
+            writeRenderedOutput(renderResult(withMeta, {
+                command,
+                json: options.json,
+                color: options.color,
+            }), options);
+            renderedSuccess = true;
+        }
+        let resolved = false;
+        const stop = () => {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            hosted.stop();
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        try {
+            await hosted.completion;
+        }
+        finally {
+            resolved = true;
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+            options.reporter?.dispose();
+        }
+        return 0;
+    }
+    catch (error) {
+        options.reporter?.dispose();
+        const finishedAt = options.clock.now();
+        const cliError = toCliError(error);
+        const result = {
+            ok: false,
+            error: cliError,
+            meta: createCommandMeta(command, startedAt, finishedAt),
+        };
+        if (renderedSuccess && options.json) {
+            // The single-JSON-object-on-stdout contract was already fulfilled by the bootstrap render
+            // above; a failure that happens later (e.g. during a long-running `completion`) must still
+            // be a JSON object, just on stderr instead — bare text here was v1's defect (leaked
+            // unparseable output onto stderr in `--json` mode).
+            options.stderr.write(`${JSON.stringify(result)}\n`);
+            return getExitCodeForError(error);
+        }
+        writeRenderedOutput(renderResult(result, {
+            command,
+            json: options.json,
+            color: options.color,
+        }), options);
+        return getExitCodeForError(error);
+    }
+};

package/dist/cli/types.d.ts

@@ -0,0 +1,20 @@
+import type { CommandMeta } from "./result-types.js";
+export type Clock = {
+    now: () => Date;
+};
+export declare const systemClock: Clock;
+export declare const createCommandMeta: (command: string, startedAt: Date, finishedAt: Date) => CommandMeta;
+export type RunCliOptions = {
+    stdout?: Pick<typeof process.stdout, "write" | "isTTY">;
+    stderr?: Pick<typeof process.stderr, "write">;
+    clock?: Clock;
+};
+export type CliIoWriters = Required<Pick<RunCliOptions, "stdout" | "stderr">>;
+export type CliRenderContext = {
+    json: boolean;
+    color: boolean;
+    stdout: CliIoWriters["stdout"];
+    stderr: CliIoWriters["stderr"];
+    clock: Clock;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/cli/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cli/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,MAAM,KAAK,GAAG;IAClB,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,KAEzB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,SAAS,MAAM,EACf,WAAW,IAAI,EACf,YAAY,IAAI,KACf,WAMF,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC;AAE9E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/B,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/B,KAAK,EAAE,KAAK,CAAC;CACd,CAAC"}

package/dist/cli/types.js

@@ -0,0 +1,10 @@
+export const systemClock = {
+    now: () => new Date(),
+};
+export const createCommandMeta = (command, startedAt, finishedAt) => {
+    return {
+        command,
+        timestamp: finishedAt.toISOString(),
+        duration_ms: finishedAt.getTime() - startedAt.getTime(),
+    };
+};

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+export { createCli } from "./cli/create-cli.js";
+export { runCli } from "./cli/dispatch.js";
+export type { RunCliOptions } from "./cli/types.js";
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/cli.js

@@ -0,0 +1,2 @@
+export { createCli } from "./cli/create-cli.js";
+export { runCli } from "./cli/dispatch.js";

package/dist/client/app-client.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The typed client handle (issue #8) returned by {@link connect}/{@link waitForSession}: a thin
+ * wrapper over the same `tools.list`/`tools.call`/`events.subscribe`/`events.since` RPC the CLI and
+ * MCP server use (`rpc/client.ts`'s `DaemonStream`), bound to one resolved session. No new privilege
+ * or transport — every call is attributed `caller: "client"` for the audit log (ARCHITECTURE.md
+ * §12). {@link AppClient.waitForEvent}'s drain-then-live pattern mirrors the built-in
+ * `appduct_wait_for_event` MCP tool (`mcp/events-tool.ts`) — see that module's doc comment for
+ * why the notification listener has to be registered before the `events.since` drain call is sent.
+ */
+import { type ToolDescriptor } from "@appduct/shared";
+import type { DaemonStream } from "../rpc/client.js";
+/** A project's own tool map — declared once, e.g. `type Tools = { sum: { args: { a: number; b:
+ * number }; result: { total: number } } }` — to get typed {@link AppClient.call} throughout a test
+ * suite. Tool names and arg/result types can't be statically known here (they're registered by the
+ * connected app at runtime): the default `result` is `any` so the untyped form (`connect()` with no
+ * generic) still lets a caller destructure a call's result without a cast, e.g. `const { total } =
+ * await app.call("sum", { a: 2, b: 3 })`. `AppClient` itself is deliberately unconstrained (no
+ * `extends Record<string, ...>`) so both `type` aliases and plain `interface`s work here — TS only
+ * infers an implicit index signature for the former, so a constrained generic would silently reject
+ * the latter. */
+export type ToolMap = Record<string, {
+    args: Record<string, unknown>;
+    result: any;
+}>;
+type ToolArgs<TTools, K extends keyof TTools> = TTools[K] extends {
+    args: infer TArgs;
+} ? TArgs : Record<string, unknown>;
+type ToolResult<TTools, K extends keyof TTools> = TTools[K] extends {
+    result: infer TResult;
+} ? TResult : unknown;
+export type CallOptions = {
+    /** Forwarded to the daemon as this call's deadline, clamped server-side to [1s, 600s]. Omitted,
+     * the daemon falls back to the tool's own declared `timeoutMs` (`registerTool`), and to 10s for a
+     * tool that declares none. Either way this is NOT the call's transport timeout, which is derived
+     * automatically so a `tool_timeout` from the daemon always arrives before this client's own
+     * transport timeout would otherwise fire and misreport it as `connection_error`. */
+    timeoutMs?: number;
+};
+export type WaitForEventOptions = {
+    /** Defaults to 30s. */
+    timeoutMs?: number;
+    /** Extra filter over the event's payload; the event still must match `name` first. A predicate
+     * that throws rejects the wait with that error rather than crashing the connection. */
+    match?: (payload: unknown) => boolean;
+    /**
+     * Exclusive lower bound on `AppEvent.seq` (a cursor from a previous {@link AppClient.events} or
+     * {@link AppClient.waitForEvent} call) — skips already-retained events at/before it instead of
+     * resolving with an old match instantly. Omitted, the retained buffer is searched from its start,
+     * so a matching event that already fired before this call still resolves immediately.
+     */
+    since?: number;
+};
+export type EventsOptions = {
+    /** Exclusive lower bound on `AppEvent.seq`; omitted returns the whole retained buffer (oldest
+     * first, subject to `limit`). */
+    since?: number;
+    /** Caps the number of events returned (oldest-first truncation); omitted returns everything
+     * matching `since` up to the buffer's own retention limit. */
+    limit?: number;
+};
+export type EventsResult = {
+    events: AppEvent[];
+    /** The highest `seq` currently retained for this session (not just among the returned events) —
+     * pass it back as `since`/`since` on the next {@link AppClient.events}/{@link
+     * AppClient.waitForEvent} call to resume after it. */
+    cursor: number;
+};
+/** An app-pushed event (`postEvent(name, payload)`), narrowed from the daemon's generic
+ * `EventNotification` envelope to the shape a `waitForEvent`/`events` caller actually wants. */
+export type AppEvent<TPayload = unknown> = {
+    name: string;
+    payload: TPayload;
+    /** Unix ms. */
+    ts: number;
+    sessionId: string;
+    alias?: string;
+    /** Monotonically increasing per-session cursor (ARCHITECTURE.md §5) assigned by the daemon's
+     * retention buffer at emit time — pass back into `since` to resume after this event. */
+    seq: number;
+};
+export type AppClient<TTools = ToolMap> = {
+    readonly sessionId: string;
+    /** `tools.list` for this session. */
+    tools(): Promise<ToolDescriptor[]>;
+    /** `tools.call`; rejects with a {@link AppductError} whose `type` preserves the wire error
+     * type verbatim (e.g. `"tool_timeout"`, `"policy_denied"`, `"session_suspended"`). */
+    call<K extends keyof TTools & string>(name: K, args: ToolArgs<TTools, K>, options?: CallOptions): Promise<ToolResult<TTools, K>>;
+    /** Drains `app_event`s retained in the daemon's per-session ring buffer since a cursor — the pull
+     * counterpart to {@link AppClient.waitForEvent}, for checking what already happened instead of
+     * waiting for the next one. Pass `cursor` from the result back as `since` on the next call to
+     * avoid re-reading events already seen. */
+    events(options?: EventsOptions): Promise<EventsResult>;
+    /**
+     * Waits for the next `app_event` (as pushed by the connected app's `postEvent(name, payload)`)
+     * matching `name`. Checks the daemon's retained buffer for an already-arrived match first, then
+     * falls back to a live wait — so an event emitted between "the caller decides to wait" and "the
+     * subscription lands" is never missed; pass `since` (a cursor from a previous {@link
+     * AppClient.events}/`waitForEvent` call) to skip events already handled and wait only for a new
+     * one, since omitting it can return an old match instantly on every call.
+     *
+     * This shares the connection's single `events.subscribe` filter (the daemon keeps one per
+     * connection, replaced — not merged — on each call); concurrent `waitForEvent` calls on the same
+     * `AppClient` all see every `app_event`, so this is safe today, but it means the connection stays
+     * subscribed to `app_event` for its lifetime once any `waitForEvent` has run.
+     */
+    waitForEvent<TPayload = unknown>(name: string, options?: WaitForEventOptions): Promise<AppEvent<TPayload>>;
+    /** Closes the underlying connection. Safe to call more than once. */
+    close(): void;
+};
+/**
+ * Transport timeout for one `tools.call`. With an explicit `timeoutMs` the daemon-side deadline is
+ * known exactly, so this is that clamped value plus slack.
+ *
+ * Without one the daemon defaults to the *tool's own* declared `timeoutMs` (issue #25), which this
+ * client does not know at call time and would need an extra `tools.list` round trip (racy against
+ * re-registration) to learn — so it falls back to the largest deadline the daemon could possibly
+ * enforce. That is deliberately generous: this watchdog only exists for a daemon that accepts the
+ * request and then never answers, since a daemon that dies or drops the socket already rejects
+ * every pending call immediately (`rpc/client.ts`'s `close` handler). Sizing it off the 10 s
+ * default instead would make this client the thing that fails a long tool call, reporting a
+ * generic transport error in place of the daemon's real one.
+ */
+export declare const transportTimeoutForToolCall: (timeoutMs: number | undefined) => number;
+export declare const makeAppClient: <TTools = ToolMap>(stream: DaemonStream, sessionId: string) => AppClient<TTools>;
+export {};
+//# sourceMappingURL=app-client.d.ts.map

package/dist/client/app-client.d.ts.map

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

package/dist/client/app-client.js

@@ -0,0 +1,223 @@
+/**
+ * The typed client handle (issue #8) returned by {@link connect}/{@link waitForSession}: a thin
+ * wrapper over the same `tools.list`/`tools.call`/`events.subscribe`/`events.since` RPC the CLI and
+ * MCP server use (`rpc/client.ts`'s `DaemonStream`), bound to one resolved session. No new privilege
+ * or transport — every call is attributed `caller: "client"` for the audit log (ARCHITECTURE.md
+ * §12). {@link AppClient.waitForEvent}'s drain-then-live pattern mirrors the built-in
+ * `appduct_wait_for_event` MCP tool (`mcp/events-tool.ts`) — see that module's doc comment for
+ * why the notification listener has to be registered before the `events.since` drain call is sent.
+ */
+import { clampToolTimeoutMs, MAX_TOOL_TIMEOUT_MS, RPC_METHODS, } from "@appduct/shared";
+import { AppductError, toAppductError } from "./errors.js";
+const DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS = 30_000;
+/** Extra headroom so the daemon's own `tool_timeout` always wins the race against this client's
+ * transport timeout, even accounting for RPC round-trip and event-loop scheduling delay. Kept
+ * local because it is a property of this transport, not of the protocol; the *bounds* it is added
+ * to come from `@appduct/shared`, so this client and the daemon cannot disagree about the
+ * deadline itself. */
+const CALL_TRANSPORT_TIMEOUT_SLACK_MS = 5_000;
+/**
+ * Transport timeout for one `tools.call`. With an explicit `timeoutMs` the daemon-side deadline is
+ * known exactly, so this is that clamped value plus slack.
+ *
+ * Without one the daemon defaults to the *tool's own* declared `timeoutMs` (issue #25), which this
+ * client does not know at call time and would need an extra `tools.list` round trip (racy against
+ * re-registration) to learn — so it falls back to the largest deadline the daemon could possibly
+ * enforce. That is deliberately generous: this watchdog only exists for a daemon that accepts the
+ * request and then never answers, since a daemon that dies or drops the socket already rejects
+ * every pending call immediately (`rpc/client.ts`'s `close` handler). Sizing it off the 10 s
+ * default instead would make this client the thing that fails a long tool call, reporting a
+ * generic transport error in place of the daemon's real one.
+ */
+export const transportTimeoutForToolCall = (timeoutMs) => {
+    const clamped = timeoutMs === undefined || !Number.isFinite(timeoutMs)
+        ? MAX_TOOL_TIMEOUT_MS
+        : clampToolTimeoutMs(timeoutMs);
+    return clamped + CALL_TRANSPORT_TIMEOUT_SLACK_MS;
+};
+export const makeAppClient = (stream, sessionId) => {
+    const client = {
+        sessionId,
+        tools: async () => {
+            try {
+                return await stream.call(RPC_METHODS.toolsList, { selector: sessionId });
+            }
+            catch (error) {
+                throw toAppductError(error);
+            }
+        },
+        call: async (name, args, options) => {
+            try {
+                const result = await stream.call(RPC_METHODS.toolsCall, {
+                    selector: sessionId,
+                    name,
+                    args,
+                    timeoutMs: options?.timeoutMs,
+                    caller: "client",
+                }, transportTimeoutForToolCall(options?.timeoutMs));
+                return result.result;
+            }
+            catch (error) {
+                throw toAppductError(error);
+            }
+        },
+        events: async (options = {}) => {
+            try {
+                const result = await stream.call(RPC_METHODS.eventsSince, {
+                    selector: sessionId,
+                    since: options.since,
+                    limit: options.limit,
+                    kinds: ["app_event"],
+                });
+                return {
+                    events: result.events
+                        .map((event) => appEventFrom(event, sessionId))
+                        .filter((event) => event !== undefined),
+                    cursor: result.cursor,
+                };
+            }
+            catch (error) {
+                throw toAppductError(error);
+            }
+        },
+        waitForEvent: (name, options = {}) => {
+            const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS;
+            const toMatch = (event) => {
+                const appEvent = appEventFrom(event, sessionId);
+                if (!appEvent || appEvent.name !== name) {
+                    return undefined;
+                }
+                if (options.match && !options.match(appEvent.payload)) {
+                    return undefined;
+                }
+                return appEvent;
+            };
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                const settle = (fn) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    clearTimeout(timer);
+                    unsubscribeClose();
+                    liveHandler = null;
+                    fn();
+                };
+                const timer = setTimeout(() => {
+                    settle(() => reject(new AppductError("timeout", `Timed out after ${timeoutMs}ms waiting for event "${name}".`)));
+                }, timeoutMs);
+                // Registered before `events.since` is even sent (not merely before it resolves): the
+                // daemon's response to that call and a `notify()` for a brand-new event can arrive in the
+                // same socket chunk, and a listener added only after awaiting that response could miss a
+                // notification from that same chunk. Buffers into `earlyEvents` until the drain below has
+                // merged its own backlog and switched this to `liveHandler`.
+                let liveHandler = null;
+                const earlyEvents = [];
+                const unsubscribeNotification = stream.onNotification((payload) => {
+                    const event = payload;
+                    if (liveHandler) {
+                        liveHandler(event);
+                    }
+                    else {
+                        earlyEvents.push(event);
+                    }
+                });
+                let unsubscribeClose = () => { };
+                const fail = (error) => {
+                    settle(() => reject(toAppductError(error)));
+                    unsubscribeNotification();
+                };
+                (async () => {
+                    await stream.call(RPC_METHODS.eventsSubscribe, { sessionSelector: sessionId, kinds: ["app_event"] });
+                    const sinceResult = await stream.call(RPC_METHODS.eventsSince, {
+                        selector: sessionId,
+                        since: options.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). 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) {
+                        try {
+                            const matched = toMatch(event);
+                            if (matched) {
+                                settle(() => resolve(matched));
+                                unsubscribeNotification();
+                                return;
+                            }
+                        }
+                        catch (error) {
+                            fail(error);
+                            return;
+                        }
+                    }
+                    // Nothing matched yet: resume live from the last event actually considered, or — if
+                    // nothing was retained/arrived at all — `events.since`'s own cursor, which 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;
+                    unsubscribeClose = stream.onClose(() => {
+                        settle(() => reject(new AppductError("connection_error", `The connection to the Appduct daemon closed while waiting for event "${name}".`)));
+                        unsubscribeNotification();
+                    });
+                    // 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;
+                        }
+                        try {
+                            const matched = toMatch(event);
+                            if (matched) {
+                                settle(() => resolve(matched));
+                                unsubscribeNotification();
+                            }
+                        }
+                        catch (error) {
+                            fail(error);
+                        }
+                    };
+                })().catch((error) => {
+                    fail(error);
+                });
+            });
+        },
+        close: () => {
+            stream.close();
+        },
+    };
+    return client;
+};
+const appEventFrom = (event, sessionId) => {
+    if (event.kind !== "app_event" || event.sessionId !== sessionId) {
+        return undefined;
+    }
+    const data = event.data;
+    if (typeof data.name !== "string") {
+        return undefined;
+    }
+    return {
+        name: data.name,
+        payload: data.payload,
+        ts: event.ts,
+        sessionId: event.sessionId,
+        alias: event.alias,
+        seq: event.seq,
+    };
+};

package/dist/client/bootstrap.d.ts

@@ -0,0 +1,48 @@
+import { type ExecFn, type OpenTarget } from "../cli/open-target.js";
+import { type MintLinkResult } from "../link.js";
+import { type SpawnFn } from "../rpc/client.js";
+import { type AppClient, type ToolMap } from "./app-client.js";
+export type LinkOptions = {
+    stateDir?: string;
+    spawn?: SpawnFn;
+    /** Auto-spawn a daemon on a missing connection. Defaults to `true`. */
+    autoSpawn?: boolean;
+    ttlSeconds?: number;
+    /** Delivers the link directly to a booted Android emulator/device or iOS simulator instead of
+     * just minting it (the CI/agent path — no human needed to scan a QR). */
+    target?: OpenTarget;
+    /** `--device` equivalent: an adb serial, a simulator udid, or a paired-device udid. */
+    device?: string;
+    /** `--bundle-id` equivalent; only valid with `target: "ios-device"`, where it overrides
+     * `config.json`'s `iosBundleId`. */
+    bundleId?: string;
+    /** `--relaunch` equivalent; only valid with `target: "ios-device"`. */
+    relaunch?: boolean;
+    /** Highest-precedence scheme source, ahead of `APPDUCT_SCHEME`, a project
+     * `.appduct/config.json`, the state dir's `config.json` and `app.json` (see `scheme.ts`). */
+    scheme?: string;
+    /** Where scheme discovery starts; defaults to `process.cwd()`. */
+    cwd?: string;
+    exec?: ExecFn;
+    /** The environment handed to `adb`/`simctl`, *not* the one `APPDUCT_SCHEME` is read from
+     * (see {@link schemeEnv}) — narrowing this must not change scheme resolution. */
+    env?: NodeJS.ProcessEnv;
+    /** The environment `APPDUCT_SCHEME` is read from; defaults to `process.env`. */
+    schemeEnv?: NodeJS.ProcessEnv;
+};
+export type LinkResult = MintLinkResult;
+/** Mints a session link via `link.create` and composes the deep link. With `target` set, delivers
+ * it directly to a booted emulator/simulator instead of leaving delivery to the caller. */
+export declare const link: (options?: LinkOptions) => Promise<LinkResult>;
+export type WaitForSessionOptions = {
+    stateDir?: string;
+    spawn?: SpawnFn;
+    /** Auto-spawn a daemon on a missing connection. Defaults to `true`. */
+    autoSpawn?: boolean;
+    /** Defaults to 120s. */
+    timeoutMs?: number;
+};
+/** Waits for `sessionId` (from {@link link}) to be claimed by a device, then returns a connected
+ * {@link AppClient} for it — resolves immediately if it's already claimed. */
+export declare const waitForSession: <TTools = ToolMap>(sessionId: string, options?: WaitForSessionOptions) => Promise<AppClient<TTools>>;
+//# sourceMappingURL=bootstrap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/client/bootstrap.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAErE,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAuD,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrG,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAK9E,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;6EACyE;IACzE,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;wCACoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;iGAC6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;qFACiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,cAAc,CAAC;AAExC;2FAC2F;AAC3F,eAAO,MAAM,IAAI,GAAU,UAAS,WAAgB,KAAG,OAAO,CAAC,UAAU,CAoBxE,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;8EAC8E;AAC9E,eAAO,MAAM,cAAc,GAAU,MAAM,GAAG,OAAO,EACnD,WAAW,MAAM,EACjB,UAAS,qBAA0B,KAClC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CA0F3B,CAAC"}