appduct 0.12.0 → 0.14.0

package/dist/cli/routes/events/tail.d.ts

@@ -0,0 +1,6 @@
+/** Route for `appduct events tail` — loaded by `routes/events/index.ts`'s router only when it
+ * runs (issue #96; replaces the removed `appduct events` streaming form). `--follow` is accepted
+ * (declared at the `events` noun level in `create-cli.ts`) but never read here: the default
+ * behavior already follows, so the flag exists only for script readability. */
+import type { Route } from "../../router.js";
+export declare const route: Route;

package/dist/cli/routes/{events.js → events/tail.js}

@@ -1015,12 +1015,14 @@ var handleEventsSinceCommand = async (options, context) => {
   try {
     const since = await stream.call(RPC_METHODS2.eventsSince, {
       selector: options.selector,
-      since: options.since
+      since: options.since,
+      name: options.name,
+      payloadMaxBytes: options.payloadMaxBytes
     });
     for (const event of since.events) {
       context.onEvent(event);
     }
-    context.onCursor?.(since.cursor);
+    context.onCursor?.({ cursor: since.cursor, dropped: since.dropped, remaining: since.remaining });
   } finally {
     stream.close();
   }
@@ -1035,7 +1037,9 @@ var handleEventsCommand = async (options, context) => {
   try {
     await stream.call(RPC_METHODS2.eventsSubscribe, {
       sessionSelector: options.selector,
-      kinds: ["app_event"]
+      kinds: ["app_event"],
+      name: options.name,
+      payloadMaxBytes: options.payloadMaxBytes
     });
   } catch (error) {
     stream.close();
@@ -1071,128 +1075,11 @@ var handleEventsCommand = async (options, context) => {
   };
 };
 
-// src/errors.ts
-var EXIT_CODE_BY_ERROR_TYPE = {
-  usage_error: 64,
-  validation_error: 65,
-  // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
-  // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
-  // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
-  // assertion failure (docs/tasks/08-appduct-doctor.md).
-  inspection_error: 66,
-  connection_error: 70,
-  session_error: 71,
-  tool_error: 72,
-  permission_error: 77,
-  internal_error: 1,
-  // `doctor --assert-present`/`--assert-absent`: the artifact was inspected successfully and the
-  // assertion did not hold. Distinct from `inspection_error` (66) — this means the answer is known
-  // and it's "no", not "couldn't tell" — and distinct from `internal_error` (1) so a caller can't
-  // conflate a normal assertion failure with an unexpected crash.
-  assertion_error: 3
-};
-var RPC_ERROR_EXIT_CLASS = {
-  no_session: "session_error",
-  ambiguous_session: "session_error",
-  unknown_session: "session_error",
-  session_not_active: "session_error",
-  session_suspended: "session_error",
-  tool_not_found: "tool_error",
-  tool_input_validation_error: "tool_error",
-  tool_output_validation_error: "tool_error",
-  tool_execution_error: "tool_error",
-  tool_serialization_error: "tool_error",
-  tool_timeout: "tool_error",
-  tool_cancelled: "tool_error",
-  policy_denied: "permission_error",
-  invalid_request: "validation_error"
-};
-var AppductCliError = class extends Error {
-  type;
-  details;
-  constructor(type, message, details) {
-    super(message);
-    this.name = "AppductCliError";
-    this.type = type;
-    this.details = details;
-  }
-};
-var usageError = (message, details) => {
-  return new AppductCliError("usage_error", message, details);
-};
-var isAppductCliError = (value) => {
-  return value instanceof AppductCliError;
-};
-var rpcErrorClass = (error) => {
-  const type = error.data?.type;
-  return type ? RPC_ERROR_EXIT_CLASS[type] : void 0;
-};
-var toCliError = (error) => {
-  if (isAppductCliError(error)) {
-    return {
-      type: error.type,
-      message: error.message,
-      details: error.details
-    };
-  }
-  if (error instanceof DaemonVersionMismatchError) {
-    return {
-      type: "connection_error",
-      message: error.message,
-      details: {
-        daemon_version: error.daemonVersion,
-        client_version: error.clientVersion,
-        session_count: error.sessionCount,
-        pending_link_count: error.pendingLinkCount
-      }
-    };
-  }
-  if (error instanceof DaemonRpcError && error.data?.type) {
-    return {
-      type: error.data.type,
-      message: error.message,
-      details: error.data.details
-    };
-  }
-  if (isDaemonUnreachableError(error)) {
-    return {
-      type: "connection_error",
-      message: error instanceof Error ? error.message : "The Appduct daemon is unreachable."
-    };
-  }
-  if (error instanceof Error) {
-    return {
-      type: "internal_error",
-      message: error.message
-    };
-  }
-  return {
-    type: "internal_error",
-    message: "An unexpected error occurred.",
-    details: error
-  };
-};
-var getExitCodeForError = (error) => {
-  if (isAppductCliError(error)) {
-    return EXIT_CODE_BY_ERROR_TYPE[error.type];
-  }
-  if (error instanceof DaemonVersionMismatchError) {
-    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
-  }
-  if (error instanceof DaemonRpcError) {
-    const cliErrorClass = rpcErrorClass(error);
-    return EXIT_CODE_BY_ERROR_TYPE[cliErrorClass ?? "internal_error"];
-  }
-  if (isDaemonUnreachableError(error)) {
-    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
-  }
-  return EXIT_CODE_BY_ERROR_TYPE.internal_error;
-};
-
 // src/output.ts
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -1293,6 +1180,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."];
@@ -1301,7 +1195,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)
@@ -1315,9 +1209,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);
 };
@@ -1335,7 +1226,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)}.`;
 };
@@ -1417,7 +1308,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) => {
@@ -1469,18 +1360,62 @@ var renderToolGroups = (colors, data) => {
     colors.green("Groups"),
     ...data.groups.map((entry) => `  ${label(entry).padEnd(width)}  ${String(entry.total).padStart(countWidth)}`),
     "",
-    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools --group <name>` to list one group's tools." : "No tool declares a group.")
+    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools ls --group <name>` to list one group's tools." : "No tool declares a group.")
   ];
 };
-var renderToolsData = (colors, data, flags, full) => {
+var renderToolsListData = (colors, data, flags, full) => {
   if (isToolGroupsListing(data)) {
     return renderToolGroups(colors, data);
   }
-  if (!isToolsListing(data)) {
-    return renderToolDetail(colors, data, flags);
-  }
   return full ? renderToolsFullListing(colors, data, flags) : renderToolSummaryTable(colors, data);
 };
+var renderEventsTruncationLine = (data) => {
+  const offset = data.offset ?? 0;
+  if (data.events.length >= data.total) {
+    return [];
+  }
+  return [
+    "",
+    `Showing ${data.events.length} of ${data.total} events (offset ${offset}). Narrow with --name <glob> or page with --offset <n>.`
+  ];
+};
+var renderEventsListData = (colors, data, flags) => {
+  const [only] = data.events;
+  if (data.name !== void 0 && !data.name.includes("*") && only !== void 0) {
+    return renderFields(
+      colors.green(`Event: ${only.name}`),
+      [
+        ["Signature", renderEventSignature(only)],
+        ["Description", only.description],
+        ["Payload schema", only.payload_schema]
+      ],
+      flags
+    );
+  }
+  if (data.events.length === 0 && data.total > 0) {
+    return [
+      colors.green("Events"),
+      `  No events at offset ${data.offset ?? 0}; ${data.total} matching event${data.total === 1 ? "" : "s"} in total.`
+    ];
+  }
+  if (data.events.length === 0) {
+    return [
+      colors.green("Events"),
+      data.name === void 0 ? "  No events declared." : `  No events match ${JSON.stringify(data.name)}.`
+    ];
+  }
+  const lines = data.events.flatMap((event) => [
+    `  ${renderEventSignature(event)}`,
+    `    ${summarizeToolDescription(event.description)}`
+  ]);
+  return [
+    colors.green("Events"),
+    ...lines,
+    ...renderEventsTruncationLine(data),
+    "",
+    "Run `appduct events ls --name <name>` for an event's full payload schema."
+  ];
+};
 var renderInvokeData = (colors, data, flags) => {
   return [colors.green("Result"), formatScalar(data, flags)];
 };
@@ -1664,15 +1599,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);
@@ -1742,25 +1681,158 @@ var renderEventLine = (event, flags) => {
   const dataSuffix = event.data === void 0 ? "" : ` ${formatJson(event.data, flags)}`;
   return `${colors.dim(timestamp)} ${colors.green(event.kind)}${target ? ` ${target}` : ""}${dataSuffix}`;
 };
-var renderEventsCursorLine = (cursor, flags) => {
-  if (flags.json) {
-    return JSON.stringify({ cursor });
+
+// src/errors.ts
+var EXIT_CODE_BY_ERROR_TYPE = {
+  usage_error: 64,
+  validation_error: 65,
+  // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
+  // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
+  // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
+  // assertion failure (docs/tasks/08-appduct-doctor.md).
+  inspection_error: 66,
+  connection_error: 70,
+  session_error: 71,
+  tool_error: 72,
+  permission_error: 77,
+  internal_error: 1,
+  // `doctor --assert-present`/`--assert-absent`: the artifact was inspected successfully and the
+  // assertion did not hold. Distinct from `inspection_error` (66) — this means the answer is known
+  // and it's "no", not "couldn't tell" — and distinct from `internal_error` (1) so a caller can't
+  // conflate a normal assertion failure with an unexpected crash.
+  assertion_error: 3
+};
+var RPC_ERROR_EXIT_CLASS = {
+  no_session: "session_error",
+  ambiguous_session: "session_error",
+  unknown_session: "session_error",
+  session_not_active: "session_error",
+  session_suspended: "session_error",
+  tool_not_found: "tool_error",
+  tool_input_validation_error: "tool_error",
+  tool_output_validation_error: "tool_error",
+  tool_execution_error: "tool_error",
+  tool_serialization_error: "tool_error",
+  tool_timeout: "tool_error",
+  tool_cancelled: "tool_error",
+  policy_denied: "permission_error",
+  invalid_request: "validation_error"
+};
+var AppductCliError = class extends Error {
+  type;
+  details;
+  constructor(type, message, details) {
+    super(message);
+    this.name = "AppductCliError";
+    this.type = type;
+    this.details = details;
   }
-  const colors = pc.createColors(flags.color);
-  return colors.dim(`cursor: ${cursor} (pass --since ${cursor} to resume from here)`);
+};
+var usageError = (message, details) => {
+  return new AppductCliError("usage_error", message, details);
+};
+var isAppductCliError = (value) => {
+  return value instanceof AppductCliError;
+};
+var rpcErrorClass = (error) => {
+  const type = error.data?.type;
+  return type ? RPC_ERROR_EXIT_CLASS[type] : void 0;
+};
+var toCliError = (error) => {
+  if (isAppductCliError(error)) {
+    return {
+      type: error.type,
+      message: error.message,
+      details: error.details
+    };
+  }
+  if (error instanceof DaemonVersionMismatchError) {
+    return {
+      type: "connection_error",
+      message: error.message,
+      details: {
+        daemon_version: error.daemonVersion,
+        client_version: error.clientVersion,
+        session_count: error.sessionCount,
+        pending_link_count: error.pendingLinkCount
+      }
+    };
+  }
+  if (error instanceof DaemonRpcError && error.data?.type) {
+    return {
+      type: error.data.type,
+      message: error.message,
+      details: error.data.details
+    };
+  }
+  if (isDaemonUnreachableError(error)) {
+    return {
+      type: "connection_error",
+      message: error instanceof Error ? error.message : "The Appduct daemon is unreachable."
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      type: "internal_error",
+      message: error.message
+    };
+  }
+  return {
+    type: "internal_error",
+    message: "An unexpected error occurred.",
+    details: error
+  };
+};
+var getExitCodeForError = (error) => {
+  if (isAppductCliError(error)) {
+    return EXIT_CODE_BY_ERROR_TYPE[error.type];
+  }
+  if (error instanceof DaemonVersionMismatchError) {
+    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
+  }
+  if (error instanceof DaemonRpcError) {
+    const cliErrorClass = rpcErrorClass(error);
+    return EXIT_CODE_BY_ERROR_TYPE[cliErrorClass ?? "internal_error"];
+  }
+  if (isDaemonUnreachableError(error)) {
+    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
+  }
+  return EXIT_CODE_BY_ERROR_TYPE.internal_error;
 };
 
 // src/cli/command-options.ts
-var parseNonNegativeIntegerOption = (value, flagName) => {
+var parsePositiveIntegerOption = (value, flagName) => {
   if (value === void 0) {
     return void 0;
   }
   const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
-  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 0) {
-    throw usageError(`"${flagName}" must be a non-negative integer.`);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
+    throw usageError(`"${flagName}" must be a positive integer.`);
   }
   return parsed;
 };
+var readTextOption = (argv, value, flagName) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value === "boolean") {
+    throw usageError(`"${flagName}" requires a value.`);
+  }
+  let raw;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") {
+      break;
+    }
+    if (token === flagName && index + 1 < argv.length) {
+      raw = argv[index + 1];
+      index += 1;
+    } else if (token.startsWith(`${flagName}=`)) {
+      raw = token.slice(flagName.length + 1);
+    }
+  }
+  return raw ?? String(Array.isArray(value) ? value.at(-1) : value);
+};
 var splitOptionalSelector = (args, commandUsage) => {
   if (args.length > 1) {
     throw usageError(`Usage: ${commandUsage} (too many arguments).`);
@@ -1874,33 +1946,33 @@ var guarded = (context) => {
   };
 };
 
-// src/cli/routes/events.ts
+// src/cli/routes/events/shared-options.ts
+var parseEventsFilterFlags = (context) => {
+  const { options } = context;
+  return {
+    name: readTextOption(context.argv, options.name, "--name"),
+    payloadMaxBytes: parsePositiveIntegerOption(options.payloadMaxBytes, "--payload-max-bytes")
+  };
+};
+
+// src/cli/routes/events/tail.ts
 var route = async (context) => {
-  const { options, stateDir, env } = context;
-  const follow = Boolean(options.follow);
+  const { stateDir, env } = context;
   return executeHostedCommand(
     commandName(context),
-    // All argument parsing happens inside the handler (not the route body) so
-    // `executeHostedCommand`'s own try/catch renders a bad argument as a normal usage_error
-    // instead of an uncaught rejection, and before the version check so a typo never waits on
-    // the daemon.
+    // Argument parsing runs inside the handler (not the route body) so `executeHostedCommand`'s
+    // own try/catch renders a bad argument as a normal usage_error instead of an uncaught
+    // rejection, and before the version check so a typo never waits on the daemon.
     () => {
-      const { selector } = splitOptionalSelector(context.args, "events [selector]");
-      const since = parseNonNegativeIntegerOption(options.since, "--since");
-      if (since !== void 0 && follow) {
-        throw usageError('"--since" is a one-shot pull and cannot be combined with "--follow".');
-      }
+      const { selector } = splitOptionalSelector(context.args, "events tail [selector]");
+      const { name, payloadMaxBytes } = parseEventsFilterFlags(context);
       return guarded(context)(
         () => handleEventsCommand(
-          { selector, since },
+          { selector, name, payloadMaxBytes },
           {
             stateDir,
             onEvent: (event) => {
               env.stdout.write(`${renderEventLine(event, env.flags)}
-`);
-            },
-            onCursor: (cursor) => {
-              env.stdout.write(`${renderEventsCursorLine(cursor, env.flags)}
 `);
             }
           }

package/dist/cli/routes/init.js

@@ -841,10 +841,10 @@ Run \`appduct init --scheme <scheme>\` with the scheme your app registers for de
       nextSteps: [
         'Add `import "@appduct/react-native/auto";` to your app entry (index.js / App.tsx) \u2014 it is what starts the in-app agent endpoint.',
         `Add the Appduct MCP server entry to your agent's MCP config. "--scheme ${scheme}" keeps that entry self-contained; ${SCHEME_ENV_VAR} and this ${PROJECT_CONFIG_RELATIVE_PATH} work too.`,
-        "With the app running, pair a device: `appduct link --open ios-sim` (or `--open android`).",
+        "With the app running, pair a device: `appduct sessions link --open ios-sim` (or `--open android`).",
         ...origin === void 0 ? [] : [`Scheme "${scheme}" was read from ${origin}.`],
         ...iosAppId === void 0 && androidAppId === void 0 ? [
-          "Delivering to a physical iPhone (`--open ios-device`) or an Android device/emulator (`--open android`) needs the installed app's id: run `appduct init --ios-app-id <id> --android-app-id <id>`, or pass --app-id on `appduct link`."
+          "Delivering to a physical iPhone (`--open ios-device`) or an Android device/emulator (`--open android`) needs the installed app's id: run `appduct init --ios-app-id <id> --android-app-id <id>`, or pass --app-id on `appduct sessions link`."
         ] : [],
         `This file is safe to commit \u2014 it holds only "scheme" and "appId". Do not point --state-dir at this directory: the state dir holds the daemon's private key and audit log, which must never be committed.`
       ]
@@ -861,6 +861,7 @@ var formatJson = (value, flags) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -956,6 +957,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."];
@@ -964,7 +972,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)
@@ -978,9 +986,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);
 };
@@ -998,7 +1003,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)}.`;
 };
@@ -1080,7 +1085,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) => {
@@ -1132,18 +1137,62 @@ var renderToolGroups = (colors, data) => {
     colors.green("Groups"),
     ...data.groups.map((entry) => `  ${label(entry).padEnd(width)}  ${String(entry.total).padStart(countWidth)}`),
     "",
-    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools --group <name>` to list one group's tools." : "No tool declares a group.")
+    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools ls --group <name>` to list one group's tools." : "No tool declares a group.")
   ];
 };
-var renderToolsData = (colors, data, flags, full) => {
+var renderToolsListData = (colors, data, flags, full) => {
   if (isToolGroupsListing(data)) {
     return renderToolGroups(colors, data);
   }
-  if (!isToolsListing(data)) {
-    return renderToolDetail(colors, data, flags);
-  }
   return full ? renderToolsFullListing(colors, data, flags) : renderToolSummaryTable(colors, data);
 };
+var renderEventsTruncationLine = (data) => {
+  const offset = data.offset ?? 0;
+  if (data.events.length >= data.total) {
+    return [];
+  }
+  return [
+    "",
+    `Showing ${data.events.length} of ${data.total} events (offset ${offset}). Narrow with --name <glob> or page with --offset <n>.`
+  ];
+};
+var renderEventsListData = (colors, data, flags) => {
+  const [only] = data.events;
+  if (data.name !== void 0 && !data.name.includes("*") && only !== void 0) {
+    return renderFields(
+      colors.green(`Event: ${only.name}`),
+      [
+        ["Signature", renderEventSignature(only)],
+        ["Description", only.description],
+        ["Payload schema", only.payload_schema]
+      ],
+      flags
+    );
+  }
+  if (data.events.length === 0 && data.total > 0) {
+    return [
+      colors.green("Events"),
+      `  No events at offset ${data.offset ?? 0}; ${data.total} matching event${data.total === 1 ? "" : "s"} in total.`
+    ];
+  }
+  if (data.events.length === 0) {
+    return [
+      colors.green("Events"),
+      data.name === void 0 ? "  No events declared." : `  No events match ${JSON.stringify(data.name)}.`
+    ];
+  }
+  const lines = data.events.flatMap((event) => [
+    `  ${renderEventSignature(event)}`,
+    `    ${summarizeToolDescription(event.description)}`
+  ]);
+  return [
+    colors.green("Events"),
+    ...lines,
+    ...renderEventsTruncationLine(data),
+    "",
+    "Run `appduct events ls --name <name>` for an event's full payload schema."
+  ];
+};
 var renderInvokeData = (colors, data, flags) => {
   return [colors.green("Result"), formatScalar(data, flags)];
 };
@@ -1327,15 +1376,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);