@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.
Files changed (392) 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 +195 -2
  7. package/dist/bridge/agent-hooks.js +1049 -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 +23 -0
  15. package/dist/bridge/code-note.js +51 -0
  16. package/dist/bridge/code-routes.d.ts +151 -0
  17. package/dist/bridge/code-routes.js +442 -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 +125 -0
  33. package/dist/bridge/dispatch-returns.js +283 -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 +210 -0
  37. package/dist/bridge/dispatch.js +286 -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 +28 -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 +61 -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 +54 -0
  96. package/dist/bridge/schedule-watch.js +255 -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 +36 -0
  104. package/dist/bridge/server-pane-routes.js +479 -0
  105. package/dist/bridge/server-routes.d.ts +108 -0
  106. package/dist/bridge/server-routes.js +556 -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 +96 -0
  136. package/dist/bridge/transcript-preview.js +491 -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 +46545 -21051
  146. package/dist/cli/actions.js +14 -1
  147. package/dist/cli/config-policy.js +25 -0
  148. package/dist/cli/config-proactivity.d.ts +3 -1
  149. package/dist/cli/config-proactivity.js +35 -3
  150. package/dist/cli/config.js +4 -1
  151. package/dist/cli/extract.d.ts +0 -8
  152. package/dist/cli/extract.js +4 -7
  153. package/dist/cli/govern.js +5 -2
  154. package/dist/cli/hooks-globs.js +1 -1
  155. package/dist/cli/hooks.d.ts +1 -1
  156. package/dist/cli/hooks.js +9 -7
  157. package/dist/cli/namespaces-projects.js +12 -6
  158. package/dist/cli/namespaces-store.js +37 -6
  159. package/dist/cli/namespaces-tasks.js +1 -1
  160. package/dist/cli/schedules.d.ts +1 -0
  161. package/dist/cli/schedules.js +164 -0
  162. package/dist/cli/session-background.js +1 -1
  163. package/dist/cli/session-git.d.ts +8 -5
  164. package/dist/cli/session-git.js +45 -120
  165. package/dist/cli/session-start.js +3 -1
  166. package/dist/cli/session-stop.js +19 -8
  167. package/dist/cli/team.js +13 -10
  168. package/dist/cli-handlers.d.ts +1 -1
  169. package/dist/cli-handlers.js +8 -4
  170. package/dist/cli-help.d.ts +5 -4
  171. package/dist/cli-help.js +15 -15
  172. package/dist/cli-registry.d.ts +4 -1
  173. package/dist/cli-registry.js +119 -6
  174. package/dist/content/archive.js +2 -2
  175. package/dist/content/citation.d.ts +11 -0
  176. package/dist/content/citation.js +18 -0
  177. package/dist/content/learning.js +2 -0
  178. package/dist/content/summarize.d.ts +14 -15
  179. package/dist/content/summarize.js +60 -5
  180. package/dist/content/validate.d.ts +17 -4
  181. package/dist/content/validate.js +200 -122
  182. package/dist/core/project-registry.d.ts +26 -0
  183. package/dist/core/project-registry.js +573 -0
  184. package/dist/core/project.js +2 -3
  185. package/dist/data/access.d.ts +16 -1
  186. package/dist/data/access.js +31 -3
  187. package/dist/data/tasks.d.ts +18 -3
  188. package/dist/data/tasks.js +8 -7
  189. package/dist/entrypoint.js +44 -10
  190. package/dist/fanout/adapters/claude.d.ts +2 -0
  191. package/dist/fanout/adapters/claude.js +7 -0
  192. package/dist/fanout/adapters/codex.d.ts +2 -0
  193. package/dist/fanout/adapters/codex.js +9 -0
  194. package/dist/fanout/adapters/opencode.d.ts +4 -0
  195. package/dist/fanout/adapters/opencode.js +9 -0
  196. package/dist/fanout/adapters/types.d.ts +21 -0
  197. package/dist/fanout/adapters/types.js +3 -0
  198. package/dist/fanout/command.d.ts +2 -0
  199. package/dist/fanout/command.js +78 -0
  200. package/dist/fanout/launcher.d.ts +27 -0
  201. package/dist/fanout/launcher.js +156 -0
  202. package/dist/fanout/opencode-serve.d.ts +24 -0
  203. package/dist/fanout/opencode-serve.js +191 -0
  204. package/dist/fanout/picker.d.ts +91 -0
  205. package/dist/fanout/picker.js +51 -0
  206. package/dist/fanout/usage.d.ts +5 -0
  207. package/dist/fanout/usage.js +51 -0
  208. package/dist/fanout/watchdog.d.ts +10 -0
  209. package/dist/fanout/watchdog.js +27 -0
  210. package/dist/filenames.d.ts +9 -0
  211. package/dist/filenames.js +11 -0
  212. package/dist/finding/context.js +4 -22
  213. package/dist/generated/memory-ui-graph.browser.js +525 -419
  214. package/dist/governance/policy-constants.d.ts +11 -0
  215. package/dist/governance/policy-constants.js +9 -0
  216. package/dist/governance/policy.d.ts +5 -8
  217. package/dist/governance/policy.js +11 -8
  218. package/dist/graph-core/camera.d.ts +24 -0
  219. package/dist/graph-core/camera.js +18 -0
  220. package/dist/graph-core/index.d.ts +2 -0
  221. package/dist/graph-core/index.js +2 -0
  222. package/dist/graph-core/labels.d.ts +77 -0
  223. package/dist/graph-core/labels.js +124 -0
  224. package/dist/graph-core/model.d.ts +13 -0
  225. package/dist/graph-core/model.js +33 -0
  226. package/dist/graph-core/types.d.ts +2 -0
  227. package/dist/home-paths.d.ts +7 -0
  228. package/dist/home-paths.js +21 -0
  229. package/dist/hooks.d.ts +3 -15
  230. package/dist/hooks.js +14 -1
  231. package/dist/index.js +24 -2
  232. package/dist/init/guard-globals.d.ts +1 -1
  233. package/dist/init/guard-globals.js +4 -4
  234. package/dist/init/init-configure.js +3 -3
  235. package/dist/init/init-uninstall.js +15 -5
  236. package/dist/init/init-walkthrough.js +1 -1
  237. package/dist/init/init.js +26 -6
  238. package/dist/init/management-preset.d.ts +1 -1
  239. package/dist/init/management-preset.js +2 -2
  240. package/dist/init/preferences.js +1 -1
  241. package/dist/init/self-wiring.js +1 -1
  242. package/dist/init/setup.d.ts +3 -26
  243. package/dist/init/setup.js +68 -593
  244. package/dist/init/shared.js +2 -0
  245. package/dist/init/store-gitignore.d.ts +1 -6
  246. package/dist/init/store-gitignore.js +2 -8
  247. package/dist/init/teardown.d.ts +1 -1
  248. package/dist/init/teardown.js +2 -2
  249. package/dist/link/context-imports.d.ts +15 -0
  250. package/dist/link/context-imports.js +101 -0
  251. package/dist/link/context.js +1 -1
  252. package/dist/link/doctor.d.ts +22 -1
  253. package/dist/link/doctor.js +128 -58
  254. package/dist/link/link.js +29 -61
  255. package/dist/link/refresh.js +2 -2
  256. package/dist/link/skills.js +26 -5
  257. package/dist/machine-identity.d.ts +3 -0
  258. package/dist/machine-identity.js +6 -0
  259. package/dist/mcp/profile.d.ts +2 -19
  260. package/dist/mcp/profile.js +64 -22
  261. package/dist/memory-ui-graph.runtime.js +525 -419
  262. package/dist/modules/code-package.d.ts +16 -0
  263. package/dist/modules/code-package.js +160 -0
  264. package/dist/modules/command.d.ts +2 -0
  265. package/dist/modules/command.js +67 -0
  266. package/dist/modules/config.d.ts +4 -0
  267. package/dist/modules/config.js +70 -0
  268. package/dist/modules/manifest.d.ts +41 -0
  269. package/dist/modules/manifest.js +1 -0
  270. package/dist/modules/provision.d.ts +3 -0
  271. package/dist/modules/provision.js +84 -0
  272. package/dist/modules/registry.d.ts +16 -0
  273. package/dist/modules/registry.js +250 -0
  274. package/dist/modules/runtime.d.ts +15 -0
  275. package/dist/modules/runtime.js +59 -0
  276. package/dist/package-metadata.js +10 -2
  277. package/dist/phren-dotenv.js +4 -2
  278. package/dist/phren-paths.d.ts +3 -2
  279. package/dist/phren-paths.js +4 -5
  280. package/dist/profile-store.js +43 -8
  281. package/dist/project-config.d.ts +19 -1
  282. package/dist/project-config.js +29 -3
  283. package/dist/project-topics.d.ts +1 -0
  284. package/dist/project-topics.js +13 -10
  285. package/dist/provider-adapters.js +1 -4
  286. package/dist/query-correlation.js +6 -6
  287. package/dist/session/artifacts.js +5 -5
  288. package/dist/session/checkpoints.js +5 -0
  289. package/dist/session/utils.d.ts +2 -2
  290. package/dist/session/utils.js +6 -6
  291. package/dist/shared/content.d.ts +1 -1
  292. package/dist/shared/content.js +1 -1
  293. package/dist/shared/data-utils.js +1 -1
  294. package/dist/shared/fragment-graph.d.ts +1 -1
  295. package/dist/shared/fragment-graph.js +5 -5
  296. package/dist/shared/index.js +48 -7
  297. package/dist/shared/retrieval.d.ts +18 -3
  298. package/dist/shared/retrieval.js +101 -12
  299. package/dist/shared/search-fallback.js +4 -6
  300. package/dist/shared/sqljs.d.ts +2 -0
  301. package/dist/shared/sqljs.js +4 -2
  302. package/dist/shared.d.ts +0 -1
  303. package/dist/shared.js +0 -1
  304. package/dist/shell/input.d.ts +1 -5
  305. package/dist/shell/input.js +16 -10
  306. package/dist/shell/palette.d.ts +2 -2
  307. package/dist/shell/palette.js +3 -7
  308. package/dist/shell/render.d.ts +3 -1
  309. package/dist/shell/render.js +4 -4
  310. package/dist/shell/shell.js +4 -1
  311. package/dist/shell/types.d.ts +1 -0
  312. package/dist/shell/types.js +4 -0
  313. package/dist/shell/view.d.ts +0 -4
  314. package/dist/shell/view.js +19 -27
  315. package/dist/skill/registry.js +25 -17
  316. package/dist/skill/state.d.ts +3 -0
  317. package/dist/skill/state.js +13 -7
  318. package/dist/status.js +38 -17
  319. package/dist/store-registry.d.ts +44 -18
  320. package/dist/store-registry.js +169 -60
  321. package/dist/store-weight.d.ts +1 -6
  322. package/dist/store-weight.js +4 -2
  323. package/dist/sync/auth-doctor.d.ts +8 -0
  324. package/dist/sync/auth-doctor.js +27 -0
  325. package/dist/sync/auth.d.ts +27 -0
  326. package/dist/sync/auth.js +114 -0
  327. package/dist/sync/conflict-resolve.d.ts +9 -0
  328. package/dist/sync/conflict-resolve.js +146 -0
  329. package/dist/sync/git-state.d.ts +4 -0
  330. package/dist/sync/git-state.js +49 -0
  331. package/dist/sync/outcome.d.ts +34 -0
  332. package/dist/sync/outcome.js +57 -0
  333. package/dist/sync/pull.d.ts +15 -7
  334. package/dist/sync/pull.js +84 -35
  335. package/dist/sync/store-merge.d.ts +29 -0
  336. package/dist/sync/store-merge.js +137 -0
  337. package/dist/sync/task-merge.d.ts +22 -0
  338. package/dist/sync/task-merge.js +158 -0
  339. package/dist/task/github.js +1 -1
  340. package/dist/task/lifecycle.d.ts +5 -0
  341. package/dist/task/lifecycle.js +67 -23
  342. package/dist/terminal-text.d.ts +5 -0
  343. package/dist/terminal-text.js +11 -0
  344. package/dist/test-global-setup.js +7 -0
  345. package/dist/tool-registry.d.ts +1 -1
  346. package/dist/tool-registry.js +3 -1
  347. package/dist/tools/code.d.ts +3 -0
  348. package/dist/tools/code.js +186 -0
  349. package/dist/tools/config.js +8 -0
  350. package/dist/tools/data.js +14 -7
  351. package/dist/tools/dispatch.d.ts +2 -0
  352. package/dist/tools/dispatch.js +66 -0
  353. package/dist/tools/finding.d.ts +11 -0
  354. package/dist/tools/finding.js +180 -123
  355. package/dist/tools/ops.js +5 -2
  356. package/dist/tools/search.js +21 -8
  357. package/dist/tools/session.js +21 -22
  358. package/dist/tools/tasks.js +8 -2
  359. package/dist/tools/types.d.ts +2 -2
  360. package/dist/tools/types.js +2 -2
  361. package/dist/ui/assets.js +1 -1
  362. package/dist/ui/data.js +14 -15
  363. package/dist/ui/deep-void.d.ts +1 -1
  364. package/dist/ui/deep-void.js +0 -1
  365. package/dist/ui/graph-chrome.d.ts +1 -1
  366. package/dist/ui/graph-chrome.js +51 -0
  367. package/dist/ui/page.js +5 -5
  368. package/dist/ui/scripts.js +67 -30
  369. package/dist/ui/server.js +52 -7
  370. package/dist/update.js +22 -11
  371. package/dist/utils-fts.js +1 -0
  372. package/dist/utils-helpers.d.ts +7 -0
  373. package/dist/utils-helpers.js +17 -0
  374. package/dist/utils.d.ts +1 -1
  375. package/dist/utils.js +1 -1
  376. package/package.json +49 -7
  377. package/plugins/opencode/phren-transcript.js +340 -0
  378. package/starter/README.md +4 -4
  379. package/starter/global/{CLAUDE.md → AGENTS.md} +2 -2
  380. package/starter/global/skills/conductor/SKILL.md +106 -0
  381. package/starter/global/skills/fanout/SKILL.md +20 -0
  382. package/starter/global/skills/phren-discover/SKILL.md +6 -6
  383. package/starter/global/skills/phren-init/SKILL.md +4 -4
  384. package/starter/global/skills/phren-sync/SKILL.md +3 -3
  385. package/starter/templates/frontend/reference/README.md +1 -1
  386. package/starter/templates/library/reference/README.md +1 -1
  387. package/starter/templates/monorepo/reference/README.md +1 -1
  388. package/starter/templates/python-project/reference/README.md +1 -1
  389. /package/starter/templates/frontend/{CLAUDE.md → AGENTS.md} +0 -0
  390. /package/starter/templates/library/{CLAUDE.md → AGENTS.md} +0 -0
  391. /package/starter/templates/monorepo/{CLAUDE.md → AGENTS.md} +0 -0
  392. /package/starter/templates/python-project/{CLAUDE.md → AGENTS.md} +0 -0
@@ -0,0 +1,27 @@
1
+ import { type CanaryResult } from "./health.js";
2
+ import { type Json } from "./protocol.js";
3
+ /** The label every canary workspace carries, so cleanup finds only its own. */
4
+ export declare const CANARY_LABEL = "phren canary";
5
+ export interface CanaryOptions {
6
+ trigger: "manual" | "daily";
7
+ store: string;
8
+ /** Starts an agent the way the phone's launch route does; the Hook passes launchSession. */
9
+ launch: (server: string, data: Json) => Promise<Json>;
10
+ /** The Hook's scheduler, when the schedules module runs it. */
11
+ scheduler?: {
12
+ lastTickAt?: Date;
13
+ };
14
+ server?: string;
15
+ root?: string;
16
+ }
17
+ /** Exercise the real launch, schedule, transcript and session paths once and
18
+ * save the outcome to canary.json. Everything it opens is closed again, even on
19
+ * failure; it never sends input to an existing pane and never runs or edits the
20
+ * owner's schedules or tasks. */
21
+ export declare function runCanary(options: CanaryOptions): Promise<CanaryResult>;
22
+ /** Whether the daily canary is on: `PHREN_CANARY_DAILY=1`, or `phren canary --daily on`. */
23
+ export declare function dailyCanaryEnabled(root?: string): Promise<boolean>;
24
+ /** A daily canary is due when none has run in the last day. */
25
+ export declare function dailyCanaryDue(root?: string, now?: number): Promise<boolean>;
26
+ /** `phren canary [--daily on|off]`: run the canary through this computer's Hook, or switch the daily run. */
27
+ export declare function runCanaryCommand(args: string[]): Promise<number>;
@@ -0,0 +1,189 @@
1
+ import { lstat, mkdtemp, realpath, rm } from "node:fs/promises";
2
+ import { hostname, tmpdir } from "node:os";
3
+ import path from "node:path";
4
+ import { getProjectDirs } from "../phren-paths.js";
5
+ import { listLiveSessions } from "./hand-off.js";
6
+ import { canaryFile, readCanary } from "./health.js";
7
+ import { paneIdentity, rpc, servers, snapshot } from "./herdr.js";
8
+ import { atomic, BridgeError, bridgeRoot, id, objects, provider } from "./protocol.js";
9
+ import { readScheduleDocument } from "./schedules.js";
10
+ import { TranscriptReader, transcriptPath } from "./transcripts.js";
11
+ /** The label every canary workspace carries, so cleanup finds only its own. */
12
+ export const CANARY_LABEL = "phren canary";
13
+ const DAY_MS = 24 * 60 * 60_000;
14
+ function reason(error) {
15
+ const text = error instanceof Error ? error.message : "Unknown failure.";
16
+ return text.replace(/[\x00-\x1f\x7f]+/g, " ").trim().slice(0, 300) || "Unknown failure.";
17
+ }
18
+ async function step(steps, name, run) {
19
+ const started = Date.now();
20
+ try {
21
+ steps.push({ name, durationMs: 0, ...await run() });
22
+ }
23
+ catch (error) {
24
+ steps.push({ name, durationMs: 0, status: "failed", reason: reason(error) });
25
+ }
26
+ steps.at(-1).durationMs = Date.now() - started;
27
+ }
28
+ /** Close every workspace this canary created, by id and by label. Never
29
+ * touches a workspace that existed before the canary started. */
30
+ async function closeCanaryWorkspaces(server, before, created) {
31
+ const failures = [];
32
+ let current;
33
+ try {
34
+ current = await snapshot(server);
35
+ }
36
+ catch (error) {
37
+ return `could not list workspaces to clean up (${reason(error)})`;
38
+ }
39
+ const mine = objects(current.workspaces).filter(workspace => !before.has(String(workspace.workspace_id))
40
+ && (workspace.workspace_id === created || workspace.label === CANARY_LABEL));
41
+ for (const workspace of mine) {
42
+ if (!id.safeParse(workspace.workspace_id).success)
43
+ continue;
44
+ try {
45
+ await rpc(server, "workspace.close", { workspace_id: workspace.workspace_id });
46
+ }
47
+ catch (error) {
48
+ failures.push(`${String(workspace.workspace_id)}: ${reason(error)}`);
49
+ }
50
+ }
51
+ return failures.length ? `cleanup failed for ${failures.join("; ")}` : undefined;
52
+ }
53
+ /** (1) A Claude conductor launched through launchSession in a temporary folder, then closed. */
54
+ async function conductorStep(options, server) {
55
+ const before = new Set(objects((await snapshot(server)).workspaces).map(workspace => String(workspace.workspace_id)));
56
+ const folder = await realpath(await mkdtemp(path.join(tmpdir(), "phren-canary-")));
57
+ let created, failure, detail;
58
+ try {
59
+ const launched = await options.launch(server, { role: "conductor", kind: "claude", label: CANARY_LABEL, cwd: folder, timeoutMs: 45_000 });
60
+ created = typeof launched.workspaceId === "string" ? launched.workspaceId : undefined;
61
+ detail = `claude started (${typeof launched.agentStatus === "string" ? launched.agentStatus : "status unknown"})`;
62
+ }
63
+ catch (error) {
64
+ failure = reason(error);
65
+ }
66
+ finally {
67
+ const cleanup = await closeCanaryWorkspaces(server, before, created);
68
+ await rm(folder, { recursive: true, force: true }).catch(() => { });
69
+ if (cleanup)
70
+ failure = failure ? `${failure}; ${cleanup}` : cleanup;
71
+ }
72
+ return failure ? { status: "failed", reason: failure } : { status: "ok", detail };
73
+ }
74
+ /** (2) Every project's schedules.yaml parses and the Hook's scheduler ticked recently. Nothing runs. */
75
+ async function scheduleStep(options) {
76
+ if (!options.scheduler)
77
+ return { status: "skipped", reason: "The schedules module is off on this computer." };
78
+ let count = 0;
79
+ const broken = [];
80
+ for (const directory of getProjectDirs(options.store)) {
81
+ const present = await lstat(path.join(directory, "schedules.yaml")).catch(() => undefined);
82
+ if (!present)
83
+ continue;
84
+ try {
85
+ count += (await readScheduleDocument(directory)).schedules.length;
86
+ }
87
+ catch (error) {
88
+ broken.push(`${path.basename(directory)}: ${reason(error)}`);
89
+ }
90
+ }
91
+ const tick = options.scheduler.lastTickAt;
92
+ if (broken.length)
93
+ return { status: "failed", reason: `schedules.yaml does not parse in ${broken.join("; ")}` };
94
+ if (!tick || Date.now() - tick.getTime() > 120_000)
95
+ return { status: "failed", reason: tick ? `The scheduler last ticked at ${tick.toISOString()}.` : "The scheduler has not ticked since the Hook started." };
96
+ return { status: "ok", detail: `${count} schedule${count === 1 ? "" : "s"} parse; the scheduler ticked at ${tick.toISOString()}` };
97
+ }
98
+ /** (3) One existing idle session's transcript, read only. No input reaches any pane. */
99
+ async function transcriptStep() {
100
+ for (const live of await servers()) {
101
+ const server = String(live.session), current = await snapshot(server);
102
+ const workspaceLabels = new Map(objects(current.workspaces).map(workspace => [workspace.workspace_id, workspace.label]));
103
+ for (const pane of objects(current.panes)) {
104
+ if (pane.agent_status !== "idle" || !provider.safeParse(pane.agent).success || workspaceLabels.get(pane.workspace_id) === CANARY_LABEL)
105
+ continue;
106
+ const session = await paneIdentity(server, pane).catch(() => undefined);
107
+ if (!session)
108
+ continue;
109
+ const source = pane.agent;
110
+ let file;
111
+ try {
112
+ file = await transcriptPath(source, session);
113
+ }
114
+ catch {
115
+ continue;
116
+ }
117
+ const page = await new TranscriptReader(file, source).read();
118
+ return { status: "ok", detail: `read ${page.entries.length} entries from an idle ${source} session` };
119
+ }
120
+ }
121
+ return { status: "skipped", reason: "No idle agent session with a transcript to read." };
122
+ }
123
+ /** (4) Every live session here and on enrolled computers; an unreachable computer fails the step. */
124
+ async function sessionsStep() {
125
+ const live = await listLiveSessions();
126
+ const detail = `${live.sessions.length} live session${live.sessions.length === 1 ? "" : "s"} across ${live.enrolled + 1} computer${live.enrolled ? "s" : ""}`;
127
+ if (live.unreachable.length)
128
+ return { status: "failed", detail, reason: `Unreachable: ${live.unreachable.map(item => `${item.computer} (${item.error})`).join("; ")}` };
129
+ return { status: "ok", detail };
130
+ }
131
+ let running;
132
+ /** Exercise the real launch, schedule, transcript and session paths once and
133
+ * save the outcome to canary.json. Everything it opens is closed again, even on
134
+ * failure; it never sends input to an existing pane and never runs or edits the
135
+ * owner's schedules or tasks. */
136
+ export function runCanary(options) {
137
+ if (running)
138
+ throw new BridgeError(409, "A canary is already running on this computer.");
139
+ running = (async () => {
140
+ const started = new Date(), steps = [], server = options.server ?? "default";
141
+ await step(steps, "conductor", () => conductorStep(options, server));
142
+ await step(steps, "schedules", () => scheduleStep(options));
143
+ await step(steps, "transcript", () => transcriptStep());
144
+ await step(steps, "sessions", () => sessionsStep());
145
+ const finished = new Date();
146
+ const result = { version: 1, trigger: options.trigger, computer: hostname(), startedAt: started.toISOString(),
147
+ finishedAt: finished.toISOString(), durationMs: finished.getTime() - started.getTime(),
148
+ ok: steps.every(item => item.status !== "failed"), steps };
149
+ await atomic(canaryFile(options.root ?? bridgeRoot()), JSON.stringify(result, null, 2) + "\n");
150
+ return result;
151
+ })().finally(() => { running = undefined; });
152
+ return running;
153
+ }
154
+ /** Whether the daily canary is on: `PHREN_CANARY_DAILY=1`, or `phren canary --daily on`. */
155
+ export async function dailyCanaryEnabled(root = bridgeRoot()) {
156
+ if (process.env.PHREN_CANARY_DAILY === "1")
157
+ return true;
158
+ return !!(await lstat(path.join(root, "canary-daily")).catch(() => undefined))?.isFile();
159
+ }
160
+ /** A daily canary is due when none has run in the last day. */
161
+ export async function dailyCanaryDue(root = bridgeRoot(), now = Date.now()) {
162
+ if (running || !await dailyCanaryEnabled(root))
163
+ return false;
164
+ const last = await readCanary(root);
165
+ return !last || now - Date.parse(last.startedAt) >= DAY_MS;
166
+ }
167
+ /** `phren canary [--daily on|off]`: run the canary through this computer's Hook, or switch the daily run. */
168
+ export async function runCanaryCommand(args) {
169
+ const { hookRequest } = await import("./client.js");
170
+ const { mkdir, writeFile } = await import("node:fs/promises");
171
+ if (args[0] === "--daily") {
172
+ const flag = path.join(bridgeRoot(), "canary-daily");
173
+ if (args[1] === "on") {
174
+ await mkdir(bridgeRoot(), { recursive: true, mode: 0o700 });
175
+ await writeFile(flag, "", { mode: 0o600 });
176
+ }
177
+ else if (args[1] === "off")
178
+ await rm(flag, { force: true });
179
+ else
180
+ throw new Error("Usage: phren canary [--daily on|off]");
181
+ console.log(`Daily canary ${args[1]}. The Hook checks every ten minutes and runs it once a day.`);
182
+ return 0;
183
+ }
184
+ if (args.length)
185
+ throw new Error("Usage: phren canary [--daily on|off]");
186
+ const result = await hookRequest("/v1/canary", {}, undefined, 240_000);
187
+ console.log(JSON.stringify(result, null, 2));
188
+ return result.ok === true ? 0 : 1;
189
+ }
@@ -0,0 +1,57 @@
1
+ import { type Json } from "./protocol.js";
2
+ import { z } from "zod";
3
+ /** One file a shell command changed, with the patch between the working
4
+ * tree before the call and after it. `root` is the repository; `path` is
5
+ * relative to it. */
6
+ export declare const changedFileSchema: z.ZodObject<{
7
+ root: z.ZodString;
8
+ path: z.ZodString;
9
+ status: z.ZodString;
10
+ patch: z.ZodString;
11
+ added: z.ZodNumber;
12
+ removed: z.ZodNumber;
13
+ redacted: z.ZodOptional<z.ZodBoolean>;
14
+ }, z.core.$strip>;
15
+ export type ChangedFile = z.infer<typeof changedFileSchema>;
16
+ export declare const secretName: (file: string) => boolean;
17
+ /** Tools whose filesystem changes are captured around the lifecycle callback. */
18
+ export declare const SHELL_TOOLS: Set<string>;
19
+ export declare function capturesChanges(tool: string, input: Json): boolean;
20
+ export declare function namedPaths(command: string, input?: Json): string[];
21
+ /** The files a call names in its structured input, never the words of a command line. */
22
+ export declare function claimedPaths(input: Json, cwd: string, home?: string): string[];
23
+ /** Remove old records first, then oldest records until within the disk budget. */
24
+ export declare function pruneChanges(now?: number): Promise<void>;
25
+ export declare function startChangeRetention(): Promise<() => void>;
26
+ /** Snapshots live only around a shell call. Persisted results are validated
27
+ * when loaded; the LRU retains at most 16 conversations, including loads. */
28
+ export declare class ToolChanges {
29
+ /** Called after a non-empty change event is recorded, so modules that follow
30
+ * file changes (the code index) can react without polling. */
31
+ onRecord?: (files: ChangedFile[]) => void;
32
+ private snapshots;
33
+ private results;
34
+ private controllers;
35
+ private claims;
36
+ private file;
37
+ private budget;
38
+ private discard;
39
+ close(): Promise<void>;
40
+ before(conversation: string, toolUseId: string, cwd: string, command: string, input?: Json): Promise<void>;
41
+ private claim;
42
+ /** Whether another conversation's call named this file while `snapshot` ran. */
43
+ private claimedElsewhere;
44
+ after(conversation: string, toolUseId: string): Promise<void>;
45
+ private compute;
46
+ private cache;
47
+ private load;
48
+ private record;
49
+ recordedPaths(conversation: string): Promise<string[]>;
50
+ view(conversation: string): ChangeLookup;
51
+ }
52
+ export interface ChangeLookup {
53
+ pending(toolUseId: string): boolean;
54
+ changes(toolUseId: string): Promise<ChangedFile[] | undefined>;
55
+ }
56
+ /** The tool calls whose output a transcript row carries. */
57
+ export declare function outputCallIds(raw: Json, source: string): string[];