appduct 0.12.0 → 0.13.0

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 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)."
@@ -660,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);
 };
@@ -680,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)}.`;
 };
@@ -762,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) => {
@@ -814,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) => {
@@ -1009,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);
@@ -1087,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
@@ -1189,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 = {
@@ -1242,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";
@@ -42,6 +35,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 +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;
@@ -72,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;
@@ -80,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;
@@ -91,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;

package/dist/rpc/client.d.ts

@@ -123,7 +123,7 @@ export type DaemonStream = {
     /** Subscribes to server→client `"event"` notifications; returns an unsubscribe function. */
     onNotification: (callback: (payload: unknown) => void) => () => void;
     /** Fires once when the underlying socket closes (daemon gone, stop(), etc.); returns an
-     * unsubscribe function. Lets long-lived stream consumers (e.g. `appduct events`) end
+     * unsubscribe function. Lets long-lived stream consumers (e.g. `appduct events tail`) end
      * gracefully instead of hanging once the connection is no longer usable. */
     onClose: (callback: () => void) => () => void;
     close: () => void;

package/dist/scheme.d.ts

@@ -1,7 +1,7 @@
 /**
  * Deep-link scheme resolution (ARCHITECTURE.md §10, issue #29).
  *
- * A scheme is needed to compose `<scheme>:///?appduct=<payload>` in `appduct link`,
+ * A scheme is needed to compose `<scheme>:///?appduct=<payload>` in `appduct sessions link`,
  * `appduct/client`'s `link()` and the MCP `appduct_connect` tool. Before this module the only
  * source was `<state-dir>/config.json` — a single global file, which meant two apps with different
  * schemes on one machine required hand-editing it on every switch.
@@ -126,7 +126,7 @@ export declare const globalConfigDirs: (options?: ProjectConfigLookupOptions) =>
  * documented precedence:
  *
  * - `<homeDir>/.appduct`, the default state dir. Essentially every project lives somewhere under
- *   the home directory, so without this a plain `appduct link` in any repo would pick up the
+ *   the home directory, so without this a plain `appduct sessions link` in any repo would pick up the
  *   global `config.json` as if it were the project's — and with `--state-dir` pointing elsewhere it
  *   would shadow the state dir the operator explicitly chose.
  * - `stateDirRoot`, the state dir actually in use, for the same reason when it is not the default.
@@ -191,7 +191,7 @@ export type ResolveSchemeOptions = {
 export declare const resolveScheme: (options?: ResolveSchemeOptions) => Promise<ResolvedScheme>;
 /**
  * The shared "no scheme anywhere" message. Every caller renders the same body so the locations
- * listed (and the fixes suggested) can't drift between `appduct link`, `appduct mcp` and
+ * listed (and the fixes suggested) can't drift between `appduct sessions link`, `appduct mcp` and
  * `appduct_connect`.
  */
 export declare const describeMissingScheme: (tried: string[]) => string;
@@ -210,7 +210,7 @@ export type ResolveAppIdOptions = {
     /** Which `appId.<platform>` key to read from a project config; see `cli/open-target.ts`'s
      * `platformOf`. */
     platform: AppIdPlatform;
-    /** `--app-id` (CLI `link`) / `appId` (MCP `appduct_connect`) / `appId` (`mintLink`, the
+    /** `--app-id` (CLI `sessions link`) / `appId` (MCP `appduct_connect`) / `appId` (`mintLink`, the
      * `appduct/client` `link()`) — highest precedence, because the target is known at the call
      * site. */
     flagAppId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appduct",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Driving React Native tools without in-app debug UI.",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,7 +45,7 @@
     "reflect-metadata": "^0.2.2",
     "toqr": "^0.1.1",
     "ws": "^8.18.3",
-    "@appduct/shared": "0.12.0"
+    "@appduct/shared": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/dist/cli/routes/events.d.ts

@@ -1,3 +0,0 @@
-/** Route for `appduct events` — loaded by `cli/dispatch.ts`'s router only when it runs. */
-import type { Route } from "../router.js";
-export declare const route: Route;

package/dist/cli/routes/invoke.d.ts

@@ -1,3 +0,0 @@
-/** Route for `appduct invoke` — loaded by `cli/dispatch.ts`'s router only when it runs. */
-import type { Route } from "../router.js";
-export declare const route: Route;

package/dist/cli/routes/link.d.ts

@@ -1,3 +0,0 @@
-/** Route for `appduct link` — loaded by `cli/dispatch.ts`'s router only when it runs. */
-import type { Route } from "../router.js";
-export declare const route: Route;

package/dist/cli/routes/ls.d.ts

@@ -1,3 +0,0 @@
-/** Route for `appduct ls` — loaded by `cli/dispatch.ts`'s router only when it runs. */
-import type { Route } from "../router.js";
-export declare const route: Route;

package/dist/cli/routes/revoke.d.ts

@@ -1,3 +0,0 @@
-/** Route for `appduct revoke` — loaded by `cli/dispatch.ts`'s router only when it runs. */
-import type { Route } from "../router.js";
-export declare const route: Route;

package/dist/cli/routes/tools.d.ts

@@ -1,3 +0,0 @@
-/** Route for `appduct tools` — loaded by `cli/dispatch.ts`'s router only when it runs. */
-import type { Route } from "../router.js";
-export declare const route: Route;