@phren/cli 0.3.12 → 0.3.13
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.
- package/dist/bridge/account-usage.d.ts +124 -0
- package/dist/bridge/account-usage.js +258 -0
- package/dist/bridge/agent-hooks.d.ts +3 -0
- package/dist/bridge/agent-hooks.js +20 -1
- package/dist/bridge/codex-hook-trust.d.ts +27 -0
- package/dist/bridge/codex-hook-trust.js +237 -0
- package/dist/bridge/command.js +3 -0
- package/dist/bridge/dispatch-command.js +9 -3
- package/dist/bridge/dispatch-returns.d.ts +5 -0
- package/dist/bridge/dispatch-returns.js +16 -6
- package/dist/bridge/dispatch.d.ts +25 -1
- package/dist/bridge/dispatch.js +35 -6
- package/dist/bridge/hand-off-queue.d.ts +74 -0
- package/dist/bridge/hand-off-queue.js +235 -0
- package/dist/bridge/hand-off.d.ts +12 -4
- package/dist/bridge/hand-off.js +27 -7
- package/dist/bridge/install.js +16 -2
- package/dist/bridge/pane-status.d.ts +12 -0
- package/dist/bridge/pane-status.js +50 -1
- package/dist/bridge/push.d.ts +6 -0
- package/dist/bridge/push.js +21 -0
- package/dist/bridge/schedule-launch.d.ts +1 -1
- package/dist/bridge/schedule-launch.js +5 -1
- package/dist/bridge/schedule-watch.d.ts +15 -1
- package/dist/bridge/schedule-watch.js +45 -10
- package/dist/bridge/server-launch.js +14 -4
- package/dist/bridge/server-overview.d.ts +8 -1
- package/dist/bridge/server-overview.js +12 -3
- package/dist/bridge/server-pane-routes.d.ts +1 -0
- package/dist/bridge/server-pane-routes.js +9 -7
- package/dist/bridge/server-routes.d.ts +4 -0
- package/dist/bridge/server-routes.js +57 -7
- package/dist/bridge/server.js +15 -2
- package/dist/bridge/session-activity.d.ts +24 -12
- package/dist/bridge/session-activity.js +36 -14
- package/dist/bridge/stalls.d.ts +22 -0
- package/dist/bridge/stalls.js +57 -0
- package/dist/bridge/sudo.d.ts +209 -0
- package/dist/bridge/sudo.js +501 -0
- package/dist/bridge/terminal-tmux.d.ts +12 -0
- package/dist/bridge/terminal-tmux.js +79 -4
- package/dist/bridge/transcript-claude.d.ts +4 -0
- package/dist/bridge/transcript-claude.js +131 -6
- package/dist/bridge/usage.d.ts +17 -0
- package/dist/bridge/usage.js +37 -3
- package/dist/bridge-hook.mjs +19448 -18102
- package/dist/cli-registry.js +7 -1
- package/dist/modules/registry.js +8 -8
- package/dist/tools/dispatch.js +17 -2
- package/package.json +1 -1
- package/starter/global/AGENTS.md +4 -0
- package/starter/global/skills/conductor/SKILL.md +34 -2
package/dist/cli-registry.js
CHANGED
|
@@ -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",
|
package/dist/modules/registry.js
CHANGED
|
@@ -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"],
|
package/dist/tools/dispatch.js
CHANGED
|
@@ -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.
|
|
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
package/starter/global/AGENTS.md
CHANGED
|
@@ -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
|
|
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
|