appduct 0.12.0 → 0.13.0

package/dist/client/index.js

@@ -1,5 +1,5 @@
 // src/client/connect.ts
-import { RPC_METHODS as RPC_METHODS3 } from "@appduct/shared";
+import { RPC_METHODS as RPC_METHODS4 } from "@appduct/shared";
 
 // src/daemon/state-dir.ts
 import { homedir } from "node:os";
@@ -1029,9 +1029,109 @@ var openDaemonStream = async (options) => {
 import {
   clampToolTimeoutMs,
   MAX_TOOL_TIMEOUT_MS,
-  RPC_METHODS as RPC_METHODS2
+  RPC_METHODS as RPC_METHODS3,
+  toAppEvent as toAppEvent2
 } from "@appduct/shared";
 
+// src/events/index.ts
+import {
+  RPC_METHODS as RPC_METHODS2,
+  toAppEvent
+} from "@appduct/shared";
+var WaitForAppEventTimeoutError = class extends Error {
+  constructor(eventName, timeoutMs) {
+    super(`Timed out after ${timeoutMs}ms waiting for event "${eventName}".`);
+    this.eventName = eventName;
+    this.timeoutMs = timeoutMs;
+    this.name = "WaitForAppEventTimeoutError";
+  }
+};
+var WaitForAppEventConnectionClosedError = class extends Error {
+  constructor(eventName) {
+    super(`The connection to the Appduct daemon closed while waiting for event "${eventName}".`);
+    this.eventName = eventName;
+    this.name = "WaitForAppEventConnectionClosedError";
+  }
+};
+var waitForAppEvent = async (stream, options) => {
+  const { sessionId, name, since, timeoutMs, payloadMaxBytes } = options;
+  let liveHandler = null;
+  const earlyEvents = [];
+  const unsubscribeNotification = stream.onNotification((payload) => {
+    const event = payload;
+    if (liveHandler) {
+      liveHandler(event);
+    } else {
+      earlyEvents.push(event);
+    }
+  });
+  let unsubscribeClose = () => {
+  };
+  try {
+    await stream.call(RPC_METHODS2.eventsSubscribe, {
+      sessionSelector: sessionId,
+      kinds: ["app_event"],
+      name,
+      payloadMaxBytes
+    });
+    const sinceResult = await stream.call(RPC_METHODS2.eventsSince, {
+      selector: sessionId,
+      since,
+      name,
+      payloadMaxBytes
+    });
+    const seenSeqs = /* @__PURE__ */ new Set();
+    const backlog = [];
+    for (const event of [...sinceResult.events, ...earlyEvents]) {
+      if (event.sessionId === sessionId && !seenSeqs.has(event.seq)) {
+        seenSeqs.add(event.seq);
+        backlog.push(event);
+      }
+    }
+    backlog.sort((a, b) => a.seq - b.seq);
+    for (const event of backlog) {
+      const appEvent = toAppEvent(event, sessionId);
+      if (appEvent) {
+        return { event: appEvent, dropped: sinceResult.dropped };
+      }
+    }
+    const highestConsideredSeq = backlog.length > 0 ? backlog[backlog.length - 1].seq : sinceResult.cursor;
+    return await new Promise((resolve2, reject) => {
+      let settled = false;
+      const settle = (fn) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        liveHandler = null;
+        fn();
+      };
+      const timer = setTimeout(() => {
+        settle(() => reject(new WaitForAppEventTimeoutError(name, timeoutMs)));
+      }, timeoutMs);
+      unsubscribeClose = stream.onClose(() => {
+        settle(() => reject(new WaitForAppEventConnectionClosedError(name)));
+      });
+      liveHandler = (event) => {
+        if (settled) {
+          return;
+        }
+        if (event.sessionId === sessionId && event.seq <= highestConsideredSeq) {
+          return;
+        }
+        const appEvent = toAppEvent(event, sessionId);
+        if (appEvent) {
+          settle(() => resolve2({ event: appEvent, dropped: sinceResult.dropped }));
+        }
+      };
+    });
+  } finally {
+    unsubscribeNotification();
+    unsubscribeClose();
+  }
+};
+
 // src/errors.ts
 var AppductCliError = class extends Error {
   type;
@@ -1103,12 +1203,14 @@ var transportTimeoutForToolCall = (timeoutMs) => {
   const clamped = timeoutMs === void 0 || !Number.isFinite(timeoutMs) ? MAX_TOOL_TIMEOUT_MS : clampToolTimeoutMs(timeoutMs);
   return clamped + CALL_TRANSPORT_TIMEOUT_SLACK_MS;
 };
-var makeAppClient = (stream, sessionId) => {
+var makeAppClient = (stream, sessionId, openStream) => {
+  let closed = false;
+  const openWaitStreams = /* @__PURE__ */ new Set();
   const client = {
     sessionId,
     tools: async () => {
       try {
-        const result = await stream.call(RPC_METHODS2.toolsList, {
+        const result = await stream.call(RPC_METHODS3.toolsList, {
           selector: sessionId
         });
         const entries = Array.isArray(result) ? result : result.tools;
@@ -1120,7 +1222,7 @@ var makeAppClient = (stream, sessionId) => {
     call: async (name, args, options) => {
       try {
         const result = await stream.call(
-          RPC_METHODS2.toolsCall,
+          RPC_METHODS3.toolsCall,
           {
             selector: sessionId,
             name,
@@ -1135,151 +1237,82 @@ var makeAppClient = (stream, sessionId) => {
         throw toAppductError(error);
       }
     },
+    // A single implementation backs both of the public type's overloaded signatures — `makeAppClient`
+    // returns `client as unknown as AppClient<TTools>` below, so nothing here has to structurally
+    // satisfy either signature on its own; the overloads are strictly a compile-time view for callers.
     events: async (options = {}) => {
       try {
-        const result = await stream.call(RPC_METHODS2.eventsSince, {
+        const result = await stream.call(RPC_METHODS3.eventsSince, {
           selector: sessionId,
           since: options.since,
-          limit: options.limit
+          limit: options.limit,
+          payloadMaxBytes: options.payloadMaxBytes
         });
         return {
-          events: result.events.map((event) => appEventFrom(event, sessionId)).filter((event) => event !== void 0),
-          cursor: result.cursor
+          events: result.events.map((event) => toAppEvent2(event, sessionId)).filter((event) => event !== void 0),
+          cursor: result.cursor,
+          dropped: result.dropped,
+          remaining: result.remaining
         };
       } catch (error) {
         throw toAppductError(error);
       }
     },
-    waitForEvent: (name, options = {}) => {
+    waitForEvent: async (name, options = {}) => {
+      if (closed) {
+        throw new AppductError(
+          "connection_error",
+          `Cannot wait for event "${name}": this AppClient (session "${sessionId}") is closed.`
+        );
+      }
       const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS;
-      const toMatch = (event) => {
-        const appEvent = appEventFrom(event, sessionId);
-        if (!appEvent || appEvent.name !== name) {
-          return void 0;
+      let waitStream;
+      try {
+        waitStream = await openStream();
+      } catch (error) {
+        throw toAppductError(error);
+      }
+      if (closed) {
+        waitStream.close();
+        throw new AppductError(
+          "connection_error",
+          `Cannot wait for event "${name}": this AppClient (session "${sessionId}") is closed.`
+        );
+      }
+      openWaitStreams.add(waitStream);
+      try {
+        const { event } = await waitForAppEvent(waitStream, {
+          sessionId,
+          name,
+          since: options.since,
+          timeoutMs,
+          payloadMaxBytes: options.payloadMaxBytes
+        });
+        return event;
+      } catch (error) {
+        if (error instanceof WaitForAppEventTimeoutError) {
+          throw new AppductError("timeout", error.message);
         }
-        if (options.match && !options.match(appEvent.payload)) {
-          return void 0;
+        if (error instanceof WaitForAppEventConnectionClosedError) {
+          throw new AppductError("connection_error", error.message);
         }
-        return appEvent;
-      };
-      return new Promise((resolve2, reject) => {
-        let settled = false;
-        const settle = (fn) => {
-          if (settled) {
-            return;
-          }
-          settled = true;
-          clearTimeout(timer);
-          unsubscribeClose();
-          liveHandler = null;
-          fn();
-        };
-        const timer = setTimeout(() => {
-          settle(
-            () => reject(new AppductError("timeout", `Timed out after ${timeoutMs}ms waiting for event "${name}".`))
-          );
-        }, timeoutMs);
-        let liveHandler = null;
-        const earlyEvents = [];
-        const unsubscribeNotification = stream.onNotification((payload) => {
-          const event = payload;
-          if (liveHandler) {
-            liveHandler(event);
-          } else {
-            earlyEvents.push(event);
-          }
-        });
-        let unsubscribeClose = () => {
-        };
-        const fail = (error) => {
-          settle(() => reject(toAppductError(error)));
-          unsubscribeNotification();
-        };
-        (async () => {
-          await stream.call(RPC_METHODS2.eventsSubscribe, { sessionSelector: sessionId, kinds: ["app_event"] });
-          const sinceResult = await stream.call(RPC_METHODS2.eventsSince, {
-            selector: sessionId,
-            since: options.since
-          });
-          const seenSeqs = /* @__PURE__ */ new Set();
-          const backlog = [];
-          for (const event of [...sinceResult.events, ...earlyEvents]) {
-            if (event.sessionId === sessionId && !seenSeqs.has(event.seq)) {
-              seenSeqs.add(event.seq);
-              backlog.push(event);
-            }
-          }
-          backlog.sort((a, b) => a.seq - b.seq);
-          for (const event of backlog) {
-            try {
-              const matched = toMatch(event);
-              if (matched) {
-                settle(() => resolve2(matched));
-                unsubscribeNotification();
-                return;
-              }
-            } catch (error) {
-              fail(error);
-              return;
-            }
-          }
-          const highestConsideredSeq = backlog.length > 0 ? backlog[backlog.length - 1].seq : sinceResult.cursor;
-          unsubscribeClose = stream.onClose(() => {
-            settle(
-              () => reject(
-                new AppductError(
-                  "connection_error",
-                  `The connection to the Appduct daemon closed while waiting for event "${name}".`
-                )
-              )
-            );
-            unsubscribeNotification();
-          });
-          liveHandler = (event) => {
-            if (settled) {
-              return;
-            }
-            if (event.sessionId === sessionId && event.seq <= highestConsideredSeq) {
-              return;
-            }
-            try {
-              const matched = toMatch(event);
-              if (matched) {
-                settle(() => resolve2(matched));
-                unsubscribeNotification();
-              }
-            } catch (error) {
-              fail(error);
-            }
-          };
-        })().catch((error) => {
-          fail(error);
-        });
-      });
+        throw toAppductError(error);
+      } finally {
+        openWaitStreams.delete(waitStream);
+        waitStream.close();
+      }
     },
     close: () => {
+      closed = true;
+      for (const waitStream of openWaitStreams) {
+        waitStream.close();
+      }
+      openWaitStreams.clear();
       stream.close();
     }
   };
   return client;
 };
-var appEventFrom = (event, sessionId) => {
-  if (event.kind !== "app_event" || event.sessionId !== sessionId) {
-    return void 0;
-  }
-  const data = event.data;
-  if (typeof data.name !== "string") {
-    return void 0;
-  }
-  return {
-    name: data.name,
-    payload: data.payload,
-    ts: event.ts,
-    sessionId: event.sessionId,
-    alias: event.alias,
-    seq: event.seq
-  };
-};
 
 // src/client/connect.ts
 var connect3 = async (options = {}) => {
@@ -1296,10 +1329,16 @@ var connect3 = async (options = {}) => {
     throw toAppductError(error);
   }
   try {
-    const detail = await stream.call(RPC_METHODS3.sessionsDescribe, {
+    const detail = await stream.call(RPC_METHODS4.sessionsDescribe, {
       selector: options.selector
     });
-    return makeAppClient(stream, detail.sessionId);
+    const openStream = () => openDaemonStream({
+      stateDir,
+      spawn: options.spawn,
+      autoSpawn: options.autoSpawn,
+      requestTimeoutMs: options.requestTimeoutMs
+    });
+    return makeAppClient(stream, detail.sessionId, openStream);
   } catch (error) {
     stream.close();
     throw toAppductError(error);
@@ -1307,7 +1346,7 @@ var connect3 = async (options = {}) => {
 };
 
 // src/client/bootstrap.ts
-import { RPC_METHODS as RPC_METHODS5 } from "@appduct/shared";
+import { RPC_METHODS as RPC_METHODS6 } from "@appduct/shared";
 
 // src/cli/open-target.ts
 import { execFile } from "node:child_process";
@@ -1604,7 +1643,7 @@ var deliverToOpenTarget = async (options) => {
 };
 
 // src/link.ts
-import { RPC_METHODS as RPC_METHODS4 } from "@appduct/shared";
+import { RPC_METHODS as RPC_METHODS5 } from "@appduct/shared";
 
 // src/scheme.ts
 import { existsSync as existsSync2 } from "node:fs";
@@ -2252,7 +2291,7 @@ var mintLink = async (options) => {
     throw usageError(invalidAppIdMessage(appId));
   }
   const result = await callDaemon(
-    RPC_METHODS4.linkCreate,
+    RPC_METHODS5.linkCreate,
     {
       ttlSeconds: options.ttlSeconds,
       addressOverride: options.target && usesLoopbackAddress(options.target) ? OPEN_TARGET_ADDRESS_OVERRIDE : void 0
@@ -2325,10 +2364,11 @@ var waitForSession = async (sessionId, options = {}) => {
   } catch (error) {
     throw toAppductError(error);
   }
+  const openStream = () => openDaemonStream({ stateDir, spawn: options.spawn, autoSpawn: options.autoSpawn });
   try {
     try {
-      await stream.call(RPC_METHODS5.sessionsDescribe, { selector: sessionId });
-      return makeAppClient(stream, sessionId);
+      await stream.call(RPC_METHODS6.sessionsDescribe, { selector: sessionId });
+      return makeAppClient(stream, sessionId, openStream);
     } catch (error) {
       if (!(error instanceof DaemonRpcError) || error.data?.type !== "unknown_session") {
         throw error;
@@ -2375,11 +2415,11 @@ var waitForSession = async (sessionId, options = {}) => {
           settle(resolve2);
         }
       });
-      stream.call(RPC_METHODS5.eventsSubscribe, { sessionSelector: sessionId, kinds: ["session_claimed"] }).catch((error) => {
+      stream.call(RPC_METHODS6.eventsSubscribe, { sessionSelector: sessionId, kinds: ["session_claimed"] }).catch((error) => {
         settle(() => reject(toAppductError(error)));
       });
     });
-    return makeAppClient(stream, sessionId);
+    return makeAppClient(stream, sessionId, openStream);
   } catch (error) {
     stream.close();
     throw toAppductError(error);

package/dist/commands/events.d.ts

@@ -1,15 +1,17 @@
 /**
- * `appduct events` (ARCHITECTURE.md §10): subscribes to `events.subscribe` for `app_event` only
- * over a persistent connection and streams the app's own events until interrupted (Ctrl-C) or the
- * connection drops. Appduct's lifecycle and tool-call kinds are not printed (issue #98). This is
- * the one command whose output isn't a single rendered `CliResult` — each event is written as it
- * arrives (NDJSON under `--json`, a human line otherwise) — so it plugs into `executeHostedCommand`
- * with a live reporter that suppresses the default one-shot bootstrap render (`cli/runner.ts`).
+ * `appduct events tail` (ARCHITECTURE.md §10): subscribes to `events.subscribe` for `app_event`
+ * only over a persistent connection and streams the app's own events until interrupted (Ctrl-C) or
+ * the connection drops. Appduct's lifecycle and tool-call kinds are not printed (issue #98). This
+ * is the one command whose output isn't a single rendered `CliResult` — each event is written as
+ * it arrives (NDJSON under `--json`, a human line otherwise) — so it plugs into
+ * `executeHostedCommand` with a live reporter that suppresses the default one-shot bootstrap
+ * render (`cli/runner.ts`).
  *
- * `--since <cursor>` (issue #6) switches to a one-shot mode: a single `events.since` pull instead
- * of a live subscription. It falls out of the same `EventsHostedResult` shape (each retained event
- * is written through `onEvent` exactly like a live one) so the CLI plumbing needs no forking — the
- * "hosted command" here just completes immediately instead of running until interrupted.
+ * `appduct events since <cursor>` (issue #6) is a one-shot mode: a single `events.since` pull
+ * instead of a live subscription, selected here by `since !== undefined`. It falls out of the same
+ * `EventsHostedResult` shape (each retained event is written through `onEvent` exactly like a live
+ * one) so the CLI plumbing needs no forking — the "hosted command" here just completes immediately
+ * instead of running until interrupted.
  */
 import { type EventNotification } from "@appduct/shared";
 import type { CliResult } from "../cli/result-types.js";
@@ -19,15 +21,30 @@ export type EventsCommandOptions = {
     /** Exclusive lower bound on `EventNotification.seq`; switches this command to a one-shot
      * `events.since` pull instead of a live `events.subscribe` stream. */
     since?: number;
+    /** Whole-name, case-sensitive glob (issue #115), forwarded to `events.subscribe`/`events.since`.
+     * No default — everything is delivered unfiltered unless asked. */
+    name?: string;
+    /** Caps an `app_event`'s payload to this many UTF-8 bytes of its JSON (issue #115), forwarded to
+     * `events.subscribe`/`events.since`. No default — nothing is truncated unless asked. */
+    payloadMaxBytes?: number;
+};
+/** `events since` mode's resulting cursor, plus how far behind or ahead of the full picture it
+ * is (issue #115): `dropped` events fell off the retention buffer before this pull, `remaining`
+ * matching events are still waiting beyond this page. */
+export type EventsSinceCursor = {
+    cursor: number;
+    dropped: number;
+    remaining: number;
 };
 export type EventsCommandContext = {
     stateDir: string;
     spawn?: SpawnFn;
     onEvent: (event: EventNotification) => void;
-    /** `--since` mode only: called once with the pull's resulting cursor, so a scripted caller
-     * doesn't have to reconstruct it by maxing `seq` over the printed lines (impossible when the
-     * response is empty — the whole point of a cursor is knowing where to resume from either way). */
-    onCursor?: (cursor: number) => void;
+    /** `events since` mode only: called once with the pull's resulting cursor (plus `dropped`/
+     * `remaining`), so a scripted caller doesn't have to reconstruct it by maxing `seq` over the
+     * printed lines (impossible when the response is empty — the whole point of a cursor is
+     * knowing where to resume from either way). */
+    onCursor?: (cursor: EventsSinceCursor) => void;
 };
 export type EventsHostedResult = {
     result: CliResult<never>;

package/dist/commands/invoke.d.ts

@@ -1,5 +1,5 @@
 /**
- * `appduct invoke` (ARCHITECTURE.md §10): `tools.call` round trip. Failures propagate as-is
+ * `appduct tools call` (ARCHITECTURE.md §10): `tools.call` round trip. Failures propagate as-is
  * (`DaemonRpcError`, preserving `error.data.type` verbatim) — `errors.ts`'s `toCliError` is what
  * renders `error.type` as the app's wire error type end-to-end, not this module's job.
  */

package/dist/commands/link.d.ts

@@ -1,5 +1,5 @@
 /**
- * `appduct link` (ARCHITECTURE.md §10, §8): CLI-flag validation (`--open`/`--device`'s
+ * `appduct sessions link` (ARCHITECTURE.md §10, §8): CLI-flag validation (`--open`/`--device`'s
  * CLI-specific error wording) around the shared `mintLink` core (`../link.ts`), which both this
  * command and `appduct/client`'s `link()` use so the deep-link shape can't drift between them.
  */

package/dist/commands/ls.d.ts

@@ -1,4 +1,4 @@
-/** `appduct ls` (ARCHITECTURE.md §10): `sessions.list` passthrough. */
+/** `appduct sessions ls` (ARCHITECTURE.md §10): `sessions.list` passthrough. */
 import type { CliResult, LsCommandData } from "../cli/result-types.js";
 import { type SpawnFn } from "../rpc/client.js";
 export type LsCommandContext = {

package/dist/commands/revoke.d.ts

@@ -1,4 +1,4 @@
-/** `appduct revoke` (ARCHITECTURE.md §10): revokes a session, optionally by selector. */
+/** `appduct sessions revoke` (ARCHITECTURE.md §10): revokes a session, optionally by selector. */
 import type { CliResult, RevokeCommandData } from "../cli/result-types.js";
 import { type SpawnFn } from "../rpc/client.js";
 export type RevokeCommandOptions = {

package/dist/commands/tools.d.ts

@@ -1,19 +1,18 @@
 /**
- * `appduct tools` (ARCHITECTURE.md §10): `tools [selector] [--full] [--group <name>] [--filter
- * <text>] [--limit <n>] [--offset <n>]` lists tools for a session; `tools [selector] --groups`
- * lists only the session's groups with their tool counts; `tools [selector] <name>` shows one
- * tool's full schema/annotations.
+ * `appduct tools ls`/`appduct tools describe` (ARCHITECTURE.md §10, issue #96): `ls [selector]
+ * [--full] [--group <name>] [--filter <text>] [--limit <n>] [--offset <n>]` lists tools for a
+ * session; `ls [selector] --groups` lists only the session's groups with their tool counts;
+ * `describe [selector] <name>` shows one tool's full schema/annotations.
  *
- * The command table gives both forms a leading optional `[selector]`, which makes a single
- * positional argument inherently ambiguous (is it the selector, or the tool name in `tools <name>`
- * with the selector omitted?). This resolves it the same way a human reading the table would:
- * first try the arg as a tool name in the implicit-selector session's registry; if no such tool
- * exists there (or the implicit selector doesn't resolve, e.g. `ambiguous_session`), fall back to
- * treating it as a selector and list that session's tools instead.
+ * The two verbs (`cli/routes/tools/ls.ts` and `cli/routes/tools/describe.ts`) split `[selector]`
+ * from `<name>` unambiguously before this handler ever runs — `describe`'s `<name>` is always the
+ * last positional, required, never a candidate selector — so there is no probing here: a listing
+ * request (`options.name === undefined`) always lists, a lookup (`options.name !== undefined`)
+ * always looks up, on the given selector or the implicit session if none was given.
  *
- * `--group`/`--filter`/`--limit`/`--offset` only ever reach the daemon on a *listing* request: the detail
- * path (an explicit `<name>`, or the ambiguous single-arg probe above) always asks for the whole,
- * unpaged registry, so a name lookup can never miss a tool that paging would have left off a page.
+ * `--group`/`--filter`/`--limit`/`--offset` only ever reach the daemon on a *listing* request: the
+ * detail path always asks for the whole, unpaged registry, so a name lookup can never miss a tool
+ * that paging would have left off a page.
  */
 import type { CliResult, ToolsCommandData } from "../cli/result-types.js";
 import { type SpawnFn } from "../rpc/client.js";

package/dist/daemon/config.d.ts

@@ -57,7 +57,7 @@ export type AppductConfig = {
     /** Operator override for advertised-address detection (daemon/address.ts); undefined = auto-detect. */
     advertisedIp?: string;
     /**
-     * Deep-link URI scheme used to compose `appduct link`'s output (ARCHITECTURE.md §10: "taken
+     * Deep-link URI scheme used to compose `appduct sessions link`'s output (ARCHITECTURE.md §10: "taken
      * from the flag, else `config.json`, else the CLI errors with a clear message"). Not part of the
      * `config.json` shape enumerated in ARCHITECTURE.md §3 (which only covers daemon-side settings),
      * but `config.json` is explicitly "all fields optional" there and this is the natural home for a

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

@@ -21,13 +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;
     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/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/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;