@paneui/cli 0.0.4 → 0.0.6

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 session participant <new|revoke>` — mint or invalidate one
+// participant URL on an existing session. Recovery + leak-containment
+// primitives that together replace the destructive `pane session delete +
+// pane session create` workaround for the lost-URL case.
+//
+// This file is a sub-noun dispatcher under `pane session`. The session
+// 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 session participant — manage one session'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 session keeps its event log, artifact pin, and created_at.
+Use 'revoke' to invalidate a single URL while keeping the session alive.
+
+Usage:
+  pane session participant <verb> <args>
+
+Verbs:
+  list <session-id>           List the participants on one session, including
+                              revoked rows (for audit). Returns
+                              { session_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 <session-id>            Mint a fresh human URL on an existing session.
+                              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 <session-id> <participant-id>
+                              Invalidate one participant URL. The session'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 session list                                       # find session_id
+  pane session participant list <session-id>              # find participant
+                                                          #   ids on that
+                                                          #   session
+  pane session participant new <session-id>               # mint a new URL
+  pane session participant revoke <session-id> <p-id>     # invalidate the
+                                                          #   old URL
+
+Output: stdout is machine-readable JSON.`;
+async function runParticipantList(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane session participant list");
+    const sessionId = args.positionals[1];
+    if (!sessionId) {
+        fail("missing <session-id> — usage: pane session participant list <session-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.listParticipants(sessionId);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runParticipantNew(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane session participant new");
+    const sessionId = args.positionals[1];
+    if (!sessionId) {
+        fail("missing <session-id> — usage: pane session participant new <session-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.mintParticipant(sessionId);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runParticipantRevoke(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane session participant revoke");
+    const sessionId = args.positionals[1];
+    const participantId = args.positionals[2];
+    if (!sessionId || !participantId) {
+        fail("missing arguments — usage: pane session participant revoke <session-id> <participant-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        await client.revokeParticipant(sessionId, participantId);
+        printJson({
+            session_id: sessionId,
+            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 session.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 session participant <list|new|revoke> (run 'pane session participant --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown participant verb '${verb}' — expected list|new|revoke (run 'pane session 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,11 +1,17 @@
-// `pane send <id>` — append an agent event to a session.
+// `pane session send <id>` — append an agent event to a session.
+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", "blob", "causation-id", "idempotency-key"];
+const KNOWN_BOOLS = [];
+export const sendHelp = `pane session send — emit an agent event into a session
 
 Usage:
-  pane send <session-id> --type <event-type> --data <path|json> [options]
+  pane session send <session-id> --type <event-type> --data <path|json> [options]
+  pane session send <session-id> --type <event-type> --blob <file-path> [options]
 
 POSTs an event to /v1/sessions/:id/events. The event is stamped as authored by
 the agent (the relay derives identity from the API key — it cannot be spoofed).
@@ -16,6 +22,12 @@ Required:
   --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:
+  --blob <path>       One-shot: upload <path> as a session-scope blob, then
+                      send an event whose payload is the BlobRef. The event
+                      data is { blob: <BlobRef> }; declare it in your event
+                      schema with \`format: pane-blob-id\` on \`blob.blob_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,6 +38,7 @@ Options:
 Output (stdout, JSON):
   { event, deduped }`;
 export async function runSend(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane session send");
     const sessionId = args.positionals[0];
     if (!sessionId)
         fail("missing <session-id>", "invalid_args");
@@ -33,8 +46,44 @@ export async function runSend(args) {
     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("blob");
+    if (dataRaw !== undefined && blobPath !== undefined) {
+        fail("--data and --blob are mutually exclusive", "invalid_args");
+    }
+    if (dataRaw === undefined && blobPath === undefined) {
+        fail("missing --data or --blob", "invalid_args");
+    }
+    const client = makeClient(args);
+    // --blob path: upload the file as a session-scope blob, then send an
+    // event whose data is { blob: <BlobRef> }. The session's event schema
+    // is expected to declare a blob field with format: pane-blob-id.
+    if (blobPath !== undefined) {
+        let bytes;
+        try {
+            bytes = readFileSync(blobPath);
+        }
+        catch (e) {
+            fail(`failed to read --blob '${blobPath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
+        }
+        try {
+            const ref = await client.uploadBlob(bytes, {
+                scope: "session",
+                sessionId: sessionId,
+                filename: basename(blobPath),
+            });
+            const res = await client.sendEvent(sessionId, {
+                type: type,
+                data: { blob: 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,7 +91,6 @@ 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, {
             type: type,

package/dist/commands/session.js

@@ -0,0 +1,118 @@
+// `pane session` — the central noun of pane: open, observe, send to, and
+// close a session.
+//
+// A session is one *use* of an artifact: an open URL the human(s) interact
+// with, plus an event log the agent reads and appends to. Every other noun
+// (artifact, blob, key, taste, feedback) exists in service of sessions.
+//
+// This file is a thin dispatcher — each verb's actual logic lives in its own
+// file (create.ts, state.ts, send.ts, watch.ts, delete.ts). The verb runners
+// expect the session id at positionals[0]; we slice off our own verb before
+// delegating so they don't need to know they're being called via `session`.
+import { runCreate } from "./create.js";
+import { runState } from "./state.js";
+import { runSend } from "./send.js";
+import { runWatch } from "./watch.js";
+import { runDelete } from "./delete.js";
+import { runList, listHelp } from "./list.js";
+import { runParticipant, participantHelp } from "./participant.js";
+import { fail } from "../output.js";
+export const sessionHelp = `pane session — open, observe, send to, and close sessions
+
+A session is one use of an artifact: an open URL the human(s) interact with,
+plus an event log the agent reads and appends to.
+
+Usage:
+  pane session <verb> [options]
+
+Verbs:
+  create            Create a session (POST /v1/sessions). Prints session_id,
+                    urls, tokens, expires_at.
+  list              Enumerate YOUR agent's sessions. The recovery primitive
+                    for "I dropped the create response" — sessions are
+                    listable, but participant tokens are stored hashed and
+                    CANNOT be recovered. Use 'participant new' to mint a
+                    fresh URL.
+  show <id>         Non-blocking snapshot: session metadata + event log.
+                    Supports --wait <secs> for relay-side long-polling.
+  send <id>         Emit an agent event into a session.
+  watch <id>        Stream a session's events as JSON-lines on stdout
+                    (long-lived; the building block for pipe-readers).
+  delete <id>       Close/delete a session (DELETE /v1/sessions/:id).
+  participant         List / mint / revoke participant URLs on an existing
+    <list|new|revoke> session. 'list' returns the participant ids you need
+                      for 'revoke'; 'new' replaces the destructive 'delete
+                      + recreate' workaround for a lost URL; 'revoke'
+                      invalidates one URL without touching the session.
+
+Run \`pane session <verb> --help\` for verb-specific options.`;
+/**
+ * Build a new ParsedArgs with the leading positional (the verb) stripped.
+ * The downstream verb runners (runState / runSend / runWatch / runDelete)
+ * read the session id at positionals[0], so we hand them an args object that
+ * looks exactly like the pre-restructure invocation.
+ */
+function shiftPositionals(args) {
+    // Propagate danglingValueFlags too — otherwise the leaf runner's
+    // assertKnownFlags can't tell that the user wrote `--title` without a
+    // value, and falls through to a less-useful downstream error.
+    const out = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+    };
+    if (args.danglingValueFlags !== undefined) {
+        out.danglingValueFlags = args.danglingValueFlags;
+    }
+    return out;
+}
+export async function runSession(args) {
+    const verb = args.positionals[0];
+    // `pane session participant --help` (verb-level help on the participant
+    // sub-noun, with no further sub-verb). The general --help pre-empt in
+    // index.ts only fires when no positional follows the noun; here a
+    // positional ("participant") is present, so the sub-noun must own its own
+    // --help routing.
+    if (verb === "participant" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(participantHelp + "\n");
+        return;
+    }
+    // `pane session list --help` — same pattern.
+    if (verb === "list" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(listHelp + "\n");
+        return;
+    }
+    const inner = shiftPositionals(args);
+    switch (verb) {
+        case "create":
+            await runCreate(inner);
+            break;
+        case "list":
+            await runList(inner);
+            break;
+        case "show":
+            await runState(inner);
+            break;
+        case "send":
+            await runSend(inner);
+            break;
+        case "watch":
+            await runWatch(inner);
+            break;
+        case "delete":
+            await runDelete(inner);
+            break;
+        case "participant":
+            await runParticipant(inner);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane session <create|list|show|send|watch|delete|participant> (run 'pane session --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown session verb '${verb}' — expected create|list|show|send|watch|delete|participant (run 'pane session --help')`, "invalid_args");
+    }
+}

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,10 +1,13 @@
-// `pane state <id>` — snapshot of a session, optionally long-polled.
+// `pane session show <id>` — snapshot of a session, 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 session show — show a session's metadata and event log
 
 Usage:
-  pane state <session-id> [options]
+  pane session show <session-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.
@@ -13,8 +16,8 @@ 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 session 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,6 +34,7 @@ Options:
 Output (stdout, JSON):
   { meta, events, next_cursor }`;
 export async function runState(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane session show");
     const sessionId = args.positionals[0];
     if (!sessionId)
         fail("missing <session-id>", "invalid_args");