@paneui/cli 0.0.5 → 0.0.7

package/dist/commands/{keys.js → key.js}

@@ -1,17 +1,21 @@
-// `pane keys` — inspect or revoke the calling agent's API key.
+// `pane key` — inspect or revoke the calling agent's API key.
 //
-// Flat command namespace: `keys` is one top-level command that branches on a
-// positional subcommand (list / revoke). The relay scopes /v1/keys to the
+// Flat command namespace: `key` is one top-level noun that branches on a
+// positional verb (list / revoke). The relay scopes /v1/keys to the
 // authenticated agent, so there is exactly one key — the caller's own. Both
-// subcommands therefore act ONLY on the caller's own key.
+// verbs therefore act ONLY on the caller's own key.
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
-export const keysHelp = `pane keys — inspect or revoke YOUR agent's API key
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+const REVOKE_BOOLS = ["yes"];
+export const keyHelp = `pane key — inspect or revoke YOUR agent's API key
 
 Usage:
-  pane keys <subcommand> [options]
+  pane key <verb> [options]
 
-Subcommands:
+Verbs:
   list       Show YOUR agent's key info. The relay scopes keys to the
              authenticated agent — there is exactly one key per agent, your
              own. Prints { agent_id, name, key_prefix, created_at,
@@ -19,18 +23,19 @@ Subcommands:
 
   revoke     Revoke YOUR OWN API key — a self-destruct. The key stops working
              IMMEDIATELY; every subsequent command fails until you run
-             'pane register' again to provision a new key. The relay only
+             'pane agent register' again to provision a new key. The relay only
              allows revoking your own key. Requires --yes to confirm.
              Prints { revoked: true, agent_id }.
 
 Options:
-  --yes               Confirm 'keys revoke' (required — it is irreversible).
+  --yes               Confirm 'key revoke' (required — it is irreversible).
   --url <url>         Relay base URL (overrides PANE_URL).
   --api-key <key>     Agent API key (overrides PANE_API_KEY).
   -h, --help          Show this help.
 
 Output: stdout is machine-readable JSON.`;
-async function runKeysList(args) {
+async function runKeyList(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane key list");
     const client = makeClient(args);
     try {
         const info = await client.listKeys();
@@ -40,9 +45,10 @@ async function runKeysList(args) {
         failFromError(e);
     }
 }
-async function runKeysRevoke(args) {
+async function runKeyRevoke(args) {
+    assertKnownFlags(args, NO_FLAGS, REVOKE_BOOLS, "pane key revoke");
     if (!args.bools.has("yes")) {
-        fail("'pane keys revoke' revokes YOUR OWN API key — it stops working " +
+        fail("'pane key revoke' revokes YOUR OWN API key — it stops working " +
             "immediately and is irreversible. Pass --yes to confirm.", "confirmation_required");
     }
     const client = makeClient(args);
@@ -58,19 +64,19 @@ async function runKeysRevoke(args) {
         failFromError(e);
     }
 }
-export async function runKeys(args) {
+export async function runKey(args) {
     const sub = args.positionals[0];
     switch (sub) {
         case "list":
-            await runKeysList(args);
+            await runKeyList(args);
             break;
         case "revoke":
-            await runKeysRevoke(args);
+            await runKeyRevoke(args);
             break;
         case undefined:
-            fail("missing subcommand — usage: pane keys <list|revoke> (run 'pane keys --help')", "invalid_args");
+            fail("missing verb — usage: pane key <list|revoke> (run 'pane key --help')", "invalid_args");
             break;
         default:
-            fail(`unknown keys subcommand '${sub}' — expected list|revoke (run 'pane keys --help')`, "invalid_args");
+            fail(`unknown key verb '${sub}' — expected list|revoke (run 'pane key --help')`, "invalid_args");
     }
 }

package/dist/commands/list.js

@@ -0,0 +1,91 @@
+// `pane surface list` — enumerate YOUR agent's surfaces.
+//
+// The recovery primitive when the create-response was dropped: the URL itself
+// is unrecoverable (the relay stores only the token hash), but every other
+// field of the surface is intact and listable here. Pair with
+// `pane surface participant new` to mint a fresh URL on a surface whose
+// original was lost.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { printJson, fail, failFromError } from "../output.js";
+const KNOWN_FLAGS = ["status", "limit", "cursor", "template-id"];
+const KNOWN_BOOLS = [];
+export const listHelp = `pane surface list — list YOUR agent's surfaces
+
+Prints surfaces (newest first) with no secrets in the response. Participant
+tokens are stored hashed and CANNOT be recovered — if you lost a surface URL,
+mint a fresh one with 'pane surface participant new <surface-id>'.
+
+Usage:
+  pane surface list [options]
+
+Options:
+  --status <s>      open | closed | all. Default: open. The status reported
+                    is the EFFECTIVE status — a row whose ttl is in the past
+                    is reported as 'closed' even if not yet swept.
+  --limit <N>       Page size (default 50, max 200).
+  --cursor <c>      Opaque cursor from a previous page's next_cursor.
+  --template-id <i> Filter to surfaces instantiated from a specific named
+                    template (head id; not version id). Inline (anonymous)
+                    templates cannot be filtered this way — they have no
+                    stable handle.
+  --url <url>       Relay base URL (overrides PANE_URL).
+  --api-key <key>   Agent API key (overrides PANE_API_KEY).
+  -h, --help        Show this help.
+
+Recovery recipe (lost the URL but the surface is still alive):
+  pane surface list                                       # find the
+                                                          #   surface_id +
+                                                          #   participant_id
+                                                          #   you lost
+  pane surface participant new <surface-id>               # mint a fresh URL
+  pane surface participant revoke <surface-id> <p-id>     # invalidate the
+                                                          #   old URL
+
+Output (stdout, JSON):
+  {
+    items: [
+      {
+        surface_id, title, status, template_id, template_version_id,
+        template_version, participants: [...], created_at, expires_at,
+        has_callback
+      },
+      ...
+    ],
+    next_cursor: <opaque|null>
+  }`;
+const STATUSES = ["open", "closed", "all"];
+export async function runList(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface list");
+    const opts = {};
+    const status = args.flags.get("status");
+    if (status !== undefined) {
+        if (!STATUSES.includes(status)) {
+            fail(`--status must be one of: ${STATUSES.join(", ")} (got '${status}')`, "invalid_args");
+        }
+        opts.status = status;
+    }
+    const limitRaw = args.flags.get("limit");
+    if (limitRaw !== undefined) {
+        const n = Number(limitRaw);
+        if (!Number.isInteger(n) || n <= 0 || n > 200) {
+            fail(`--limit must be an integer in 1..200 (got '${limitRaw}')`, "invalid_args");
+        }
+        opts.limit = n;
+    }
+    const cursor = args.flags.get("cursor");
+    if (cursor !== undefined && cursor !== "")
+        opts.cursor = cursor;
+    const templateId = args.flags.get("template-id");
+    if (templateId !== undefined && templateId !== "") {
+        opts.template_id = templateId;
+    }
+    const client = makeClient(args);
+    try {
+        const page = await client.listSessions(opts);
+        printJson(page);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/logout.js

@@ -1,25 +1,29 @@
-// `pane logout` — clear the locally-saved relay URL + API key.
+// `pane agent logout` — clear the locally-saved relay URL + API key.
+import { assertKnownFlags } from "../argv.js";
 import { clearStore } from "../store.js";
 import { printJson } from "../output.js";
-export const logoutHelp = `pane logout — clear the saved relay URL + API key
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+export const logoutHelp = `pane agent logout — clear the saved relay URL + API key
 
 Usage:
-  pane logout [options]
+  pane agent logout [options]
 
 Deletes the CLI config file (\${XDG_CONFIG_HOME:-~/.config}/pane/config.json),
-which holds the relay URL and the agent API key saved by 'pane register'.
+which holds the relay URL and the agent API key saved by 'pane agent register'.
 Idempotent — no error if there is nothing to clear.
 
 This only clears the LOCAL config. It does NOT revoke the key on the relay —
 the key keeps working until it is revoked. To revoke it on the relay, use
-'pane keys revoke'.
+'pane key revoke'.
 
 Options:
   -h, --help          Show this help.
 
 Output (stdout, JSON):
   { cleared: true, path }`;
-export async function runLogout() {
+export async function runLogout(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane agent logout");
     const path = clearStore();
     printJson({ cleared: true, path });
 }

package/dist/commands/participant.js

@@ -0,0 +1,137 @@
+// `pane surface participant <new|revoke>` — mint or invalidate one
+// participant URL on an existing surface. Recovery + leak-containment
+// primitives that together replace the destructive `pane surface delete +
+// pane surface create` workaround for the lost-URL case.
+//
+// This file is a sub-noun dispatcher under `pane surface`. The surface
+// dispatcher hands us a ParsedArgs whose positionals[0] is "participant"
+// (our sub-noun marker), so we read the verb from positionals[1] and the
+// args from positionals[2..]. This mirrors the way every other sub-verb
+// runner (runState, runDelete, ...) reads positionals[0] as its first arg
+// after a single shift.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { printJson, fail, failFromError } from "../output.js";
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+export const participantHelp = `pane surface participant — manage one surface's participant URLs
+
+Participant tokens are stored hashed on the relay and CANNOT be recovered.
+If you lost the create-response (and the URL with it), use 'new' to mint a
+fresh URL — the surface keeps its event log, template pin, and created_at.
+Use 'revoke' to invalidate a single URL while keeping the surface alive.
+
+Usage:
+  pane surface participant <verb> <args>
+
+Verbs:
+  list <surface-id>           List the participants on one surface, including
+                              revoked rows (for audit). Returns
+                              { surface_id, items: [...] } where each item
+                              carries { participant_id, kind, token_prefix,
+                              joined_at, revoked_at }. Use this to find the
+                              participant_id you need to pass to 'revoke'.
+
+  new <surface-id>            Mint a fresh human URL on an existing surface.
+                              Returns { participant_id, kind, token, url,
+                              created_at } — ONCE. The plaintext token is
+                              never recoverable; save the response (pipe to
+                              a JSONL log) before delivering the URL.
+
+  revoke <surface-id> <participant-id>
+                              Invalidate one participant URL. The surface's
+                              other participants (and the agent's own
+                              websocket) are untouched. Idempotent: running
+                              revoke twice still returns success.
+                              Note: existing WebSocket connections held
+                              under the revoked token are NOT actively
+                              kicked in v1; new HTTP and WS connections
+                              under that token will fail with 404.
+
+Options:
+  --url <url>                 Relay base URL (overrides PANE_URL).
+  --api-key <key>             Agent API key (overrides PANE_API_KEY).
+  -h, --help                  Show this help.
+
+Recovery recipe:
+  pane surface list                                       # find surface_id
+  pane surface participant list <surface-id>              # find participant
+                                                          #   ids on that
+                                                          #   surface
+  pane surface participant new <surface-id>               # mint a new URL
+  pane surface participant revoke <surface-id> <p-id>     # invalidate the
+                                                          #   old URL
+
+Output: stdout is machine-readable JSON.`;
+async function runParticipantList(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane surface participant list");
+    const surfaceId = args.positionals[1];
+    if (!surfaceId) {
+        fail("missing <surface-id> — usage: pane surface participant list <surface-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.listParticipants(surfaceId);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runParticipantNew(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane surface participant new");
+    const surfaceId = args.positionals[1];
+    if (!surfaceId) {
+        fail("missing <surface-id> — usage: pane surface participant new <surface-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.mintParticipant(surfaceId);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runParticipantRevoke(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane surface participant revoke");
+    const surfaceId = args.positionals[1];
+    const participantId = args.positionals[2];
+    if (!surfaceId || !participantId) {
+        fail("missing arguments — usage: pane surface participant revoke <surface-id> <participant-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        await client.revokeParticipant(surfaceId, participantId);
+        printJson({
+            surface_id: surfaceId,
+            participant_id: participantId,
+            revoked: true,
+        });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+export async function runParticipant(args) {
+    // positionals[0] is the verb (list | new | revoke), positionals[1..] are
+    // the verb's args. (The surface.ts dispatcher already shifted off the
+    // "participant" marker before calling us.)
+    const verb = args.positionals[0];
+    switch (verb) {
+        case "list":
+            await runParticipantList(args);
+            break;
+        case "new":
+            await runParticipantNew(args);
+            break;
+        case "revoke":
+            await runParticipantRevoke(args);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane surface participant <list|new|revoke> (run 'pane surface participant --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown participant verb '${verb}' — expected list|new|revoke (run 'pane surface participant --help')`, "invalid_args");
+    }
+}

package/dist/commands/register.js

@@ -1,4 +1,4 @@
-// `pane register` — self-provision an agent API key from the relay.
+// `pane agent register` — self-provision an agent API key from the relay.
 //
 // This is the one command that needs no API key: it is the call that obtains
 // one. If the relay runs REGISTRATION_MODE=secret, pass the shared
@@ -6,14 +6,17 @@
 // (and relay URL) are persisted to the CLI config file, so every later command
 // works with only PANE_URL (or nothing) set.
 import { registerAgent, PaneApiError } from "@paneui/core";
+import { assertKnownFlags } from "../argv.js";
 import { DEFAULT_RELAY_URL } from "../config.js";
 import { printJson, fail, failUpgradeRequired } from "../output.js";
 import { readStore, writeStore } from "../store.js";
 import { VERSION } from "../version.js";
-export const registerHelp = `pane register — register this agent with the relay and save the key locally
+const KNOWN_FLAGS = ["name", "secret"];
+const KNOWN_BOOLS = ["print-key"];
+export const registerHelp = `pane agent register — register this agent with the relay and save the key locally
 
 Usage:
-  pane register [options]
+  pane agent register [options]
 
 Calls POST /v1/register, then saves the returned API key (and relay URL) to the
 CLI config file — so afterwards every other command works with only PANE_URL
@@ -36,6 +39,7 @@ Output (stdout, JSON):
 The API key is saved to the CLI config file (mode 0600); it is not printed
 unless --print-key is passed.`;
 export async function runRegister(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane agent register");
     const store = readStore();
     const url = args.flags.get("url") ??
         process.env.PANE_URL ??
@@ -56,7 +60,7 @@ export async function runRegister(args) {
         if (e instanceof PaneApiError) {
             // 426 cli_upgrade_required goes through the shared upgrade-message
             // path (stderr block + exit 75) so the SKILL.md's instructions to the
-            // agent's harness fire on `pane register` too.
+            // agent's harness fire on `pane agent register` too.
             if (e.status === 426 && e.code === "cli_upgrade_required") {
                 failUpgradeRequired(e);
             }

package/dist/commands/send.js

@@ -1,21 +1,39 @@
-// `pane send <id>` — append an agent event to a session.
+// `pane surface send <id>` — append an agent event to a surface.
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { resolveJson } from "../input.js";
 import { printJson, fail, failFromError } from "../output.js";
-export const sendHelp = `pane send — emit an agent event into a session
+const KNOWN_FLAGS = [
+    "type",
+    "data",
+    "attachment",
+    "causation-id",
+    "idempotency-key",
+];
+const KNOWN_BOOLS = [];
+export const sendHelp = `pane surface send — emit an agent event into a surface
 
 Usage:
-  pane send <session-id> --type <event-type> --data <path|json> [options]
+  pane surface send <surface-id> --type <event-type> --data <path|json> [options]
+  pane surface send <surface-id> --type <event-type> --attachment <file-path> [options]
 
-POSTs an event to /v1/sessions/:id/events. The event is stamped as authored by
+POSTs an event to /v1/surfaces/:id/events. The event is stamped as authored by
 the agent (the relay derives identity from the API key — it cannot be spoofed).
 
 Required:
-  --type <t>          Event type. Must exist in the session's event schema
+  --type <t>          Event type. Must exist in the surface's event schema
                       with the agent in its emittedBy list.
   --data <v>          Event payload: a file path to a .json file, or inline
                       JSON. Use --data 'null' or --data '{}' for no payload.
 
+  ALTERNATIVE to --data:
+  --attachment <path>       One-shot: upload <path> as a surface-scope attachment, then
+                      send an event whose payload is the AttachmentRef. The event
+                      data is { attachment: <AttachmentRef> }; declare it in your event
+                      schema with \`format: pane-attachment-id\` on \`attachment.attachment_id\`.
+
 Options:
   --causation-id <id> Opaque causation id stored verbatim on the event.
   --idempotency-key <k>  Dedup key — a repeat send with the same key is a no-op.
@@ -26,15 +44,52 @@ Options:
 Output (stdout, JSON):
   { event, deduped }`;
 export async function runSend(args) {
-    const sessionId = args.positionals[0];
-    if (!sessionId)
-        fail("missing <session-id>", "invalid_args");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface send");
+    const surfaceId = args.positionals[0];
+    if (!surfaceId)
+        fail("missing <surface-id>", "invalid_args");
     const type = args.flags.get("type");
     if (!type)
         fail("missing --type", "invalid_args");
     const dataRaw = args.flags.get("data");
-    if (dataRaw === undefined)
-        fail("missing --data", "invalid_args");
+    const blobPath = args.flags.get("attachment");
+    if (dataRaw !== undefined && blobPath !== undefined) {
+        fail("--data and --attachment are mutually exclusive", "invalid_args");
+    }
+    if (dataRaw === undefined && blobPath === undefined) {
+        fail("missing --data or --attachment", "invalid_args");
+    }
+    const client = makeClient(args);
+    // --attachment path: upload the file as a surface-scope attachment, then send an
+    // event whose data is { attachment: <AttachmentRef> }. The surface's event schema
+    // is expected to declare a attachment field with format: pane-attachment-id.
+    if (blobPath !== undefined) {
+        let bytes;
+        try {
+            bytes = readFileSync(blobPath);
+        }
+        catch (e) {
+            fail(`failed to read --attachment '${blobPath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
+        }
+        try {
+            const ref = await client.uploadBlob(bytes, {
+                scope: "surface",
+                surfaceId: surfaceId,
+                filename: basename(blobPath),
+            });
+            const res = await client.sendEvent(surfaceId, {
+                type: type,
+                data: { attachment: ref },
+                causationId: args.flags.get("causation-id"),
+                idempotencyKey: args.flags.get("idempotency-key"),
+            });
+            printJson(res);
+        }
+        catch (e) {
+            failFromError(e);
+        }
+        return;
+    }
     let data;
     try {
         data = resolveJson(dataRaw, "--data");
@@ -42,9 +97,8 @@ export async function runSend(args) {
     catch (e) {
         fail(e instanceof Error ? e.message : String(e), "invalid_args");
     }
-    const client = makeClient(args);
     try {
-        const res = await client.sendEvent(sessionId, {
+        const res = await client.sendEvent(surfaceId, {
             type: type,
             data,
             causationId: args.flags.get("causation-id"),

package/dist/commands/skill.js

@@ -7,37 +7,41 @@
 // agent always reads what the relay it's actually talking to wants it
 // to read.
 //
-// Two subcommands:
-//   `pane skill`           — print the full markdown to stdout (the
+// Two verbs:
+//   `pane skill show`      — print the full markdown to stdout (the
 //                            install / refresh path; pipe to a file).
 //   `pane skill version`   — print just the relay's skill version (the
 //                            "is my local copy stale?" probe). The agent
 //                            compares this to the `<!-- pane skill v… -->`
 //                            comment in its local skill file and re-runs
-//                            `pane skill > <path>` when they differ.
+//                            `pane skill show > <path>` when they differ.
 //
 // Both are unauthenticated — the skill route is public on the relay and
 // an agent on a too-old CLI must be able to read the upgrade instructions
 // even before it has registered (or before its key was minted).
+import { assertKnownFlags } from "../argv.js";
 import { resolveRelayUrl } from "../config.js";
 import { fail } from "../output.js";
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+const VERSION_BOOLS = ["plain"];
 import { VERSION } from "../version.js";
 export const skillHelp = `pane skill — fetch the relay's SKILL.md (or its version)
 
 Usage:
-  pane skill                          Print the full skill to stdout.
+  pane skill show                     Print the full skill to stdout.
   pane skill version [--plain]        Print just the relay's skill version.
 
 The skill is auto-updating: the relay's deployed image owns the version,
 so this is always the skill that matches the relay you are talking to.
 
 Unauthenticated — no API key needed. An agent can call either form
-before 'pane register' to bootstrap or refresh its local skill copy.
+before 'pane agent register' to bootstrap or refresh its local skill copy.
 
-Subcommands:
-  (bare)              Fetch GET /skills/pane/SKILL.md and write the raw
+Verbs:
+  show                Fetch GET /skills/pane/SKILL.md and write the raw
                       markdown to stdout. Pipe to your local skill path:
-                          pane skill > ~/.claude/skills/pane/SKILL.md
+                          pane skill show > ~/.claude/skills/pane/SKILL.md
   version             Fetch GET /skills/pane/SKILL.md/version and print
                       the relay's skill version. Default output is the
                       JSON envelope; --plain prints just the version
@@ -78,8 +82,9 @@ async function failOnNon2xx(res, target) {
     const body = await res.text().catch(() => "");
     fail(`relay returned ${res.status} for ${target}${body ? ": " + body.slice(0, 200) : ""}`, "relay_error");
 }
-// `pane skill` (no positional) — print the full skill.
+// `pane skill show` — print the full skill.
 async function runSkillFetch(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane skill show");
     const url = resolveRelayUrl(args);
     const target = url + "/skills/pane/SKILL.md";
     const res = await fetchOrFail(target);
@@ -94,6 +99,7 @@ async function runSkillFetch(args) {
 }
 // `pane skill version [--plain]` — print just the version.
 async function runSkillVersion(args) {
+    assertKnownFlags(args, NO_FLAGS, VERSION_BOOLS, "pane skill version");
     const url = resolveRelayUrl(args);
     const target = url + "/skills/pane/SKILL.md/version";
     const res = await fetchOrFail(target);
@@ -124,13 +130,16 @@ async function runSkillVersion(args) {
 export async function runSkill(args) {
     const sub = args.positionals[0];
     switch (sub) {
-        case undefined:
+        case "show":
             await runSkillFetch(args);
             break;
         case "version":
             await runSkillVersion(args);
             break;
+        case undefined:
+            fail("missing verb — usage: pane skill <show|version> (run 'pane skill --help')", "invalid_args");
+            break;
         default:
-            fail(`unknown skill subcommand '${sub}' — expected 'version' or no subcommand (run 'pane skill --help')`, "invalid_args");
+            fail(`unknown skill verb '${sub}' — expected show|version (run 'pane skill --help')`, "invalid_args");
     }
 }

package/dist/commands/state.js

@@ -1,20 +1,23 @@
-// `pane state <id>` — snapshot of a session, optionally long-polled.
+// `pane surface show <id>` — snapshot of a surface, optionally long-polled.
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
-export const stateHelp = `pane state — show a session's metadata and event log
+const KNOWN_FLAGS = ["since", "wait"];
+const KNOWN_BOOLS = [];
+export const stateHelp = `pane surface show — show a surface's metadata and event log
 
 Usage:
-  pane state <session-id> [options]
+  pane surface show <surface-id> [options]
 
-By default non-blocking: fetches session metadata (GET /v1/sessions/:id) plus
-the event log (GET /v1/sessions/:id/events) and prints them together.
+By default non-blocking: fetches surface metadata (GET /v1/surfaces/:id) plus
+the event log (GET /v1/surfaces/:id/events) and prints them together.
 
 With --wait, blocks at the relay for up to <secs> if no new events are
 available since the cursor — returns as soon as something lands. Use this
 for headless polling agents that can't keep a WebSocket open (cron,
 FaaS, slow links): poll, then re-poll using next_cursor as --since on the
-next call. Compared to 'pane watch', it's higher latency per round-trip
-but no long-lived connection.
+next call. Compared to 'pane surface watch', it's higher latency per
+round-trip but no long-lived connection.
 
 Options:
   --since <cursor>    Only return events after this opaque cursor. Pass
@@ -31,9 +34,10 @@ Options:
 Output (stdout, JSON):
   { meta, events, next_cursor }`;
 export async function runState(args) {
-    const sessionId = args.positionals[0];
-    if (!sessionId)
-        fail("missing <session-id>", "invalid_args");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface show");
+    const surfaceId = args.positionals[0];
+    if (!surfaceId)
+        fail("missing <surface-id>", "invalid_args");
     const since = args.flags.get("since") ?? null;
     // --wait <secs>: hand the server the long-poll window. The relay caps
     // this at 30s; we pass the raw value and let the relay clamp (sending
@@ -50,8 +54,8 @@ export async function runState(args) {
     }
     const client = makeClient(args);
     try {
-        const meta = await client.getSession(sessionId);
-        const page = await client.getEvents(sessionId, {
+        const meta = await client.getSession(surfaceId);
+        const page = await client.getEvents(surfaceId, {
             since,
             ...(waitSeconds !== undefined ? { waitSeconds } : {}),
         });