@paigy/harness 0.3.0 → 0.3.1

package/dist/cli.js

@@ -23175,6 +23175,79 @@ function detectAll(deps = {}) {
   return CATALOG.map((entry) => detect(entry, deps));
 }
 
+// src/cli-args.ts
+var USAGE = "usage: paigy-harness setup | pair | host [--grant DIR]\u2026 | service | enable-tools [--scope user|project] | hatch NAME [--voice KEY] [--slot SLOT] | handoff | [--harness claude|codex|agy] [--mode bypass|ask] [--cwd DIR] [--identity NAME] [--grace SECONDS] [--doctor] PROMPT\u2026";
+function parseArgs(argv) {
+  const args = { harness: "claude", mode: "bypass", cwd: process.cwd(), doctor: false, help: false, host: false, pair: false, service: false, setup: false, enableTools: false, scope: "user", grant: [], hatch: null, voice: null, slot: null, identity: null, graceSeconds: 90, prompt: "", handoff: false };
+  const words = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+    if (arg === "--harness") {
+      const v = next();
+      if (v !== "claude" && v !== "codex" && v !== "agy") return { error: `--harness must be claude, codex, or agy, got ${v ?? "nothing"}` };
+      args.harness = v;
+    } else if (arg === "--mode") {
+      const v = next();
+      if (v !== "bypass" && v !== "ask") return { error: `--mode must be bypass or ask, got ${v ?? "nothing"}` };
+      args.mode = v;
+    } else if (arg === "--cwd") {
+      const v = next();
+      if (!v) return { error: "--cwd needs a directory" };
+      args.cwd = v;
+    } else if (arg === "--doctor") {
+      args.doctor = true;
+    } else if (arg === "-h" || arg === "--help" || arg === "help") {
+      args.help = true;
+    } else if (arg === "--scope") {
+      const v = next();
+      if (v !== "user" && v !== "project") return { error: `--scope must be user or project, got ${v ?? "nothing"}` };
+      args.scope = v;
+    } else if (arg === "--grace") {
+      const v = Number(next());
+      if (!Number.isFinite(v) || v < 0) return { error: "--grace needs seconds (0 = straight to phone)" };
+      args.graceSeconds = v;
+    } else if (arg === "host") {
+      args.host = true;
+    } else if (arg === "pair") {
+      args.pair = true;
+    } else if (arg === "setup") {
+      args.setup = true;
+    } else if (arg === "service") {
+      args.service = true;
+    } else if (arg === "--grant") {
+      const v = next();
+      if (!v) return { error: "--grant needs a folder to allow" };
+      args.grant.push(v);
+    } else if (arg === "handoff") {
+      args.handoff = true;
+    } else if (arg === "enable-tools") {
+      args.enableTools = true;
+    } else if (arg === "hatch") {
+      const v = next();
+      if (!v) return { error: 'hatch needs a name: paigy-harness hatch "Voice bug hunter"' };
+      args.hatch = v;
+    } else if (arg === "--voice") {
+      args.voice = next() ?? null;
+    } else if (arg === "--slot") {
+      args.slot = next() ?? null;
+    } else if (arg === "--identity") {
+      const v = next();
+      if (!v) return { error: "--identity needs a hatched agent's name" };
+      args.identity = v;
+    } else if (arg?.startsWith("--")) {
+      return { error: `unknown flag ${arg}` };
+    } else if (arg) {
+      words.push(arg);
+    }
+  }
+  args.prompt = words.join(" ");
+  if (args.help) return args;
+  if (!args.doctor && !args.handoff && !args.hatch && !args.host && !args.pair && !args.service && !args.setup && !args.enableTools && !args.prompt) return { error: "a prompt is required (or setup / --doctor / pair / host / service / enable-tools / hatch NAME / handoff)" };
+  return args;
+}
+var ENABLE_TOOLS_COMMAND = "npx -y -p @paigy/mcp@latest paigy-enable-tools";
+
 // ../../packages/sdk/dist/index.js
 import { createRequire as __sdkCreateRequire } from "module";
 import { randomUUID } from "crypto";
@@ -29694,7 +29767,7 @@ var NotifyRequestSchema = external_exports.object({
   if (r.ask !== void 0) {
     for (const f of ["context", "select", "points"]) {
       if (r[f] !== void 0)
-        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives it (use \`needs\` for multi-part asks)` });
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives the answer shape from your prose. Drop ${f} and say it in \`ask\` instead ("should I\u2026" for approve/deny, "which of these\u2026" for a pick), passing \`options\` when you're offering concrete alternatives.` });
     }
     return;
   }
@@ -29967,7 +30040,13 @@ var NotifyPlanUnitSchema = external_exports.object({
   proposal: external_exports.object({
     select: SelectShapeSchema,
     options: external_exports.array(external_exports.object({ label: external_exports.string().min(1) })).optional()
-  }).optional()
+  }).optional(),
+  /** What the broker READ this unit as wanting from the human (#952 layer 2): a `decision`
+   *  between alternatives, an `approval` the agent is blocked on, or `knowledge` it just
+   *  needs to know. Reported so the agent can correct a misread the same way it ratifies a
+   *  shape — the read RAISES (a decision always asks) and never silences a question the
+   *  agent declared (#731, #923). */
+  wants: external_exports.enum(["decision", "approval", "knowledge"]).optional()
 });
 var NotifyPlanSchema = external_exports.object({
   units: external_exports.array(NotifyPlanUnitSchema),
@@ -30214,6 +30293,15 @@ var HistoryItemSchema = external_exports.object({
   /** When you answered the agent's notification (agent→user only). */
   humanAckedAt: external_exports.string().nullable()
 });
+var ACTIVITY_LINES = 2;
+var ACTIVITY_LINE_MAX = 80;
+var AgentActivitySchema = external_exports.object({
+  /** Oldest first, so the newest line is last — the one that replaces in place. */
+  lines: external_exports.array(external_exports.string().max(ACTIVITY_LINE_MAX)).max(ACTIVITY_LINES),
+  /** When the harness observed this tail. Its own timestamp, not the heartbeat's: a beat
+   *  that carries an UNCHANGED tail must not make a stalled agent look like it just moved. */
+  at: external_exports.string().datetime()
+});
 var ConnectionSummarySchema = external_exports.object({
   /** The connection = the agent's token id (used to address a request). */
   id: external_exports.string(),
@@ -30247,6 +30335,11 @@ var ConnectionSummarySchema = external_exports.object({
     harnesses: external_exports.array(external_exports.object({ name: external_exports.string(), label: external_exports.string(), status: external_exports.string() })).optional(),
     workspaces: external_exports.array(external_exports.string()).optional()
   }).optional(),
+  /** The tail of this agent's working log, when a harness is driving it — the agent page's
+   *  live strip. Absent for anything the desktop harness isn't running (a hatched identity
+   *  used straight from a terminal emits no work events; the page says so rather than
+   *  drawing an empty box). */
+  activity: AgentActivitySchema.optional(),
   /** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: external_exports.boolean()
@@ -31081,10 +31174,14 @@ async function claimSessions(opts = {}) {
   return (await res.json()).sessions;
 }
 async function heartbeat(runtime, opts = {}) {
+  const body = {
+    ...runtime !== void 0 ? { runtime } : {},
+    ...opts.activity !== void 0 ? { activity: opts.activity } : {}
+  };
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/presence`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${authToken(opts.token)}` },
-    ...runtime !== void 0 ? { body: JSON.stringify({ runtime }) } : {}
+    ...Object.keys(body).length > 0 ? { body: JSON.stringify(body) } : {}
   }));
   if (!res.ok) throw new Error(`heartbeat failed: ${res.status}`);
 }
@@ -31299,7 +31396,7 @@ var NotifyRequestSchema2 = external_exports.object({
   if (r.ask !== void 0) {
     for (const f of ["context", "select", "points"]) {
       if (r[f] !== void 0)
-        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives it (use \`needs\` for multi-part asks)` });
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives the answer shape from your prose. Drop ${f} and say it in \`ask\` instead ("should I\u2026" for approve/deny, "which of these\u2026" for a pick), passing \`options\` when you're offering concrete alternatives.` });
     }
     return;
   }
@@ -31534,7 +31631,13 @@ var NotifyPlanUnitSchema2 = external_exports.object({
   proposal: external_exports.object({
     select: SelectShapeSchema2,
     options: external_exports.array(external_exports.object({ label: external_exports.string().min(1) })).optional()
-  }).optional()
+  }).optional(),
+  /** What the broker READ this unit as wanting from the human (#952 layer 2): a `decision`
+   *  between alternatives, an `approval` the agent is blocked on, or `knowledge` it just
+   *  needs to know. Reported so the agent can correct a misread the same way it ratifies a
+   *  shape — the read RAISES (a decision always asks) and never silences a question the
+   *  agent declared (#731, #923). */
+  wants: external_exports.enum(["decision", "approval", "knowledge"]).optional()
 });
 var NotifyPlanSchema2 = external_exports.object({
   units: external_exports.array(NotifyPlanUnitSchema2),
@@ -31781,6 +31884,15 @@ var HistoryItemSchema2 = external_exports.object({
   /** When you answered the agent's notification (agent→user only). */
   humanAckedAt: external_exports.string().nullable()
 });
+var ACTIVITY_LINES2 = 2;
+var ACTIVITY_LINE_MAX2 = 80;
+var AgentActivitySchema2 = external_exports.object({
+  /** Oldest first, so the newest line is last — the one that replaces in place. */
+  lines: external_exports.array(external_exports.string().max(ACTIVITY_LINE_MAX2)).max(ACTIVITY_LINES2),
+  /** When the harness observed this tail. Its own timestamp, not the heartbeat's: a beat
+   *  that carries an UNCHANGED tail must not make a stalled agent look like it just moved. */
+  at: external_exports.string().datetime()
+});
 var ConnectionSummarySchema2 = external_exports.object({
   /** The connection = the agent's token id (used to address a request). */
   id: external_exports.string(),
@@ -31814,6 +31926,11 @@ var ConnectionSummarySchema2 = external_exports.object({
     harnesses: external_exports.array(external_exports.object({ name: external_exports.string(), label: external_exports.string(), status: external_exports.string() })).optional(),
     workspaces: external_exports.array(external_exports.string()).optional()
   }).optional(),
+  /** The tail of this agent's working log, when a harness is driving it — the agent page's
+   *  live strip. Absent for anything the desktop harness isn't running (a hatched identity
+   *  used straight from a terminal emits no work events; the page says so rather than
+   *  drawing an empty box). */
+  activity: AgentActivitySchema2.optional(),
   /** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: external_exports.boolean()
@@ -32690,9 +32807,30 @@ function startSession(opts) {
   };
 }
 
+// src/paigy/activity.ts
+function shortenPaths(s) {
+  return s.replace(/(?<![\w.@+-])(?:\/[\w.@+-]+){3,}/g, (p) => {
+    const parts = p.split("/").filter(Boolean);
+    return `\u2026/${parts.slice(-2).join("/")}`;
+  });
+}
+function workLine(event) {
+  const note = (event.note ?? "").split("\n").find((l) => l.trim()) ?? "";
+  const line = shortenPaths([event.tool.trim(), note.trim()].filter(Boolean).join(" \u2014 ").replace(/\s+/g, " "));
+  return line.length > ACTIVITY_LINE_MAX2 ? `${line.slice(0, ACTIVITY_LINE_MAX2 - 1)}\u2026` : line;
+}
+function pushWork(lines, line) {
+  if (!line || lines[lines.length - 1] === line) return [...lines];
+  return [...lines, line].slice(-ACTIVITY_LINES2);
+}
+function sameTail(a, b) {
+  return a.length === b.length && a.every((l, i) => l === b[i]);
+}
+
 // src/run.ts
 function runHarness(opts) {
   let running = true;
+  let tail = [];
   const state = { ...opts.exclusive ? { exclusive: true } : {} };
   let session = null;
   const asMe = { token: opts.token };
@@ -32722,6 +32860,7 @@ function runHarness(opts) {
     }
     if (event.kind === "work") {
       opts.log(`\u2699 ${event.tool}${event.note ? ` \u2014 ${event.note.split("\n")[0] ?? ""}` : ""}`);
+      tail = pushWork(tail, workLine(event));
       return;
     }
     const { parentId } = await mirror(event, state, deps);
@@ -32729,6 +32868,7 @@ function runHarness(opts) {
     if (event.kind === "turn") opts.log(`${event.role}: ${event.text.split("\n")[0] ?? ""}`);
     if (event.kind === "idle") {
       state.resting = true;
+      tail = [];
       if (endsWithQuestion(event.result)) {
         const local = await opts.localAsk?.question?.(event.result ?? "") ?? null;
         if (local?.trim() && session && running) {
@@ -32766,8 +32906,10 @@ function runHarness(opts) {
       session?.send(text);
     },
     working: () => running && state.resting !== true,
+    tail: () => [...tail],
     stop() {
       running = false;
+      tail = [];
       cancelAsks(state);
       session?.stop();
       session = null;
@@ -32909,6 +33051,27 @@ function startHost(opts) {
       opts.log(`\u25B6 woke ${label} (${harness}) \u2014 work was waiting in ${workspace}`);
     }
   }
+  const ACTIVITY_MS = 2e3;
+  const published = /* @__PURE__ */ new Map();
+  const streamActivity = () => {
+    const publishTail = (token, lines) => {
+      void heartbeat(void 0, { token, activity: { lines, at: (/* @__PURE__ */ new Date()).toISOString() } }).catch(() => {
+      });
+    };
+    for (const [key, r] of runs) {
+      if (!r.token) continue;
+      const lines = r.run.tail();
+      const was = published.get(key);
+      if (was && sameTail(was.lines, lines)) continue;
+      published.set(key, { token: r.token, lines });
+      publishTail(r.token, lines);
+    }
+    for (const [key, was] of published) {
+      if (runs.has(key)) continue;
+      published.delete(key);
+      if (was.lines.length > 0) publishTail(was.token, []);
+    }
+  };
   const publish = () => {
     try {
       writeFileSync3(HOST_FILE, JSON.stringify({ pid: process.pid, at: Date.now(), roster: api.roster() }));
@@ -32922,6 +33085,7 @@ function startHost(opts) {
     void sweepSlots();
     publish();
   }, 5e3);
+  const activityTick = setInterval(streamActivity, ACTIVITY_MS);
   const stopSessions = () => {
     for (const { run, label } of runs.values()) {
       run.stop();
@@ -32959,6 +33123,8 @@ function startHost(opts) {
       clearInterval(pulse);
       clearInterval(spawnPoll);
       stopSessions();
+      streamActivity();
+      clearInterval(activityTick);
       try {
         writeFileSync3(HOST_FILE, JSON.stringify({ pid: process.pid, at: 0, roster: [] }));
       } catch {
@@ -32970,74 +33136,38 @@ function startHost(opts) {
 }
 
 // src/cli.ts
-function parseArgs(argv) {
-  const args = { harness: "claude", mode: "bypass", cwd: process.cwd(), doctor: false, host: false, pair: false, service: false, setup: false, grant: [], hatch: null, voice: null, slot: null, identity: null, graceSeconds: 90, prompt: "", handoff: false };
-  const words = [];
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    const next = () => argv[++i];
-    if (arg === "--harness") {
-      const v = next();
-      if (v !== "claude" && v !== "codex" && v !== "agy") return { error: `--harness must be claude, codex, or agy, got ${v ?? "nothing"}` };
-      args.harness = v;
-    } else if (arg === "--mode") {
-      const v = next();
-      if (v !== "bypass" && v !== "ask") return { error: `--mode must be bypass or ask, got ${v ?? "nothing"}` };
-      args.mode = v;
-    } else if (arg === "--cwd") {
-      const v = next();
-      if (!v) return { error: "--cwd needs a directory" };
-      args.cwd = v;
-    } else if (arg === "--doctor") {
-      args.doctor = true;
-    } else if (arg === "--grace") {
-      const v = Number(next());
-      if (!Number.isFinite(v) || v < 0) return { error: "--grace needs seconds (0 = straight to phone)" };
-      args.graceSeconds = v;
-    } else if (arg === "host") {
-      args.host = true;
-    } else if (arg === "pair") {
-      args.pair = true;
-    } else if (arg === "setup") {
-      args.setup = true;
-    } else if (arg === "service") {
-      args.service = true;
-    } else if (arg === "--grant") {
-      const v = next();
-      if (!v) return { error: "--grant needs a folder to allow" };
-      args.grant.push(v);
-    } else if (arg === "handoff") {
-      args.handoff = true;
-    } else if (arg === "hatch") {
-      const v = next();
-      if (!v) return { error: 'hatch needs a name: paigy-harness hatch "Voice bug hunter"' };
-      args.hatch = v;
-    } else if (arg === "--voice") {
-      args.voice = next() ?? null;
-    } else if (arg === "--slot") {
-      args.slot = next() ?? null;
-    } else if (arg === "--identity") {
-      const v = next();
-      if (!v) return { error: "--identity needs a hatched agent's name" };
-      args.identity = v;
-    } else if (arg?.startsWith("--")) {
-      return { error: `unknown flag ${arg}` };
-    } else if (arg) {
-      words.push(arg);
-    }
-  }
-  args.prompt = words.join(" ");
-  if (!args.doctor && !args.handoff && !args.hatch && !args.host && !args.pair && !args.service && !args.setup && !args.prompt) return { error: "a prompt is required (or setup / --doctor / pair / host / service / hatch NAME / handoff)" };
-  return args;
-}
 var STATUS_MARK = { ready: "\u2713", login: "\u25D0", "adapter-missing": "\u25D0", missing: "\u2717" };
 async function main() {
   const parsed = parseArgs(process.argv.slice(2));
   if ("error" in parsed) {
     console.error(`paigy-harness: ${parsed.error}`);
-    console.error("usage: paigy-harness setup | pair | host [--grant DIR]\u2026 | service | hatch NAME [--voice KEY] [--slot SLOT] | handoff | [--harness claude|codex|agy] [--mode bypass|ask] [--cwd DIR] [--identity NAME] [--grace SECONDS] [--doctor] PROMPT\u2026");
+    console.error(USAGE);
     process.exit(2);
   }
+  if (parsed.help) {
+    console.log(USAGE);
+    console.log("");
+    console.log("  setup          pair this machine, set up every agent found here, install the host service");
+    console.log("  pair           pair this machine only (QR / code)");
+    console.log("  host           host sessions your phone launches (--grant DIR to allow a folder)");
+    console.log("  service        install the host as a login service (macOS)");
+    console.log("  enable-tools   allowlist Paigy's tools in Claude Code so they don't prompt each time");
+    console.log("  hatch NAME     mint a sibling identity from this machine's credential");
+    console.log("  handoff        pin this terminal's identity here so your phone can resume it");
+    console.log("  --doctor       report which agent CLIs are installed and ready");
+    console.log("");
+    console.log('Anything else is a PROMPT: paigy-harness --harness codex "fix the tests"');
+    return;
+  }
+  if (parsed.enableTools) {
+    try {
+      execSync(`${ENABLE_TOOLS_COMMAND} --scope ${parsed.scope}`, { stdio: "inherit", shell: "/bin/sh" });
+    } catch {
+      console.error(`Couldn't run it \u2014 try directly: ${ENABLE_TOOLS_COMMAND} --scope ${parsed.scope}`);
+      process.exit(1);
+    }
+    return;
+  }
   if (parsed.doctor) {
     for (const a of detectAll()) {
       console.log(`${STATUS_MARK[a.status]} ${a.label}${a.hint ? ` \u2014 ${a.hint}` : ""}${a.install ? `
@@ -33120,6 +33250,14 @@ async function main() {
       } catch {
       }
     }
+    if (which("claude")) {
+      try {
+        execSync(ENABLE_TOOLS_COMMAND, { stdio: "ignore", shell: "/bin/sh" });
+        console.log("\u2713 Paigy's tools allowlisted in Claude Code (they won't prompt each time)");
+      } catch {
+        console.log(`  allowlist it later with: paigy-harness enable-tools`);
+      }
+    }
     try {
       const settings = join5(homedir6(), ".claude", "settings.json");
       if (which("claude") && existsSync5(settings)) {
@@ -33306,9 +33444,6 @@ async function main() {
   });
 }
 void main();
-export {
-  parseArgs
-};
 /*! Bundled license information:
 
 undici/lib/web/fetch/body.js: