owenloop 0.4.1 → 0.5.1

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 (282) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +182 -53
  3. package/bin/owenloop.mjs +50 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +176 -0
  5. package/dist/packages/work/src/agent/brief.js +197 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +141 -0
  7. package/dist/packages/work/src/agent/loop.js +669 -0
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  11. package/dist/packages/work/src/agent/workdir.js +319 -0
  12. package/dist/packages/work/src/bundle/cache.d.ts +92 -0
  13. package/dist/packages/work/src/bundle/cache.js +338 -0
  14. package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
  15. package/dist/packages/work/src/bundle/fetch.js +345 -0
  16. package/dist/packages/work/src/bundle/types.d.ts +164 -0
  17. package/dist/packages/work/src/bundle/types.js +1 -0
  18. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  19. package/dist/packages/work/src/consumed-verifier.js +205 -0
  20. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  21. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  22. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  23. package/dist/packages/work/src/credentials/reader.js +32 -0
  24. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  25. package/dist/packages/work/src/credentials/resolve.js +56 -0
  26. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  27. package/dist/packages/work/src/exec/instructions.js +323 -0
  28. package/dist/packages/work/src/exec/loop.d.ts +40 -0
  29. package/dist/packages/work/src/exec/loop.js +332 -0
  30. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  31. package/dist/packages/work/src/exec/payload.js +54 -0
  32. package/dist/packages/work/src/exec/receipt.d.ts +41 -0
  33. package/dist/packages/work/src/exec/receipt.js +32 -0
  34. package/dist/packages/work/src/exec/runner.d.ts +71 -0
  35. package/dist/packages/work/src/exec/runner.js +256 -0
  36. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  37. package/dist/packages/work/src/harness/child-env.js +134 -0
  38. package/dist/packages/work/src/harness/claude.d.ts +140 -0
  39. package/dist/packages/work/src/harness/claude.js +837 -0
  40. package/dist/packages/work/src/harness/codex.d.ts +111 -0
  41. package/dist/packages/work/src/harness/codex.js +1024 -0
  42. package/dist/packages/work/src/harness/contract.d.ts +308 -0
  43. package/dist/packages/work/src/harness/contract.js +32 -0
  44. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  45. package/dist/packages/work/src/harness/fake.js +91 -0
  46. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  47. package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
  48. package/dist/packages/work/src/harness/permissions.d.ts +75 -0
  49. package/dist/packages/work/src/harness/permissions.js +182 -0
  50. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  51. package/dist/packages/work/src/harness/registry.js +45 -0
  52. package/dist/packages/work/src/harness/session-store.d.ts +181 -0
  53. package/dist/packages/work/src/harness/session-store.js +523 -0
  54. package/dist/packages/work/src/harness/types.d.ts +29 -0
  55. package/dist/packages/work/src/harness/types.js +14 -0
  56. package/dist/packages/work/src/harnesses.d.ts +38 -0
  57. package/dist/packages/work/src/harnesses.js +38 -0
  58. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  59. package/dist/packages/work/src/hold/loop.js +23 -0
  60. package/dist/packages/work/src/hold/mcp.d.ts +75 -0
  61. package/dist/packages/work/src/hold/mcp.js +264 -0
  62. package/dist/packages/work/src/hub/client.d.ts +23 -0
  63. package/dist/packages/work/src/hub/client.js +91 -0
  64. package/dist/packages/work/src/hub/types.d.ts +326 -0
  65. package/dist/packages/work/src/hub/types.js +26 -0
  66. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  67. package/dist/packages/work/src/lease/loop.js +277 -0
  68. package/dist/packages/work/src/main.d.ts +1 -0
  69. package/dist/packages/work/src/main.js +48 -0
  70. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  71. package/dist/packages/work/src/mcp/server.js +320 -0
  72. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  73. package/dist/packages/work/src/owenloop-bin.js +18 -0
  74. package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
  75. package/dist/packages/work/src/roles/agent-run.js +529 -0
  76. package/dist/packages/work/src/roles/exec.d.ts +48 -0
  77. package/dist/packages/work/src/roles/exec.js +228 -0
  78. package/dist/packages/work/src/roles/hold.d.ts +72 -0
  79. package/dist/packages/work/src/roles/hold.js +363 -0
  80. package/dist/packages/work/src/roles/join.d.ts +18 -0
  81. package/dist/packages/work/src/roles/join.js +204 -0
  82. package/dist/packages/work/src/roles/lint.d.ts +58 -0
  83. package/dist/packages/work/src/roles/lint.js +234 -0
  84. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  85. package/dist/packages/work/src/roles/prepare.js +249 -0
  86. package/dist/packages/work/src/roles/release.d.ts +48 -0
  87. package/dist/packages/work/src/roles/release.js +137 -0
  88. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  89. package/dist/packages/work/src/roles/sessions.js +180 -0
  90. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  91. package/dist/packages/work/src/roles/settings.js +71 -0
  92. package/dist/packages/work/src/roles/shift.d.ts +13 -0
  93. package/dist/packages/work/src/roles/shift.js +250 -0
  94. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  95. package/dist/packages/work/src/roles/signals.js +62 -0
  96. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  97. package/dist/packages/work/src/settings/provision.js +47 -0
  98. package/dist/packages/work/src/settings/settings.d.ts +136 -0
  99. package/dist/packages/work/src/settings/settings.js +155 -0
  100. package/dist/packages/work/src/shift/client.d.ts +24 -0
  101. package/dist/packages/work/src/shift/client.js +124 -0
  102. package/dist/packages/work/src/shift/loop.d.ts +131 -0
  103. package/dist/packages/work/src/shift/loop.js +751 -0
  104. package/dist/packages/work/src/shift/protocol.d.ts +95 -0
  105. package/dist/packages/work/src/shift/protocol.js +24 -0
  106. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  107. package/dist/packages/work/src/shift/routing.js +50 -0
  108. package/dist/packages/work/src/shift/runtime.d.ts +45 -0
  109. package/dist/packages/work/src/shift/runtime.js +337 -0
  110. package/dist/packages/work/src/shift/server.d.ts +23 -0
  111. package/dist/packages/work/src/shift/server.js +716 -0
  112. package/dist/packages/work/src/shift/spawn.d.ts +109 -0
  113. package/dist/packages/work/src/shift/spawn.js +158 -0
  114. package/dist/packages/work/src/shift/state.d.ts +79 -0
  115. package/dist/packages/work/src/shift/state.js +385 -0
  116. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  117. package/dist/packages/work/src/submit-proof.js +93 -0
  118. package/dist/packages/work/src/usage.d.ts +6 -0
  119. package/dist/packages/work/src/usage.js +175 -0
  120. package/dist/src/add.d.ts +189 -0
  121. package/dist/src/add.js +300 -0
  122. package/dist/src/archive.d.ts +97 -0
  123. package/dist/src/archive.js +591 -0
  124. package/dist/src/bundle/index.d.ts +64 -0
  125. package/dist/src/bundle/index.js +508 -0
  126. package/dist/src/bundle/manifest.d.ts +50 -0
  127. package/dist/src/bundle/manifest.js +435 -0
  128. package/dist/src/bundle/runtime.d.ts +26 -0
  129. package/dist/src/bundle/runtime.js +64 -0
  130. package/dist/src/bundle/tar.d.ts +62 -0
  131. package/dist/src/bundle/tar.js +238 -0
  132. package/dist/src/bundle/types.d.ts +105 -0
  133. package/dist/src/bundle/types.js +21 -0
  134. package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
  135. package/dist/src/cli.js +5968 -0
  136. package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
  137. package/dist/{credentials.js → src/credentials.js} +35 -31
  138. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  139. package/dist/src/crypto/allowed-signers.js +307 -0
  140. package/dist/src/crypto/canonical.d.ts +8 -0
  141. package/dist/src/crypto/canonical.js +92 -0
  142. package/dist/src/crypto/chain.d.ts +65 -0
  143. package/dist/src/crypto/chain.js +377 -0
  144. package/dist/src/crypto/dsse.d.ts +209 -0
  145. package/dist/src/crypto/dsse.js +282 -0
  146. package/dist/src/crypto/enrollment.d.ts +78 -0
  147. package/dist/src/crypto/enrollment.js +186 -0
  148. package/dist/src/crypto/index.d.ts +48 -0
  149. package/dist/src/crypto/index.js +44 -0
  150. package/dist/src/crypto/keys.d.ts +258 -0
  151. package/dist/src/crypto/keys.js +908 -0
  152. package/dist/src/crypto/org-root.d.ts +33 -0
  153. package/dist/src/crypto/org-root.js +78 -0
  154. package/dist/src/crypto/origin-rules.d.ts +56 -0
  155. package/dist/src/crypto/origin-rules.js +143 -0
  156. package/dist/src/crypto/policy-floor.d.ts +98 -0
  157. package/dist/src/crypto/policy-floor.js +353 -0
  158. package/dist/src/crypto/records.d.ts +316 -0
  159. package/dist/src/crypto/records.js +157 -0
  160. package/dist/src/crypto/scope.d.ts +49 -0
  161. package/dist/src/crypto/scope.js +83 -0
  162. package/dist/src/crypto/ssh.d.ts +171 -0
  163. package/dist/src/crypto/ssh.js +396 -0
  164. package/dist/src/crypto/submission.d.ts +33 -0
  165. package/dist/src/crypto/submission.js +47 -0
  166. package/dist/src/crypto/trust-roots.d.ts +29 -0
  167. package/dist/src/crypto/trust-roots.js +39 -0
  168. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  169. package/dist/src/crypto/verify-consumed.js +259 -0
  170. package/dist/src/crypto/verify-origin.d.ts +50 -0
  171. package/dist/src/crypto/verify-origin.js +151 -0
  172. package/dist/src/crypto/verify-publication.d.ts +60 -0
  173. package/dist/src/crypto/verify-publication.js +150 -0
  174. package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
  175. package/dist/{defs.js → src/defs.js} +181 -61
  176. package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
  177. package/dist/{engine.js → src/engine.js} +251 -47
  178. package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
  179. package/dist/{factory.js → src/factory.js} +16 -4
  180. package/dist/src/global-config.d.ts +59 -0
  181. package/dist/src/global-config.js +84 -0
  182. package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
  183. package/dist/{hub.js → src/hub.js} +493 -52
  184. package/dist/src/index.d.ts +47 -0
  185. package/dist/src/index.js +41 -0
  186. package/dist/src/install.d.ts +538 -0
  187. package/dist/src/install.js +1981 -0
  188. package/dist/src/lock.d.ts +38 -0
  189. package/dist/src/lock.js +325 -0
  190. package/dist/src/mcp/serve.d.ts +109 -0
  191. package/dist/{mcp → src/mcp}/serve.js +335 -75
  192. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  193. package/dist/{mcp → src/mcp}/server.js +18 -10
  194. package/dist/{model.d.ts → src/model.d.ts} +15 -0
  195. package/dist/{model.js → src/model.js} +112 -2
  196. package/dist/src/order-resolver.d.ts +184 -0
  197. package/dist/src/order-resolver.js +252 -0
  198. package/dist/src/package-version.d.ts +10 -0
  199. package/dist/src/package-version.js +42 -0
  200. package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
  201. package/dist/{paths.js → src/paths.js} +18 -0
  202. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  203. package/dist/src/schemas/index.d.ts +1416 -0
  204. package/dist/src/schemas/index.js +31 -0
  205. package/dist/src/schemas/order.v1.schema.json +106 -0
  206. package/dist/src/schemas/origin.v1.schema.json +68 -0
  207. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  208. package/dist/src/schemas/publication.v1.schema.json +31 -0
  209. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  210. package/dist/src/schemas/submission.v1.schema.json +61 -0
  211. package/dist/src/store/def-source.d.ts +52 -0
  212. package/dist/src/store/def-source.js +335 -0
  213. package/dist/src/store/index-file.d.ts +69 -0
  214. package/dist/src/store/index-file.js +151 -0
  215. package/dist/src/store/index.d.ts +27 -0
  216. package/dist/src/store/index.js +22 -0
  217. package/dist/src/store/ingestor.d.ts +43 -0
  218. package/dist/src/store/ingestor.js +211 -0
  219. package/dist/src/store/install.d.ts +228 -0
  220. package/dist/src/store/install.js +555 -0
  221. package/dist/src/store/instruction-source.d.ts +49 -0
  222. package/dist/src/store/instruction-source.js +298 -0
  223. package/dist/src/store/origin-evidence.d.ts +21 -0
  224. package/dist/src/store/origin-evidence.js +66 -0
  225. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  226. package/dist/src/store/pre-commit-verifier.js +418 -0
  227. package/dist/src/store/resolve.d.ts +138 -0
  228. package/dist/src/store/resolve.js +363 -0
  229. package/dist/src/store/types.d.ts +288 -0
  230. package/dist/src/store/types.js +356 -0
  231. package/dist/{types.d.ts → src/types.d.ts} +58 -24
  232. package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
  233. package/dist/src/untar.js +38 -0
  234. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  235. package/dist/{util.js → src/util.js} +3 -2
  236. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  237. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  238. package/docs/agent-runner.md +86 -0
  239. package/docs/authoring.md +150 -59
  240. package/docs/bundles.md +250 -0
  241. package/docs/cli.md +1758 -163
  242. package/docs/crypto.md +816 -0
  243. package/docs/design.md +374 -52
  244. package/docs/embedding.md +135 -27
  245. package/docs/wire-contracts.md +380 -0
  246. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  247. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  248. package/examples/workflows/judges/gate-sharpness.md +39 -0
  249. package/examples/workflows/judges/security.md +34 -0
  250. package/package.json +22 -8
  251. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  252. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  253. package/plugins/claude-code/plugin/.mcp.json +14 -0
  254. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  255. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  256. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  257. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  258. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  259. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  260. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  261. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  262. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  263. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  264. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  265. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  266. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  267. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  268. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
  269. package/dist/add.d.ts +0 -384
  270. package/dist/add.js +0 -834
  271. package/dist/cli.js +0 -3270
  272. package/dist/index.d.ts +0 -32
  273. package/dist/index.js +0 -23
  274. package/dist/lock.d.ts +0 -80
  275. package/dist/lock.js +0 -217
  276. package/dist/mcp/serve.d.ts +0 -84
  277. package/dist/untar.js +0 -164
  278. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  279. /package/dist/{schema.js → src/schema.js} +0 -0
  280. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  281. /package/dist/{store.js → src/store.js} +0 -0
  282. /package/dist/{types.js → src/types.js} +0 -0
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The `hold` loop (C4) — keeps one order's lease alive on behalf of an
3
+ * interactive session, and performs the final-breath handoff on shutdown.
4
+ *
5
+ * The cadence/backoff/clock-jump/final-breath CORE moved to `src/lease/loop.ts`
6
+ * in C5 (plan decision 4) so `hold` and the self-leasing `exec` share ONE
7
+ * implementation. This module is now a thin adapter: it fixes the role prefix to
8
+ * `'hold'` (so every emitted message string is byte-identical to C4) and
9
+ * re-exports the loop's public surface under the hold names its callers and
10
+ * tests already import. `hold` never reads the order packet, so it omits
11
+ * `onOrder`; its `stop(reason?)` always releases (the session died — hand the
12
+ * order back).
13
+ *
14
+ * See `src/lease/loop.ts` for the full lifecycle documentation.
15
+ */
16
+ import { createLeaseLoop } from "../lease/loop.js";
17
+ export function createHoldLoop(opts) {
18
+ const loop = createLeaseLoop({ ...opts, role: 'hold' });
19
+ return {
20
+ run: () => loop.run(),
21
+ stop: (reason, stopOpts) => loop.stop(reason, stopOpts),
22
+ };
23
+ }
@@ -0,0 +1,75 @@
1
+ /**
2
+ * The `owenloop work hold --mcp` stdio-MCP mount (plan part 2).
3
+ *
4
+ * A born-bound work-holder: the D2 stamped Step Agent's frontmatter declares
5
+ * `mcpServers.owenloop = owenloop work hold --order <wf>/<run> --origin <url> --mcp`,
6
+ * so when the Step Agent session boots it launches THIS as a stdio MCP server. The
7
+ * server exposes three bare tools the model uses to do its order:
8
+ * - `get_order` → the order packet (prompt, inputs, owed outputs) for the run
9
+ * this holder is bound to. No ids are arguments — they came in on argv, never
10
+ * through the model.
11
+ * - `submit` → post a receipt for an owed output path; when the hub reports
12
+ * the submit CLOSED the run, the lease loop is stopped with `release:false`
13
+ * (the claim is already gone).
14
+ * - `reject` → invalidate a consumed artifact through the claiming step's
15
+ * server-derived authority; the client never supplies `by`. A CLOSED reject
16
+ * also stops the lease loop without releasing the already-closed claim.
17
+ *
18
+ * Underneath the tools, the SAME lease loop the CLI `hold` runs keeps the order's
19
+ * lease warm: `createHoldMcp` builds the loop with `onOrder` wired to capture the
20
+ * first-contact packet (so `get_order` needn't re-fetch) and both output sinks
21
+ * routed to stderr (stdout is the JSON-RPC channel). The role starts the loop and
22
+ * pumps stdin into the server; loop and server share one process, and stdin EOF
23
+ * (the session died) stops the loop for its final-breath release.
24
+ *
25
+ * This module is pure wiring + tool handlers — no stdio, no process, no timers of
26
+ * its own — so a unit test drives the tools with a fake hub and a scriptable
27
+ * clock. The role (`src/roles/hold.ts`) owns the real stdin/stdout pump.
28
+ */
29
+ import { type ToolRegistration } from '../mcp/server.ts';
30
+ import type { HubClient } from '../hub/client.ts';
31
+ import type { ContactHolder } from '../hub/types.ts';
32
+ import { type SubmissionKeyManager } from '../submit-proof.ts';
33
+ import type { SshProcessAdapter } from '../../../../src/crypto/ssh.ts';
34
+ import type { ConsumedVerifier } from '../consumed-verifier.ts';
35
+ import { type HoldLoop } from './loop.ts';
36
+ export declare const HOLD_MCP_TOOL_NAMES: readonly ["get_order", "submit", "reject"];
37
+ export type HoldMcpToolName = (typeof HOLD_MCP_TOOL_NAMES)[number];
38
+ export interface HoldMcpDeps {
39
+ hub: HubClient;
40
+ workflow: string;
41
+ run: string;
42
+ /** Positive registration list. Absent exposes the full three-tool server. */
43
+ tools?: readonly HoldMcpToolName[];
44
+ /** Hub origin used to resolve the local machine signing key. */
45
+ origin?: string;
46
+ principalKeys?: SubmissionKeyManager;
47
+ env?: Record<string, string | undefined>;
48
+ /** Injectable ssh-keygen seam for hermetic submit-proof tests. */
49
+ sshProcess?: SshProcessAdapter;
50
+ /** Gate dynamic consumed values before the packet reaches the model. */
51
+ consumedVerifier?: ConsumedVerifier;
52
+ /** B3 holder tag; rides get_order/heartbeat when known. */
53
+ holder?: ContactHolder;
54
+ sleep: (ms: number) => Promise<void>;
55
+ now: () => number;
56
+ /** Diagnostics sink — stderr (stdout is the MCP transport). */
57
+ err: (line: string) => void;
58
+ heartbeatIntervalMs?: number;
59
+ /** Wall-gap slack before a tick is treated as a clock jump (default 30_000). */
60
+ jumpToleranceMs?: number;
61
+ }
62
+ export interface HoldMcpMount {
63
+ /** Exactly the selected registrations; full mode has all three tools. */
64
+ tools: ToolRegistration[];
65
+ /** The lease loop kept warm underneath — the role runs and stops it. */
66
+ loop: HoldLoop;
67
+ }
68
+ /**
69
+ * Build the hold MCP mount: the lease loop plus a positive tool selection. The
70
+ * default selection is the full `get_order`/`submit`/`reject` surface. A caller
71
+ * can request an exact subset; future registrations do not enter that subset
72
+ * unless the caller names them. The role creates the MCP server around `tools`,
73
+ * starts `loop.run()`, and pumps stdin — stopping the loop on stdin EOF.
74
+ */
75
+ export declare function createHoldMcp(deps: HoldMcpDeps): HoldMcpMount;
@@ -0,0 +1,264 @@
1
+ /**
2
+ * The `owenloop work hold --mcp` stdio-MCP mount (plan part 2).
3
+ *
4
+ * A born-bound work-holder: the D2 stamped Step Agent's frontmatter declares
5
+ * `mcpServers.owenloop = owenloop work hold --order <wf>/<run> --origin <url> --mcp`,
6
+ * so when the Step Agent session boots it launches THIS as a stdio MCP server. The
7
+ * server exposes three bare tools the model uses to do its order:
8
+ * - `get_order` → the order packet (prompt, inputs, owed outputs) for the run
9
+ * this holder is bound to. No ids are arguments — they came in on argv, never
10
+ * through the model.
11
+ * - `submit` → post a receipt for an owed output path; when the hub reports
12
+ * the submit CLOSED the run, the lease loop is stopped with `release:false`
13
+ * (the claim is already gone).
14
+ * - `reject` → invalidate a consumed artifact through the claiming step's
15
+ * server-derived authority; the client never supplies `by`. A CLOSED reject
16
+ * also stops the lease loop without releasing the already-closed claim.
17
+ *
18
+ * Underneath the tools, the SAME lease loop the CLI `hold` runs keeps the order's
19
+ * lease warm: `createHoldMcp` builds the loop with `onOrder` wired to capture the
20
+ * first-contact packet (so `get_order` needn't re-fetch) and both output sinks
21
+ * routed to stderr (stdout is the JSON-RPC channel). The role starts the loop and
22
+ * pumps stdin into the server; loop and server share one process, and stdin EOF
23
+ * (the session died) stops the loop for its final-breath release.
24
+ *
25
+ * This module is pure wiring + tool handlers — no stdio, no process, no timers of
26
+ * its own — so a unit test drives the tools with a fake hub and a scriptable
27
+ * clock. The role (`src/roles/hold.ts`) owns the real stdin/stdout pump.
28
+ */
29
+ import { textResult } from "../mcp/server.js";
30
+ import { buildSubmitProof } from "../submit-proof.js";
31
+ import { createHoldLoop } from "./loop.js";
32
+ export const HOLD_MCP_TOOL_NAMES = ['get_order', 'submit', 'reject'];
33
+ function errMsg(e) {
34
+ return e instanceof Error ? e.message : String(e);
35
+ }
36
+ /** A lean, model-facing view of the order packet. */
37
+ function orderView(res) {
38
+ return { workflow: res.workflow, run: res.run, order: res.order, text: res.text };
39
+ }
40
+ /**
41
+ * Build the hold MCP mount: the lease loop plus a positive tool selection. The
42
+ * default selection is the full `get_order`/`submit`/`reject` surface. A caller
43
+ * can request an exact subset; future registrations do not enter that subset
44
+ * unless the caller names them. The role creates the MCP server around `tools`,
45
+ * starts `loop.run()`, and pumps stdin — stopping the loop on stdin EOF.
46
+ */
47
+ export function createHoldMcp(deps) {
48
+ const { hub, workflow, run } = deps;
49
+ const holderReq = deps.holder !== undefined ? { holder: deps.holder } : {};
50
+ // The loop's first contact arrives synchronously, but consume-side verification
51
+ // is asynchronous. Keep the unverified response in a private pending slot until
52
+ // a tool call gates it; only a gated response may populate `captured` and reach
53
+ // either the model or submit-proof construction.
54
+ let firstContact;
55
+ let captured;
56
+ // Set the moment the lease loop's run() settles (lease-lost, completed,
57
+ // released, …): from then on this mount no longer holds the order, so BOTH
58
+ // registered tools fast-fail with isError and never touch the hub again (plan section 4
59
+ // — a lost claim must not be worked or double-submitted).
60
+ let terminal;
61
+ const inner = createHoldLoop({
62
+ hub,
63
+ workflow,
64
+ run,
65
+ sleep: deps.sleep,
66
+ now: deps.now,
67
+ // Both sinks to stderr: stdout is the JSON-RPC frame channel.
68
+ out: deps.err,
69
+ err: deps.err,
70
+ onOrder: (res) => {
71
+ firstContact = res;
72
+ },
73
+ ...(deps.holder !== undefined ? { holder: deps.holder } : {}),
74
+ ...(deps.heartbeatIntervalMs !== undefined ? { heartbeatIntervalMs: deps.heartbeatIntervalMs } : {}),
75
+ ...(deps.jumpToleranceMs !== undefined ? { jumpToleranceMs: deps.jumpToleranceMs } : {}),
76
+ });
77
+ // The loop the role runs is a thin wrapper that records the terminal outcome
78
+ // when run() settles, so the tool guards see it without the role's help.
79
+ const loop = {
80
+ run: async () => {
81
+ const outcome = await inner.run();
82
+ terminal = outcome;
83
+ return outcome;
84
+ },
85
+ stop: (reason, stopOpts) => inner.stop(reason, stopOpts),
86
+ };
87
+ /** The fast-fail both tools apply once the hold is over. */
88
+ function terminalGuard() {
89
+ if (terminal === undefined)
90
+ return undefined;
91
+ return textResult({ error: `order no longer held (${terminal}) — stop` }, true);
92
+ }
93
+ async function gate(res) {
94
+ if (res.order === null)
95
+ return undefined;
96
+ const hasConsumedData = Object.keys(res.order.consumes).length > 0
97
+ || res.order.owes.some((owed) => owed.reasons.length > 0 || owed.proof !== undefined);
98
+ if (deps.consumedVerifier === undefined) {
99
+ if (!hasConsumedData)
100
+ return undefined;
101
+ return textResult({
102
+ error: `consumed artifact refusal (prerequisite) for ${res.workflow}/${res.run}: consume-side verifier is not configured; dynamic values cannot be admitted to the MCP model`,
103
+ }, true);
104
+ }
105
+ try {
106
+ const checked = await deps.consumedVerifier(res.order, { hardRule: false });
107
+ if (!checked.ok)
108
+ return textResult({ error: checked.reason }, true);
109
+ for (const warning of checked.warnings)
110
+ deps.err(warning);
111
+ return undefined;
112
+ }
113
+ catch (error) {
114
+ return textResult({ error: `consumed artifact refusal (prerequisite) for ${res.workflow}/${res.run}: ${errMsg(error)}` }, true);
115
+ }
116
+ }
117
+ const getOrderTool = {
118
+ name: 'get_order',
119
+ description: "Return this work-holder's order — the prompt, consumed inputs, and owed output paths for the run it is bound to. Takes no arguments (the run is fixed at launch).",
120
+ inputSchema: { type: 'object', properties: {}, additionalProperties: false },
121
+ handler: async () => {
122
+ const gone = terminalGuard();
123
+ if (gone !== undefined)
124
+ return gone;
125
+ if (captured !== undefined) {
126
+ const refused = await gate(captured);
127
+ if (refused !== undefined)
128
+ return refused;
129
+ return textResult(orderView(captured));
130
+ }
131
+ if (firstContact !== undefined) {
132
+ const refused = await gate(firstContact);
133
+ if (refused !== undefined)
134
+ return refused;
135
+ captured = firstContact;
136
+ return textResult(orderView(firstContact));
137
+ }
138
+ try {
139
+ const res = await hub.getOrder({ workflow, run, ...holderReq });
140
+ const refused = await gate(res);
141
+ if (refused !== undefined)
142
+ return refused;
143
+ captured = res;
144
+ return textResult(orderView(res));
145
+ }
146
+ catch (e) {
147
+ return textResult({ error: errMsg(e) }, true);
148
+ }
149
+ },
150
+ };
151
+ const submitTool = {
152
+ name: 'submit',
153
+ description: 'Submit a receipt for one owed output path of this order. Set done=true when this is the final value for the path. When the hub reports the run has closed, the holder releases and exits.',
154
+ inputSchema: {
155
+ type: 'object',
156
+ required: ['path', 'value'],
157
+ properties: {
158
+ path: { type: 'string', description: 'The owed output path to submit a receipt for.' },
159
+ value: { description: 'The receipt value (any JSON).' },
160
+ done: { type: 'boolean', description: 'Mark this the final submit for the path.' },
161
+ },
162
+ additionalProperties: false,
163
+ },
164
+ handler: async (args) => {
165
+ const gone = terminalGuard();
166
+ if (gone !== undefined)
167
+ return gone;
168
+ const path = args['path'];
169
+ if (typeof path !== 'string' || path === '') {
170
+ return textResult({ error: 'submit requires a non-empty string "path"' }, true);
171
+ }
172
+ if (!('value' in args)) {
173
+ return textResult({ error: 'submit requires a "value"' }, true);
174
+ }
175
+ const done = args['done'];
176
+ try {
177
+ // Submit is also a dynamic-data boundary. Fetch and gate the bound
178
+ // packet even when no origin was supplied for submit-proof signing;
179
+ // otherwise a direct submit call could bypass MCP consume-side
180
+ // verification without first calling get_order.
181
+ let orderResponse = captured ?? firstContact;
182
+ if (orderResponse === undefined) {
183
+ orderResponse = await hub.getOrder({ workflow, run, ...holderReq });
184
+ }
185
+ const refused = await gate(orderResponse);
186
+ if (refused !== undefined)
187
+ return refused;
188
+ captured = orderResponse;
189
+ let proof;
190
+ if (deps.origin !== undefined && orderResponse.order !== null) {
191
+ proof = await buildSubmitProof({
192
+ origin: deps.origin,
193
+ order: orderResponse.order,
194
+ path,
195
+ value: args['value'],
196
+ now: deps.now,
197
+ warn: deps.err,
198
+ ...(deps.principalKeys !== undefined ? { principalKeys: deps.principalKeys } : {}),
199
+ ...(deps.env !== undefined ? { env: deps.env } : {}),
200
+ ...(deps.sshProcess !== undefined ? { sshProcess: deps.sshProcess } : {}),
201
+ });
202
+ }
203
+ const res = await hub.submit({
204
+ workflow,
205
+ run,
206
+ path,
207
+ value: args['value'],
208
+ ...(typeof done === 'boolean' ? { done } : {}),
209
+ ...(proof !== undefined ? { proof } : {}),
210
+ ...holderReq,
211
+ });
212
+ // The run closed — stop holding WITHOUT releasing (the claim is gone).
213
+ if (res.closed === true)
214
+ loop.stop('submitted', { release: false });
215
+ return textResult({ outcome: res.outcome, closed: res.closed ?? false, text: res.text });
216
+ }
217
+ catch (e) {
218
+ return textResult({ error: errMsg(e) }, true);
219
+ }
220
+ },
221
+ };
222
+ const rejectTool = {
223
+ name: 'reject',
224
+ description: 'Reject a consumed artifact path with a reason. The hub derives the rejecting step from this held run; the client cannot supply `by`.',
225
+ inputSchema: {
226
+ type: 'object',
227
+ required: ['path', 'text'],
228
+ properties: {
229
+ path: { type: 'string', description: 'The consumed artifact path to reject.' },
230
+ text: { type: 'string', description: 'The reason for rejecting the artifact.' },
231
+ },
232
+ additionalProperties: false,
233
+ },
234
+ handler: async (args) => {
235
+ const gone = terminalGuard();
236
+ if (gone !== undefined)
237
+ return gone;
238
+ const path = args['path'];
239
+ const text = args['text'];
240
+ if (typeof path !== 'string' || path.trim() === '') {
241
+ return textResult({ error: 'reject requires a non-empty string "path"' }, true);
242
+ }
243
+ if (typeof text !== 'string' || text.trim() === '') {
244
+ return textResult({ error: 'reject requires a non-empty string "text"' }, true);
245
+ }
246
+ try {
247
+ const res = await hub.reject({ workflow, run, path, text });
248
+ if (res.closed === true)
249
+ loop.stop('submitted', { release: false });
250
+ return textResult({ ok: res.ok, closed: res.closed ?? false, text: res.text });
251
+ }
252
+ catch (e) {
253
+ return textResult({ error: errMsg(e) }, true);
254
+ }
255
+ },
256
+ };
257
+ const registrations = {
258
+ get_order: getOrderTool,
259
+ submit: submitTool,
260
+ reject: rejectTool,
261
+ };
262
+ const selected = deps.tools ?? HOLD_MCP_TOOL_NAMES;
263
+ return { tools: selected.map((name) => registrations[name]), loop };
264
+ }
@@ -0,0 +1,23 @@
1
+ import type { GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
2
+ export interface HubClientOptions {
3
+ /** Hub origin, e.g. `https://hub.owenloop.dev` (no trailing slash needed). */
4
+ origin: string;
5
+ /** Resolves the bearer token per call — the CredentialReader seam. */
6
+ getToken: () => Promise<string>;
7
+ /** Override the transport in tests; defaults to the global `fetch`. */
8
+ fetchImpl?: typeof fetch;
9
+ }
10
+ export interface HubClient {
11
+ whatsNext(req?: WhatsNextRequest): Promise<WhatsNextResponse>;
12
+ getOrder(req: GetOrderRequest): Promise<GetOrderResponse>;
13
+ heartbeat(req: HeartbeatRequest): Promise<HeartbeatResponse>;
14
+ release(req: ReleaseRequest): Promise<ReleaseResponse>;
15
+ submit(req: SubmitRequest): Promise<SubmitResponse>;
16
+ reject(req: RejectRequest): Promise<RejectResponse>;
17
+ whoami(): Promise<WhoamiResponse>;
18
+ /** B5 cheap wake pre-check; `cursor` rides the query string only when set. */
19
+ wake(cursor?: number): Promise<WakeResponse>;
20
+ /** B4 Shift presence register/refresh. */
21
+ presencePing(req: PresencePingRequest): Promise<PresencePingResponse>;
22
+ }
23
+ export declare function createHubClient(opts: HubClientOptions): HubClient;
@@ -0,0 +1,91 @@
1
+ /**
2
+ * Typed hub client for the verb surface the roles call. Transport and auth
3
+ * wiring are real; in tests the client is exercised only against a fake
4
+ * `fetchImpl` or a throwaway `node:http` server (never a live hub).
5
+ *
6
+ * Every call sends `Authorization: Bearer <token>` (from the injected
7
+ * `getToken` — the seam where a CredentialReader plugs in later) and
8
+ * `content-type: application/json`, POSTs JSON to `<origin>/api/<verb>` (GET
9
+ * for `whoami`), and parses the `{ text, ...data }` envelope. Non-2xx becomes a
10
+ * `HubError`.
11
+ *
12
+ * PRESENCE (B4) + WAKE (B5): the C1 client deliberately omitted these because
13
+ * their hub surface did not exist yet. Both are merged now, so C3 adds
14
+ * `presencePing` (POST `/api/presence_ping`) and `wake` (GET `/api/wake`,
15
+ * cursor in the query string) matching the hub-edge shapes.
16
+ *
17
+ * No retries/backoff and no token refresh in C1 — the roles own their retry
18
+ * policy later, and oauth-kind token refresh stays inside owenloop.
19
+ */
20
+ import { HubError } from "./types.js";
21
+ export function createHubClient(opts) {
22
+ const base = opts.origin.replace(/\/+$/, '');
23
+ const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
24
+ async function authHeaders() {
25
+ const token = await opts.getToken();
26
+ return {
27
+ authorization: `Bearer ${token}`,
28
+ 'content-type': 'application/json',
29
+ };
30
+ }
31
+ function retryAfterMs(res) {
32
+ const raw = res.headers.get('retry-after')?.trim();
33
+ if (!raw)
34
+ return undefined;
35
+ const seconds = Number(raw);
36
+ if (Number.isFinite(seconds) && seconds >= 0)
37
+ return Math.ceil(seconds * 1_000);
38
+ const at = Date.parse(raw);
39
+ if (!Number.isFinite(at))
40
+ return undefined;
41
+ return Math.max(0, at - Date.now());
42
+ }
43
+ async function parse(res) {
44
+ const raw = await res.text();
45
+ if (!res.ok) {
46
+ let code;
47
+ let message = raw;
48
+ try {
49
+ const body = JSON.parse(raw);
50
+ if (body && typeof body === 'object') {
51
+ code = body.error;
52
+ message = body.message ?? raw;
53
+ }
54
+ }
55
+ catch {
56
+ // Not JSON — keep the raw text as the message.
57
+ }
58
+ throw new HubError(res.status, message, code, retryAfterMs(res));
59
+ }
60
+ return JSON.parse(raw);
61
+ }
62
+ async function post(verb, body) {
63
+ const res = await fetchImpl(`${base}/api/${verb}`, {
64
+ method: 'POST',
65
+ headers: await authHeaders(),
66
+ body: JSON.stringify(body),
67
+ });
68
+ return parse(res);
69
+ }
70
+ async function get(verb, query) {
71
+ const url = query !== undefined && query !== '' ? `${base}/api/${verb}?${query}` : `${base}/api/${verb}`;
72
+ const res = await fetchImpl(url, {
73
+ method: 'GET',
74
+ headers: await authHeaders(),
75
+ });
76
+ return parse(res);
77
+ }
78
+ return {
79
+ whatsNext: (req = {}) => post('whats_next', req),
80
+ getOrder: (req) => post('get_order', req),
81
+ heartbeat: (req) => post('heartbeat', req),
82
+ release: (req) => post('release', req),
83
+ submit: (req) => post('submit', req),
84
+ reject: (req) => post('reject', req),
85
+ whoami: () => get('whoami'),
86
+ // Cursor is an opaque non-negative integer; omit it entirely to bootstrap
87
+ // (the hub treats missing/invalid as a `changed: true` first sweep).
88
+ wake: (cursor) => get('wake', typeof cursor === 'number' ? `cursor=${encodeURIComponent(String(cursor))}` : undefined),
89
+ presencePing: (req) => post('presence_ping', req),
90
+ };
91
+ }