appduct 0.12.0 → 0.14.0

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

@@ -0,0 +1,4 @@
+/** Route for `appduct tools ls` — loaded by `routes/tools/index.ts`'s router only when it runs
+ * (issue #96; replaces the removed `appduct tools [selector]` listing form). */
+import type { Route } from "../../router.js";
+export declare const route: Route;

package/dist/cli/routes/{tools.js → tools/ls.js}

@@ -1,6 +1,3 @@
-// src/cli/routes/tools.ts
-import { isValidToolGroup } from "@appduct/shared";
-
 // src/commands/tools.ts
 import { RPC_METHODS as RPC_METHODS2 } from "@appduct/shared";
 
@@ -1105,38 +1102,18 @@ var handleToolsCommand = async (options, context) => {
   if (options.name !== void 0 && hasListingOnlyOptions(options)) {
     throw listingOnlyError();
   }
-  if (options.selector !== void 0 && options.name !== void 0) {
+  if (options.name !== void 0) {
     const result = await listTools(options.selector, context);
     const tool = findTool(result.tools, options.name);
     if (!tool) {
       throw usageError(
-        `Tool "${options.name}" is not registered on session "${options.selector}".`,
+        options.selector !== void 0 ? `Tool "${options.name}" is not registered on session "${options.selector}".` : `Tool "${options.name}" is not registered.`,
         { available: result.tools.map((entry) => entry.name) }
       );
     }
     return { ok: true, data: tool };
   }
-  if (options.selector !== void 0) {
-    let implicitTools;
-    try {
-      implicitTools = await listTools(void 0, context);
-    } catch (error) {
-      if (!(error instanceof DaemonRpcError)) {
-        throw error;
-      }
-    }
-    if (implicitTools) {
-      const tool = findTool(implicitTools.tools, options.selector);
-      if (tool) {
-        if (hasListingOnlyOptions(options)) {
-          throw listingOnlyError();
-        }
-        return { ok: true, data: tool };
-      }
-    }
-    return { ok: true, data: await listOrGroups(options.selector, options, context) };
-  }
-  return { ok: true, data: await listOrGroups(void 0, options, context) };
+  return { ok: true, data: await listOrGroups(options.selector, options, context) };
 };
 
 // src/cli/command-options.ts
@@ -1182,17 +1159,11 @@ var readTextOption = (argv, value, flagName) => {
   }
   return raw ?? String(Array.isArray(value) ? value.at(-1) : value);
 };
-var splitOptionalSelectorAndTarget = (args, commandUsage) => {
-  if (args.length > 2) {
+var splitOptionalSelector = (args, commandUsage) => {
+  if (args.length > 1) {
     throw usageError(`Usage: ${commandUsage} (too many arguments).`);
   }
-  if (args.length === 2) {
-    return { selector: args[0], target: args[1] };
-  }
-  if (args.length === 1) {
-    return { selectorOrTarget: args[0] };
-  }
-  return {};
+  return { selector: args[0] };
 };
 
 // src/cli/global-flags.ts
@@ -1204,6 +1175,7 @@ var formatJson = (value, flags) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -1299,6 +1271,13 @@ var formatDevice = (device) => {
   const label = parts.length > 0 ? parts.join(" ") : "unknown device";
   return device.os ? `${label} (${device.os})` : label;
 };
+var SUSPEND_REASON_LABELS = {
+  app_backgrounded: "app in background",
+  connection_lost: "connection lost"
+};
+var formatSessionState = (session) => {
+  return session.suspendReason ? `${session.state} (${SUSPEND_REASON_LABELS[session.suspendReason]})` : session.state;
+};
 var renderLsData = (colors, data, now) => {
   if (data.length === 0) {
     return [colors.dim("Sessions"), "  No Appduct sessions are registered."];
@@ -1307,7 +1286,7 @@ var renderLsData = (colors, data, now) => {
   const headers = ["Alias", "State", "Device", "Tools", "Age"];
   const rows = data.map((session) => [
     session.alias,
-    session.state,
+    formatSessionState(session),
     formatDevice(session.device),
     String(session.toolCount),
     formatAge(session.claimedAt ?? session.createdAt, nowIso)
@@ -1321,9 +1300,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);
 };
@@ -1341,7 +1317,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)}.`;
 };
@@ -1423,7 +1399,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) => {
@@ -1475,18 +1451,62 @@ var renderToolGroups = (colors, data) => {
     colors.green("Groups"),
     ...data.groups.map((entry) => `  ${label(entry).padEnd(width)}  ${String(entry.total).padStart(countWidth)}`),
     "",
-    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools --group <name>` to list one group's tools." : "No tool declares a group.")
+    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools ls --group <name>` to list one group's tools." : "No tool declares a group.")
   ];
 };
-var renderToolsData = (colors, data, flags, full) => {
+var renderToolsListData = (colors, data, flags, full) => {
   if (isToolGroupsListing(data)) {
     return renderToolGroups(colors, data);
   }
-  if (!isToolsListing(data)) {
-    return renderToolDetail(colors, data, flags);
-  }
   return full ? renderToolsFullListing(colors, data, flags) : renderToolSummaryTable(colors, data);
 };
+var renderEventsTruncationLine = (data) => {
+  const offset = data.offset ?? 0;
+  if (data.events.length >= data.total) {
+    return [];
+  }
+  return [
+    "",
+    `Showing ${data.events.length} of ${data.total} events (offset ${offset}). Narrow with --name <glob> or page with --offset <n>.`
+  ];
+};
+var renderEventsListData = (colors, data, flags) => {
+  const [only] = data.events;
+  if (data.name !== void 0 && !data.name.includes("*") && only !== void 0) {
+    return renderFields(
+      colors.green(`Event: ${only.name}`),
+      [
+        ["Signature", renderEventSignature(only)],
+        ["Description", only.description],
+        ["Payload schema", only.payload_schema]
+      ],
+      flags
+    );
+  }
+  if (data.events.length === 0 && data.total > 0) {
+    return [
+      colors.green("Events"),
+      `  No events at offset ${data.offset ?? 0}; ${data.total} matching event${data.total === 1 ? "" : "s"} in total.`
+    ];
+  }
+  if (data.events.length === 0) {
+    return [
+      colors.green("Events"),
+      data.name === void 0 ? "  No events declared." : `  No events match ${JSON.stringify(data.name)}.`
+    ];
+  }
+  const lines = data.events.flatMap((event) => [
+    `  ${renderEventSignature(event)}`,
+    `    ${summarizeToolDescription(event.description)}`
+  ]);
+  return [
+    colors.green("Events"),
+    ...lines,
+    ...renderEventsTruncationLine(data),
+    "",
+    "Run `appduct events ls --name <name>` for an event's full payload schema."
+  ];
+};
 var renderInvokeData = (colors, data, flags) => {
   return [colors.green("Result"), formatScalar(data, flags)];
 };
@@ -1670,15 +1690,19 @@ var renderSuccessData = (colors, command, data, options) => {
       return renderInitData(colors, data, flags);
     case "keygen":
       return renderKeygenData(colors, data, flags);
-    case "link":
+    case "sessions link":
       return renderLinkData(colors, data, flags, options.qr);
-    case "ls":
+    case "sessions ls":
       return renderLsData(colors, data, options.now ?? /* @__PURE__ */ new Date());
-    case "tools":
-      return renderToolsData(colors, data, flags, options.full);
-    case "invoke":
+    case "tools ls":
+      return renderToolsListData(colors, data, flags, options.full);
+    case "tools describe":
+      return renderToolDetail(colors, data, flags);
+    case "events ls":
+      return renderEventsListData(colors, data, flags);
+    case "tools call":
       return renderInvokeData(colors, data, flags);
-    case "revoke":
+    case "sessions revoke":
       return renderRevokeData(colors, data);
     case "daemon run":
       return renderDaemonRunData(colors, data, flags);
@@ -1824,7 +1848,24 @@ var guarded = (context) => {
   };
 };
 
-// src/cli/routes/tools.ts
+// src/cli/routes/tools/shared-options.ts
+import { isValidToolGroup } from "@appduct/shared";
+var parseToolsListingFlags = (context) => {
+  const { options } = context;
+  const limit = parsePositiveIntegerOption(options.limit, "--limit");
+  const offset = parseNonNegativeIntegerOption(options.offset, "--offset");
+  const filter = readTextOption(context.argv, options.filter, "--filter");
+  const group = readTextOption(context.argv, options.group, "--group");
+  if (group !== void 0 && !isValidToolGroup(group)) {
+    throw usageError(
+      `"--group" must be a group name like "checkout" or "checkout/payment" (one or two "/"-separated segments of [a-zA-Z0-9_-], at most 64 characters each); got ${JSON.stringify(group)}.`
+    );
+  }
+  const groups = options.groups === void 0 ? void 0 : Boolean(options.groups);
+  return { group, groups, filter, limit, offset };
+};
+
+// src/cli/routes/tools/ls.ts
 var route = async (context) => {
   const { options, stateDir } = context;
   return executeCommand(
@@ -1833,29 +1874,12 @@ var route = async (context) => {
     // 64, `--json` envelope) instead of escaping the route as an uncaught rejection, and before
     // the version check so a typo never waits on (or restarts) the daemon.
     () => {
-      const { selector, target, selectorOrTarget } = splitOptionalSelectorAndTarget(
-        context.args,
-        "tools [selector] [name]"
-      );
-      const limit = parsePositiveIntegerOption(options.limit, "--limit");
-      const offset = parseNonNegativeIntegerOption(options.offset, "--offset");
-      const filter = readTextOption(context.argv, options.filter, "--filter");
-      const group = readTextOption(context.argv, options.group, "--group");
-      if (group !== void 0 && !isValidToolGroup(group)) {
-        throw usageError(
-          `"--group" must be a group name like "checkout" or "checkout/payment" (one or two "/"-separated segments of [a-zA-Z0-9_-], at most 64 characters each); got ${JSON.stringify(group)}.`
-        );
-      }
-      const groups = options.groups === void 0 ? void 0 : Boolean(options.groups);
-      if (groups && options.full) {
+      const { selector } = splitOptionalSelector(context.args, "tools ls [selector]");
+      const listing = parseToolsListingFlags(context);
+      if (listing.groups && options.full) {
         throw usageError('"--groups" lists groups only and cannot be combined with "--full".');
       }
-      return guarded(context)(
-        () => handleToolsCommand(
-          { selector: selector ?? selectorOrTarget, name: target, group, groups, filter, limit, offset },
-          { stateDir }
-        )
-      )();
+      return guarded(context)(() => handleToolsCommand({ selector, ...listing }, { stateDir }))();
     },
     context.env,
     { full: Boolean(options.full) }

package/dist/cli/routes/tools/shared-options.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The listing-only flags (`--group`/`--groups`/`--filter`/`--limit`/`--offset`) shared by
+ * `tools ls`, which acts on them, and `tools describe`, which only needs them parsed so it can
+ * reject one next to a `<name>` with the same usage error it has always gotten
+ * (`commands/tools.ts`'s `hasListingOnlyOptions`). Kept out of `index.ts` — nothing outside this
+ * directory imports it — since a route module, not the noun's router, is the caller.
+ */
+import type { RouteContext } from "../../router.js";
+export type ToolsListingFlags = {
+    group?: string;
+    groups?: boolean;
+    filter?: string;
+    limit?: number;
+    offset?: number;
+};
+export declare const parseToolsListingFlags: (context: RouteContext) => ToolsListingFlags;

package/dist/cli/routes/tools/shared-options.js

@@ -0,0 +1,122 @@
+// src/cli/routes/tools/shared-options.ts
+import { isValidToolGroup } from "@appduct/shared";
+
+// src/rpc/client.ts
+import { join as join2 } from "node:path";
+import { RPC_METHODS } from "@appduct/shared";
+
+// src/daemon/config.ts
+var DEFAULT_DAEMON_LOG_MAX_BYTES = 10 * 1024 * 1024;
+
+// src/package-root.ts
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_NAME = "appduct";
+var cached;
+var getPackageRoot = () => {
+  if (cached !== void 0) {
+    return cached;
+  }
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (; ; ) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      let name;
+      try {
+        name = JSON.parse(readFileSync(candidate, "utf8")).name;
+      } catch {
+      }
+      if (name === PACKAGE_NAME) {
+        cached = dir;
+        return dir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error(`Could not locate the "${PACKAGE_NAME}" package root above ${import.meta.url}.`);
+    }
+    dir = parent;
+  }
+};
+
+// src/rpc/client.ts
+var defaultBinPath = join2(getPackageRoot(), "bin.js");
+
+// src/errors.ts
+var AppductCliError = class extends Error {
+  type;
+  details;
+  constructor(type, message, details) {
+    super(message);
+    this.name = "AppductCliError";
+    this.type = type;
+    this.details = details;
+  }
+};
+var usageError = (message, details) => {
+  return new AppductCliError("usage_error", message, details);
+};
+
+// src/cli/command-options.ts
+var parsePositiveIntegerOption = (value, flagName) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
+    throw usageError(`"${flagName}" must be a positive integer.`);
+  }
+  return parsed;
+};
+var parseNonNegativeIntegerOption = (value, flagName) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 0) {
+    throw usageError(`"${flagName}" must be a non-negative integer.`);
+  }
+  return parsed;
+};
+var readTextOption = (argv, value, flagName) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value === "boolean") {
+    throw usageError(`"${flagName}" requires a value.`);
+  }
+  let raw;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") {
+      break;
+    }
+    if (token === flagName && index + 1 < argv.length) {
+      raw = argv[index + 1];
+      index += 1;
+    } else if (token.startsWith(`${flagName}=`)) {
+      raw = token.slice(flagName.length + 1);
+    }
+  }
+  return raw ?? String(Array.isArray(value) ? value.at(-1) : value);
+};
+
+// src/cli/routes/tools/shared-options.ts
+var parseToolsListingFlags = (context) => {
+  const { options } = context;
+  const limit = parsePositiveIntegerOption(options.limit, "--limit");
+  const offset = parseNonNegativeIntegerOption(options.offset, "--offset");
+  const filter = readTextOption(context.argv, options.filter, "--filter");
+  const group = readTextOption(context.argv, options.group, "--group");
+  if (group !== void 0 && !isValidToolGroup(group)) {
+    throw usageError(
+      `"--group" must be a group name like "checkout" or "checkout/payment" (one or two "/"-separated segments of [a-zA-Z0-9_-], at most 64 characters each); got ${JSON.stringify(group)}.`
+    );
+  }
+  const groups = options.groups === void 0 ? void 0 : Boolean(options.groups);
+  return { group, groups, filter, limit, offset };
+};
+export {
+  parseToolsListingFlags
+};

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

@@ -3,11 +3,12 @@
  * wrapper over the same `tools.list`/`tools.call`/`events.subscribe`/`events.since` RPC the CLI and
  * MCP server use (`rpc/client.ts`'s `DaemonStream`), bound to one resolved session. No new privilege
  * or transport — every call is attributed `caller: "client"` for the audit log (ARCHITECTURE.md
- * §12). {@link AppClient.waitForEvent}'s drain-then-live pattern mirrors the built-in
- * `appduct_wait_for_event` MCP tool (`mcp/events-tool.ts`) — see that module's doc comment for
- * why the notification listener has to be registered before the `events.since` drain call is sent.
+ * §12). {@link AppClient.waitForEvent} is `events/index.ts`'s `waitForAppEvent` (issue #114) — the
+ * same drain-then-live implementation the built-in `appduct_wait_for_event` MCP tool
+ * (`mcp/events-tool.ts`) uses — called on a fresh stream opened for that one wait, so concurrent
+ * waits on the same `AppClient` never share (and can't clobber) one connection's subscription.
  */
-import { type ListedToolDescriptor } from "@appduct/shared";
+import { type AppEvent, type FullAppEvent, type ListedToolDescriptor } from "@appduct/shared";
 import type { DaemonStream } from "../rpc/client.js";
 /** A project's own tool map — declared once, e.g. `type Tools = { sum: { args: { a: number; b:
  * number }; result: { total: number } } }` — to get typed {@link AppClient.call} throughout a test
@@ -39,9 +40,6 @@ export type CallOptions = {
 export type WaitForEventOptions = {
     /** Defaults to 30s. */
     timeoutMs?: number;
-    /** Extra filter over the event's payload; the event still must match `name` first. A predicate
-     * that throws rejects the wait with that error rather than crashing the connection. */
-    match?: (payload: unknown) => boolean;
     /**
      * Exclusive lower bound on `AppEvent.seq` (a cursor from a previous {@link AppClient.events} or
      * {@link AppClient.waitForEvent} call) — skips already-retained events at/before it instead of
@@ -49,6 +47,12 @@ export type WaitForEventOptions = {
      * so a matching event that already fired before this call still resolves immediately.
      */
     since?: number;
+    /**
+     * Caps the resolved event's payload to this many UTF-8 bytes of its JSON, daemon-side (issue
+     * #114, same cap {@link AppClient.events} takes). Omitted, the payload is delivered whole; passed,
+     * the resolved event may come back truncated — see {@link AppClient.waitForEvent}'s overloads.
+     */
+    payloadMaxBytes?: number;
 };
 export type EventsOptions = {
     /** Exclusive lower bound on `AppEvent.seq`; omitted returns the whole retained buffer (oldest
@@ -58,26 +62,35 @@ export type EventsOptions = {
      * matching `since` up to the buffer's own retention limit. */
     limit?: number;
 };
-export type EventsResult = {
-    events: AppEvent[];
+/** `events.since`'s `dropped`/`remaining`, shared by both of {@link AppClient.events}'s overloaded
+ * results (issue #113). */
+export type EventsCounts = {
+    /** App events after `since` that were evicted before this call could return them (`0` once
+     * nothing has fallen off — including across a gap of only Appduct's own kinds, which never
+     * advance `seq`). */
+    dropped: number;
+    /** Events still matching this query after the returned (possibly `limit`-truncated) page; `0`
+     * on the last page. */
+    remaining: number;
+};
+/** {@link AppClient.events}'s result with no `payloadMaxBytes` — every event's `payload` is
+ * readable unnarrowed. */
+export type FullEventsResult = EventsCounts & {
+    events: FullAppEvent[];
     /** The highest `seq` currently retained for this session (not just among the returned events) —
-     * pass it back as `since`/`since` on the next {@link AppClient.events}/{@link
-     * AppClient.waitForEvent} call to resume after it. */
+     * pass it back as `since` on the next {@link AppClient.events}/{@link AppClient.waitForEvent}
+     * call to resume after it. */
     cursor: number;
 };
-/** An app-pushed event (`postEvent(name, payload)`), narrowed from the daemon's generic
- * `EventNotification` envelope to the shape a `waitForEvent`/`events` caller actually wants. */
-export type AppEvent<TPayload = unknown> = {
-    name: string;
-    payload: TPayload;
-    /** Unix ms. */
-    ts: number;
-    sessionId: string;
-    alias?: string;
-    /** Monotonically increasing per-session cursor (ARCHITECTURE.md §5) assigned by the daemon's
-     * retention buffer at emit time — pass back into `since` to resume after this event. */
-    seq: number;
+/** {@link AppClient.events}'s result once a `payloadMaxBytes` cap is given — narrow each event on
+ * `truncated` before reading `payload`. */
+export type EventsResult = EventsCounts & {
+    events: AppEvent[];
+    cursor: number;
 };
+/** Re-exported from `@appduct/shared` (issue #112) so `appduct/client` keeps its own public
+ * `AppEvent` name and doc comment for a `waitForEvent`/`events` caller. */
+export type { AppEvent, FullAppEvent } from "@appduct/shared";
 export type AppClient<TTools = ToolMap> = {
     readonly sessionId: string;
     /** `tools.list` for this session. An entry spells an ungrouped tool's `group` as `null`,
@@ -86,26 +99,70 @@ export type AppClient<TTools = ToolMap> = {
     /** `tools.call`; rejects with a {@link AppductError} whose `type` preserves the wire error
      * type verbatim (e.g. `"tool_timeout"`, `"policy_denied"`, `"session_suspended"`). */
     call<K extends keyof TTools & string>(name: K, args: ToolArgs<TTools, K>, options?: CallOptions): Promise<ToolResult<TTools, K>>;
-    /** Drains `app_event`s retained in the daemon's per-session ring buffer since a cursor — the pull
+    /**
+     * Drains `app_event`s retained in the daemon's per-session ring buffer since a cursor — the pull
      * counterpart to {@link AppClient.waitForEvent}, for checking what already happened instead of
      * waiting for the next one. Pass `cursor` from the result back as `since` on the next call to
-     * avoid re-reading events already seen. */
-    events(options?: EventsOptions): Promise<EventsResult>;
+     * avoid re-reading events already seen. `dropped`/`remaining` (issue #113) report, respectively,
+     * how many app events after `since` were evicted before this call could return them, and how
+     * much more still matches after this page.
+     *
+     * Overloaded on `payloadMaxBytes` (issue #113): omit it and every event's `payload` is readable
+     * unnarrowed ({@link FullEventsResult}); pass it to cap each payload's JSON to that many UTF-8
+     * bytes, and narrow each event on `truncated` before reading `payload` ({@link EventsResult}) —
+     * an event whose payload was over the cap has `payloadPreview`/`payloadBytes` instead.
+     *
+     * The uncapped overload is listed first, but excludes `payloadMaxBytes` from its type
+     * (`payloadMaxBytes?: undefined`) rather than simply omitting the key from `EventsOptions`:
+     * TypeScript's excess-property check only rejects an extra `payloadMaxBytes` on an object
+     * *literal* passed directly as the argument, so an options bag held in a variable would
+     * otherwise still structurally match plain `EventsOptions` and resolve to `FullEventsResult`
+     * — letting `event.payload` compile unnarrowed even though the daemon truncated it (issue
+     * #113's review). Requiring the key to be `undefined` when present means a variable whose
+     * `payloadMaxBytes` is typed `number` (required or optional) fails to match this overload —
+     * by excess-property check for a literal, by property-type mismatch for a variable — and
+     * falls through to the capped overload below, which accepts any `payloadMaxBytes` (including
+     * `number | undefined`) and returns the narrowed `EventsResult` whenever the type cannot
+     * prove the payload is uncapped.
+     */
+    events(options?: EventsOptions & {
+        payloadMaxBytes?: undefined;
+    }): Promise<FullEventsResult>;
+    events(options: EventsOptions & {
+        payloadMaxBytes?: number;
+    }): Promise<EventsResult>;
     /**
      * Waits for the next `app_event` (as pushed by the connected app's `postEvent(name, payload)`)
-     * matching `name`. Checks the daemon's retained buffer for an already-arrived match first, then
-     * falls back to a live wait — so an event emitted between "the caller decides to wait" and "the
-     * subscription lands" is never missed; pass `since` (a cursor from a previous {@link
+     * whose name matches `name`, a whole-name, case-sensitive glob (issue #114: `*` matches any run
+     * of characters, a pattern with no `*` is an exact name — e.g. `"cart.*"`, or `"*"` for the next
+     * event of any name). Checks the daemon's retained buffer for an already-arrived match first,
+     * then falls back to a live wait — so an event emitted between "the caller decides to wait" and
+     * "the subscription lands" is never missed; pass `since` (a cursor from a previous {@link
      * AppClient.events}/`waitForEvent` call) to skip events already handled and wait only for a new
      * one, since omitting it can return an old match instantly on every call.
      *
-     * This shares the connection's single `events.subscribe` filter (the daemon keeps one per
-     * connection, replaced — not merged — on each call); concurrent `waitForEvent` calls on the same
-     * `AppClient` all see every `app_event`, so this is safe today, but it means the connection stays
-     * subscribed to `app_event` for its lifetime once any `waitForEvent` has run.
+     * Opens its own daemon stream for this one wait (issue #114) rather than sharing this
+     * `AppClient`'s connection, so concurrent `waitForEvent` calls with different `name`s each get
+     * their own `events.subscribe` filter and resolve on their own event.
+     *
+     * Overloaded on `payloadMaxBytes` the same way {@link AppClient.events} is (issue #114): omit it
+     * and the resolved event's `payload` is readable unnarrowed ({@link FullAppEvent}); pass it to
+     * cap the payload's JSON to that many UTF-8 bytes daemon-side, and narrow on `truncated` before
+     * reading `payload` ({@link AppEvent}) — an event whose payload was over the cap has
+     * `payloadPreview`/`payloadBytes` instead. See {@link AppClient.events}'s doc comment for why the
+     * uncapped overload spells its `payloadMaxBytes` as `undefined` rather than omitting the key.
      */
-    waitForEvent<TPayload = unknown>(name: string, options?: WaitForEventOptions): Promise<AppEvent<TPayload>>;
-    /** Closes the underlying connection. Safe to call more than once. */
+    waitForEvent<TPayload = unknown>(name: string, options?: WaitForEventOptions & {
+        payloadMaxBytes?: undefined;
+    }): Promise<FullAppEvent<TPayload>>;
+    waitForEvent<TPayload = unknown>(name: string, options: WaitForEventOptions & {
+        payloadMaxBytes?: number;
+    }): Promise<AppEvent<TPayload>>;
+    /** Closes the underlying connection, and every stream a still-pending {@link
+     * AppClient.waitForEvent} call opened for itself — each such call rejects with a `"connection_error"`
+     * {@link AppductError}, the same way it did before `waitForEvent` moved onto its own stream (issue
+     * #114). A `waitForEvent` call made after `close()` rejects immediately with the same error and
+     * never opens a stream (so it never auto-spawns a daemon). Safe to call more than once. */
     close(): void;
 };
 /**
@@ -122,5 +179,7 @@ export type AppClient<TTools = ToolMap> = {
  * generic transport error in place of the daemon's real one.
  */
 export declare const transportTimeoutForToolCall: (timeoutMs: number | undefined) => number;
-export declare const makeAppClient: <TTools = ToolMap>(stream: DaemonStream, sessionId: string) => AppClient<TTools>;
-export {};
+export declare const makeAppClient: <TTools = ToolMap>(stream: DaemonStream, sessionId: string, 
+/** Opens a fresh `DaemonStream` for one {@link AppClient.waitForEvent} call (issue #114) — every
+ * other method keeps using `stream` above. */
+openStream: () => Promise<DaemonStream>) => AppClient<TTools>;

package/dist/client/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * `appduct/client` (issue #8): a first-class programmatic client for test runners — a thin typed
  * wrapper over the same daemon RPC the CLI and MCP server use, so a Jest/Vitest/Detox spec can
- * `connect()`/`call()` instead of spawning `appduct invoke ... --json` and parsing stdout.
+ * `connect()`/`call()` instead of spawning `appduct tools call ... --json` and parsing stdout.
  *
  * ```ts
  * import { connect } from "appduct/client";
@@ -14,5 +14,6 @@
 export { connect, type ConnectOptions } from "./connect.js";
 export { link, waitForSession, type LinkOptions, type LinkResult, type WaitForSessionOptions } from "./bootstrap.js";
 export { AppductError, type AppductErrorType } from "./errors.js";
-export type { AppClient, AppEvent, CallOptions, EventsOptions, EventsResult, ToolMap, WaitForEventOptions, } from "./app-client.js";
+export type { AppClient, AppEvent, CallOptions, EventsOptions, EventsResult, FullAppEvent, FullEventsResult, ToolMap, WaitForEventOptions, } from "./app-client.js";
+export type { TruncatedAppEvent } from "@appduct/shared";
 export type { AgentEndpoint, ErrorType, ListedToolDescriptor, ToolDescriptor } from "@appduct/shared";