appduct 0.13.0 → 0.15.0

package/dist/cli/routes/mcp.js

@@ -14,6 +14,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "daemonLogMaxBytes",
   "eventsLogMaxBytes",
   "policy",
+  "webOrigins",
   "advertisedIp",
   "scheme",
   "restartDaemonOnVersionMismatch"
@@ -74,6 +75,7 @@ var defaultConfig = (paths) => {
     daemonLogMaxBytes: DEFAULT_DAEMON_LOG_MAX_BYTES,
     eventsLogMaxBytes: 10 * 1024 * 1024,
     restartDaemonOnVersionMismatch: false,
+    webOrigins: [],
     policy: {
       default: "allow",
       destructive: "allow"
@@ -144,6 +146,12 @@ var loadConfig = async (paths, options = {}) => {
       "restartDaemonOnVersionMismatch"
     );
   }
+  if (parsed.webOrigins !== void 0) {
+    if (!Array.isArray(parsed.webOrigins)) {
+      throw configError("webOrigins", "must be an array of origin strings.");
+    }
+    config.webOrigins = parsed.webOrigins.map((origin) => requireNonEmptyString(origin, "webOrigins"));
+  }
   if (parsed.policy !== void 0) {
     if (typeof parsed.policy !== "object" || parsed.policy === null || Array.isArray(parsed.policy)) {
       throw configError("policy", "must be an object.");
@@ -1069,7 +1077,7 @@ var EXIT_CODE_BY_ERROR_TYPE = {
   // 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).
+  // assertion failure.
   inspection_error: 66,
   connection_error: 70,
   session_error: 71,
@@ -1829,23 +1837,34 @@ var probeIosProjectYml = async (root) => {
   };
 };
 var PROBES = [
-  probeAndroidGradle,
-  probeAndroidManifest,
-  probeIosInfoPlist,
-  probeIosProjectYml
+  ["android", probeAndroidGradle],
+  ["android", probeAndroidManifest],
+  ["ios", probeIosInfoPlist],
+  ["ios", probeIosProjectYml]
 ];
+var isFlutterProject = async (root) => {
+  return (await readCappedText(join5(root, "pubspec.yaml"))).ok;
+};
 var discoverNativeScheme = async (root) => {
   const tried = [];
   const results = [];
-  for (const probe of PROBES) {
-    const outcome = await probe(root);
-    tried.push(...outcome.tried);
-    if (outcome.result !== void 0) {
-      results.push(outcome.result);
+  const flutter = await isFlutterProject(root);
+  const androidRoot = flutter ? join5(root, "android") : root;
+  const iosRoots = flutter ? [join5(root, "ios"), join5(root, "macos")] : [root];
+  for (const [platform, probe] of PROBES) {
+    let roots = [root];
+    if (platform === "android") {
+      roots = [androidRoot];
+    } else if (probe === probeIosInfoPlist) {
+      roots = iosRoots;
+    }
+    for (const probeRoot of roots) {
+      const outcome = await probe(probeRoot);
+      tried.push(...outcome.tried);
+      if (outcome.result !== void 0) {
+        results.push(outcome.result);
+      }
     }
-  }
-  if (results.length === 0) {
-    return { tried };
   }
   const distinctSchemes = new Set(results.map((entry) => entry.scheme));
   if (distinctSchemes.size > 1) {
@@ -1853,7 +1872,7 @@ var discoverNativeScheme = async (root) => {
       "Conflicting deep-link schemes found in this project: " + results.map((entry) => `${entry.origin} says ${JSON.stringify(entry.scheme)}`).join(", but ") + ". Appduct will not guess which one is right \u2014 pass --scheme <scheme> to pick one."
     );
   }
-  return { result: results[0], tried };
+  return { results, tried };
 };
 
 // src/scheme.ts
@@ -1916,19 +1935,21 @@ var discoverStaticProjectScheme = async (cwd) => {
   const tried = [`${appJsonPath} ("expo.scheme")`];
   const appJsonScheme = await discoverExpoScheme(cwd);
   if (appJsonScheme !== void 0) {
-    return { scheme: appJsonScheme, source: "app-json", origin: appJsonPath, tried };
+    return { scheme: appJsonScheme, source: "app-json", origin: appJsonPath, nativeResults: [], tried };
   }
   const native = await discoverNativeScheme(resolve(cwd));
   tried.push(...native.tried);
-  if (native.result !== void 0) {
+  const [first] = native.results;
+  if (first !== void 0) {
     return {
-      scheme: native.result.scheme,
-      source: native.result.source,
-      origin: native.result.origin,
+      scheme: first.scheme,
+      source: first.source,
+      origin: first.origin,
+      nativeResults: native.results,
       tried
     };
   }
-  return { tried };
+  return { nativeResults: [], tried };
 };
 var globalConfigDirs = (options = {}) => {
   const excluded = /* @__PURE__ */ new Set([join6(resolve(options.homeDir ?? homedir()), PROJECT_CONFIG_DIR)]);
@@ -2104,6 +2125,25 @@ ${tried.map((location, index) => `  ${index + 1}. ${location}`).join("\n")}
 
 // src/link.ts
 var composeDeepLink = (scheme, result) => `${scheme}:///?appduct=${result.deepLinkPayload}&pin=${encodeURIComponent(result.pin)}`;
+var assertWebPageUrl = (pageUrl) => {
+  let protocol;
+  try {
+    protocol = new URL(pageUrl).protocol;
+  } catch {
+  }
+  if (protocol !== "http:" && protocol !== "https:") {
+    throw usageError(`"url" must be an http(s) URL (got "${pageUrl}").`);
+  }
+};
+var composeWebLink = (pageUrl, result) => {
+  const payload = result.deepLinkPayload;
+  return {
+    sessionId: result.sessionId,
+    url: `${pageUrl.split("#")[0]}#appduct=${payload}`,
+    script: `window.__APPDUCT__.connect("${payload}")`,
+    expiresAt: result.expiresAt
+  };
+};
 
 // src/qr-terminal.ts
 import { toQR } from "toqr";
@@ -2146,14 +2186,18 @@ var WAIT_FOR_SESSION_TOOL_NAME = "appduct_wait_for_session";
 var OPEN_TARGET_ADDRESS_OVERRIDE = "127.0.0.1";
 var DEFAULT_WAIT_TIMEOUT_MS = 12e4;
 var NO_TARGET = "none";
+var WEB_TARGET = "web";
 var QR_INSTRUCTIONS = 'This link was NOT delivered to a device \u2014 a human has to open it. Before calling appduct_wait_for_session: show the user the "qr" field verbatim inside a fenced code block (it is pre-rendered terminal art \u2014 do not redraw, summarize, or describe it), show "deepLink" underneath it for a device that cannot scan, and ask the user to scan it with the target device. Only then call appduct_wait_for_session; it blocks until the device connects and gives no output while it waits, so calling it before you have asked will look like a hang.';
 var CONNECT_TOOL_DESCRIPTOR = {
   name: CONNECT_TOOL_NAME,
-  description: 'Mint an Appduct session link and get it onto a device. With no "target", auto-detects a booted iOS simulator or attached Android device and delivers the link to it, returning { sessionId, delivered: true, autoDetected: true } \u2014 this is the normal agent path and needs no human. Pass target "android" or "ios-sim" (optionally with "device") to choose explicitly, or target "none" to force the human flow. Delivering to "android" (explicit or auto-detected) needs "appId" (the Android package name) \u2014 without it, more than one installed app declaring the same scheme would show an ambiguous "Open with" chooser on the device instead of failing loudly. Target "ios-device" is an experimental, never-auto-detected path that delivers to a paired physical iPhone/iPad via xcrun devicectl; it needs "appId" (the iOS bundle id), iOS 17+, Xcode 15+, a connected and trusted device with Developer Mode on, a dev-signed build installed, and the phone on the same network as this machine. An "appId" not supplied here falls back to "appId.<platform>" in the nearest .appduct/config.json (see "appduct init"); it is rejected outright with target "ios-sim" or "none", which need no app id. Pass "relaunch": true with ios-device if the app is already running and the delivery does not take. Only when no device is detected (or target is "none") does this return a QR code for a human to scan, along with an "instructions" field saying what to do with it. Follow up with appduct_wait_for_session to know when the device has connected.',
+  description: `Mint an Appduct session link and get it onto a device. With no "target", auto-detects a booted iOS simulator or attached Android device and delivers the link to it, returning { sessionId, delivered: true, autoDetected: true } \u2014 this is the normal agent path and needs no human. Pass target "android" or "ios-sim" (optionally with "device") to choose explicitly, or target "none" to force the human flow. Delivering to "android" (explicit or auto-detected) needs "appId" (the Android package name) \u2014 without it, more than one installed app declaring the same scheme would show an ambiguous "Open with" chooser on the device instead of failing loudly. Target "ios-device" is an experimental, never-auto-detected path that delivers to a paired physical iPhone/iPad via xcrun devicectl; it needs "appId" (the iOS bundle id), iOS 17+, Xcode 15+, a connected and trusted device with Developer Mode on, a dev-signed build installed, and the phone on the same network as this machine. An "appId" not supplied here falls back to "appId.<platform>" in the nearest .appduct/config.json (see "appduct init"); it is rejected outright with target "ios-sim" or "none", which need no app id. Pass "relaunch": true with ios-device if the app is already running and the delivery does not take. Target "web" is for a web page: pass "url" (the page to open) and get back { url, script } \u2014 open "url" in a browser, or run "script" in a page that is already open, then call appduct_wait_for_session. It needs no scheme and no device. To have the daemon attach a page that is already open in a Chrome launched with --remote-debugging-port, also pass "browserUrl" (its debugging endpoint on this machine: 127.0.0.1, [::1] or localhost, such as http://127.0.0.1:9222): the tab whose address starts with "url" is attached and the call returns { sessionId, url, targetId, attached: true }, with no further step; "url" is the tab's own address. When no tab or several match, the error lists the open tabs with their target ids; pass one as "targetId" to pick it. A popup, or a page in a new tab, is not attached. Only when no device is detected (or target is "none") does this return a QR code for a human to scan, along with an "instructions" field saying what to do with it. Follow up with appduct_wait_for_session to know when the device has connected.`,
   inputSchema: {
     type: "object",
     properties: {
-      target: { type: "string", enum: ["android", "ios-sim", "ios-device", NO_TARGET] },
+      target: { type: "string", enum: ["android", "ios-sim", "ios-device", NO_TARGET, WEB_TARGET] },
+      url: { type: "string" },
+      browserUrl: { type: "string" },
+      targetId: { type: "string" },
       device: { type: "string" },
       appId: { type: "string" },
       relaunch: { type: "boolean" },
@@ -2192,10 +2236,10 @@ var asOptionalConnectTarget = (value) => {
   if (value === void 0) {
     return void 0;
   }
-  if (typeof value !== "string" || !(isOpenTarget(value) || value === NO_TARGET)) {
+  if (typeof value !== "string" || !(isOpenTarget(value) || value === NO_TARGET || value === WEB_TARGET)) {
     throw new McpBuiltinToolError(
       "invalid_request",
-      '"target" must be "android", "ios-sim", "ios-device", or "none".'
+      '"target" must be "android", "ios-sim", "ios-device", "web", or "none".'
     );
   }
   return value;
@@ -2273,6 +2317,42 @@ var handleConnectTool = async (rawArgs, deps) => {
   const appId = asOptionalNonEmptyString(args.appId, "appId");
   const relaunch = asOptionalBoolean(args.relaunch, "relaunch");
   const ttlSeconds = asOptionalPositiveNumber(args.ttlSeconds, "ttlSeconds");
+  const url = asOptionalNonEmptyString(args.url, "url");
+  const browserUrl = asOptionalNonEmptyString(args.browserUrl, "browserUrl");
+  const targetId = asOptionalNonEmptyString(args.targetId, "targetId");
+  if ((browserUrl !== void 0 || targetId !== void 0) && requestedTarget !== WEB_TARGET) {
+    throw new McpBuiltinToolError("invalid_request", '"browserUrl" and "targetId" only apply with target "web".');
+  }
+  if (targetId !== void 0 && browserUrl === void 0) {
+    throw new McpBuiltinToolError("invalid_request", '"targetId" needs "browserUrl": it names a tab of that browser.');
+  }
+  if (requestedTarget === WEB_TARGET) {
+    if (url === void 0) {
+      throw new McpBuiltinToolError("invalid_request", '"url" (the page to open) is required with target "web".');
+    }
+    if (device !== void 0 || appId !== void 0 || relaunch !== void 0) {
+      throw new McpBuiltinToolError(
+        "invalid_request",
+        '"device", "appId" and "relaunch" do not apply with target "web".'
+      );
+    }
+    try {
+      assertWebPageUrl(url);
+    } catch (error) {
+      throw new McpBuiltinToolError("invalid_request", error.message);
+    }
+    if (browserUrl !== void 0) {
+      const attached = await deps.call(RPC_METHODS3.webAttach, { url, browserUrl, targetId, ttlSeconds });
+      return { ...attached, attached: true };
+    }
+    return composeWebLink(
+      url,
+      await deps.call(RPC_METHODS3.linkCreate, { ttlSeconds, transport: "web" })
+    );
+  }
+  if (url !== void 0) {
+    throw new McpBuiltinToolError("invalid_request", '"url" only applies with target "web".');
+  }
   if (device !== void 0 && (requestedTarget === void 0 || requestedTarget === NO_TARGET)) {
     throw new McpBuiltinToolError(
       "invalid_request",
@@ -2657,6 +2737,7 @@ var resolveAppTool = async (call, selector, name) => {
 // src/mcp/events-tool.ts
 import {
   RPC_METHODS as RPC_METHODS6,
+  renderEventSignature,
   toAppEvent as toAppEvent2
 } from "@appduct/shared";
 
@@ -2760,16 +2841,36 @@ var waitForAppEvent = async (stream, options) => {
 };
 
 // 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. 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.`,
@@ -2859,6 +2960,31 @@ var rejectMatch = (args) => {
     );
   }
 };
+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);
@@ -3153,6 +3279,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
       ]
@@ -3181,6 +3308,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 }));
       }
@@ -3329,6 +3459,7 @@ var formatJson = (value, flags) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature as renderEventSignature2,
   renderToolSignature as renderToolSignature2,
   summarizeToolDescription as summarizeToolDescription2
 } from "@appduct/shared";
@@ -3387,6 +3518,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."];
@@ -3395,7 +3533,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)
@@ -3569,10 +3707,87 @@ 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", 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)];
 };
 var renderLinkData = (colors, data, flags, qr) => {
+  if ("attached" in data) {
+    return [
+      colors.green("Page Attached"),
+      ...renderFields(
+        "Page",
+        [
+          ["Session", data.sessionId],
+          ["Tab", data.targetId],
+          ["URL", data.url],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
+  if ("script" in data) {
+    return [
+      colors.green("Link Created"),
+      ...renderFields(
+        "Link",
+        [
+          ["Session", data.sessionId],
+          ["URL", data.url],
+          ["Script", data.script],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
   const lines = [
     colors.green("Link Created"),
     ...renderFields(
@@ -3693,6 +3908,7 @@ var renderDaemonStatusData = (colors, data, flags) => {
         ["PID", data.daemon.pid],
         ["Started at", data.daemon.started_at],
         ["WSS port", data.daemon.wss_port],
+        ["Web port", data.daemon.web_port],
         ["Pinned keys", data.daemon.pinned_keys.length],
         ["Sessions", data.daemon.session_count]
       ],
@@ -3760,6 +3976,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/sessions/index.js

@@ -93,7 +93,7 @@ var EXIT_CODE_BY_ERROR_TYPE = {
   // 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).
+  // assertion failure.
   inspection_error: 66,
   connection_error: 70,
   session_error: 71,
@@ -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,10 +498,87 @@ 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)];
 };
 var renderLinkData = (colors, data, flags, qr) => {
+  if ("attached" in data) {
+    return [
+      colors.green("Page Attached"),
+      ...renderFields(
+        "Page",
+        [
+          ["Session", data.sessionId],
+          ["Tab", data.targetId],
+          ["URL", data.url],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
+  if ("script" in data) {
+    return [
+      colors.green("Link Created"),
+      ...renderFields(
+        "Link",
+        [
+          ["Session", data.sessionId],
+          ["URL", data.url],
+          ["Script", data.script],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
   const lines = [
     colors.green("Link Created"),
     ...renderFields(
@@ -614,6 +699,7 @@ var renderDaemonStatusData = (colors, data, flags) => {
         ["PID", data.daemon.pid],
         ["Started at", data.daemon.started_at],
         ["WSS port", data.daemon.wss_port],
+        ["Web port", data.daemon.web_port],
         ["Pinned keys", data.daemon.pinned_keys.length],
         ["Sessions", data.daemon.session_count]
       ],
@@ -681,6 +767,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":