appduct 0.11.1 → 0.13.0

package/dist/daemon/event-bus.d.ts

@@ -4,9 +4,10 @@
  * per-session retention ring buffer, and must never let a throwing subscriber take down the daemon
  * or another subscriber.
  *
- * Retention (issue #6): every session-scoped event (`sessionId` set), except the high-frequency
- * kinds in `EXCLUDED_FROM_RETENTION`, is appended to a per-session ring buffer with a
- * monotonically increasing `seq`, capped at `bufferSize` entries (oldest dropped first). A
+ * Retention (issue #6, #98): every session-scoped event gets a monotonically increasing per-session
+ * `seq`, but only `app_event` is appended to the per-session ring buffer, capped at `bufferSize`
+ * entries (oldest dropped first). Appduct's own kinds (lifecycle, tool calls) are fanned out live
+ * and never retained, so no number of tool calls can evict an app event. A
  * session's buffer is discarded the moment it emits a terminal event (`session_expired` /
  * `session_revoked`) — "terminal states free the alias" (sessions.ts) applies to retained events
  * too, matching "no persisted history" (ARCHITECTURE.md §3/§13) — or via an explicit `drop()` for
@@ -20,14 +21,45 @@ export type EventBusEmitInput = Omit<EventNotification, "ts" | "seq"> & {
     ts?: number;
 };
 export type EventBusListener = (event: EventNotification) => void;
+export type ProjectAppEventOptions = {
+    /** Whole-name, case-sensitive glob (issue #112): `*` matches any run of characters, a pattern
+     * with no `*` is an exact name. */
+    name?: string;
+    /** Caps the payload's JSON to this many UTF-8 bytes (issue #113); see {@link truncateToUtf8Bytes}. */
+    payloadMaxBytes?: number;
+};
+/**
+ * Whether `event` survives `options.name`'s glob, and truncates its payload to `options
+ * .payloadMaxBytes` when given — the one implementation `since()`'s drain and `daemon.ts`'s
+ * `events.subscribe` fan-out both call, so the two can't drift apart (issue #112, #113). Returns
+ * `event` (unchanged, or with its payload replaced by a preview) when it should be kept,
+ * `undefined` when it should be dropped.
+ *
+ * Only an `app_event` carries a `name`/`payload` to filter or truncate, so every other kind passes
+ * through unfiltered and untouched regardless of either option — the `kinds` filter
+ * (`events.subscribe`) is what narrows those.
+ */
+export declare const projectAppEvent: (event: EventNotification, options?: ProjectAppEventOptions) => EventNotification | undefined;
 export type EventsSinceQuery = {
     since?: number;
-    kinds?: EventKind[];
     limit?: number;
+    /** Whole-name, case-sensitive glob (issue #112): `*` matches any run of characters, a pattern
+     * with no `*` is an exact name. See {@link projectAppEvent}. */
+    name?: string;
+    /** Caps a returned `app_event`'s payload to this many UTF-8 bytes of its JSON (issue #113);
+     * applied to the page actually returned, after `name`/`limit`, via {@link projectAppEvent}. */
+    payloadMaxBytes?: number;
 };
 export type EventsSinceQueryResult = {
     events: EventNotification[];
     cursor: number;
+    /** How many app events after `since` were evicted before this call could return them (issue
+     * #113): `max(0, oldest.seq - since - 1)`, `oldest` being the buffer's current oldest retained
+     * entry. `0` once nothing has fallen off, and `since` defaults to `0` when omitted. */
+    dropped: number;
+    /** How many events still match `since`/`name` after the returned (possibly `limit`-truncated)
+     * page. `0` on the last page. */
+    remaining: number;
 };
 export type EventBus = {
     emit: (event: EventBusEmitInput) => void;

package/dist/daemon/events-log.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The daemon's own event log, `<stateDir>/events.log` (ARCHITECTURE.md §3): one JSON line per
+ * event, for debugging Appduct itself. The daemon decides which events to record; this module only
+ * writes them and keeps the file bounded.
+ *
+ * Writes are serialized on a promise queue, so {@link EventsLog.record} returns at once and never
+ * blocks the emitter. After each append the file is rotated to a single backup once it is over
+ * `maxBytes`, so the current file is never above the cap once a write has settled. A failed write
+ * or rotation is warned, never thrown, and never stops later writes.
+ */
+import type { EventNotification } from "@appduct/shared";
+/** A file that only ever grows by whole lines, with one backup slot. */
+export type AppendOnlyFile = {
+    /** Appends `line` plus a newline, creating the file at mode `0600` if it is missing. */
+    append(line: string): Promise<void>;
+    /** Current size in bytes; `0` when the file does not exist. */
+    size(): Promise<number>;
+    /** Moves the file to the backup slot, replacing any previous backup. */
+    rotate(): Promise<void>;
+};
+export type EventsLog = {
+    /** Queues `event` as one JSON line; returns immediately. */
+    record(event: EventNotification): void;
+    /** Resolves once every write queued so far has settled. */
+    flush(): Promise<void>;
+};
+export declare const createEventsLog: (options: {
+    file: AppendOnlyFile;
+    maxBytes: number;
+    warn: (message: string) => void;
+}) => EventsLog;

package/dist/daemon/memory-append-only-file.d.ts

@@ -0,0 +1,17 @@
+/** In-memory {@link AppendOnlyFile} for tests: inspect the lines written and the backup, or make
+ * appends fail. */
+import type { AppendOnlyFile } from "./events-log.js";
+export declare class MemoryAppendOnlyFile implements AppendOnlyFile {
+    private current;
+    private backup;
+    private appendError;
+    append(line: string): Promise<void>;
+    size(): Promise<number>;
+    rotate(): Promise<void>;
+    /** Lines in the current file, without their newlines. */
+    lines(): string[];
+    /** Lines in the backup, without their newlines. */
+    backupLines(): string[];
+    /** Makes every append throw `error` until called again with `undefined`. */
+    failAppendsWith(error: Error | undefined): void;
+}

package/dist/daemon/node-append-only-file.d.ts

@@ -0,0 +1,9 @@
+/** {@link AppendOnlyFile} on the real filesystem; the backup is `<path>.1`. */
+import type { AppendOnlyFile } from "./events-log.js";
+export declare class NodeAppendOnlyFile implements AppendOnlyFile {
+    private readonly path;
+    constructor(path: string);
+    append(line: string): Promise<void>;
+    size(): Promise<number>;
+    rotate(): Promise<void>;
+}

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 {

package/dist/daemon/state-dir.d.ts

@@ -11,6 +11,8 @@ export type StateDirPaths = {
     socketPath: string;
     pidFilePath: string;
     logFilePath: string;
+    /** The daemon's own event log; rotated to `<eventsLogPath>.1`. */
+    eventsLogPath: string;
     keyPath: string;
     configPath: string;
     auditDir: string;

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]", "Stream the app's events, or replay them since a cursor: tail or since.").usage("events <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).'
+  ).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 session/tool events until interrupted.").option("--follow", "Accepted for script readability; the default behavior already follows.").option("--since <cursor>", "One-shot: print 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)."
@@ -164,6 +167,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "eventBufferSize",
   "auditRetentionDays",
   "daemonLogMaxBytes",
+  "eventsLogMaxBytes",
   "policy",
   "advertisedIp",
   "scheme",
@@ -223,6 +227,7 @@ var defaultConfig = (paths) => {
     eventBufferSize: 256,
     auditRetentionDays: DEFAULT_AUDIT_RETENTION_DAYS,
     daemonLogMaxBytes: DEFAULT_DAEMON_LOG_MAX_BYTES,
+    eventsLogMaxBytes: 10 * 1024 * 1024,
     restartDaemonOnVersionMismatch: false,
     policy: {
       default: "allow",
@@ -285,6 +290,9 @@ var loadConfig = async (paths, options = {}) => {
   if (parsed.daemonLogMaxBytes !== void 0) {
     config.daemonLogMaxBytes = requirePositiveInteger(parsed.daemonLogMaxBytes, "daemonLogMaxBytes");
   }
+  if (parsed.eventsLogMaxBytes !== void 0) {
+    config.eventsLogMaxBytes = requirePositiveInteger(parsed.eventsLogMaxBytes, "eventsLogMaxBytes");
+  }
   if (parsed.restartDaemonOnVersionMismatch !== void 0) {
     config.restartDaemonOnVersionMismatch = requireBoolean(
       parsed.restartDaemonOnVersionMismatch,
@@ -333,6 +341,7 @@ var getStateDirPaths = (stateDir) => {
     socketPath: join3(stateDir, "daemon.sock"),
     pidFilePath: join3(stateDir, "daemon.pid"),
     logFilePath: join3(stateDir, "daemon.log"),
+    eventsLogPath: join3(stateDir, "events.log"),
     keyPath: join3(stateDir, "key.pem"),
     configPath: join3(stateDir, "config.json"),
     auditDir: join3(stateDir, "audit"),
@@ -654,9 +663,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);
 };
@@ -674,7 +680,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)}.`;
 };
@@ -756,7 +762,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) => {
@@ -808,16 +814,13 @@ 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 renderInvokeData = (colors, data, flags) => {
@@ -1003,15 +1006,17 @@ 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 "tools call":
       return renderInvokeData(colors, data, flags);
-    case "revoke":
+    case "sessions revoke":
       return renderRevokeData(colors, data);
     case "daemon run":
       return renderDaemonRunData(colors, data, flags);
@@ -1081,12 +1086,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
@@ -1183,21 +1197,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 = {
@@ -1236,7 +1259,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.
  *

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,19 +4,12 @@
  * 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 EVENTS_TOOL_NAME = "appduct_events";
@@ -38,17 +31,17 @@ export declare const EVENTS_TOOL_DESCRIPTOR: {
                 readonly type: "integer";
                 readonly minimum: 0;
             };
-            readonly kinds: {
-                readonly type: "array";
-                readonly items: {
-                    readonly type: "string";
-                    readonly enum: readonly ["daemon_started", "link_created", "link_expired", "session_claimed", "session_suspended", "session_resumed", "session_revoked", "session_expired", "tools_changed", "app_event", "tool_call_started", "tool_call_progress", "tool_call_finished"];
-                };
-            };
             readonly limit: {
                 readonly type: "integer";
                 readonly exclusiveMinimum: 0;
             };
+            readonly name: {
+                readonly type: "string";
+            };
+            readonly payloadMaxBytes: {
+                readonly type: "integer";
+                readonly exclusiveMinimum: 0;
+            };
         };
         readonly additionalProperties: false;
     };
@@ -65,12 +58,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;
@@ -79,6 +66,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;
@@ -87,7 +78,13 @@ export declare const WAIT_FOR_EVENT_TOOL_DESCRIPTOR: {
 export type EventsToolDeps = {
     call: DaemonCall;
 };
-export declare const handleEventsTool: (rawArgs: unknown, deps: EventsToolDeps) => Promise<EventsSinceResult>;
+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;
@@ -98,13 +95,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 = {

package/dist/output.d.ts

@@ -8,18 +8,41 @@ export type RenderOptions = {
      * (which is only attached under `--verbose`). Defaults to the wall clock when omitted, matching
      * the pre-`--verbose` fallback behavior for a caller that doesn't care (e.g. non-`ls` tests). */
     now?: Date;
-    /** `link`-only: also render the deep link as terminal QR art (never affects `--json` output). */
+    /** `sessions link`-only: also render the deep link as terminal QR art (never affects `--json`
+     * output). */
     qr?: boolean;
-    /** `tools`-only: render full schemas/annotations for every listed tool, not just name+description. */
+    /** `tools ls`-only: render full schemas/annotations for every listed tool, not just
+     * name+description. */
     full?: boolean;
 };
 export declare const renderResult: (result: CliResult<unknown>, options: RenderOptions) => {
     stdout?: string;
     stderr?: string;
 };
-/** Renders one `appduct events` line: NDJSON under `--json`, a compact human line otherwise. */
+/** Renders one `appduct events tail`/`appduct events since` line: NDJSON under `--json`, a
+ * compact human line otherwise. */
 export declare const renderEventLine: (event: EventNotification, flags: GlobalFlags) => string;
-/** Renders the trailing cursor line for `appduct events --since` (issue #6): NDJSON under
+/** The filter flags to echo back into the hinted resume command in {@link renderEventsCursorLine}
+ * (issue #115's should-fix on #96's echoed selector): the same `--name`/`--payload-max-bytes`
+ * the caller passed to this pull, forwarded as-is so following the hint doesn't silently widen
+ * the query. */
+export type EventsCursorLineFilters = {
+    name?: string;
+    payloadMaxBytes?: number;
+};
+/** 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 declare const renderEventsCursorLine: (cursor: number, flags: GlobalFlags) => string;
+ * events (impossible when the response is empty), a human note otherwise. `selector` is the
+ * device/session selector the caller passed (issue #96): with two devices connected, a resume
+ * hint that dropped it would resolve to `ambiguous_session`, so it is echoed back in the hinted
+ * command when present. `dropped`/`remaining` (issue #115) are carried straight from
+ * `events.since`'s own result: how many events fell off the retention buffer before this pull,
+ * and how many matching events are still waiting beyond this page. `filters` (issue #115) are the
+ * `--name`/`--payload-max-bytes` flags this pull used: without them the hint would silently drop
+ * the query's filter and cap, so they are echoed into the hinted command exactly like the
+ * selector (`--name`'s glob is shell-quoted since it can carry `*` or spaces). */
+export declare const renderEventsCursorLine: (cursor: {
+    cursor: number;
+    dropped: number;
+    remaining: number;
+}, flags: GlobalFlags, selector?: string, filters?: EventsCursorLineFilters) => string;