appduct 0.12.0 → 0.14.0

package/dist/cli/routes/mcp.js

@@ -208,7 +208,7 @@ import {
   McpError,
   ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-import { RPC_METHODS as RPC_METHODS6 } from "@appduct/shared";
+import { RPC_METHODS as RPC_METHODS7 } from "@appduct/shared";
 
 // src/daemon/calls.ts
 import {
@@ -2656,40 +2656,167 @@ var resolveAppTool = async (call, selector, name) => {
 
 // src/mcp/events-tool.ts
 import {
-  RPC_METHODS as RPC_METHODS5
+  RPC_METHODS as RPC_METHODS6,
+  renderEventSignature,
+  toAppEvent as toAppEvent2
 } from "@appduct/shared";
+
+// src/events/index.ts
+import {
+  RPC_METHODS as RPC_METHODS5,
+  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_METHODS5.eventsSubscribe, {
+      sessionSelector: sessionId,
+      kinds: ["app_event"],
+      name,
+      payloadMaxBytes
+    });
+    const sinceResult = await stream.call(RPC_METHODS5.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/mcp/events-tool.ts
+var LIST_EVENTS_TOOL_NAME = "appduct_list_events";
 var EVENTS_TOOL_NAME = "appduct_events";
 var WAIT_FOR_EVENT_TOOL_NAME = "appduct_wait_for_event";
+var DEFAULT_EVENTS_LIMIT = 50;
+var DEFAULT_EVENTS_PAYLOAD_MAX_BYTES = 4096;
+var DEFAULT_LIST_EVENTS_LIMIT = 50;
 var DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS = 12e4;
 var MAX_WAIT_FOR_EVENT_TIMEOUT_MS = 25 * 60 * 1e3;
 var WAIT_FOR_EVENT_PROGRESS_INTERVAL_MS = 6e4;
 var clampWaitForEventTimeoutMs = (requestedMs) => {
   return Math.min(requestedMs ?? DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS, MAX_WAIT_FOR_EVENT_TIMEOUT_MS);
 };
+var LIST_EVENTS_TOOL_DESCRIPTOR = {
+  name: LIST_EVENTS_TOOL_NAME,
+  description: `List the events the connected app declared, as one-line signatures (\`name { field: type }\`) with each event's description. Call this before appduct_wait_for_event or appduct_events so you wait on a name the app really posts instead of guessing one. An app that declares no events returns an empty list, which does not mean it posts none. name is a whole-name, case-sensitive glob (* matches any run of characters), e.g. "cart.*"; a name without * that matches a declared event also returns that event's payload_schema. limit (default ${DEFAULT_LIST_EVENTS_LIMIT}) and offset page the name-sorted list, and total counts every match before paging. Returns { session, total, limit, events }, each event { name, signature, description }.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      selector: {
+        type: "string",
+        minLength: 1,
+        description: "Session alias or id. Omit to target the sole active/suspended session."
+      },
+      name: { type: "string", minLength: 1 },
+      limit: { type: "integer", exclusiveMinimum: 0 },
+      offset: { type: "integer", minimum: 0 }
+    },
+    additionalProperties: false
+  }
+};
 var EVENTS_TOOL_DESCRIPTOR = {
   name: EVENTS_TOOL_NAME,
-  description: "Drain the events the app posted with postEvent(name, payload) that the daemon retained for a session since a cursor, for checking what the app reported after calling a tool or triggering app behavior. With no selector, targets the sole active/suspended session. Returns { events, cursor }; pass cursor back as since on the next call to avoid re-reading events you've already seen. limit (if given) keeps the OLDEST events in the window and advances cursor only past what was actually returned, so repeated calls page forward through everything retained rather than skipping ahead.",
+  description: `Drain the events the app posted with postEvent(name, payload) that the daemon retained for a session since a cursor, for checking what the app reported after calling a tool or triggering app behavior. With no selector, targets the sole active/suspended session. name filters to events whose name matches a whole-name, case-sensitive glob (* matches any run of characters; a pattern without * is an exact name), e.g. "cart.*". Returns { events, cursor, dropped, remaining } with each event as { name, payload, ts, seq, sessionId, alias } or, once a payload's JSON exceeds payloadMaxBytes (default 4096), as { name, payloadPreview, truncated: true, payloadBytes, ts, seq, sessionId, alias } instead \u2014 check truncated before reading payload. pass cursor back as since on the next call to avoid re-reading events you've already seen; dropped counts app events after since that were evicted before this call could return them (0 once nothing has fallen off), and remaining counts events still matching this query after the returned page (0 on the last page). limit (default 50) keeps the OLDEST events in the window and advances cursor only past what was actually returned, so repeated calls page forward through everything retained rather than skipping ahead.`,
   inputSchema: {
     type: "object",
     properties: {
       selector: { type: "string" },
       since: { type: "integer", minimum: 0 },
-      limit: { type: "integer", exclusiveMinimum: 0 }
+      limit: { type: "integer", exclusiveMinimum: 0 },
+      name: { type: "string" },
+      payloadMaxBytes: { type: "integer", exclusiveMinimum: 0 }
     },
     additionalProperties: false
   }
 };
 var WAIT_FOR_EVENT_TOOL_DESCRIPTOR = {
   name: WAIT_FOR_EVENT_TOOL_NAME,
-  description: "Wait for the connected app to push an event via postEvent(name, payload) matching name (and, if match is given, every one of its keys strictly-equal \u2014 primitives only, not objects/arrays \u2014 in the event's payload). Checks already-retained events first, so an event that already fired before this call still resolves immediately; pass since (a cursor from a previous appduct_events/appduct_wait_for_event call) to skip events you've already handled and wait only for a new one \u2014 omitting it can return an old match instantly on every call. Requires a claimed session to already exist (use appduct_wait_for_session first if not). Resolves with { sessionId, alias, name, payload, ts, seq }, or rejects with tool_timeout after timeoutMs (default 120000ms, capped server-side at 1500000ms). A call still running after about two minutes moves to a Claude Code background task, so the result may arrive well after this call returns.",
+  description: `Wait for the connected app to push an event via postEvent(name, payload) whose name matches name, a whole-name, case-sensitive glob (* matches any run of characters; a pattern without * is an exact name, e.g. "cart.*", or "*" for the next event of any name). Checks already-retained events first, so an event that already fired before this call still resolves immediately; pass since (a cursor from a previous appduct_events/appduct_wait_for_event call) to skip events you've already handled and wait only for a new one \u2014 omitting it can return an old match instantly on every call. Requires a claimed session to already exist (use appduct_wait_for_session first if not). Resolves with { sessionId, alias, name, payload, ts, seq, dropped } or, once a payload's JSON exceeds payloadMaxBytes (default 4096), with { payloadPreview, truncated: true, payloadBytes } in place of payload \u2014 check truncated before reading payload; dropped counts app events after since that were evicted before this call could return them (0 once nothing has fallen off). Rejects with tool_timeout after timeoutMs (default 120000ms, capped server-side at 1500000ms). A call still running after about two minutes moves to a Claude Code background task, so the result may arrive well after this call returns.`,
   inputSchema: {
     type: "object",
     properties: {
       selector: { type: "string" },
       name: { type: "string" },
-      match: { type: "object", additionalProperties: { type: ["string", "number", "boolean", "null"] } },
       since: { type: "integer", minimum: 0 },
-      timeoutMs: { type: "number", exclusiveMinimum: 0 }
+      timeoutMs: { type: "number", exclusiveMinimum: 0 },
+      payloadMaxBytes: { type: "integer", exclusiveMinimum: 0 }
     },
     required: ["name"],
     additionalProperties: false
@@ -2745,169 +2872,108 @@ var rejectKinds = (args) => {
     );
   }
 };
-var isMatchPrimitive = (value) => {
-  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
-};
-var asOptionalMatch = (value) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new McpBuiltinToolError("invalid_request", '"match" must be a JSON object.');
-  }
-  const record = value;
-  for (const [key, entry] of Object.entries(record)) {
-    if (!isMatchPrimitive(entry)) {
-      throw new McpBuiltinToolError(
-        "invalid_request",
-        `"match.${key}" must be a string, number, boolean, or null (objects/arrays can never match).`
-      );
-    }
+var rejectMatch = (args) => {
+  if (args.match !== void 0) {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      '"match" is not supported: "name" is a glob, and a payload predicate is not offered on any surface \u2014 loop on appduct_wait_for_event with "since" instead.'
+    );
   }
-  return record;
+};
+var handleListEventsTool = async (rawArgs, call) => {
+  const args = asRecord3(rawArgs);
+  rejectUnknownKeys(args, LIST_EVENTS_TOOL_NAME, ["selector", "name", "limit", "offset"]);
+  const session = await resolveSession(call, asOptionalString(args.selector, "selector"));
+  const name = asOptionalString(args.name, "name");
+  const limit = args.limit ?? DEFAULT_LIST_EVENTS_LIMIT;
+  const result = await call(RPC_METHODS6.eventsList, {
+    selector: session.sessionId,
+    ...name !== void 0 ? { name } : {},
+    limit,
+    ...args.offset !== void 0 && args.offset !== null ? { offset: args.offset } : {}
+  });
+  const lookup = name !== void 0 && !name.includes("*");
+  return {
+    session: session.alias,
+    total: result.total,
+    limit,
+    events: result.events.map((event) => ({
+      name: event.name,
+      signature: renderEventSignature(event),
+      description: event.description,
+      ...lookup && event.payload_schema !== void 0 ? { payload_schema: event.payload_schema } : {}
+    }))
+  };
 };
 var handleEventsTool = async (rawArgs, deps) => {
   const args = asRecord3(rawArgs);
   rejectKinds(args);
-  return deps.call(RPC_METHODS5.eventsSince, {
+  const result = await deps.call(RPC_METHODS6.eventsSince, {
     selector: asOptionalString2(args.selector, "selector"),
     since: asOptionalNonNegativeInteger(args.since, "since"),
-    limit: asOptionalPositiveInteger(args.limit, "limit")
+    limit: asOptionalPositiveInteger(args.limit, "limit") ?? DEFAULT_EVENTS_LIMIT,
+    name: asOptionalString2(args.name, "name"),
+    // Issue #113: this tool always caps a payload, so a caller reading the result straight into
+    // its context can't be blown out by one gigantic app-pushed payload; `payloadMaxBytes` lets a
+    // caller raise or lower that default.
+    payloadMaxBytes: asOptionalPositiveInteger(args.payloadMaxBytes, "payloadMaxBytes") ?? DEFAULT_EVENTS_PAYLOAD_MAX_BYTES
   });
-};
-var payloadShallowMatches = (payload, match) => {
-  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
-    return false;
-  }
-  const record = payload;
-  return Object.entries(match).every(([key, value]) => record[key] === value);
+  return {
+    events: result.events.map((event) => event.sessionId === void 0 ? void 0 : toAppEvent2(event, event.sessionId)).filter((event) => event !== void 0),
+    cursor: result.cursor,
+    dropped: result.dropped,
+    remaining: result.remaining
+  };
 };
 var handleWaitForEventTool = async (rawArgs, deps) => {
   const args = asRecord3(rawArgs);
   rejectKinds(args);
+  rejectMatch(args);
   const selector = asOptionalString2(args.selector, "selector");
   const name = asOptionalString2(args.name, "name");
   if (!name) {
     throw new McpBuiltinToolError("invalid_request", '"name" must be a non-empty string.');
   }
-  const match = asOptionalMatch(args.match);
   const since = asOptionalNonNegativeInteger(args.since, "since");
   const timeoutMs = clampWaitForEventTimeoutMs(asOptionalPositiveNumber2(args.timeoutMs, "timeoutMs"));
+  const payloadMaxBytes = asOptionalPositiveInteger(args.payloadMaxBytes, "payloadMaxBytes") ?? DEFAULT_EVENTS_PAYLOAD_MAX_BYTES;
   const stream = await openDaemonStream({ stateDir: deps.stateDir, spawn: deps.spawn });
   try {
-    const described = await stream.call(RPC_METHODS5.sessionsDescribe, { selector });
-    const sessionId = described.sessionId;
-    const alias = described.alias;
-    const toResult = (event) => {
-      if (event.kind !== "app_event" || event.sessionId !== sessionId) {
-        return void 0;
-      }
-      const data = event.data;
-      if (data.name !== name) {
-        return void 0;
-      }
-      if (match && !payloadShallowMatches(data.payload, match)) {
-        return void 0;
-      }
-      return { sessionId, alias, name, payload: data.payload, ts: event.ts, seq: event.seq };
-    };
-    let liveHandler = null;
-    const earlyEvents = [];
-    const unsubscribeNotification = stream.onNotification((payload) => {
-      const event = payload;
-      if (liveHandler) {
-        liveHandler(event);
-      } else {
-        earlyEvents.push(event);
-      }
-    });
-    let unsubscribeClose = () => {
-    };
+    const described = await stream.call(RPC_METHODS6.sessionsDescribe, { selector });
+    const startedAt = Date.now();
+    const progressTimer = deps.progress ? setInterval(() => {
+      deps.progress.sendNotification({
+        method: "notifications/progress",
+        params: {
+          progressToken: deps.progress.token,
+          progress: Date.now() - startedAt,
+          total: timeoutMs,
+          message: `Still waiting for event "${name}"...`
+        }
+      }).catch(() => {
+      });
+    }, WAIT_FOR_EVENT_PROGRESS_INTERVAL_MS) : void 0;
     try {
-      await stream.call(RPC_METHODS5.eventsSubscribe, { sessionSelector: sessionId, kinds: ["app_event"] });
-      const sinceResult = await stream.call(RPC_METHODS5.eventsSince, {
-        selector: sessionId,
-        since
+      const { event, dropped } = await waitForAppEvent(stream, {
+        sessionId: described.sessionId,
+        name,
+        since,
+        timeoutMs,
+        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);
-        }
+      return { ...event, dropped };
+    } catch (error) {
+      if (error instanceof WaitForAppEventTimeoutError) {
+        throw new McpBuiltinToolError("tool_timeout", error.message);
       }
-      backlog.sort((a, b) => a.seq - b.seq);
-      for (const event of backlog) {
-        const result = toResult(event);
-        if (result) {
-          return result;
-        }
+      if (error instanceof WaitForAppEventConnectionClosedError) {
+        throw new McpBuiltinToolError("tool_execution_error", error.message);
       }
-      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);
-          if (progressTimer) {
-            clearInterval(progressTimer);
-          }
-          liveHandler = null;
-          fn();
-        };
-        const timer = setTimeout(() => {
-          settle(
-            () => reject(
-              new McpBuiltinToolError(
-                "tool_timeout",
-                `Timed out after ${timeoutMs}ms waiting for event "${name}".`
-              )
-            )
-          );
-        }, timeoutMs);
-        const startedAt = Date.now();
-        const progressTimer = deps.progress ? setInterval(() => {
-          deps.progress.sendNotification({
-            method: "notifications/progress",
-            params: {
-              progressToken: deps.progress.token,
-              progress: Date.now() - startedAt,
-              total: timeoutMs,
-              message: `Still waiting for event "${name}"...`
-            }
-          }).catch(() => {
-          });
-        }, WAIT_FOR_EVENT_PROGRESS_INTERVAL_MS) : void 0;
-        unsubscribeClose = stream.onClose(() => {
-          settle(
-            () => reject(
-              new McpBuiltinToolError(
-                "tool_execution_error",
-                `The connection to the Appduct daemon closed while waiting for event "${name}".`
-              )
-            )
-          );
-        });
-        liveHandler = (event) => {
-          if (settled) {
-            return;
-          }
-          if (event.sessionId === sessionId && event.seq <= highestConsideredSeq) {
-            return;
-          }
-          const result = toResult(event);
-          if (result) {
-            settle(() => resolve2(result));
-          }
-        };
-      });
+      throw error;
     } finally {
-      unsubscribeNotification();
-      unsubscribeClose();
+      if (progressTimer) {
+        clearInterval(progressTimer);
+      }
     }
   } finally {
     stream.close();
@@ -3047,7 +3113,7 @@ var createMcpServer = async (options) => {
     }
     if (progressToken === void 0) {
       const result = await stream.call(
-        RPC_METHODS6.toolsCall,
+        RPC_METHODS7.toolsCall,
         {
           selector: tool.sessionId,
           name: tool.descriptor.name,
@@ -3062,7 +3128,7 @@ var createMcpServer = async (options) => {
     }
     const progressStream = await openStream({ stateDir: options.stateDir, spawn: options.spawn });
     try {
-      await progressStream.call(RPC_METHODS6.eventsSubscribe, {
+      await progressStream.call(RPC_METHODS7.eventsSubscribe, {
         sessionSelector: tool.sessionId,
         kinds: ["tool_call_started", "tool_call_progress"]
       });
@@ -3072,7 +3138,7 @@ var createMcpServer = async (options) => {
         if (callId === void 0 || !cancelRequested) {
           return;
         }
-        progressStream.call(RPC_METHODS6.toolsCancel, { selector: tool.sessionId, callId, reason: "mcp_client_cancelled" }).catch((error) => {
+        progressStream.call(RPC_METHODS7.toolsCancel, { selector: tool.sessionId, callId, reason: "mcp_client_cancelled" }).catch((error) => {
           console.error("appduct mcp: failed to cancel an app tool call:", error);
         });
       };
@@ -3105,7 +3171,7 @@ var createMcpServer = async (options) => {
       });
       try {
         const result = await progressStream.call(
-          RPC_METHODS6.toolsCall,
+          RPC_METHODS7.toolsCall,
           {
             selector: tool.sessionId,
             name: tool.descriptor.name,
@@ -3133,6 +3199,7 @@ var createMcpServer = async (options) => {
         LIST_TOOLS_TOOL_DESCRIPTOR,
         DESCRIBE_TOOL_TOOL_DESCRIPTOR,
         CALL_TOOL_TOOL_DESCRIPTOR,
+        LIST_EVENTS_TOOL_DESCRIPTOR,
         EVENTS_TOOL_DESCRIPTOR,
         WAIT_FOR_EVENT_TOOL_DESCRIPTOR
       ]
@@ -3161,6 +3228,9 @@ var createMcpServer = async (options) => {
           await handleWaitForSessionTool(args, { stateDir: options.stateDir, spawn: options.spawn })
         );
       }
+      if (name === LIST_EVENTS_TOOL_NAME) {
+        return toolSuccessContent(await handleListEventsTool(args, stream.call));
+      }
       if (name === EVENTS_TOOL_NAME) {
         return toolSuccessContent(await handleEventsTool(args, { call: stream.call }));
       }
@@ -3217,7 +3287,7 @@ var createMcpServer = async (options) => {
     if (request.params.uri !== SESSIONS_RESOURCE_URI) {
       throw new Error(`Unknown resource "${request.params.uri}".`);
     }
-    const sessions = await stream.call(RPC_METHODS6.sessionsList);
+    const sessions = await stream.call(RPC_METHODS7.sessionsList);
     return {
       contents: [{ uri: SESSIONS_RESOURCE_URI, mimeType: "application/json", text: JSON.stringify(sessions) }]
     };
@@ -3309,6 +3379,7 @@ var formatJson = (value, flags) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature as renderEventSignature2,
   renderToolSignature as renderToolSignature2,
   summarizeToolDescription as summarizeToolDescription2
 } from "@appduct/shared";
@@ -3367,6 +3438,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."];
@@ -3375,7 +3453,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)
@@ -3389,9 +3467,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);
 };
@@ -3409,7 +3484,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)}.`;
 };
@@ -3491,7 +3566,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) => {
@@ -3543,18 +3618,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", renderEventSignature2(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) => [
+    `  ${renderEventSignature2(event)}`,
+    `    ${summarizeToolDescription2(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)];
 };
@@ -3738,15 +3857,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);

package/dist/cli/routes/sessions/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Route for `appduct sessions` — itself a router over the session verbs, so `sessions ls` loads
+ * only `ls.ts` (issue #96). cac matches only the noun (`cli/create-cli.ts`), so the verb arrives
+ * here as the first positional rather than as a cac command of its own — the same shape
+ * `routes/daemon/index.ts` already uses for `daemon status`.
+ */
+export declare const route: import("../../router.js").Route;