clawborrator-cli 0.0.49 → 0.0.51

package/README.md

@@ -77,6 +77,8 @@ claw session attach 6d04…uuid
 claw session info @backend                     # one-shot detail dump
 claw session events @backend --kind chat       # transcript history (--limit / --after / --before)
 claw session messages @backend                 # operator-to-operator chat (op-messages)
+claw session files @backend                    # list file attachments on a session
+claw session file-rm 42                        # delete a file by id (refcount-sweeps blob if last ref)
 
 claw session prompt @backend "deploy to staging"   # fire-and-forget
 claw session prompt @backend "@MRIIOT/rust-expert what is a lifetime?"  # public-agent dispatch

package/dist-bundled/claw.cjs

@@ -67830,7 +67830,7 @@ var sessionAttach = new Command("attach").description("open a TUI on a session \
   const limitArg = String(opts.limit ?? "50").toLowerCase();
   const historyLimit = limitArg === "all" ? 5e3 : limitArg === "0" ? 0 : Math.max(0, parseInt(limitArg, 10) || 0);
   if (historyLimit > 0) {
-    const kindsParam = opts.opMessages === false ? "&kinds=event" : "";
+    const kindsParam = opts.opMessages === false ? "&kinds=event,file" : "";
     try {
       const tl = await api.get(`/api/v1/sessions/${encodeURIComponent(sessionId)}/timeline?limit=${historyLimit}${kindsParam}`);
       if (tl.items.length > 0) {
@@ -67843,8 +67843,11 @@ var sessionAttach = new Command("attach").description("open a TUI on a session \
               /* fromBacklog */
               true
             );
-          } else {
+          } else if (item.kind === "op-message") {
             console.log(`${DIM2}[${shortTs(item.ts)}]${RESET2} ${GREEN}@${item.authorLogin}${RESET2}  ${item.text}`);
+          } else if (item.kind === "file") {
+            const verb = item.action === "uploaded" ? `${GREEN}\u{1F4CE} uploaded${RESET2}` : `${RED}\u2717 deleted${RESET2}`;
+            console.log(`${DIM2}[${shortTs(item.ts)}]${RESET2} ${BLUE}@${item.file.uploaderLogin}${RESET2}  ${verb} ${BOLD2}${item.file.filename}${RESET2} ${DIM2}(${fmtBytes(item.file.size)} \xB7 fileId=${item.file.id})${RESET2}`);
           }
         }
         console.log(`${DIM2}\u2500\u2500\u2500 live \u2500\u2500\u2500${RESET2}`);
@@ -68124,6 +68127,12 @@ function printInbound(msg, myLogin) {
       if (!msg.connected) stopWorking();
       break;
     }
+    case "file_event": {
+      const verb = msg.action === "uploaded" ? `${GREEN}\u{1F4CE} uploaded${RESET2}` : `${RED}\u2717 deleted${RESET2}`;
+      const f = msg.file;
+      say(`${DIM2}[${ts()}]${RESET2} ${BLUE}@${f.uploaderLogin}${RESET2}  ${verb} ${BOLD2}${f.filename}${RESET2} ${DIM2}(${fmtBytes(f.size)} \xB7 fileId=${f.id})${RESET2}`);
+      break;
+    }
     case "ack":
       break;
     case "error":
@@ -68135,6 +68144,12 @@ function shortTs(iso) {
   const d = new Date(iso);
   return Number.isFinite(d.getTime()) ? d.toLocaleTimeString() : iso.slice(11, 19);
 }
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 ** 3) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  return `${(n / 1024 ** 3).toFixed(2)} GB`;
+}
 function previewPayload(p) {
   const text = p?.text ?? p?.preview ?? p?.outputPreview ?? "";
   if (typeof text === "string" && text.length > 0) {
@@ -68543,6 +68558,51 @@ var sessionSharesCmd = new Command("shares").description("list users granted acc
     console.log(`  @${s.login.padEnd(20)} ${s.role.padEnd(9)} since ${s.createdAt}`);
   }
 });
+function fmtBytes2(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 ** 3) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  return `${(n / 1024 ** 3).toFixed(2)} GB`;
+}
+var sessionFiles = new Command("files").description("list a session's file attachments. Use --all to include soft-deleted rows.").argument("<ref>", "session UUID or @routingName").option("--all", "include soft-deleted rows").option("--json", "emit one JSON object per line").action(async (ref, opts) => {
+  const id = await resolveSessionId(ref);
+  const data = await api.get(`/api/v1/sessions/${encodeURIComponent(id)}/files`);
+  const live = opts.all ? data.items : data.items.filter((f) => !f.deletedAt);
+  if (live.length === 0) {
+    if (!opts.json) console.log("no files");
+    return;
+  }
+  for (const f of live) {
+    if (opts.json) {
+      console.log(JSON.stringify(f));
+      continue;
+    }
+    const ts2 = f.uploadedAt.slice(0, 19).replace("T", " ");
+    const flag = f.deletedAt ? " [deleted]" : "";
+    const sha = f.sha256.slice(0, 12);
+    console.log(`#${String(f.id).padStart(5)} ${ts2}  ${fmtBytes2(f.size).padStart(8)}  @${f.uploaderLogin.padEnd(20)} ${f.scope.padEnd(11)} sha=${sha}\u2026  ${f.filename}${flag}`);
+  }
+});
+var sessionFileRm = new Command("file-rm").description("delete a file by id. Soft-deletes the row; on-disk blob is swept once no live row references its sha. Prompter+ on the file's session.").argument("<fileId>", "file id (from `claw session files` output, the # column)").action(async (fileId) => {
+  const id = Number(fileId);
+  if (!Number.isFinite(id) || id <= 0) {
+    console.error("error: fileId must be a positive integer");
+    process.exit(2);
+  }
+  const r = await api.delete(
+    `/api/v1/files/${id}`
+  );
+  if (r.alreadyDeleted) {
+    console.log(`(file #${id} was already deleted)`);
+    return;
+  }
+  const refs = r.refsRemaining ?? 0;
+  if (r.blobDeleted) {
+    console.log(`\u2717 deleted file #${id} \u2014 blob swept (${fmtBytes2(r.freedBytes ?? 0)} freed; was the last reference)`);
+  } else {
+    console.log(`\u2717 deleted file #${id} \u2014 blob retained (${refs} other live reference${refs === 1 ? "" : "s"})`);
+  }
+});
 var sessionUnshareCmd = new Command("unshare").description("revoke a user's share access to a session. Owner-only.").argument("<ref>", "session UUID or @routingName").argument("<login>", "GitHub login (with or without leading @)").action(async (ref, login) => {
   const id = await resolveSessionId(ref);
   const cleanLogin = login.replace(/^@/, "");
@@ -68555,7 +68615,7 @@ var sessionUnshareCmd = new Command("unshare").description("revoke a user's shar
     console.log(`\u2717 revoked @${out.login}'s access to ${out.sessionId.slice(0, 8)}\u2026`);
   }
 });
-var sessionCmd = new Command("session").description("manage Claude Code sessions registered with this hub").addCommand(sessionList).addCommand(sessionInfo).addCommand(sessionAttach).addCommand(sessionEvents).addCommand(sessionMessages).addCommand(sessionArchive).addCommand(sessionPrune).addCommand(sessionPrompt).addCommand(sessionDelete).addCommand(sessionShareCmd).addCommand(sessionSharesCmd).addCommand(sessionUnshareCmd);
+var sessionCmd = new Command("session").description("manage Claude Code sessions registered with this hub").addCommand(sessionList).addCommand(sessionInfo).addCommand(sessionAttach).addCommand(sessionEvents).addCommand(sessionMessages).addCommand(sessionArchive).addCommand(sessionPrune).addCommand(sessionPrompt).addCommand(sessionDelete).addCommand(sessionShareCmd).addCommand(sessionSharesCmd).addCommand(sessionUnshareCmd).addCommand(sessionFiles).addCommand(sessionFileRm);
 
 // src/commands/token.ts
 var import_node_fs2 = require("node:fs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawborrator-cli",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "type": "module",
   "description": "claw — command-line client for clawborrator. Attach to remote Claude Code sessions, send prompts, resolve permission gates, route across sessions, manage public agents and webhooks. Auth via GitHub OAuth + PKCE.",
   "license": "MIT",
@@ -40,8 +40,7 @@
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=cjs --target=node20 --outfile=dist-bundled/claw.cjs --banner:js=\"#!/usr/bin/env node\"",
     "dev": "tsx src/index.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run bundle && node ./scripts/inject-readme.mjs",
-    "postpack": "node ./scripts/inject-readme.mjs --restore"
+    "prepublishOnly": "npm run bundle"
   },
   "devDependencies": {
     "@clawborrator/shared": "*",
@@ -55,7 +54,5 @@
     "tsx": "^4.19.1",
     "typescript": "^5.6.2",
     "ws": "^8.18.0"
-  },
-  "readme": "# clawborrator-cli\n\n`claw` — command-line client for [clawborrator](https://next.clawborrator.com),\na control plane for Claude Code sessions.\n\nWhat you can do with it from a terminal:\n\n- Attach to any CC session you can see (yours or shared with you), watch\n  prompts and tool calls stream in, type your own prompts, approve or\n  deny permission gates, chat with other operators on the side.\n- Send one-shot prompts to a session non-interactively (CI-friendly).\n- Mint channel tokens (`ck_live_…`) and drop a ready-to-use `.mcp.json`\n  block so a CC running on this machine appears on the hub.\n- Route prompts across sessions (`claw route @backend \"what time is it\"`)\n  with reply tracking.\n- Share sessions with teammates at viewer / prompter / approver role.\n- Publish a session as a public expert agent (`@<owner>/<slug>`,\n  callable from any prompt).\n- Subscribe to webhooks for chat / permission / file / agent events.\n\nThe hub is at <https://next.clawborrator.com> by default — point at a\nself-hosted instance with `claw login --hub <url>` (persists per\nmachine).\n\n---\n\n## Install\n\n```bash\n# one-off (no global install)\nnpx clawborrator-cli@latest login\n\n# or pin globally\nnpm install -g clawborrator-cli\nclaw login\n```\n\nRequires Node 20+.\n\n---\n\n## First-time setup\n\n```bash\n# 1. Authenticate (opens a browser → GitHub → back to a localhost\n#    callback that hands you a 30-day session token).\nclaw login\n\n# 2. Confirm.\nclaw whoami\n# logged in as @your-github-login\n\n# 3. (optional) Mint a channel token + drop the .mcp.json block so\n#    your local Claude Code registers a session against the hub.\nclaw token mint --name \"$(hostname)\" --mcp-snippet --out .mcp.json\n# → now restart `claude code` in this directory and it'll appear in\n#   `claw session list`.\n```\n\nThe session token is stored at `~/.clawborrator/config.json` (mode\n0600). To talk to a different hub, pass `--hub <url>` once on login;\nthe URL persists.\n\n---\n\n## Cheatsheet\n\n### Sessions\n\n```bash\nclaw session list                              # your sessions + ones shared with you\nclaw session ls --connected                    # only currently-online ones\n\nclaw session attach @backend                   # interactive TUI: live tail + send prompts + approve gates\nclaw session attach 6d04…uuid\n\nclaw session info @backend                     # one-shot detail dump\nclaw session events @backend --kind chat       # transcript history (--limit / --after / --before)\nclaw session messages @backend                 # operator-to-operator chat (op-messages)\n\nclaw session prompt @backend \"deploy to staging\"   # fire-and-forget\nclaw session prompt @backend \"@MRIIOT/rust-expert what is a lifetime?\"  # public-agent dispatch\nclaw session prompt @backend \"@alice/frontend ...\"  # cross-account peer (if shared)\n\nclaw session share @backend alice --role prompter  # grant access (viewer | prompter | approver)\nclaw session shares @backend                       # list current shares\nclaw session unshare @backend alice                # revoke\n\nclaw session archive @backend                  # soft-delete (auto-resurrects on next CC start in the same project)\nclaw session prune --dry-run                   # find duplicate-routing-name rows\nclaw session delete @backend --hard            # permanent (cascades events / op-messages / shares)\n```\n\n`<ref>` in any subcommand accepts the session UUID, the `@routingName`\nfor sessions you own, or `@owner/routingName` for sessions shared with\nyou.\n\n### Cross-session routing\n\n```bash\nclaw peers                                     # sessions reachable for routing (yours + shared)\n\nclaw route @backend \"what time is it\"          # ask-mode: blocks up to 60s for the reply\nclaw route @alice/frontend \"...\" --tell        # tell-mode: fire-and-forget\n\nclaw probe \"do you have a User model\" --peers @backend,@frontend   # parallel fan-out\nclaw probe \"...\"                               # implicit: every online reachable peer\n```\n\nRouting requires prompter+ on the target. Peer's CC must be online\nand not mid-turn for someone else (driver-claim contention returns a\n409 and you retry in a moment).\n\n### Channel tokens\n\nFor your local Claude Code to register a session against the hub,\nclawborrator-mcp needs a `ck_live_…` token in the project's\n`.mcp.json`:\n\n```bash\nclaw token mint --name \"alice-laptop\" --mcp-snippet --out .mcp.json\n# → writes a ready-to-use .mcp.json\n# → prints the plaintext token to stderr ONCE — copy it if you didn't redirect\n\nclaw token list                                # list active tokens\nclaw token revoke <id>                         # revoke (cascade-archives sessions registered with it)\n```\n\n> **Windows note:** prefer `--out <path>` over PowerShell `>`\n> redirection. PowerShell's default redirection writes UTF-16 LE with\n> BOM, which CC rejects when parsing `.mcp.json`. `--out` writes UTF-8\n> without BOM.\n\n### Public expert agents\n\nA session you own can be published as `@<your-login>/<slug>`,\ncallable by any signed-in user:\n\n```bash\nclaw agents publish --session <uuid> --name \"rust expert\" --tagline \"answers Rust questions\" --published\n# → @MRIIOT/rust-expert is live; rate-limited per-user, capped at\n#   1000 queries/day by default.\n\nclaw agents list                               # discover everyone's published agents\nclaw agents list --mine                        # your own agents (any status, includes draft)\n\nclaw agents update @MRIIOT/rust-expert --budget 5000\nclaw agents update @MRIIOT/rust-expert --composable        # opt out of isolation (cross-session routing tools enabled while answering)\nclaw agents update @MRIIOT/rust-expert --status draft      # take it offline without unpublishing\n\nclaw agents inbound @MRIIOT/rust-expert --days 7  # who's been calling: ok / denied / latency / top askers / recent\n\nclaw agents unpublish @MRIIOT/rust-expert\n```\n\nDefault mode is `--isolated` (recommended): the agent's CC cannot\nuse cross-session routing tools while answering a public dispatch.\nUse `--composable` only for orchestrator-style agents that need to\nreach other peers.\n\nAnyone can also call your agent over the\n[A2A protocol](https://a2a-protocol.org) at\n`/api/a2a/v1/agents/<owner>/<slug>` — see the\n[A2A bridge reference](https://next.clawborrator.com/demos/a2a-docs/).\n\n### Webhooks\n\nSubscribe to events for sessions you can see:\n\n```bash\nclaw webhook add --url https://your-server/hook \\\n  --events 'chat.event,permission.requested,permission.resolved'\n\nclaw webhook list\nclaw webhook test <id>                         # queue a synthetic webhook.test delivery\nclaw webhook rm <id>\n```\n\nThe signing secret is shown ONCE on `add`. HMAC-SHA256 in the\n`X-Clawborrator-Signature: t=…,v1=…` header (Stripe-style).\nVerification recipes for Node + Python and the full event catalog\nlive at the\n[webhooks reference](https://next.clawborrator.com/demos/webhooks/).\n\n### Auth\n\n```bash\nclaw login                                     # browser-based GitHub OAuth (PKCE)\nclaw login --hub https://your-hub.example.com  # point at a different hub; persists\nclaw whoami\nclaw logout                                    # revokes the session token + clears local config\n```\n\n---\n\n## `claw session attach` — the TUI\n\nThis is the killer feature. Three or more humans attached to the\nsame Claude Code session, seeing each other's prompts in real time,\nracing on tool-permission approvals, talking to each other in a side\nchannel that doesn't pollute Claude's context.\n\n```\n$ claw session attach @backend\n\n  attached to @backend (cwd /home/alice/repo, role: prompter, alice (you), bob)\n  ───────────────────────────────────────────────────────────────────────────\n  [10:42] @bob ›       deploy to staging\n  [10:42] claude       I'll start by running the test suite first…\n  [10:42] → Bash       npm run test\n                       ↳ permission gate: /y to approve, /n to deny  (alice can decide)\n  /y\n  [10:42] ✓ Bash       (allowed by @alice)\n  [10:43] ✓ Bash       (npm run test exited 0)\n  [10:43] claude       Tests pass. Running deploy now…\n  ───────────────────────────────────────────────────────────────────────────\n  > _                                                          [/help for commands]\n```\n\nIn-TUI commands:\n\n| | |\n|---|---|\n| `<text>` | send a prompt to the attached session |\n| `@peer <text>` | route to a peer session and wait for the reply |\n| `/op <text>` | operator-to-operator chat (visible to peers, not to Claude) |\n| `/y` `/n` | approve / deny the most recent permission gate |\n| `/peers` | show currently-reachable peer sessions |\n| `/help` | full list |\n| `Ctrl-C` | detach (the session keeps running) |\n\n---\n\n## Configuration\n\n| Path | Contents |\n|---|---|\n| `~/.clawborrator/config.json` | hub URL + session token (mode 0600) |\n| `$CLAWBORRATOR_HUB` | env override for hub URL (one-shot, doesn't persist) |\n\n---\n\n## Troubleshooting\n\n**\"can't connect to localhost:8787\" after login.** You're on a\npre-0.0.45 install pointed at the dev default. Upgrade to\n`@latest` and re-run `claw login`; the new default points at\n`https://next.clawborrator.com`. Or pass `--hub` explicitly.\n\n**OAuth callback hangs / \"state is required\" in the browser.** On\nWindows the callback URL contains `&` which CMD's `start` builtin\ntreats as a separator. Upgrade to a recent version of the CLI\n(0.0.41+); we now quote the URL through `windowsVerbatimArguments`.\n\n**`.mcp.json` written via `>` doesn't work.** PowerShell encodes\nredirected output as UTF-16 LE with BOM. CC's MCP parser doesn't\nhandle the BOM. Use `claw token mint … --mcp-snippet --out .mcp.json`\ninstead — that writes UTF-8 without BOM directly to disk.\n\n**`claw session attach` shows \"auth failed\".** Your session token\nexpired (30-day hard cap, no refresh). Run `claw login` again and\nre-attach.\n\n**Cross-session routing returns \"is offline\" or \"is processing a\nturn for another user\".** The peer's CC needs to be online (channel\nWS open) and not mid-turn for someone else. Wait or pick a different\npeer.\n\n---\n\n## Where to look next\n\n- **Hub home & demos:** <https://next.clawborrator.com/>\n- **REST API (OpenAPI):** <https://next.clawborrator.com/docs>\n- **WebSocket (AsyncAPI):** <https://next.clawborrator.com/ws-docs>\n- **Webhook reference:** <https://next.clawborrator.com/demos/webhooks/>\n- **A2A bridge reference:** <https://next.clawborrator.com/demos/a2a-docs/>\n- **Source / issues / contributing:** <https://github.com/clawborrator/hub_v1>\n\nThe CLI source is in `cli/` of the same repo; it's a thin shell over\nthe REST + WS surface, so anything `claw` does you can do directly\nfrom any HTTP client.\n\n---\n\n## License\n\nMIT.\n",
-  "readmeFilename": "README.md"
+  }
 }