@phren/cli 0.3.13 → 0.3.15

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 (52) hide show
  1. package/README.md +1 -1
  2. package/dist/bridge/account-usage.d.ts +2 -1
  3. package/dist/bridge/account-usage.js +8 -1
  4. package/dist/bridge/claude-accounts.d.ts +3 -0
  5. package/dist/bridge/claude-accounts.js +13 -1
  6. package/dist/bridge/codex-app-server.d.ts +6 -0
  7. package/dist/bridge/codex-app-server.js +3 -1
  8. package/dist/bridge/codex-servers.d.ts +25 -1
  9. package/dist/bridge/codex-servers.js +78 -14
  10. package/dist/bridge/command.js +1 -1
  11. package/dist/bridge/conductor-group.d.ts +2 -0
  12. package/dist/bridge/conductor-group.js +17 -5
  13. package/dist/bridge/conductor-sets.js +23 -3
  14. package/dist/bridge/dispatch-command.d.ts +1 -0
  15. package/dist/bridge/dispatch-command.js +40 -2
  16. package/dist/bridge/dispatch-returns.d.ts +24 -1
  17. package/dist/bridge/dispatch-returns.js +125 -12
  18. package/dist/bridge/dispatch.d.ts +76 -0
  19. package/dist/bridge/dispatch.js +7 -0
  20. package/dist/bridge/hand-off-queue.d.ts +3 -0
  21. package/dist/bridge/hand-off-queue.js +9 -0
  22. package/dist/bridge/install.d.ts +8 -1
  23. package/dist/bridge/install.js +44 -5
  24. package/dist/bridge/owner-inbox-view.d.ts +6 -0
  25. package/dist/bridge/owner-inbox-view.js +32 -0
  26. package/dist/bridge/owner-inbox.d.ts +117 -0
  27. package/dist/bridge/owner-inbox.js +120 -0
  28. package/dist/bridge/return-contract.d.ts +35 -0
  29. package/dist/bridge/return-contract.js +10 -0
  30. package/dist/bridge/server-launch.js +12 -1
  31. package/dist/bridge/server-routes.d.ts +5 -0
  32. package/dist/bridge/server-routes.js +22 -1
  33. package/dist/bridge/server.js +37 -1
  34. package/dist/bridge/subscription.d.ts +13 -0
  35. package/dist/bridge/subscription.js +24 -0
  36. package/dist/bridge/terminal-herdr.js +1 -0
  37. package/dist/bridge/terminal-tmux.js +1 -0
  38. package/dist/bridge/terminal.d.ts +1 -0
  39. package/dist/bridge/terminal.js +1 -0
  40. package/dist/bridge/usage.d.ts +6 -0
  41. package/dist/bridge/usage.js +57 -10
  42. package/dist/bridge/worker-close.d.ts +10 -0
  43. package/dist/bridge/worker-close.js +77 -0
  44. package/dist/bridge/worker-reports.d.ts +10 -0
  45. package/dist/bridge/worker-reports.js +63 -0
  46. package/dist/bridge-hook.mjs +5158 -4480
  47. package/dist/cli-registry.js +9 -2
  48. package/dist/modules/registry.js +5 -5
  49. package/dist/test-global-setup.js +7 -0
  50. package/dist/tools/dispatch.js +33 -1
  51. package/package.json +1 -1
  52. package/starter/global/skills/conductor/SKILL.md +35 -0
@@ -160,12 +160,13 @@ export const REGISTRY = [
160
160
  },
161
161
  },
162
162
  {
163
- name: "dispatch", topic: "core", usage: "phren dispatch <computer|anywhere> <project> --label <label> --prompt <brief> [--harness codex|claude|opencode] [--model <model>] [--effort <effort>] [--account <id>] [--permission-mode <mode>]",
163
+ name: "dispatch", topic: "core", usage: "phren dispatch <computer|anywhere> <project> --label <label> --prompt <brief> [--harness codex|claude|opencode] [--model <model>] [--effort <effort>] [--account <id>] [--permission-mode <mode>] [--keep-open]",
164
164
  summary: "Dispatch a worker brief through Phren Hook",
165
165
  subcommands: [{ name: "status", usage: "phren dispatch status", summary: "List local dispatch receipts" },
166
166
  { name: "returns", usage: "phren dispatch returns", summary: "List unread worker returns (done, needs you, blocked, gone) and mark them read" },
167
167
  { name: "sessions", usage: "phren dispatch sessions", summary: "List live agent sessions on this and every enrolled computer" },
168
- { name: "usage", usage: "phren dispatch usage [--json]", summary: "Show agent usage on this and every enrolled computer, merged by account" }],
168
+ { name: "usage", usage: "phren dispatch usage [--json]", summary: "Show agent usage on this and every enrolled computer, merged by account" },
169
+ { name: "report", usage: "phren dispatch report --prs <JSON>", summary: "Record this worker turn's PR evidence for the integrator" }],
169
170
  run: async (args) => (await import("./bridge/dispatch-command.js")).runDispatch(args),
170
171
  },
171
172
  {
@@ -186,6 +187,11 @@ export const REGISTRY = [
186
187
  summary: "Agent usage per harness (limits, resets, spend) across computers from Phren Hook, without Phren memory",
187
188
  run: async (args) => (await import("./computers/command.js")).runUsage(args),
188
189
  },
190
+ {
191
+ name: "owner-inbox", topic: "core", usage: "phren owner-inbox [list [--all] | add <title> [--project <slug>] [--id <uuid>] | resolve <id> [--computer <name>] [--resolution <text>]]",
192
+ summary: "List, add and resolve what waits on the owner",
193
+ run: async (args) => (await import("./bridge/dispatch-command.js")).runOwnerInbox(args),
194
+ },
189
195
  {
190
196
  name: "hand-off", topic: "core", usage: "phren hand-off <computer|local> --session <id> --text <prompt> [--account <id>]",
191
197
  summary: "Send work to an existing agent session through Phren Hook",
@@ -200,6 +206,7 @@ export const REGISTRY = [
200
206
  name: "conductor", topic: "core", usage: "phren conductor <subcommand>",
201
207
  summary: "Make or stop this computer's conductor, list linked computer sets, and manage standing grants",
202
208
  subcommands: [
209
+ { name: "integrator", usage: "phren conductor integrator [--session <id> [--computer <name>] | --clear]", summary: "Configure the session that receives structured PR-ready reports" },
203
210
  { name: "status", usage: "phren conductor status", summary: "This computer's conductor and the set name it holds" },
204
211
  { name: "make", usage: "phren conductor make [--pane <id>] [--mux herdr:<name>|tmux:<name>]", summary: "Make the agent in this pane (or --pane) this computer's conductor" },
205
212
  { name: "stop", usage: "phren conductor stop [--pane <id>]", summary: "End this computer's conductor role; the agent keeps running" },
@@ -128,11 +128,11 @@ export const BUILTIN_MODULES = [
128
128
  },
129
129
  {
130
130
  schemaVersion: 1, name: "conductor", version: VERSION, defaultEnabled: false, requires: ["memory", "hook"],
131
- tools: full(["dispatch", "dispatch_returns", "dispatch_approve", "hand_off", "live_sessions", "account_usage", "authority"]), cliCommands: ["dispatch", "dispatch status", "dispatch returns", "dispatch sessions", "dispatch usage", "hand-off", "conductor", "conductor grants", "conductor status", "conductor make", "conductor stop", "conductor sets", "authority", "bridge enroll-computer"], agentHooks: [],
132
- hookRoutes: [...routes("GET", ["/v1/dispatch", "/v1/dispatch/capacity", "/v1/dispatch/arrival", "/v1/conductor", "/v1/conductor/grants", "/v1/computers", "/v1/sets", "/v1/authority"]),
133
- ...routes("POST", ["/v1/dispatch", "/v1/dispatch/workers", "/v1/dispatch/returns", "/v1/dispatch/approve", "/v1/hand-off", "/v1/hand-off/status", "/v1/conductor/grants", "/v1/conductor/make", "/v1/conductor/stop", "/v1/sets/name", "/v1/authority", "/v1/authority/confirm"]), ...routes("DELETE", ["/v1/conductor/grants", "/v1/authority"])],
134
- capabilities: ["dispatch", "conductorSets"], storeFiles: ["global/skills/conductor/**"],
135
- localFiles: ["<bridge>/hooks.yaml", "<bridge>/conductor.yaml", "<bridge>/conductor-role.json", "<bridge>/authority.yaml", "<bridge>/authority-confirmations.json", "<bridge>/dispatches/*.json", "<bridge>/hand-offs/*.json"], phoneScreens: [], skills: ["conductor"],
131
+ tools: full(["dispatch", "dispatch_returns", "dispatch_approve", "hand_off", "live_sessions", "account_usage", "authority", "dispatch_report", "owner_inbox"]), cliCommands: ["dispatch", "dispatch status", "dispatch returns", "dispatch sessions", "dispatch usage", "dispatch report", "hand-off", "conductor", "conductor grants", "conductor status", "conductor make", "conductor stop", "conductor sets", "conductor integrator", "owner-inbox", "authority", "bridge enroll-computer"], agentHooks: [],
132
+ hookRoutes: [...routes("GET", ["/v1/dispatch", "/v1/dispatch/capacity", "/v1/dispatch/arrival", "/v1/conductor", "/v1/conductor/grants", "/v1/computers", "/v1/sets", "/v1/authority", "/v1/owner-inbox", "/v1/conductor/integrator"]),
133
+ ...routes("POST", ["/v1/dispatch", "/v1/dispatch/workers", "/v1/dispatch/returns", "/v1/dispatch/approve", "/v1/dispatch/report", "/v1/dispatch/close", "/v1/owner-inbox", "/v1/conductor/integrator", "/v1/hand-off", "/v1/hand-off/status", "/v1/conductor/grants", "/v1/conductor/make", "/v1/conductor/stop", "/v1/sets/name", "/v1/authority", "/v1/authority/confirm"]), ...routes("DELETE", ["/v1/conductor/grants", "/v1/authority"])],
134
+ capabilities: ["dispatch", "conductorSets", "ownerInbox", "workerReports", "queuedHandOff"], storeFiles: ["global/skills/conductor/**"],
135
+ localFiles: ["<bridge>/hooks.yaml", "<bridge>/conductor.yaml", "<bridge>/conductor-role.json", "<bridge>/authority.yaml", "<bridge>/authority-confirmations.json", "<bridge>/dispatches/*.json", "<bridge>/hand-offs/*.json", "<bridge>/worker-reports/*.json", "<bridge>/closed-workers/*.json", "<bridge>/owner-inbox.json", "<bridge>/integrator.json"], phoneScreens: [], skills: ["conductor"],
136
136
  },
137
137
  {
138
138
  schemaVersion: 1, name: "fanout", version: VERSION, defaultEnabled: false, requires: ["memory", "hook"],
@@ -47,6 +47,13 @@ function sandboxHomeDir() {
47
47
  // would point that at their real files, so both fall back to the sandbox.
48
48
  delete process.env.CLAUDE_CONFIG_DIR;
49
49
  delete process.env.CODEX_HOME;
50
+ // A run inside a Hook-launched worker inherits the Hook's own service
51
+ // variables. PHREN_BRIDGE_HOME pointed every install and init test at the
52
+ // real Hook, and `phren init` on a scratch store ran a real
53
+ // `systemctl --user stop phren-hook.service`. Unset, each falls back to
54
+ // the sandbox home, as on a clean machine.
55
+ for (const name of ["PHREN_BRIDGE_HOME", "PHREN_HERDR_HOME", "PHREN_PROFILE", "PHREN_DISPATCH_ID", "PHREN_CODEX_SERVER"])
56
+ delete process.env[name];
50
57
  }
51
58
  export async function teardown() {
52
59
  if (sandboxHome)
@@ -1,3 +1,5 @@
1
+ import { prsSchema } from "../bridge/return-contract.js";
2
+ import { ownerInboxSchema } from "../bridge/owner-inbox.js";
1
3
  import { z } from "zod";
2
4
  import { hookRequest } from "../bridge/client.js";
3
5
  import { dispatchSchema } from "../bridge/dispatch.js";
@@ -21,9 +23,39 @@ export function register(server) {
21
23
  return mcpResponse({ ok: false, error: error instanceof Error ? error.message : "Dispatch failed." });
22
24
  }
23
25
  });
26
+ server.registerTool("dispatch_report", {
27
+ title: "◆ phren · report PRs",
28
+ description: "Report PR evidence to this worker's own Hook before finishing the turn. The done return carries prs (url, repo, branch, tests summary, notes), and the Hook queues it to the configured integrator. No direct worker messaging or GitHub comment is needed. Does not claim tests passed or complete a task.",
29
+ inputSchema: { prs: prsSchema },
30
+ }, async (input) => {
31
+ try {
32
+ const origin = await terminalPaneFromEnv();
33
+ if (!origin)
34
+ throw new Error("Run dispatch_report inside the worker's terminal pane.");
35
+ const result = await hookRequest("/v1/dispatch/report", { ...input, origin });
36
+ return mcpResponse({ ok: result.ok === true, data: result, message: "PR evidence recorded for this turn's done return." });
37
+ }
38
+ catch (error) {
39
+ return mcpResponse({ ok: false, error: error instanceof Error ? error.message : "Could not report PR evidence." });
40
+ }
41
+ });
42
+ server.registerTool("owner_inbox", {
43
+ title: "◆ phren · owner inbox",
44
+ description: "One owner inbox on this conductor's Hook: list open needs-you returns, blocked prompts and manual items; add a title and optional project; resolve an id with an optional resolution. Reading returns does not resolve inbox items. Resolving an inbox item does not answer or approve a worker prompt. Use operation add, list or resolve (also through phren_admin action owner_inbox). includeResolved lists history. Keep an id on retried adds.",
45
+ inputSchema: ownerInboxSchema.omit({ action: true }).extend({ operation: ownerInboxSchema.shape.action }),
46
+ }, async (input) => {
47
+ try {
48
+ const { operation, ...rest } = input;
49
+ const result = await hookRequest("/v1/owner-inbox", { ...rest, action: operation ?? "list" });
50
+ return mcpResponse({ ok: result.ok === true, data: result, message: input.operation === "add" ? "Added to the owner inbox." : input.operation === "resolve" ? "Owner inbox item resolved." : `${Array.isArray(result.items) ? result.items.length : 0} owner inbox items.` });
51
+ }
52
+ catch (error) {
53
+ return mcpResponse({ ok: false, error: error instanceof Error ? error.message : "Could not read the owner inbox." });
54
+ }
55
+ });
24
56
  server.registerTool("dispatch_returns", {
25
57
  title: "◆ phren · dispatch returns",
26
- description: "List unread returns from dispatched workers and mark them read: the worker finished (done, with its final reply), finished by asking the owner something (needs-you, with the question), failed (the harness ended the turn on an error such as a usage limit, with the error), is blocked on terminal input, or its pane is gone. A blocked row with an `approval` field (actionId, tool, request) is a permission request the worker is waiting on, forwarded from its computer: answer it with dispatch_approve. A worker that ended its turn with background tasks pending is waited on for up to two hours; a row has `waited` (the most tasks it waited on) or, if some were still running after that, `background`. Each row has the dispatch id, computer, project, label and the worker's target for hand_off.",
58
+ description: "List unread returns from dispatched workers and mark them read: the worker finished (done, with its final reply), finished by asking the owner something (needs-you, with the question), failed (the harness ended the turn on an error such as a usage limit, with the error), is blocked on terminal input, or its pane is gone. A blocked row with an `approval` field (actionId, tool, request) is a permission request the worker is waiting on, forwarded from its computer: answer it with dispatch_approve. A worker that ended its turn with background tasks pending is waited on for up to two hours; a row has `waited` (the most tasks it waited on) or, if some were still running after that, `background`. A stalled row flags an unchanged working screen and transcript. A done row can include structured prs and integratorDelivery. Reading a done return closes its finished pane unless closeOnFinish:false was specified, after rechecking new and queued work. Each row has the dispatch id, computer, project, label and the worker's target for hand_off.",
27
59
  inputSchema: {},
28
60
  }, async () => {
29
61
  try {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.3.13",
3
+ "version": "0.3.15",
4
4
  "description": "Knowledge layer for AI agents - CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,6 +41,15 @@ Your tools, use these instead of exploring the CLI or the Hook's files:
41
41
  back since you last asked: done with the final reply, needs-you with the
42
42
  question, stalled with an unchanged screen and transcript, failed with the error (a usage limit), blocked, or gone. Reading them marks them read. In core use
43
43
  `phren_admin(action: "dispatch_returns")`.
44
+ - `dispatch_report`: workers record `prs`, an array of `{url, repo, branch,
45
+ tests, notes?}`, on their own Hook before ending the turn. The done return
46
+ carries that evidence, and the Hook queues it to the configured integrator.
47
+ In core use `phren_admin(action: "dispatch_report", prs)`.
48
+ - `owner_inbox` (CLI `phren owner-inbox`): list what waits on the owner across
49
+ linked computers, add a title with optional project, or resolve an id with
50
+ optional resolution. In core use `phren_admin(action: "owner_inbox", ...)`.
51
+ Use an item's `inboxComputer` as `computer` when resolving a remote item;
52
+ omit it for `local`. Say which computers were unreachable.
44
53
  - `phren dispatch status`: receipts of what you dispatched.
45
54
  - `get_tasks`, `get_project_summary`, `search_knowledge`: the store's memory.
46
55
 
@@ -149,6 +158,32 @@ skips one whose account for that harness is exhausted. Place
149
158
  briefs sequentially, respecting busy/rate-limit responses. Keep their dispatch
150
159
  IDs. Do not send local filesystem paths as remote project names.
151
160
 
161
+ Configure the integrator once with `phren conductor integrator --session <id>
162
+ [--computer <name>]`; list with `phren conductor integrator`, clear with
163
+ `--clear`. A dispatch can override it with `integrator: {computer?, target}`.
164
+ The integrator's full target is bound to that conversation. Workers report
165
+ structured PR evidence with `dispatch_report(prs)` in full or
166
+ `phren_admin(action:"dispatch_report", prs)` in core before finishing; they do not
167
+ need direct messaging or a GitHub comment to reach it. Inspect `prs` and
168
+ `integratorDelivery` in receipts and verify the evidence before integration.
169
+
170
+ Finished worker panes close after their done return is read. Use
171
+ `closeOnFinish:false` (`--keep-open` in the CLI) for a worker you will reuse.
172
+ The Hook rechecks its ended turn and skips a pane with new work, background
173
+ tasks, queued messages or uncertain delivery. Intentional closes do not return
174
+ `gone`. Reading returns can close panes, so record any follow-up first.
175
+
176
+ Keep one owner inbox item for each decision or action that waits on the owner.
177
+ Needs-you returns and blocked prompts appear automatically, even if their
178
+ returns were read. Add other actions such as restarting the router with
179
+ `owner_inbox(operation:"add", title, project?, id?)` in full or
180
+ `phren_admin(action:"owner_inbox", operation:"add", title, project?, id?)` in
181
+ core; keep the id on retries.
182
+ Resolve an item only once the owner decided or completed the action. Resolution
183
+ does not send an answer, approve a prompt, or mark a task complete. Send an
184
+ owner's answer separately with queued `hand_off`. A source that stopped waiting
185
+ is retained as `live:false` until resolved; a resolved source stays resolved.
186
+
152
187
  `accepted` on a receipt is prompt acceptance, not worker completion. Returns
153
188
  arrive on their own: the Hook follows every worker you dispatch, and when you
154
189
  are idle it types one line into this session, such as `Return: Linuxbox parser