appduct 0.12.0 → 0.14.0

package/dist/daemon/registry.d.ts

@@ -1,18 +1,26 @@
 /**
- * Per-session tool registry (ARCHITECTURE.md §7). Callers (sessions.ts/listener.ts) must validate
- * incoming `tool_registry_snapshot`/`tool_registry_delta` wire messages with the shared guards
- * *before* calling into this module — v1 crashed by indexing into an unvalidated `tools: [null]`
- * snapshot; this module only ever stores already-validated {@link ToolDescriptor}s.
+ * Per-session registry of what an app declared, by name (ARCHITECTURE.md §7): one instance holds a
+ * session's tools, another its events (issue #124). Callers (sessions.ts) must validate incoming
+ * `tool_registry_*`/`event_registry_*` wire messages with the shared guards *before* calling into
+ * this module — v1 crashed by indexing into an unvalidated `tools: [null]` snapshot; this module
+ * only ever stores already-validated descriptors.
  */
-import type { ToolDescriptor } from "@appduct/shared";
-export type ToolRegistry = {
+import type { EventDescriptor, ToolDescriptor } from "@appduct/shared";
+export type Registry<T extends {
+    name: string;
+}> = {
     /** Authoritative replace: used for the initial snapshot and every post-resume re-sync. */
-    snapshot: (tools: ToolDescriptor[]) => void;
-    upsert: (tool: ToolDescriptor) => void;
+    snapshot: (items: T[]) => void;
+    upsert: (item: T) => void;
     remove: (name: string) => void;
-    list: () => ToolDescriptor[];
-    get: (name: string) => ToolDescriptor | undefined;
+    list: () => T[];
+    get: (name: string) => T | undefined;
     count: () => number;
 };
-/** `onChange` fires after every mutation (snapshot/upsert/remove) — used to emit `tools_changed`. */
-export declare const createToolRegistry: (onChange?: () => void) => ToolRegistry;
+export type ToolRegistry = Registry<ToolDescriptor>;
+export type EventRegistry = Registry<EventDescriptor>;
+/** `onChange` fires after every mutation (snapshot/upsert/remove) — used to emit `tools_changed`
+ * and `events_changed`. */
+export declare const createRegistry: <T extends {
+    name: string;
+}>(onChange?: () => void) => Registry<T>;

package/dist/daemon/rpc-errors.d.ts

@@ -2,7 +2,7 @@
  * The error the daemon's RPC handlers throw to answer a request with a typed wire error
  * (ARCHITECTURE.md §5). It lives apart from `rpc-server.ts` so the modules that *raise* it — the
  * session engine, the call engine — don't drag the socket server itself into every bundle that
- * needs, say, a call-timeout constant from `calls.ts` (the CLI's `invoke` route does).
+ * needs, say, a call-timeout constant from `calls.ts` (the CLI's `tools call` route does).
  */
 import type { ErrorType } from "@appduct/shared";
 export declare class RpcApplicationError extends Error {
@@ -14,3 +14,6 @@ export declare class RpcApplicationError extends Error {
     /** JSON-RPC error code; defaults to the shared "server error" range. */
     code?: number, details?: unknown | undefined);
 }
+/** The `session_suspended` message for an app that closed its socket because it went to the
+ * background: says why and how to recover. */
+export declare const appBackgroundedMessage: (alias: string) => string;

package/dist/daemon/sessions.d.ts

@@ -10,12 +10,12 @@
  * §6: "terminal states free the alias" — there is no persisted history, matching §3/§13's "no
  * per-session files, all state in-daemon-memory").
  */
-import { type EventMessage, type SessionClaimMessage, type SessionResumeMessage, type SessionSummary, type ToolCallMessage, type ToolCallProgressMessage, type ToolCancelMessage, type ToolErrorMessage, type ToolResultMessage } from "@appduct/shared";
+import { type EventMessage, type SessionClaimMessage, type SessionResumeMessage, type SessionSummary, type SessionSuspendReason, type ToolCallMessage, type ToolCallProgressMessage, type ToolCancelMessage, type ToolErrorMessage, type ToolResultMessage } from "@appduct/shared";
 import type { WebSocket } from "ws";
 import type { Clock } from "../cli/types.js";
 import type { EventBus } from "./event-bus.js";
 import { type CreatedLink } from "./links.js";
-import { type ToolRegistry } from "./registry.js";
+import { type EventRegistry, type ToolRegistry } from "./registry.js";
 import { type TimerFns } from "./timers.js";
 /** Wire message types allowed *after* claim (session_claim/session_resume are pre-claim only). */
 export declare const POST_CLAIM_MESSAGE_TYPES: Set<string>;
@@ -69,7 +69,9 @@ export type SessionManager = {
         sessionId: string;
         alias: string;
         state: "active" | "suspended";
+        suspendReason?: SessionSuspendReason;
         registry: ToolRegistry;
+        eventRegistry: EventRegistry;
     };
     /** Sends a `tool_call` frame to the session's active socket; `false` if the session has no
      * active socket right now (caller has typically already checked ACTIVE state via

package/dist/errors.d.ts

@@ -18,7 +18,7 @@ export declare const isAppductCliError: (value: unknown) => value is AppductCliE
  * Converts any error thrown from a command handler into the CLI's rendered `CliError` shape.
  * RPC/app-originated failures (`DaemonRpcError` with a preserved `data.type`) keep that type
  * **verbatim** in `type` — never re-wrapped under a generic bucket (ARCHITECTURE.md §5) — so e.g.
- * `invoke --json` on a failing tool call renders `error.type === "tool_execution_error"`, not
+ * `tools call --json` on a failing tool call renders `error.type === "tool_execution_error"`, not
  * `"tool_error"`. `getExitCodeForError` still buckets that same error into a sysexits class.
  */
 export declare const toCliError: (error: unknown) => CliError;

package/dist/events/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `waitForAppEvent` (issue #114): the one drain-then-live wait implementation shared by the
+ * built-in `appduct_wait_for_event` MCP tool (`mcp/events-tool.ts`) and `appduct/client`'s
+ * `AppClient.waitForEvent` (`client/app-client.ts`), which used to each carry their own copy.
+ *
+ * Filtering by `name` (a whole-name, case-sensitive glob — issue #112) and truncating a payload
+ * over `payloadMaxBytes` (issue #113) both happen daemon-side, via the same `projectAppEvent`
+ * (`daemon/event-bus.ts`) that `events.since`'s drain and `events.subscribe`'s live fan-out both
+ * already call — this module forwards `name`/`payloadMaxBytes` to both RPCs and never re-checks
+ * a name or re-truncates a payload itself.
+ *
+ * The drain-then-live shape exists to close the race `appduct_wait_for_session` doesn't have to
+ * worry about: a session is either claimed or not, but an app event can fire between "the caller
+ * decides to wait" and "the wait subscription lands". The notification listener is registered
+ * *before* `events.subscribe` is even sent — not merely before it resolves — because the
+ * daemon's response to that call and a `notify()` for a brand-new event can arrive in the same
+ * socket chunk; `rpc/client.ts`'s `DaemonStream` fans a chunk's notification lines out to
+ * whatever listeners exist at the moment it's processed, so a listener added only after `await`ing
+ * that response could miss a notification line from that same chunk. Arrivals before the drain
+ * has been merged into the backlog are buffered, then merged in (deduped by `seq`) before falling
+ * through to the live phase.
+ *
+ * `stream` is the caller's: opened and closed by the caller. Every caller of this module opens
+ * one stream per `waitForAppEvent` call — the MCP tool always did (`openDaemonStream` per
+ * `tools/call`), and the SDK now does too, so concurrent `waitForEvent` calls with different
+ * `name`s never clobber a shared connection's single `events.subscribe` filter.
+ */
+import { type AppEvent } from "@appduct/shared";
+import type { DaemonStream } from "../rpc/client.js";
+export type WaitForAppEventOptions = {
+    sessionId: string;
+    /** Whole-name, case-sensitive glob (issue #112): `*` matches any run of characters, a pattern
+     * with no `*` is an exact name — forwarded verbatim to `events.since`/`events.subscribe`. */
+    name: string;
+    /** Exclusive lower bound on `AppEvent.seq`; omitted drains the whole retained buffer. */
+    since?: number;
+    timeoutMs: number;
+    /** Caps the resolved event's payload to this many UTF-8 bytes of its JSON, daemon-side, on
+     * both the drain and the live half. Omitted, payloads are delivered whole. */
+    payloadMaxBytes?: number;
+};
+export type WaitForAppEventResult = {
+    event: AppEvent;
+    /** `events.since`'s own `dropped` from the drain: app events after `since` that were evicted
+     * before the drain could return them (`0` once nothing has fallen off). Reflects only the
+     * drain — an event that resolves this wait live was delivered, not dropped. */
+    dropped: number;
+};
+/** Raised when nothing matching `name` arrived within `timeoutMs`. */
+export declare class WaitForAppEventTimeoutError extends Error {
+    readonly eventName: string;
+    readonly timeoutMs: number;
+    constructor(eventName: string, timeoutMs: number);
+}
+/** Raised when `stream` closes (daemon gone, `stop()`, etc.) while a live wait was in flight. */
+export declare class WaitForAppEventConnectionClosedError extends Error {
+    readonly eventName: string;
+    constructor(eventName: string);
+}
+export declare const waitForAppEvent: (stream: DaemonStream, options: WaitForAppEventOptions) => Promise<WaitForAppEventResult>;

package/dist/index.js

@@ -121,27 +121,30 @@ var createCli = () => {
     'Android package name to write as "appId.android" (needed to deliver a link with --open android).'
   );
   cli.command("keygen", "Generate an Appduct host private key and print its app fingerprint.").option("--out <path>", "Destination path (default: <state-dir>/key.pem).").option("--force", "Overwrite an existing key at the destination path.");
-  cli.command("link", "Mint a pending session and print its deep link.").option("--ttl <seconds>", "Link time-to-live in seconds (default: from config.json).").option("--qr", "Also render the deep link as a terminal QR code.").option(
+  cli.command("sessions [...args]", "Manage Appduct sessions: ls, revoke, or link.").usage("sessions <ls|revoke|link> [selector] [args]").option("--ttl <seconds>", "link: time-to-live in seconds (default: from config.json).").option("--qr", "link: also render the deep link as a terminal QR code.").option(
     "--scheme <scheme>",
-    `Deep-link URI scheme (also: APPDUCT_SCHEME; default: .appduct/config.json, then app.json's "expo.scheme", then the Android/iOS project files in <cwd>).`
+    `link: deep-link URI scheme (also: APPDUCT_SCHEME; default: .appduct/config.json, then app.json's "expo.scheme", then the Android/iOS project files in <cwd>).`
   ).option(
     "--open <target>",
-    "Deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental)."
-  ).option("--device <id>", "adb serial, simulator udid or paired-device udid to target when --open is ambiguous.").option(
+    "link: deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental)."
+  ).option("--device <id>", "link: adb serial, simulator udid or paired-device udid to target when --open is ambiguous.").option(
     "--app-id <id>",
-    `Installed app id for --open android/ios-device (default: .appduct/config.json's "appId.<platform>").`
+    `link: installed app id for --open android/ios-device (default: .appduct/config.json's "appId.<platform>").`
   ).option(
     "--relaunch",
-    "With --open ios-device, terminate a running instance first (try this if delivery to an already-running app does nothing)."
+    "link: with --open ios-device, terminate a running instance first (try this if delivery to an already-running app does nothing)."
   );
-  cli.command("ls", "List Appduct sessions.");
-  cli.command("tools [selector] [name]", "List a session's tools, or show one tool's full schema.").option("--full", "Render full schemas/annotations for every listed tool.").option("--group <name>", 'Only tools in this group ("checkout" includes "checkout/payment").').option("--groups", "List the session's groups with tool counts instead of its tools.").option("--filter <text>", "Only tools whose name or description contains this text (case-insensitive).").option("--limit <n>", "Show at most n tools.").option("--offset <n>", "Skip the first n tools of the sorted list.");
-  cli.command("invoke [selector] [tool]", "Call a tool on a session.").option("--input <json>", "Tool input arguments as a JSON object.").option(
+  cli.command("tools [...args]", "List a session's tools, describe one, or call one: ls, describe, or call.").usage("tools <ls|describe|call> [selector] [args]").option("--full", "ls: render full schemas/annotations for every listed tool.").option("--group <name>", 'ls: only tools in this group ("checkout" includes "checkout/payment").').option("--groups", "ls: list the session's groups with tool counts instead of its tools.").option("--filter <text>", "ls: only tools whose name or description contains this text (case-insensitive).").option("--limit <n>", "ls: show at most n tools.").option("--offset <n>", "ls: skip the first n tools of the sorted list.").option("--input <json>", "call: tool input arguments as a JSON object.").option(
     "--timeout <ms>",
-    "Call timeout in milliseconds. Shortens the deadline; it cannot extend one past the app's own timer, which is the tool's declared timeoutMs (else 10000)."
+    "call: call timeout in milliseconds. Shortens the deadline; it cannot extend one past the app's own timer, which is the tool's declared timeoutMs (else 10000)."
+  );
+  cli.command("events [...args]", "List the events an app declares, stream them, or replay them since a cursor: ls, tail, or since.").usage("events <ls|tail|since> [selector] [args]").option("--follow", "tail: accepted for script readability; the default behavior already follows.").option(
+    "--name <glob>",
+    `Only events whose name matches this whole-name, case-sensitive glob ("*" matches any run of characters). ls: an exact name prints that event's full payload schema.`
+  ).option("--limit <n>", "ls: show at most n events.").option("--offset <n>", "ls: skip the first n events of the name-sorted list.").option(
+    "--payload-max-bytes <n>",
+    "Cap each event's payload at this many UTF-8 bytes of its JSON; over the cap, the event carries payloadPreview, payloadBytes and truncated: true instead of payload."
   );
-  cli.command("events [selector]", "Stream the events the app posts until interrupted.").option("--follow", "Accepted for script readability; the default behavior already follows.").option("--since <cursor>", "One-shot: print the app events retained since this cursor instead of streaming live.");
-  cli.command("revoke [selector]", "Revoke a session.");
   cli.command("mcp", "Start a stdio MCP server that gives MCP clients access to connected apps' tools.").option(
     "--scheme <scheme>",
     "Deep-link URI scheme for appduct_connect (also: APPDUCT_SCHEME)."
@@ -543,6 +546,7 @@ var getExitCodeForError = (error) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -638,6 +642,13 @@ var formatDevice = (device) => {
   const label = parts.length > 0 ? parts.join(" ") : "unknown device";
   return device.os ? `${label} (${device.os})` : label;
 };
+var SUSPEND_REASON_LABELS = {
+  app_backgrounded: "app in background",
+  connection_lost: "connection lost"
+};
+var formatSessionState = (session) => {
+  return session.suspendReason ? `${session.state} (${SUSPEND_REASON_LABELS[session.suspendReason]})` : session.state;
+};
 var renderLsData = (colors, data, now) => {
   if (data.length === 0) {
     return [colors.dim("Sessions"), "  No Appduct sessions are registered."];
@@ -646,7 +657,7 @@ var renderLsData = (colors, data, now) => {
   const headers = ["Alias", "State", "Device", "Tools", "Age"];
   const rows = data.map((session) => [
     session.alias,
-    session.state,
+    formatSessionState(session),
     formatDevice(session.device),
     String(session.toolCount),
     formatAge(session.claimedAt ?? session.createdAt, nowIso)
@@ -660,9 +671,6 @@ var renderLsData = (colors, data, now) => {
     ...rows.map((row) => `  ${row.map((cell, index) => cell.padEnd(widths[index])).join("  ")}`)
   ];
 };
-var isToolsListing = (data) => {
-  return typeof data === "object" && data !== null && Array.isArray(data.tools);
-};
 var isToolGroupsListing = (data) => {
   return typeof data === "object" && data !== null && Array.isArray(data.groups) && !Array.isArray(data.tools);
 };
@@ -680,7 +688,7 @@ var renderEmptyToolsLine = (data) => {
   }
   if (data.group !== void 0) {
     const match = data.filter === void 0 ? "" : ` match ${JSON.stringify(data.filter)}`;
-    return `  No tools in group ${JSON.stringify(data.group)}${match}. Run \`appduct tools --groups\` to see the session's groups.`;
+    return `  No tools in group ${JSON.stringify(data.group)}${match}. Run \`appduct tools ls --groups\` to see the session's groups.`;
   }
   return data.filter === void 0 ? "  No tools registered." : `  No tools match ${JSON.stringify(data.filter)}.`;
 };
@@ -762,7 +770,7 @@ var renderToolSummaryTable = (colors, data) => {
     ...grouped ? renderGroupedToolLines(colors, data.tools) : data.tools.flatMap((tool) => renderToolSummaryLines(tool, "  ")),
     ...renderTruncationLine(data),
     "",
-    "Run `appduct tools <name>` for a tool's full schema."
+    "Run `appduct tools describe <name>` for a tool's full schema."
   ];
 };
 var renderToolDetail = (colors, tool, flags) => {
@@ -814,18 +822,62 @@ var renderToolGroups = (colors, data) => {
     colors.green("Groups"),
     ...data.groups.map((entry) => `  ${label(entry).padEnd(width)}  ${String(entry.total).padStart(countWidth)}`),
     "",
-    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools --group <name>` to list one group's tools." : "No tool declares a group.")
+    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools ls --group <name>` to list one group's tools." : "No tool declares a group.")
   ];
 };
-var renderToolsData = (colors, data, flags, full) => {
+var renderToolsListData = (colors, data, flags, full) => {
   if (isToolGroupsListing(data)) {
     return renderToolGroups(colors, data);
   }
-  if (!isToolsListing(data)) {
-    return renderToolDetail(colors, data, flags);
-  }
   return full ? renderToolsFullListing(colors, data, flags) : renderToolSummaryTable(colors, data);
 };
+var renderEventsTruncationLine = (data) => {
+  const offset = data.offset ?? 0;
+  if (data.events.length >= data.total) {
+    return [];
+  }
+  return [
+    "",
+    `Showing ${data.events.length} of ${data.total} events (offset ${offset}). Narrow with --name <glob> or page with --offset <n>.`
+  ];
+};
+var renderEventsListData = (colors, data, flags) => {
+  const [only] = data.events;
+  if (data.name !== void 0 && !data.name.includes("*") && only !== void 0) {
+    return renderFields(
+      colors.green(`Event: ${only.name}`),
+      [
+        ["Signature", renderEventSignature(only)],
+        ["Description", only.description],
+        ["Payload schema", only.payload_schema]
+      ],
+      flags
+    );
+  }
+  if (data.events.length === 0 && data.total > 0) {
+    return [
+      colors.green("Events"),
+      `  No events at offset ${data.offset ?? 0}; ${data.total} matching event${data.total === 1 ? "" : "s"} in total.`
+    ];
+  }
+  if (data.events.length === 0) {
+    return [
+      colors.green("Events"),
+      data.name === void 0 ? "  No events declared." : `  No events match ${JSON.stringify(data.name)}.`
+    ];
+  }
+  const lines = data.events.flatMap((event) => [
+    `  ${renderEventSignature(event)}`,
+    `    ${summarizeToolDescription(event.description)}`
+  ]);
+  return [
+    colors.green("Events"),
+    ...lines,
+    ...renderEventsTruncationLine(data),
+    "",
+    "Run `appduct events ls --name <name>` for an event's full payload schema."
+  ];
+};
 var renderInvokeData = (colors, data, flags) => {
   return [colors.green("Result"), formatScalar(data, flags)];
 };
@@ -1009,15 +1061,19 @@ var renderSuccessData = (colors, command, data, options) => {
       return renderInitData(colors, data, flags);
     case "keygen":
       return renderKeygenData(colors, data, flags);
-    case "link":
+    case "sessions link":
       return renderLinkData(colors, data, flags, options.qr);
-    case "ls":
+    case "sessions ls":
       return renderLsData(colors, data, options.now ?? /* @__PURE__ */ new Date());
-    case "tools":
-      return renderToolsData(colors, data, flags, options.full);
-    case "invoke":
+    case "tools ls":
+      return renderToolsListData(colors, data, flags, options.full);
+    case "tools describe":
+      return renderToolDetail(colors, data, flags);
+    case "events ls":
+      return renderEventsListData(colors, data, flags);
+    case "tools call":
       return renderInvokeData(colors, data, flags);
-    case "revoke":
+    case "sessions revoke":
       return renderRevokeData(colors, data);
     case "daemon run":
       return renderDaemonRunData(colors, data, flags);
@@ -1087,12 +1143,21 @@ var renderEventLine = (event, flags) => {
   const dataSuffix = event.data === void 0 ? "" : ` ${formatJson(event.data, flags)}`;
   return `${colors.dim(timestamp)} ${colors.green(event.kind)}${target ? ` ${target}` : ""}${dataSuffix}`;
 };
-var renderEventsCursorLine = (cursor, flags) => {
+var shellQuote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+var renderEventsCursorLine = (cursor, flags, selector, filters) => {
   if (flags.json) {
-    return JSON.stringify({ cursor });
+    return JSON.stringify({ cursor: cursor.cursor, dropped: cursor.dropped, remaining: cursor.remaining });
   }
   const colors = pc.createColors(flags.color);
-  return colors.dim(`cursor: ${cursor} (pass --since ${cursor} to resume from here)`);
+  const target = selector === void 0 ? `${cursor.cursor}` : `${selector} ${cursor.cursor}`;
+  const flagTokens = [
+    ...filters?.name === void 0 ? [] : [`--name ${shellQuote(filters.name)}`],
+    ...filters?.payloadMaxBytes === void 0 ? [] : [`--payload-max-bytes ${filters.payloadMaxBytes}`]
+  ];
+  const command = [`appduct events since ${target}`, ...flagTokens].join(" ");
+  return colors.dim(
+    `cursor: ${cursor.cursor}, dropped: ${cursor.dropped}, remaining: ${cursor.remaining} (run "${command}" to resume from here)`
+  );
 };
 
 // src/cli/envelope.ts
@@ -1189,21 +1254,30 @@ var DAEMON_RESTART_ENV = "APPDUCT_DAEMON_RESTART";
 var isEnvTruthy = (value) => {
   return value === "1" || value?.toLowerCase() === "true";
 };
+var REMOVED_COMMANDS = {
+  ls: "sessions ls",
+  revoke: "sessions revoke",
+  link: "sessions link",
+  invoke: "tools call"
+};
+var rootUnknownCommandError = (word) => {
+  if (word !== void 0 && Object.hasOwn(REMOVED_COMMANDS, word)) {
+    return usageError(`Unknown command "${word}"; use "appduct ${REMOVED_COMMANDS[word]}".`);
+  }
+  return unknownCommandError(word);
+};
 var rootRouter = createRouter(
   {
     init: () => import("./cli/routes/init.js"),
     keygen: () => import("./cli/routes/keygen.js"),
-    link: () => import("./cli/routes/link.js"),
-    ls: () => import("./cli/routes/ls.js"),
-    tools: () => import("./cli/routes/tools.js"),
-    invoke: () => import("./cli/routes/invoke.js"),
-    revoke: () => import("./cli/routes/revoke.js"),
-    events: () => import("./cli/routes/events.js"),
+    sessions: () => import("./cli/routes/sessions/index.js"),
+    tools: () => import("./cli/routes/tools/index.js"),
+    events: () => import("./cli/routes/events/index.js"),
     mcp: () => import("./cli/routes/mcp.js"),
     doctor: () => import("./cli/routes/doctor.js"),
     daemon: () => import("./cli/routes/daemon/index.js")
   },
-  { unknown: unknownCommandError }
+  { unknown: rootUnknownCommandError }
 );
 var runCli = async (argv, options = {}) => {
   const writers = {
@@ -1242,7 +1316,7 @@ var runCli = async (argv, options = {}) => {
       return executeCommand(
         "cli",
         () => {
-          throw usageError(`Unknown command "${parsedArgs[0]}".`);
+          throw rootUnknownCommandError(parsedArgs[0]);
         },
         {
           flags,

package/dist/link.d.ts

@@ -2,7 +2,7 @@
  * 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
+ * Android emulator/device or iOS simulator. Used by `commands/link.ts` (`appduct sessions 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

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

@@ -1,8 +1,9 @@
 /**
  * The built-in `appduct_list_tools` / `appduct_describe_tool` / `appduct_call_tool` MCP tools
  * (ARCHITECTURE.md §9). The app's own tools are never listed as MCP tools. An agent reaches them
- * the way the CLI does: compact signatures first (`appduct tools`), one full schema on demand
- * (`appduct tools <name>`), then a call by name (`appduct invoke`). A registry of hundreds of tools
+ * the way the CLI does: compact signatures first (`appduct tools ls`), one full schema on demand
+ * (`appduct tools describe <name>`), then a call by name (`appduct tools call`). A registry of
+ * hundreds of tools
  * therefore costs a client three fixed tool definitions, and `tools/list` never changes while an
  * agent works.
  *
@@ -106,12 +107,30 @@ export type ResolvedAppTool = {
     descriptor: ListedToolDescriptor;
     policy: EffectivePolicyDecision;
 };
+type ResolvedSession = {
+    sessionId: string;
+    alias: string;
+};
 export type CallToolArgs = {
     selector?: string;
     name: string;
     args: Record<string, unknown>;
     timeoutMs?: number;
 };
+/** Every key an agent sends must be one the tool declares. A misspelled key (`arguments` for
+ * `args`, `timeout_ms` for `timeoutMs`) would otherwise be dropped silently, and the tool would run
+ * without what the agent meant to pass. */
+export declare const rejectUnknownKeys: (args: Record<string, unknown>, tool: string, allowed: readonly string[]) => void;
+/** `null` counts as absent for every optional field: some clients fill unset optional
+ * parameters with `null` rather than leaving them out. */
+export declare const asOptionalString: (value: unknown, field: string) => string | undefined;
+/** Resolves `selector` (an alias, a session id, or nothing) to one concrete session first, with
+ * the daemon's own rules and errors (`no_session`, `ambiguous_session`, `unknown_session`).
+ * Everything after that is routed by the **session id**, never the alias: the daemon frees an
+ * alias when a session ends and gives it to the next device of the same model, so routing by alias
+ * could land a call — one the user may already have approved — on a different device. If the
+ * session goes away mid-call, the next daemon call fails with `unknown_session` instead. */
+export declare const resolveSession: (call: DaemonCall, selector: string | undefined) => Promise<ResolvedSession>;
 export declare const handleListToolsTool: (rawArgs: unknown, call: DaemonCall) => Promise<{
     groups?: import("@appduct/shared").ToolGroupSummary[] | undefined;
     tools: {
@@ -151,3 +170,4 @@ export declare const parseCallToolArgs: (rawArgs: unknown) => CallToolArgs;
  */
 export declare const resolveCallDeadline: (tool: ResolvedAppTool, requestedTimeoutMs: number | undefined) => number;
 export declare const resolveAppTool: (call: DaemonCall, selector: string | undefined, name: string) => Promise<ResolvedAppTool>;
+export {};

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

@@ -71,7 +71,7 @@ export declare class McpBuiltinToolError extends Error {
 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,
+     * server startup against the shared order in `scheme.ts` — the same one `appduct sessions 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

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

@@ -4,27 +4,48 @@
  * per-session retention buffer on the daemon side — see `daemon/event-bus.ts`). MCP is
  * request/response, so an agent otherwise has no way to observe anything the app pushes.
  *
- * `appduct_wait_for_event` drains the retained buffer for an already-arrived match before
- * falling back to a live wait, exactly to avoid the race `appduct_wait_for_session` doesn't
- * have to worry about (a session is either claimed or it isn't, but an `app_event` can easily fire
- * between "the agent decides to wait" and "the wait subscription lands"). The live notification
- * listener is registered *before* the `events.since` drain call is even sent — not merely before
- * it resolves — because the daemon's response to that call and a subsequent `notify()` for a new
- * event can arrive in the same socket chunk; `rpc/client.ts` fans a chunk's notification lines out
- * to whatever listeners exist at the moment it's processed, so a listener added only after `await
- * stream.call(eventsSince, …)` returns can miss an event that was already in that same chunk.
- * Arrivals before the drain has been merged into the backlog are buffered, then merged in
- * (deduped by `seq`) before falling through to the live phase — see `handleWaitForEventTool` below.
+ * `appduct_wait_for_event`'s drain-then-live wait is `events/index.ts`'s `waitForAppEvent`
+ * (issue #114) — the same implementation `appduct/client`'s `AppClient.waitForEvent` uses — this
+ * module only resolves the selector, applies MCP-specific defaults (`payloadMaxBytes`), and maps
+ * that module's typed errors onto this tool's `tool_timeout`/`tool_execution_error`.
  */
-import { type EventsSinceResult } from "@appduct/shared";
+import { type AppEvent } from "@appduct/shared";
 import { type SpawnFn } from "../rpc/client.js";
 import type { DaemonCall } from "./daemon-tools.js";
+export declare const LIST_EVENTS_TOOL_NAME = "appduct_list_events";
 export declare const EVENTS_TOOL_NAME = "appduct_events";
 export declare const WAIT_FOR_EVENT_TOOL_NAME = "appduct_wait_for_event";
 /** Server-side cap on `timeoutMs` (issue #6's "Cap timeoutMs server-side below the idle window
  * rather than trusting the caller") — a pure function so the cap's boundary behavior is
  * unit-testable without spinning up a daemon or actually waiting out either bound. */
 export declare const clampWaitForEventTimeoutMs: (requestedMs: number | undefined) => number;
+export declare const LIST_EVENTS_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_list_events";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly selector: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Session alias or id. Omit to target the sole active/suspended session.";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly exclusiveMinimum: 0;
+            };
+            readonly offset: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+        };
+        readonly additionalProperties: false;
+    };
+};
 export declare const EVENTS_TOOL_DESCRIPTOR: {
     readonly name: "appduct_events";
     readonly description: string;
@@ -42,6 +63,13 @@ export declare const EVENTS_TOOL_DESCRIPTOR: {
                 readonly type: "integer";
                 readonly exclusiveMinimum: 0;
             };
+            readonly name: {
+                readonly type: "string";
+            };
+            readonly payloadMaxBytes: {
+                readonly type: "integer";
+                readonly exclusiveMinimum: 0;
+            };
         };
         readonly additionalProperties: false;
     };
@@ -58,12 +86,6 @@ export declare const WAIT_FOR_EVENT_TOOL_DESCRIPTOR: {
             readonly name: {
                 readonly type: "string";
             };
-            readonly match: {
-                readonly type: "object";
-                readonly additionalProperties: {
-                    readonly type: readonly ["string", "number", "boolean", "null"];
-                };
-            };
             readonly since: {
                 readonly type: "integer";
                 readonly minimum: 0;
@@ -72,6 +94,10 @@ export declare const WAIT_FOR_EVENT_TOOL_DESCRIPTOR: {
                 readonly type: "number";
                 readonly exclusiveMinimum: 0;
             };
+            readonly payloadMaxBytes: {
+                readonly type: "integer";
+                readonly exclusiveMinimum: 0;
+            };
         };
         readonly required: readonly ["name"];
         readonly additionalProperties: false;
@@ -80,7 +106,24 @@ export declare const WAIT_FOR_EVENT_TOOL_DESCRIPTOR: {
 export type EventsToolDeps = {
     call: DaemonCall;
 };
-export declare const handleEventsTool: (rawArgs: unknown, deps: EventsToolDeps) => Promise<EventsSinceResult>;
+export declare const handleListEventsTool: (rawArgs: unknown, call: DaemonCall) => Promise<{
+    session: string;
+    total: number;
+    limit: {};
+    events: {
+        payload_schema?: import("@appduct/shared").EventSchemaDescriptor | undefined;
+        name: string;
+        signature: string;
+        description: string;
+    }[];
+}>;
+export type EventsToolResult = {
+    events: AppEvent[];
+    cursor: number;
+    dropped: number;
+    remaining: number;
+};
+export declare const handleEventsTool: (rawArgs: unknown, deps: EventsToolDeps) => Promise<EventsToolResult>;
 export type WaitForEventToolDeps = {
     stateDir: string;
     spawn?: SpawnFn;
@@ -91,13 +134,10 @@ export type WaitForEventToolDeps = {
         sendNotification: (notification: unknown) => Promise<void>;
     };
 };
-export type WaitForEventToolResult = {
-    sessionId: string;
-    alias?: string;
-    name: string;
-    payload: unknown;
-    /** Unix ms. */
-    ts: number;
-    seq: number;
+/** An `AppEvent` (full or truncated — issue #113) plus `dropped` from the drain (issue #114). */
+export type WaitForEventToolResult = AppEvent & {
+    /** App events after `since` that were evicted before this call could return them (`0` once
+     * nothing has fallen off). */
+    dropped: number;
 };
 export declare const handleWaitForEventTool: (rawArgs: unknown, deps: WaitForEventToolDeps) => Promise<WaitForEventToolResult>;

package/dist/native-scheme.d.ts

@@ -25,7 +25,7 @@
  * **Disagreement is not guessed away.** If more than one probe below resolves to a *different*
  * scheme (e.g. a monorepo whose `android/` and `ios/` declare different values), discovery throws
  * a usage error naming every conflicting source instead of picking one — silently choosing would
- * mean `appduct link` opens the wrong app on whichever platform lost.
+ * mean `appduct sessions link` opens the wrong app on whichever platform lost.
  */
 export type NativeSchemeSource = "android-gradle" | "android-manifest" | "ios-info-plist" | "ios-project-yml";
 export type NativeSchemeProbeResult = {