appduct 0.12.0 → 0.13.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,10 +2656,114 @@ var resolveAppTool = async (call, selector, name) => {
 
 // src/mcp/events-tool.ts
 import {
-  RPC_METHODS as RPC_METHODS5
+  RPC_METHODS as RPC_METHODS6,
+  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 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_WAIT_FOR_EVENT_TIMEOUT_MS = 12e4;
 var MAX_WAIT_FOR_EVENT_TIMEOUT_MS = 25 * 60 * 1e3;
 var WAIT_FOR_EVENT_PROGRESS_INTERVAL_MS = 6e4;
@@ -2668,28 +2772,30 @@ var clampWaitForEventTimeoutMs = (requestedMs) => {
 };
 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 +2851,83 @@ 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 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 +3067,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 +3082,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 +3092,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 +3125,7 @@ var createMcpServer = async (options) => {
       });
       try {
         const result = await progressStream.call(
-          RPC_METHODS6.toolsCall,
+          RPC_METHODS7.toolsCall,
           {
             selector: tool.sessionId,
             name: tool.descriptor.name,
@@ -3217,7 +3237,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) }]
     };
@@ -3389,9 +3409,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 +3426,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 +3508,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,16 +3560,13 @@ 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 renderInvokeData = (colors, data, flags) => {
@@ -3738,15 +3752,17 @@ 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 "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;