@paneui/cli 0.0.6 → 0.0.8

package/dist/commands/claim.js

@@ -0,0 +1,68 @@
+// `pane agent claim <code>` — bind this agent to a human via a one-shot
+// claim code the human generated in their settings UI.
+//
+// Flow (§6.1):
+//   1. Alice opens Settings → "Claim an agent" → relay mints a one-shot code,
+//      shows it to her once, 15-min TTL.
+//   2. Alice hands the code to the agent out-of-band (this CLI invocation
+//      is exactly that handoff).
+//   3. CLI calls POST /v1/agents/claim with the calling agent's API key.
+//   4. Relay binds Agent.ownerHumanId = alice.id, migrates surface ownership.
+//
+// The CLI does NOT print the human's email or id — only the relay's response,
+// which is { ok, owner_human_id, claimed_at }. The agent's existing API key
+// keeps working.
+import { PaneClient, PaneApiError } from "@paneui/core";
+import { assertKnownFlags } from "../argv.js";
+import { resolveConfig } from "../config.js";
+import { printJson, fail } from "../output.js";
+const KNOWN_FLAGS = ["url", "api-key"];
+const KNOWN_BOOLS = [];
+export const claimHelp = `pane agent claim — claim this agent for a human
+
+Usage:
+  pane agent claim <code>
+
+Binds the calling agent to the human whose one-shot claim code is provided.
+The human generates the code in their settings UI (or via the relay's
+POST /v1/self/claim-codes endpoint) and hands it to the agent out-of-band.
+
+Arguments:
+  <code>              The one-shot claim code (begins with cc_). Required.
+
+Options:
+  --url <url>         Relay base URL. Falls back to PANE_URL / config file.
+  --api-key <key>     Agent API key. Falls back to PANE_API_KEY / config file.
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  { ok: true, owner_human_id, claimed_at }
+
+Errors:
+  invalid_code             code is unknown, expired, or already consumed
+  agent_already_claimed    this agent already has an owning human
+
+Notes:
+  This is a one-way operation. To rotate the owner, revoke this agent
+  (\`pane key revoke\`) and register a new one.`;
+export async function runClaim(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane agent claim");
+    const code = args.positionals[0];
+    if (!code) {
+        fail("missing required argument: <code> — run 'pane agent claim --help'", "invalid_args");
+        return;
+    }
+    const creds = resolveConfig(args);
+    const client = new PaneClient({ url: creds.url, apiKey: creds.apiKey });
+    try {
+        const result = await client.claimAgent(code);
+        printJson(result);
+    }
+    catch (err) {
+        if (err instanceof PaneApiError) {
+            fail(err.message, err.code);
+            return;
+        }
+        throw err;
+    }
+}

package/dist/commands/create.js

@@ -1,13 +1,13 @@
-// `pane session create` — create a session via POST /v1/sessions.
+// `pane surface create` — create a surface via POST /v1/surfaces.
 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",
+    "template",
+    "template-id",
+    "template-type",
     "version",
     "event-schema",
     "input-schema",
@@ -26,9 +26,9 @@ const KNOWN_BOOLS = [];
 //
 // Match strategy: longest prefix wins. Schema paths whose top segment isn't
 // in the table fall back to dotted notation so we degrade gracefully on
-// fields that don't have a single corresponding flag (e.g. `artifact.source`
-// — there's no single --artifact-source flag for the inline form, just
-// --artifact pointing at the whole blob).
+// fields that don't have a single corresponding flag (e.g. `template.source`
+// — there's no single --template-source flag for the inline form, just
+// --template pointing at the whole attachment).
 const SCHEMA_PATH_TO_FLAG = {
     participants: "--participants",
     "participants.humans": "--participants",
@@ -37,12 +37,12 @@ const SCHEMA_PATH_TO_FLAG = {
     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",
+    "template.id": "--template-id",
+    "template.version": "--version",
+    "template.type": "--template-type",
+    "template.source": "--template",
+    "template.event_schema": "--event-schema",
+    "template.input_schema": "--input-schema",
 };
 function schemaPathToFlag(path) {
     const dotted = path.map(String).join(".");
@@ -57,32 +57,32 @@ function schemaPathToFlag(path) {
     }
     return dotted;
 }
-export const createHelp = `pane session create — create a Pane session
+export const createHelp = `pane surface create — create a Pane surface
 
-A session is one use of an artifact. Supply the artifact in ONE of two ways:
+A surface is one use of an template. Supply the template in ONE of two ways:
 
-  Reference form — instance an existing reusable artifact (the cheap path,
+  Reference form — instance an existing reusable template (the cheap path,
   no HTML re-sent):
-    pane session create --artifact-id <id|slug> [--version <n>] [--input-data <v>]
+    pane surface create --template-id <id|slug> [--version <n>] [--input-data <v>]
 
-  Inline form — a one-off artifact, defined on this call:
-    pane session create --artifact <path|inline> [--event-schema <path|json>] [options]
+  Inline form — a one-off template, defined on this call:
+    pane surface create --template <path|inline> [--event-schema <path|json>] [options]
 
-Exactly one of --artifact-id / --artifact must be given.
+Exactly one of --template-id / --template must be given.
 
-Artifact (choose one):
-  --artifact-id <v>   Reference an existing named artifact by id or slug.
-                      Tip: run 'pane artifact search <keywords>' first — a
-                      suitable artifact may already exist; reuse it instead of
+Template (choose one):
+  --template-id <v>   Reference an existing named template by id or slug.
+                      Tip: run 'pane template search <keywords>' first — a
+                      suitable template may already exist; reuse it instead of
                       regenerating HTML.
-  --version <n>       With --artifact-id: pin a specific version. Defaults to
-                      the artifact's latest version.
-  --artifact <v>      Inline HTML artifact. Either a file path / URL, or inline
-                      HTML. Combine with --artifact-type to control reading.
+  --version <n>       With --template-id: pin a specific version. Defaults to
+                      the template's latest version.
+  --template <v>      Inline HTML template. Either a file path / URL, or inline
+                      HTML. Combine with --template-type to control reading.
   --event-schema <v>  Inline-form event schema. A .json file, or inline JSON.
-                      Optional with --artifact. Omit for a view-only artifact
+                      Optional with --template. Omit for a view-only template
                       (a report/dashboard the human only views — no page/agent
-                      events). Ignored with --artifact-id.
+                      events). Ignored with --template-id.
 
                       Shape — an object with an "events" map, keyed by event
                       type. Each entry declares who may emit it and the JSON
@@ -103,30 +103,30 @@ Artifact (choose one):
                       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
+                      Optional with --template, rejected with --template-id
+                      (the schema comes from the pinned template version
+                      there). When present, the surface's --input-data is
+                      validated against it AND any attachment ids declared at a
+                      "format": "pane-attachment-id" site become reachable from the
+                      page via window.pane.downloadBlob. Without it, attachment
                       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
+                      --template-id references a named template, the relay
+                      falls back to Template.name. Inline (--template …) 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
+                      inline JSON), validated by the relay against the template
                       version's input_schema. The page reads it as
                       window.pane.inputData.
-  --artifact-type <t> "html-inline" (default) or "html-ref". With "html-ref"
-                      the --artifact value is treated as a URL. Note: the relay
-                      does not serve "html-ref" artifacts in this release and
-                      will reject the session — use "html-inline".
-  --ttl <seconds>     Session time-to-live in seconds. The relay clamps this
+  --template-type <t> "html-inline" (default) or "html-ref". With "html-ref"
+                      the --template value is treated as a URL. Note: the relay
+                      does not serve "html-ref" templates in this release and
+                      will reject the surface — use "html-inline".
+  --ttl <seconds>     Surface time-to-live in seconds. The relay clamps this
                       to its configured MAX_TTL_SECONDS (defaults: 1 h
                       requested, 24 h max for self-host; hosted may differ).
                       The returned \`expires_at\` is the authoritative value.
@@ -138,19 +138,19 @@ Options:
   -h, --help          Show this help.
 
 Output (stdout, JSON):
-  { session_id, urls, tokens, expires_at }
+  { surface_id, urls, tokens, expires_at }
 
 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.
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface create");
+    const artifactIdVal = args.flags.get("template-id");
+    const artifactVal = args.flags.get("template");
+    // Exactly one of the two template forms must be present.
     if (artifactIdVal !== undefined && artifactVal !== undefined) {
-        fail("pass only one of --artifact-id (reference an existing artifact) or --artifact (inline a one-off)", "invalid_args");
+        fail("pass only one of --template-id (reference an existing template) or --template (inline a one-off)", "invalid_args");
     }
     if (artifactIdVal === undefined && artifactVal === undefined) {
-        fail("missing artifact — pass --artifact-id <id|slug> to reference an existing artifact, or --artifact <path|inline> to inline one", "invalid_args");
+        fail("missing template — pass --template-id <id|slug> to reference an existing template, or --template <path|inline> to inline one", "invalid_args");
     }
     // Assemble a candidate request object, then validate the whole thing with
     // the shared Zod schema (single source of truth, matches what the relay
@@ -158,11 +158,11 @@ export async function runCreate(args) {
     // flag-specific message; the schema then enforces shape and bounds.
     const candidate = {};
     if (artifactIdVal !== undefined) {
-        // Reference form — instance an existing named artifact. --artifact /
-        // --event-schema / --input-schema are not used here: the artifact's
+        // Reference form — instance an existing named template. --template /
+        // --event-schema / --input-schema are not used here: the template'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");
+            fail("--input-schema is incompatible with --template-id — the input schema comes from the pinned template version. Author the schema on the template (`pane template create --input-schema …`) instead.", "invalid_args");
         }
         const ref = { id: artifactIdVal };
         const versionRaw = args.flags.get("version");
@@ -173,40 +173,40 @@ export async function runCreate(args) {
             }
             ref["version"] = version;
         }
-        candidate["artifact"] = ref;
+        candidate["template"] = ref;
     }
     else {
-        // Inline form — the event + input schemas ride inside the `artifact`
-        // object; the relay transparently creates an anonymous artifact behind
+        // Inline form — the event + input schemas ride inside the `template`
+        // object; the relay transparently creates an anonymous template 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.
+        //    through unvalidated AND any attachment ids in it are unreachable from
+        //    the page (the participant attachment-download bridge walks input_data
+        //    against the template version's inputSchema). Pass --input-schema
+        //    when --input-data carries attachment 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");
+        const templateType = (args.flags.get("template-type") ?? "html-inline");
+        if (templateType !== "html-inline" && templateType !== "html-ref") {
+            fail("--template-type must be 'html-inline' or 'html-ref'", "invalid_args");
         }
         // html-ref: the value is a URL, used verbatim. html-inline: file or literal.
         let source;
         try {
             source =
-                artifactType === "html-ref" ? artifactVal : resolveText(artifactVal);
+                templateType === "html-ref" ? artifactVal : resolveText(artifactVal);
         }
         catch (e) {
             fail(e instanceof Error ? e.message : String(e), "invalid_args");
         }
-        // Build the inline artifact object. event_schema / input_schema are
+        // Build the inline template 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
+        // omission is meaningful at the relay (view-only template / no input
         // contract).
         const inlineArtifact = {
-            type: artifactType,
+            type: templateType,
             source,
         };
         if (schemaVal !== undefined) {
@@ -229,11 +229,11 @@ export async function runCreate(args) {
                 fail(e instanceof Error ? e.message : String(e), "invalid_args");
             }
         }
-        candidate["artifact"] = inlineArtifact;
+        candidate["template"] = 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
+    // single source of truth: it enforces "required, with --template-id +
+    // Template.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");

package/dist/commands/delete.js

@@ -1,16 +1,16 @@
-// `pane session delete <id>` — close/delete a session.
+// `pane surface delete <id>` — close/delete a surface.
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
 const KNOWN_FLAGS = [];
 const KNOWN_BOOLS = [];
-export const deleteHelp = `pane session delete — close/delete a session
+export const deleteHelp = `pane surface delete — close/delete a surface
 
 Usage:
-  pane session delete <session-id> [options]
+  pane surface delete <surface-id> [options]
 
-Closes and deletes the session (DELETE /v1/sessions/:id). Idempotent on the
-relay side — deleting an already-closed session still succeeds.
+Closes and deletes the surface (DELETE /v1/surfaces/:id). Idempotent on the
+relay side — deleting an already-closed surface still succeeds.
 
 Options:
   --url <url>         Relay base URL (overrides PANE_URL).
@@ -18,16 +18,16 @@ Options:
   -h, --help          Show this help.
 
 Output (stdout, JSON):
-  { session_id, deleted: true }`;
+  { surface_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");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface delete");
+    const surfaceId = args.positionals[0];
+    if (!surfaceId)
+        fail("missing <surface-id>", "invalid_args");
     const client = makeClient(args);
     try {
-        await client.deleteSession(sessionId);
-        printJson({ session_id: sessionId, deleted: true });
+        await client.deleteSession(surfaceId);
+        printJson({ surface_id: surfaceId, deleted: true });
     }
     catch (e) {
         failFromError(e);

package/dist/commands/feedback.js

@@ -1,7 +1,7 @@
 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 CREATE_FLAGS = ["type", "message", "surface-id"];
 const LIST_FLAGS = ["limit", "before"];
 const NO_BOOLS = [];
 export const feedbackHelp = `pane feedback — submit / list feedback to the relay operator
@@ -25,7 +25,7 @@ Options for 'create':
   --type <bug|feature|note>   Feedback category. Required.
   --message <text|->          Message body. Pass '-' to read from stdin.
                               1..4000 chars after trim.
-  --session-id <id>           Optional session this feedback relates to;
+  --surface-id <id>           Optional surface this feedback relates to;
                               must belong to YOUR agent.
 
 Options for 'list':
@@ -38,7 +38,7 @@ Global:
   -h, --help                  Show this help.
 
 Examples:
-  pane feedback create --type bug --message "watch hangs on empty session"
+  pane feedback create --type bug --message "watch hangs on empty surface"
   echo "long-form note..." | pane feedback create --type note --message -
   pane feedback list --limit 20
 
@@ -55,7 +55,7 @@ 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");
+    const surfaceId = args.flags.get("surface-id");
     if (type === undefined) {
         fail("'pane feedback create' requires --type <bug|feature|note>", "invalid_args");
     }
@@ -83,7 +83,7 @@ async function runFeedbackCreate(args) {
         const res = await client.submitFeedback({
             type: type,
             message,
-            ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(surfaceId !== undefined ? { surfaceId } : {}),
         });
         printJson(res);
     }

package/dist/commands/list.js

@@ -1,23 +1,23 @@
-// `pane session list` — enumerate YOUR agent's sessions.
+// `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 session is intact and listable here. Pair with
-// `pane session participant new` to mint a fresh URL on a session whose
+// 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", "artifact-id"];
+const KNOWN_FLAGS = ["status", "limit", "cursor", "template-id"];
 const KNOWN_BOOLS = [];
-export const listHelp = `pane session list — list YOUR agent's sessions
+export const listHelp = `pane surface list — list YOUR agent's surfaces
 
-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>'.
+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 session list [options]
+  pane surface list [options]
 
 Options:
   --status <s>      open | closed | all. Default: open. The status reported
@@ -25,29 +25,29 @@ Options:
                     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
+  --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 session is still alive):
-  pane session list                                       # find the
-                                                          #   session_id +
+Recovery recipe (lost the URL but the surface is still alive):
+  pane surface list                                       # find the
+                                                          #   surface_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
+  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: [
       {
-        session_id, title, status, artifact_id, artifact_version_id,
-        artifact_version, participants: [...], created_at, expires_at,
+        surface_id, title, status, template_id, template_version_id,
+        template_version, participants: [...], created_at, expires_at,
         has_callback
       },
       ...
@@ -56,7 +56,7 @@ Output (stdout, JSON):
   }`;
 const STATUSES = ["open", "closed", "all"];
 export async function runList(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane session list");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface list");
     const opts = {};
     const status = args.flags.get("status");
     if (status !== undefined) {
@@ -76,9 +76,9 @@ export async function runList(args) {
     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 templateId = args.flags.get("template-id");
+    if (templateId !== undefined && templateId !== "") {
+        opts.template_id = templateId;
     }
     const client = makeClient(args);
     try {