appduct 0.13.0 → 0.14.0

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

@@ -28,6 +28,16 @@ export type ProjectAppEventOptions = {
     /** Caps the payload's JSON to this many UTF-8 bytes (issue #113); see {@link truncateToUtf8Bytes}. */
     payloadMaxBytes?: number;
 };
+/** Whether `name` matches the whole-name glob `pattern` (`*` matches any run of characters,
+ * everything else literally), in time linear in the two strings' lengths.
+ *
+ * No regex and no backtracking: the daemon is single-threaded, so a match that blows up blocks
+ * every session and RPC client (issue #112 review). Compiling `*` to `.*` was exponential in the
+ * star count, and a two-pointer matcher that backtracks to the last `*` was still quadratic.
+ * Instead the pattern is split on `*`: the first piece must be a prefix, the last a suffix, and
+ * each middle piece is found in order with `indexOf`. Taking the leftmost occurrence of each
+ * middle piece is always safe, because it leaves the most room for the pieces after it. */
+export declare const matchesNameGlob: (pattern: string, name: string) => boolean;
 /**
  * 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

package/dist/daemon/registry.d.ts

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

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

@@ -14,3 +14,6 @@ export declare class RpcApplicationError extends Error {
     /** JSON-RPC error code; defaults to the shared "server error" range. */
     code?: number, details?: unknown | undefined);
 }
+/** The `session_suspended` message for an app that closed its socket because it went to the
+ * background: says why and how to recover. */
+export declare const appBackgroundedMessage: (alias: string) => string;

package/dist/daemon/sessions.d.ts

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

package/dist/index.js

@@ -138,10 +138,10 @@ var createCli = () => {
     "--timeout <ms>",
     "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(
+  cli.command("events [...args]", "List the events an app declares, stream them, or replay them since a cursor: ls, tail, or since.").usage("events <ls|tail|since> [selector] [args]").option("--follow", "tail: accepted for script readability; the default behavior already follows.").option(
     "--name <glob>",
-    'Only events whose name matches this whole-name, case-sensitive glob ("*" matches any run of characters).'
-  ).option(
+    `Only events whose name matches this whole-name, case-sensitive glob ("*" matches any run of characters). ls: an exact name prints that event's full payload schema.`
+  ).option("--limit <n>", "ls: show at most n events.").option("--offset <n>", "ls: skip the first n events of the name-sorted list.").option(
     "--payload-max-bytes <n>",
     "Cap each event's payload at this many UTF-8 bytes of its JSON; over the cap, the event carries payloadPreview, payloadBytes and truncated: true instead of payload."
   );
@@ -546,6 +546,7 @@ var getExitCodeForError = (error) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -641,6 +642,13 @@ var formatDevice = (device) => {
   const label = parts.length > 0 ? parts.join(" ") : "unknown device";
   return device.os ? `${label} (${device.os})` : label;
 };
+var SUSPEND_REASON_LABELS = {
+  app_backgrounded: "app in background",
+  connection_lost: "connection lost"
+};
+var formatSessionState = (session) => {
+  return session.suspendReason ? `${session.state} (${SUSPEND_REASON_LABELS[session.suspendReason]})` : session.state;
+};
 var renderLsData = (colors, data, now) => {
   if (data.length === 0) {
     return [colors.dim("Sessions"), "  No Appduct sessions are registered."];
@@ -649,7 +657,7 @@ var renderLsData = (colors, data, now) => {
   const headers = ["Alias", "State", "Device", "Tools", "Age"];
   const rows = data.map((session) => [
     session.alias,
-    session.state,
+    formatSessionState(session),
     formatDevice(session.device),
     String(session.toolCount),
     formatAge(session.claimedAt ?? session.createdAt, nowIso)
@@ -823,6 +831,53 @@ var renderToolsListData = (colors, data, flags, full) => {
   }
   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)];
 };
@@ -1014,6 +1069,8 @@ var renderSuccessData = (colors, command, data, options) => {
       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 "sessions revoke":

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

@@ -107,12 +107,30 @@ export type ResolvedAppTool = {
     descriptor: ListedToolDescriptor;
     policy: EffectivePolicyDecision;
 };
+type ResolvedSession = {
+    sessionId: string;
+    alias: string;
+};
 export type CallToolArgs = {
     selector?: string;
     name: string;
     args: Record<string, unknown>;
     timeoutMs?: number;
 };
+/** Every key an agent sends must be one the tool declares. A misspelled key (`arguments` for
+ * `args`, `timeout_ms` for `timeoutMs`) would otherwise be dropped silently, and the tool would run
+ * without what the agent meant to pass. */
+export declare const rejectUnknownKeys: (args: Record<string, unknown>, tool: string, allowed: readonly string[]) => void;
+/** `null` counts as absent for every optional field: some clients fill unset optional
+ * parameters with `null` rather than leaving them out. */
+export declare const asOptionalString: (value: unknown, field: string) => string | undefined;
+/** Resolves `selector` (an alias, a session id, or nothing) to one concrete session first, with
+ * the daemon's own rules and errors (`no_session`, `ambiguous_session`, `unknown_session`).
+ * Everything after that is routed by the **session id**, never the alias: the daemon frees an
+ * alias when a session ends and gives it to the next device of the same model, so routing by alias
+ * could land a call — one the user may already have approved — on a different device. If the
+ * session goes away mid-call, the next daemon call fails with `unknown_session` instead. */
+export declare const resolveSession: (call: DaemonCall, selector: string | undefined) => Promise<ResolvedSession>;
 export declare const handleListToolsTool: (rawArgs: unknown, call: DaemonCall) => Promise<{
     groups?: import("@appduct/shared").ToolGroupSummary[] | undefined;
     tools: {
@@ -152,3 +170,4 @@ export declare const parseCallToolArgs: (rawArgs: unknown) => CallToolArgs;
  */
 export declare const resolveCallDeadline: (tool: ResolvedAppTool, requestedTimeoutMs: number | undefined) => number;
 export declare const resolveAppTool: (call: DaemonCall, selector: string | undefined, name: string) => Promise<ResolvedAppTool>;
+export {};

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

@@ -12,12 +12,40 @@
 import { type AppEvent } from "@appduct/shared";
 import { type SpawnFn } from "../rpc/client.js";
 import type { DaemonCall } from "./daemon-tools.js";
+export declare const LIST_EVENTS_TOOL_NAME = "appduct_list_events";
 export declare const EVENTS_TOOL_NAME = "appduct_events";
 export declare const WAIT_FOR_EVENT_TOOL_NAME = "appduct_wait_for_event";
 /** Server-side cap on `timeoutMs` (issue #6's "Cap timeoutMs server-side below the idle window
  * rather than trusting the caller") — a pure function so the cap's boundary behavior is
  * unit-testable without spinning up a daemon or actually waiting out either bound. */
 export declare const clampWaitForEventTimeoutMs: (requestedMs: number | undefined) => number;
+export declare const LIST_EVENTS_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_list_events";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly selector: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Session alias or id. Omit to target the sole active/suspended session.";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly exclusiveMinimum: 0;
+            };
+            readonly offset: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+        };
+        readonly additionalProperties: false;
+    };
+};
 export declare const EVENTS_TOOL_DESCRIPTOR: {
     readonly name: "appduct_events";
     readonly description: string;
@@ -78,6 +106,17 @@ export declare const WAIT_FOR_EVENT_TOOL_DESCRIPTOR: {
 export type EventsToolDeps = {
     call: DaemonCall;
 };
+export declare const handleListEventsTool: (rawArgs: unknown, call: DaemonCall) => Promise<{
+    session: string;
+    total: number;
+    limit: {};
+    events: {
+        payload_schema?: import("@appduct/shared").EventSchemaDescriptor | undefined;
+        name: string;
+        signature: string;
+        description: string;
+    }[];
+}>;
 export type EventsToolResult = {
     events: AppEvent[];
     cursor: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appduct",
-  "version": "0.13.0",
+  "version": "0.14.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.13.0"
+    "@appduct/shared": "0.14.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",