appduct 0.12.0 → 0.14.0

package/README.md

@@ -9,7 +9,7 @@ The `appduct` package is the operator/agent side of Appduct: a CLI and an MCP se
 ## Why use this package
 
 - **One daemon, many devices.** It auto-spawns on first use, serves every device on one `wss://` port, and survives Metro reloads, backgrounding, and network flaps by suspending and resuming sessions instead of dying with them.
-- **Same surface for humans and agents.** The CLI (`tools`, `invoke`, `events`, ...) and `appduct mcp` use the same RPC methods, so an agent sees the tools a human operator does.
+- **Same surface for humans and agents.** The CLI (`sessions`, `tools`, `events`, ...) and `appduct mcp` use the same RPC methods, so an agent sees the tools a human operator does.
 - **Hardened control plane.** The CLI and MCP server never touch sockets, keys, or state files directly — everything goes through a Unix-domain-socket RPC surface gated by filesystem permissions (see [`docs/SECURITY.md`][security]).
 - **Fits production-minded apps.** The app only exposes what you register; trust boundaries are pins and TLS, and production deployments can gate tools with policy and audit every call.
 
@@ -17,44 +17,49 @@ The `appduct` package is the operator/agent side of Appduct: a CLI and an MCP se
 
 ```bash
 npm install -g appduct
-appduct link --scheme myapp --qr
+appduct sessions link --scheme myapp --qr
 ```
 
-`link` needs your app's deep-link scheme: pass `--scheme` (the app's `expo.scheme`, or its bare-RN equivalent), or set `"scheme"` once in `~/.appduct/config.json` and omit the flag. Without either, the command exits with a usage error.
+`sessions link` needs your app's deep-link scheme: pass `--scheme` (the app's `expo.scheme`, or its bare-RN equivalent), or set `"scheme"` once in `~/.appduct/config.json` and omit the flag. Without either, the command exits with a usage error.
 
 Scan the QR (or open the deep link) in an Appduct-enabled app, then:
 
 ```bash
-appduct tools
-appduct invoke sum --input '{"a":2,"b":3}'
+appduct tools ls
+appduct tools call sum --input '{"a":2,"b":3}'
 ```
 
 That's the whole loop. There is no host process to start — `appduct` auto-spawns its daemon the first time any command needs it.
 
 ## Commands
 
+Every command is `appduct <noun> <verb> [selector] [args]`, the same shape as `appduct daemon run|start|stop|status`:
+
 | Command | Role |
 | --- | --- |
 | `appduct init [--scheme <s>] [--ios-app-id <id>] [--android-app-id <id>] [--force]` | set up an app directory: write `.appduct/config.json`, print the MCP snippet |
 | `appduct keygen [--out <path>] [--force]` | generate a daemon private key, print its app pin |
-| `appduct link [--ttl <s>] [--qr] [--open android\|ios-sim\|ios-device] [--device <id>] [--app-id <id>] [--scheme <s>]` | mint a pending session and print its deep link |
-| `appduct ls` | list sessions: alias, state, device, tool count |
-| `appduct tools [selector] [name] [--full] [--group <name>] [--filter <text>] [--limit <n>] [--offset <n>]` | list a session's tools (one call signature + description per line), or show one tool's full schema |
-| `appduct tools [selector] --groups` | list a session's tool groups with their tool counts |
-| `appduct invoke [selector] <tool> --input '<json>' [--timeout <ms>]` | call a tool |
-| `appduct events [selector] [--follow] [--since <cursor>]` | stream the events the app posts with `postEvent` (default), or one-shot pull the ones retained since `<cursor>` (`--since`); `--json` emits NDJSON |
-| `appduct revoke [selector]` | revoke a session |
+| `appduct sessions ls` | list sessions: alias, state, device, tool count |
+| `appduct sessions link [--ttl <s>] [--qr] [--open android\|ios-sim\|ios-device] [--device <id>] [--app-id <id>] [--scheme <s>]` | mint a pending session and print its deep link |
+| `appduct sessions revoke [selector]` | revoke a session |
+| `appduct tools ls [selector] [--full] [--group <name>] [--filter <text>] [--limit <n>] [--offset <n>]` | list a session's tools (one call signature + description per line) |
+| `appduct tools ls [selector] --groups` | list a session's tool groups with their tool counts |
+| `appduct tools describe [selector] <name>` | show one tool's full schema |
+| `appduct tools call [selector] <name> --input '<json>' [--timeout <ms>]` | call a tool |
+| `appduct events ls [selector] [--name <glob>] [--limit <n>] [--offset <n>]` | list the events the app declares, one signature line each; an exact `--name` prints the full payload schema; `--limit`/`--offset` page a long list, ending with a `Showing n of total events (offset o).` line when events were left out; `--json` carries the full descriptors, with `total` counting matches before paging |
+| `appduct events tail [selector] [--follow]` | stream the events the app posts with `postEvent`; `--json` emits NDJSON |
+| `appduct events since [selector] <cursor>` | one-shot pull the events retained since `<cursor>`; `--json` emits NDJSON |
 | `appduct daemon run\|start\|stop\|status` | daemon lifecycle |
 | `appduct mcp [--scheme <s>]` | start a stdio MCP server proxying connected apps' tools to MCP clients |
 | `appduct doctor <artifact> [--assert-present\|--assert-absent]` | release-gate step: report or assert whether a built `.app`/`.ipa`/`.apk`/`.aab` contains Appduct |
 
-Every command that targets a session accepts an optional `selector` (a session id or an alias from `appduct ls`); omit it when exactly one session is active. Global flags: `--json` (machine-readable output; compact by default, one line), `--pretty` (indent `--json` output, and JSON values embedded in human output, 2 spaces — never NDJSON event lines), `--verbose` (include the `meta` block — `command`, `timestamp`, `duration_ms` — omitted by default in both human and `--json` output), `--no-color`, `--state-dir <path>` (default `~/.appduct`), `--daemon-restart` (on a daemon/CLI version mismatch, restart the daemon even though that drops live sessions and unclaimed links — `APPDUCT_DAEMON_RESTART=1` and `config.json`'s `restartDaemonOnVersionMismatch` do the same for every command, and `--no-daemon-restart` overrules both for one). Run `appduct <command> --help` for the exact flags of any command.
+Every command that targets a session accepts an optional `selector` (a session id or an alias from `appduct sessions ls`); omit it when exactly one session is active. Global flags: `--json` (machine-readable output; compact by default, one line), `--pretty` (indent `--json` output, and JSON values embedded in human output, 2 spaces — never NDJSON event lines), `--verbose` (include the `meta` block — `command`, `timestamp`, `duration_ms` — omitted by default in both human and `--json` output), `--no-color`, `--state-dir <path>` (default `~/.appduct`), `--daemon-restart` (on a daemon/CLI version mismatch, restart the daemon even though that drops live sessions and unclaimed links — `APPDUCT_DAEMON_RESTART=1` and `config.json`'s `restartDaemonOnVersionMismatch` do the same for every command, and `--no-daemon-restart` overrules both for one). Run `appduct <noun> --help` for the exact flags any of its verbs takes.
 
-`--timeout` on `invoke` is clamped to 1,000–600,000 ms and can only **shorten** the deadline, never extend it past the app's own timer: the app aborts the handler at the tool's declared `timeoutMs`, or 10 seconds for a tool that declares none, regardless of what the caller asks for. If a tool needs more room, declare `timeoutMs` on its registration.
+`--timeout` on `tools call` is clamped to 1,000–600,000 ms and can only **shorten** the deadline, never extend it past the app's own timer: the app aborts the handler at the tool's declared `timeoutMs`, or 10 seconds for a tool that declares none, regardless of what the caller asks for. If a tool needs more room, declare `timeoutMs` on its registration.
 
-### `appduct tools`: a signature per tool
+### `appduct tools ls`: a signature per tool
 
-`appduct tools` prints one call signature plus a one-line description per tool, not the full schema — cheap to read even against an app that registers hundreds of tools:
+`appduct tools ls` prints one call signature plus a one-line description per tool, not the full schema — cheap to read even against an app that registers hundreds of tools:
 
 ```
 Tools
@@ -63,16 +68,16 @@ Tools
   set_flag(name: "dark_mode" | "new_checkout", enabled: bool)  [prompt]
     Toggle a feature flag.
 
-Run `appduct tools <name>` for a tool's full schema.
+Run `appduct tools describe <name>` for a tool's full schema.
 ```
 
-A signature is derived straight from the tool's JSON Schema: required params are `name: type`, optional ones `name?: type` (with `= <default>` when the schema declares a short one), and `-> type` is the result when the tool declares an `output_schema`. `...` anywhere means the schema shape wasn't one this renderer could summarize — the tool's full schema (`appduct tools <name>`) still has it. A `[prompt]`/`[deny]` tag follows a tool whose effective policy isn't `"allow"`.
+A signature is derived straight from the tool's JSON Schema: required params are `name: type`, optional ones `name?: type` (with `= <default>` when the schema declares a short one), and `-> type` is the result when the tool declares an `output_schema`. `...` anywhere means the schema shape wasn't one this renderer could summarize — the tool's full schema (`appduct tools describe <name>`) still has it. A `[prompt]`/`[deny]` tag follows a tool whose effective policy isn't `"allow"`.
 
-Use `--filter <text>` to narrow the listing to tools whose name or description contains `<text>` (case-insensitive), and `--limit <n>`/`--offset <n>` to page through it; a truncated listing prints a trailing `Showing n of total tools (offset o). Narrow with --filter <text> or page with --offset <n>.` line so you know more were left out. `appduct tools --json` returns `{ tools, total, groups }` — `total` is the count after `--group`/`--filter` but before `--limit`/`--offset`. `appduct tools <name>` (a single tool) is unaffected by any of this and always returns the bare tool descriptor; passing `--group`, `--groups`, `--filter`, `--limit` or `--offset` with a `<name>` is a usage error.
+Use `--filter <text>` to narrow the listing to tools whose name or description contains `<text>` (case-insensitive), and `--limit <n>`/`--offset <n>` to page through it; a truncated listing prints a trailing `Showing n of total tools (offset o). Narrow with --filter <text> or page with --offset <n>.` line so you know more were left out. `appduct tools ls --json` returns `{ tools, total, groups }` — `total` is the count after `--group`/`--filter` but before `--limit`/`--offset`. `appduct tools describe <name>` (a single tool) is unaffected by any of this and always returns the bare tool descriptor; passing `--group`, `--groups`, `--filter`, `--limit` or `--offset` with `describe` is a usage error.
 
 ### Tool groups
 
-When the app puts its tools in groups ([`docs/TOOLS.md`](../../docs/TOOLS.md#group-tools-in-a-large-app)), `appduct tools` lists them under group headings, with subgroups indented under their parent and ungrouped tools last:
+When the app puts its tools in groups ([`docs/TOOLS.md`](../../docs/TOOLS.md#group-tools-in-a-large-app)), `appduct tools ls` lists them under group headings, with subgroups indented under their parent and ungrouped tools last:
 
 ```
 Tools
@@ -93,23 +98,23 @@ Tools
 On a large app, start with `--groups` to see what there is, then list one group:
 
 ```
-$ appduct tools --groups
+$ appduct tools ls --groups
 Groups
   cart                12
   checkout             8
     checkout/payment   3
   (ungrouped)          2
 
-22 tools in total. Run `appduct tools --group <name>` to list one group's tools.
+22 tools in total. Run `appduct tools ls --group <name>` to list one group's tools.
 
-$ appduct tools --group checkout
+$ appduct tools ls --group checkout
 ```
 
 `--group checkout` lists `checkout` and all of its subgroups; `--group checkout/payment` lists only that subgroup. Matching is by whole name and case-sensitive, so `--group checkout` never matches a `checkoutx` group. `--group` combines with `--filter`, `--limit` and `--offset`. When a listing without `--group` is cut short, the footer names the top-level groups to narrow to: `Showing 5 of 22 tools (offset 0). Narrow with --group <name> (groups: cart 12, checkout 8) or --filter <text>, or page with --offset <n>.` A group that is not one or two `/`-separated names of letters, digits, `_` and `-` (for example `checkout/` or `a/b/c`) is a usage error. With `--json`, each tool carries its `group` — `null` for an ungrouped tool, exactly the value `groups` uses for its own ungrouped row — and `groups` lists every group with its count, whatever `--group` or `--filter` you passed.
 
 ### The deep-link scheme
 
-`appduct link`, `appduct mcp`, and the MCP `appduct_connect` tool all resolve the scheme the same way, first match wins:
+`appduct sessions link`, `appduct mcp`, and the MCP `appduct_connect` tool all resolve the scheme the same way, first match wins:
 
 1. `--scheme <s>`
 2. the `APPDUCT_SCHEME` environment variable
@@ -164,17 +169,17 @@ It needs all of:
 - **iOS 17 or newer** on the device, and **Xcode 15 or newer** on the host (`devicectl` doesn't exist before that). For iOS 16 and below, use the QR/deep-link flow instead.
 - The device **paired and trusted** by this Mac, with **Developer Mode** enabled on it (Settings → Privacy & Security → Developer Mode).
 - A **development-signed build of your app already installed** — `devicectl` launches an installed app, it doesn't install one.
-- The phone and this machine **on the same network**, reachable at the address the link advertises. `appduct link` prints it on its `Endpoint` line (`--json`: `endpoint.address`); `advertisedIp` in `config.json` overrides detection. If no routable address is found, detection falls back to `127.0.0.1` — which a phone can't reach — so `ios-device` refuses to deliver such a link and tells you to set `advertisedIp`.
+- The phone and this machine **on the same network**, reachable at the address the link advertises. `appduct sessions link` prints it on its `Endpoint` line (`--json`: `endpoint.address`); `advertisedIp` in `config.json` overrides detection. If no routable address is found, detection falls back to `127.0.0.1` — which a phone can't reach — so `ios-device` refuses to deliver such a link and tells you to set `advertisedIp`.
 - The app's **bundle id** — see [Delivering the link to a device](#delivering-the-link-to-a-device) for how to supply it.
 
 ```bash
-appduct link --scheme myapp --open ios-device --app-id com.example.myapp
+appduct sessions link --scheme myapp --open ios-device --app-id com.example.myapp
 ```
 
 Two things worth knowing before you rely on this:
 
 - **What happens when the app is already running hasn't been verified on hardware.** If delivery to an already-running app does nothing, pass **`--relaunch`** (`relaunch: true` over MCP) — it kills the running instance first. Appduct copes with the restart either way; a delivered link supersedes a held session.
-- **A physical iPhone is never auto-detected.** `appduct_connect` called without a `target` only considers booted simulators and attached Android devices, and `appduct link` without `--open` doesn't look for a device at all — a paired iPhone is often someone's personal phone, so it has to be asked for explicitly.
+- **A physical iPhone is never auto-detected.** `appduct_connect` called without a `target` only considers booted simulators and attached Android devices, and `appduct sessions link` without `--open` doesn't look for a device at all — a paired iPhone is often someone's personal phone, so it has to be asked for explicitly.
 
 ## MCP setup (Claude Code, Cursor, and similar)
 
@@ -208,23 +213,23 @@ Once configured, an agent reaches the connected app's tools through three built-
 
 | Tool | Does what | CLI equivalent |
 | --- | --- | --- |
-| `appduct_list_tools` | Lists the app's tools as one-line signatures, with each tool's group and policy, plus the app's groups with counts. Returns 50 at a time unless given `limit`; takes `group`, `filter` and `offset`. | `appduct tools` |
-| `appduct_describe_tool` | Shows one tool's full input and output schema. | `appduct tools <name>` |
-| `appduct_call_tool` | Calls a tool by `name` with `args`, with progress and errors preserved. | `appduct invoke` |
+| `appduct_list_tools` | Lists the app's tools as one-line signatures, with each tool's group and policy, plus the app's groups with counts. Returns 50 at a time unless given `limit`; takes `group`, `filter` and `offset`. | `appduct tools ls` |
+| `appduct_describe_tool` | Shows one tool's full input and output schema. | `appduct tools describe <name>` |
+| `appduct_call_tool` | Calls a tool by `name` with `args`, with progress and errors preserved. | `appduct tools call` |
 
-The app's tools don't show up as MCP tools of their own. An app with hundreds of tools still adds only these three to the agent's tool list, and that list doesn't change when tools register or a device connects. With more than one device connected, each of the three needs `selector`: the session alias or id from `appduct ls`.
+The app's tools don't show up as MCP tools of their own. An app with hundreds of tools still adds only these three to the agent's tool list, and that list doesn't change when tools register or a device connects. With more than one device connected, each of the three needs `selector`: the session alias or id from `appduct sessions ls`.
 
 Your MCP client asks permission for `appduct_call_tool` as a single tool, so choosing "always allow" there approves every tool the app registers, destructive ones included. To keep a person approving those calls, set `policy.destructive` to `"prompt"` in the state directory's `config.json`. Each call to a tool marked `destructiveHint` then shows an approval prompt in clients that support it, and is denied in clients that don't. A destructive tool without that annotation falls under `policy.default` instead.
 
 Set this before you connect: the daemon reads `config.json` only when it starts, so changing it later takes `appduct daemon stop`. That disconnects every device, which then has to link again, and leaves a running `appduct mcp` without a daemon, so restart the MCP server in your client as well.
 
-Four more built-in tools cover what the app's own tools can't. `appduct_connect` mints a link and, by default, delivers it to whichever `android`/`ios-sim` device it detects — pass `target`/`device` to choose, or `target: "none"` to force the human flow — falling back to a QR code, plus instructions to show it, only when there's nothing to deliver to. Delivering to `android` (chosen or detected) needs `appId`, resolved the same way as `--app-id` (see [Delivering the link to a device](#delivering-the-link-to-a-device)); passing it with `target: "ios-sim"` or `"none"` is an error. `appduct_wait_for_session` then waits for that session to be claimed. `target: "ios-device"` reaches a paired physical iPhone or iPad, with `appId` and the [prerequisites above](#--open-ios-device-experimental) — it's experimental and never auto-detected, so an agent has to ask for it by name.
+Five more built-in tools cover what the app's own tools can't. `appduct_connect` mints a link and, by default, delivers it to whichever `android`/`ios-sim` device it detects — pass `target`/`device` to choose, or `target: "none"` to force the human flow — falling back to a QR code, plus instructions to show it, only when there's nothing to deliver to. Delivering to `android` (chosen or detected) needs `appId`, resolved the same way as `--app-id` (see [Delivering the link to a device](#delivering-the-link-to-a-device)); passing it with `target: "ios-sim"` or `"none"` is an error. `appduct_wait_for_session` then waits for that session to be claimed. `target: "ios-device"` reaches a paired physical iPhone or iPad, with `appId` and the [prerequisites above](#--open-ios-device-experimental) — it's experimental and never auto-detected, so an agent has to ask for it by name.
 
-The other two give an agent a pull surface over `postEvent()`-pushed app events: `appduct_events` drains everything retained since a cursor, and `appduct_wait_for_event` blocks for a matching event (checking what's already retained before waiting live), rejecting with `tool_timeout` if none arrives in time.
+The other three give an agent a pull surface over `postEvent()`-pushed app events. `appduct_list_events` lists the events the app declared (`appduct events ls`) as signatures with descriptions, plus the payload schema when `name` is an exact name, so an agent learns the names before it waits on one. `appduct_events` drains everything retained since a cursor, and `appduct_wait_for_event` blocks for the next event whose name matches `name`, a whole-name glob (`*` waits for any name) — checking what's already retained before waiting live — rejecting with `tool_timeout` if none arrives in time.
 
 ## Test runners: `appduct/client`
 
-A thin typed wrapper over the same daemon RPC the CLI and MCP server use — for a Jest/Vitest/Detox spec that drives a running app without spawning `appduct invoke ... --json` and parsing stdout:
+A thin typed wrapper over the same daemon RPC the CLI and MCP server use — for a Jest/Vitest/Detox spec that drives a running app without spawning `appduct tools call ... --json` and parsing stdout:
 
 ```ts
 import { connect } from "appduct/client";
@@ -264,18 +269,19 @@ const app = await connect<Tools>();
 const { total } = await app.call("sum", { a: 2, b: 3 }); // typed
 ```
 
-`waitForEvent` first drains the daemon's per-session retained buffer for an already-arrived match before falling back to a live wait, so it's safe to call after the action that emits the event. Pass `since` (the `cursor` from a previous `app.events()`/`waitForEvent()` call) to skip events already handled:
+`waitForEvent`'s first argument is a whole-name glob (`*` waits for any name, `"cart.*"` for any name starting with `cart.`). It first drains the daemon's per-session retained buffer for an already-arrived match before falling back to a live wait, so it's safe to call after the action that emits the event. Pass `since` (the `cursor` from a previous `app.events()`/`waitForEvent()` call) to skip events already handled, and `payloadMaxBytes` to cap the resolved event's payload the same way `app.events()` does — without it the payload always comes back whole:
 
 ```ts
 const { events, cursor } = await app.events();               // pull: what already happened
 const next = await app.waitForEvent("checkout_done", { since: cursor });
+const capped = await app.waitForEvent("checkout_done", { payloadMaxBytes: 1024 }); // check `truncated` before reading `payload`
 ```
 
 For everything else, the package exports `runCli` and the command handlers from [`src/index.ts`](https://github.com/callstackincubator/appduct/blob/main/packages/appduct/src/index.ts), so you can embed the same behavior in Node or Bun scripts without shelling out.
 
 ## Keys and pins
 
-You can skip this entirely while your app has no `cliPins` configured — the zero-config default, in any build type. The daemon auto-generates its own `key.pem` the first time it starts if one isn't already there (mode `0600`) and prints its `sha256/...` fingerprint on that first run; `appduct link` carries that fingerprint on the deep link for the app to pick up. See [`docs/SECURITY.md`][security]'s "Trust modes" for what that does and doesn't protect.
+You can skip this entirely while your app has no `cliPins` configured — the zero-config default, in any build type. The daemon auto-generates its own `key.pem` the first time it starts if one isn't already there (mode `0600`) and prints its `sha256/...` fingerprint on that first run; `appduct sessions link` carries that fingerprint on the deep link for the app to pick up. See [`docs/SECURITY.md`][security]'s "Trust modes" for what that does and doesn't protect.
 
 For a build that should trust only a key you embedded ahead of time, generate one explicitly:
 
@@ -285,7 +291,7 @@ appduct keygen
 
 This writes an unencrypted PEM private key (PKCS#8) to `<state-dir>/key.pem` by default (override with `--out`; add `--force` to overwrite) and prints the exact `sha256/...` SPKI fingerprint your app should place into `cliPins`. It runs non-interactively, so it's safe to call from CI or a setup script.
 
-`appduct link`'s deep link is `<scheme>:///?appduct=<payload>&pin=<sha256/...>`. The `appduct` param is the binary v2 bootstrap payload (address, session id, token, expiry); `pin` is a separate, out-of-band query param carrying the daemon's current SPKI fingerprint for apps that want to pick it up. An app build with embedded `cliPins` ignores `pin` outright — embedded pins always win, in every build type. A build with no embedded pins trusts it for that one session.
+`appduct sessions link`'s deep link is `<scheme>:///?appduct=<payload>&pin=<sha256/...>`. The `appduct` param is the binary v2 bootstrap payload (address, session id, token, expiry); `pin` is a separate, out-of-band query param carrying the daemon's current SPKI fingerprint for apps that want to pick it up. An app build with embedded `cliPins` ignores `pin` outright — embedded pins always win, in every build type. A build with no embedded pins trusts it for that one session.
 
 ## Daemon lifecycle
 

package/dist/bin.js

@@ -123,27 +123,30 @@ var createCli = () => {
     'Android package name to write as "appId.android" (needed to deliver a link with --open android).'
   );
   cli.command("keygen", "Generate an Appduct host private key and print its app fingerprint.").option("--out <path>", "Destination path (default: <state-dir>/key.pem).").option("--force", "Overwrite an existing key at the destination path.");
-  cli.command("link", "Mint a pending session and print its deep link.").option("--ttl <seconds>", "Link time-to-live in seconds (default: from config.json).").option("--qr", "Also render the deep link as a terminal QR code.").option(
+  cli.command("sessions [...args]", "Manage Appduct sessions: ls, revoke, or link.").usage("sessions <ls|revoke|link> [selector] [args]").option("--ttl <seconds>", "link: time-to-live in seconds (default: from config.json).").option("--qr", "link: also render the deep link as a terminal QR code.").option(
     "--scheme <scheme>",
-    `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>).`
+    `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>",
-    "Deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental)."
-  ).option("--device <id>", "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)."
+  ).option("--device <id>", "link: adb serial, simulator udid or paired-device udid to target when --open is ambiguous.").option(
     "--app-id <id>",
-    `Installed app id for --open android/ios-device (default: .appduct/config.json's "appId.<platform>").`
+    `link: installed app id for --open android/ios-device (default: .appduct/config.json's "appId.<platform>").`
   ).option(
     "--relaunch",
-    "With --open ios-device, terminate a running instance first (try this if delivery to an already-running app does nothing)."
+    "link: with --open ios-device, terminate a running instance first (try this if delivery to an already-running app does nothing)."
   );
-  cli.command("ls", "List Appduct sessions.");
-  cli.command("tools [selector] [name]", "List a session's tools, or show one tool's full schema.").option("--full", "Render full schemas/annotations for every listed tool.").option("--group <name>", 'Only tools in this group ("checkout" includes "checkout/payment").').option("--groups", "List the session's groups with tool counts instead of its tools.").option("--filter <text>", "Only tools whose name or description contains this text (case-insensitive).").option("--limit <n>", "Show at most n tools.").option("--offset <n>", "Skip the first n tools of the sorted list.");
-  cli.command("invoke [selector] [tool]", "Call a tool on a session.").option("--input <json>", "Tool input arguments as a JSON object.").option(
+  cli.command("tools [...args]", "List a session's tools, describe one, or call one: ls, describe, or call.").usage("tools <ls|describe|call> [selector] [args]").option("--full", "ls: render full schemas/annotations for every listed tool.").option("--group <name>", 'ls: only tools in this group ("checkout" includes "checkout/payment").').option("--groups", "ls: list the session's groups with tool counts instead of its tools.").option("--filter <text>", "ls: only tools whose name or description contains this text (case-insensitive).").option("--limit <n>", "ls: show at most n tools.").option("--offset <n>", "ls: skip the first n tools of the sorted list.").option("--input <json>", "call: tool input arguments as a JSON object.").option(
     "--timeout <ms>",
-    "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)."
+    "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]", "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). 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."
   );
-  cli.command("events [selector]", "Stream the events the app posts until interrupted.").option("--follow", "Accepted for script readability; the default behavior already follows.").option("--since <cursor>", "One-shot: print the app events retained since this cursor instead of streaming live.");
-  cli.command("revoke [selector]", "Revoke a session.");
   cli.command("mcp", "Start a stdio MCP server that gives MCP clients access to connected apps' tools.").option(
     "--scheme <scheme>",
     "Deep-link URI scheme for appduct_connect (also: APPDUCT_SCHEME)."
@@ -521,6 +524,7 @@ var getExitCodeForError = (error) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -616,6 +620,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."];
@@ -624,7 +635,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)
@@ -638,9 +649,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);
 };
@@ -658,7 +666,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)}.`;
 };
@@ -740,7 +748,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) => {
@@ -792,18 +800,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)];
 };
@@ -987,15 +1039,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);
@@ -1150,21 +1206,30 @@ var DAEMON_RESTART_ENV = "APPDUCT_DAEMON_RESTART";
 var isEnvTruthy = (value) => {
   return value === "1" || value?.toLowerCase() === "true";
 };
+var REMOVED_COMMANDS = {
+  ls: "sessions ls",
+  revoke: "sessions revoke",
+  link: "sessions link",
+  invoke: "tools call"
+};
+var rootUnknownCommandError = (word) => {
+  if (word !== void 0 && Object.hasOwn(REMOVED_COMMANDS, word)) {
+    return usageError(`Unknown command "${word}"; use "appduct ${REMOVED_COMMANDS[word]}".`);
+  }
+  return unknownCommandError(word);
+};
 var rootRouter = createRouter(
   {
     init: () => import("./cli/routes/init.js"),
     keygen: () => import("./cli/routes/keygen.js"),
-    link: () => import("./cli/routes/link.js"),
-    ls: () => import("./cli/routes/ls.js"),
-    tools: () => import("./cli/routes/tools.js"),
-    invoke: () => import("./cli/routes/invoke.js"),
-    revoke: () => import("./cli/routes/revoke.js"),
-    events: () => import("./cli/routes/events.js"),
+    sessions: () => import("./cli/routes/sessions/index.js"),
+    tools: () => import("./cli/routes/tools/index.js"),
+    events: () => import("./cli/routes/events/index.js"),
     mcp: () => import("./cli/routes/mcp.js"),
     doctor: () => import("./cli/routes/doctor.js"),
     daemon: () => import("./cli/routes/daemon/index.js")
   },
-  { unknown: unknownCommandError }
+  { unknown: rootUnknownCommandError }
 );
 var runCli = async (argv, options = {}) => {
   const writers = {
@@ -1203,7 +1268,7 @@ var runCli = async (argv, options = {}) => {
       return executeCommand(
         "cli",
         () => {
-          throw usageError(`Unknown command "${parsedArgs[0]}".`);
+          throw rootUnknownCommandError(parsedArgs[0]);
         },
         {
           flags,

package/dist/cli/command-options.d.ts

@@ -7,8 +7,9 @@
  * positive integer, or throws a clear `usage_error`. */
 export declare const parsePositiveIntegerOption: (value: unknown, flagName: string) => number | undefined;
 /** Parses a `cac`-provided option value into a non-negative integer (0 allowed, unlike
- * {@link parsePositiveIntegerOption}), or throws a clear `usage_error`. Used by `events --since`,
- * whose cursor `0` is a meaningful "everything retained" value, not an omission. */
+ * {@link parsePositiveIntegerOption}), or throws a clear `usage_error`. Used by `events since`'s
+ * `<cursor>` positional, whose value `0` is a meaningful "everything retained" value, not an
+ * omission. */
 export declare const parseNonNegativeIntegerOption: (value: unknown, flagName: string) => number | undefined;
 /**
  * Reads a free-text flag's value exactly as typed. `cac` coerces any numeric-looking value to a
@@ -19,9 +20,9 @@ export declare const parseNonNegativeIntegerOption: (value: unknown, flagName: s
  */
 export declare const readTextOption: (argv: readonly string[], value: unknown, flagName: string) => string | undefined;
 /**
- * Splits the positional args of a command shaped `<command> [selector] <target>` (e.g. `invoke
- * [selector] <tool>`, `tools [selector] <name>`): the last positional is always the required
- * target, everything before it (zero or one args) is the optional selector.
+ * Splits the positional args of a command shaped `<command> [selector] <target>` (e.g. `tools
+ * call [selector] <tool>`, `tools describe [selector] <name>`): the last positional is always the
+ * required target, everything before it (zero or one args) is the optional selector.
  */
 export declare const splitSelectorAndRequiredTarget: (args: readonly string[], commandUsage: string) => {
     selector?: string;
@@ -33,18 +34,7 @@ export declare const splitOptionalSelector: (args: readonly string[], commandUsa
     selector?: string;
 };
 /**
- * Splits the positional args of a command shaped `<command> [selector] [target]` (`tools [selector]
- * [name]`): with 2 args, `(selector, target)`; with 1, the single arg is ambiguous between "the
- * selector" and "the target with the selector omitted" — the caller resolves that (see
- * `commands/tools.ts`), so it comes back unlabeled here as `selectorOrTarget`.
- */
-export declare const splitOptionalSelectorAndTarget: (args: readonly string[], commandUsage: string) => {
-    selector?: string;
-    target?: string;
-    selectorOrTarget?: string;
-};
-/**
- * Parses the JSON payload for `invoke --input`; never throws a raw `SyntaxError` at the CLI
+ * Parses the JSON payload for `tools call --input`; never throws a raw `SyntaxError` at the CLI
  * boundary. A missing flag is a usage error (nothing was given); a present-but-unparseable or
  * wrong-shaped value is a validation error (something was given, and it's invalid).
  */

package/dist/cli/result-types.d.ts

@@ -4,7 +4,7 @@
  * the thin-client shapes for the v2 command table.
  */
 import type { OpenTarget } from "./open-target.js";
-import type { AgentEndpoint, EffectivePolicyDecision, EventNotification, SessionSummary, ToolGroupSummary, ToolsListEntry, ToolsListResult } from "@appduct/shared";
+import type { AgentEndpoint, EffectivePolicyDecision, EventNotification, EventsListResult, SessionSummary, ToolGroupSummary, ToolsListEntry, ToolsListResult } from "@appduct/shared";
 /**
  * CLI-domain error classes, used only to pick a sysexits-style exit code (see `errors.ts`).
  * `CliError.type` itself is *not* restricted to this union: RPC/app-originated failures preserve
@@ -111,9 +111,10 @@ export type LinkCommandData = {
     /** The `--open` target the link was delivered to, alongside `delivered`. */
     target?: OpenTarget;
 };
-/** `appduct ls`: `sessions.list` passthrough, verbatim (ARCHITECTURE.md §10: "--json passthrough"). */
+/** `appduct sessions ls`: `sessions.list` passthrough, verbatim (ARCHITECTURE.md §10: "--json
+ * passthrough"). */
 export type LsCommandData = SessionSummary[];
-/** `appduct tools`'s listing form: the daemon's `tools.list` result, plus the `--group`/`--filter`/
+/** `appduct tools ls`'s listing form: the daemon's `tools.list` result, plus the `--group`/`--filter`/
  * `--limit`/`--offset` inputs that produced it (only the ones actually given — echoed so `--json` and the
  * human renderer's "Showing n of total" line can report what was asked for without threading the
  * CLI options through separately). */
@@ -123,22 +124,31 @@ export type ToolsListing = ToolsListResult & {
     group?: string;
     filter?: string;
 };
-/** `appduct tools --groups`: the daemon's `groups` summary alone, plus the registry's size. */
+/** `appduct tools ls --groups`: the daemon's `groups` summary alone, plus the registry's size. */
 export type ToolGroupsListing = {
     groups: ToolGroupSummary[];
     /** Every tool in the session, grouped or not. */
     total: number;
 };
-/** `appduct tools`: a listing, a groups summary (`--groups`), or a single entry when a tool name
- * resolved to a detail lookup. The detail form is the daemon's own listing entry, picked out of
- * `tools.list` — not a registration, so its `group` is `null` for an ungrouped tool. */
+/** `appduct tools ls`/`appduct tools describe`: a listing, a groups summary (`--groups`), or a
+ * single entry when `describe`'s `<name>` resolved to a tool. The detail form is the daemon's own
+ * listing entry, picked out of `tools.list` — not a registration, so its `group` is `null` for an
+ * ungrouped tool. */
 export type ToolsCommandData = ToolsListing | ToolGroupsListing | ToolsListEntry;
-/** `appduct invoke`: the tool's raw result payload, printed as-is. */
+/** `appduct events ls`: the daemon's `events.list` result, plus the `--name`/`--limit`/`--offset`
+ * inputs that produced it (only the ones actually given). */
+export type EventsListing = EventsListResult & {
+    name?: string;
+    limit?: number;
+    offset?: number;
+};
+/** `appduct tools call`: the tool's raw result payload, printed as-is. */
 export type InvokeCommandData = unknown;
 export type RevokeCommandData = {
     ok: true;
 };
-/** A single `appduct events` line, in both human and NDJSON (`--json`) rendering. */
+/** A single `appduct events tail`/`appduct events since` line, in both human and NDJSON
+ * (`--json`) rendering. */
 export type EventsCommandLine = EventNotification;
 export type DaemonRunCommandData = {
     daemon: {