owenloop 0.5.8 → 0.5.9

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 (87) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +4 -2
  3. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  4. package/dist/packages/work/src/agent/loop.js +48 -6
  5. package/dist/packages/work/src/consumed-verifier.js +6 -17
  6. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  7. package/dist/packages/work/src/exec/loop.js +181 -32
  8. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  9. package/dist/packages/work/src/exec/receipt.js +6 -6
  10. package/dist/packages/work/src/harness/claude.js +100 -0
  11. package/dist/packages/work/src/hub/client.d.ts +19 -4
  12. package/dist/packages/work/src/hub/client.js +7 -3
  13. package/dist/packages/work/src/hub/types.d.ts +84 -0
  14. package/dist/packages/work/src/main.js +1 -0
  15. package/dist/packages/work/src/roles/agent-run.js +19 -22
  16. package/dist/packages/work/src/roles/exec.js +2 -0
  17. package/dist/packages/work/src/roles/settings.js +2 -0
  18. package/dist/packages/work/src/roles/shift.js +14 -2
  19. package/dist/packages/work/src/roles/util.d.ts +1 -0
  20. package/dist/packages/work/src/roles/util.js +10 -0
  21. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  22. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  23. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  24. package/dist/packages/work/src/settings/roster.js +364 -5
  25. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  26. package/dist/packages/work/src/settings/serving.js +79 -0
  27. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  28. package/dist/packages/work/src/settings/settings.js +14 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  30. package/dist/packages/work/src/shift/loop.js +299 -51
  31. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  32. package/dist/packages/work/src/shift/runtime.d.ts +15 -0
  33. package/dist/packages/work/src/shift/runtime.js +94 -4
  34. package/dist/packages/work/src/shift/server.js +2 -0
  35. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  36. package/dist/packages/work/src/shift/spawn.js +16 -13
  37. package/dist/packages/work/src/shift/state.d.ts +29 -2
  38. package/dist/packages/work/src/shift/state.js +45 -15
  39. package/dist/packages/work/src/usage.d.ts +1 -1
  40. package/dist/packages/work/src/usage.js +7 -1
  41. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  42. package/dist/packages/work/src/util/modifier-init.js +73 -0
  43. package/dist/src/bundle/tar.d.ts +9 -4
  44. package/dist/src/bundle/tar.js +9 -4
  45. package/dist/src/capabilities.d.ts +6 -0
  46. package/dist/src/cli.d.ts +14 -1
  47. package/dist/src/cli.js +687 -75
  48. package/dist/src/config-dir.d.ts +1 -1
  49. package/dist/src/config-dir.js +1 -1
  50. package/dist/src/crypto/index.d.ts +1 -1
  51. package/dist/src/crypto/index.js +1 -1
  52. package/dist/src/crypto/org-root.d.ts +30 -12
  53. package/dist/src/crypto/org-root.js +162 -14
  54. package/dist/src/crypto/records.d.ts +2 -0
  55. package/dist/src/crypto/records.js +2 -0
  56. package/dist/src/defs.d.ts +6 -1
  57. package/dist/src/defs.js +203 -8
  58. package/dist/src/engine.d.ts +42 -7
  59. package/dist/src/engine.js +158 -16
  60. package/dist/src/index.d.ts +4 -4
  61. package/dist/src/index.js +2 -2
  62. package/dist/src/mcp/serve.d.ts +22 -0
  63. package/dist/src/mcp/serve.js +88 -8
  64. package/dist/src/model.d.ts +2 -0
  65. package/dist/src/model.js +32 -25
  66. package/dist/src/order-resolver.d.ts +1 -0
  67. package/dist/src/order-resolver.js +8 -1
  68. package/dist/src/schemas/index.d.ts +11 -0
  69. package/dist/src/schemas/order.v1.schema.json +7 -1
  70. package/dist/src/store.d.ts +5 -0
  71. package/dist/src/store.js +43 -8
  72. package/dist/src/types.d.ts +40 -3
  73. package/docs/authoring.md +90 -2
  74. package/docs/bundles.md +26 -2
  75. package/docs/cli.md +170 -28
  76. package/docs/crypto.md +19 -3
  77. package/docs/design.md +70 -1
  78. package/docs/routing.md +189 -34
  79. package/docs/shift-logs.md +20 -9
  80. package/docs/wire-contracts.md +50 -7
  81. package/examples/workflows/delivery.yaml +31 -14
  82. package/examples/workflows/ship.yaml +10 -2
  83. package/package.json +1 -1
  84. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  85. package/plugins/claude-code/plugin/.mcp.json +1 -1
  86. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  87. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
@@ -1,7 +1,8 @@
1
+ import { type AcquireFileLockOpts } from '../../../../src/lock.ts';
1
2
  import type { HubClient } from '../hub/client.ts';
2
3
  import { type WorkOrder } from '../hub/types.ts';
3
4
  import type { FetchedStep } from '../bundle/types.ts';
4
- import { type Liveness } from './state.ts';
5
+ import { type ReconcileOptions, type Liveness } from './state.ts';
5
6
  import { sweepWorkDirs as sweepWorkDirsImpl } from '../agent/workdir.ts';
6
7
  import type { Spawner } from './spawn.ts';
7
8
  import { type ShiftEvent } from './protocol.ts';
@@ -22,7 +23,8 @@ export interface ShiftLoopOptions {
22
23
  onEvent?: (event: ShiftEvent) => void;
23
24
  cacheDir: string;
24
25
  stateDir: string;
25
- /** Max concurrent in-flight orders (exec + agent-run children). */
26
+ /** Max concurrent in-flight orders (exec + agent-run children), including
27
+ * any slots reserved from the agent lane for exec work. */
26
28
  cap: number;
27
29
  /** Serve crews this shift accepts (sent to presence + whats_next). INITIAL
28
30
  * value only — live-mutable via the `ShiftLoop.setShift` (MCP `clock_in`). */
@@ -49,12 +51,37 @@ export interface ShiftLoopOptions {
49
51
  resolveOrderStep?: (order: WorkOrder) => Promise<FetchedStep | undefined>;
50
52
  pollIntervalMs: number;
51
53
  presenceIntervalMs: number;
54
+ /** Weak hub-roster cache refresh cadence; undefined disables refresh. */
55
+ rosterSyncIntervalMs?: number;
56
+ /** Upper bound for one low-priority refresh attempt. */
57
+ rosterSyncTimeoutMs?: number;
58
+ /** Daemon-owned cache write, injected so failure cannot kill the loop. */
59
+ syncRosters?: (signal: AbortSignal) => Promise<void>;
60
+ /**
61
+ * Compute the serving set for the live serve crews. Kept injectable so the
62
+ * loop does no filesystem work; absent means the legitimate empty set.
63
+ */
64
+ computeServeCapabilities?: (crews: readonly string[]) => string[];
52
65
  /**
53
66
  * Max concurrent `agent-run` children (default 4). A SECOND budget, applied
54
- * ON TOP OF `cap` — never a replacement for it. An agent turn is long and
55
- * memory-heavy where a command is short, so the two cannot share one number.
67
+ * INSIDE `cap` — never a replacement for it. The effective budget also
68
+ * accounts for `execReserve`. An agent turn is long and memory-heavy where
69
+ * a command is short, so the two cannot share one number.
56
70
  */
57
71
  maxConcurrentAgents?: number;
72
+ /**
73
+ * Slots INSIDE `cap` that `agent-run` children may never occupy, so an
74
+ * exec/command order always has somewhere to land (default 1).
75
+ *
76
+ * A scheduling control, not a capacity one: it never raises the total child
77
+ * ceiling. Clamped to `cap - 1` so it cannot consume the whole cap.
78
+ */
79
+ execReserve?: number;
80
+ /**
81
+ * How long to retain a claim this shift cannot dispatch before returning it
82
+ * to the hub. Defaults to 0: do not queue locally.
83
+ */
84
+ localQueueHoldMs?: number;
58
85
  /**
59
86
  * PHASE 4 — the root under which per-RUN agent work directories live
60
87
  * (`<workRoot>/<workflow>/<run>/`). ABSENT DISABLES THE REAPER entirely: with
@@ -72,10 +99,34 @@ export interface ShiftLoopOptions {
72
99
  once?: boolean;
73
100
  /** Injectable liveness probe (tests). */
74
101
  isAlive?: Liveness;
102
+ /** Test seam for deterministic races at the shared dispatch lock. */
103
+ dispatchLockOptions?: Pick<AcquireFileLockOpts, 'beforeOpen'>;
75
104
  /** PHASE 4 — injected in tests so the reaper can be exercised without a
76
105
  * filesystem. Defaults to `sweepWorkDirs` from `src/agent/workdir.ts`. */
77
106
  sweepWorkDirs?: typeof sweepWorkDirsImpl;
78
107
  }
108
+ export interface LockedRemovalOptions {
109
+ dispatchLockOptions?: Pick<AcquireFileLockOpts, 'beforeOpen'>;
110
+ waitMs?: number;
111
+ label?: string;
112
+ }
113
+ /** Run a state mutation while holding the lock that serializes dispatch state. */
114
+ export declare function withDispatchLock<T>(stateDir: string, options: LockedRemovalOptions | undefined, fn: () => T): T;
115
+ /**
116
+ * Remove one child record while holding the same lock that serializes durable
117
+ * reservation creation. The record is deliberately re-read by
118
+ * `removeChildRecord` only after acquisition, so a stale observer cannot erase
119
+ * a newer dispatch for the same run.
120
+ */
121
+ export declare function removeChildRecordUnderDispatchLock(stateDir: string, run: string, recordOptions?: {
122
+ pid?: number;
123
+ }, options?: LockedRemovalOptions): boolean;
124
+ /**
125
+ * Reconciliation callbacks for every unlocked Shift daemon path. Keep these
126
+ * together with the lock-held removal primitive so startup and the poll loop
127
+ * cannot silently diverge.
128
+ */
129
+ export declare function createLockedRemovalCallbacks(stateDir: string, options?: LockedRemovalOptions): Pick<ReconcileOptions, 'removeAbandonedReservation' | 'removeDeadChild' | 'settleLiveChild'>;
79
130
  export interface ShiftLoop {
80
131
  run(): Promise<number>;
81
132
  stop(): void;
@@ -90,6 +141,8 @@ export interface ShiftLoop {
90
141
  freeCapacity(): number;
91
142
  /** Live dispatch-cap used by status and next responses. */
92
143
  getCap(): number;
144
+ /** Live agent-lane ceiling after the exec reserve is applied. */
145
+ agentCeiling(): number;
93
146
  /** Adjust the live dispatch cap for internal callers and tests. */
94
147
  setCap(cap: number): void;
95
148
  /** The shift's live identity: the presence name and the crew scope (`serve_crews`)
@@ -99,6 +152,8 @@ export interface ShiftLoop {
99
152
  name: string;
100
153
  serveCrews: string[];
101
154
  };
155
+ /** The derived serving set currently advertised to the hub. */
156
+ getServeCapabilities(): string[];
102
157
  /** Set the live shift identity (the socket `clock_in` operation). A field left ABSENT is
103
158
  * left unchanged; `serveCrews: []` explicitly means "all crews". Also makes the
104
159
  * next presence ping due immediately, so the new identity reaches the hub on the
@@ -124,6 +179,17 @@ export interface ShiftLoop {
124
179
  * next reconcile's pid probe frees the slot anyway.
125
180
  */
126
181
  noteRunEnded(run: string): void;
182
+ /**
183
+ * A dispatched worker process ENDED. Frees the dispatch slot it held on every
184
+ * terminal outcome, including a mid-turn completion that exits 0. This is the
185
+ * primary release path; reconciliation remains the crash/restart backstop.
186
+ */
187
+ noteChildExited(exit: {
188
+ workflow: string;
189
+ run: string;
190
+ kind: 'exec' | 'agent-run';
191
+ pid: number;
192
+ }): void;
127
193
  /**
128
194
  * A dispatched child exited non-zero. Charges one failure against that run's
129
195
  * STEP and arms the brake window — see `STEP_BRAKE_DELAYS_MS`.
@@ -142,9 +208,46 @@ export interface ShiftLoop {
142
208
  run: string;
143
209
  }): void;
144
210
  }
211
+ /** The hub reaps a never-contacted claim after this long. Every client-side
212
+ * re-offer latency must stay strictly under it. */
213
+ export declare const HUB_PICKUP_WINDOW_MS = 120000;
145
214
  /**
146
215
  * The hub reaps a never-contacted claim after 120 seconds. Stop local queueing
147
216
  * after 90 seconds so a detached child retains 30 seconds to make first contact.
148
217
  */
149
- export declare const MAX_PENDING_CANDIDATE_AGE_MS = 90000;
218
+ export declare const MAX_PENDING_CANDIDATE_AGE_MS: number;
219
+ /**
220
+ * THE PER-STEP FAILURE BRAKE.
221
+ *
222
+ * Every in-flight guard in this file keys on the RUN id — `liveRuns`,
223
+ * `workerRuns`, `claimed`, `pendingCandidates`. That is correct for the case
224
+ * they were written for: one claim, one child. It is blind to the case where a
225
+ * step fails the same way forever.
226
+ *
227
+ * Observed 2026-08-12: `local-check` of one instance was dispatched five-plus
228
+ * times in seconds under a DIFFERENT run id each time
229
+ * (run_fd94d88a…, run_5ec4d807…, run_d8cdf03f…, run_67c8e2db…, run_072755ba…).
230
+ * The child refused its consumed artifact, exited non-zero WITHOUT submitting,
231
+ * the hub released the claim, and the next poll handed the same step back under
232
+ * a fresh run id. A fresh run id matches none of the run-keyed guards, so
233
+ * nothing bounded the respawns.
234
+ *
235
+ * So the brake is keyed on the identity that actually repeats — the STEP, as
236
+ * `(workflow, step, key)`. `key` is part of the identity because a fanned-out
237
+ * step has one legitimately concurrent order per key, and those must not brake
238
+ * each other.
239
+ *
240
+ * WHAT IS COUNTED, AND WHY IT IS NOT DISPATCHES. The event counted against that
241
+ * key is a WORKER FAILURE — a child that exited non-zero, reported into the
242
+ * loop through `noteWorkerFailure` — never a dispatch. Counting dispatches
243
+ * conflates a storm with legitimate concurrency: the hub can offer several
244
+ * DISTINCT runs of one step in a single sweep, and metering the second through
245
+ * fifth of those would throttle healthy work. A failure is direct evidence that
246
+ * running this step again right now is unlikely to help; a dispatch is evidence
247
+ * of nothing.
248
+ *
249
+ * It is a rate limit, never a ban. A step that has not failed is dispatched
250
+ * with zero delay, however many orders arrive for it at once.
251
+ */
252
+ export declare const STEP_BRAKE_DELAYS_MS: readonly [2000, 8000, 30000, 60000, 90000];
150
253
  export declare function createShiftLoop(opts: ShiftLoopOptions): ShiftLoop;