@phren/cli 0.3.12 → 0.3.14

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 (58) hide show
  1. package/dist/bridge/account-usage.d.ts +124 -0
  2. package/dist/bridge/account-usage.js +258 -0
  3. package/dist/bridge/agent-hooks.d.ts +3 -0
  4. package/dist/bridge/agent-hooks.js +20 -1
  5. package/dist/bridge/codex-app-server.d.ts +6 -0
  6. package/dist/bridge/codex-app-server.js +3 -1
  7. package/dist/bridge/codex-hook-trust.d.ts +27 -0
  8. package/dist/bridge/codex-hook-trust.js +237 -0
  9. package/dist/bridge/codex-servers.d.ts +25 -1
  10. package/dist/bridge/codex-servers.js +78 -14
  11. package/dist/bridge/command.js +4 -1
  12. package/dist/bridge/dispatch-command.js +9 -3
  13. package/dist/bridge/dispatch-returns.d.ts +8 -0
  14. package/dist/bridge/dispatch-returns.js +21 -6
  15. package/dist/bridge/dispatch.d.ts +25 -1
  16. package/dist/bridge/dispatch.js +35 -6
  17. package/dist/bridge/hand-off-queue.d.ts +74 -0
  18. package/dist/bridge/hand-off-queue.js +235 -0
  19. package/dist/bridge/hand-off.d.ts +12 -4
  20. package/dist/bridge/hand-off.js +27 -7
  21. package/dist/bridge/install.d.ts +8 -1
  22. package/dist/bridge/install.js +60 -7
  23. package/dist/bridge/pane-status.d.ts +12 -0
  24. package/dist/bridge/pane-status.js +50 -1
  25. package/dist/bridge/push.d.ts +6 -0
  26. package/dist/bridge/push.js +21 -0
  27. package/dist/bridge/schedule-launch.d.ts +1 -1
  28. package/dist/bridge/schedule-launch.js +5 -1
  29. package/dist/bridge/schedule-watch.d.ts +15 -1
  30. package/dist/bridge/schedule-watch.js +45 -10
  31. package/dist/bridge/server-launch.js +14 -4
  32. package/dist/bridge/server-overview.d.ts +8 -1
  33. package/dist/bridge/server-overview.js +12 -3
  34. package/dist/bridge/server-pane-routes.d.ts +1 -0
  35. package/dist/bridge/server-pane-routes.js +9 -7
  36. package/dist/bridge/server-routes.d.ts +4 -0
  37. package/dist/bridge/server-routes.js +57 -7
  38. package/dist/bridge/server.js +15 -2
  39. package/dist/bridge/session-activity.d.ts +24 -12
  40. package/dist/bridge/session-activity.js +36 -14
  41. package/dist/bridge/stalls.d.ts +22 -0
  42. package/dist/bridge/stalls.js +57 -0
  43. package/dist/bridge/sudo.d.ts +209 -0
  44. package/dist/bridge/sudo.js +501 -0
  45. package/dist/bridge/terminal-tmux.d.ts +12 -0
  46. package/dist/bridge/terminal-tmux.js +79 -4
  47. package/dist/bridge/transcript-claude.d.ts +4 -0
  48. package/dist/bridge/transcript-claude.js +131 -6
  49. package/dist/bridge/usage.d.ts +17 -0
  50. package/dist/bridge/usage.js +37 -3
  51. package/dist/bridge-hook.mjs +24911 -23487
  52. package/dist/cli-registry.js +7 -1
  53. package/dist/modules/registry.js +8 -8
  54. package/dist/test-global-setup.js +7 -0
  55. package/dist/tools/dispatch.js +17 -2
  56. package/package.json +1 -1
  57. package/starter/global/AGENTS.md +4 -0
  58. package/starter/global/skills/conductor/SKILL.md +34 -2
@@ -164,9 +164,15 @@ export const REGISTRY = [
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
- { name: "sessions", usage: "phren dispatch sessions", summary: "List live agent sessions on this and every enrolled computer" }],
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
169
  run: async (args) => (await import("./bridge/dispatch-command.js")).runDispatch(args),
169
170
  },
171
+ {
172
+ name: "sudo", topic: "core", standalone: true, usage: "phren sudo <command...>",
173
+ summary: "Run sudo -A with Phren Hook's askpass: your phone shows the command and asks for the password, for `!` commands and agents with no terminal",
174
+ run: async (args) => (await import("./bridge/sudo.js")).runSudo(args),
175
+ },
170
176
  {
171
177
  name: "computers", topic: "core", standalone: true,
172
178
  usage: "phren computers [<name>] [--resources] [--pick [mac|linux|any]] [--exclude a,b] [--local] [--json] | phren computers mcp",
@@ -69,7 +69,7 @@ export const BUILTIN_MODULES = [
69
69
  cliCommands: [
70
70
  "bridge", "bridge install", "bridge update", "bridge uninstall", "bridge rollback", "bridge status",
71
71
  "bridge doctor", "bridge usage", "bridge usage-statusline", "bridge hook", "bridge serve", "bridge ssh", "pair",
72
- "bridge fanouts archive", "bridge accounts", "canary", "computers", "computers mcp", "usage",
72
+ "bridge fanouts archive", "bridge accounts", "bridge askpass", "canary", "computers", "computers mcp", "usage", "sudo",
73
73
  ],
74
74
  agentHooks: [
75
75
  { agents: ["codex"], events: ["SessionStart", "UserPromptSubmit", "Stop", "PermissionRequest"], handler: "bridge-hook.mjs hook codex" },
@@ -81,7 +81,7 @@ export const BUILTIN_MODULES = [
81
81
  "/v1/health", "/v1/health/details", "/v1/health/peers", "/v1/muxes", "/v1/activity", "/v1/metrics", "/v1/web-servers", "/v1/simulators",
82
82
  "/v1/simulators/screenshot", "/v1/simulators/apps", "/v1/files", "/v1/models", "/v1/harnesses", "/v1/projects/files",
83
83
  "/v1/uploads/image", "/v1/files/range", "/v1/usage", "/v1/resources", "/v1/speech/voices", "/v1/push/status", "/v1/projects/locate", "/v1/projects/repos",
84
- "/v1/workspaces", "/v1/workspaces/panes", "/v1/transcripts/blob", "/v1/transcripts/history",
84
+ "/v1/workspaces", "/v1/workspaces/panes", "/v1/transcripts/blob", "/v1/transcripts/history", "/v1/sudo",
85
85
  "/v1/subagents", "/v1/subagents/transcript", "/v1/subagents/messages",
86
86
  ]),
87
87
  ...routes("POST", [
@@ -89,17 +89,17 @@ export const BUILTIN_MODULES = [
89
89
  "/v1/workspaces/launch", "/v1/workspaces/create", "/v1/workspaces/focus", "/v1/workspaces/rename",
90
90
  "/v1/workspaces/close", "/v1/sessions/rename", "/v1/prompt", "/v1/prompt/status", "/v1/model", "/v1/settings", "/v1/side-question/dismiss", "/v1/keys", "/v1/secret", "/v1/upload",
91
91
  "/v1/approvals/answer", "/v1/questions/answer", "/v1/subagents/resume", "/v1/subagents/archive-finished", "/v1/canary",
92
- "/v1/speech",
92
+ "/v1/speech", "/v1/sudo/answer",
93
93
  ]),
94
94
  ...routes("WS", ["/v1/transcripts", "/v1/status", "/v1/overview", "/v1/speech/transcribe"]),
95
95
  ],
96
96
  capabilities: [
97
97
  "hook", "transcript", "progress", "images", "prompt", "stop", "terminal", "shell", "herdr",
98
98
  "webServers", "webPreview", "activity", "approvals", "questions", "accountUsage", "providers",
99
- "files", "repositoryFiles", "subagents", "sideQuestions", "approvalPush", "simulators", "overviewStream", "speech", "speechTimestamps", "speechVoices", "speechFormats", "transcribe", "promptOnce", "promptStatus", "resources", "sessionRename",
99
+ "files", "repositoryFiles", "subagents", "sideQuestions", "approvalPush", "simulators", "overviewStream", "speech", "speechTimestamps", "speechVoices", "speechFormats", "transcribe", "promptOnce", "promptStatus", "resources", "sessionRename", "sudo", "sudoOutcome",
100
100
  ],
101
101
  storeFiles: [".runtime/sessions/opencode-*.events.jsonl", ".runtime/approvals/opencode-*.json"],
102
- localFiles: ["<bridge>/installed.json", "<bridge>/versions/**", "<bridge>/current", "<bridge>/dispatch", "<bridge>/computer-id", "<bridge>/canary.json", "<bridge>/canary-daily"],
102
+ localFiles: ["<bridge>/installed.json", "<bridge>/versions/**", "<bridge>/current", "<bridge>/dispatch", "<bridge>/askpass", "<bridge>/computer-id", "<bridge>/canary.json", "<bridge>/canary-daily"],
103
103
  phoneScreens: [{ screen: "LiveSessionsView", capability: "hook" }, { screen: "AgentChatView", capability: "transcript" }],
104
104
  skills: [],
105
105
  },
@@ -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", "authority"]), cliCommands: ["dispatch", "dispatch status", "dispatch returns", "dispatch sessions", "hand-off", "conductor", "conductor grants", "conductor status", "conductor make", "conductor stop", "conductor sets", "authority", "bridge enroll-computer"], agentHooks: [],
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
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/conductor/grants", "/v1/conductor/make", "/v1/conductor/stop", "/v1/sets/name", "/v1/authority", "/v1/authority/confirm"]), ...routes("DELETE", ["/v1/conductor/grants", "/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
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"], phoneScreens: [], 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"],
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)
@@ -2,6 +2,7 @@ import { z } from "zod";
2
2
  import { hookRequest } from "../bridge/client.js";
3
3
  import { dispatchSchema } from "../bridge/dispatch.js";
4
4
  import { handOff, handOffSchema, listLiveSessions } from "../bridge/hand-off.js";
5
+ import { readAccountUsage, usageSummary } from "../bridge/account-usage.js";
5
6
  import { terminalPaneFromEnv } from "../bridge/terminal.js";
6
7
  import { mcpResponse } from "./types.js";
7
8
  export function register(server) {
@@ -69,6 +70,20 @@ export function register(server) {
69
70
  return mcpResponse({ ok: false, error: error instanceof Error ? error.message : "Could not list live sessions." });
70
71
  }
71
72
  });
73
+ server.registerTool("account_usage", {
74
+ title: "◆ phren · account usage",
75
+ description: "Agent usage on this computer and every enrolled computer, merged by account: one row per Claude login, Codex, OpenCode, OpenCode Go, OpenRouter and GitHub Copilot, with its windows (percent used, percent left, reset time), leftPercent (the least room on any window), nearLimit (under 20% left: information, not a reason to avoid it), exhausted (a window at 100% or refusing requests, with availableIn), freshness (updatedAt, age, stale), and the computers where it is signed in with the Claude account id dispatch takes there. A window whose reset passed says reset and has no percent; a report over 15 minutes old is stale. Call it before dispatch: never send work to an exhausted account; a low one is fine, and one that resets soon is worth using before it does. Harnesses no computer reported are in noData; unreachable computers and computers not linked in hooks.yaml are listed separately: their usage is unknown, not zero.",
76
+ inputSchema: {},
77
+ }, async () => {
78
+ try {
79
+ const result = await readAccountUsage();
80
+ const note = result.peerError ? ` Enrolled computers were skipped: ${result.peerError}` : "";
81
+ return mcpResponse({ ok: true, data: result, message: `${usageSummary(result)}${note}` });
82
+ }
83
+ catch (error) {
84
+ return mcpResponse({ ok: false, error: error instanceof Error ? error.message : "Could not read account usage." });
85
+ }
86
+ });
72
87
  server.registerTool("authority", {
73
88
  title: "◆ phren · release authority",
74
89
  description: "Read the owner's release authority policy: per project, which release-type actions (merge, publish, deploy, app-store, github-admin) are go and which are ask-first, and the highest permission mode an agent may start a worker in there. Quote the project's `line` in a brief that asks for release work, and declare those actions in dispatch's releaseActions. An ask-first action needs the owner's confirmation first; ask the owner, never try to confirm it yourself. Read-only: only the owner changes the policy. Without project, lists every project the policy names.",
@@ -85,12 +100,12 @@ export function register(server) {
85
100
  });
86
101
  server.registerTool("hand_off", {
87
102
  title: "◆ phren · hand off",
88
- description: "Deliver a prompt to an existing local or enrolled-computer agent session through Phren Hook. Prefer a session that already owns the project and is idle or doing related work.",
103
+ description: "Deliver a prompt to an existing local or enrolled-computer agent session through Phren Hook. Busy workers receive a durable queued message at their next idle. Keep deliveryId on retries. Use status:true with deliveryId and target or session to read queued, delivered, uncertain or failed without sending. Uncertain delivery is never retried automatically.",
89
104
  inputSchema: handOffSchema,
90
105
  }, async (input) => {
91
106
  try {
92
107
  const result = await handOff(input);
93
- return mcpResponse({ ok: result.ok, data: result, message: result.delivered ? "Prompt delivered to the existing session." : "Prompt delivery was not confirmed." });
108
+ return mcpResponse({ ok: result.ok, data: result, message: result.delivered ? "Prompt delivered to the existing session." : result.queued ? `Prompt queued as ${result.deliveryId}. The Hook will deliver it at idle and notify the sender.` : "Prompt delivery was not confirmed; do not resend with a new id." });
94
109
  }
95
110
  catch (error) {
96
111
  return mcpResponse({ ok: false, error: error instanceof Error ? error.message : "Hand-off failed." });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.3.12",
3
+ "version": "0.3.14",
4
4
  "description": "Knowledge layer for AI agents - CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {
@@ -30,6 +30,10 @@ Worth saving: decisions and why, pitfalls with the fix, patterns that worked, me
30
30
 
31
31
  Every agent follows these rules, and tells phren about non-obvious findings before handing work back.
32
32
 
33
+ ## sudo
34
+
35
+ With no terminal, run `sudo -A <command>` (or `phren sudo <command>`): the owner types the password on their phone. Plain `sudo` fails there. Never ask for, store or echo the password.
36
+
33
37
  ## Where things are
34
38
 
35
39
  `~/.phren` (or `$PHREN_PATH`) is a git repo: `global/` for everything-everywhere, `<project>/` for each project's AGENTS.md, findings, tasks and skills, `profiles/` and `machines.yaml` for which projects belong on which machine. `phren doctor` explains anything that is off. If the MCP server is not running, phren still injects context through hooks; the CLI (`phren search`, `phren add-finding`) does the rest.
@@ -27,10 +27,19 @@ Your tools, use these instead of exploring the CLI or the Hook's files:
27
27
  but have no Hook link here: say they were not checked, never that nothing is
28
28
  running there.
29
29
  - `hand_off`: send a prompt to one of those sessions.
30
+ - `account_usage` (CLI `phren dispatch usage`): every computer's agent usage
31
+ merged by account (each Claude login, Codex, OpenCode Go and the rest): percent
32
+ left on each window, when it resets, whether the numbers are fresh, and the
33
+ computers where it is signed in. In core use
34
+ `phren_admin(action: "account_usage")`.
35
+ - `hand_off`: send a prompt to one of those sessions. A busy session queues it
36
+ durably in its Hook. Keep its `deliveryId`; `queued` means waiting, `delivered`
37
+ means confirmed. Check with `hand_off(target|session, computer?, deliveryId,
38
+ status:true)` and no text. Never resend with a new id because it is busy.
30
39
  - `dispatch`: start a new worker on a computer (or `anywhere`).
31
40
  - `dispatch_returns` (CLI `phren dispatch returns`): what your workers sent
32
41
  back since you last asked: done with the final reply, needs-you with the
33
- question, failed with the error (a usage limit), blocked, or gone. Reading them marks them read. In core use
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
34
43
  `phren_admin(action: "dispatch_returns")`.
35
44
  - `phren dispatch status`: receipts of what you dispatched.
36
45
  - `get_tasks`, `get_project_summary`, `search_knowledge`: the store's memory.
@@ -76,6 +85,9 @@ file ownership; give each remote lead a base revision, acceptance checks, local
76
85
  fanout limit, report time and integration instructions. Every brief repeats the
77
86
  owner's repository constraints, including any prohibition on commits, pushes,
78
87
  branches or particular tests. Dispatch never expands the owner's authorization.
88
+ A worker that needs root runs `sudo -A <command>`: its launch sets
89
+ `SUDO_ASKPASS`, and the owner approves the exact command and types the
90
+ password on the phone. Plain `sudo` fails without a terminal.
79
91
 
80
92
  You are the one conductor for this computer and every computer linked with
81
93
  it; a second conductor in the group is refused at launch. Conductors on
@@ -100,6 +112,21 @@ run` or `codex exec`, a launch script, nohup) has no manifest, so the phone and
100
112
  you cannot see, resume or review it. Workers that exist only as processes do
101
113
  not count as dispatched.
102
114
 
115
+ Check `account_usage` before you dispatch, once per batch. The one hard rule:
116
+ never dispatch to an account that is `exhausted` (a window at 100%, or
117
+ refusing requests), until its `availableIn` passes. Low quota is information,
118
+ not a reason to steer away: `nearLimit` (under 20% left) is still usable, and
119
+ the owner often wants quota used up before it resets, so an account with quota
120
+ left that resets soon is a good pick; use it before it resets. For Claude, pass
121
+ the `account` id the row's `computers` list gives for the computer you pick. A
122
+ `stale` row's numbers may be out of date, and a window marked `reset` has
123
+ rolled over with no new number yet: say so rather than quoting them. Name the
124
+ choice in the dispatch line, such as "Desk has the parser checks on Codex,
125
+ using its last 15% before the week resets tomorrow." When every account is
126
+ exhausted, tell the owner before dispatching. The owner's explicit choice of
127
+ harness or account always wins. Usage on `unreachable` and `notLinked`
128
+ computers is unknown, not zero.
129
+
103
130
  Prefer handing work to a session that already owns the project and is idle or
104
131
  doing related work; call `hand_off` in full or `phren_admin(action: "hand_off",
105
132
  computer?, target|session, text)` in core. Otherwise dispatch a new worker.
@@ -117,7 +144,8 @@ owner's release authority policy first with `authority` in full or
117
144
  ask them, and never confirm or change the policy yourself. The policy only
118
145
  restricts; when a worker's own harness still refuses release work, only the
119
146
  owner's own harness settings can allow it.
120
- `anywhere` chooses the connected computer with the fewest working agents. Place
147
+ `anywhere` chooses the connected computer with the fewest working agents, and
148
+ skips one whose account for that harness is exhausted. Place
121
149
  briefs sequentially, respecting busy/rate-limit responses. Keep their dispatch
122
150
  IDs. Do not send local filesystem paths as remote project names.
123
151
 
@@ -144,6 +172,10 @@ permission prompt: say so and point the owner to the phone or the terminal. A
144
172
  owner before giving its work to another agent. A `done` reply is the worker's
145
173
  own account; check its evidence before saying tests passed or work merged.
146
174
 
175
+ A `stalled` return or `live_sessions` row with `stalled:true` means both the
176
+ screen and transcript have stopped changing while working. Check it and report
177
+ what is known; do not launch a duplicate or interrupt it just because of the flag.
178
+
147
179
  An uncertain delivery is never retried automatically. Inspect its known target
148
180
  or status before deciding with the owner whether a replacement is needed. Keep
149
181
  unavailable workers visible instead of giving their work to another agent