@paneui/cli 0.0.4 → 0.0.6

package/dist/commands/blob-upload.js

@@ -0,0 +1,79 @@
+// `pane blob upload` — POST /v1/blobs (multipart), three scopes.
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = [
+    "file",
+    "scope",
+    "session-id",
+    "artifact-id",
+    "filename",
+    "mime",
+];
+const KNOWN_BOOLS = [];
+export const blobUploadHelp = `pane blob upload — upload a local file as a blob
+
+Usage:
+  pane blob upload --file <path> [options]
+
+Required:
+  --file <path>          Local file to upload.
+
+Scope (default: agent):
+  --scope <s>            "agent" | "session" | "artifact".
+  --session-id <id>      Required when --scope=session.
+  --artifact-id <id>     Required when --scope=artifact.
+
+Optional:
+  --filename <name>      Display filename (otherwise basename of --file).
+  --mime <type>          Declared Content-Type. The relay sniffs the bytes
+                         regardless — this is advisory.
+  --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, JSON):
+  BlobRef — { blob_id, scope, mime, size, sha256, ... }`;
+export async function runBlobUpload(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane blob upload");
+    const filePath = args.flags.get("file");
+    if (!filePath) {
+        fail("missing --file <path> — 'pane blob upload' requires a local file to upload", "invalid_args");
+    }
+    let bytes;
+    try {
+        bytes = readFileSync(filePath);
+    }
+    catch (e) {
+        fail(`failed to read --file '${filePath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
+    }
+    const scopeRaw = args.flags.get("scope") ?? "agent";
+    if (scopeRaw !== "agent" &&
+        scopeRaw !== "session" &&
+        scopeRaw !== "artifact") {
+        fail(`unknown --scope '${scopeRaw}' — expected one of: agent, session, artifact`, "invalid_args");
+    }
+    const scope = scopeRaw;
+    if (scope === "session" && !args.flags.get("session-id")) {
+        fail("--scope=session requires --session-id <id>", "invalid_args");
+    }
+    if (scope === "artifact" && !args.flags.get("artifact-id")) {
+        fail("--scope=artifact requires --artifact-id <id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const ref = await client.uploadBlob(bytes, {
+            scope,
+            sessionId: args.flags.get("session-id"),
+            artifactId: args.flags.get("artifact-id"),
+            filename: args.flags.get("filename") ?? basename(filePath),
+            mime: args.flags.get("mime"),
+        });
+        printJson(ref);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/blob.js

@@ -0,0 +1,135 @@
+// `pane blob` — manage binary attachments (blobs) on the relay.
+//
+// A blob is a typed binary file (image, PDF, audio, video, etc.) owned by an
+// agent and optionally bound to a session or artifact. Pages reference blobs
+// by id with `format: pane-blob-id`; participants can fetch a blob through a
+// minted capability URL (/b/<token>) without needing the agent's API key.
+//
+// This file is a thin dispatcher — each verb's actual logic lives in its own
+// file (blob-upload.ts, blob-download.ts, blob-show.ts, blob-delete.ts) and
+// the token sub-noun is dispatched via blob-token.ts.
+//
+// Most blob verbs read their primary positional (the blob_id) at
+// positionals[0]; we slice off our own verb before delegating so each verb
+// runner doesn't need to know it was reached through `pane blob`.
+import { runBlobUpload, blobUploadHelp } from "./blob-upload.js";
+import { runBlobDownload, blobDownloadHelp } from "./blob-download.js";
+import { runBlobShow, blobShowHelp } from "./blob-show.js";
+import { runBlobList, blobListHelp } from "./blob-list.js";
+import { runBlobDelete, blobDeleteHelp } from "./blob-delete.js";
+import { runBlobToken, blobTokenHelp } from "./blob-token.js";
+import { fail } from "../output.js";
+export const blobHelp = `pane blob — manage blobs (binary attachments) on the relay
+
+A blob is a typed binary file (image, PDF, audio, video, ...) the agent has
+uploaded to the relay. Blobs are scoped:
+
+  agent     — reusable across the agent's sessions (default)
+  session   — bound to one session; deleted with it
+  artifact  — bound to a reusable artifact; deleted with it
+
+Pages reference blobs by id (the relay's schema validates the id with
+\`format: pane-blob-id\`). For a participant-facing URL that bypasses the
+agent's API key, mint a token with 'pane blob token mint'.
+
+Usage:
+  pane blob <verb> [options]
+
+Verbs:
+  upload                 Upload a local file. Required: --file. Optional:
+                         --scope, --session-id, --artifact-id, --filename,
+                         --mime. Prints { blob_id, scope, mime, size, sha256,
+                         ... }.
+
+  download <blob-id>     Download a blob by id. Use --out <path> to write a
+                         file (default: writes to stdout — useful for piping).
+
+  show <blob-id>         Print a blob's metadata (HEAD-based — doesn't
+                         download the bytes).
+
+  list                   Enumerate YOUR agent's non-deleted blobs (newest
+                         first). Supports --cursor + --limit for pagination.
+
+  delete <blob-id>       Soft-delete a blob. Idempotent.
+
+  token <verb>           Capability URLs for a blob (mint | revoke | list).
+                         'mint' returns a /b/<token> URL anyone can GET, with
+                         optional --ttl and --once. 'revoke' invalidates one
+                         token. 'list' enumerates a blob's tokens (without
+                         the token plaintext, which is unrecoverable).
+
+Run \`pane blob <verb> --help\` for verb-specific options.
+
+Output: stdout is machine-readable JSON. Errors go to stderr as
+{"error":{"code","message"}} with a non-zero exit.`;
+/**
+ * Build a new ParsedArgs with the leading positional (the verb) stripped.
+ * The downstream verb runners read their primary positional (the blob_id)
+ * at positionals[0], so we hand them an args object that looks exactly like
+ * they were called directly — mirrors session.ts's shiftPositionals.
+ */
+function shiftPositionals(args) {
+    // Propagate danglingValueFlags so the leaf runner's assertKnownFlags
+    // can still distinguish "unknown flag" from "missing value" — see the
+    // matching note in session.ts's shiftPositionals.
+    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 runBlob(args) {
+    const verb = args.positionals[0];
+    // `pane blob token --help` (verb-level help on the token 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 ("token") is
+    // present, so the sub-noun must own its own --help routing.
+    if (verb === "token" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(blobTokenHelp + "\n");
+        return;
+    }
+    // `pane blob list --help` — same pattern (list takes no required positional
+    // so the general pre-empt would already fire, but for parity with session.ts
+    // we route through here when args carry the "list" positional explicitly).
+    if (verb === "list" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(blobListHelp + "\n");
+        return;
+    }
+    const inner = shiftPositionals(args);
+    switch (verb) {
+        case "upload":
+            await runBlobUpload(inner);
+            break;
+        case "download":
+            await runBlobDownload(inner);
+            break;
+        case "show":
+            await runBlobShow(inner);
+            break;
+        case "list":
+            await runBlobList(inner);
+            break;
+        case "delete":
+            await runBlobDelete(inner);
+            break;
+        case "token":
+            await runBlobToken(inner);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane blob <upload|download|show|list|delete|token> (run 'pane blob --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown blob verb '${verb}' — expected upload|download|show|list|delete|token (run 'pane blob --help')`, "invalid_args");
+    }
+}
+// Re-export per-verb helps so tests / docs can import them by canonical name
+// without knowing which file owns each verb.
+export { blobUploadHelp, blobDownloadHelp, blobShowHelp, blobListHelp, blobDeleteHelp, blobTokenHelp, };

package/dist/commands/config.js

@@ -1,14 +1,19 @@
-// `pane config` — show the resolved relay config without a network call.
+// `pane config show` — show the resolved relay config without a network call.
+import { assertKnownFlags } from "../argv.js";
 import { describeConfig } from "../config.js";
-import { printJson } from "../output.js";
+import { printJson, fail } from "../output.js";
+const NO_FLAGS = [];
+const NO_BOOLS = [];
 export const configHelp = `pane config — show the resolved relay config
 
 Usage:
-  pane config [options]
+  pane config show [options]
 
-Prints the relay URL and API-key info the CLI would use, and where each value
-came from. Makes NO network call — purely inspects flags, env vars, and the
-saved config file.
+Verbs:
+  show                Print the relay URL and API-key info the CLI would use,
+                      and where each value came from. Makes NO network call —
+                      purely inspects flags, env vars, and the saved config
+                      file.
 
 The API key is never printed in full: only a short masked prefix.
 
@@ -26,6 +31,20 @@ Output (stdout, JSON):
     key_source,     "flag" | "env" | "store" | "none"
     config_path     absolute path to the CLI config file
   }`;
-export async function runConfig(args) {
+async function runConfigShow(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane config show");
     printJson(describeConfig(args));
 }
+export async function runConfig(args) {
+    const verb = args.positionals[0];
+    switch (verb) {
+        case "show":
+            await runConfigShow(args);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane config show (run 'pane config --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown config verb '${verb}' — expected show (run 'pane config --help')`, "invalid_args");
+    }
+}

package/dist/commands/create.js

@@ -1,8 +1,24 @@
-// `pane create` — create a session via POST /v1/sessions.
+// `pane session create` — create a session via POST /v1/sessions.
 import { createSessionSchema } from "@paneui/core";
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { resolveJson, resolveText } from "../input.js";
 import { printJson, fail, failFromError } from "../output.js";
+const KNOWN_FLAGS = [
+    "artifact",
+    "artifact-id",
+    "artifact-type",
+    "version",
+    "event-schema",
+    "input-schema",
+    "title",
+    "input-data",
+    "ttl",
+    "participants",
+    "metadata",
+    "callback",
+];
+const KNOWN_BOOLS = [];
 // Translate a Zod schema path (e.g. ["participants","humans"]) back to the
 // public CLI flag the user actually typed. Without this, a `--participants 0`
 // rejection surfaces as `participants.humans: ...` — which leaks the wire
@@ -20,11 +36,13 @@ const SCHEMA_PATH_TO_FLAG = {
     metadata: "--metadata",
     callback: "--callback",
     input_data: "--input-data",
+    title: "--title",
     "artifact.id": "--artifact-id",
     "artifact.version": "--version",
     "artifact.type": "--artifact-type",
     "artifact.source": "--artifact",
     "artifact.event_schema": "--event-schema",
+    "artifact.input_schema": "--input-schema",
 };
 function schemaPathToFlag(path) {
     const dotted = path.map(String).join(".");
@@ -39,16 +57,16 @@ function schemaPathToFlag(path) {
     }
     return dotted;
 }
-export const createHelp = `pane create — create a Pane session
+export const createHelp = `pane session create — create a Pane session
 
 A session is one use of an artifact. Supply the artifact in ONE of two ways:
 
   Reference form — instance an existing reusable artifact (the cheap path,
   no HTML re-sent):
-    pane create --artifact-id <id|slug> [--version <n>] [--input-data <v>]
+    pane session create --artifact-id <id|slug> [--version <n>] [--input-data <v>]
 
   Inline form — a one-off artifact, defined on this call:
-    pane create --artifact <path|inline> [--event-schema <path|json>] [options]
+    pane session create --artifact <path|inline> [--event-schema <path|json>] [options]
 
 Exactly one of --artifact-id / --artifact must be given.
 
@@ -84,8 +102,22 @@ Artifact (choose one):
                       emittedBy is any non-empty subset of ["page", "agent"].
                       payload is a JSON Schema; the relay validates every
                       emit against it. See docs/SPEC.md for the full grammar.
+  --input-schema <v>  Inline-form input schema. A .json file, or inline JSON.
+                      Optional with --artifact, rejected with --artifact-id
+                      (the schema comes from the pinned artifact version
+                      there). When present, the session's --input-data is
+                      validated against it AND any blob ids declared at a
+                      "format": "pane-blob-id" site become reachable from the
+                      page via window.pane.downloadBlob. Without it, blob
+                      refs in --input-data are silently unreachable. See
+                      docs/SPEC.md and #208.
 
 Options:
+  --title <text>      Tab title shown to the human (max 80 chars, single
+                      line). Required, with one ergonomic exception: when
+                      --artifact-id references a named artifact, the relay
+                      falls back to Artifact.name. Inline (--artifact …) form
+                      always needs --title.
   --input-data <v>    This instance's seed data — a JSON object (file path or
                       inline JSON), validated by the relay against the artifact
                       version's input_schema. The page reads it as
@@ -110,6 +142,7 @@ Output (stdout, JSON):
 
 Deliver urls.humans to the human(s); keep tokens.agent for the WS stream.`;
 export async function runCreate(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane session create");
     const artifactIdVal = args.flags.get("artifact-id");
     const artifactVal = args.flags.get("artifact");
     // Exactly one of the two artifact forms must be present.
@@ -126,7 +159,11 @@ export async function runCreate(args) {
     const candidate = {};
     if (artifactIdVal !== undefined) {
         // Reference form — instance an existing named artifact. --artifact /
-        // --event-schema are not needed here.
+        // --event-schema / --input-schema are not used here: the artifact's
+        // pinned version carries them already.
+        if (args.flags.get("input-schema") !== undefined) {
+            fail("--input-schema is incompatible with --artifact-id — the input schema comes from the pinned artifact version. Author the schema on the artifact (`pane artifact create --input-schema …`) instead.", "invalid_args");
+        }
         const ref = { id: artifactIdVal };
         const versionRaw = args.flags.get("version");
         if (versionRaw !== undefined) {
@@ -139,12 +176,18 @@ export async function runCreate(args) {
         candidate["artifact"] = ref;
     }
     else {
-        // Inline form — the event schema rides inside the `artifact` object; the
-        // relay transparently creates an anonymous artifact behind it.
-        // --event-schema is optional: omitting it makes a view-only one-off (a
-        // report/dashboard the human only views), and the relay then rejects every
-        // page/agent emit.
+        // Inline form — the event + input schemas ride inside the `artifact`
+        // object; the relay transparently creates an anonymous artifact behind
+        // it. Both schemas are optional:
+        //  - --event-schema absent → view-only one-off (no page/agent emits)
+        //  - --input-schema absent → no input contract; --input-data passes
+        //    through unvalidated AND any blob ids in it are unreachable from
+        //    the page (the participant blob-download bridge walks input_data
+        //    against the artifact version's inputSchema). Pass --input-schema
+        //    when --input-data carries blob refs the page needs to render.
+        //    See #208.
         const schemaVal = args.flags.get("event-schema");
+        const inputSchemaVal = args.flags.get("input-schema");
         const artifactType = (args.flags.get("artifact-type") ?? "html-inline");
         if (artifactType !== "html-inline" && artifactType !== "html-ref") {
             fail("--artifact-type must be 'html-inline' or 'html-ref'", "invalid_args");
@@ -158,8 +201,10 @@ export async function runCreate(args) {
         catch (e) {
             fail(e instanceof Error ? e.message : String(e), "invalid_args");
         }
-        // Build the inline artifact object. event_schema is OMITTED entirely (not
-        // set to undefined) when --event-schema is absent — a view-only artifact.
+        // Build the inline artifact object. event_schema / input_schema are
+        // OMITTED entirely (not set to undefined) when their flags are absent —
+        // omission is meaningful at the relay (view-only artifact / no input
+        // contract).
         const inlineArtifact = {
             type: artifactType,
             source,
@@ -172,8 +217,29 @@ export async function runCreate(args) {
                 fail(e instanceof Error ? e.message : String(e), "invalid_args");
             }
         }
+        if (inputSchemaVal !== undefined) {
+            try {
+                const v = resolveJson(inputSchemaVal, "--input-schema");
+                if (v === null || typeof v !== "object" || Array.isArray(v)) {
+                    fail("--input-schema must be a JSON object", "invalid_args");
+                }
+                inlineArtifact["input_schema"] = v;
+            }
+            catch (e) {
+                fail(e instanceof Error ? e.message : String(e), "invalid_args");
+            }
+        }
         candidate["artifact"] = inlineArtifact;
     }
+    // --title — passthrough, no client-side requiredness. The relay is the
+    // single source of truth: it enforces "required, with --artifact-id +
+    // Artifact.name as the only fallback" and the shape rules (length, control
+    // chars). Keeping all that server-side avoids drift between the CLI's
+    // pre-checks and the relay's actual rules.
+    const titleRaw = args.flags.get("title");
+    if (titleRaw !== undefined) {
+        candidate["title"] = titleRaw;
+    }
     // --input-data — per-instance seed data, applies to either form (the relay
     // validates it against the pinned version's input_schema).
     const inputDataRaw = args.flags.get("input-data");

package/dist/commands/delete.js

@@ -1,10 +1,13 @@
-// `pane delete <id>` — close/delete a session.
+// `pane session delete <id>` — close/delete a session.
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
-export const deleteHelp = `pane delete — close/delete a session
+const KNOWN_FLAGS = [];
+const KNOWN_BOOLS = [];
+export const deleteHelp = `pane session delete — close/delete a session
 
 Usage:
-  pane delete <session-id> [options]
+  pane session delete <session-id> [options]
 
 Closes and deletes the session (DELETE /v1/sessions/:id). Idempotent on the
 relay side — deleting an already-closed session still succeeds.
@@ -17,6 +20,7 @@ Options:
 Output (stdout, JSON):
   { session_id, deleted: true }`;
 export async function runDelete(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane session delete");
     const sessionId = args.positionals[0];
     if (!sessionId)
         fail("missing <session-id>", "invalid_args");

package/dist/commands/feedback.js

@@ -1,5 +1,9 @@
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
+const CREATE_FLAGS = ["type", "message", "session-id"];
+const LIST_FLAGS = ["limit", "before"];
+const NO_BOOLS = [];
 export const feedbackHelp = `pane feedback — submit / list feedback to the relay operator
 
 Feedback is a one-shot bug report, feature request, or note from YOUR agent
@@ -48,6 +52,7 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8");
 }
 async function runFeedbackCreate(args) {
+    assertKnownFlags(args, CREATE_FLAGS, NO_BOOLS, "pane feedback create");
     const type = args.flags.get("type");
     const rawMessage = args.flags.get("message");
     const sessionId = args.flags.get("session-id");
@@ -87,6 +92,7 @@ async function runFeedbackCreate(args) {
     }
 }
 async function runFeedbackList(args) {
+    assertKnownFlags(args, LIST_FLAGS, NO_BOOLS, "pane feedback list");
     const limitRaw = args.flags.get("limit");
     const before = args.flags.get("before");
     let limit;

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 session list` — enumerate YOUR agent's sessions.
+//
+// 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 session is intact and listable here. Pair with
+// `pane session participant new` to mint a fresh URL on a session 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", "artifact-id"];
+const KNOWN_BOOLS = [];
+export const listHelp = `pane session list — list YOUR agent's sessions
+
+Prints sessions (newest first) with no secrets in the response. Participant
+tokens are stored hashed and CANNOT be recovered — if you lost a session URL,
+mint a fresh one with 'pane session participant new <session-id>'.
+
+Usage:
+  pane session 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.
+  --artifact-id <i> Filter to sessions instantiated from a specific named
+                    artifact (head id; not version id). Inline (anonymous)
+                    artifacts 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 session is still alive):
+  pane session list                                       # find the
+                                                          #   session_id +
+                                                          #   participant_id
+                                                          #   you lost
+  pane session participant new <session-id>               # mint a fresh URL
+  pane session participant revoke <session-id> <p-id>     # invalidate the
+                                                          #   old URL
+
+Output (stdout, JSON):
+  {
+    items: [
+      {
+        session_id, title, status, artifact_id, artifact_version_id,
+        artifact_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 session 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 artifactId = args.flags.get("artifact-id");
+    if (artifactId !== undefined && artifactId !== "") {
+        opts.artifact_id = artifactId;
+    }
+    const client = makeClient(args);
+    try {
+        const page = await client.listSessions(opts);
+        printJson(page);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}