owenloop 0.4.0 → 0.5.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 (155) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +98 -25
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{add.d.ts → src/add.d.ts} +12 -40
  109. package/dist/{add.js → src/add.js} +11 -176
  110. package/dist/src/cli.d.ts +147 -0
  111. package/dist/{cli.js → src/cli.js} +1643 -353
  112. package/dist/src/credentials.d.ts +280 -0
  113. package/dist/src/credentials.js +697 -0
  114. package/dist/{defs.js → src/defs.js} +59 -36
  115. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  116. package/dist/{engine.js → src/engine.js} +29 -20
  117. package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
  118. package/dist/{hub.js → src/hub.js} +531 -1
  119. package/dist/{index.d.ts → src/index.d.ts} +3 -1
  120. package/dist/{index.js → src/index.js} +2 -1
  121. package/dist/src/lock.d.ts +80 -0
  122. package/dist/src/lock.js +217 -0
  123. package/dist/src/mcp/serve.d.ts +85 -0
  124. package/dist/src/mcp/serve.js +702 -0
  125. package/dist/src/mcp/server.d.ts +132 -0
  126. package/dist/src/mcp/server.js +327 -0
  127. package/dist/{model.d.ts → src/model.d.ts} +59 -4
  128. package/dist/{model.js → src/model.js} +149 -22
  129. package/dist/{types.d.ts → src/types.d.ts} +66 -24
  130. package/dist/{util.d.ts → src/util.d.ts} +25 -0
  131. package/dist/{util.js → src/util.js} +26 -0
  132. package/dist/src/work-settings.d.ts +57 -0
  133. package/dist/src/work-settings.js +84 -0
  134. package/docs/authoring.md +102 -53
  135. package/docs/cli.md +883 -29
  136. package/docs/design.md +119 -45
  137. package/docs/embedding.md +39 -14
  138. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  139. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  140. package/examples/workflows/judges/gate-sharpness.md +39 -0
  141. package/examples/workflows/judges/security.md +34 -0
  142. package/package.json +17 -8
  143. package/dist/cli.d.ts +0 -83
  144. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  145. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  146. /package/dist/{factory.js → src/factory.js} +0 -0
  147. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  148. /package/dist/{paths.js → src/paths.js} +0 -0
  149. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  150. /package/dist/{schema.js → src/schema.js} +0 -0
  151. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  152. /package/dist/{store.js → src/store.js} +0 -0
  153. /package/dist/{types.js → src/types.js} +0 -0
  154. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  155. /package/dist/{untar.js → src/untar.js} +0 -0
@@ -0,0 +1,542 @@
1
+ /**
2
+ * The `agent-run` orchestration core (Phase 3) — the detached, self-leasing
3
+ * worker that HOSTS one step agent instead of stamping a file for someone else
4
+ * to run.
5
+ *
6
+ * It is `src/exec/loop.ts` for AGENT orders: same shared lease loop, same
7
+ * first-contact race, same `mapNoHold`, same `stop()` guard, every side effect
8
+ * injected (hub, adapter resolution, step material, session-store writer,
9
+ * sleep/clock, output sinks) so tests drive it with fakes and no real process.
10
+ *
11
+ * ══ THE INVARIANT ══
12
+ *
13
+ * The step agent signals TASK completion by calling the `submit` MCP tool inside
14
+ * the mounted `owenloop work hold --mcp` grandchild. This worker learns of that ONLY
15
+ * from the hub lease outcome — `createLeaseLoop().run()` resolving `'completed'`,
16
+ * or a direct `hub.getOrder` seeing `lease.outcome`. The harness stream
17
+ * (`AgentEvent`) and the SETTLING of `adapter.start()` are telemetry and
18
+ * liveness only, and are never evidence of task success or failure.
19
+ *
20
+ * The trap this design exists to avoid: `start()` resolves at TURN end, which
21
+ * happens within milliseconds of the agent calling `submit`, while the worker's
22
+ * next lease heartbeat may be a full `heartbeatIntervalMs` away. A worker that
23
+ * read "`start()` settled with no outcome yet" as "the agent did not submit"
24
+ * would RELEASE a run that had just completed, and the hub would re-offer a
25
+ * closed order. So `start()` settling never releases. It only:
26
+ *
27
+ * 1. writes the session record `turn-ended`; then
28
+ * 2. enters the bounded CONFIRM phase (`confirmOutcome` below), racing the
29
+ * lease loop against a short-cadence `hub.getOrder` poll.
30
+ *
31
+ * ══ THE CLOSED CONTRACT QUESTION ══
32
+ *
33
+ * `docs/agent-runner.md` recorded the promise-settle semantics of a non-resume
34
+ * harness failure as OPEN: `start()` may reject with a plain `Error`, or resolve
35
+ * after emitting `exited`. As the single caller, Phase 3 CLOSES it: BOTH settle
36
+ * paths are treated identically — each writes `turn-ended` and enters the
37
+ * confirm phase, and neither is read as success or failure. Nothing in this file
38
+ * branches on the settle shape.
39
+ *
40
+ * ══ PHASE 4: RESUME ON REJECTION ══
41
+ *
42
+ * Until Phase 4 this loop only ever called `adapter.start(...)`, so a re-offer —
43
+ * including a REJECTION re-offer, where the agent needs to hear three sentences
44
+ * of feedback about work it already did — paid for a whole cold start with the
45
+ * whole brief. `chooseTurn` below now picks one of two paths per firing:
46
+ *
47
+ * RESUME — `adapter.deliver(prevRef, <the rejection delta>, ...)`. The provider
48
+ * still holds the original brief, the file reads, the tool results and the
49
+ * prior submission, so the message is ONLY what is new. Same session token,
50
+ * `attempt` incremented.
51
+ * COLD REPLAY — `adapter.start(<brief + a trailing rejection section>, ...)`.
52
+ * A new session, a new token, `attempt` incremented all the same.
53
+ *
54
+ * The resume/replay decision is spelled out in `chooseTurn`'s own comment. A
55
+ * resume that the provider refuses (`ResumeUnavailableError`) falls back to a
56
+ * cold replay WITHIN THE SAME FIRING — the order is still leased, so handing it
57
+ * back would waste a whole re-offer cycle to learn something already known.
58
+ */
59
+ import { existsSync } from 'node:fs';
60
+ import { createLeaseLoop } from "../lease/loop.js";
61
+ import { isResumeUnavailable } from "../harness/contract.js";
62
+ import { orderId } from "../harness/session-store.js";
63
+ import { buildOwenloopMcp, renderBrief, renderRejection, renderReplayBrief, } from "./brief.js";
64
+ /** Default confirm-phase cadence: one `get_order` per second. */
65
+ export const DEFAULT_CONFIRM_INTERVAL_MS = 1_000;
66
+ /** Default confirm-phase bound: give the hub 15s to show the submit's outcome. */
67
+ export const DEFAULT_SUBMIT_GRACE_MS = 15_000;
68
+ function errMsg(e) {
69
+ return e instanceof Error ? e.message : String(e);
70
+ }
71
+ /**
72
+ * Poll `get_order` at `intervalMs` for at most `graceMs`, answering ONE
73
+ * question: did the hub see the agent's `submit`?
74
+ *
75
+ * - `lease.outcome` present ⇒ `'submitted'` — the run closed.
76
+ * - `lease.claimed === false` with no outcome ⇒ `'lease-lost'` — something
77
+ * else took the run; releasing would be wrong and a submit would race it.
78
+ * - the grace expires, still claimed, still no outcome ⇒ `'no-submit'`.
79
+ *
80
+ * It calls `hub.getOrder` DIRECTLY rather than poking the lease loop:
81
+ * `LeaseLoop`'s public surface is `{run, stop}` with no probe-now method, and
82
+ * `src/lease/loop.ts` is load-bearing for six existing drills and must stay
83
+ * unchanged. Re-calling `get_order` while already holding the claim is exactly
84
+ * what the lease loop's own heartbeat does, so this adds no new hub semantics.
85
+ *
86
+ * A throwing `get_order` is transient by assumption: it is logged and the poll
87
+ * continues until the grace expires. Nothing here releases; only the caller does.
88
+ */
89
+ export async function confirmOutcome(o) {
90
+ const deadline = o.now() + o.graceMs;
91
+ for (;;) {
92
+ if (o.cancelled?.() === true)
93
+ return 'no-submit';
94
+ let res;
95
+ try {
96
+ res = await o.hub.getOrder({ workflow: o.workflow, run: o.run, holder: o.holder });
97
+ }
98
+ catch (e) {
99
+ o.err(`owenloop work agent-run: confirm get_order failed: ${errMsg(e)} (retrying within the grace)`);
100
+ }
101
+ if (res !== undefined) {
102
+ if (res.lease.outcome !== undefined)
103
+ return 'submitted';
104
+ if (res.lease.claimed === false)
105
+ return 'lease-lost';
106
+ }
107
+ if (o.now() >= deadline)
108
+ return 'no-submit';
109
+ await o.sleep(o.intervalMs);
110
+ }
111
+ }
112
+ export function createAgentRunLoop(opts) {
113
+ const { hub, workflow } = opts;
114
+ const runId = opts.run;
115
+ const order = orderId(workflow, runId);
116
+ let signalled = false;
117
+ let leaseSettled = false;
118
+ let torndown = false;
119
+ let leasePromise;
120
+ let adapter;
121
+ let sessionRef;
122
+ let adapterId = '';
123
+ let stepName = '';
124
+ let attempt = 1;
125
+ let createdAt = 0;
126
+ let recordCwd = opts.cwd;
127
+ /** The watermark written on every record this firing produces — see
128
+ * `SessionRecord.deliveredReasonAt`. Carried forward from the prior record
129
+ * when this firing delivered no new reasons, so it can never regress. */
130
+ let deliveredReasonAt;
131
+ let resolveOrder;
132
+ const orderReady = new Promise((r) => {
133
+ resolveOrder = r;
134
+ });
135
+ const lease = createLeaseLoop({
136
+ hub,
137
+ workflow,
138
+ run: runId,
139
+ role: 'agent-run',
140
+ holder: opts.holder,
141
+ onOrder: (res) => resolveOrder?.(res),
142
+ sleep: opts.sleep,
143
+ now: opts.now,
144
+ out: opts.out,
145
+ err: opts.err,
146
+ ...(opts.random !== undefined ? { random: opts.random } : {}),
147
+ ...(opts.heartbeatIntervalMs !== undefined ? { heartbeatIntervalMs: opts.heartbeatIntervalMs } : {}),
148
+ ...(opts.jumpToleranceMs !== undefined ? { jumpToleranceMs: opts.jumpToleranceMs } : {}),
149
+ ...(opts.failureWindowMs !== undefined ? { failureWindowMs: opts.failureWindowMs } : {}),
150
+ });
151
+ /**
152
+ * Append one session record. `harness`/`token` come from the `started` event's
153
+ * ref when there is one; before that event (a harness that died on launch)
154
+ * they fall back to the resolved adapter id and an empty token, so the store
155
+ * still shows the attempt existed and died.
156
+ */
157
+ function record(status) {
158
+ if (stepName === '')
159
+ return; // no order packet yet — nothing to key a record by
160
+ const at = opts.now();
161
+ if (createdAt === 0)
162
+ createdAt = at;
163
+ opts.appendSession({
164
+ workflow,
165
+ run: runId,
166
+ step: stepName,
167
+ order,
168
+ attempt,
169
+ harness: sessionRef?.harness ?? adapterId,
170
+ token: sessionRef?.token ?? '',
171
+ cwd: recordCwd,
172
+ status,
173
+ createdAt,
174
+ ...(deliveredReasonAt !== undefined ? { deliveredReasonAt } : {}),
175
+ updatedAt: at,
176
+ });
177
+ }
178
+ /**
179
+ * Tear the harness session down. Guarded so the signal path and the normal
180
+ * end-of-run path together still stop the session exactly once; never throws.
181
+ */
182
+ async function teardown() {
183
+ if (adapter === undefined || sessionRef === undefined || torndown)
184
+ return;
185
+ torndown = true;
186
+ try {
187
+ await adapter.stop(sessionRef);
188
+ }
189
+ catch (e) {
190
+ opts.err(`owenloop work agent-run: adapter stop failed: ${errMsg(e)} (ignored)`);
191
+ }
192
+ }
193
+ /** A first-contact / no-hold lease outcome → worker outcome. Mirrors exec. */
194
+ function mapNoHold(o) {
195
+ switch (o) {
196
+ case 'completed':
197
+ return 'completed';
198
+ case 'ownership-error':
199
+ return 'ownership-error';
200
+ case 'hub-unreachable':
201
+ return 'hub-unreachable';
202
+ case 'lease-lost':
203
+ return 'lease-lost';
204
+ case 'stopped':
205
+ return signalled ? 'killed' : 'stopped';
206
+ case 'released':
207
+ case 'release-failed':
208
+ // stop() with release fired before the hold was ever established.
209
+ return 'killed';
210
+ }
211
+ }
212
+ /**
213
+ * A lease outcome observed while the turn was still running.
214
+ *
215
+ * `'completed'` here is a SUCCESS, not a failure: the agent called `submit`
216
+ * and the lease loop's heartbeat saw the outcome before the model turn ended.
217
+ */
218
+ function mapLeaseDuringTurn(o) {
219
+ if (o === 'completed')
220
+ return 'submitted';
221
+ if (o === 'ownership-error')
222
+ return 'ownership-error';
223
+ if (o === 'hub-unreachable')
224
+ return 'hub-unreachable';
225
+ return 'lease-lost';
226
+ }
227
+ /** Log one harness event. Telemetry only — nothing here decides an outcome. */
228
+ function onEvent(e) {
229
+ switch (e.kind) {
230
+ case 'started':
231
+ sessionRef = e.ref;
232
+ opts.err(`owenloop work agent-run: session started for ${order} (harness '${e.ref.harness}')`);
233
+ // Persist on the EVENT, not on the start() resolve, so a mid-turn crash
234
+ // still leaves a resumable record behind (the contract requires this).
235
+ record('active');
236
+ return;
237
+ case 'progress':
238
+ opts.err(`owenloop work agent-run: ${e.text}`);
239
+ return;
240
+ case 'needs_input':
241
+ opts.err(`owenloop work agent-run: WARNING the step agent asked for input and this contract has no reply channel — ${e.question}`);
242
+ return;
243
+ case 'turn_ended':
244
+ opts.err(`owenloop work agent-run: turn ended for ${order} (telemetry — the hub decides the outcome)`);
245
+ return;
246
+ case 'exited':
247
+ opts.err(`owenloop work agent-run: harness exited (code ${String(e.exitCode)}${e.error !== undefined ? `, ${e.error}` : ''}) — telemetry only, ignored for the outcome`);
248
+ return;
249
+ }
250
+ }
251
+ /** Release and finish. Used by every path that hands the order back. */
252
+ async function releaseWith(reason, outcome) {
253
+ lease.stop(reason);
254
+ await leasePromise;
255
+ return outcome;
256
+ }
257
+ async function run() {
258
+ leasePromise = lease.run();
259
+ void leasePromise.then(() => {
260
+ leaseSettled = true;
261
+ });
262
+ // First contact race: the order arrives (hold established), or the lease
263
+ // resolves terminally before we ever established it.
264
+ const first = await Promise.race([
265
+ orderReady.then((res) => ({ t: 'order', res })),
266
+ leasePromise.then((o) => ({ t: 'lease', o })),
267
+ ]);
268
+ if (first.t === 'lease')
269
+ return mapNoHold(first.o);
270
+ const packet = first.res.order;
271
+ if (packet === null || packet.executor === 'command' || (typeof packet.command === 'string' && packet.command !== '')) {
272
+ opts.err(`owenloop work agent-run: ${order} is not an agent order (misroute) — releasing`);
273
+ return releaseWith('misroute', 'misroute');
274
+ }
275
+ stepName = packet.step;
276
+ recordCwd = packet.workdir ?? opts.cwd;
277
+ // The step spec. No bundle / no spec ⇒ we cannot brief anybody; release so
278
+ // the order lapses back through the hub's pickup window.
279
+ let material;
280
+ try {
281
+ material = await opts.loadStep(packet);
282
+ }
283
+ catch (e) {
284
+ opts.err(`owenloop work agent-run: loading the step spec for ${order} failed: ${errMsg(e)}`);
285
+ material = null;
286
+ }
287
+ if (material === null) {
288
+ opts.err(`owenloop work agent-run: no step spec for '${packet.step}' — releasing for the pickup window`);
289
+ return releaseWith('no-template', 'no-template');
290
+ }
291
+ /** `material` is a `let`, so its null-narrowing does not survive into the
292
+ * closures below. This const carries the narrowing across. */
293
+ const step = material;
294
+ const resolution = opts.resolveAdapter(step.harness);
295
+ adapterId = resolution.id;
296
+ if (resolution.adapter === undefined) {
297
+ const known = resolution.registered.length > 0 ? resolution.registered.join(', ') : '<none>';
298
+ opts.err(`owenloop work agent-run: no adapter registered for harness '${resolution.id}' (registered: ${known}) — releasing`);
299
+ return releaseWith('no-harness', 'no-harness');
300
+ }
301
+ adapter = resolution.adapter;
302
+ /** The same object as `adapter`, but narrowed — the module-scope `adapter`
303
+ * stays `HarnessAdapter | undefined` for `teardown`/`stop`. */
304
+ const active = resolution.adapter;
305
+ attempt = opts.nextAttempt(workflow, runId, packet.step);
306
+ const spec = {
307
+ workflow,
308
+ run: runId,
309
+ origin: opts.origin,
310
+ account: opts.account,
311
+ ...(opts.shiftId !== undefined ? { shiftId: opts.shiftId } : {}),
312
+ };
313
+ // Permissions arrive PRE-NORMALIZED in the spec. `prepare` ran
314
+ // `normalizeStepPermissions` over the step's `x.harness` options at cache
315
+ // time, so this loop never looks inside an extension bag and never has a bag
316
+ // key — vendor-keyed lookup does not exist in neutral code any more.
317
+ const permissions = step.permissions;
318
+ // ---- PHASE 4: resume or cold replay? -----------------------------------
319
+ //
320
+ // The delta first, because "is there anything new to say?" is one of the
321
+ // resume preconditions. `renderRejection` reads `packet.owes[].reasons`
322
+ // filtered to `at > prev.deliveredReasonAt` — the packet's `owes` IS the set
323
+ // of paths being re-armed, so no extra path filter is needed here.
324
+ const prev = opts.latestSession?.(workflow, runId, packet.step) ?? null;
325
+ const dirExists = opts.dirExists ?? existsSync;
326
+ const delta = renderRejection({
327
+ packet,
328
+ ...(prev?.deliveredReasonAt !== undefined ? { deliveredReasonAt: prev.deliveredReasonAt } : {}),
329
+ });
330
+ // EVERY condition must hold. Each is a separate reason, and each is a
331
+ // documented cold-start case rather than an error:
332
+ // prev !== null first firing — there is no session to resume
333
+ // prev.token !== '' the record predates its `started` event, so
334
+ // no provider token was ever minted
335
+ // prev.harness === resolution.id NEVER resume a session into a different
336
+ // vendor; the token means nothing there
337
+ // prev.status !== 'dead' a session recorded dead is not resumable
338
+ // resumeTier !== 'replay' the adapter says it has no resume at all
339
+ // prev.cwd === recordCwd the resolved working directory moved, so the
340
+ // session is scoped to the wrong place
341
+ // dirExists(prev.cwd) a reaped work dir invalidates the session
342
+ // delta.message !== '' nothing new to say — a resume that says
343
+ // nothing spends a turn communicating nothing
344
+ const resumable = prev !== null &&
345
+ prev.token !== '' &&
346
+ prev.harness === resolution.id &&
347
+ prev.status !== 'dead' &&
348
+ active.resumeTier !== 'replay' &&
349
+ prev.cwd === recordCwd &&
350
+ dirExists(prev.cwd) &&
351
+ delta.message !== '';
352
+ // The watermark this firing's records carry. It STARTS at the prior value —
353
+ // never at the delta's — and advances only once the reasons have actually
354
+ // reached the agent (`markDelivered`, called after `deliver`/`start`
355
+ // RESOLVES). Carrying the prior value forward is also what keeps a cold start
356
+ // with no new feedback from making already-delivered reasons look undelivered.
357
+ deliveredReasonAt = prev?.deliveredReasonAt;
358
+ /**
359
+ * Advance the watermark to the newest reason this firing carried.
360
+ *
361
+ * CALLED ONLY AFTER THE TURN'S DELIVERY RESOLVED. Persisting the advance
362
+ * BEFORE the delivery is attempted permanently swallows the feedback: a
363
+ * `deliver` that fails for a non-resume reason (transport/spawn failure), or
364
+ * a process that dies mid-turn, would leave a record claiming the reasons
365
+ * were delivered by a session that never conveyed them, and the next firing
366
+ * would filter every one of them out (`at > watermark`) and cold-start with a
367
+ * BARE brief — so the agent would never learn why it was rejected and would
368
+ * repeat the rejected submission.
369
+ *
370
+ * The `ResumeUnavailable` → cold-replay fallback stays correct because
371
+ * `coldArgs()` re-renders from `prev?.deliveredReasonAt`, not from this
372
+ * variable.
373
+ */
374
+ function markDelivered() {
375
+ if (delta.deliveredReasonAt !== undefined)
376
+ deliveredReasonAt = delta.deliveredReasonAt;
377
+ }
378
+ const owenloopMcp = buildOwenloopMcp(spec);
379
+ const deliverArgs = {
380
+ cwd: recordCwd,
381
+ owenloopMcp,
382
+ permissions,
383
+ ...(packet.model !== undefined ? { model: packet.model } : {}),
384
+ };
385
+ /** Built lazily: a cold start after a refused resume needs a FRESH one. */
386
+ const coldArgs = () => ({
387
+ // The replay brief is the ordinary brief PLUS a trailing rejection section,
388
+ // capped at roughly 100k tokens. With no delta it is just the brief.
389
+ brief: renderReplayBrief(renderBrief(step.brief, spec), {
390
+ packet,
391
+ ...(prev?.deliveredReasonAt !== undefined
392
+ ? { deliveredReasonAt: prev.deliveredReasonAt }
393
+ : {}),
394
+ }),
395
+ cwd: recordCwd,
396
+ owenloopMcp,
397
+ permissions,
398
+ ...(packet.model !== undefined ? { model: packet.model } : {}),
399
+ });
400
+ const path = resumable ? 'resume' : delta.message !== '' ? 'cold replay' : 'cold start';
401
+ opts.out(`owenloop work agent-run: hosting ${order} (step '${packet.step}', harness '${resolution.id}', attempt ${attempt}, ${path})`);
402
+ /** Cold-start this firing. Shared by the ordinary path and the fallback. */
403
+ async function coldStart() {
404
+ try {
405
+ const ref = await active.start(coldArgs(), onEvent);
406
+ sessionRef = ref;
407
+ // The replay brief carried the reasons, and the turn it opened has now
408
+ // ended — only here is the watermark honest. (The `active` row written
409
+ // from the `started` event fires INSIDE this call and therefore still
410
+ // carries the prior watermark, which is the safe direction: a crash
411
+ // between the two re-delivers rather than swallows.)
412
+ markDelivered();
413
+ return { t: 'turn' };
414
+ }
415
+ catch (e) {
416
+ return { t: 'turn', failure: e };
417
+ }
418
+ }
419
+ /**
420
+ * One turn, by whichever path the decision above picked. NEVER rejects: both
421
+ * settle shapes are folded into one 'turn' result on purpose (the closed
422
+ * contract question — see this file's header).
423
+ */
424
+ async function chooseTurn() {
425
+ if (!resumable || prev === null)
426
+ return coldStart();
427
+ // Resume keeps the PRIOR token, so the store shows two rows for the same
428
+ // `(workflow, run, step)` with the same token and successive attempts —
429
+ // which is how "same session" is observable at all. `deliver` never emits
430
+ // `started`, so the record has to be written here rather than from the
431
+ // event, and `createdAt` is the SESSION's birth, not this attempt's.
432
+ sessionRef = { harness: prev.harness, token: prev.token };
433
+ createdAt = prev.createdAt;
434
+ opts.err(`owenloop work agent-run: resuming session ${prev.token} for ${order} with ${delta.count} new rejection reason${delta.count === 1 ? '' : 's'} (no brief re-sent)`);
435
+ // Deliberately written with the PRIOR watermark: nothing has been delivered
436
+ // yet, and this row is what the next firing reads if this turn never
437
+ // completes. See `markDelivered`.
438
+ record('active');
439
+ try {
440
+ await active.deliver(sessionRef, delta.message, deliverArgs, onEvent);
441
+ markDelivered();
442
+ return { t: 'turn' };
443
+ }
444
+ catch (e) {
445
+ if (!isResumeUnavailable(e))
446
+ return { t: 'turn', failure: e };
447
+ // The provider forgot the session. The order is still leased, so falling
448
+ // back HERE costs one cold start; handing it back would cost a whole
449
+ // re-offer cycle to rediscover the same fact.
450
+ opts.err(`owenloop work agent-run: resume of session ${prev.token} was refused (${errMsg(e)}) — falling back to a cold replay in this same firing`);
451
+ // Forget the dead session so the `started` event mints a new record with
452
+ // a NEW token and its own createdAt, and so teardown does not try to stop
453
+ // a session the provider has already lost.
454
+ sessionRef = undefined;
455
+ createdAt = 0;
456
+ return coldStart();
457
+ }
458
+ }
459
+ const turnDone = chooseTurn();
460
+ const raced = await Promise.race([turnDone, leasePromise.then((o) => ({ t: 'lease', o }))]);
461
+ if (raced.t === 'lease') {
462
+ await teardown();
463
+ if (raced.o === 'completed') {
464
+ opts.out(`owenloop work agent-run: ${order} completed mid-turn (the hub reported an outcome)`);
465
+ record('submitted');
466
+ return 'submitted';
467
+ }
468
+ record('dead');
469
+ if (signalled) {
470
+ opts.err(`owenloop work agent-run: signalled mid-turn — tore the session down, released ${order}`);
471
+ return 'killed';
472
+ }
473
+ opts.err(`owenloop work agent-run: lease ${raced.o} mid-turn — tore the session down, no outcome observed`);
474
+ return mapLeaseDuringTurn(raced.o);
475
+ }
476
+ // TURN END — NOT task end. Log the failure shape for humans, then confirm.
477
+ if (raced.failure !== undefined) {
478
+ const why = isResumeUnavailable(raced.failure)
479
+ ? `the harness could not resume the session (${errMsg(raced.failure)})`
480
+ : errMsg(raced.failure);
481
+ opts.err(`owenloop work agent-run: the turn failed (${why}) — confirming with the hub before deciding anything`);
482
+ }
483
+ record('turn-ended');
484
+ const confirmed = await Promise.race([
485
+ confirmOutcome({
486
+ hub,
487
+ workflow,
488
+ run: runId,
489
+ holder: opts.holder,
490
+ sleep: opts.sleep,
491
+ now: opts.now,
492
+ err: opts.err,
493
+ intervalMs: opts.confirmIntervalMs ?? DEFAULT_CONFIRM_INTERVAL_MS,
494
+ graceMs: opts.submitGraceMs ?? DEFAULT_SUBMIT_GRACE_MS,
495
+ cancelled: () => signalled || leaseSettled,
496
+ }).then((v) => ({ t: 'confirm', v })),
497
+ leasePromise.then((o) => ({ t: 'lease', o })),
498
+ ]);
499
+ await teardown();
500
+ if (confirmed.t === 'lease') {
501
+ if (confirmed.o === 'completed') {
502
+ record('submitted');
503
+ opts.out(`owenloop work agent-run: ${order} submitted (the lease loop observed the hub outcome)`);
504
+ return 'submitted';
505
+ }
506
+ record('dead');
507
+ if (signalled)
508
+ return 'killed';
509
+ return mapLeaseDuringTurn(confirmed.o);
510
+ }
511
+ switch (confirmed.v) {
512
+ case 'submitted':
513
+ record('submitted');
514
+ opts.out(`owenloop work agent-run: ${order} submitted (confirmed by the hub) — stopping without release`);
515
+ // The run has CLOSED. Releasing after a close is a confusing no-op that
516
+ // races nothing useful, so stop the lease without one.
517
+ lease.stop('submitted', { release: false });
518
+ await leasePromise;
519
+ return 'submitted';
520
+ case 'lease-lost':
521
+ record('dead');
522
+ opts.err(`owenloop work agent-run: the claim on ${order} is gone and no outcome was reported — not releasing`);
523
+ lease.stop('lease-lost', { release: false });
524
+ await leasePromise;
525
+ return 'lease-lost';
526
+ case 'no-submit':
527
+ record('dead');
528
+ opts.err(`owenloop work agent-run: the turn ended and no submit reached the hub within the confirm grace — releasing ${order} for re-offer`);
529
+ // Release so the hub re-offers immediately instead of waiting out the
530
+ // claim TTL. This is the ONLY path that releases on a turn end.
531
+ return releaseWith('no-submit', 'no-submit');
532
+ }
533
+ }
534
+ function stop(reason) {
535
+ if (signalled)
536
+ return;
537
+ signalled = true;
538
+ void teardown();
539
+ lease.stop(reason ?? 'signal'); // release:true — hand the killed order back
540
+ }
541
+ return { run, stop };
542
+ }