@phren/cli 0.3.4 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/dist/bridge/agent-hooks.d.ts +6 -0
  2. package/dist/bridge/agent-hooks.js +63 -23
  3. package/dist/bridge/canary.d.ts +4 -0
  4. package/dist/bridge/canary.js +17 -4
  5. package/dist/bridge/changes.d.ts +7 -0
  6. package/dist/bridge/changes.js +6 -1
  7. package/dist/bridge/client.js +2 -1
  8. package/dist/bridge/command.js +7 -5
  9. package/dist/bridge/conductor-group.d.ts +1 -0
  10. package/dist/bridge/conductor-group.js +4 -3
  11. package/dist/bridge/dispatch-command.js +2 -2
  12. package/dist/bridge/fanouts.js +6 -2
  13. package/dist/bridge/hand-off.d.ts +1 -0
  14. package/dist/bridge/hand-off.js +3 -2
  15. package/dist/bridge/harness-status.d.ts +12 -0
  16. package/dist/bridge/harness-status.js +153 -0
  17. package/dist/bridge/health.d.ts +18 -0
  18. package/dist/bridge/health.js +30 -4
  19. package/dist/bridge/herdr.d.ts +6 -0
  20. package/dist/bridge/herdr.js +62 -8
  21. package/dist/bridge/install.js +4 -0
  22. package/dist/bridge/model-switch.js +5 -4
  23. package/dist/bridge/models.js +3 -2
  24. package/dist/bridge/pane-status.d.ts +37 -0
  25. package/dist/bridge/pane-status.js +139 -0
  26. package/dist/bridge/pane-text.d.ts +3 -11
  27. package/dist/bridge/pane-text.js +9 -16
  28. package/dist/bridge/peers.js +9 -6
  29. package/dist/bridge/prompt-once.d.ts +26 -0
  30. package/dist/bridge/prompt-once.js +69 -0
  31. package/dist/bridge/protocol.d.ts +10 -0
  32. package/dist/bridge/protocol.js +10 -0
  33. package/dist/bridge/schedule-format.d.ts +2 -0
  34. package/dist/bridge/schedule-launch.d.ts +10 -1
  35. package/dist/bridge/schedule-launch.js +29 -3
  36. package/dist/bridge/schedule-watch.js +1 -1
  37. package/dist/bridge/schedules.d.ts +10 -0
  38. package/dist/bridge/schedules.js +40 -0
  39. package/dist/bridge/server-launch.js +12 -10
  40. package/dist/bridge/server-pane-routes.js +23 -9
  41. package/dist/bridge/server-routes.d.ts +1 -0
  42. package/dist/bridge/server-routes.js +1 -1
  43. package/dist/bridge/session-servers.js +5 -6
  44. package/dist/bridge/side-questions.js +6 -5
  45. package/dist/bridge/terminal-choice.d.ts +11 -0
  46. package/dist/bridge/terminal-choice.js +37 -0
  47. package/dist/bridge/terminal-herdr.d.ts +5 -0
  48. package/dist/bridge/terminal-herdr.js +57 -0
  49. package/dist/bridge/terminal-tmux.d.ts +111 -0
  50. package/dist/bridge/terminal-tmux.js +549 -0
  51. package/dist/bridge/terminal.d.ts +119 -0
  52. package/dist/bridge/terminal.js +66 -0
  53. package/dist/bridge/transcript-claude.d.ts +6 -0
  54. package/dist/bridge/transcript-claude.js +20 -0
  55. package/dist/bridge/transcript-opencode.js +1 -1
  56. package/dist/bridge/transcript-preview.js +1 -1
  57. package/dist/bridge/transport.js +10 -4
  58. package/dist/bridge-hook.mjs +4800 -3397
  59. package/dist/cli-registry.js +7 -0
  60. package/dist/entrypoint.d.ts +2 -0
  61. package/dist/entrypoint.js +5 -1
  62. package/dist/index.js +8 -2
  63. package/dist/init/init.js +4 -0
  64. package/dist/link/doctor.js +33 -30
  65. package/dist/mcp/plugin-mode.d.ts +16 -0
  66. package/dist/mcp/plugin-mode.js +106 -0
  67. package/dist/modules/agent-package.d.ts +35 -0
  68. package/dist/modules/agent-package.js +133 -0
  69. package/dist/modules/registry.js +2 -2
  70. package/dist/session/utils.js +1 -1
  71. package/dist/tools/dispatch.js +2 -2
  72. package/package.json +1 -1
  73. package/plugins/opencode/phren-transcript.js +97 -6
  74. package/starter/global/skills/phren-consolidate/SKILL.md +1 -1
  75. package/starter/global/skills/phren-discover/SKILL.md +1 -1
  76. package/starter/global/skills/phren-init/SKILL.md +6 -8
  77. package/starter/global/skills/phren-profiles/SKILL.md +1 -1
  78. package/starter/global/skills/phren-summarize/SKILL.md +1 -1
  79. package/starter/global/skills/phren-sync/SKILL.md +1 -1
@@ -6,6 +6,12 @@ import path from "node:path";
6
6
  const PHREN_STORE = "__PHREN_STORE__";
7
7
  const FLUSH_MS = 250;
8
8
  const MAX_TOOL_OUTPUT = 200_000;
9
+ // OpenCode's read tool returns a picture as an inline data URL on the tool
10
+ // part (`state.attachments`). The Hook serves images up to 8 MiB; the session
11
+ // budget bounds what every flush rewrites.
12
+ const MAX_IMAGE_DATA = 4_000_000;
13
+ const MAX_SESSION_IMAGE_DATA = 24_000_000;
14
+ const IMAGE_DATA_URL = /^data:(image\/(?:png|jpeg|gif|webp));base64,([A-Za-z0-9+/=]+)$/;
9
15
  const STOP_REASONS = { stop: "end_turn", "tool-calls": "tool_use", length: "max_tokens" };
10
16
  const OPENCODE_SESSION = /^ses_[0-9A-Za-z]{1,64}$/;
11
17
  const APPROVAL_POLL_MS = 200;
@@ -145,14 +151,36 @@ function blocksFor(message) {
145
151
  return blocks;
146
152
  }
147
153
 
148
- function toolResults(message) {
154
+ /** A tool's picture attachments as Anthropic-shaped image blocks, the form the
155
+ * Hook's image route and the phone already read from Claude Code. Only inline
156
+ * data URLs are carried; an image over the caps becomes a text marker. */
157
+ function toolImages(state, budget) {
158
+ const blocks = [];
159
+ for (const attachment of Array.isArray(state?.attachments) ? state.attachments : []) {
160
+ if (attachment?.type !== "file" || typeof attachment.url !== "string") continue;
161
+ const match = IMAGE_DATA_URL.exec(attachment.url);
162
+ if (!match) continue;
163
+ const data = match[2];
164
+ if (data.length > MAX_IMAGE_DATA || data.length > budget.remaining) {
165
+ blocks.push({ type: "text", text: "[Image not included: too large to show on the phone]" });
166
+ continue;
167
+ }
168
+ budget.remaining -= data.length;
169
+ blocks.push({ type: "image", source: { type: "base64", media_type: match[1], data } });
170
+ }
171
+ return blocks;
172
+ }
173
+
174
+ function toolResults(message, budget) {
149
175
  const results = [];
150
176
  for (const id of message.partOrder) {
151
177
  const part = message.parts.get(id);
152
178
  if (!part || part.type !== "tool" || typeof part.callID !== "string") continue;
153
179
  const status = part.state?.status;
154
180
  if (status !== "completed" && status !== "error") continue;
155
- results.push({ type: "tool_result", tool_use_id: part.callID, content: toolOutput(part.state), is_error: status === "error" });
181
+ const output = toolOutput(part.state), images = toolImages(part.state, budget);
182
+ const content = images.length ? [{ type: "text", text: output }, ...images] : output;
183
+ results.push({ type: "tool_result", tool_use_id: part.callID, content, is_error: status === "error" });
156
184
  }
157
185
  return results;
158
186
  }
@@ -163,6 +191,7 @@ function linesFor(session) {
163
191
  .filter(Boolean)
164
192
  .sort((a, b) => (a.info?.time?.created ?? 0) - (b.info?.time?.created ?? 0) || String(a.info?.id).localeCompare(String(b.info?.id)));
165
193
  const lines = [];
194
+ const budget = { remaining: MAX_SESSION_IMAGE_DATA };
166
195
  let seq = 0;
167
196
  const emit = (type, data, created) => {
168
197
  lines.push(JSON.stringify({ seq: seq++, time: new Date(created || Date.now()).toISOString(), type, data }));
@@ -180,15 +209,48 @@ function linesFor(session) {
180
209
  data.usage = { input_tokens: info.tokens.input ?? 0, output_tokens: info.tokens.output ?? 0 };
181
210
  }
182
211
  if (blocks.length) emit("assistant/message", data, info.time?.created);
183
- const results = toolResults(message);
212
+ const results = toolResults(message, budget);
184
213
  if (results.length) emit("tool/results", { message: { role: "user", content: results } }, info.time?.updated ?? info.time?.created);
185
214
  }
186
215
  }
187
216
  return lines;
188
217
  }
189
218
 
219
+ /** Which conversation this OpenCode process is showing, by PID: the Hook
220
+ * reads it to bind a pane when Herdr reports no session for it. */
221
+ const pidBindingFile = () => path.join(storeRoot(), ".runtime", "sessions", `opencode-pid-${process.pid}.json`);
222
+ function writePidBinding(sessionID) {
223
+ mkdirSync(path.dirname(pidBindingFile()), { recursive: true });
224
+ writeJsonAtomic(pidBindingFile(), { session: sessionID, at: new Date().toISOString() });
225
+ }
226
+
227
+ /** What this OpenCode process is doing, by PID: "working", "idle" or
228
+ * "blocked" (a permission waits for an answer). The Hook reads it for a pane
229
+ * whose terminal does not watch its agents (tmux); Herdr has its own. */
230
+ const statusFile = () => path.join(storeRoot(), ".runtime", "sessions", `opencode-status-${process.pid}.json`);
231
+
190
232
  export const PhrenTranscriptPlugin = async () => {
191
233
  const sessions = new Map();
234
+ // Subagent sessions run inside the same process; the pane shows their parent.
235
+ const children = new Set();
236
+ let boundSession;
237
+ // A reused PID must not inherit an old process's conversation or state.
238
+ try { removeFile(pidBindingFile()); removeFile(statusFile()); } catch {}
239
+ let recordedStatus;
240
+ // Permission asks still open, by id: while any is, the process is blocked.
241
+ const asking = new Set();
242
+ const recordStatus = (status, sessionID) => {
243
+ // A fan-out worker runs headless, in no pane.
244
+ if (process.env.PHREN_FANOUT_JOB) return;
245
+ const next = asking.size && status === "working" ? "blocked" : status;
246
+ if (next === recordedStatus) return;
247
+ try {
248
+ mkdirSync(path.dirname(statusFile()), { recursive: true });
249
+ writeJsonAtomic(statusFile(), { status: next, ...(sessionID ? { session: sessionID } : {}), at: new Date().toISOString() });
250
+ recordedStatus = next;
251
+ } catch {}
252
+ };
253
+ const permissionId = properties => text(properties?.permissionID) || text(properties?.requestID) || text(properties?.id);
192
254
  const timers = new Map();
193
255
  const written = new Map();
194
256
  const pendingApprovals = new Set();
@@ -257,8 +319,12 @@ export const PhrenTranscriptPlugin = async () => {
257
319
  return {
258
320
  "chat.message": async (input, output) => {
259
321
  if (!OPENCODE_SESSION.test(text(input?.sessionID)) || !output?.message) return;
322
+ if (!process.env.PHREN_FANOUT_JOB && !children.has(input.sessionID) && boundSession !== input.sessionID) {
323
+ try { writePidBinding(input.sessionID); boundSession = input.sessionID; } catch {}
324
+ }
260
325
  rememberInfo(input.sessionID, output.message);
261
326
  for (const part of output.parts ?? []) rememberPart(input.sessionID, output.message.id, part);
327
+ if (!children.has(input.sessionID)) recordStatus("working", input.sessionID);
262
328
  },
263
329
  "permission.ask": async (input, output) => {
264
330
  // A fan-out worker runs headless in its own worktree with nobody watching
@@ -276,7 +342,11 @@ export const PhrenTranscriptPlugin = async () => {
276
342
  writeBlocked(input);
277
343
  return;
278
344
  }
279
- let request, answer, pendingSession;
345
+ let request, answer, pendingSession, decision;
346
+ // The ask blocks the process until it is answered: here from the
347
+ // phone, or in the terminal (permission.replied below).
348
+ const askId = text(input?.id);
349
+ if (askId) { asking.add(askId); recordStatus("blocked", text(input?.sessionID)); }
280
350
  try {
281
351
  const sessionID = text(input?.sessionID), id = text(input?.id);
282
352
  if (!OPENCODE_SESSION.test(sessionID) || !id) { setStatus(output, "ask"); return; }
@@ -294,7 +364,6 @@ export const PhrenTranscriptPlugin = async () => {
294
364
  title: text(input.title) || `Allow ${text(input.type) || "action"}?`, message: permissionMessage(input),
295
365
  createdAt: new Date(created).toISOString(), expiresAt: new Date(created + APPROVAL_DEADLINE_MS).toISOString() });
296
366
  const deadline = created + APPROVAL_DEADLINE_MS;
297
- let decision;
298
367
  while (Date.now() < deadline) {
299
368
  await sleep(APPROVAL_POLL_MS);
300
369
  try {
@@ -311,11 +380,25 @@ export const PhrenTranscriptPlugin = async () => {
311
380
  if (answer) removeFile(answer);
312
381
  if (request) removeFile(request);
313
382
  if (pendingSession) pendingApprovals.delete(pendingSession);
383
+ // Answered from the phone: back to work. Otherwise the terminal asks.
384
+ if (askId && (decision === "approve" || decision === "deny")) { asking.delete(askId); recordStatus("working", pendingSession); }
314
385
  }
315
386
  },
316
387
  event: async ({ event }) => {
317
388
  const properties = event?.properties ?? {};
389
+ if ((event?.type === "session.created" || event?.type === "session.updated") && properties.info?.parentID
390
+ && OPENCODE_SESSION.test(text(properties.info.id))) children.add(properties.info.id);
318
391
  const sessionID = typeof properties.sessionID === "string" ? properties.sessionID : properties.info?.sessionID ?? properties.part?.sessionID;
392
+ // Permission events name the ask (permission.updated / permission.asked)
393
+ // and its answer, which may come from the terminal.
394
+ if (event?.type === "permission.updated" || event?.type === "permission.asked") {
395
+ const id = permissionId(properties);
396
+ if (id) { asking.add(id); recordStatus("blocked", text(sessionID)); }
397
+ } else if (event?.type === "permission.replied") {
398
+ const id = permissionId(properties);
399
+ if (id) asking.delete(id); else asking.clear();
400
+ recordStatus("working", text(sessionID));
401
+ }
319
402
  if (!OPENCODE_SESSION.test(text(sessionID))) return;
320
403
  if (event.type === "message.updated") rememberInfo(sessionID, properties.info);
321
404
  else if (event.type === "message.part.updated") rememberPart(sessionID, properties.part?.messageID, properties.part);
@@ -334,7 +417,15 @@ export const PhrenTranscriptPlugin = async () => {
334
417
  } else if (event.type === "session.idle" || event.type === "session.error") {
335
418
  sessionState(sessionID).idle = true;
336
419
  flush(sessionID);
337
- } else if (event.type === "session.status" && properties.status?.type === "busy") sessionState(sessionID).idle = false;
420
+ if (!children.has(sessionID)) { asking.clear(); recordStatus("idle", sessionID); }
421
+ } else if (event.type === "session.status") {
422
+ if (properties.status?.type === "busy") sessionState(sessionID).idle = false;
423
+ // A subagent's session runs inside its parent's turn.
424
+ if (!children.has(sessionID) && ["busy", "retry", "idle"].includes(properties.status?.type)) {
425
+ if (properties.status.type === "idle") asking.clear();
426
+ recordStatus(properties.status.type === "idle" ? "idle" : "working", sessionID);
427
+ }
428
+ }
338
429
  },
339
430
  };
340
431
  };
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-consolidate
3
- description: Find patterns across project findings and surface insights that apply everywhere.
3
+ description: Find patterns that repeat across several projects' phren findings and promote the ones that apply everywhere into shared global memory.
4
4
  dependencies:
5
5
  - git
6
6
  ---
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-discover
3
- description: Audit your phren repo and tell you exactly what needs attention.
3
+ description: Audit the phren memory store and report what needs attention, such as stale content, projects missing a summary, skill gaps and unhealthy task queues, with the top three things to fix.
4
4
  dependencies:
5
5
  - git
6
6
  - gh
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-init
3
- description: Set up a new project in phren with summary, AGENTS.md, task, and skill templates.
3
+ description: Set up phren memory. Creates the store with `phren init` on first use, or adds the current project to an existing store with its summary, AGENTS.md and task list. Use when phren reports no store or the user wants a project remembered.
4
4
  dependencies:
5
5
  - git
6
6
  ---
@@ -24,17 +24,15 @@ PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
24
24
  ls "$PHREN_DIR" 2>/dev/null
25
25
  ```
26
26
 
27
- If the phren directory doesn't exist, offer to create it:
28
- > "No phren repo found. Want me to create one at ~/.phren? This will set up the base directory structure (global/, profiles/, machines.yaml)."
27
+ If the phren directory doesn't exist, this is a first run. Offer to set phren up:
28
+ > "phren has no memory store on this machine yet. Want me to run `phren init`? It creates a local git-backed store at ~/.phren and registers phren's memory hooks and MCP server with Claude Code (and any other agents it finds). Nothing leaves this machine unless you add a git remote."
29
29
 
30
- If the user says yes, create the base structure:
30
+ If the user says yes, let the CLI build the store; never create it by hand:
31
31
  ```bash
32
- mkdir -p "$PHREN_DIR"/{global/skills,profiles}
33
- # Create a starter machines.yaml
34
- # Create a starter profile
32
+ if command -v phren >/dev/null 2>&1; then phren init --yes; else npx -y @phren/cli init --yes; fi
35
33
  ```
36
34
 
37
- Then continue with the project scaffolding below.
35
+ If phren's MCP server is running in setup mode it offers the same thing as the `phren_setup` tool (`confirm: true` runs it). Either way, tell the user to restart Claude Code afterwards so the memory tools and hooks load, then continue with the project scaffolding below if they named a project.
38
36
 
39
37
  ## With a project name
40
38
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-profiles
3
- description: Manage machine-to-profile and profile-to-project mappings in phren. Multi-machine users only.
3
+ description: Inspect or change which projects each machine loads from the phren store (machine-to-profile and profile-to-project mappings). Only for users who sync phren across several machines.
4
4
  dependencies:
5
5
  - git
6
6
  ---
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-summarize
3
- description: Write the "what we know" paragraph for each topic archive yourself, from the bullets phren hands you, using the model you are already running as. No API key, no local model.
3
+ description: Write the grounded "what we know" paragraph for each phren topic archive from the bullets phren provides, using the model already running. No API key or local model needed.
4
4
  ---
5
5
  # /phren-summarize
6
6
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-sync
3
- description: Pull your phren store onto this machine or push local changes back. Thin wrapper around the CLI, which does the linking.
3
+ description: Pull the phren memory store onto this machine (and wire it with `phren init`) or push local memory changes to its git remote. Use on a new machine or when memory on another machine should catch up.
4
4
  dependencies:
5
5
  - git
6
6
  ---