@phren/cli 0.2.15 → 0.3.0
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/README.md +2 -2
- package/dist/agent-instructions.d.ts +12 -0
- package/dist/agent-instructions.js +52 -0
- package/dist/bridge/agent-hook-stores.d.ts +32 -0
- package/dist/bridge/agent-hook-stores.js +67 -0
- package/dist/bridge/agent-hooks.d.ts +195 -2
- package/dist/bridge/agent-hooks.js +1049 -38
- package/dist/bridge/canary.d.ts +27 -0
- package/dist/bridge/canary.js +189 -0
- package/dist/bridge/changes.d.ts +57 -0
- package/dist/bridge/changes.js +403 -0
- package/dist/bridge/client.d.ts +3 -0
- package/dist/bridge/client.js +36 -0
- package/dist/bridge/code-note.d.ts +23 -0
- package/dist/bridge/code-note.js +51 -0
- package/dist/bridge/code-routes.d.ts +151 -0
- package/dist/bridge/code-routes.js +442 -0
- package/dist/bridge/codex-threads.d.ts +27 -0
- package/dist/bridge/codex-threads.js +442 -0
- package/dist/bridge/command.d.ts +7 -0
- package/dist/bridge/command.js +50 -5
- package/dist/bridge/computer-names.d.ts +4 -0
- package/dist/bridge/computer-names.js +16 -0
- package/dist/bridge/computers.d.ts +9 -0
- package/dist/bridge/computers.js +111 -0
- package/dist/bridge/context.d.ts +14 -0
- package/dist/bridge/context.js +149 -0
- package/dist/bridge/dispatch-command.d.ts +3 -0
- package/dist/bridge/dispatch-command.js +93 -0
- package/dist/bridge/dispatch-hosts.d.ts +23 -0
- package/dist/bridge/dispatch-hosts.js +25 -0
- package/dist/bridge/dispatch-returns.d.ts +125 -0
- package/dist/bridge/dispatch-returns.js +283 -0
- package/dist/bridge/dispatch-tree.d.ts +54 -0
- package/dist/bridge/dispatch-tree.js +198 -0
- package/dist/bridge/dispatch.d.ts +210 -0
- package/dist/bridge/dispatch.js +286 -0
- package/dist/bridge/enroll.d.ts +31 -0
- package/dist/bridge/enroll.js +236 -0
- package/dist/bridge/fanout-messages.d.ts +74 -0
- package/dist/bridge/fanout-messages.js +230 -0
- package/dist/bridge/fanouts.d.ts +160 -0
- package/dist/bridge/fanouts.js +702 -0
- package/dist/bridge/file-range.d.ts +16 -0
- package/dist/bridge/file-range.js +90 -0
- package/dist/bridge/files.d.ts +20 -0
- package/dist/bridge/files.js +54 -0
- package/dist/bridge/git-publish.d.ts +23 -0
- package/dist/bridge/git-publish.js +145 -0
- package/dist/bridge/git-worktrees.d.ts +21 -0
- package/dist/bridge/git-worktrees.js +150 -0
- package/dist/bridge/git.d.ts +54 -0
- package/dist/bridge/git.js +552 -0
- package/dist/bridge/grants.d.ts +31 -0
- package/dist/bridge/grants.js +181 -0
- package/dist/bridge/hand-off.d.ts +79 -0
- package/dist/bridge/hand-off.js +151 -0
- package/dist/bridge/health.d.ts +128 -0
- package/dist/bridge/health.js +260 -0
- package/dist/bridge/herdr.d.ts +79 -6
- package/dist/bridge/herdr.js +292 -27
- package/dist/bridge/hook-main.js +2 -0
- package/dist/bridge/install.d.ts +28 -1
- package/dist/bridge/install.js +225 -38
- package/dist/bridge/launch-worktree.d.ts +21 -0
- package/dist/bridge/launch-worktree.js +70 -0
- package/dist/bridge/limits.d.ts +20 -0
- package/dist/bridge/limits.js +65 -0
- package/dist/bridge/locate.d.ts +16 -0
- package/dist/bridge/locate.js +75 -0
- package/dist/bridge/metrics.d.ts +29 -0
- package/dist/bridge/metrics.js +71 -0
- package/dist/bridge/model-switch.d.ts +35 -0
- package/dist/bridge/model-switch.js +250 -0
- package/dist/bridge/models.d.ts +46 -0
- package/dist/bridge/models.js +257 -0
- package/dist/bridge/opencode-approvals.d.ts +6 -0
- package/dist/bridge/opencode-approvals.js +60 -0
- package/dist/bridge/pane-text.d.ts +15 -0
- package/dist/bridge/pane-text.js +23 -0
- package/dist/bridge/peers.d.ts +27 -0
- package/dist/bridge/peers.js +130 -0
- package/dist/bridge/projects.d.ts +12 -1
- package/dist/bridge/projects.js +268 -20
- package/dist/bridge/protocol.d.ts +35 -2
- package/dist/bridge/protocol.js +61 -7
- package/dist/bridge/push.d.ts +83 -0
- package/dist/bridge/push.js +199 -0
- package/dist/bridge/questions.d.ts +38 -0
- package/dist/bridge/questions.js +205 -0
- package/dist/bridge/schedule-format.d.ts +103 -0
- package/dist/bridge/schedule-format.js +266 -0
- package/dist/bridge/schedule-launch.d.ts +11 -0
- package/dist/bridge/schedule-launch.js +169 -0
- package/dist/bridge/schedule-watch.d.ts +54 -0
- package/dist/bridge/schedule-watch.js +255 -0
- package/dist/bridge/schedules.d.ts +48 -0
- package/dist/bridge/schedules.js +205 -0
- package/dist/bridge/server-launch.d.ts +14 -0
- package/dist/bridge/server-launch.js +218 -0
- package/dist/bridge/server-overview.d.ts +45 -0
- package/dist/bridge/server-overview.js +102 -0
- package/dist/bridge/server-pane-routes.d.ts +36 -0
- package/dist/bridge/server-pane-routes.js +479 -0
- package/dist/bridge/server-routes.d.ts +108 -0
- package/dist/bridge/server-routes.js +556 -0
- package/dist/bridge/server-stream.d.ts +46 -0
- package/dist/bridge/server-stream.js +253 -0
- package/dist/bridge/server.d.ts +3 -15
- package/dist/bridge/server.js +162 -264
- package/dist/bridge/session-servers.d.ts +24 -0
- package/dist/bridge/session-servers.js +136 -0
- package/dist/bridge/side-questions.d.ts +74 -0
- package/dist/bridge/side-questions.js +252 -0
- package/dist/bridge/simulators.d.ts +28 -0
- package/dist/bridge/simulators.js +198 -0
- package/dist/bridge/speech-transcribe.d.ts +24 -0
- package/dist/bridge/speech-transcribe.js +124 -0
- package/dist/bridge/speech.d.ts +35 -0
- package/dist/bridge/speech.js +98 -0
- package/dist/bridge/steps.d.ts +13 -0
- package/dist/bridge/steps.js +222 -0
- package/dist/bridge/tab-activity.d.ts +18 -0
- package/dist/bridge/tab-activity.js +99 -0
- package/dist/bridge/terminal-choice.d.ts +64 -0
- package/dist/bridge/terminal-choice.js +281 -0
- package/dist/bridge/transcript-claude.d.ts +22 -0
- package/dist/bridge/transcript-claude.js +353 -0
- package/dist/bridge/transcript-codex.d.ts +30 -0
- package/dist/bridge/transcript-codex.js +282 -0
- package/dist/bridge/transcript-copilot.d.ts +4 -0
- package/dist/bridge/transcript-copilot.js +14 -0
- package/dist/bridge/transcript-opencode.d.ts +5 -0
- package/dist/bridge/transcript-opencode.js +26 -0
- package/dist/bridge/transcript-preview.d.ts +96 -0
- package/dist/bridge/transcript-preview.js +491 -0
- package/dist/bridge/transcripts.d.ts +81 -4
- package/dist/bridge/transcripts.js +332 -67
- package/dist/bridge/transport.d.ts +3 -0
- package/dist/bridge/transport.js +96 -15
- package/dist/bridge/uploads.d.ts +15 -0
- package/dist/bridge/uploads.js +44 -2
- package/dist/bridge/usage.d.ts +124 -0
- package/dist/bridge/usage.js +859 -0
- package/dist/bridge-hook.mjs +46545 -21051
- package/dist/cli/actions.js +14 -1
- package/dist/cli/config-policy.js +25 -0
- package/dist/cli/config-proactivity.d.ts +3 -1
- package/dist/cli/config-proactivity.js +35 -3
- package/dist/cli/config.js +4 -1
- package/dist/cli/extract.d.ts +0 -8
- package/dist/cli/extract.js +4 -7
- package/dist/cli/govern.js +5 -2
- package/dist/cli/hooks-globs.js +1 -1
- package/dist/cli/hooks.d.ts +1 -1
- package/dist/cli/hooks.js +9 -7
- package/dist/cli/namespaces-projects.js +12 -6
- package/dist/cli/namespaces-store.js +37 -6
- package/dist/cli/namespaces-tasks.js +1 -1
- package/dist/cli/schedules.d.ts +1 -0
- package/dist/cli/schedules.js +164 -0
- package/dist/cli/session-background.js +1 -1
- package/dist/cli/session-git.d.ts +8 -5
- package/dist/cli/session-git.js +45 -120
- package/dist/cli/session-start.js +3 -1
- package/dist/cli/session-stop.js +19 -8
- package/dist/cli/team.js +13 -10
- package/dist/cli-handlers.d.ts +1 -1
- package/dist/cli-handlers.js +8 -4
- package/dist/cli-help.d.ts +5 -4
- package/dist/cli-help.js +15 -15
- package/dist/cli-registry.d.ts +4 -1
- package/dist/cli-registry.js +119 -6
- package/dist/content/archive.js +2 -2
- package/dist/content/citation.d.ts +11 -0
- package/dist/content/citation.js +18 -0
- package/dist/content/learning.js +2 -0
- package/dist/content/summarize.d.ts +14 -15
- package/dist/content/summarize.js +60 -5
- package/dist/content/validate.d.ts +17 -4
- package/dist/content/validate.js +200 -122
- package/dist/core/project-registry.d.ts +26 -0
- package/dist/core/project-registry.js +573 -0
- package/dist/core/project.js +2 -3
- package/dist/data/access.d.ts +16 -1
- package/dist/data/access.js +31 -3
- package/dist/data/tasks.d.ts +18 -3
- package/dist/data/tasks.js +8 -7
- package/dist/entrypoint.js +44 -10
- package/dist/fanout/adapters/claude.d.ts +2 -0
- package/dist/fanout/adapters/claude.js +7 -0
- package/dist/fanout/adapters/codex.d.ts +2 -0
- package/dist/fanout/adapters/codex.js +9 -0
- package/dist/fanout/adapters/opencode.d.ts +4 -0
- package/dist/fanout/adapters/opencode.js +9 -0
- package/dist/fanout/adapters/types.d.ts +21 -0
- package/dist/fanout/adapters/types.js +3 -0
- package/dist/fanout/command.d.ts +2 -0
- package/dist/fanout/command.js +78 -0
- package/dist/fanout/launcher.d.ts +27 -0
- package/dist/fanout/launcher.js +156 -0
- package/dist/fanout/opencode-serve.d.ts +24 -0
- package/dist/fanout/opencode-serve.js +191 -0
- package/dist/fanout/picker.d.ts +91 -0
- package/dist/fanout/picker.js +51 -0
- package/dist/fanout/usage.d.ts +5 -0
- package/dist/fanout/usage.js +51 -0
- package/dist/fanout/watchdog.d.ts +10 -0
- package/dist/fanout/watchdog.js +27 -0
- package/dist/filenames.d.ts +9 -0
- package/dist/filenames.js +11 -0
- package/dist/finding/context.js +4 -22
- package/dist/generated/memory-ui-graph.browser.js +525 -419
- package/dist/governance/policy-constants.d.ts +11 -0
- package/dist/governance/policy-constants.js +9 -0
- package/dist/governance/policy.d.ts +5 -8
- package/dist/governance/policy.js +11 -8
- package/dist/graph-core/camera.d.ts +24 -0
- package/dist/graph-core/camera.js +18 -0
- package/dist/graph-core/index.d.ts +2 -0
- package/dist/graph-core/index.js +2 -0
- package/dist/graph-core/labels.d.ts +77 -0
- package/dist/graph-core/labels.js +124 -0
- package/dist/graph-core/model.d.ts +13 -0
- package/dist/graph-core/model.js +33 -0
- package/dist/graph-core/types.d.ts +2 -0
- package/dist/home-paths.d.ts +7 -0
- package/dist/home-paths.js +21 -0
- package/dist/hooks.d.ts +3 -15
- package/dist/hooks.js +14 -1
- package/dist/index.js +24 -2
- package/dist/init/guard-globals.d.ts +1 -1
- package/dist/init/guard-globals.js +4 -4
- package/dist/init/init-configure.js +3 -3
- package/dist/init/init-uninstall.js +15 -5
- package/dist/init/init-walkthrough.js +1 -1
- package/dist/init/init.js +26 -6
- package/dist/init/management-preset.d.ts +1 -1
- package/dist/init/management-preset.js +2 -2
- package/dist/init/preferences.js +1 -1
- package/dist/init/self-wiring.js +1 -1
- package/dist/init/setup.d.ts +3 -26
- package/dist/init/setup.js +68 -593
- package/dist/init/shared.js +2 -0
- package/dist/init/store-gitignore.d.ts +1 -6
- package/dist/init/store-gitignore.js +2 -8
- package/dist/init/teardown.d.ts +1 -1
- package/dist/init/teardown.js +2 -2
- package/dist/link/context-imports.d.ts +15 -0
- package/dist/link/context-imports.js +101 -0
- package/dist/link/context.js +1 -1
- package/dist/link/doctor.d.ts +22 -1
- package/dist/link/doctor.js +128 -58
- package/dist/link/link.js +29 -61
- package/dist/link/refresh.js +2 -2
- package/dist/link/skills.js +26 -5
- package/dist/machine-identity.d.ts +3 -0
- package/dist/machine-identity.js +6 -0
- package/dist/mcp/profile.d.ts +2 -19
- package/dist/mcp/profile.js +64 -22
- package/dist/memory-ui-graph.runtime.js +525 -419
- package/dist/modules/code-package.d.ts +16 -0
- package/dist/modules/code-package.js +160 -0
- package/dist/modules/command.d.ts +2 -0
- package/dist/modules/command.js +67 -0
- package/dist/modules/config.d.ts +4 -0
- package/dist/modules/config.js +70 -0
- package/dist/modules/manifest.d.ts +41 -0
- package/dist/modules/manifest.js +1 -0
- package/dist/modules/provision.d.ts +3 -0
- package/dist/modules/provision.js +84 -0
- package/dist/modules/registry.d.ts +16 -0
- package/dist/modules/registry.js +250 -0
- package/dist/modules/runtime.d.ts +15 -0
- package/dist/modules/runtime.js +59 -0
- package/dist/package-metadata.js +10 -2
- package/dist/phren-dotenv.js +4 -2
- package/dist/phren-paths.d.ts +3 -2
- package/dist/phren-paths.js +4 -5
- package/dist/profile-store.js +43 -8
- package/dist/project-config.d.ts +19 -1
- package/dist/project-config.js +29 -3
- package/dist/project-topics.d.ts +1 -0
- package/dist/project-topics.js +13 -10
- package/dist/provider-adapters.js +1 -4
- package/dist/query-correlation.js +6 -6
- package/dist/session/artifacts.js +5 -5
- package/dist/session/checkpoints.js +5 -0
- package/dist/session/utils.d.ts +2 -2
- package/dist/session/utils.js +6 -6
- package/dist/shared/content.d.ts +1 -1
- package/dist/shared/content.js +1 -1
- package/dist/shared/data-utils.js +1 -1
- package/dist/shared/fragment-graph.d.ts +1 -1
- package/dist/shared/fragment-graph.js +5 -5
- package/dist/shared/index.js +48 -7
- package/dist/shared/retrieval.d.ts +18 -3
- package/dist/shared/retrieval.js +101 -12
- package/dist/shared/search-fallback.js +4 -6
- package/dist/shared/sqljs.d.ts +2 -0
- package/dist/shared/sqljs.js +4 -2
- package/dist/shared.d.ts +0 -1
- package/dist/shared.js +0 -1
- package/dist/shell/input.d.ts +1 -5
- package/dist/shell/input.js +16 -10
- package/dist/shell/palette.d.ts +2 -2
- package/dist/shell/palette.js +3 -7
- package/dist/shell/render.d.ts +3 -1
- package/dist/shell/render.js +4 -4
- package/dist/shell/shell.js +4 -1
- package/dist/shell/types.d.ts +1 -0
- package/dist/shell/types.js +4 -0
- package/dist/shell/view.d.ts +0 -4
- package/dist/shell/view.js +19 -27
- package/dist/skill/registry.js +25 -17
- package/dist/skill/state.d.ts +3 -0
- package/dist/skill/state.js +13 -7
- package/dist/status.js +38 -17
- package/dist/store-registry.d.ts +44 -18
- package/dist/store-registry.js +169 -60
- package/dist/store-weight.d.ts +1 -6
- package/dist/store-weight.js +4 -2
- package/dist/sync/auth-doctor.d.ts +8 -0
- package/dist/sync/auth-doctor.js +27 -0
- package/dist/sync/auth.d.ts +27 -0
- package/dist/sync/auth.js +114 -0
- package/dist/sync/conflict-resolve.d.ts +9 -0
- package/dist/sync/conflict-resolve.js +146 -0
- package/dist/sync/git-state.d.ts +4 -0
- package/dist/sync/git-state.js +49 -0
- package/dist/sync/outcome.d.ts +34 -0
- package/dist/sync/outcome.js +57 -0
- package/dist/sync/pull.d.ts +15 -7
- package/dist/sync/pull.js +84 -35
- package/dist/sync/store-merge.d.ts +29 -0
- package/dist/sync/store-merge.js +137 -0
- package/dist/sync/task-merge.d.ts +22 -0
- package/dist/sync/task-merge.js +158 -0
- package/dist/task/github.js +1 -1
- package/dist/task/lifecycle.d.ts +5 -0
- package/dist/task/lifecycle.js +67 -23
- package/dist/terminal-text.d.ts +5 -0
- package/dist/terminal-text.js +11 -0
- package/dist/test-global-setup.js +7 -0
- package/dist/tool-registry.d.ts +1 -1
- package/dist/tool-registry.js +3 -1
- package/dist/tools/code.d.ts +3 -0
- package/dist/tools/code.js +186 -0
- package/dist/tools/config.js +8 -0
- package/dist/tools/data.js +14 -7
- package/dist/tools/dispatch.d.ts +2 -0
- package/dist/tools/dispatch.js +66 -0
- package/dist/tools/finding.d.ts +11 -0
- package/dist/tools/finding.js +180 -123
- package/dist/tools/ops.js +5 -2
- package/dist/tools/search.js +21 -8
- package/dist/tools/session.js +21 -22
- package/dist/tools/tasks.js +8 -2
- package/dist/tools/types.d.ts +2 -2
- package/dist/tools/types.js +2 -2
- package/dist/ui/assets.js +1 -1
- package/dist/ui/data.js +14 -15
- package/dist/ui/deep-void.d.ts +1 -1
- package/dist/ui/deep-void.js +0 -1
- package/dist/ui/graph-chrome.d.ts +1 -1
- package/dist/ui/graph-chrome.js +51 -0
- package/dist/ui/page.js +5 -5
- package/dist/ui/scripts.js +67 -30
- package/dist/ui/server.js +52 -7
- package/dist/update.js +22 -11
- package/dist/utils-fts.js +1 -0
- package/dist/utils-helpers.d.ts +7 -0
- package/dist/utils-helpers.js +17 -0
- package/dist/utils.d.ts +1 -1
- package/dist/utils.js +1 -1
- package/package.json +49 -7
- package/plugins/opencode/phren-transcript.js +340 -0
- package/starter/README.md +4 -4
- package/starter/global/{CLAUDE.md → AGENTS.md} +2 -2
- package/starter/global/skills/conductor/SKILL.md +106 -0
- package/starter/global/skills/fanout/SKILL.md +20 -0
- package/starter/global/skills/phren-discover/SKILL.md +6 -6
- package/starter/global/skills/phren-init/SKILL.md +4 -4
- package/starter/global/skills/phren-sync/SKILL.md +3 -3
- package/starter/templates/frontend/reference/README.md +1 -1
- package/starter/templates/library/reference/README.md +1 -1
- package/starter/templates/monorepo/reference/README.md +1 -1
- package/starter/templates/python-project/reference/README.md +1 -1
- /package/starter/templates/frontend/{CLAUDE.md → AGENTS.md} +0 -0
- /package/starter/templates/library/{CLAUDE.md → AGENTS.md} +0 -0
- /package/starter/templates/monorepo/{CLAUDE.md → AGENTS.md} +0 -0
- /package/starter/templates/python-project/{CLAUDE.md → AGENTS.md} +0 -0
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
// Installed by Phren Hook and replaced on every update. Copy it under another name to customize.
|
|
2
|
+
import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
|
|
3
|
+
import { homedir } from "node:os";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
|
|
6
|
+
const PHREN_STORE = "__PHREN_STORE__";
|
|
7
|
+
const FLUSH_MS = 250;
|
|
8
|
+
const MAX_TOOL_OUTPUT = 200_000;
|
|
9
|
+
const STOP_REASONS = { stop: "end_turn", "tool-calls": "tool_use", length: "max_tokens" };
|
|
10
|
+
const OPENCODE_SESSION = /^ses_[0-9A-Za-z]{1,64}$/;
|
|
11
|
+
const APPROVAL_POLL_MS = 200;
|
|
12
|
+
const APPROVAL_DEADLINE_MS = 50_000;
|
|
13
|
+
|
|
14
|
+
function storeRoot() {
|
|
15
|
+
if (PHREN_STORE && !PHREN_STORE.startsWith("__")) return PHREN_STORE;
|
|
16
|
+
const configured = process.env.PHREN_PATH?.trim();
|
|
17
|
+
if (!configured) return path.join(homedir(), ".phren");
|
|
18
|
+
const expanded = configured === "~" ? homedir() : configured.startsWith("~/") ? path.join(homedir(), configured.slice(2)) : configured;
|
|
19
|
+
return path.resolve(expanded);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function text(value) {
|
|
23
|
+
return typeof value === "string" ? value : "";
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function approvalDirectory() {
|
|
27
|
+
return path.join(storeRoot(), ".runtime", "approvals");
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function fanoutDirectory() {
|
|
31
|
+
const configured = process.env.PHREN_FANOUT_DIR?.trim();
|
|
32
|
+
if (configured) return path.resolve(configured);
|
|
33
|
+
return path.join(storeRoot(), ".runtime", "agent-fanouts", text(process.env.PHREN_FANOUT_JOB));
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function fanoutPatterns(input) {
|
|
37
|
+
const value = input?.pattern;
|
|
38
|
+
if (Array.isArray(value)) return value.filter(entry => typeof entry === "string" && entry);
|
|
39
|
+
return typeof value === "string" && value ? [value] : [];
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** The worktree's grandparent is the scratch root the fan-out launcher owns:
|
|
43
|
+
* external reads and writes are allowed only inside it. */
|
|
44
|
+
function underScratchRoot(value) {
|
|
45
|
+
const scratch = path.dirname(path.dirname(path.resolve(process.cwd())));
|
|
46
|
+
if (scratch === path.parse(scratch).root) return false;
|
|
47
|
+
const resolved = path.resolve(scratch, value);
|
|
48
|
+
return resolved === scratch || resolved.startsWith(scratch + path.sep);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function under(parent, value) {
|
|
52
|
+
if (!parent || parent === path.parse(parent).root) return false;
|
|
53
|
+
const root = path.resolve(parent), resolved = path.resolve(root, value);
|
|
54
|
+
return resolved === root || resolved.startsWith(root + path.sep);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** Beyond the scratch root, a worker legitimately reads its own machine: the
|
|
58
|
+
* node_modules its worktree links into the main checkout, the store it was
|
|
59
|
+
* briefed from, the toolchains a build shells out to, and the temporary
|
|
60
|
+
* directories those builds write. Everything outside this set is refused. */
|
|
61
|
+
function fanoutReadable(value) {
|
|
62
|
+
if (underScratchRoot(value)) return true;
|
|
63
|
+
const home = process.env.HOME || "";
|
|
64
|
+
const roots = [home, storeRoot(), "/tmp", "/private/tmp", "/var/folders", "/private/var/folders",
|
|
65
|
+
"/Applications/Xcode.app", "/Library/Developer"];
|
|
66
|
+
return roots.some(root => under(root, value));
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** A headless fan-out worker may edit, run commands and fetch, and continue
|
|
70
|
+
* when OpenCode's own loop detector asks (the launcher's watchdog stops a real
|
|
71
|
+
* loop and says why, which is a clearer failure than a refused permission).
|
|
72
|
+
* Anything else is refused outright. */
|
|
73
|
+
function fanoutAllowed(input) {
|
|
74
|
+
const kind = text(input?.type);
|
|
75
|
+
if (kind === "edit" || kind === "bash" || kind === "webfetch" || kind === "doom_loop") return true;
|
|
76
|
+
if (kind !== "external_directory") return false;
|
|
77
|
+
const patterns = fanoutPatterns(input);
|
|
78
|
+
return patterns.length > 0 && patterns.every(fanoutReadable);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function writeBlocked(input) {
|
|
82
|
+
try {
|
|
83
|
+
const directory = fanoutDirectory();
|
|
84
|
+
mkdirSync(directory, { recursive: true });
|
|
85
|
+
writeJsonAtomic(path.join(directory, "blocked.json"), {
|
|
86
|
+
type: text(input?.type) || "action",
|
|
87
|
+
pattern: fanoutPatterns(input).join(", "),
|
|
88
|
+
message: permissionMessage(input),
|
|
89
|
+
at: new Date().toISOString(),
|
|
90
|
+
});
|
|
91
|
+
} catch {}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function approvalPaths(sessionID) {
|
|
95
|
+
const base = path.join(approvalDirectory(), `opencode-${sessionID}`);
|
|
96
|
+
return { request: `${base}.request.json`, answer: `${base}.answer.json` };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
function writeJsonAtomic(file, value) {
|
|
100
|
+
const staging = `${file}.${process.pid}.tmp`;
|
|
101
|
+
writeFileSync(staging, JSON.stringify(value), { mode: 0o600 });
|
|
102
|
+
renameSync(staging, file);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function removeFile(file) {
|
|
106
|
+
try { unlinkSync(file); } catch {}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
function sleep(ms) {
|
|
110
|
+
return new Promise(resolve => setTimeout(resolve, ms));
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
function setStatus(output, status) {
|
|
114
|
+
if (output && typeof output === "object") output.status = status;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
function permissionMessage(input) {
|
|
118
|
+
const type = text(input?.type) || "action";
|
|
119
|
+
const pattern = Array.isArray(input?.pattern)
|
|
120
|
+
? input.pattern.filter(value => typeof value === "string").join(", ")
|
|
121
|
+
: text(input?.pattern);
|
|
122
|
+
const metadata = input?.metadata && typeof input.metadata === "object" ? input.metadata : {};
|
|
123
|
+
const detail = [pattern, text(metadata.command), text(metadata.description), text(metadata.path), text(metadata.url)].find(value => value);
|
|
124
|
+
return (detail ? `${type}: ${detail}` : `opencode asks to use ${type}.`).slice(0, 2000);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
function toolOutput(state) {
|
|
128
|
+
if (!state || typeof state !== "object") return "";
|
|
129
|
+
const output = state.output ?? state.metadata?.output ?? state.result ?? "";
|
|
130
|
+
const value = typeof output === "string" ? output : JSON.stringify(output ?? "");
|
|
131
|
+
return value.length > MAX_TOOL_OUTPUT ? value.slice(0, MAX_TOOL_OUTPUT) : value;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
function blocksFor(message) {
|
|
135
|
+
const blocks = [];
|
|
136
|
+
for (const id of message.partOrder) {
|
|
137
|
+
const part = message.parts.get(id);
|
|
138
|
+
if (!part || typeof part !== "object") continue;
|
|
139
|
+
if (part.type === "text" && typeof part.text === "string" && part.text.length) {
|
|
140
|
+
blocks.push({ type: "text", text: part.text });
|
|
141
|
+
} else if (part.type === "tool" && typeof part.callID === "string") {
|
|
142
|
+
blocks.push({ type: "tool_use", id: part.callID, name: text(part.tool) || "tool", input: part.state?.input ?? {} });
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
return blocks;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function toolResults(message) {
|
|
149
|
+
const results = [];
|
|
150
|
+
for (const id of message.partOrder) {
|
|
151
|
+
const part = message.parts.get(id);
|
|
152
|
+
if (!part || part.type !== "tool" || typeof part.callID !== "string") continue;
|
|
153
|
+
const status = part.state?.status;
|
|
154
|
+
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" });
|
|
156
|
+
}
|
|
157
|
+
return results;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
function linesFor(session) {
|
|
161
|
+
const messages = session.order
|
|
162
|
+
.map(id => session.messages.get(id))
|
|
163
|
+
.filter(Boolean)
|
|
164
|
+
.sort((a, b) => (a.info?.time?.created ?? 0) - (b.info?.time?.created ?? 0) || String(a.info?.id).localeCompare(String(b.info?.id)));
|
|
165
|
+
const lines = [];
|
|
166
|
+
let seq = 0;
|
|
167
|
+
const emit = (type, data, created) => {
|
|
168
|
+
lines.push(JSON.stringify({ seq: seq++, time: new Date(created || Date.now()).toISOString(), type, data }));
|
|
169
|
+
};
|
|
170
|
+
for (const message of messages) {
|
|
171
|
+
const info = message.info ?? {};
|
|
172
|
+
if (info.role === "user") {
|
|
173
|
+
const blocks = blocksFor(message);
|
|
174
|
+
if (blocks.length) emit("user/message", { source: "user", message: { role: "user", content: blocks } }, info.time?.created);
|
|
175
|
+
} else if (info.role === "assistant") {
|
|
176
|
+
const complete = Boolean(info.time?.completed || info.finish);
|
|
177
|
+
const blocks = blocksFor(message).filter(block => complete || block.type !== "text");
|
|
178
|
+
const data = { stop_reason: STOP_REASONS[info.finish] || info.finish || "end_turn", message: { role: "assistant", content: blocks } };
|
|
179
|
+
if (info.tokens && (typeof info.tokens.input === "number" || typeof info.tokens.output === "number")) {
|
|
180
|
+
data.usage = { input_tokens: info.tokens.input ?? 0, output_tokens: info.tokens.output ?? 0 };
|
|
181
|
+
}
|
|
182
|
+
if (blocks.length) emit("assistant/message", data, info.time?.created);
|
|
183
|
+
const results = toolResults(message);
|
|
184
|
+
if (results.length) emit("tool/results", { message: { role: "user", content: results } }, info.time?.updated ?? info.time?.created);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
return lines;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
export const PhrenTranscriptPlugin = async () => {
|
|
191
|
+
const sessions = new Map();
|
|
192
|
+
const timers = new Map();
|
|
193
|
+
const written = new Map();
|
|
194
|
+
const pendingApprovals = new Set();
|
|
195
|
+
|
|
196
|
+
const sessionState = sessionID => {
|
|
197
|
+
let state = sessions.get(sessionID);
|
|
198
|
+
if (!state) { state = { messages: new Map(), order: [], idle: false }; sessions.set(sessionID, state); }
|
|
199
|
+
return state;
|
|
200
|
+
};
|
|
201
|
+
|
|
202
|
+
const messageState = (sessionID, messageID) => {
|
|
203
|
+
const state = sessionState(sessionID);
|
|
204
|
+
let message = state.messages.get(messageID);
|
|
205
|
+
if (!message) { message = { info: { id: messageID }, parts: new Map(), partOrder: [] }; state.messages.set(messageID, message); state.order.push(messageID); }
|
|
206
|
+
return message;
|
|
207
|
+
};
|
|
208
|
+
|
|
209
|
+
const flush = sessionID => {
|
|
210
|
+
const state = sessions.get(sessionID);
|
|
211
|
+
if (!state) return;
|
|
212
|
+
const body = linesFor(state);
|
|
213
|
+
const content = body.length ? body.join("\n") + "\n" : "";
|
|
214
|
+
const directory = path.join(storeRoot(), ".runtime", "sessions");
|
|
215
|
+
mkdirSync(directory, { recursive: true });
|
|
216
|
+
const file = path.join(directory, `opencode-${sessionID}.events.jsonl`);
|
|
217
|
+
const messages = state.order.map(id => state.messages.get(id));
|
|
218
|
+
const latest = messages.at(-1), info = latest?.info;
|
|
219
|
+
const user = messages.findLast(message => message.info?.role === "user");
|
|
220
|
+
const preview = !state.idle && info?.role === "assistant" && !info.time?.completed && !info.finish
|
|
221
|
+
? blocksFor(latest).filter(block => block.type === "text").map(block => block.text).join("\n").slice(0, 32_768) : "";
|
|
222
|
+
if (preview && user?.info.time?.created) writeJsonAtomic(file + ".preview.json", {
|
|
223
|
+
turnStartedAt: new Date(user.info.time.created).toISOString(), text: preview,
|
|
224
|
+
});
|
|
225
|
+
else removeFile(file + ".preview.json");
|
|
226
|
+
if (written.get(sessionID) === content) return;
|
|
227
|
+
const staging = `${file}.${process.pid}.tmp`;
|
|
228
|
+
writeFileSync(staging, content, { mode: 0o600 });
|
|
229
|
+
renameSync(staging, file);
|
|
230
|
+
written.set(sessionID, content);
|
|
231
|
+
};
|
|
232
|
+
|
|
233
|
+
const schedule = sessionID => {
|
|
234
|
+
if (!sessionID || timers.has(sessionID)) return;
|
|
235
|
+
timers.set(sessionID, setTimeout(() => {
|
|
236
|
+
timers.delete(sessionID);
|
|
237
|
+
try { flush(sessionID); } catch {}
|
|
238
|
+
}, FLUSH_MS));
|
|
239
|
+
};
|
|
240
|
+
|
|
241
|
+
const rememberInfo = (sessionID, info) => {
|
|
242
|
+
if (!info || typeof info.id !== "string") return;
|
|
243
|
+
const message = messageState(sessionID, info.id);
|
|
244
|
+
message.info = { ...message.info, ...info };
|
|
245
|
+
if (info.role === "user") sessionState(sessionID).idle = false;
|
|
246
|
+
schedule(sessionID);
|
|
247
|
+
};
|
|
248
|
+
|
|
249
|
+
const rememberPart = (sessionID, messageID, part) => {
|
|
250
|
+
if (!part || typeof part.id !== "string" || typeof messageID !== "string") return;
|
|
251
|
+
const message = messageState(sessionID, messageID);
|
|
252
|
+
if (!message.parts.has(part.id)) message.partOrder.push(part.id);
|
|
253
|
+
message.parts.set(part.id, part);
|
|
254
|
+
schedule(sessionID);
|
|
255
|
+
};
|
|
256
|
+
|
|
257
|
+
return {
|
|
258
|
+
"chat.message": async (input, output) => {
|
|
259
|
+
if (!OPENCODE_SESSION.test(text(input?.sessionID)) || !output?.message) return;
|
|
260
|
+
rememberInfo(input.sessionID, output.message);
|
|
261
|
+
for (const part of output.parts ?? []) rememberPart(input.sessionID, output.message.id, part);
|
|
262
|
+
},
|
|
263
|
+
"permission.ask": async (input, output) => {
|
|
264
|
+
// A fan-out worker runs headless in its own worktree with nobody watching
|
|
265
|
+
// the phone's approval queue, so edits, commands and fetches inside that
|
|
266
|
+
// worktree are granted here and anything else is refused outright rather
|
|
267
|
+
// than waiting 50 seconds for an answer that never comes.
|
|
268
|
+
if (process.env.PHREN_FANOUT_JOB) {
|
|
269
|
+
if (fanoutAllowed(input)) { setStatus(output, "allow"); return; }
|
|
270
|
+
// A worker the launcher drives through `opencode serve` relays the
|
|
271
|
+
// ask to the phone and resumes on the owner's answer.
|
|
272
|
+
if (process.env.PHREN_FANOUT_APPROVALS === "1") { setStatus(output, "ask"); return; }
|
|
273
|
+
setStatus(output, "deny");
|
|
274
|
+
// A denied permission aborts the turn; record what was refused so the
|
|
275
|
+
// Hook can report the worker as blocked rather than finished.
|
|
276
|
+
writeBlocked(input);
|
|
277
|
+
return;
|
|
278
|
+
}
|
|
279
|
+
let request, answer, pendingSession;
|
|
280
|
+
try {
|
|
281
|
+
const sessionID = text(input?.sessionID), id = text(input?.id);
|
|
282
|
+
if (!OPENCODE_SESSION.test(sessionID) || !id) { setStatus(output, "ask"); return; }
|
|
283
|
+
// A second request for this session belongs in the terminal until
|
|
284
|
+
// the existing phone request has finished.
|
|
285
|
+
if (pendingApprovals.has(sessionID)) { setStatus(output, "ask"); return; }
|
|
286
|
+
pendingApprovals.add(sessionID);
|
|
287
|
+
pendingSession = sessionID;
|
|
288
|
+
const paths = approvalPaths(sessionID);
|
|
289
|
+
request = paths.request; answer = paths.answer;
|
|
290
|
+
mkdirSync(approvalDirectory(), { recursive: true });
|
|
291
|
+
removeFile(answer);
|
|
292
|
+
const created = Date.now();
|
|
293
|
+
writeJsonAtomic(request, { id, sessionID, type: text(input.type) || "action",
|
|
294
|
+
title: text(input.title) || `Allow ${text(input.type) || "action"}?`, message: permissionMessage(input),
|
|
295
|
+
createdAt: new Date(created).toISOString(), expiresAt: new Date(created + APPROVAL_DEADLINE_MS).toISOString() });
|
|
296
|
+
const deadline = created + APPROVAL_DEADLINE_MS;
|
|
297
|
+
let decision;
|
|
298
|
+
while (Date.now() < deadline) {
|
|
299
|
+
await sleep(APPROVAL_POLL_MS);
|
|
300
|
+
try {
|
|
301
|
+
const info = lstatSync(answer);
|
|
302
|
+
if (!info.isFile() || info.size > 65_536) continue;
|
|
303
|
+
const value = JSON.parse(readFileSync(answer, "utf8"));
|
|
304
|
+
if (value && value.id === id) { decision = value.decision; break; }
|
|
305
|
+
} catch {}
|
|
306
|
+
}
|
|
307
|
+
setStatus(output, decision === "approve" ? "allow" : decision === "deny" ? "deny" : "ask");
|
|
308
|
+
} catch {
|
|
309
|
+
setStatus(output, "ask");
|
|
310
|
+
} finally {
|
|
311
|
+
if (answer) removeFile(answer);
|
|
312
|
+
if (request) removeFile(request);
|
|
313
|
+
if (pendingSession) pendingApprovals.delete(pendingSession);
|
|
314
|
+
}
|
|
315
|
+
},
|
|
316
|
+
event: async ({ event }) => {
|
|
317
|
+
const properties = event?.properties ?? {};
|
|
318
|
+
const sessionID = typeof properties.sessionID === "string" ? properties.sessionID : properties.info?.sessionID ?? properties.part?.sessionID;
|
|
319
|
+
if (!OPENCODE_SESSION.test(text(sessionID))) return;
|
|
320
|
+
if (event.type === "message.updated") rememberInfo(sessionID, properties.info);
|
|
321
|
+
else if (event.type === "message.part.updated") rememberPart(sessionID, properties.part?.messageID, properties.part);
|
|
322
|
+
else if (event.type === "message.part.delta" && properties.field === "text" && typeof properties.delta === "string") {
|
|
323
|
+
const message = messageState(sessionID, properties.messageID);
|
|
324
|
+
const part = message.parts.get(properties.partID);
|
|
325
|
+
if (part?.type === "text") rememberPart(sessionID, properties.messageID, { ...part, text: text(part.text) + properties.delta });
|
|
326
|
+
}
|
|
327
|
+
else if (event.type === "message.removed") {
|
|
328
|
+
const state = sessions.get(sessionID);
|
|
329
|
+
if (state && typeof properties.messageID === "string") {
|
|
330
|
+
state.messages.delete(properties.messageID);
|
|
331
|
+
state.order = state.order.filter(id => id !== properties.messageID);
|
|
332
|
+
schedule(sessionID);
|
|
333
|
+
}
|
|
334
|
+
} else if (event.type === "session.idle" || event.type === "session.error") {
|
|
335
|
+
sessionState(sessionID).idle = true;
|
|
336
|
+
flush(sessionID);
|
|
337
|
+
} else if (event.type === "session.status" && properties.status?.type === "busy") sessionState(sessionID).idle = false;
|
|
338
|
+
},
|
|
339
|
+
};
|
|
340
|
+
};
|
package/starter/README.md
CHANGED
|
@@ -9,10 +9,10 @@ Each subdirectory is a project. Add one for every codebase you work on.
|
|
|
9
9
|
```
|
|
10
10
|
~/.phren/
|
|
11
11
|
├── global/ # context that applies to every project
|
|
12
|
-
│ ├──
|
|
12
|
+
│ ├── AGENTS.md
|
|
13
13
|
│ └── skills/ # personal workflow skills
|
|
14
14
|
├── my-project/
|
|
15
|
-
│ ├──
|
|
15
|
+
│ ├── AGENTS.md # architecture, commands, key patterns
|
|
16
16
|
│ ├── summary.md # five-line project card
|
|
17
17
|
│ ├── FINDINGS.md # fragments accumulated over time
|
|
18
18
|
│ ├── tasks.md # task queue that persists across sessions
|
|
@@ -28,13 +28,13 @@ New to phren? Here's what each file does and when it matters.
|
|
|
28
28
|
|
|
29
29
|
**summary.md** is the elevator pitch. Phren shows this to Claude first so it knows what project it's working on. Keep it to 5 lines: what, stack, status, run command, biggest insight.
|
|
30
30
|
|
|
31
|
-
**
|
|
31
|
+
**AGENTS.md** is the project bible. Commands, architecture, key patterns, things to never do. Claude reads this before making changes. The better this file is, the fewer mistakes Claude makes.
|
|
32
32
|
|
|
33
33
|
**FINDINGS.md** fills itself. As Claude discovers insights, patterns, and decisions during your sessions, it tells phren and entries land here grouped by date. Old entries fade from retrieval over time. Wrong entries can be removed with `remove_finding()`.
|
|
34
34
|
|
|
35
35
|
**tasks.md** is your task board file. It keeps Active (working now), Queue (up next), and Done (finished) in one place so the work history stays with the project. You can also manage it from `phren shell`.
|
|
36
36
|
|
|
37
|
-
**global/
|
|
37
|
+
**global/AGENTS.md** applies everywhere. Your style preferences, tool choices, things Claude should always know regardless of which project you're in.
|
|
38
38
|
|
|
39
39
|
**profiles/** and **machines.yaml** handle multi-machine setups. Map hostnames to profiles, and profiles to project lists. Your work laptop sees work projects, your home machine sees personal ones.
|
|
40
40
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Instructions for the agent
|
|
2
2
|
|
|
3
|
-
<!-- phren copies this to ~/.phren/global/
|
|
3
|
+
<!-- phren copies this to ~/.phren/global/AGENTS.md and links it as ~/.claude/CLAUDE.md. Every session reads it, so keep it short and addressed to the agent. Fill in "How I work"; leave the rest. -->
|
|
4
4
|
|
|
5
5
|
## Memory lives in phren
|
|
6
6
|
|
|
@@ -32,4 +32,4 @@ Every agent follows these rules, and tells phren about non-obvious findings befo
|
|
|
32
32
|
|
|
33
33
|
## Where things are
|
|
34
34
|
|
|
35
|
-
`~/.phren` (or `$PHREN_PATH`) is a git repo: `global/` for everything-everywhere, `<project>/` for each project's
|
|
35
|
+
`~/.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.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: conductor
|
|
3
|
+
description: Coordinate independent Phren tasks across every project in the store and every enrolled computer, supervise their local agent fanout, and integrate verified returns in a concise dispatcher voice.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Conductor
|
|
7
|
+
|
|
8
|
+
You are the owner's dispatcher for the whole store, not one project. You start
|
|
9
|
+
in the phren store itself; that folder is not a project and not your work.
|
|
10
|
+
|
|
11
|
+
First, before trusting your tools, check which phren you are running:
|
|
12
|
+
`phren --version` and `command -v phren`. If the version is older than the one
|
|
13
|
+
the store or the owner expects, or the path is not the install you expect (a
|
|
14
|
+
stale global package, an old checkout), tell the owner in one line and say
|
|
15
|
+
which tools may be missing or behave differently.
|
|
16
|
+
|
|
17
|
+
Then read the relevant projects' summaries and Phren tasks
|
|
18
|
+
(`get_project_summary`, `get_tasks`) before selecting work.
|
|
19
|
+
|
|
20
|
+
Your tools, use these instead of exploring the CLI or the Hook's files:
|
|
21
|
+
|
|
22
|
+
- `live_sessions` (CLI `phren dispatch sessions`): every live agent on this
|
|
23
|
+
computer and each enrolled one, with project, harness, status, `idleFor`
|
|
24
|
+
(seconds since it last changed) and the target `hand_off` takes. Start here
|
|
25
|
+
when asked what is running. Computers it could not reach are listed; say so
|
|
26
|
+
rather than guessing. Computers in `notLinked` are registered in the store
|
|
27
|
+
but have no Hook link here: say they were not checked, never that nothing is
|
|
28
|
+
running there.
|
|
29
|
+
- `hand_off`: send a prompt to one of those sessions.
|
|
30
|
+
- `dispatch`: start a new worker on a computer (or `anywhere`).
|
|
31
|
+
- `dispatch_returns` (CLI `phren dispatch returns`): what your workers sent
|
|
32
|
+
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
|
|
34
|
+
`phren_admin(action: "dispatch_returns")`.
|
|
35
|
+
- `phren dispatch status`: receipts of what you dispatched.
|
|
36
|
+
- `get_tasks`, `get_project_summary`, `search_knowledge`: the store's memory.
|
|
37
|
+
|
|
38
|
+
Keep
|
|
39
|
+
engineering detail in worker briefs and review artifacts. In the owner's chat,
|
|
40
|
+
write one short line per dispatch and one per return:
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
Linuxbox: parser checks sent to Codex (configured default); report due 14:20 PT.
|
|
44
|
+
Desk: navigation checks returned; tests passed; not merged.
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Include computer, brief, harness/model, and the next expected report time on a
|
|
48
|
+
dispatch. Include who finished what, test result and merged/not merged on a
|
|
49
|
+
return. If a result or deadline is unknown, say so. Surface questions in the same
|
|
50
|
+
short voice with the worker's choices; do not turn the chat into code commentary.
|
|
51
|
+
|
|
52
|
+
Pick five to ten independent tasks when that many are available and capacity
|
|
53
|
+
permits. Do not manufacture tasks to fill the batch. Separate dependencies and
|
|
54
|
+
file ownership; give each remote lead a base revision, acceptance checks, local
|
|
55
|
+
fanout limit, report time and integration instructions. Every brief repeats the
|
|
56
|
+
owner's repository constraints, including any prohibition on commits, pushes,
|
|
57
|
+
branches or particular tests. Dispatch never expands the owner's authorization.
|
|
58
|
+
|
|
59
|
+
Prefer Codex. Use OpenCode Go when its account and harness are connected. Use
|
|
60
|
+
OpenRouter only when the owner explicitly requests it; an unavailable account
|
|
61
|
+
does not authorize another paid provider. Name an explicit model when instructed,
|
|
62
|
+
otherwise use and report the remote configured default. Each remote lead owns
|
|
63
|
+
its local checkouts, fanout and provider rate limits. Where installed, local
|
|
64
|
+
workers use the fanout wrapper's `scripts/run.sh --provider codex|opencode
|
|
65
|
+
--label --worktree [--model] [--mode]` contract and parent-bound manifests.
|
|
66
|
+
|
|
67
|
+
Prefer handing work to a session that already owns the project and is idle or
|
|
68
|
+
doing related work; call `hand_off` in full or `phren_admin(action: "hand_off",
|
|
69
|
+
computer?, target|session, text)` in core. Otherwise dispatch a new worker.
|
|
70
|
+
Write one short line either way. Call `dispatch` in full or
|
|
71
|
+
`phren_admin(action: "dispatch", computer, project, harness, model?, prompt, label)`
|
|
72
|
+
in core. The CLI equivalent is `phren dispatch <computer|anywhere> <project>
|
|
73
|
+
--harness <harness> --label <label> --prompt <brief> [--model <model>]`.
|
|
74
|
+
`anywhere` chooses the connected computer with the fewest working agents. Place
|
|
75
|
+
briefs sequentially, respecting busy/rate-limit responses. Keep their dispatch
|
|
76
|
+
IDs. Do not send local filesystem paths as remote project names.
|
|
77
|
+
|
|
78
|
+
`accepted` on a receipt is prompt acceptance, not worker completion. Returns
|
|
79
|
+
arrive on their own: the Hook follows every worker you dispatch, and when you
|
|
80
|
+
are idle it types one line into this session, such as `Return: Linuxbox parser
|
|
81
|
+
checks done, tests passed (dispatch <id>). Call dispatch_returns.` When you see
|
|
82
|
+
one, call `dispatch_returns` and report each return in one short line. You may
|
|
83
|
+
also call it whenever you want the current state; do not poll it in a loop, and
|
|
84
|
+
do not read remote transcripts by hand to learn whether a worker finished. Tell
|
|
85
|
+
the owner a return time as an expectation, not a promise.
|
|
86
|
+
|
|
87
|
+
For a `needs-you` return, surface the worker's question in the owner's chat
|
|
88
|
+
with its choices as the worker wrote them; do not rewrite or answer it for the
|
|
89
|
+
owner unless the owner already decided. Send the answer back with `hand_off`
|
|
90
|
+
to the row's `target`. A `blocked` worker waits on terminal input, such as a
|
|
91
|
+
permission prompt: say so and point the owner to the phone or the terminal. A
|
|
92
|
+
`gone` worker's pane closed or was taken over: say so, and decide with the
|
|
93
|
+
owner before giving its work to another agent. A `done` reply is the worker's
|
|
94
|
+
own account; check its evidence before saying tests passed or work merged.
|
|
95
|
+
|
|
96
|
+
An uncertain delivery is never retried automatically. Inspect its known target
|
|
97
|
+
or status before deciding with the owner whether a replacement is needed. Keep
|
|
98
|
+
unavailable workers visible instead of giving their work to another agent
|
|
99
|
+
while the original may still be running.
|
|
100
|
+
|
|
101
|
+
Integrate returned changes in dependency order within the owner's allowed
|
|
102
|
+
workflow. Run a cleanup pass across the combined result and the affected checks.
|
|
103
|
+
Require evidence before saying tests passed or merged. Ship only within existing
|
|
104
|
+
authorization; if publication is not authorized, return the reviewable result.
|
|
105
|
+
Update Phren tasks when verified complete and save durable decisions. A worker's
|
|
106
|
+
finished turn alone does not complete the owner's task.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: fanout
|
|
3
|
+
description: Delegate independent, bounded implementation or review work to headless agent workers using phren fanout.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Fan out when independent tasks can make progress alongside the lead's work.
|
|
7
|
+
Give each writer a separate worktree and a concrete output to validate. A brief
|
|
8
|
+
should name the goal, owned files, constraints, tests, and completion report.
|
|
9
|
+
Include relevant findings and exact review issues; avoid sending the whole chat.
|
|
10
|
+
|
|
11
|
+
Enable Hook and fanout, then use `phren fanout run --tier narrow|wide|review
|
|
12
|
+
--label LABEL --worktree PATH < brief.txt`. The command chooses an eligible
|
|
13
|
+
provider using current usage, errors and concurrency. Use `phren fanout usage`
|
|
14
|
+
to inspect it, and `--provider`/`--model` for an explicit choice subject to caps.
|
|
15
|
+
|
|
16
|
+
Use `phren fanout list` to inspect jobs, `phren fanout resume JOB < feedback.txt`
|
|
17
|
+
to send a bounded follow-up, and `phren fanout review JOB` for a review round.
|
|
18
|
+
Codex resumes inherit their original sandbox; ask a resumed author to review
|
|
19
|
+
without edits. Use a fresh review-tier worker for an enforced read-only sandbox.
|
|
20
|
+
Archive completed jobs with `phren fanout archive`.
|
|
@@ -41,7 +41,7 @@ for dir in "$PHREN_DIR"/*/; do
|
|
|
41
41
|
PROJECT=$(basename "$dir")
|
|
42
42
|
[ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
|
|
43
43
|
|
|
44
|
-
[ -f "$dir/
|
|
44
|
+
[ -f "$dir/AGENTS.md" ] && echo "$PROJECT: has AGENTS.md" || echo "$PROJECT: MISSING AGENTS.md"
|
|
45
45
|
[ -f "$dir/summary.md" ] && echo "$PROJECT: has summary.md" || echo "$PROJECT: MISSING summary.md"
|
|
46
46
|
[ -f "$dir/FINDINGS.md" ] && echo "$PROJECT: has FINDINGS.md" || echo "$PROJECT: MISSING FINDINGS.md"
|
|
47
47
|
[ -f "$dir/tasks.md" ] && echo "$PROJECT: has tasks.md" || echo "$PROJECT: MISSING tasks.md"
|
|
@@ -63,9 +63,9 @@ for dir in */; do
|
|
|
63
63
|
echo "$PROJECT/FINDINGS.md: last updated $LAST_MODIFIED"
|
|
64
64
|
fi
|
|
65
65
|
|
|
66
|
-
if [ -f "$dir/
|
|
67
|
-
LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/
|
|
68
|
-
echo "$PROJECT/
|
|
66
|
+
if [ -f "$dir/AGENTS.md" ]; then
|
|
67
|
+
LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/AGENTS.md" 2>/dev/null || stat -c %Y "$dir/AGENTS.md" 2>/dev/null || stat -f %m "$dir/AGENTS.md" 2>/dev/null)
|
|
68
|
+
echo "$PROJECT/AGENTS.md: last updated $LAST_MODIFIED"
|
|
69
69
|
fi
|
|
70
70
|
done
|
|
71
71
|
```
|
|
@@ -121,7 +121,7 @@ phren-discover
|
|
|
121
121
|
|
|
122
122
|
Projects without core files:
|
|
123
123
|
|
|
124
|
-
| Project |
|
|
124
|
+
| Project | AGENTS.md | summary.md | FINDINGS.md | tasks.md |
|
|
125
125
|
|---------|-----------|------------|--------------|------------|
|
|
126
126
|
| myapp | ok | MISSING | MISSING | ok |
|
|
127
127
|
| api | ok | ok | ok | MISSING |
|
|
@@ -130,7 +130,7 @@ Projects without core files:
|
|
|
130
130
|
|
|
131
131
|
Files not updated in 30+ days:
|
|
132
132
|
- my-app/FINDINGS.md: last updated 45 days ago
|
|
133
|
-
- frontend/
|
|
133
|
+
- frontend/AGENTS.md: last updated 62 days ago
|
|
134
134
|
|
|
135
135
|
## Section 3: Skill gaps
|
|
136
136
|
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: phren-init
|
|
3
|
-
description: Set up a new project in phren with summary,
|
|
3
|
+
description: Set up a new project in phren with summary, AGENTS.md, task, and skill templates.
|
|
4
4
|
dependencies:
|
|
5
5
|
- git
|
|
6
6
|
---
|
|
7
7
|
# phren-init - Scaffold a new project
|
|
8
8
|
|
|
9
|
-
> Set up a new project in phren with summary,
|
|
9
|
+
> Set up a new project in phren with summary, AGENTS.md, task, and skill templates.
|
|
10
10
|
|
|
11
11
|
Add a new project to your phren instance, or bootstrap phren itself if you're starting fresh.
|
|
12
12
|
|
|
@@ -68,7 +68,7 @@ Watch out: <the one thing that trips people up>
|
|
|
68
68
|
|
|
69
69
|
Ask the user for these if you can't figure them out from the project directory. If the project directory exists on disk (e.g. `~/<project-name>/`), read its package.json, pyproject.toml, README, or similar to pre-fill.
|
|
70
70
|
|
|
71
|
-
### 4. Create
|
|
71
|
+
### 4. Create AGENTS.md
|
|
72
72
|
|
|
73
73
|
```markdown
|
|
74
74
|
# <project-name>
|
|
@@ -177,7 +177,7 @@ phren-init <project-name>
|
|
|
177
177
|
|
|
178
178
|
Created:
|
|
179
179
|
$PHREN_DIR/<project-name>/summary.md
|
|
180
|
-
$PHREN_DIR/<project-name>/
|
|
180
|
+
$PHREN_DIR/<project-name>/AGENTS.md
|
|
181
181
|
$PHREN_DIR/<project-name>/tasks.md
|
|
182
182
|
$PHREN_DIR/<project-name>/skills/README.md
|
|
183
183
|
|
|
@@ -11,7 +11,7 @@ phren's store is a git repo (`~/.phren`, or `$PHREN_PATH`) that syncs across mac
|
|
|
11
11
|
## Pull (new machine, or "sync my config")
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
|
-
|
|
14
|
+
phren store sync # or on a new machine: git clone <store-url> ~/.phren
|
|
15
15
|
phren profile switch <profile> # maps this machine (hostname) to a profile in machines.yaml
|
|
16
16
|
phren init -y # wires MCP, hooks, skill mirrors, project links for that profile
|
|
17
17
|
phren doctor # anything still red is either a repo not cloned here or a team store to join
|
|
@@ -21,7 +21,7 @@ If `machines.yaml` has no entry for this machine, ask which profile to use (`ls
|
|
|
21
21
|
|
|
22
22
|
## Push ("save this to my phren", "sync back")
|
|
23
23
|
|
|
24
|
-
Store files are the linked originals, so edits made through `~/.claude/skills/*` or a project's `
|
|
24
|
+
Store files are the linked originals, so edits made through `~/.claude/skills/*` or a project's `AGENTS.md` are already in the store. Commit and push from there:
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
27
|
git -C ~/.phren add -A && git -C ~/.phren commit -m "<what changed> from $(hostname)" && git -C ~/.phren push
|
|
@@ -31,7 +31,7 @@ The stop hook auto-saves too; a manual push is only for "I want it on the other
|
|
|
31
31
|
|
|
32
32
|
## Conflicts
|
|
33
33
|
|
|
34
|
-
`
|
|
34
|
+
`phren store sync` union-merges conflicts in `tasks.md`, `FINDINGS.md`, and task archives. For other conflicts, it aborts the merge and reports the paths for manual resolution. Never drop a side silently.
|
|
35
35
|
|
|
36
36
|
## Related
|
|
37
37
|
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|