appduct 0.13.0 → 0.14.0

package/README.md

@@ -46,6 +46,7 @@ Every command is `appduct <noun> <verb> [selector] [args]`, the same shape as `a
 | `appduct tools ls [selector] --groups` | list a session's tool groups with their tool counts |
 | `appduct tools describe [selector] <name>` | show one tool's full schema |
 | `appduct tools call [selector] <name> --input '<json>' [--timeout <ms>]` | call a tool |
+| `appduct events ls [selector] [--name <glob>] [--limit <n>] [--offset <n>]` | list the events the app declares, one signature line each; an exact `--name` prints the full payload schema; `--limit`/`--offset` page a long list, ending with a `Showing n of total events (offset o).` line when events were left out; `--json` carries the full descriptors, with `total` counting matches before paging |
 | `appduct events tail [selector] [--follow]` | stream the events the app posts with `postEvent`; `--json` emits NDJSON |
 | `appduct events since [selector] <cursor>` | one-shot pull the events retained since `<cursor>`; `--json` emits NDJSON |
 | `appduct daemon run\|start\|stop\|status` | daemon lifecycle |
@@ -222,9 +223,9 @@ Your MCP client asks permission for `appduct_call_tool` as a single tool, so cho
 
 Set this before you connect: the daemon reads `config.json` only when it starts, so changing it later takes `appduct daemon stop`. That disconnects every device, which then has to link again, and leaves a running `appduct mcp` without a daemon, so restart the MCP server in your client as well.
 
-Four more built-in tools cover what the app's own tools can't. `appduct_connect` mints a link and, by default, delivers it to whichever `android`/`ios-sim` device it detects — pass `target`/`device` to choose, or `target: "none"` to force the human flow — falling back to a QR code, plus instructions to show it, only when there's nothing to deliver to. Delivering to `android` (chosen or detected) needs `appId`, resolved the same way as `--app-id` (see [Delivering the link to a device](#delivering-the-link-to-a-device)); passing it with `target: "ios-sim"` or `"none"` is an error. `appduct_wait_for_session` then waits for that session to be claimed. `target: "ios-device"` reaches a paired physical iPhone or iPad, with `appId` and the [prerequisites above](#--open-ios-device-experimental) — it's experimental and never auto-detected, so an agent has to ask for it by name.
+Five more built-in tools cover what the app's own tools can't. `appduct_connect` mints a link and, by default, delivers it to whichever `android`/`ios-sim` device it detects — pass `target`/`device` to choose, or `target: "none"` to force the human flow — falling back to a QR code, plus instructions to show it, only when there's nothing to deliver to. Delivering to `android` (chosen or detected) needs `appId`, resolved the same way as `--app-id` (see [Delivering the link to a device](#delivering-the-link-to-a-device)); passing it with `target: "ios-sim"` or `"none"` is an error. `appduct_wait_for_session` then waits for that session to be claimed. `target: "ios-device"` reaches a paired physical iPhone or iPad, with `appId` and the [prerequisites above](#--open-ios-device-experimental) — it's experimental and never auto-detected, so an agent has to ask for it by name.
 
-The other two give an agent a pull surface over `postEvent()`-pushed app events: `appduct_events` drains everything retained since a cursor, and `appduct_wait_for_event` blocks for the next event whose name matches `name`, a whole-name glob (`*` waits for any name) — checking what's already retained before waiting live — rejecting with `tool_timeout` if none arrives in time.
+The other three give an agent a pull surface over `postEvent()`-pushed app events. `appduct_list_events` lists the events the app declared (`appduct events ls`) as signatures with descriptions, plus the payload schema when `name` is an exact name, so an agent learns the names before it waits on one. `appduct_events` drains everything retained since a cursor, and `appduct_wait_for_event` blocks for the next event whose name matches `name`, a whole-name glob (`*` waits for any name) — checking what's already retained before waiting live — rejecting with `tool_timeout` if none arrives in time.
 
 ## Test runners: `appduct/client`
 

package/dist/bin.js

@@ -140,10 +140,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."
   );
@@ -524,6 +524,7 @@ var getExitCodeForError = (error) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -619,6 +620,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."];
@@ -627,7 +635,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)
@@ -801,6 +809,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)];
 };
@@ -992,6 +1047,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/cli/result-types.d.ts

@@ -4,7 +4,7 @@
  * the thin-client shapes for the v2 command table.
  */
 import type { OpenTarget } from "./open-target.js";
-import type { AgentEndpoint, EffectivePolicyDecision, EventNotification, SessionSummary, ToolGroupSummary, ToolsListEntry, ToolsListResult } from "@appduct/shared";
+import type { AgentEndpoint, EffectivePolicyDecision, EventNotification, EventsListResult, SessionSummary, ToolGroupSummary, ToolsListEntry, ToolsListResult } from "@appduct/shared";
 /**
  * CLI-domain error classes, used only to pick a sysexits-style exit code (see `errors.ts`).
  * `CliError.type` itself is *not* restricted to this union: RPC/app-originated failures preserve
@@ -135,6 +135,13 @@ export type ToolGroupsListing = {
  * listing entry, picked out of `tools.list` — not a registration, so its `group` is `null` for an
  * ungrouped tool. */
 export type ToolsCommandData = ToolsListing | ToolGroupsListing | ToolsListEntry;
+/** `appduct events ls`: the daemon's `events.list` result, plus the `--name`/`--limit`/`--offset`
+ * inputs that produced it (only the ones actually given). */
+export type EventsListing = EventsListResult & {
+    name?: string;
+    limit?: number;
+    offset?: number;
+};
 /** `appduct tools call`: the tool's raw result payload, printed as-is. */
 export type InvokeCommandData = unknown;
 export type RevokeCommandData = {

package/dist/cli/routes/daemon/index.js

@@ -213,6 +213,7 @@ var formatJson = (value, flags) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -308,6 +309,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."];
@@ -316,7 +324,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)
@@ -490,6 +498,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)];
 };
@@ -681,6 +736,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/cli/routes/daemon/run.js

@@ -484,6 +484,7 @@ var RpcApplicationError = class extends Error {
     this.name = "RpcApplicationError";
   }
 };
+var appBackgroundedMessage = (alias) => `Session "${alias}" is suspended because the app is in the background. Bring the app to the foreground to resume it.`;
 
 // src/daemon/timers.ts
 var systemTimers = {
@@ -586,7 +587,7 @@ var createCallsManager = (options) => {
     const message = { type: "tool_cancel", session_id: sessionId, id: callId, reason };
     return options.sendCancel(sessionId, message);
   };
-  const rejectSession = (sessionId, errorType) => {
+  const rejectSession = (sessionId, errorType, options2 = {}) => {
     const sessionMap = pendingBySession.get(sessionId);
     if (!sessionMap) {
       return;
@@ -594,13 +595,19 @@ var createCallsManager = (options) => {
     pendingBySession.delete(sessionId);
     for (const pending of sessionMap.values()) {
       timers.clearTimeout(pending.timer);
-      pending.reject(new RpcApplicationError(errorType, `Session transitioned while the call was pending.`));
+      pending.reject(
+        new RpcApplicationError(
+          errorType,
+          options2.backgrounded ? appBackgroundedMessage(pending.alias) : "Session transitioned while the call was pending."
+        )
+      );
     }
   };
   const unsubscribeFromEventBus = options.eventBus.subscribe((event) => {
     const errorType = TERMINATING_KIND_ERROR_TYPES[event.kind];
     if (errorType && event.sessionId) {
-      rejectSession(event.sessionId, errorType);
+      const backgrounded = event.kind === "session_suspended" && event.data.reason === "app_backgrounded";
+      rejectSession(event.sessionId, errorType, { backgrounded });
     }
   });
   const disposeAll = () => {
@@ -791,6 +798,8 @@ import {
   isEventMessage,
   isToolCallProgressMessage,
   isToolErrorMessage,
+  isEventRegistryDeltaMessage,
+  isEventRegistrySnapshotMessage,
   isToolRegistryDeltaMessage,
   isToolRegistrySnapshotMessage,
   isToolResultMessage,
@@ -888,7 +897,7 @@ var createPendingLinkRegistry = (options) => {
 };
 
 // src/daemon/registry.ts
-var createToolRegistry = (onChange) => {
+var createRegistry = (onChange) => {
   let tools = /* @__PURE__ */ new Map();
   const notify = () => {
     onChange?.();
@@ -918,6 +927,8 @@ var RESUME_TOKEN_BYTES = 32;
 var POST_CLAIM_MESSAGE_TYPES = /* @__PURE__ */ new Set([
   "tool_registry_snapshot",
   "tool_registry_delta",
+  "event_registry_snapshot",
+  "event_registry_delta",
   "tool_result",
   "tool_error",
   "tool_call_progress",
@@ -988,6 +999,7 @@ var createSessionManager = (options) => {
       createdAt: session.createdAt.toISOString(),
       claimedAt: session.claimedAt.toISOString(),
       ...session.suspendedAt ? { suspendedAt: session.suspendedAt.toISOString() } : {},
+      ...session.suspendReason ? { suspendReason: session.suspendReason } : {},
       toolCount: session.registry.count()
     };
   };
@@ -1024,7 +1036,8 @@ var createSessionManager = (options) => {
       alias: session.alias,
       resume_token: session.resumeToken.toString("base64url"),
       keepalive_interval_s: options.keepaliveIntervalSeconds,
-      grace_s: options.graceSeconds
+      grace_s: options.graceSeconds,
+      event_registry: true
     };
     socket.send(JSON.stringify(ack), (error) => {
       if (error) {
@@ -1032,17 +1045,18 @@ var createSessionManager = (options) => {
       }
     });
   };
-  const suspend = (sessionId) => {
+  const suspend = (sessionId, reason) => {
     const session = sessions.get(sessionId);
     if (!session || session.state !== "active") {
       return;
     }
     session.state = "suspended";
     session.suspendedAt = clock.now();
+    session.suspendReason = reason;
     session.socket = void 0;
     session.missedPongs = 0;
     session.graceTimer = timers.setTimeout(() => expire(sessionId), options.graceSeconds * 1e3);
-    emit("session_suspended", session.sessionId, session.alias, {});
+    emit("session_suspended", session.sessionId, session.alias, { reason });
   };
   const expire = (sessionId) => {
     const session = sessions.get(sessionId);
@@ -1059,9 +1073,10 @@ var createSessionManager = (options) => {
     socket.on("pong", () => {
       session.missedPongs = 0;
     });
-    socket.on("close", () => {
+    socket.on("close", (code, reason) => {
       if (session.socket === socket) {
-        suspend(session.sessionId);
+        const backgrounded = code === 1001 && reason.toString("utf8") === "app_backgrounded";
+        suspend(session.sessionId, backgrounded ? "app_backgrounded" : "connection_lost");
       }
     });
   };
@@ -1073,7 +1088,7 @@ var createSessionManager = (options) => {
       if (session.missedPongs >= 2) {
         const staleSocket = session.socket;
         session.socket = void 0;
-        suspend(session.sessionId);
+        suspend(session.sessionId, "connection_lost");
         staleSocket.terminate();
         continue;
       }
@@ -1138,8 +1153,11 @@ var createSessionManager = (options) => {
       resumeToken: randomBytes3(RESUME_TOKEN_BYTES),
       socket,
       missedPongs: 0,
-      registry: createToolRegistry(() => {
+      registry: createRegistry(() => {
         emit("tools_changed", sessionId, alias, { toolCount: session.registry.count() });
+      }),
+      eventRegistry: createRegistry(() => {
+        emit("events_changed", sessionId, alias, { eventCount: session.eventRegistry.count() });
       })
     };
     sessions.set(sessionId, session);
@@ -1171,6 +1189,7 @@ var createSessionManager = (options) => {
     session.resumeToken = randomBytes3(RESUME_TOKEN_BYTES);
     session.state = "active";
     session.suspendedAt = void 0;
+    session.suspendReason = void 0;
     session.socket = socket;
     session.missedPongs = 0;
     attachSocketHandlers(session);
@@ -1205,6 +1224,26 @@ var createSessionManager = (options) => {
         }
         return;
       }
+      case "event_registry_snapshot": {
+        if (!isEventRegistrySnapshotMessage(message)) {
+          closeSocket(socket, 1008, "invalid_registry");
+          return;
+        }
+        session.eventRegistry.snapshot(message.events);
+        return;
+      }
+      case "event_registry_delta": {
+        if (!isEventRegistryDeltaMessage(message)) {
+          closeSocket(socket, 1008, "invalid_registry");
+          return;
+        }
+        if (message.operation === "upsert") {
+          session.eventRegistry.upsert(message.event);
+        } else {
+          session.eventRegistry.remove(message.name);
+        }
+        return;
+      }
       case "tool_result": {
         if (!isToolResultMessage(message)) {
           closeSocket(socket, 1008, "invalid_message");
@@ -1272,7 +1311,14 @@ var createSessionManager = (options) => {
   };
   const resolveForTools = (selector) => {
     const session = resolveSession(selector);
-    return { sessionId: session.sessionId, alias: session.alias, state: session.state, registry: session.registry };
+    return {
+      sessionId: session.sessionId,
+      alias: session.alias,
+      state: session.state,
+      suspendReason: session.suspendReason,
+      registry: session.registry,
+      eventRegistry: session.eventRegistry
+    };
   };
   const sendToApp = (sessionId, message) => {
     const session = sessions.get(sessionId);
@@ -2040,6 +2086,26 @@ var asSelectorParams = (params) => {
   }
   return { selector };
 };
+var asPageParams = (record) => {
+  const limit = record.limit;
+  if (limit !== void 0 && (typeof limit !== "number" || !Number.isInteger(limit) || limit <= 0)) {
+    throw new RpcApplicationError("invalid_request", '"limit" must be a positive integer.');
+  }
+  const offset = record.offset;
+  if (offset !== void 0 && (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0)) {
+    throw new RpcApplicationError("invalid_request", '"offset" must be a non-negative integer.');
+  }
+  return { limit, offset };
+};
+var asEventsListParams = (params) => {
+  const { selector } = asSelectorParams(params);
+  const record = asRecordParams(params);
+  const name = record.name;
+  if (name !== void 0 && typeof name !== "string") {
+    throw new RpcApplicationError("invalid_request", '"name" must be a string.');
+  }
+  return { selector, name, ...asPageParams(record) };
+};
 var asToolsListParams = (params) => {
   const { selector } = asSelectorParams(params);
   const record = asRecordParams(params);
@@ -2057,14 +2123,7 @@ var asToolsListParams = (params) => {
       `"filter" must be a string of at most ${MAX_TOOLS_FILTER_LENGTH} characters.`
     );
   }
-  const limit = record.limit;
-  if (limit !== void 0 && (typeof limit !== "number" || !Number.isInteger(limit) || limit <= 0)) {
-    throw new RpcApplicationError("invalid_request", '"limit" must be a positive integer.');
-  }
-  const offset = record.offset;
-  if (offset !== void 0 && (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0)) {
-    throw new RpcApplicationError("invalid_request", '"offset" must be a non-negative integer.');
-  }
+  const { limit, offset } = asPageParams(record);
   return {
     selector,
     group,
@@ -2395,6 +2454,17 @@ var startDaemon = async (options) => {
           activeSessionManager.revoke(selector);
           return { ok: true };
         },
+        [RPC_METHODS.eventsList]: (params) => {
+          const { selector, name, limit, offset } = asEventsListParams(params);
+          const registered = activeSessionManager.resolveForTools(selector).eventRegistry.list();
+          const sorted = registered.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+          const matching = name === void 0 ? sorted : sorted.filter((event) => matchesNameGlob(name, event.name));
+          const start = offset ?? 0;
+          return {
+            events: limit === void 0 ? matching.slice(start) : matching.slice(start, start + limit),
+            total: matching.length
+          };
+        },
         [RPC_METHODS.toolsList]: (params) => {
           const { selector, group, filter, limit, offset } = asToolsListParams(params);
           const resolved = activeSessionManager.resolveForTools(selector);
@@ -2442,7 +2512,10 @@ var startDaemon = async (options) => {
           if (resolved.state !== "active") {
             const errorType = resolved.state === "suspended" ? "session_suspended" : "session_not_active";
             writeAudit("error", errorType);
-            throw new RpcApplicationError(errorType, `Session "${resolved.alias}" is not active.`);
+            throw new RpcApplicationError(
+              errorType,
+              resolved.suspendReason === "app_backgrounded" ? appBackgroundedMessage(resolved.alias) : `Session "${resolved.alias}" is not active.`
+            );
           }
           const tool = resolved.registry.get(name);
           if (!tool) {
@@ -2786,6 +2859,7 @@ var formatJson = (value, flags) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -2881,6 +2955,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."];
@@ -2889,7 +2970,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)
@@ -3063,6 +3144,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)];
 };
@@ -3254,6 +3382,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":