@paneui/cli 0.0.6 → 0.0.8

package/dist/commands/participant.js

@@ -1,9 +1,9 @@
-// `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.
+// `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 session`. The session
+// 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
@@ -14,32 +14,32 @@ 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
+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 session keeps its event log, artifact pin, and created_at.
-Use 'revoke' to invalidate a single URL while keeping the session alive.
+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 session participant <verb> <args>
+  pane surface participant <verb> <args>
 
 Verbs:
-  list <session-id>           List the participants on one session, including
+  list <surface-id>           List the participants on one surface, including
                               revoked rows (for audit). Returns
-                              { session_id, items: [...] } where each item
+                              { 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 <session-id>            Mint a fresh human URL on an existing session.
+  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 <session-id> <participant-id>
-                              Invalidate one participant URL. The session's
+  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.
@@ -54,24 +54,24 @@ Options:
   -h, --help                  Show this help.
 
 Recovery recipe:
-  pane session list                                       # find session_id
-  pane session participant list <session-id>              # find participant
+  pane surface list                                       # find surface_id
+  pane surface participant list <surface-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
+                                                          #   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 session participant list");
-    const sessionId = args.positionals[1];
-    if (!sessionId) {
-        fail("missing <session-id> — usage: pane session participant list <session-id>", "invalid_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(sessionId);
+        const res = await client.listParticipants(surfaceId);
         printJson(res);
     }
     catch (e) {
@@ -79,14 +79,14 @@ async function runParticipantList(args) {
     }
 }
 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");
+    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(sessionId);
+        const res = await client.mintParticipant(surfaceId);
         printJson(res);
     }
     catch (e) {
@@ -94,17 +94,17 @@ async function runParticipantNew(args) {
     }
 }
 async function runParticipantRevoke(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane session participant revoke");
-    const sessionId = args.positionals[1];
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane surface participant revoke");
+    const surfaceId = 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");
+    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(sessionId, participantId);
+        await client.revokeParticipant(surfaceId, participantId);
         printJson({
-            session_id: sessionId,
+            surface_id: surfaceId,
             participant_id: participantId,
             revoked: true,
         });
@@ -115,7 +115,7 @@ async function runParticipantRevoke(args) {
 }
 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
+    // the verb's args. (The surface.ts dispatcher already shifted off the
     // "participant" marker before calling us.)
     const verb = args.positionals[0];
     switch (verb) {
@@ -129,9 +129,9 @@ export async function runParticipant(args) {
             await runParticipantRevoke(args);
             break;
         case undefined:
-            fail("missing verb — usage: pane session participant <list|new|revoke> (run 'pane session participant --help')", "invalid_args");
+            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 session participant --help')`, "invalid_args");
+            fail(`unknown participant verb '${verb}' — expected list|new|revoke (run 'pane surface participant --help')`, "invalid_args");
     }
 }

package/dist/commands/send.js

@@ -1,32 +1,38 @@
-// `pane session 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";
-const KNOWN_FLAGS = ["type", "data", "blob", "causation-id", "idempotency-key"];
+const KNOWN_FLAGS = [
+    "type",
+    "data",
+    "attachment",
+    "causation-id",
+    "idempotency-key",
+];
 const KNOWN_BOOLS = [];
-export const sendHelp = `pane session send — emit an agent event into a session
+export const sendHelp = `pane surface send — emit an agent event into a surface
 
 Usage:
-  pane session send <session-id> --type <event-type> --data <path|json> [options]
-  pane session send <session-id> --type <event-type> --blob <file-path> [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:
-  --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\`.
+  --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.
@@ -38,42 +44,42 @@ 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");
+    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");
-    const blobPath = args.flags.get("blob");
+    const blobPath = args.flags.get("attachment");
     if (dataRaw !== undefined && blobPath !== undefined) {
-        fail("--data and --blob are mutually exclusive", "invalid_args");
+        fail("--data and --attachment are mutually exclusive", "invalid_args");
     }
     if (dataRaw === undefined && blobPath === undefined) {
-        fail("missing --data or --blob", "invalid_args");
+        fail("missing --data or --attachment", "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.
+    // --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 --blob '${blobPath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
+            fail(`failed to read --attachment '${blobPath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
         }
         try {
             const ref = await client.uploadBlob(bytes, {
-                scope: "session",
-                sessionId: sessionId,
+                scope: "surface",
+                surfaceId: surfaceId,
                 filename: basename(blobPath),
             });
-            const res = await client.sendEvent(sessionId, {
+            const res = await client.sendEvent(surfaceId, {
                 type: type,
-                data: { blob: ref },
+                data: { attachment: ref },
                 causationId: args.flags.get("causation-id"),
                 idempotencyKey: args.flags.get("idempotency-key"),
             });
@@ -92,7 +98,7 @@ export async function runSend(args) {
         fail(e instanceof Error ? e.message : String(e), "invalid_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/state.js

@@ -1,22 +1,22 @@
-// `pane session show <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";
 const KNOWN_FLAGS = ["since", "wait"];
 const KNOWN_BOOLS = [];
-export const stateHelp = `pane session show — show a session's metadata and event log
+export const stateHelp = `pane surface show — show a surface's metadata and event log
 
 Usage:
-  pane session show <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 session watch', it's higher latency per
+next call. Compared to 'pane surface watch', it's higher latency per
 round-trip but no long-lived connection.
 
 Options:
@@ -34,10 +34,10 @@ 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");
+    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
@@ -54,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 } : {}),
         });

package/dist/commands/{session.js → surface.js}

@@ -1,14 +1,14 @@
-// `pane session` — the central noun of pane: open, observe, send to, and
-// close a session.
+// `pane surface` — the central noun of pane: open, observe, send to, and
+// close a surface.
 //
-// A session is one *use* of an artifact: an open URL the human(s) interact
+// A surface is one *use* of an template: 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.
+// (template, attachment, key, taste, feedback) exists in service of surfaces.
 //
 // 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`.
+// expect the surface id at positionals[0]; we slice off our own verb before
+// delegating so they don't need to know they're being called via `surface`.
 import { runCreate } from "./create.js";
 import { runState } from "./state.js";
 import { runSend } from "./send.js";
@@ -17,39 +17,39 @@ 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
+export const sessionHelp = `pane surface — open, observe, send to, and close surfaces
 
-A session is one use of an artifact: an open URL the human(s) interact with,
+A surface is one use of an template: an open URL the human(s) interact with,
 plus an event log the agent reads and appends to.
 
 Usage:
-  pane session <verb> [options]
+  pane surface <verb> [options]
 
 Verbs:
-  create            Create a session (POST /v1/sessions). Prints session_id,
+  create            Create a surface (POST /v1/surfaces). Prints surface_id,
                     urls, tokens, expires_at.
-  list              Enumerate YOUR agent's sessions. The recovery primitive
-                    for "I dropped the create response" — sessions are
+  list              Enumerate YOUR agent's surfaces. The recovery primitive
+                    for "I dropped the create response" — surfaces 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.
+  show <id>         Non-blocking snapshot: surface 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
+  send <id>         Emit an agent event into a surface.
+  watch <id>        Stream a surface'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).
+  delete <id>       Close/delete a surface (DELETE /v1/surfaces/:id).
   participant         List / mint / revoke participant URLs on an existing
-    <list|new|revoke> session. 'list' returns the participant ids you need
+    <list|new|revoke> surface. '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.
+                      invalidates one URL without touching the surface.
 
-Run \`pane session <verb> --help\` for verb-specific options.`;
+Run \`pane surface <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
+ * read the surface id at positionals[0], so we hand them an args object that
  * looks exactly like the pre-restructure invocation.
  */
 function shiftPositionals(args) {
@@ -68,7 +68,7 @@ function shiftPositionals(args) {
 }
 export async function runSession(args) {
     const verb = args.positionals[0];
-    // `pane session participant --help` (verb-level help on the participant
+    // `pane surface 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
@@ -79,7 +79,7 @@ export async function runSession(args) {
         process.stdout.write(participantHelp + "\n");
         return;
     }
-    // `pane session list --help` — same pattern.
+    // `pane surface list --help` — same pattern.
     if (verb === "list" &&
         args.bools.has("help") &&
         args.positionals.length === 1) {
@@ -110,9 +110,9 @@ export async function runSession(args) {
             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");
+            fail("missing verb — usage: pane surface <create|list|show|send|watch|delete|participant> (run 'pane surface --help')", "invalid_args");
             break;
         default:
-            fail(`unknown session verb '${verb}' — expected create|list|show|send|watch|delete|participant (run 'pane session --help')`, "invalid_args");
+            fail(`unknown surface verb '${verb}' — expected create|list|show|send|watch|delete|participant (run 'pane surface --help')`, "invalid_args");
     }
 }

package/dist/commands/taste.js

@@ -1,21 +1,21 @@
 // `pane taste` — read / write / clear the calling agent's freeform "taste
-// notes" markdown blob.
+// notes" markdown attachment.
 //
 // Taste notes are presentation preferences the agent has learned from human
 // feedback ("denser layout", "no rounded corners", "use a dark header") — the
-// kind of guidance that should outlive a single session. The intended loop:
+// kind of guidance that should outlive a single surface. The intended loop:
 //
-//   1. Before generating a pane artifact, run `pane taste get` and feed the
+//   1. Before generating a pane template, run `pane taste get` and feed the
 //      `taste` field into the prompt so prior preferences shape the output.
 //   2. When the human gives new presentation feedback, run `pane taste get`,
 //      merge the feedback into the existing notes IN THE PROMPT, then call
-//      `pane taste set` with the WHOLE new blob (the relay does whole-blob
+//      `pane taste set` with the WHOLE new attachment (the relay does whole-attachment
 //      replace, not append — that's deliberate, so the notes can't grow
 //      unbounded into noise).
 //
 // Keep taste notes about *presentation/UI taste only* — colours, density,
-// component preferences. Project context, todos, and per-session state belong
-// somewhere else. Today the blob is keyed by the agent's API key (per-agent);
+// component preferences. Project context, todos, and per-surface state belong
+// somewhere else. Today the attachment is keyed by the agent's API key (per-agent);
 // when pane gains first-class humans, this may move to per-human.
 import { readFileSync } from "node:fs";
 import { assertKnownFlags } from "../argv.js";
@@ -27,25 +27,25 @@ const SET_FLAGS = ["file"];
 const CLEAR_BOOLS = ["yes"];
 export const tasteHelp = `pane taste — read / write / clear YOUR agent's UI taste notes
 
-Taste notes are a small markdown blob storing presentation preferences your
+Taste notes are a small markdown attachment storing presentation preferences your
 agent has picked up from human feedback ("denser table", "no rounded corners",
-"use a dark header"). Read them before generating a pane artifact so prior
+"use a dark header"). Read them before generating a pane template so prior
 feedback shapes the output; rewrite them whenever the human gives new
 presentation feedback. Keep entries about UI/presentation taste only — not
-project context, todos, or session state.
+project context, todos, or surface state.
 
 Usage:
   pane taste <subcommand> [options]
 
 Subcommands:
-  get        Print the current notes blob:
+  get        Print the current notes attachment:
              { taste: string|null, updated_at: string|null, bytes: number }.
              taste is null and bytes is 0 when notes have never been written.
 
-  set        Whole-blob replace. Source the markdown via --file <path>,
+  set        Whole-attachment replace. Source the markdown via --file <path>,
              --file - (read stdin), or by piping into 'pane taste set' with
              no flag. The relay rejects empty/whitespace-only payloads and
-             caps the blob at MAX_TASTE_BYTES (utf8). To clear the notes,
+             caps the attachment at MAX_TASTE_BYTES (utf8). To clear the notes,
              use 'pane taste clear', not 'set' with an empty body.
 
   clear      Delete the notes. Requires --yes (it is destructive). Prints
@@ -92,7 +92,7 @@ async function runTasteGet(args) {
 async function runTasteSet(args) {
     assertKnownFlags(args, SET_FLAGS, NO_BOOLS, "pane taste set");
     const filePath = args.flags.get("file");
-    // Source the blob deterministically — no isTTY-flag fusing, because
+    // Source the attachment deterministically — no isTTY-flag fusing, because
     // `!process.stdin.isTTY` is true under every non-interactive caller
     // (pipes, redirects, closed fd, CI, agent harnesses) and would wrongly
     // reject `--file` for the entire target audience. See issue #148.
@@ -119,7 +119,7 @@ async function runTasteSet(args) {
         fail("'pane taste set' needs input — pass --file <path>, pipe markdown on stdin, or use --file -", "invalid_args");
     }
     if (taste.trim().length === 0) {
-        fail("'pane taste set' refuses an empty or whitespace-only blob — use 'pane taste clear --yes' to delete the notes", "invalid_args");
+        fail("'pane taste set' refuses an empty or whitespace-only attachment — use 'pane taste clear --yes' to delete the notes", "invalid_args");
     }
     const client = makeClient(args);
     try {