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,326 @@
1
+ /**
2
+ * Typed request/response shapes for the remote coordinator's transport surface.
3
+ * Every response carries human-readable `text` plus the verb-specific data.
4
+ * Payloads stay loose where callers do not consume a field directly.
5
+ */
6
+ /** Common envelope: every verb returns a human-readable `text` plus verb data. */
7
+ export interface HubResponse {
8
+ text: string;
9
+ }
10
+ export interface WhatsNextRequest {
11
+ workflow?: string;
12
+ /** Server-side filter for which serve crews this caller will accept. */
13
+ serve_crews?: string[];
14
+ }
15
+ /**
16
+ * One work order from a per-workflow `whats_next` sweep. `run` is the order
17
+ * identifier used by the other transport verbs. The work order is routing and
18
+ * dynamic input data; authored instruction text is resolved from the local
19
+ * workflow store by the worker.
20
+ */
21
+ export interface WorkOrder {
22
+ workflow: string;
23
+ run: string;
24
+ step: string;
25
+ /** Target reference-order fields; optional because the deployed hub may omit them. */
26
+ key?: string;
27
+ index?: number;
28
+ defDigest?: string;
29
+ /** Authoritative worker lane on modern whats_next responses. */
30
+ worker?: string;
31
+ consumedFingerprint?: Record<string, number>;
32
+ owes?: Array<{
33
+ path: string;
34
+ /** Claim-time committed version when a version-aware hub projects it. */
35
+ version?: number;
36
+ judgmentRejects: number;
37
+ schemaRejects: number;
38
+ reasons: ReasonEntry[];
39
+ proof?: string;
40
+ }>;
41
+ consumes: Record<string, unknown>;
42
+ expected_outputs: Array<{
43
+ path: string;
44
+ schema?: unknown;
45
+ }>;
46
+ feedback: string[];
47
+ advisory: {
48
+ model?: string;
49
+ tools?: string[];
50
+ };
51
+ submit_hint: string;
52
+ }
53
+ /** One instance row from an inbox-mode (`workflow` omitted) `whats_next`. */
54
+ export interface InboxInstance {
55
+ workflow: string;
56
+ def: string;
57
+ done: boolean;
58
+ eligible: number;
59
+ blocked: number;
60
+ owedSeededInputs: string[];
61
+ }
62
+ /**
63
+ * The `{ text, ...data }` envelope of a `whats_next` response, flattened as
64
+ * the REST layer serves it (`c.json({ text, ...data })`). Per-workflow mode
65
+ * carries `workflow`/`def`/`orders`; inbox mode carries `instances`. Both are
66
+ * optional because a single type covers both modes.
67
+ */
68
+ export interface WhatsNextResponse extends HubResponse {
69
+ /** Per-workflow mode: the instance id echoed back. */
70
+ workflow?: string;
71
+ /** Per-workflow mode: the def name (used to locate the cached bundle). */
72
+ def?: string;
73
+ /** Per-workflow mode: the served work orders (empty when nothing eligible). */
74
+ orders?: WorkOrder[];
75
+ /** Inbox mode (no `workflow`): the caller's servable instances. */
76
+ instances?: InboxInstance[];
77
+ }
78
+ /**
79
+ * B5 `GET /api/wake?cursor=<n>` response. The cursor is the org's current max
80
+ * `events.seq` (monotonic, never reused). `changed` is true when a servable
81
+ * event exists strictly after the client's cursor; a missing/invalid cursor
82
+ * bootstraps to `changed: true` with the real max seq. Always adopt the
83
+ * returned cursor — it is monotonic by construction (source: hub-core
84
+ * `verbs/wake.ts`).
85
+ */
86
+ export interface WakeResponse extends HubResponse {
87
+ cursor: number;
88
+ changed: boolean;
89
+ }
90
+ /**
91
+ * B4 `POST /api/presence_ping` body. `name` is non-empty, ≤200 chars.
92
+ * `serve_crews` omitted means OVERWRITE-to-empty hub-side (a ping is the full
93
+ * current truth about a Shift), so always send the crews this shift
94
+ * serves (source: hub-core `verbs/presence-ping.ts`).
95
+ *
96
+ * `shift_id`/`started_at` are W7's self-declared attribution fields — the
97
+ * Shift process incarnation id (`shf_<uuid>`, regenerated every restart,
98
+ * never persisted) and its process start time. Advisory only (D8/INV-82):
99
+ * never used for authorization, routing, dispatch, or claim correctness.
100
+ *
101
+ * WIRE CONVENTION (deliberate, do not "normalize"): these two top-level fields
102
+ * are snake_case even in TS, mirroring the hub's wire body verbatim — unlike
103
+ * `ContactHolder.shiftId` below, whose nested object keys are camelCase on
104
+ * the wire. Both conventions are correct for where they live.
105
+ */
106
+ export interface PresencePingRequest {
107
+ name: string;
108
+ serve_crews?: string[];
109
+ shift_id?: string;
110
+ started_at?: number;
111
+ /** Epoch-millisecond timestamp of the last accepted local shift attendance. */
112
+ attended_at?: number;
113
+ }
114
+ /** B4 `presence_ping` response envelope (flattened `{ text, ...data }`). */
115
+ export interface PresencePingResponse extends HubResponse {
116
+ ok: true;
117
+ name: string;
118
+ lastSeen: number;
119
+ }
120
+ /**
121
+ * The holder identity a contacting process (`get_order`/`heartbeat`) tags its
122
+ * claim with. Mirrors hub-core `claim-holders-table.ts` `ContactHolder`
123
+ * exactly — the wire shape is an OBJECT, not a string (hub-edge passes
124
+ * `body.holder` through verbatim). `kind` selects the drain policy (`exec` is
125
+ * exempt from release-by-session, C6); `id` is the session id or exec process
126
+ * identity. C4's `hold` always presents `{ kind: 'session', id }` (D5: `id`
127
+ * falls back to `anon:<hostname>:<pid>` when no session id is configured — a
128
+ * holder is now ALWAYS sent, never omitted).
129
+ *
130
+ * `shiftId` (W7) is the self-declared Shift process incarnation id
131
+ * (`shf_<uuid>`) that dispatched this holder, when known — advisory only
132
+ * (D8/INV-82), never used for authorization/routing/dispatch/claim decisions.
133
+ * Nested-object convention: camelCase on the wire (unlike `PresencePingRequest`'s
134
+ * top-level snake_case fields above) — this asymmetry is deliberate.
135
+ */
136
+ export interface ContactHolder {
137
+ kind: 'session' | 'exec';
138
+ id: string;
139
+ shiftId?: string;
140
+ }
141
+ export interface GetOrderRequest {
142
+ workflow: string;
143
+ run: string;
144
+ /** B3 holder tag distinguishing a session-hold from an exec run. */
145
+ holder?: ContactHolder;
146
+ }
147
+ /**
148
+ * Live lease state for a run, mirroring hub-core `get-order.ts`'s `lease`:
149
+ * `claimed` is whether THIS run still holds its task's claim (with no terminal
150
+ * `outcome`); `outcome` is set once the run has closed. hold reads these two to
151
+ * classify a heartbeat failure — `outcome` set ⇒ the order finished (benign);
152
+ * `claimed: false` with no outcome ⇒ the lease was lost.
153
+ */
154
+ export interface Lease {
155
+ claimed: boolean;
156
+ claimedAt?: number;
157
+ heartbeatAt?: number;
158
+ outcome?: string;
159
+ }
160
+ /**
161
+ * The persisted order packet re-served by the transport. The packet carries
162
+ * the definition projection digest and dynamic routing/state fields only.
163
+ * Workers must resolve authored command or prompt text from the local store.
164
+ * Proof/version fields describe the target protocol and remain optional because
165
+ * the deployed hub can omit them; optionality does not imply end-to-end support.
166
+ */
167
+ export interface OrderPacket {
168
+ run: string;
169
+ workflow: string;
170
+ step: string;
171
+ key: string;
172
+ index?: number;
173
+ /** Projection digest identifying the installed definition snapshot. */
174
+ defDigest: string;
175
+ inputs: string[];
176
+ outputs: string[];
177
+ /** Opaque location hint — the worker's cwd when set. */
178
+ workdir?: string;
179
+ model?: string;
180
+ /** Worker kind; `'command'` for command orders, absent means agent. */
181
+ worker?: string;
182
+ /** Artifact stem this order's judge step must verdict, when present. */
183
+ judge?: string;
184
+ spec?: Record<string, unknown>;
185
+ x?: Record<string, unknown>;
186
+ consumes: Record<string, unknown>;
187
+ /** Claim-time consumed versions when a compatible hub preserves the map. */
188
+ consumedFingerprint?: Record<string, number>;
189
+ /** Target-protocol proof map; the deployed hub currently omits this field. */
190
+ consumesProof?: string;
191
+ /** The owed outputs and their reason threads. */
192
+ owes: Array<{
193
+ path: string;
194
+ /** Claim-time committed version when a version-aware hub projects it. */
195
+ version?: number;
196
+ judgmentRejects: number;
197
+ schemaRejects: number;
198
+ reasons: ReasonEntry[];
199
+ /** Target-protocol reason-thread proof; the deployed hub may omit it. */
200
+ proof?: string;
201
+ }>;
202
+ cause?: string;
203
+ }
204
+ /** One entry in an artifact's append-only reason thread (loose mirror). */
205
+ export interface ReasonEntry {
206
+ at: number;
207
+ action: string;
208
+ kind: string;
209
+ by: string;
210
+ text: string;
211
+ fromVersion?: number;
212
+ }
213
+ export interface GetOrderResponse extends HubResponse {
214
+ workflow: string;
215
+ run: string;
216
+ /** The persisted order packet, or `null` for a pre-v7 run. */
217
+ order: OrderPacket | null;
218
+ lease: Lease;
219
+ }
220
+ export interface HeartbeatRequest {
221
+ workflow: string;
222
+ run: string;
223
+ holder?: ContactHolder;
224
+ }
225
+ export type HeartbeatResponse = HubResponse;
226
+ export type ReleaseRequest = {
227
+ session: string;
228
+ } | {
229
+ workflow: string;
230
+ run: string;
231
+ };
232
+ /**
233
+ * Response shapes mirror hub-core `verbs/release.ts` (verified 2026-07-18):
234
+ * - by-session: `{ released: Array<{workflow, run}> }` — the agent-held claims
235
+ * that were re-offered (empty when nothing was held). Exec-held claims are
236
+ * excluded server-side (SQL `holder_kind = 'exec'` is not in the session
237
+ * set); the hub does NOT enumerate them, so the client can only NOTE the
238
+ * drain-exempt-ion, never list which claims were exempt.
239
+ * - targeted: `{ released: boolean, reason?, workflow?, run? }` — idempotent
240
+ * (a not-held target is `released: false`, not an error).
241
+ *
242
+ * The by-session form's `released` array is REQUIRED (the drain role reads it);
243
+ * the targeted form's fields are all optional so callers that only do a
244
+ * fire-and-forget targeted release (hold/exec's final breath) need not model
245
+ * the payload — they ignore the response entirely.
246
+ */
247
+ export interface ReleaseSessionResponse extends HubResponse {
248
+ released: Array<{
249
+ workflow: string;
250
+ run: string;
251
+ }>;
252
+ }
253
+ export interface ReleaseTargetedResponse extends HubResponse {
254
+ released?: boolean;
255
+ reason?: string;
256
+ workflow?: string;
257
+ run?: string;
258
+ }
259
+ export type ReleaseResponse = ReleaseSessionResponse | ReleaseTargetedResponse;
260
+ export interface SubmitRequest {
261
+ workflow: string;
262
+ run: string;
263
+ path: string;
264
+ value: unknown;
265
+ done?: boolean;
266
+ /** Target-protocol DSSE envelope; production submit transport currently drops it. */
267
+ proof?: string;
268
+ /** W7: who produced this submission (D4) — carried on all three submit paths. */
269
+ holder?: ContactHolder;
270
+ }
271
+ /**
272
+ * submit's flattened `{ text, ...data }` envelope (verified against hub-core
273
+ * `verbs/submit.ts` + hub-edge `routes.ts` on 2026-07-17). `outcome` is the
274
+ * commit verdict: `green`/`submitted` are success (the value landed);
275
+ * `schema-rejected`/`born-rejected`/`artifact-too-large`/
276
+ * `artifact-normalization-failed` are failures. `closed` reports whether that
277
+ * submit closed the run (only present on a `green`/`submitted` outcome). The
278
+ * deployed response does not return the committed version, the next target
279
+ * version, proof acceptance, or an idempotency result. exec treats any
280
+ * non-green/submitted outcome as a failed submit (exit 1).
281
+ */
282
+ export interface SubmitResponse extends HubResponse {
283
+ outcome?: string;
284
+ closed?: boolean;
285
+ }
286
+ /**
287
+ * Invalidate an artifact through the claiming worker's consume-edge authority.
288
+ * `by` is deliberately absent: the hub derives the actor from the claiming
289
+ * run's step, so a worker cannot impersonate another step.
290
+ */
291
+ export interface RejectRequest {
292
+ workflow: string;
293
+ run: string;
294
+ path: string;
295
+ text: string;
296
+ }
297
+ /** The reject verb's flattened response envelope. */
298
+ export interface RejectResponse extends HubResponse {
299
+ ok: boolean;
300
+ closed?: boolean;
301
+ }
302
+ export interface WhoamiResponse extends HubResponse {
303
+ orgId: string;
304
+ orgName: string;
305
+ actor: {
306
+ id: string;
307
+ kind: 'member' | 'agent';
308
+ role: 'admin' | 'author' | 'operator' | 'agent';
309
+ scopes: string[];
310
+ };
311
+ tokenStatus: 'active';
312
+ authMethod: 'token' | 'oauth' | 'session' | 'debug';
313
+ email?: string;
314
+ }
315
+ /**
316
+ * Thrown for any non-2xx hub response. `code` is the hub's `error` slug
317
+ * (e.g. `bad_request`) when the body parsed as the hub's `{ error, message }`
318
+ * JSON; otherwise `message` carries the raw response text.
319
+ */
320
+ export declare class HubError extends Error {
321
+ readonly status: number;
322
+ readonly code?: string;
323
+ /** Server-requested delay before retrying, normalized from Retry-After. */
324
+ readonly retryAfterMs?: number;
325
+ constructor(status: number, message: string, code?: string, retryAfterMs?: number);
326
+ }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Typed request/response shapes for the remote coordinator's transport surface.
3
+ * Every response carries human-readable `text` plus the verb-specific data.
4
+ * Payloads stay loose where callers do not consume a field directly.
5
+ */
6
+ // ---- errors -----------------------------------------------------------------
7
+ /**
8
+ * Thrown for any non-2xx hub response. `code` is the hub's `error` slug
9
+ * (e.g. `bad_request`) when the body parsed as the hub's `{ error, message }`
10
+ * JSON; otherwise `message` carries the raw response text.
11
+ */
12
+ export class HubError extends Error {
13
+ status;
14
+ code;
15
+ /** Server-requested delay before retrying, normalized from Retry-After. */
16
+ retryAfterMs;
17
+ constructor(status, message, code, retryAfterMs) {
18
+ super(message);
19
+ this.name = 'HubError';
20
+ this.status = status;
21
+ if (code !== undefined)
22
+ this.code = code;
23
+ if (retryAfterMs !== undefined)
24
+ this.retryAfterMs = retryAfterMs;
25
+ }
26
+ }
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The lease-loop core — keeps ONE order's lease alive by heartbeating the hub
3
+ * on a safe cadence, and performs a bounded final-breath release on shutdown.
4
+ *
5
+ * Extracted from C4's `hold` loop (C5, plan decision 4) so the two self-leasing
6
+ * roles share ONE implementation of cadence/backoff/clock-jump/classification/
7
+ * final-breath rather than duplicating it:
8
+ * - `hold` (`src/hold/loop.ts`) wraps this with `role: 'hold'` — its observable
9
+ * behavior (outcomes, exit codes, every emitted message string) is unchanged;
10
+ * the hold tests pass unedited.
11
+ * - `exec` (`src/exec/loop.ts`) wraps this with `role: 'exec'` and an `onOrder`
12
+ * callback so it can read the first-contact order packet and run the command
13
+ * while this loop keeps the lease warm underneath it.
14
+ *
15
+ * Like C3's shift loop, every side effect is injected (hub client, sleep/clock,
16
+ * jitter, output sinks) so every test drives it with a fake hub, a scriptable
17
+ * clock, and no real timers.
18
+ *
19
+ * LIFECYCLE
20
+ * - First contact: `get_order({workflow, run, holder})`. This beats the lease,
21
+ * closes the B2 pickup window, tags the holder, and validates the
22
+ * (workflow, run) pairing. On a claimed lease it fires `onOrder(res)` (so the
23
+ * caller can read the packet from the SAME response — no second fetch) and
24
+ * returns `holding`. `lease.claimed:false` with an `outcome` ⇒ the order
25
+ * already finished (`completed`); with no outcome ⇒ nothing to hold
26
+ * (`lease-lost`). A 403 ⇒ `ownership-error`; other throws retry under the
27
+ * backoff policy before giving up `hub-unreachable`.
28
+ * - Tick: abortable `sleep(heartbeatIntervalMs)` → clock-jump check (a wall gap
29
+ * beyond interval + tolerance, e.g. a laptop sleeping, triggers a `get_order`
30
+ * lease check BEFORE the next beat so we fail fast on a dead lease) →
31
+ * `heartbeat({workflow, run, holder})`.
32
+ * - Heartbeat failure: 403 ⇒ `ownership-error` immediately; any other error
33
+ * (the engine's lease-gone 500 included) is classified via `get_order`
34
+ * (`outcome` ⇒ `completed`, unclaimed ⇒ `lease-lost`, still claimed / classify
35
+ * failed ⇒ transient). Transient failures back off (exponential + jitter,
36
+ * base 1s ×2 cap 30s) without ever sleeping past the failure window; once
37
+ * consecutive failures span `failureWindowMs`, one last classify then
38
+ * `hub-unreachable`.
39
+ * - `stop(reason, {release?})` flips a flag checked between awaits AND aborts
40
+ * the in-flight interval sleep (final breath fires ~immediately, not up to a
41
+ * full interval late), then — unless the order already `completed` or the
42
+ * caller passed `release:false` — a targeted `release` bounded at
43
+ * RELEASE_CAP_MS. `release:false` is exec's "the run just closed via submit,
44
+ * don't release" path (a release then would be a confusing no-op). Release is
45
+ * idempotent hub-side (`not-held` is a no-op, never a throw), so a normal
46
+ * completion or a reaper race both land as `released`; a throw/timeout is
47
+ * `release-failed`.
48
+ *
49
+ * OUTCOME → the role maps each to an exit code in one place (see the roles).
50
+ */
51
+ import { type ContactHolder, type GetOrderResponse } from '../hub/types.ts';
52
+ import type { HubClient } from '../hub/client.ts';
53
+ /** Discriminated result of a lease run; the role maps these to exit codes. */
54
+ export type LeaseOutcome = 'completed' | 'released' | 'release-failed' | 'ownership-error' | 'lease-lost' | 'hub-unreachable' | 'stopped';
55
+ /** Options handed to `stop()`. */
56
+ export interface StopOptions {
57
+ /** Skip the final-breath release (default true = release). exec passes false
58
+ * after a successful submit — the run already closed, so releasing would be a
59
+ * confusing no-op in the logs. */
60
+ release?: boolean;
61
+ }
62
+ export interface LeaseLoopOptions {
63
+ hub: HubClient;
64
+ workflow: string;
65
+ run: string;
66
+ /** Message prefix `owenloop work ${role}: …`. hold passes `'hold'`, exec `'exec'`. */
67
+ role: string;
68
+ /** `{kind, id}` when the holder identity is known; else omitted. */
69
+ holder?: ContactHolder;
70
+ /** Fired once on a successful first contact, with the same get_order response
71
+ * that established the hold — the caller reads the order packet from it. */
72
+ onOrder?: (res: GetOrderResponse) => void;
73
+ /** Injected sleep — tests pass a scriptable stub (no real timers). */
74
+ sleep: (ms: number) => Promise<void>;
75
+ /** Injected clock. */
76
+ now: () => number;
77
+ /** Jitter seam (default `Math.random`). */
78
+ random?: () => number;
79
+ /** stdout sink (one line per call; newline appended by the caller). */
80
+ out: (line: string) => void;
81
+ /** stderr sink. */
82
+ err: (line: string) => void;
83
+ /** Heartbeat cadence (default 60_000). */
84
+ heartbeatIntervalMs?: number;
85
+ /** Wall-gap slack before a tick is treated as a clock jump (default 30_000). */
86
+ jumpToleranceMs?: number;
87
+ /** Consecutive-failure give-up horizon (default 180_000). */
88
+ failureWindowMs?: number;
89
+ }
90
+ export interface LeaseLoop {
91
+ run(): Promise<LeaseOutcome>;
92
+ stop(reason?: string, opts?: StopOptions): void;
93
+ }
94
+ export declare function createLeaseLoop(opts: LeaseLoopOptions): LeaseLoop;