@tarfa/cli 0.1.2 → 0.1.3

package/README.md

@@ -0,0 +1,37 @@
+# @tarfa/cli
+
+The Tarfa agent and command line. Tarfa is a phone app ([tarfa.app](https://tarfa.app)) that shows
+and drives the Claude Code, Codex and shell sessions (tmux workspaces) running on your machines.
+This package runs on each machine (macOS or Linux): it serves that machine's workspaces to your
+phone, end to end encrypted, and gives every workspace the `tarfa` command.
+
+## Install
+
+Needs `tmux` and [mise](https://mise.jdx.dev). Nothing is compiled.
+
+```sh
+mise use -g node@24 npm:@tarfa/cli@latest
+tarfa setup --machine-id <name> --project-roots ~/workspace --tailscale serve --dry-run   # see the plan
+tarfa setup --machine-id <name> --project-roots ~/workspace --tailscale serve --pair      # run it
+```
+
+`tarfa setup` writes `~/.tarfa/agent.env`, the agent key, the service (a systemd user unit or a
+launchd agent) and the Claude Code hooks, publishes the phone port with Tailscale, and prints a
+pairing link and QR code. Open it on the phone, inside the installed app. `tarfa setup --help`
+lists every flag.
+
+## Day to day
+
+```sh
+tarfa pair        # a one-time pairing link for another phone
+tarfa devices     # paired phones; revoke or forget one
+tarfa update      # install the newest release and restart the agent; workspaces survive
+tarfa ls          # this machine's workspaces
+tarfa --help      # every command
+```
+
+## More
+
+The full runbook, including publishing the phone port without Tailscale and running your own copy
+of the app, is [docs/DEPLOY.md](https://github.com/abumalick/tarfa/blob/main/docs/DEPLOY.md).
+Source and issues: [github.com/abumalick/tarfa](https://github.com/abumalick/tarfa).

package/dist/{chunk-XAYVIDCU.js → chunk-X6FKPFHV.js}

@@ -5416,6 +5416,9 @@ var clientMessageSchema = z6.discriminatedUnion("type", [
   z6.object({ type: z6.literal("voiceStart"), workspaceId: z6.string(), id: z6.string() }),
   z6.object({ type: z6.literal("voiceChunk"), id: z6.string(), data: z6.string() }),
   z6.object({ type: z6.literal("voiceEnd"), id: z6.string() }),
+  // The text of Claude's last reply in a workspace, read aloud on the phone. Sent only to an agent
+  // whose authResult names the `lastReply` feature.
+  z6.object({ type: z6.literal("lastReply"), workspaceId: z6.string() }),
   z6.object({ type: z6.literal("resize"), workspaceId: z6.string(), cols: dim, rows: dim }),
   // `remember` is set only when the command came from the Custom field: the agent then adds it
   // to the machine's launcher list. Additive, so an older agent just ignores it.
@@ -5437,6 +5440,7 @@ var clientMessageSchema = z6.discriminatedUnion("type", [
 ]);
 var detachReasonSchema = z6.enum(["opened-elsewhere", "closed", "error"]);
 var PROTOCOL_VERSION = 1;
+var AGENT_FEATURES = { lastReply: "lastReply" };
 var agentMessageSchema = z6.discriminatedUnion("type", [
   // `credential` is what authenticated the session; `enrolled` says the device key is enrolled (written), so the
   // phone forgets its token and pairing secret. Both optional: an older agent sends neither.
@@ -5448,7 +5452,9 @@ var agentMessageSchema = z6.discriminatedUnion("type", [
     credential: z6.enum(["device", "pairing", "token"]).optional().catch(void 0),
     enrolled: z6.boolean().optional().catch(void 0),
     pushed: z6.literal(true).optional().catch(void 0),
-    agent: z6.object({ protocol: z6.number().int(), version: z6.string().optional() }).optional().catch(void 0)
+    // `features` names what this agent answers beyond the protocol, so the PWA offers a control
+    // only to an agent that supports it (a worktree agent shares a release's version number).
+    agent: z6.object({ protocol: z6.number().int(), version: z6.string().optional(), features: z6.array(z6.string()).optional().catch(void 0) }).optional().catch(void 0)
   }),
   // `claudeVoice`: whether this machine can play a Claude voice dictation (see voiceStart).
   // An older agent omits it, and the PWA then treats Claude voice as unavailable there.
@@ -5484,6 +5490,8 @@ var agentMessageSchema = z6.discriminatedUnion("type", [
   z6.object({ type: z6.literal("attached"), workspaceId: z6.string() }),
   z6.object({ type: z6.literal("output"), workspaceId: z6.string(), data: z6.string() }),
   z6.object({ type: z6.literal("fileStored"), workspaceId: z6.string(), path: z6.string() }),
+  // `text` is null when the agent holds no reply for that workspace (none since it started, or not Claude).
+  z6.object({ type: z6.literal("lastReply"), workspaceId: z6.string(), text: z6.string().nullable() }),
   z6.object({ type: z6.literal("voiceDone"), id: z6.string(), ok: z6.boolean(), error: z6.string().optional() }),
   z6.object({ type: z6.literal("detached"), workspaceId: z6.string(), reason: detachReasonSchema }),
   z6.object({ type: z6.literal("closed"), workspaceId: z6.string() }),
@@ -6127,6 +6135,7 @@ export {
   pdfMediaType,
   audioMediaType,
   PROTOCOL_VERSION,
+  AGENT_FEATURES,
   parseClientMessage,
   parseBrowserClientMessage,
   parseBrowserAgentMessage,

package/dist/cli.js

@@ -63,7 +63,7 @@ import {
   unitRunsLauncher,
   withEnrolmentMode,
   withLegacyEnv
-} from "./chunk-XAYVIDCU.js";
+} from "./chunk-X6FKPFHV.js";
 
 // src/cli.ts
 import { randomBytes } from "node:crypto";
@@ -1197,7 +1197,10 @@ async function cliState(home, env) {
 var CODEX_NEXT_STEP = "open Codex and trust the Tarfa hooks in /hooks; repeat after any hook change";
 async function run3(argv, rawEnv, home, io = {}) {
   const env = withLegacyEnv(rawEnv);
+  if (argv[0] === void 0 || argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") return HELP;
   if (argv[0] === "--version" || argv[0] === "-v") return packageVersion();
+  if (argv[0] === "serve") throw new UsageError("usage: tarfa serve   (no options: runs the agent in the foreground, as the service does)");
+  if (!COMMANDS.has(argv[0])) throw new UsageError(`unknown command: ${argv[0]} (run \`tarfa --help\`)`);
   if (argv[0] === "setup") return setup(argv.slice(1), env, home, io);
   if (argv[0] === "apply") return apply2(argv.slice(1), env, home, io);
   if (argv[0] === "update") return update(argv.slice(1), env, home, io);
@@ -1272,9 +1275,54 @@ async function run3(argv, rawEnv, home, io = {}) {
     case "devices":
       return devices(new FileDeviceStore(config.devicesPath), rest);
     default:
-      throw new Error(`unknown command: ${command ?? "(none)"}`);
+      throw new UsageError(`unknown command: ${command} (run \`tarfa --help\`)`);
   }
 }
+var HELP = `usage: tarfa <command> [options]   (\`tarfa setup --help\`, \`tarfa apply --help\` and \`tarfa update --help\` list their flags)
+
+Set up this machine:
+  setup          write agent.env, the agent key, the service and the hooks, then check the phone port
+  pair           print a one-time pairing link and QR code for a phone
+  devices        list, revoke or forget paired phones; switch enrolment on, off or closed
+  update         install the newest @tarfa/cli and apply it (package installs)
+  apply          rewrite the launcher and service if they changed, reinstall the hooks, restart
+  install-hooks  install the Claude Code and Codex hooks that report each workspace's status
+  serve          run the agent in the foreground (what the service runs)
+
+Workspaces on this machine:
+  ls             list workspaces and their state
+  spawn          open a workspace on a project with a brief on stdin (--child to orchestrate it)
+  peek           print the end of a workspace's screen
+  wait           wait until one of the workspaces stops working
+  send           send a message to another workspace
+  unpark         reopen parked workspaces
+  rename         rename a workspace (without an id: this one)
+  close          close workspaces
+  list, create, recent, browse   the agent's own views, as JSON
+
+  --version      print the version`;
+var COMMANDS = /* @__PURE__ */ new Set([
+  "setup",
+  "apply",
+  "update",
+  "pair",
+  "connect",
+  "relay-key",
+  "devices",
+  "install-hooks",
+  "ls",
+  "spawn",
+  "peek",
+  "unpark",
+  "rename",
+  "send",
+  "close",
+  "wait",
+  "list",
+  "create",
+  "recent",
+  "browse"
+]);
 var LS_USAGE = `usage: tarfa ls [--json] [--mine] [--parent <workspace id>] [--role ${WORKSPACE_ROLES.join("|")}] [--path <project dir>]`;
 var SPAWN_USAGE = "usage: tarfa spawn [--title <title>] [--child] [--model <model>] [--cli claude|codex|pi] <projectPath>   (brief on stdin)";
 var SPAWN_CLIS = ["claude", "codex", "pi"];
@@ -1981,7 +2029,7 @@ function formatRoster(roster) {
 }
 if (isEntrypoint(import.meta.url, process.argv[1])) {
   const argv = process.argv.slice(2);
-  const program = argv[0] === "serve" ? import("./serve.js").then((agent) => agent.main()) : run3(argv, process.env, homedir()).then((out) => {
+  const program = argv[0] === "serve" && argv.length === 1 ? import("./serve.js").then((agent) => agent.main()) : run3(argv, process.env, homedir()).then((out) => {
     process.stdout.write(`${out}
 `);
   });

package/dist/serve.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  AGENT_FEATURES,
   CodexAppServer,
   CodexAppServerDown,
   DEVICE_REFUSED,
@@ -74,7 +75,7 @@ import {
   systemPathResolver,
   withLegacyEnv,
   writeFileAtomic
-} from "./chunk-XAYVIDCU.js";
+} from "./chunk-X6FKPFHV.js";
 
 // src/serve.ts
 import { homedir as homedir2 } from "node:os";
@@ -1332,7 +1333,7 @@ var NoiseClientConnection = class {
       return;
     }
     if (message.type === "authResult" && message.ok) {
-      const accepted = { ...message, agent: { protocol: PROTOCOL_VERSION, ...this.options.agentVersion ? { version: this.options.agentVersion } : {} } };
+      const accepted = { ...message, agent: { protocol: PROTOCOL_VERSION, ...this.options.agentVersion ? { version: this.options.agentVersion } : {}, features: [AGENT_FEATURES.lastReply] } };
       message = accepted;
       if (!this.awaitingPhone) this.cancelDeadline();
       this.session.raiseCap(MAX_MESSAGE_BYTES);
@@ -2550,6 +2551,10 @@ var ConnectionHandler = class {
         voice.session?.end();
         return;
       }
+      case "lastReply": {
+        this.conn.send({ type: "lastReply", workspaceId: message.workspaceId, text: this.deps.lastReplies?.get(message.workspaceId) ?? null });
+        return;
+      }
       case "ping": {
         this.conn.send({ type: "pong" });
         return;
@@ -2941,6 +2946,25 @@ function applyHookEvent(deps, input) {
   return decision.status ? { workspaceId: input.sessionName, status: decision.status } : null;
 }
 
+// src/application/last-replies.ts
+var MAX_REPLY_CHARS = 64e3;
+var TURN_ENDS = /* @__PURE__ */ new Set(["Stop", "StopFailure"]);
+var LastReplies = class {
+  replies = /* @__PURE__ */ new Map();
+  record(id, event, payload) {
+    if (!TURN_ENDS.has(event) || typeof payload !== "object" || payload === null) return;
+    const text = payload.last_assistant_message;
+    if (typeof text !== "string" || text.trim() === "") return;
+    this.replies.set(id, text.slice(0, MAX_REPLY_CHARS));
+  }
+  get(id) {
+    return this.replies.get(id) ?? null;
+  }
+  forget(id) {
+    this.replies.delete(id);
+  }
+};
+
 // src/application/send-message.ts
 import { randomBytes } from "node:crypto";
 function headerSafe(name) {
@@ -3148,6 +3172,7 @@ var WsServer = class {
   oscTurnEnded = /* @__PURE__ */ new Set();
   // Hooks posted by Codex thread, applied one after another in arrival order.
   threadHooks = Promise.resolve();
+  lastReplies = new LastReplies();
   // The panes showing a question or menu at the last poll.
   asking = /* @__PURE__ */ new Set();
   // The last OSC 7501 record seen per pane, so only a change is applied (applyProgramStatus).
@@ -3178,6 +3203,7 @@ var WsServer = class {
     this.sentDuringTool.delete(id);
     this.oscTurnEnded.delete(id);
     this.programSeen.delete(id);
+    this.lastReplies.forget(id);
   }
   // pollTitles logs and drops a workspace it saw go, but it runs only while a phone is connected
   // and never follows a hidden folder. This drops the rest, so an exited workspace's number is
@@ -3282,7 +3308,8 @@ var WsServer = class {
       forgetWorkspace: (id, closing) => this.forgetWorkspace(id, closing),
       dropWorkspaceState: (id) => this.dropWorkspaceState(id),
       broadcastClosed: (id) => this.broadcastClosed(id),
-      messagedLast: this.messagedLast
+      messagedLast: this.messagedLast,
+      lastReplies: this.lastReplies
     });
     this.handlers.add(handler);
     conn.onClose(() => {
@@ -3306,9 +3333,9 @@ var WsServer = class {
       res.writeHead(401).end();
       return;
     }
-    let body = "";
     let bytes = 0;
     let refused = false;
+    const chunks = [];
     req.on("data", (chunk) => {
       if (refused) return;
       bytes += chunk.length;
@@ -3318,10 +3345,11 @@ var WsServer = class {
         req.destroy();
         return;
       }
-      body += chunk;
+      chunks.push(chunk);
     });
     req.on("end", () => {
       if (refused) return;
+      const body = Buffer.concat(chunks).toString("utf8");
       if (route === "/unpark") {
         void this.handleUnpark(body, res);
         return;
@@ -3374,6 +3402,7 @@ var WsServer = class {
   applyHook(sessionName, event, claude, agent) {
     const statusBefore = this.deps.status.get(sessionName);
     const messagedBefore = this.messagedLast.has(sessionName);
+    this.lastReplies.record(sessionName, event, claude);
     applyHookEvent(
       {
         store: this.deps.status,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tarfa/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Tarfa agent and CLI: serves your Claude Code terminal sessions (tmux workspaces) to the Tarfa phone app.",
   "repository": {
     "type": "git",