appduct 0.13.0 → 0.15.0

package/dist/daemon/daemon.d.ts

@@ -7,10 +7,11 @@
  * recorded to the audit log inline in the `tools.call` handler below.
  */
 import type { Clock } from "../cli/types.js";
+import { type ConnectDevtoolsBrowser } from "../devtools-relay/index.js";
 import { detectAdvertisedAddress } from "./address.js";
 import { type AppductConfig, type ConfigWarnFn } from "./config.js";
 import { type EventBus } from "./event-bus.js";
-import { type DaemonListener } from "./listener.js";
+import { type DaemonListener, type WebListener } from "./listener.js";
 import { type RpcServer } from "./rpc-server.js";
 import { type StateDirPaths } from "./state-dir.js";
 import { type TimerFns } from "./timers.js";
@@ -27,6 +28,8 @@ export type DaemonOptions = {
      * `config.advertisedIp`. Overridable so tests can simulate a network change between two
      * `link.create` calls without mocking `os.networkInterfaces()` process-wide. */
     detectAddress?: () => ReturnType<typeof detectAdvertisedAddress>;
+    /** Reaches a debugging-port browser for `web.attach`; defaults to raw CDP over `ws`. */
+    connectDevtoolsBrowser?: ConnectDevtoolsBrowser;
 };
 export type RunningDaemon = {
     paths: StateDirPaths;
@@ -34,6 +37,8 @@ export type RunningDaemon = {
     startedAt: Date;
     server: RpcServer;
     listener: DaemonListener;
+    /** The plain-HTTP listener web pages connect to. */
+    webListener: WebListener;
     /** The host certificate the listener serves, so an in-process client can trust it. */
     tls: TlsManager;
     eventBus: EventBus;

package/dist/daemon/event-bus.d.ts

@@ -28,6 +28,16 @@ export type ProjectAppEventOptions = {
     /** Caps the payload's JSON to this many UTF-8 bytes (issue #113); see {@link truncateToUtf8Bytes}. */
     payloadMaxBytes?: number;
 };
+/** Whether `name` matches the whole-name glob `pattern` (`*` matches any run of characters,
+ * everything else literally), in time linear in the two strings' lengths.
+ *
+ * No regex and no backtracking: the daemon is single-threaded, so a match that blows up blocks
+ * every session and RPC client (issue #112 review). Compiling `*` to `.*` was exponential in the
+ * star count, and a two-pointer matcher that backtracks to the last `*` was still quadratic.
+ * Instead the pattern is split on `*`: the first piece must be a prefix, the last a suffix, and
+ * each middle piece is found in order with `indexOf`. Taking the leftmost occurrence of each
+ * middle piece is always safe, because it leaves the most room for the pieces after it. */
+export declare const matchesNameGlob: (pattern: string, name: string) => boolean;
 /**
  * Whether `event` survives `options.name`'s glob, and truncates its payload to `options
  * .payloadMaxBytes` when given — the one implementation `since()`'s drain and `daemon.ts`'s

package/dist/daemon/links.d.ts

@@ -5,7 +5,7 @@
  * Pending links are cheap and re-issuable — they are never persisted and never appear in
  * `sessions.list`/`sessions.describe` (only claimed sessions do; see sessions.ts).
  */
-import { type AgentEndpoint } from "@appduct/shared";
+import { type AgentEndpoint, type LinkTransport } from "@appduct/shared";
 import type { Clock } from "../cli/types.js";
 import type { EventBus } from "./event-bus.js";
 import type { TimerFns } from "./timers.js";
@@ -15,6 +15,8 @@ export type PendingLink = {
     token: Buffer;
     createdAt: Date;
     expiresAt: Date;
+    /** The listener this link can be claimed on, and only that one. */
+    transport: LinkTransport;
 };
 export type CreatedLink = {
     link: PendingLink;
@@ -22,8 +24,9 @@ export type CreatedLink = {
     endpoint: AgentEndpoint;
 };
 export type PendingLinkRegistryOptions = {
-    /** Resolves the current advertised endpoint at mint time (address may be re-detected). */
-    getEndpoint: () => AgentEndpoint;
+    /** Resolves the current advertised endpoint of a transport at mint time (the native address may
+     * be re-detected). */
+    getEndpoint: (transport: LinkTransport) => AgentEndpoint;
     clock: Clock;
     timers: TimerFns;
     eventBus: EventBus;
@@ -31,8 +34,9 @@ export type PendingLinkRegistryOptions = {
 export type PendingLinkRegistry = {
     /** `addressOverride` forces the endpoint address encoded into this one link's bootstrap payload
      * (the emulator/simulator fast path: `127.0.0.1`), leaving the detected endpoint used by
-     * every other link unaffected. */
-    create: (ttlSeconds: number, addressOverride?: string) => CreatedLink;
+     * every other link unaffected. It does not apply to a `web` link, whose address is always the
+     * loopback one the web listener binds. */
+    create: (ttlSeconds: number, addressOverride?: string, transport?: LinkTransport) => CreatedLink;
     /** Looks up a pending link without consuming it (used to distinguish "unknown" from "already claimed"). */
     get: (sessionId: string) => PendingLink | undefined;
     /** Removes and returns the link (successful claim consumes its single use). */

package/dist/daemon/listener.d.ts

@@ -1,5 +1,6 @@
 /**
- * The pinned-TLS WebSocket listener (ARCHITECTURE.md §7). A thin frame-level gate in front of
+ * The pinned-TLS WebSocket listener and the plain-HTTP web listener (ARCHITECTURE.md §7). Both put
+ * the same thin frame-level gate in front of
  * `SessionManager`: JSON/binary/size hygiene, the pre-claim timeout, and post-claim
  * type/session-id routing. All state-machine decisions (claim/resume/registry/close-code choice)
  * live in sessions.ts — this module never inspects session state itself.
@@ -14,7 +15,13 @@ import { type SessionManager } from "./sessions.js";
 import type { TlsManager, TlsMaterial } from "./tls.js";
 import { type TimerFns } from "./timers.js";
 export type ListenerOptions = {
+    /** `0` asks the OS for a free port. */
     port: number;
+    /** Also bind `127.0.0.1` on the same port (issue #249). macOS lets another program bind
+     * `127.0.0.1:<port>` under a wildcard listener and then routes loopback clients to it; holding
+     * that address ourselves stops it. Linux refuses that bind for everyone, us included, because
+     * the wildcard listener already covers loopback there. */
+    bindLoopback: boolean;
     tls: TlsManager;
     sessionManager: SessionManager;
     preClaimTimeoutMs?: number;
@@ -31,3 +38,23 @@ export type DaemonListener = {
     close: () => Promise<void>;
 };
 export declare const startListener: (options: ListenerOptions) => Promise<DaemonListener>;
+export type WebListenerOptions = {
+    sessionManager: SessionManager;
+    /** Origins allowed in addition to localhost, `127.0.0.1` and `[::1]` on any port. Compared
+     * as exact strings against the `Origin` header (`config.json`'s `webOrigins`). */
+    origins: readonly string[];
+    preClaimTimeoutMs?: number;
+    timers?: TimerFns;
+};
+export type WebListener = {
+    port: () => number | undefined;
+    close: () => Promise<void>;
+};
+/**
+ * The plain-HTTP listener web pages connect to, bound to `127.0.0.1` on an OS-assigned port. A
+ * browser cannot pin the daemon's self-signed certificate, so it cannot use the TLS listener.
+ * Instead every upgrade is checked against its `Origin` header and refused with 403 unless that
+ * is a loopback origin or listed in `origins`. A request with no `Origin` is let through: only a
+ * local non-browser process sends none, and it could connect to the daemon anyway.
+ */
+export declare const startWebListener: (options: WebListenerOptions) => Promise<WebListener>;

package/dist/daemon/registry.d.ts

@@ -1,18 +1,26 @@
 /**
- * Per-session tool registry (ARCHITECTURE.md §7). Callers (sessions.ts/listener.ts) must validate
- * incoming `tool_registry_snapshot`/`tool_registry_delta` wire messages with the shared guards
- * *before* calling into this module — v1 crashed by indexing into an unvalidated `tools: [null]`
- * snapshot; this module only ever stores already-validated {@link ToolDescriptor}s.
+ * Per-session registry of what an app declared, by name (ARCHITECTURE.md §7): one instance holds a
+ * session's tools, another its events (issue #124). Callers (sessions.ts) must validate incoming
+ * `tool_registry_*`/`event_registry_*` wire messages with the shared guards *before* calling into
+ * this module — v1 crashed by indexing into an unvalidated `tools: [null]` snapshot; this module
+ * only ever stores already-validated descriptors.
  */
-import type { ToolDescriptor } from "@appduct/shared";
-export type ToolRegistry = {
+import type { EventDescriptor, ToolDescriptor } from "@appduct/shared";
+export type Registry<T extends {
+    name: string;
+}> = {
     /** Authoritative replace: used for the initial snapshot and every post-resume re-sync. */
-    snapshot: (tools: ToolDescriptor[]) => void;
-    upsert: (tool: ToolDescriptor) => void;
+    snapshot: (items: T[]) => void;
+    upsert: (item: T) => void;
     remove: (name: string) => void;
-    list: () => ToolDescriptor[];
-    get: (name: string) => ToolDescriptor | undefined;
+    list: () => T[];
+    get: (name: string) => T | undefined;
     count: () => number;
 };
-/** `onChange` fires after every mutation (snapshot/upsert/remove) — used to emit `tools_changed`. */
-export declare const createToolRegistry: (onChange?: () => void) => ToolRegistry;
+export type ToolRegistry = Registry<ToolDescriptor>;
+export type EventRegistry = Registry<EventDescriptor>;
+/** `onChange` fires after every mutation (snapshot/upsert/remove) — used to emit `tools_changed`
+ * and `events_changed`. */
+export declare const createRegistry: <T extends {
+    name: string;
+}>(onChange?: () => void) => Registry<T>;

package/dist/daemon/rpc-errors.d.ts

@@ -14,3 +14,9 @@ export declare class RpcApplicationError extends Error {
     /** JSON-RPC error code; defaults to the shared "server error" range. */
     code?: number, details?: unknown | undefined);
 }
+/** The `session_suspended` message for an app that closed its socket because it went to the
+ * background: says why and how to recover. */
+export declare const appBackgroundedMessage: (alias: string) => string;
+/** The `session_suspended` message for a call that was pending when the app reconnected on a new
+ * socket: the app dropped the call with the old socket, so its result is lost. */
+export declare const appReconnectedMessage: (alias: string) => string;

package/dist/daemon/sessions.d.ts

@@ -10,12 +10,12 @@
  * §6: "terminal states free the alias" — there is no persisted history, matching §3/§13's "no
  * per-session files, all state in-daemon-memory").
  */
-import { type EventMessage, type SessionClaimMessage, type SessionResumeMessage, type SessionSummary, type ToolCallMessage, type ToolCallProgressMessage, type ToolCancelMessage, type ToolErrorMessage, type ToolResultMessage } from "@appduct/shared";
+import { type EventMessage, type SessionClaimMessage, type SessionResumeMessage, type LinkTransport, type SessionSummary, type SessionSuspendReason, type ToolCallMessage, type ToolCallProgressMessage, type ToolCancelMessage, type ToolErrorMessage, type ToolResultMessage } from "@appduct/shared";
 import type { WebSocket } from "ws";
 import type { Clock } from "../cli/types.js";
 import type { EventBus } from "./event-bus.js";
 import { type CreatedLink } from "./links.js";
-import { type ToolRegistry } from "./registry.js";
+import { type EventRegistry, type ToolRegistry } from "./registry.js";
 import { type TimerFns } from "./timers.js";
 /** Wire message types allowed *after* claim (session_claim/session_resume are pre-claim only). */
 export declare const POST_CLAIM_MESSAGE_TYPES: Set<string>;
@@ -26,7 +26,7 @@ export type SessionManagerOptions = {
     graceSeconds: number;
     keepaliveIntervalSeconds: number;
     linkTtlSeconds: number;
-    getEndpoint: () => CreatedLink["endpoint"];
+    getEndpoint: (transport: LinkTransport) => CreatedLink["endpoint"];
     eventBus: EventBus;
     clock?: Clock;
     timers?: TimerFns;
@@ -48,11 +48,15 @@ export type SessionManager = {
      * 07's emulator/simulator fast path); see `links.ts`'s `PendingLinkRegistry.create`. Omits
      * `LinkCreateResult.pin` — the session manager has no `TlsManager` handle, so the RPC handler
      * (`daemon.ts`) attaches the current SPKI pin itself before returning to the caller. */
-    createLink: (ttlSeconds?: number, addressOverride?: string) => Omit<LinkCreateResult, "pin">;
-    /** First message on a fresh socket. Returns the claimed sessionId, or `null` after closing the socket. */
-    handleClaim: (socket: WebSocket, message: SessionClaimMessage) => string | null;
-    /** First message on a resume socket. Returns the resumed sessionId, or `null` after closing the socket. */
-    handleResume: (socket: WebSocket, message: SessionResumeMessage) => string | null;
+    createLink: (ttlSeconds?: number, addressOverride?: string, transport?: LinkTransport) => Omit<LinkCreateResult, "pin">;
+    /** First message on a fresh socket accepted on `transport`'s listener. Returns the claimed
+     * sessionId, or `null` after closing the socket. A link minted for the other transport is
+     * refused with `wrong_transport` and stays claimable on its own listener. */
+    handleClaim: (socket: WebSocket, message: SessionClaimMessage, transport: LinkTransport) => string | null;
+    /** First message on a resume socket accepted on `transport`'s listener. Returns the resumed
+     * sessionId, or `null` after closing the socket. A session claimed on the other listener is
+     * refused with `wrong_transport` before its token is checked, so its token is not rotated. */
+    handleResume: (socket: WebSocket, message: SessionResumeMessage, transport: LinkTransport) => string | null;
     /** Dispatches an already-type-checked post-claim message; closes the socket on invalid content. */
     handlePostClaimMessage: (sessionId: string, socket: WebSocket, message: Record<string, unknown>) => void;
     list: () => SessionSummary[];
@@ -69,7 +73,9 @@ export type SessionManager = {
         sessionId: string;
         alias: string;
         state: "active" | "suspended";
+        suspendReason?: SessionSuspendReason;
         registry: ToolRegistry;
+        eventRegistry: EventRegistry;
     };
     /** Sends a `tool_call` frame to the session's active socket; `false` if the session has no
      * active socket right now (caller has typically already checked ACTIVE state via

package/dist/daemon/tls.d.ts

@@ -23,9 +23,6 @@ export declare class HostKeyError extends Error {
  * Deliberately the same shape as `ConfigWarnFn` (`config.ts`) so callers can pass the same
  * function through without an adapter. */
 export type TlsWarnFn = (message: string) => void;
-/** Refuses a key file that is group/world-readable. Missing files are handled by the caller
- * (`loadOrGenerateHostKeyPem`), which auto-generates instead of throwing. */
-export declare const loadHostKeyPem: (keyPath: string) => Promise<string>;
 /**
  * Loads the host key at `keyPath`, generating one in its place if none exists yet (dev-mode
  * zero-config bootstrap). Only the ENOENT case auto-generates: any other `stat`/`readFile` failure

package/dist/devtools-relay/attach-tab.d.ts

@@ -0,0 +1,33 @@
+import { type RelayLink } from "./relay.js";
+import type { DevtoolsBrowser, DevtoolsPage, OpenDaemonSocket } from "./ports.js";
+export type AttachBrowserTabOptions = {
+    browser: DevtoolsBrowser;
+    /**
+     * The page relayed for each target id. Attaching a tab closes the page already relayed for it, so a
+     * tab has one relay however its browser was reached; the new page is recorded here as soon as it is open.
+     */
+    relayedTabs: Map<string, DevtoolsPage>;
+    /** The tab's address, or the start of it. */
+    url: string;
+    /** Picks the tab directly, for when several tabs match `url`. */
+    targetId?: string;
+    /** Mints the web link for the page. Called once a tab is picked, so a failed pick strands no link. */
+    mintLink: () => Promise<RelayLink & {
+        sessionId: string;
+        expiresAt: number;
+    }>;
+    openDaemonSocket: OpenDaemonSocket;
+};
+/** `url` is the tab's own address, without the link's payload. */
+export type AttachedTab = {
+    sessionId: string;
+    url: string;
+    targetId: string;
+    expiresAt: number;
+};
+/**
+ * Picks a tab of a debugging-port browser, relays its page to the daemon and connects it over the
+ * binding, so the session outlives this call. The page must already load `@appduct/web`. Reloading
+ * resumes the session; a popup or a navigation that creates a new target is not relayed.
+ */
+export declare const attachBrowserTab: (options: AttachBrowserTabOptions) => Promise<AttachedTab>;

package/dist/devtools-relay/index.d.ts

@@ -0,0 +1,8 @@
+export { createMemoryDaemonSockets, type MemoryDaemonSocket, type MemoryDaemonSockets } from "./memory-daemon-sockets.js";
+export { attachBrowserTab, type AttachBrowserTabOptions, type AttachedTab } from "./attach-tab.js";
+export { createMemoryDevtoolsBrowser, type MemoryDevtoolsBrowser } from "./memory-devtools-browser.js";
+export { createMemoryPageChannel, type MemoryPageChannel } from "./memory-page-channel.js";
+export { connectNodeDevtoolsBrowser } from "./node-devtools-browser.js";
+export { openNodeDaemonSocket } from "./node-daemon-socket.js";
+export type { ConnectDevtoolsBrowser, DaemonSocket, DaemonSocketEvents, DevtoolsBrowser, DevtoolsPage, DevtoolsTarget, OpenDaemonSocket, PageChannel } from "./ports.js";
+export { linkPayload, parseLink, relayPage, type RelayLink } from "./relay.js";

package/dist/devtools-relay/memory-daemon-sockets.d.ts

@@ -0,0 +1,20 @@
+import type { OpenDaemonSocket } from "./ports.js";
+/** One daemon socket the relay opened, driven by the test. */
+export type MemoryDaemonSocket = {
+    readonly url: string;
+    /** Text frames the relay sent, in order. */
+    readonly sent: string[];
+    /** How the relay closed the socket, once it did. */
+    readonly closedByRelay: {
+        code: number;
+        reason: string;
+    } | undefined;
+    open(): void;
+    receive(text: string): void;
+    closeFromDaemon(code: number, reason: string): void;
+};
+export type MemoryDaemonSockets = {
+    open: OpenDaemonSocket;
+    readonly sockets: MemoryDaemonSocket[];
+};
+export declare const createMemoryDaemonSockets: () => MemoryDaemonSockets;

package/dist/devtools-relay/memory-devtools-browser.d.ts

@@ -0,0 +1,10 @@
+import type { DevtoolsBrowser, DevtoolsTarget } from "./ports.js";
+import { type MemoryPageChannel } from "./memory-page-channel.js";
+export type MemoryDevtoolsBrowser = DevtoolsBrowser & {
+    /** The tab's page, as the relay sees it: the one the next `openPage` returns, then the latest it returned. */
+    page(targetId: string): MemoryPageChannel;
+    /** Target ids passed to `openPage`, in order, that have not been closed since. */
+    attachedTargets(): string[];
+};
+/** A browser with the given tabs, each backed by a memory page channel. */
+export declare const createMemoryDevtoolsBrowser: (tabs: DevtoolsTarget[]) => MemoryDevtoolsBrowser;

package/dist/devtools-relay/memory-page-channel.d.ts

@@ -0,0 +1,16 @@
+import type { PageChannel } from "./ports.js";
+export type MemoryPageChannel = PageChannel & {
+    /** The page calls its binding with an object, sent as JSON. */
+    call(message: Record<string, unknown>): void;
+    /** The document is destroyed. */
+    resetContext(): void;
+    /** The connection is dropped: the context resets once, then the page stops calling the relay. */
+    close(): void;
+    /** What the relay delivered to `__APPDUCT__.receive`, parsed. */
+    received(): Record<string, unknown>[];
+    /** Every other expression evaluated in the page, in order. */
+    evaluated(): string[];
+    /** Makes `evaluate` reject for expressions matching `pattern`. */
+    failEvaluate(pattern: RegExp, error: Error): void;
+};
+export declare const createMemoryPageChannel: () => MemoryPageChannel;

package/dist/devtools-relay/node-daemon-socket.d.ts

@@ -0,0 +1,3 @@
+import type { OpenDaemonSocket } from "./ports.js";
+/** A `ws` client. It sends no `Origin`, which the daemon's web listener lets through. */
+export declare const openNodeDaemonSocket: OpenDaemonSocket;

package/dist/devtools-relay/node-devtools-browser.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectDevtoolsBrowser } from "./ports.js";
+/** A browser reached over its HTTP debugging endpoint, one raw-CDP WebSocket per relayed tab. */
+export declare const connectNodeDevtoolsBrowser: ConnectDevtoolsBrowser;

package/dist/devtools-relay/ports.d.ts

@@ -0,0 +1,48 @@
+/** What the relay needs from outside the process. Each port has a memory fake beside it. */
+/** The page the session runs in, as the relay sees it. A Playwright `Page` is adapted to this by `attachPage`. */
+export type PageChannel = {
+    /** Calls the page makes to its exposed binding, as the JSON string it passed. */
+    onBindingCall(handler: (json: string) => void): void;
+    /** Runs an expression in the page's current document. Rejects when there is none. */
+    evaluate(expression: string): Promise<unknown>;
+    /** A document was destroyed or replaced: a reload, a navigation to another document, or the page closing. */
+    onContextReset(handler: () => void): void;
+};
+export type DaemonSocketEvents = {
+    open(): void;
+    message(text: string): void;
+    close(code: number, reason: string): void;
+};
+export type DaemonSocket = {
+    send(text: string): void;
+    close(code: number, reason: string): void;
+};
+/** Opens a WebSocket to the daemon's web listener, with no `Origin`. */
+export type OpenDaemonSocket = (url: string, events: DaemonSocketEvents) => DaemonSocket;
+/** A tab the browser lists. */
+export type DevtoolsTarget = {
+    /** The CDP target id, stable for the life of the tab. */
+    id: string;
+    url: string;
+    title: string;
+};
+/** A tab opened for relaying: the page channel plus the way to let go of it. */
+export type DevtoolsPage = PageChannel & {
+    /** Drops the tab's binding connection. The page keeps running; it just has no relay. */
+    close(): void;
+};
+/** A Chromium launched with `--remote-debugging-port`, as the daemon sees it. */
+export type DevtoolsBrowser = {
+    /** The open tabs, in the order the browser lists them. Rejects when the browser cannot be reached. */
+    targets(): Promise<DevtoolsTarget[]>;
+    /**
+     * Opens the tab for relaying: `window.__appductBinding(json)` exists in its current document and in
+     * every later one, and `onContextReset` fires when its document is destroyed or the tab closes.
+     * Opening a tab that is already open drops the earlier connection.
+     */
+    openPage(targetId: string): Promise<DevtoolsPage>;
+    /** Drops every connection `openPage` made. */
+    close(): void;
+};
+/** Reaches the browser whose debugging endpoint is `browserUrl`, such as `http://127.0.0.1:9222`. */
+export type ConnectDevtoolsBrowser = (browserUrl: string) => DevtoolsBrowser;

package/dist/devtools-relay/relay.d.ts

@@ -0,0 +1,16 @@
+import { type BootstrapPayload } from "@appduct/shared";
+import type { OpenDaemonSocket, PageChannel } from "./ports.js";
+/** A link from `link({ target: "web", url })`: the page URL with `#appduct=<payload>`. */
+export type RelayLink = {
+    url: string;
+};
+/** The bootstrap payload in the link's fragment. */
+export declare const linkPayload: (link: RelayLink) => string;
+/** The bootstrap a link carries; throws when the link has no payload or the payload is not an Appduct link. */
+export declare const parseLink: (link: RelayLink) => BootstrapPayload;
+/**
+ * Carries one page's session frames between the page's binding and the daemon's web listener. The
+ * page asks for a daemon socket when its transport opens, and the relay closes it when the page's
+ * document is destroyed, so the daemon suspends the session and the reloaded page resumes it.
+ */
+export declare const relayPage: (page: PageChannel, link: RelayLink, openDaemonSocket: OpenDaemonSocket) => void;

package/dist/index.js

@@ -126,8 +126,11 @@ var createCli = () => {
     `link: deep-link URI scheme (also: APPDUCT_SCHEME; default: .appduct/config.json, then app.json's "expo.scheme", then the Android/iOS project files in <cwd>).`
   ).option(
     "--open <target>",
-    "link: deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental)."
-  ).option("--device <id>", "link: adb serial, simulator udid or paired-device udid to target when --open is ambiguous.").option(
+    "link: deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental), or with `web <url>` return the page URL and a connect script for a web page."
+  ).option(
+    "--browser-url <url>",
+    "link: with --open web, attach the tab of a Chrome launched with --remote-debugging-port (such as http://127.0.0.1:9222) and claim a session on it."
+  ).option("--target-id <id>", "link: with --browser-url, the CDP target id of the tab to attach when several tabs match <url>.").option("--device <id>", "link: adb serial, simulator udid or paired-device udid to target when --open is ambiguous.").option(
     "--app-id <id>",
     `link: installed app id for --open android/ios-device (default: .appduct/config.json's "appId.<platform>").`
   ).option(
@@ -138,10 +141,10 @@ var createCli = () => {
     "--timeout <ms>",
     "call: call timeout in milliseconds. Shortens the deadline; it cannot extend one past the app's own timer, which is the tool's declared timeoutMs (else 10000)."
   );
-  cli.command("events [...args]", "Stream the app's events, or replay them since a cursor: tail or since.").usage("events <tail|since> [selector] [args]").option("--follow", "tail: accepted for script readability; the default behavior already follows.").option(
+  cli.command("events [...args]", "List the events an app declares, stream them, or replay them since a cursor: ls, tail, or since.").usage("events <ls|tail|since> [selector] [args]").option("--follow", "tail: accepted for script readability; the default behavior already follows.").option(
     "--name <glob>",
-    'Only events whose name matches this whole-name, case-sensitive glob ("*" matches any run of characters).'
-  ).option(
+    `Only events whose name matches this whole-name, case-sensitive glob ("*" matches any run of characters). ls: an exact name prints that event's full payload schema.`
+  ).option("--limit <n>", "ls: show at most n events.").option("--offset <n>", "ls: skip the first n events of the name-sorted list.").option(
     "--payload-max-bytes <n>",
     "Cap each event's payload at this many UTF-8 bytes of its JSON; over the cap, the event carries payloadPreview, payloadBytes and truncated: true instead of payload."
   );
@@ -169,6 +172,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "daemonLogMaxBytes",
   "eventsLogMaxBytes",
   "policy",
+  "webOrigins",
   "advertisedIp",
   "scheme",
   "restartDaemonOnVersionMismatch"
@@ -229,6 +233,7 @@ var defaultConfig = (paths) => {
     daemonLogMaxBytes: DEFAULT_DAEMON_LOG_MAX_BYTES,
     eventsLogMaxBytes: 10 * 1024 * 1024,
     restartDaemonOnVersionMismatch: false,
+    webOrigins: [],
     policy: {
       default: "allow",
       destructive: "allow"
@@ -299,6 +304,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.");
@@ -407,7 +418,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,
@@ -546,6 +557,7 @@ var getExitCodeForError = (error) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -641,6 +653,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."];
@@ -649,7 +668,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)
@@ -823,10 +842,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(
@@ -947,6 +1043,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]
       ],
@@ -1014,6 +1111,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":