@phren/cli 0.2.15 → 0.2.16

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 (386) hide show
  1. package/README.md +2 -2
  2. package/dist/agent-instructions.d.ts +12 -0
  3. package/dist/agent-instructions.js +52 -0
  4. package/dist/bridge/agent-hook-stores.d.ts +32 -0
  5. package/dist/bridge/agent-hook-stores.js +67 -0
  6. package/dist/bridge/agent-hooks.d.ts +193 -2
  7. package/dist/bridge/agent-hooks.js +1045 -38
  8. package/dist/bridge/canary.d.ts +27 -0
  9. package/dist/bridge/canary.js +189 -0
  10. package/dist/bridge/changes.d.ts +57 -0
  11. package/dist/bridge/changes.js +403 -0
  12. package/dist/bridge/client.d.ts +3 -0
  13. package/dist/bridge/client.js +36 -0
  14. package/dist/bridge/code-note.d.ts +22 -0
  15. package/dist/bridge/code-note.js +42 -0
  16. package/dist/bridge/code-routes.d.ts +133 -0
  17. package/dist/bridge/code-routes.js +319 -0
  18. package/dist/bridge/codex-threads.d.ts +27 -0
  19. package/dist/bridge/codex-threads.js +442 -0
  20. package/dist/bridge/command.d.ts +7 -0
  21. package/dist/bridge/command.js +50 -5
  22. package/dist/bridge/computer-names.d.ts +4 -0
  23. package/dist/bridge/computer-names.js +16 -0
  24. package/dist/bridge/computers.d.ts +9 -0
  25. package/dist/bridge/computers.js +111 -0
  26. package/dist/bridge/context.d.ts +14 -0
  27. package/dist/bridge/context.js +149 -0
  28. package/dist/bridge/dispatch-command.d.ts +3 -0
  29. package/dist/bridge/dispatch-command.js +93 -0
  30. package/dist/bridge/dispatch-hosts.d.ts +23 -0
  31. package/dist/bridge/dispatch-hosts.js +25 -0
  32. package/dist/bridge/dispatch-returns.d.ts +123 -0
  33. package/dist/bridge/dispatch-returns.js +279 -0
  34. package/dist/bridge/dispatch-tree.d.ts +54 -0
  35. package/dist/bridge/dispatch-tree.js +198 -0
  36. package/dist/bridge/dispatch.d.ts +207 -0
  37. package/dist/bridge/dispatch.js +261 -0
  38. package/dist/bridge/enroll.d.ts +31 -0
  39. package/dist/bridge/enroll.js +236 -0
  40. package/dist/bridge/fanout-messages.d.ts +74 -0
  41. package/dist/bridge/fanout-messages.js +230 -0
  42. package/dist/bridge/fanouts.d.ts +160 -0
  43. package/dist/bridge/fanouts.js +702 -0
  44. package/dist/bridge/file-range.d.ts +16 -0
  45. package/dist/bridge/file-range.js +90 -0
  46. package/dist/bridge/files.d.ts +20 -0
  47. package/dist/bridge/files.js +54 -0
  48. package/dist/bridge/git-publish.d.ts +23 -0
  49. package/dist/bridge/git-publish.js +145 -0
  50. package/dist/bridge/git-worktrees.d.ts +21 -0
  51. package/dist/bridge/git-worktrees.js +150 -0
  52. package/dist/bridge/git.d.ts +54 -0
  53. package/dist/bridge/git.js +552 -0
  54. package/dist/bridge/grants.d.ts +31 -0
  55. package/dist/bridge/grants.js +181 -0
  56. package/dist/bridge/hand-off.d.ts +79 -0
  57. package/dist/bridge/hand-off.js +151 -0
  58. package/dist/bridge/health.d.ts +128 -0
  59. package/dist/bridge/health.js +260 -0
  60. package/dist/bridge/herdr.d.ts +79 -6
  61. package/dist/bridge/herdr.js +292 -27
  62. package/dist/bridge/hook-main.js +2 -0
  63. package/dist/bridge/install.d.ts +32 -1
  64. package/dist/bridge/install.js +225 -38
  65. package/dist/bridge/launch-worktree.d.ts +21 -0
  66. package/dist/bridge/launch-worktree.js +70 -0
  67. package/dist/bridge/limits.d.ts +20 -0
  68. package/dist/bridge/limits.js +65 -0
  69. package/dist/bridge/locate.d.ts +16 -0
  70. package/dist/bridge/locate.js +75 -0
  71. package/dist/bridge/metrics.d.ts +29 -0
  72. package/dist/bridge/metrics.js +71 -0
  73. package/dist/bridge/model-switch.d.ts +35 -0
  74. package/dist/bridge/model-switch.js +250 -0
  75. package/dist/bridge/models.d.ts +46 -0
  76. package/dist/bridge/models.js +257 -0
  77. package/dist/bridge/opencode-approvals.d.ts +6 -0
  78. package/dist/bridge/opencode-approvals.js +60 -0
  79. package/dist/bridge/pane-text.d.ts +15 -0
  80. package/dist/bridge/pane-text.js +23 -0
  81. package/dist/bridge/peers.d.ts +27 -0
  82. package/dist/bridge/peers.js +130 -0
  83. package/dist/bridge/projects.d.ts +12 -1
  84. package/dist/bridge/projects.js +268 -20
  85. package/dist/bridge/protocol.d.ts +35 -2
  86. package/dist/bridge/protocol.js +42 -7
  87. package/dist/bridge/push.d.ts +83 -0
  88. package/dist/bridge/push.js +199 -0
  89. package/dist/bridge/questions.d.ts +38 -0
  90. package/dist/bridge/questions.js +205 -0
  91. package/dist/bridge/schedule-format.d.ts +103 -0
  92. package/dist/bridge/schedule-format.js +266 -0
  93. package/dist/bridge/schedule-launch.d.ts +11 -0
  94. package/dist/bridge/schedule-launch.js +169 -0
  95. package/dist/bridge/schedule-watch.d.ts +52 -0
  96. package/dist/bridge/schedule-watch.js +242 -0
  97. package/dist/bridge/schedules.d.ts +48 -0
  98. package/dist/bridge/schedules.js +205 -0
  99. package/dist/bridge/server-launch.d.ts +14 -0
  100. package/dist/bridge/server-launch.js +218 -0
  101. package/dist/bridge/server-overview.d.ts +45 -0
  102. package/dist/bridge/server-overview.js +102 -0
  103. package/dist/bridge/server-pane-routes.d.ts +29 -0
  104. package/dist/bridge/server-pane-routes.js +400 -0
  105. package/dist/bridge/server-routes.d.ts +106 -0
  106. package/dist/bridge/server-routes.js +538 -0
  107. package/dist/bridge/server-stream.d.ts +46 -0
  108. package/dist/bridge/server-stream.js +253 -0
  109. package/dist/bridge/server.d.ts +3 -15
  110. package/dist/bridge/server.js +162 -264
  111. package/dist/bridge/session-servers.d.ts +24 -0
  112. package/dist/bridge/session-servers.js +136 -0
  113. package/dist/bridge/side-questions.d.ts +74 -0
  114. package/dist/bridge/side-questions.js +252 -0
  115. package/dist/bridge/simulators.d.ts +28 -0
  116. package/dist/bridge/simulators.js +198 -0
  117. package/dist/bridge/speech-transcribe.d.ts +24 -0
  118. package/dist/bridge/speech-transcribe.js +124 -0
  119. package/dist/bridge/speech.d.ts +35 -0
  120. package/dist/bridge/speech.js +98 -0
  121. package/dist/bridge/steps.d.ts +13 -0
  122. package/dist/bridge/steps.js +222 -0
  123. package/dist/bridge/tab-activity.d.ts +18 -0
  124. package/dist/bridge/tab-activity.js +99 -0
  125. package/dist/bridge/terminal-choice.d.ts +64 -0
  126. package/dist/bridge/terminal-choice.js +281 -0
  127. package/dist/bridge/transcript-claude.d.ts +22 -0
  128. package/dist/bridge/transcript-claude.js +353 -0
  129. package/dist/bridge/transcript-codex.d.ts +30 -0
  130. package/dist/bridge/transcript-codex.js +282 -0
  131. package/dist/bridge/transcript-copilot.d.ts +4 -0
  132. package/dist/bridge/transcript-copilot.js +14 -0
  133. package/dist/bridge/transcript-opencode.d.ts +5 -0
  134. package/dist/bridge/transcript-opencode.js +26 -0
  135. package/dist/bridge/transcript-preview.d.ts +94 -0
  136. package/dist/bridge/transcript-preview.js +476 -0
  137. package/dist/bridge/transcripts.d.ts +81 -4
  138. package/dist/bridge/transcripts.js +332 -67
  139. package/dist/bridge/transport.d.ts +3 -0
  140. package/dist/bridge/transport.js +96 -15
  141. package/dist/bridge/uploads.d.ts +15 -0
  142. package/dist/bridge/uploads.js +44 -2
  143. package/dist/bridge/usage.d.ts +124 -0
  144. package/dist/bridge/usage.js +859 -0
  145. package/dist/bridge-hook.mjs +41246 -21385
  146. package/dist/cli/actions.js +14 -1
  147. package/dist/cli/config-proactivity.d.ts +3 -1
  148. package/dist/cli/config-proactivity.js +35 -3
  149. package/dist/cli/config.js +4 -1
  150. package/dist/cli/extract.js +3 -6
  151. package/dist/cli/govern.js +5 -2
  152. package/dist/cli/hooks-globs.js +1 -1
  153. package/dist/cli/hooks.d.ts +1 -1
  154. package/dist/cli/hooks.js +9 -7
  155. package/dist/cli/namespaces-projects.js +12 -6
  156. package/dist/cli/namespaces-store.js +37 -6
  157. package/dist/cli/namespaces-tasks.js +1 -1
  158. package/dist/cli/schedules.d.ts +1 -0
  159. package/dist/cli/schedules.js +164 -0
  160. package/dist/cli/session-background.js +1 -1
  161. package/dist/cli/session-git.d.ts +8 -5
  162. package/dist/cli/session-git.js +45 -120
  163. package/dist/cli/session-start.js +3 -1
  164. package/dist/cli/session-stop.js +19 -8
  165. package/dist/cli/team.js +13 -10
  166. package/dist/cli-handlers.d.ts +1 -1
  167. package/dist/cli-handlers.js +8 -4
  168. package/dist/cli-help.d.ts +5 -4
  169. package/dist/cli-help.js +15 -15
  170. package/dist/cli-registry.d.ts +4 -1
  171. package/dist/cli-registry.js +119 -6
  172. package/dist/content/archive.js +2 -2
  173. package/dist/content/citation.d.ts +11 -0
  174. package/dist/content/citation.js +18 -0
  175. package/dist/content/learning.js +2 -0
  176. package/dist/content/summarize.d.ts +14 -15
  177. package/dist/content/summarize.js +60 -5
  178. package/dist/content/validate.d.ts +3 -1
  179. package/dist/content/validate.js +26 -8
  180. package/dist/core/project-registry.d.ts +26 -0
  181. package/dist/core/project-registry.js +573 -0
  182. package/dist/core/project.js +2 -3
  183. package/dist/data/access.d.ts +7 -1
  184. package/dist/data/access.js +13 -3
  185. package/dist/data/tasks.d.ts +18 -3
  186. package/dist/data/tasks.js +8 -7
  187. package/dist/entrypoint.js +44 -10
  188. package/dist/fanout/adapters/claude.d.ts +2 -0
  189. package/dist/fanout/adapters/claude.js +7 -0
  190. package/dist/fanout/adapters/codex.d.ts +2 -0
  191. package/dist/fanout/adapters/codex.js +9 -0
  192. package/dist/fanout/adapters/opencode.d.ts +4 -0
  193. package/dist/fanout/adapters/opencode.js +9 -0
  194. package/dist/fanout/adapters/types.d.ts +21 -0
  195. package/dist/fanout/adapters/types.js +3 -0
  196. package/dist/fanout/command.d.ts +2 -0
  197. package/dist/fanout/command.js +78 -0
  198. package/dist/fanout/launcher.d.ts +27 -0
  199. package/dist/fanout/launcher.js +156 -0
  200. package/dist/fanout/opencode-serve.d.ts +24 -0
  201. package/dist/fanout/opencode-serve.js +191 -0
  202. package/dist/fanout/picker.d.ts +91 -0
  203. package/dist/fanout/picker.js +51 -0
  204. package/dist/fanout/usage.d.ts +5 -0
  205. package/dist/fanout/usage.js +51 -0
  206. package/dist/fanout/watchdog.d.ts +10 -0
  207. package/dist/fanout/watchdog.js +27 -0
  208. package/dist/filenames.d.ts +9 -0
  209. package/dist/filenames.js +11 -0
  210. package/dist/finding/context.js +4 -22
  211. package/dist/generated/memory-ui-graph.browser.js +279 -283
  212. package/dist/governance/policy-constants.d.ts +11 -0
  213. package/dist/governance/policy-constants.js +9 -0
  214. package/dist/governance/policy.d.ts +5 -8
  215. package/dist/governance/policy.js +7 -5
  216. package/dist/graph-core/camera.d.ts +24 -0
  217. package/dist/graph-core/camera.js +18 -0
  218. package/dist/graph-core/index.d.ts +2 -0
  219. package/dist/graph-core/index.js +2 -0
  220. package/dist/graph-core/labels.d.ts +77 -0
  221. package/dist/graph-core/labels.js +124 -0
  222. package/dist/graph-core/model.d.ts +13 -0
  223. package/dist/graph-core/model.js +33 -0
  224. package/dist/graph-core/types.d.ts +2 -0
  225. package/dist/home-paths.d.ts +7 -0
  226. package/dist/home-paths.js +21 -0
  227. package/dist/hooks.d.ts +3 -0
  228. package/dist/hooks.js +13 -0
  229. package/dist/index.js +24 -2
  230. package/dist/init/guard-globals.d.ts +1 -1
  231. package/dist/init/guard-globals.js +4 -4
  232. package/dist/init/init-configure.js +3 -3
  233. package/dist/init/init-uninstall.js +2 -2
  234. package/dist/init/init-walkthrough.js +1 -1
  235. package/dist/init/init.js +26 -6
  236. package/dist/init/management-preset.d.ts +1 -1
  237. package/dist/init/management-preset.js +2 -2
  238. package/dist/init/preferences.js +1 -1
  239. package/dist/init/self-wiring.js +1 -1
  240. package/dist/init/setup.d.ts +3 -26
  241. package/dist/init/setup.js +49 -588
  242. package/dist/init/shared.js +2 -0
  243. package/dist/init/store-gitignore.d.ts +1 -1
  244. package/dist/init/store-gitignore.js +2 -0
  245. package/dist/init/teardown.d.ts +1 -1
  246. package/dist/init/teardown.js +2 -2
  247. package/dist/link/context.js +1 -1
  248. package/dist/link/doctor.d.ts +22 -1
  249. package/dist/link/doctor.js +100 -54
  250. package/dist/link/link.js +29 -61
  251. package/dist/link/refresh.js +2 -2
  252. package/dist/link/skills.js +26 -5
  253. package/dist/machine-identity.d.ts +3 -0
  254. package/dist/machine-identity.js +6 -0
  255. package/dist/mcp/profile.d.ts +2 -15
  256. package/dist/mcp/profile.js +64 -9
  257. package/dist/memory-ui-graph.runtime.js +279 -283
  258. package/dist/modules/code-package.d.ts +16 -0
  259. package/dist/modules/code-package.js +152 -0
  260. package/dist/modules/command.d.ts +2 -0
  261. package/dist/modules/command.js +67 -0
  262. package/dist/modules/config.d.ts +4 -0
  263. package/dist/modules/config.js +70 -0
  264. package/dist/modules/manifest.d.ts +41 -0
  265. package/dist/modules/manifest.js +1 -0
  266. package/dist/modules/provision.d.ts +3 -0
  267. package/dist/modules/provision.js +84 -0
  268. package/dist/modules/registry.d.ts +16 -0
  269. package/dist/modules/registry.js +250 -0
  270. package/dist/modules/runtime.d.ts +15 -0
  271. package/dist/modules/runtime.js +59 -0
  272. package/dist/package-metadata.js +10 -2
  273. package/dist/phren-dotenv.js +4 -2
  274. package/dist/phren-paths.d.ts +3 -2
  275. package/dist/phren-paths.js +4 -5
  276. package/dist/profile-store.js +4 -5
  277. package/dist/project-config.d.ts +19 -1
  278. package/dist/project-config.js +29 -3
  279. package/dist/project-topics.js +4 -4
  280. package/dist/provider-adapters.js +1 -4
  281. package/dist/query-correlation.js +6 -6
  282. package/dist/session/artifacts.js +5 -5
  283. package/dist/session/checkpoints.js +5 -0
  284. package/dist/session/utils.d.ts +2 -2
  285. package/dist/session/utils.js +6 -6
  286. package/dist/shared/content.d.ts +1 -1
  287. package/dist/shared/content.js +1 -1
  288. package/dist/shared/data-utils.js +1 -1
  289. package/dist/shared/fragment-graph.d.ts +1 -1
  290. package/dist/shared/fragment-graph.js +5 -5
  291. package/dist/shared/index.js +48 -7
  292. package/dist/shared/retrieval.d.ts +18 -1
  293. package/dist/shared/retrieval.js +100 -11
  294. package/dist/shared/search-fallback.js +4 -6
  295. package/dist/shared/sqljs.d.ts +2 -0
  296. package/dist/shared/sqljs.js +4 -2
  297. package/dist/shared.d.ts +0 -1
  298. package/dist/shared.js +0 -1
  299. package/dist/shell/input.d.ts +1 -5
  300. package/dist/shell/input.js +16 -10
  301. package/dist/shell/palette.d.ts +2 -2
  302. package/dist/shell/palette.js +3 -7
  303. package/dist/shell/render.d.ts +3 -1
  304. package/dist/shell/render.js +4 -4
  305. package/dist/shell/shell.js +4 -1
  306. package/dist/shell/types.d.ts +1 -0
  307. package/dist/shell/types.js +4 -0
  308. package/dist/shell/view.d.ts +0 -4
  309. package/dist/shell/view.js +19 -27
  310. package/dist/skill/registry.js +25 -17
  311. package/dist/skill/state.d.ts +3 -0
  312. package/dist/skill/state.js +13 -7
  313. package/dist/status.js +38 -17
  314. package/dist/store-registry.d.ts +44 -18
  315. package/dist/store-registry.js +169 -60
  316. package/dist/store-weight.d.ts +1 -6
  317. package/dist/store-weight.js +4 -2
  318. package/dist/sync/auth-doctor.d.ts +8 -0
  319. package/dist/sync/auth-doctor.js +27 -0
  320. package/dist/sync/auth.d.ts +27 -0
  321. package/dist/sync/auth.js +114 -0
  322. package/dist/sync/conflict-resolve.d.ts +9 -0
  323. package/dist/sync/conflict-resolve.js +146 -0
  324. package/dist/sync/git-state.d.ts +4 -0
  325. package/dist/sync/git-state.js +49 -0
  326. package/dist/sync/outcome.d.ts +34 -0
  327. package/dist/sync/outcome.js +57 -0
  328. package/dist/sync/pull.d.ts +15 -7
  329. package/dist/sync/pull.js +84 -35
  330. package/dist/sync/store-merge.d.ts +29 -0
  331. package/dist/sync/store-merge.js +137 -0
  332. package/dist/sync/task-merge.d.ts +22 -0
  333. package/dist/sync/task-merge.js +158 -0
  334. package/dist/task/github.js +1 -1
  335. package/dist/task/lifecycle.d.ts +5 -0
  336. package/dist/task/lifecycle.js +67 -23
  337. package/dist/terminal-text.d.ts +5 -0
  338. package/dist/terminal-text.js +11 -0
  339. package/dist/test-global-setup.js +7 -0
  340. package/dist/tool-registry.d.ts +1 -1
  341. package/dist/tool-registry.js +3 -1
  342. package/dist/tools/code.d.ts +3 -0
  343. package/dist/tools/code.js +178 -0
  344. package/dist/tools/config.js +5 -0
  345. package/dist/tools/data.js +14 -7
  346. package/dist/tools/dispatch.d.ts +2 -0
  347. package/dist/tools/dispatch.js +66 -0
  348. package/dist/tools/finding.js +43 -41
  349. package/dist/tools/ops.js +5 -2
  350. package/dist/tools/search.js +21 -8
  351. package/dist/tools/session.js +21 -22
  352. package/dist/tools/tasks.js +8 -2
  353. package/dist/tools/types.d.ts +2 -2
  354. package/dist/tools/types.js +2 -2
  355. package/dist/ui/assets.js +1 -1
  356. package/dist/ui/data.js +14 -15
  357. package/dist/ui/deep-void.d.ts +1 -1
  358. package/dist/ui/deep-void.js +0 -1
  359. package/dist/ui/graph-chrome.d.ts +1 -1
  360. package/dist/ui/graph-chrome.js +51 -0
  361. package/dist/ui/page.js +5 -5
  362. package/dist/ui/scripts.js +67 -30
  363. package/dist/ui/server.js +34 -6
  364. package/dist/update.js +1 -1
  365. package/dist/utils-fts.js +1 -0
  366. package/dist/utils-helpers.d.ts +7 -0
  367. package/dist/utils-helpers.js +17 -0
  368. package/dist/utils.d.ts +1 -1
  369. package/dist/utils.js +1 -1
  370. package/package.json +45 -3
  371. package/plugins/opencode/phren-transcript.js +340 -0
  372. package/starter/README.md +4 -4
  373. package/starter/global/{CLAUDE.md → AGENTS.md} +2 -2
  374. package/starter/global/skills/conductor/SKILL.md +106 -0
  375. package/starter/global/skills/fanout/SKILL.md +20 -0
  376. package/starter/global/skills/phren-discover/SKILL.md +6 -6
  377. package/starter/global/skills/phren-init/SKILL.md +4 -4
  378. package/starter/global/skills/phren-sync/SKILL.md +3 -3
  379. package/starter/templates/frontend/reference/README.md +1 -1
  380. package/starter/templates/library/reference/README.md +1 -1
  381. package/starter/templates/monorepo/reference/README.md +1 -1
  382. package/starter/templates/python-project/reference/README.md +1 -1
  383. /package/starter/templates/frontend/{CLAUDE.md → AGENTS.md} +0 -0
  384. /package/starter/templates/library/{CLAUDE.md → AGENTS.md} +0 -0
  385. /package/starter/templates/monorepo/{CLAUDE.md → AGENTS.md} +0 -0
  386. /package/starter/templates/python-project/{CLAUDE.md → AGENTS.md} +0 -0
@@ -0,0 +1,181 @@
1
+ import { tryFileLock } from "../governance/locks.js";
2
+ import { lstat, mkdir, readFile } from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { dump, load } from "js-yaml";
5
+ import { z } from "zod";
6
+ import { atomic, BridgeError, bridgeRoot, computerName } from "./protocol.js";
7
+ const grantAction = z.enum(["dispatch", "hand_off"]);
8
+ const grantScope = z.union([
9
+ z.literal("global"),
10
+ z.string().regex(/^project:[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/),
11
+ ]);
12
+ export const grantSchema = z.object({
13
+ scope: grantScope.describe("global, or project:<slug> for one project."),
14
+ actions: z.array(grantAction).min(1).max(2).describe("Which conductor actions this grant covers."),
15
+ computers: z.array(computerName).min(1).max(32).optional().describe("Named verified peers; omitted means any."),
16
+ until: z.string().datetime({ offset: true }).optional().describe("Expiry timestamp; omitted means until revoked."),
17
+ }).strict();
18
+ const grantFile = (root = bridgeRoot()) => path.join(root, "conductor.yaml");
19
+ const fileSchema = z.object({ grants: z.array(grantSchema).max(64) }).strict();
20
+ async function regularPrivateFile(file) {
21
+ const info = await lstat(file).catch(() => undefined);
22
+ if (!info)
23
+ return false;
24
+ if (!info.isFile() || info.isSymbolicLink() || info.size > 65_536 || (info.mode & 0o077)) {
25
+ throw new BridgeError(409, "conductor.yaml must be a private regular file (0600), at most 64 KiB.");
26
+ }
27
+ return true;
28
+ }
29
+ /** js-yaml parses an unquoted timestamp as a Date; keep the schema string-only
30
+ * and accept the bare `until: 2026-10-01T00:00Z` form from the docs. */
31
+ function normalizeGrants(raw) {
32
+ if (!raw || typeof raw !== "object" || Array.isArray(raw))
33
+ return raw;
34
+ const file = { ...raw };
35
+ if (Array.isArray(file.grants)) {
36
+ file.grants = file.grants.map(item => {
37
+ if (!item || typeof item !== "object" || Array.isArray(item))
38
+ return item;
39
+ const grant = { ...item };
40
+ if (grant.until instanceof Date)
41
+ grant.until = grant.until.toISOString();
42
+ else if (typeof grant.until === "string") {
43
+ const parsed = Date.parse(grant.until);
44
+ if (!Number.isNaN(parsed))
45
+ grant.until = new Date(parsed).toISOString();
46
+ }
47
+ return grant;
48
+ });
49
+ }
50
+ return file;
51
+ }
52
+ export async function listGrants(root = bridgeRoot()) {
53
+ const file = grantFile(root);
54
+ if (!await regularPrivateFile(file))
55
+ return [];
56
+ const parsed = fileSchema.safeParse(normalizeGrants(load(await readFile(file, "utf8"))));
57
+ if (!parsed.success)
58
+ throw new BridgeError(409, "conductor.yaml does not match the grants schema.");
59
+ const now = Date.now();
60
+ return parsed.data.grants.filter(grant => !grant.until || Date.parse(grant.until) > now);
61
+ }
62
+ async function writeGrants(root, grants) {
63
+ const file = grantFile(root);
64
+ await mkdir(root, { recursive: true, mode: 0o700 });
65
+ await atomic(file, dump({ grants }, { lineWidth: 120 }));
66
+ }
67
+ /** Project scope beats global; a named computer list beats any. */
68
+ function specificity(grant) {
69
+ return (grant.scope === "global" ? 0 : 2) + (grant.computers ? 1 : 0);
70
+ }
71
+ /** Most specific matching grant wins. A computers-restricted grant never
72
+ * covers an unresolved destination: `anywhere` may pick a peer outside the
73
+ * list, and a local hand-off never goes to one of them. */
74
+ export function matchGrant(grants, query, now = Date.now()) {
75
+ const matches = grants.filter(grant => {
76
+ if (!grant.actions.includes(query.action))
77
+ return false;
78
+ if (grant.until && Date.parse(grant.until) <= now)
79
+ return false;
80
+ if (grant.scope !== "global") {
81
+ const slug = grant.scope.slice("project:".length);
82
+ if (query.project !== slug)
83
+ return false;
84
+ }
85
+ if (grant.computers && (!query.computer || query.computer === "anywhere" || !grant.computers.includes(query.computer)))
86
+ return false;
87
+ return true;
88
+ });
89
+ return matches.sort((a, b) => specificity(b) - specificity(a))[0];
90
+ }
91
+ export function grantLabel(grant) {
92
+ return grant.scope;
93
+ }
94
+ const mutations = new Map();
95
+ async function mutateGrants(root, action) {
96
+ const key = path.resolve(root);
97
+ const previous = mutations.get(key) ?? Promise.resolve();
98
+ const pending = previous.catch(() => { }).then(async () => {
99
+ const release = tryFileLock(grantFile(key));
100
+ if (!release)
101
+ throw new BridgeError(409, "Conductor grants are being updated. Try again.");
102
+ try {
103
+ return await action();
104
+ }
105
+ finally {
106
+ release();
107
+ }
108
+ });
109
+ mutations.set(key, pending);
110
+ try {
111
+ return await pending;
112
+ }
113
+ finally {
114
+ if (mutations.get(key) === pending)
115
+ mutations.delete(key);
116
+ }
117
+ }
118
+ export async function addGrant(input, root = bridgeRoot()) {
119
+ return mutateGrants(root, async () => {
120
+ const grant = grantSchema.parse(input);
121
+ const existing = await listGrants(root);
122
+ if (existing.some(item => canonicalGrant(item) === canonicalGrant(grant))) {
123
+ throw new BridgeError(409, "That grant is already listed.");
124
+ }
125
+ if (existing.length >= 64)
126
+ throw new BridgeError(409, "conductor.yaml already holds 64 grants.");
127
+ await writeGrants(root, [...existing, grant]);
128
+ return grant;
129
+ });
130
+ }
131
+ function canonicalGrant(grant) {
132
+ return JSON.stringify([grant.scope, [...grant.actions].sort(), grant.computers ? [...grant.computers].sort() : null, grant.until ?? null]);
133
+ }
134
+ /** Write a grant from an approval card answer: already listed is success. */
135
+ export async function ensureGrant(input, root = bridgeRoot()) {
136
+ return mutateGrants(root, async () => {
137
+ const grant = grantSchema.parse(input);
138
+ const existing = await listGrants(root);
139
+ if (existing.some(item => canonicalGrant(item) === canonicalGrant(grant)))
140
+ return grant;
141
+ if (existing.length >= 64)
142
+ throw new BridgeError(409, "conductor.yaml already holds 64 grants.");
143
+ await writeGrants(root, [...existing, grant]);
144
+ return grant;
145
+ });
146
+ }
147
+ export async function removeGrant(input, root = bridgeRoot()) {
148
+ return mutateGrants(root, async () => {
149
+ const body = z.object({
150
+ index: z.number().int().min(0).max(63).optional(),
151
+ expected: grantSchema.optional(),
152
+ scope: grantScope.optional(),
153
+ actions: z.array(grantAction).min(1).max(2).optional(),
154
+ computers: z.array(computerName).min(1).max(32).optional(),
155
+ until: z.string().datetime({ offset: true }).optional(),
156
+ }).strict().refine(value => value.index !== undefined || value.scope !== undefined, { message: "Provide an index or a scope to remove." }).parse(input);
157
+ const existing = await listGrants(root);
158
+ if (!existing.length)
159
+ throw new BridgeError(404, "There are no conductor grants to remove.");
160
+ let index = body.index;
161
+ if (index === undefined) {
162
+ // Scope names the row; the optional fields refine it. They never invent a
163
+ // default actions list, which would miss a single-action grant.
164
+ const sameSet = (a, b) => a.length === b.length && [...a].sort().join() === [...b].sort().join();
165
+ index = existing.findIndex(grant => grant.scope === body.scope
166
+ && (body.actions === undefined || sameSet(grant.actions, body.actions))
167
+ && (body.computers === undefined || (grant.computers !== undefined && sameSet(grant.computers, body.computers)))
168
+ && (body.until === undefined || grant.until === body.until));
169
+ if (index < 0)
170
+ throw new BridgeError(404, "No conductor grant matches that scope.");
171
+ }
172
+ if (index >= existing.length)
173
+ throw new BridgeError(404, "No conductor grant has that index.");
174
+ if (body.expected && canonicalGrant(existing[index]) !== canonicalGrant(body.expected)) {
175
+ throw new BridgeError(409, "The grants list changed. Refresh it before revoking this grant.");
176
+ }
177
+ const [removed] = existing.splice(index, 1);
178
+ await writeGrants(root, existing);
179
+ return removed;
180
+ });
181
+ }
@@ -0,0 +1,79 @@
1
+ import { z } from "zod";
2
+ import { type Target } from "./protocol.js";
3
+ export declare const handOffSchema: z.ZodObject<{
4
+ computer: z.ZodOptional<z.ZodString>;
5
+ target: z.ZodOptional<z.ZodObject<{
6
+ server: z.ZodString;
7
+ workspace: z.ZodString;
8
+ tab: z.ZodString;
9
+ pane: z.ZodString;
10
+ source: z.ZodEnum<{
11
+ claude: "claude";
12
+ codex: "codex";
13
+ copilot: "copilot";
14
+ opencode: "opencode";
15
+ phren: "phren";
16
+ }>;
17
+ session: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
18
+ }, z.core.$strip>>;
19
+ session: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>;
20
+ project: z.ZodOptional<z.ZodString>;
21
+ text: z.ZodString;
22
+ }, z.core.$strict>;
23
+ export type HandOffInput = z.infer<typeof handOffSchema>;
24
+ export declare function handOff(input: unknown): Promise<{
25
+ ok: boolean;
26
+ delivered: boolean;
27
+ target: Target;
28
+ label?: string;
29
+ granted?: string;
30
+ }>;
31
+ /** One live agent pane, on this computer or an enrolled one. */
32
+ export interface LiveSession {
33
+ computer: string;
34
+ local: boolean;
35
+ project?: string;
36
+ label?: string;
37
+ title?: string;
38
+ agent?: string;
39
+ status?: string;
40
+ role?: string;
41
+ branch?: string;
42
+ model?: string;
43
+ target?: Target;
44
+ /** Seconds since the tab last changed, when the Hook has seen it change. */
45
+ idleFor?: number;
46
+ }
47
+ /** A computer name's first DNS label, lowercased: `Desk`, `desk.local` and
48
+ * `Desk.example.net` are one computer. DHCP and Bonjour add domains to the
49
+ * same machine's name, so full names do not identify a computer. */
50
+ export declare function computerLabel(name: string): string;
51
+ /** A registered computer this Hook cannot see, with the other names the store
52
+ * registers it under. */
53
+ export interface NotLinkedComputer {
54
+ name: string;
55
+ aliases?: string[];
56
+ }
57
+ /** Computers the store registers (machines.yaml) that this Hook has no
58
+ * verified connection to, so their sessions cannot be listed from here.
59
+ * Names are compared by first label against this computer's names and each
60
+ * peer's name, address and aliases; names sharing a label collapse into one
61
+ * entry. */
62
+ export declare function notLinkedComputers(store: string | null, here: string, linked: readonly string[]): NotLinkedComputer[];
63
+ export interface LiveSessions {
64
+ sessions: LiveSession[];
65
+ unreachable: {
66
+ computer: string;
67
+ error: string;
68
+ }[];
69
+ /** Registered in the store but not linked in hooks.yaml: unknown, not idle. */
70
+ notLinked: NotLinkedComputer[];
71
+ enrolled: number;
72
+ peerError?: string;
73
+ }
74
+ /** Every live agent the conductor could hand work to: this computer's Herdr
75
+ * overview plus each enrolled computer's, read through its verified Hook.
76
+ * An unreachable computer is reported, never silently dropped. */
77
+ export declare function listLiveSessions(options?: {
78
+ store?: string | null;
79
+ }): Promise<LiveSessions>;
@@ -0,0 +1,151 @@
1
+ import { z } from "zod";
2
+ import { computerName } from "./computers.js";
3
+ import { hookRequest } from "./client.js";
4
+ import { projectName } from "./dispatch.js";
5
+ import { grantLabel, listGrants, matchGrant } from "./grants.js";
6
+ import { hookPeers, optionalHookPeers, peerRequest } from "./peers.js";
7
+ import { BridgeError, object, objects, sessionId, targetSchema } from "./protocol.js";
8
+ import { findPhrenPath } from "../phren-paths.js";
9
+ import { listMachines } from "../profile-store.js";
10
+ import { localNames } from "./computer-names.js";
11
+ const promptText = z.string().min(1).max(32768).refine(value => !/[\x00-\x08\x0b-\x1f\x7f]/.test(value));
12
+ export const handOffSchema = z.object({
13
+ computer: computerName.optional().describe("Enrolled computer name. Omit for this computer."),
14
+ target: targetSchema.optional().describe("Complete live target for the existing session."),
15
+ session: sessionId.optional().describe("Session id to resolve through the Hook workspace overview."),
16
+ project: projectName.optional().describe("Project slug this hand-off belongs to, for conductor grant matching."),
17
+ text: promptText.describe("Prompt to deliver to the existing session, at most 32768 characters."),
18
+ }).strict().superRefine((value, context) => {
19
+ if ((value.target === undefined) === (value.session === undefined))
20
+ context.addIssue({ code: "custom", message: "Provide exactly one of target or session." });
21
+ });
22
+ /** The pane's project (its folder) or workspace label, for the conductor's
23
+ * card; never a reason to fail a delivery. */
24
+ function labelOf(group, tab) {
25
+ const folder = typeof tab.cwd === "string" && tab.role !== "conductor" ? tab.cwd.split("/").filter(Boolean).at(-1) : undefined;
26
+ return folder || (typeof group.label === "string" && group.label ? group.label : undefined);
27
+ }
28
+ async function findInOverview(request, match, server) {
29
+ const route = server ? `/v1/workspaces?server=${encodeURIComponent(server)}` : "/v1/workspaces";
30
+ const overview = await request(route);
31
+ for (const group of objects(overview.groups))
32
+ for (const tab of objects(group.children)) {
33
+ const parsed = targetSchema.safeParse(tab.target);
34
+ if (parsed.success && match(parsed.data))
35
+ return { target: parsed.data, label: labelOf(group, tab) };
36
+ }
37
+ return undefined;
38
+ }
39
+ async function targetFromOverview(request, session, server) {
40
+ const found = await findInOverview(request, target => target.session === session, server);
41
+ if (!found)
42
+ throw new BridgeError(404, "No live session with that id appears in the workspace overview.");
43
+ return found;
44
+ }
45
+ export async function handOff(input) {
46
+ const data = handOffSchema.parse(input);
47
+ let request;
48
+ let peer;
49
+ if (data.computer === undefined)
50
+ request = (route, body) => hookRequest(route, body);
51
+ else {
52
+ peer = (await hookPeers()).find(candidate => candidate.name === data.computer);
53
+ if (!peer)
54
+ throw new BridgeError(404, "Unknown computer. Add its verified connection to hooks.yaml.");
55
+ request = (route, body) => peerRequest(peer, route, body);
56
+ }
57
+ const resolved = data.target ? undefined : await targetFromOverview(request, data.session, peer?.server);
58
+ const target = data.target ?? resolved.target;
59
+ if (peer && target.server !== peer.server)
60
+ throw new BridgeError(400, "The target belongs to a different Herdr server on that computer.");
61
+ const grant = matchGrant(await listGrants(), { action: "hand_off", project: data.project, computer: data.computer });
62
+ const result = await request("/v1/prompt", { target, text: data.text });
63
+ const delivered = result.ok === true && result.deliveryUncertain !== true;
64
+ // A session id was resolved from the overview already; an explicit target
65
+ // is looked up once more, best effort, for its label.
66
+ const label = resolved ? resolved.label
67
+ : await findInOverview(request, found => found.pane === target.pane && found.session === target.session, peer?.server)
68
+ .then(found => found?.label, () => undefined);
69
+ return { ok: delivered, delivered, target, ...(label ? { label } : {}), ...(grant ? { granted: grantLabel(grant) } : {}) };
70
+ }
71
+ function sessionsFrom(overview, computer, local, now = Date.now()) {
72
+ const sessions = [];
73
+ for (const group of objects(overview.groups))
74
+ for (const tab of objects(group.children)) {
75
+ if (typeof tab.agent !== "string")
76
+ continue;
77
+ const target = targetSchema.safeParse(tab.target);
78
+ const cwd = typeof tab.cwd === "string" ? tab.cwd : "";
79
+ const text = (value) => typeof value === "string" && value ? value : undefined;
80
+ const changedAt = typeof tab.lastChangedAt === "string" ? Date.parse(tab.lastChangedAt) : NaN;
81
+ // A conductor sits in the store, not a project.
82
+ sessions.push({ computer, local, project: tab.role === "conductor" ? undefined : text(cwd.split("/").filter(Boolean).at(-1)), label: text(group.label),
83
+ title: text(tab.title), agent: tab.agent, status: text(tab.agentStatus), role: text(tab.role),
84
+ branch: text(tab.branch), model: text(tab.model), ...(target.success ? { target: target.data } : {}),
85
+ ...(Number.isFinite(changedAt) ? { idleFor: Math.max(0, Math.floor((now - changedAt) / 1000)) } : {}) });
86
+ }
87
+ return sessions;
88
+ }
89
+ /** A computer name's first DNS label, lowercased: `Desk`, `desk.local` and
90
+ * `Desk.example.net` are one computer. DHCP and Bonjour add domains to the
91
+ * same machine's name, so full names do not identify a computer. */
92
+ export function computerLabel(name) {
93
+ const value = name.trim().toLowerCase();
94
+ // An IPv4 address is one name, not a label and a domain.
95
+ return /^\d+(\.\d+){3}$/.test(value) ? value : value.split(".")[0] ?? "";
96
+ }
97
+ /** Computers the store registers (machines.yaml) that this Hook has no
98
+ * verified connection to, so their sessions cannot be listed from here.
99
+ * Names are compared by first label against this computer's names and each
100
+ * peer's name, address and aliases; names sharing a label collapse into one
101
+ * entry. */
102
+ export function notLinkedComputers(store, here, linked) {
103
+ if (!store)
104
+ return [];
105
+ const machines = listMachines(store);
106
+ if (!machines.ok)
107
+ return [];
108
+ const known = new Set([here, ...localNames(), ...linked].map(computerLabel).filter(Boolean));
109
+ const groups = new Map();
110
+ for (const name of Object.keys(machines.data)) {
111
+ const label = computerLabel(name);
112
+ if (!label || known.has(label))
113
+ continue;
114
+ groups.set(label, [...(groups.get(label) ?? []), name]);
115
+ }
116
+ return [...groups.values()].map(names => {
117
+ // The shortest name leads (usually the bare label); the rest are aliases.
118
+ const [name, ...aliases] = [...names].sort((a, b) => a.length - b.length || a.localeCompare(b));
119
+ return aliases.length ? { name, aliases } : { name };
120
+ }).sort((a, b) => a.name.localeCompare(b.name));
121
+ }
122
+ /** Every live agent the conductor could hand work to: this computer's Herdr
123
+ * overview plus each enrolled computer's, read through its verified Hook.
124
+ * An unreachable computer is reported, never silently dropped. */
125
+ export async function listLiveSessions(options = {}) {
126
+ const health = await hookRequest("/v1/health");
127
+ const here = typeof object(health.computer).name === "string" ? String(object(health.computer).name) : "this computer";
128
+ const sessions = sessionsFrom(await hookRequest("/v1/workspaces"), here, true);
129
+ const { peers, peerError } = await optionalHookPeers();
130
+ const unreachable = [];
131
+ // Names each peer answers to (its hostname, Bonjour name), so a computer
132
+ // registered under another of its names is not reported as unlinked.
133
+ const peerNames = [];
134
+ await Promise.all(peers.map(async (peer) => {
135
+ try {
136
+ const route = peer.server && peer.server !== "default" ? `/v1/workspaces?server=${encodeURIComponent(peer.server)}` : "/v1/workspaces";
137
+ const [overview, health] = await Promise.all([peerRequest(peer, route), peerRequest(peer, "/v1/health").catch(() => ({}))]);
138
+ sessions.push(...sessionsFrom(overview, peer.name, false));
139
+ const computer = object(object(health).computer);
140
+ for (const name of [computer.name, ...(Array.isArray(computer.aliases) ? computer.aliases : [])])
141
+ if (typeof name === "string")
142
+ peerNames.push(name);
143
+ }
144
+ catch (error) {
145
+ unreachable.push({ computer: peer.name, error: error instanceof Error ? error.message : "Unreachable." });
146
+ }
147
+ }));
148
+ const store = options.store !== undefined ? options.store : findPhrenPath();
149
+ const notLinked = notLinkedComputers(store, here, [...peers.flatMap(peer => [peer.name, peer.address]), ...peerNames]);
150
+ return { sessions, unreachable, notLinked, enrolled: peers.length, ...(peerError ? { peerError } : {}) };
151
+ }
@@ -0,0 +1,128 @@
1
+ /** One tool's installed version, or why there is none. */
2
+ export interface ToolVersion {
3
+ tool: string;
4
+ status: "ok" | "missing" | "error";
5
+ version?: string;
6
+ detail?: string;
7
+ }
8
+ export interface StoreSync {
9
+ name: string;
10
+ role: string;
11
+ available: boolean;
12
+ branch?: string;
13
+ upstream?: string;
14
+ ahead?: number;
15
+ behind?: number;
16
+ lastPushStatus?: string;
17
+ lastPushAt?: string;
18
+ lastSuccessfulPushAt?: string;
19
+ consecutiveFailures?: number;
20
+ /** The last sync failure in plain words, only while the store is failing. */
21
+ error?: string;
22
+ degraded: boolean;
23
+ }
24
+ export interface LastScheduledRun {
25
+ name?: string;
26
+ project: string;
27
+ status: string;
28
+ reason?: string;
29
+ startedAt: string;
30
+ finishedAt?: string;
31
+ }
32
+ export interface PeerHealth {
33
+ name: string;
34
+ reachable: boolean;
35
+ ms: number;
36
+ error?: string;
37
+ version?: string;
38
+ /** Whether the peer's own hooks.yaml lists this computer; null when its Hook is too old to say. */
39
+ listsBack: boolean | null;
40
+ }
41
+ export interface CanaryStep {
42
+ name: string;
43
+ status: "ok" | "failed" | "skipped";
44
+ durationMs: number;
45
+ reason?: string;
46
+ detail?: string;
47
+ }
48
+ export interface CanaryResult {
49
+ version: 1;
50
+ trigger: "manual" | "daily";
51
+ computer: string;
52
+ startedAt: string;
53
+ finishedAt: string;
54
+ durationMs: number;
55
+ ok: boolean;
56
+ steps: CanaryStep[];
57
+ }
58
+ export interface HealthDetails {
59
+ product: "phren-hook";
60
+ computer: {
61
+ name: string;
62
+ id?: string;
63
+ };
64
+ checkedAt: string;
65
+ versions: ToolVersion[];
66
+ stores: StoreSync[];
67
+ schedules: {
68
+ running: boolean | null;
69
+ lastTickAt?: string;
70
+ lastRun: LastScheduledRun | null;
71
+ };
72
+ peers: {
73
+ configured: boolean;
74
+ error?: string;
75
+ computers: PeerHealth[];
76
+ };
77
+ push: {
78
+ configured: boolean;
79
+ devices?: number;
80
+ };
81
+ canary: CanaryResult | null;
82
+ }
83
+ export interface HealthOptions {
84
+ /** The running Hook's own version; undefined when asked from outside a Hook. */
85
+ hookVersion?: string;
86
+ computerId?: string;
87
+ store: string;
88
+ /** The Hook knows whether its scheduler runs; a CLI caller does not. */
89
+ scheduler?: {
90
+ running: boolean;
91
+ lastTickAt?: Date;
92
+ };
93
+ /** The Hook's loaded APNs sender; a CLI caller checks for apns.json instead. */
94
+ push?: {
95
+ configured: boolean;
96
+ devices: number;
97
+ };
98
+ }
99
+ /** `<tool> --version`, bounded to 3 seconds and remembered for 5 minutes. */
100
+ export declare function toolVersion(tool: string, executable?: string): Promise<ToolVersion>;
101
+ /** Only for tests: forget cached versions. */
102
+ export declare function clearVersionCache(): void;
103
+ /** Branch and ahead/behind against the upstream as last fetched; nothing is fetched here. */
104
+ export declare function storeSync(store: string): Promise<StoreSync[]>;
105
+ /** The newest run in schedule-runs.jsonl, with its schedule's name when the project still has it. */
106
+ export declare function lastScheduledRun(store: string, runsFile?: string): Promise<LastScheduledRun | null>;
107
+ /** Whether this computer's hooks.yaml lists the caller, by pinned host key or by name. */
108
+ export declare function listsCaller(caller: {
109
+ name?: string;
110
+ hostKey?: string;
111
+ }): Promise<{
112
+ computers: string[];
113
+ knowsCaller: boolean;
114
+ }>;
115
+ export declare function canaryFile(root?: string): string;
116
+ export declare function readCanary(root?: string): Promise<CanaryResult | null>;
117
+ /** Everything a person needs to tell whether phren is healthy on this computer.
118
+ * Bounded: versions are cached, each peer probe stops at 5 seconds, and nothing
119
+ * here returns a secret, a file's contents or a store path. */
120
+ export declare function healthDetails(options: HealthOptions): Promise<HealthDetails>;
121
+ /** Plain lines for `phren status`. */
122
+ export declare function formatHealth(health: HealthDetails, color: {
123
+ dim: string;
124
+ reset: string;
125
+ red: string;
126
+ yellow: string;
127
+ green: string;
128
+ }): string[];