owenloop 0.5.6 → 0.5.8

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 (82) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +3 -6
  3. package/dist/packages/work/src/agent/approvals.d.ts +53 -0
  4. package/dist/packages/work/src/agent/approvals.js +132 -0
  5. package/dist/packages/work/src/agent/brief.d.ts +12 -0
  6. package/dist/packages/work/src/agent/brief.js +51 -0
  7. package/dist/packages/work/src/agent/capability-model.d.ts +64 -82
  8. package/dist/packages/work/src/agent/capability-model.js +94 -91
  9. package/dist/packages/work/src/agent/loop.d.ts +43 -25
  10. package/dist/packages/work/src/agent/loop.js +135 -50
  11. package/dist/packages/work/src/bundle/types.d.ts +3 -3
  12. package/dist/packages/work/src/exec/loop.js +37 -15
  13. package/dist/packages/work/src/harness/child-env.js +4 -5
  14. package/dist/packages/work/src/harness/claude.d.ts +4 -0
  15. package/dist/packages/work/src/harness/claude.js +72 -3
  16. package/dist/packages/work/src/harness/codex.d.ts +37 -1
  17. package/dist/packages/work/src/harness/codex.js +136 -18
  18. package/dist/packages/work/src/harness/contract.d.ts +54 -1
  19. package/dist/packages/work/src/harness/session-store.d.ts +127 -17
  20. package/dist/packages/work/src/harness/session-store.js +157 -60
  21. package/dist/packages/work/src/hub/client.d.ts +13 -1
  22. package/dist/packages/work/src/hub/client.js +3 -0
  23. package/dist/packages/work/src/hub/types.d.ts +104 -3
  24. package/dist/packages/work/src/main.js +1 -0
  25. package/dist/packages/work/src/roles/agent-run.js +52 -42
  26. package/dist/packages/work/src/roles/approvals.d.ts +76 -0
  27. package/dist/packages/work/src/roles/approvals.js +231 -0
  28. package/dist/packages/work/src/roles/sessions.d.ts +3 -2
  29. package/dist/packages/work/src/roles/sessions.js +9 -2
  30. package/dist/packages/work/src/roles/settings.js +1 -1
  31. package/dist/packages/work/src/settings/roster.d.ts +21 -0
  32. package/dist/packages/work/src/settings/roster.js +80 -0
  33. package/dist/packages/work/src/settings/settings.d.ts +12 -24
  34. package/dist/packages/work/src/settings/settings.js +17 -35
  35. package/dist/packages/work/src/shift/loop.d.ts +2 -0
  36. package/dist/packages/work/src/shift/loop.js +2 -0
  37. package/dist/packages/work/src/shift/runtime.js +17 -9
  38. package/dist/packages/work/src/shift/spawn.d.ts +10 -53
  39. package/dist/packages/work/src/shift/spawn.js +28 -60
  40. package/dist/packages/work/src/usage.d.ts +1 -1
  41. package/dist/packages/work/src/usage.js +8 -4
  42. package/dist/src/capabilities.d.ts +44 -0
  43. package/dist/src/capabilities.js +38 -0
  44. package/dist/src/cli.d.ts +1 -0
  45. package/dist/src/cli.js +460 -5
  46. package/dist/src/config-dir.d.ts +13 -18
  47. package/dist/src/config-dir.js +15 -23
  48. package/dist/src/credentials.d.ts +1 -1
  49. package/dist/src/credentials.js +1 -1
  50. package/dist/src/crypto/records.d.ts +3 -0
  51. package/dist/src/crypto/records.js +19 -0
  52. package/dist/src/crypto/trust-roots.d.ts +2 -2
  53. package/dist/src/crypto/trust-roots.js +2 -2
  54. package/dist/src/engine.d.ts +14 -0
  55. package/dist/src/engine.js +26 -14
  56. package/dist/src/global-config.d.ts +4 -7
  57. package/dist/src/global-config.js +4 -7
  58. package/dist/src/hub.d.ts +207 -5
  59. package/dist/src/hub.js +263 -3
  60. package/dist/src/index.d.ts +2 -2
  61. package/dist/src/index.js +1 -1
  62. package/dist/src/model.d.ts +37 -1
  63. package/dist/src/model.js +47 -1
  64. package/dist/src/schemas/index.d.ts +19 -0
  65. package/dist/src/schemas/order.v1.schema.json +15 -1
  66. package/dist/src/store/pre-commit-verifier.js +1 -1
  67. package/dist/src/types.d.ts +58 -4
  68. package/dist/src/work-settings.d.ts +2 -4
  69. package/dist/src/work-settings.js +2 -4
  70. package/docs/agent-runner.md +2 -2
  71. package/docs/bundles.md +3 -1
  72. package/docs/cli.md +295 -101
  73. package/docs/crypto.md +14 -14
  74. package/docs/routing.md +607 -0
  75. package/docs/shift-logs.md +22 -6
  76. package/package.json +1 -1
  77. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  78. package/plugins/claude-code/plugin/.mcp.json +1 -1
  79. package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
  80. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  81. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  82. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
@@ -52,6 +52,7 @@
52
52
  import { closeSync, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
53
53
  import { join } from 'node:path';
54
54
  import { acquireFileLockSync, releaseFileLock } from "../../../../src/lock.js";
55
+ import { defaultIsAlive } from "../shift/state.js";
55
56
  const STATUSES = new Set(['active', 'turn-ended', 'submitted', 'dead']);
56
57
  /** Default compaction threshold — plan §3's 2 MB. */
57
58
  export const DEFAULT_MAX_BYTES = 2_000_000;
@@ -83,10 +84,12 @@ function isNonEmptyString(v) {
83
84
  * The non-empty-string fields `isSessionRecord` requires, in the order it checks
84
85
  * them. Declared once and kept stable so a record failing several checks always
85
86
  * reports the SAME field, which keeps the skip message deterministic.
86
- * `status` is not here — its check is a membership test, not a string test — and
87
- * is applied after these, preserving the original check order.
87
+ *
88
+ * `token` is NOT here — see `firstInvalidSessionRecordField`. `status` is not
89
+ * here either: its check is a membership test, not a string test, and is applied
90
+ * after these, preserving the original check order.
88
91
  */
89
- const SESSION_RECORD_STRING_FIELDS = ['workflow', 'run', 'step', 'harness', 'token'];
92
+ const SESSION_RECORD_STRING_FIELDS = ['workflow', 'run', 'step', 'harness'];
90
93
  /**
91
94
  * Name of the first field of `v` that fails the `SessionRecord` schema, or
92
95
  * `null` when the record is valid. `'<root>'` means `v` is not a plain object at
@@ -96,9 +99,43 @@ const SESSION_RECORD_STRING_FIELDS = ['workflow', 'run', 'step', 'harness', 'tok
96
99
  * in terms of this function, so the accept/reject decision and the reported
97
100
  * field name can never drift apart.
98
101
  *
99
- * Checks exactly the fields whose absence would make the record unusable for a
100
- * resume: the three key fields plus the harness and token it exists to carry,
101
- * and a `status` inside the four literals. Everything else is carried verbatim.
102
+ * Checks exactly the fields whose absence would make the record unusable: the
103
+ * three key fields, the harness that says which vendor the row belongs to, a
104
+ * `token` that is a string, and a `status` inside the four literals. Everything
105
+ * else is carried verbatim.
106
+ *
107
+ * ── WHY AN EMPTY `token` IS VALID, THOUGH IT ONCE WAS NOT ────────────────────
108
+ *
109
+ * `token` must be a STRING, but it may be EMPTY. The writer produces an empty
110
+ * one deliberately: `agent/loop.ts` appends a record before the harness emits
111
+ * its `started` event, so that a harness which dies on launch still leaves proof
112
+ * the attempt existed and died. Its own comment says so. Requiring the token to
113
+ * be non-empty here threw exactly those records away — the reader discarded the
114
+ * evidence the writer went out of its way to leave.
115
+ *
116
+ * The cost was not only the lost rows. Every such line was reported on stdout as
117
+ * `field "token" failed schema check`, once per reading process. On this machine
118
+ * that was ~94 lines printed by each of three shifts on every boot: ~280 warning
119
+ * lines about records that were behaving exactly as designed, drowning the
120
+ * warnings that meant something.
121
+ *
122
+ * Nothing downstream is harmed by admitting them, because every consumer already
123
+ * expected the empty case and guarded for it BEFORE this change:
124
+ * - `agent/loop.ts` requires `prev.token !== ''` to resume, with a comment
125
+ * naming this exact case ("the record predates its `started` event").
126
+ * - `roles/sessions.ts` renders no resume command for one.
127
+ * - `shouldRetireSession` reads `pid`/owner/`status` and never the token.
128
+ *
129
+ * The guard in the loop is in fact PROOF of the intent: it is unreachable code
130
+ * unless records with an empty token can be read back.
131
+ *
132
+ * ── WHY `key` IS CHECKED ONLY WHEN PRESENT ───────────────────────────────────
133
+ *
134
+ * `key` was added after rows already existed, so ABSENT is legal and means "this
135
+ * row predates the field". PRESENT-BUT-NOT-A-STRING is not legal: it would be a
136
+ * row nobody wrote, and `latestForTask` would silently mis-key it. `''` is a
137
+ * perfectly good key — it is what an unfanned step carries — so emptiness is
138
+ * never the test here.
102
139
  */
103
140
  function firstInvalidSessionRecordField(v) {
104
141
  if (typeof v !== 'object' || v === null || Array.isArray(v))
@@ -108,6 +145,13 @@ function firstInvalidSessionRecordField(v) {
108
145
  if (!isNonEmptyString(r[field]))
109
146
  return field;
110
147
  }
148
+ // Checked after `harness` and before `status`, which is where it sat when it
149
+ // was a non-empty check, so a record failing several fields still reports the
150
+ // same one it always did.
151
+ if (typeof r['token'] !== 'string')
152
+ return 'token';
153
+ if (r['key'] !== undefined && typeof r['key'] !== 'string')
154
+ return 'key';
111
155
  if (typeof r['status'] !== 'string' || !STATUSES.has(r['status']))
112
156
  return 'status';
113
157
  return null;
@@ -285,6 +329,11 @@ export function readSessions(file, opts = {}) {
285
329
  // debugging after a file-integrity problem that did not exist. The second
286
330
  // pass runs only on this failure branch, so valid records pay nothing.
287
331
  // The field NAME only, never its value — `token` is credential-shaped.
332
+ //
333
+ // Those empty-`token` records are no longer invalid at all — the schema
334
+ // admits them now (see `firstInvalidSessionRecordField`). Reaching this
335
+ // branch therefore means something genuinely wrong with the record, which
336
+ // is what makes the line worth printing.
288
337
  const badField = firstInvalidSessionRecordField(parsed) ?? '<unknown>';
289
338
  warn(`owenloop work sessions: skipping invalid record at ${file}:${i + 1}: field "${badField}" failed schema check`);
290
339
  continue;
@@ -294,9 +343,19 @@ export function readSessions(file, opts = {}) {
294
343
  return out;
295
344
  }
296
345
  /**
297
- * The newest record for `(workflow, run, step)`, or `null` when the file is
298
- * missing or holds no match. Scans forward and keeps the LAST match (last-wins).
299
- * Side-effect-free — it never writes, never compacts, and never throws.
346
+ * The newest record for `(workflow, run, step)` — that is, for ONE FIRING of one
347
+ * step — or `null` when the file is missing or holds no match. Scans forward and
348
+ * keeps the LAST match (last-wins). Side-effect-free: it never writes, never
349
+ * compacts, and never throws.
350
+ *
351
+ * ── THIS IS THE PER-FIRING LOOKUP. IT CANNOT FIND A PREVIOUS FIRING. ─────────
352
+ *
353
+ * The hub mints a fresh `run` id every time it claims a step. Two firings of the
354
+ * same step therefore NEVER share a `run`, so this function can only ever return
355
+ * a record written during the very firing that is asking. Use it for questions
356
+ * that really are about one firing — "did THIS firing already take a work dir?",
357
+ * "which sessions belong to the run I am tearing down?" — and never to ask "has
358
+ * this step run before?". That second question is `latestForTask`.
300
359
  */
301
360
  export function latestFor(file, workflow, run, step) {
302
361
  const want = keyOf(workflow, run, step);
@@ -307,6 +366,43 @@ export function latestFor(file, workflow, run, step) {
307
366
  }
308
367
  return best;
309
368
  }
369
+ /** Identity of an engine TASK. Same JSON-array encoding as `keyOf`, and for the
370
+ * same reason: no combination of field values can collide into one key. */
371
+ function taskKeyOf(task) {
372
+ return JSON.stringify([task.workflow, task.step, task.key]);
373
+ }
374
+ /**
375
+ * The newest record for an engine TASK — the last session recorded for this
376
+ * step at this key, no matter which firing wrote it — or `null` when there is
377
+ * none. Last-wins, side-effect-free, same as `latestFor`.
378
+ *
379
+ * ── WHY THIS EXISTS ALONGSIDE `latestFor` ────────────────────────────────────
380
+ *
381
+ * `latestFor` keys on `run`, which the hub re-mints per firing, so it answers
382
+ * "what happened during THIS firing?". Resume needs the opposite question: "did
383
+ * a previous firing of this same step leave a session I can re-enter?" Only
384
+ * `(workflow, step, key)` survives long enough to answer that.
385
+ *
386
+ * ── WHY A ROW WITHOUT `key` NEVER MATCHES ────────────────────────────────────
387
+ *
388
+ * Rows written before `key` existed carry no task identity at all. Guessing one
389
+ * — treating absent as `''`, say — would attribute an unfanned row and a fanned
390
+ * row to the same task and hand a worker someone else's session. Skipping them
391
+ * costs only a cold start on the first firing after upgrade, which is the safe
392
+ * direction to be wrong in. The test is `=== undefined`, because `''` is a real
393
+ * key that must match.
394
+ */
395
+ export function latestForTask(file, task) {
396
+ const want = taskKeyOf(task);
397
+ let best = null;
398
+ for (const rec of readSessions(file)) {
399
+ if (rec.key === undefined)
400
+ continue;
401
+ if (taskKeyOf({ workflow: rec.workflow, step: rec.step, key: rec.key }) === want)
402
+ best = rec;
403
+ }
404
+ return best;
405
+ }
310
406
  /** The lock shared by append and compaction for one session log. */
311
407
  function writerLockPath(file) {
312
408
  return `${file}.lock`;
@@ -456,57 +552,51 @@ export function markRunSessionsDead(file, workflow, run, now, opts = {}) {
456
552
  });
457
553
  }
458
554
  /**
459
- * PHASE 6, ITEM 4 — retire the `active` sessions of runs that are no longer
460
- * running, so a crash or a reboot does not leave the store claiming a turn is in
461
- * flight when no process exists.
462
- *
463
- * WHAT IS BROKEN WITHOUT THIS. `src/agent/loop.ts` writes `status: 'active'` when
464
- * a turn starts and rewrites it at turn end. A worker killed mid-turn — SIGKILL,
465
- * a panic, a reboot — never reaches the rewrite, so the newest row for that step
466
- * says `active` forever. Nothing else ever corrects it.
555
+ * Decide whether one active session row is safe to retire.
467
556
  *
468
- * ── WHY THIS IS NOT `markRunSessionsDead` ────────────────────────────────────
469
- *
470
- * `markRunSessionsDead` retires EVERY non-`dead` newest row of a run. Reusing it
471
- * here would destroy exactly the capability this phase has to keep working:
472
- * `src/agent/loop.ts` refuses to resume a session whose previous status is
473
- * `dead`, and a `turn-ended` or `submitted` row is a COMPLETED turn whose
474
- * provider-side session is intact. A reboot does not invalidate one. Leaving
475
- * those rows alone is precisely what "resume still works after a reboot" means.
476
- *
477
- * So ONLY `active` rows are eligible, and only for runs absent from
478
- * `liveRunIds`.
479
- *
480
- * ── WHY RETIRING AN ORPHANED `active` ROW IS THE RIGHT DIRECTION TO BE WRONG ──
481
- *
482
- * An interrupted turn is the state you least want to resume into: the harness may
483
- * have half-applied tool calls the worker has no record of, so a resumed session
484
- * would carry a model that believes work happened which did not. The cost of
485
- * retiring it is one cold replay. The cost of resuming it is silent divergence.
486
- *
487
- * ── KNOWN FALSE POSITIVE, STATED RATHER THAN ENGINEERED AROUND ───────────────
488
- *
489
- * An `owenloop work agent-run` started BY HAND, outside the shift, has no child record
490
- * in the shift state dir, so a shift booting at that moment sees its `active` row
491
- * as orphaned and retires it. The cost is one cold replay on a hand-run debugging
492
- * session. Two things keep it small: the caller invokes this at BOOT only, which
493
- * narrows the window to an instant, and every retirement is returned so the
494
- * caller can log it with its `(workflow, run, step)`. Do NOT add a pid field to
495
- * `SessionRecord` to close this — the record is deliberately machine-portable
496
- * metadata, and the shift state dir is already the system of record for liveness.
497
- *
498
- * IDEMPOTENT: the rows it appends are `dead`, so a second call finds nothing
499
- * `active` left and appends nothing.
500
- *
501
- * FAILURE STANCE: `appendSession` propagates, and so does this — same as
502
- * `markRunSessionsDead`.
503
- *
504
- * @param liveRunIds run ids with a live `agent-run` child RIGHT NOW. A run in
505
- * this set is skipped whatever its status.
506
- * @returns the records that were retired, as they were BEFORE retirement, so the
507
- * caller can log what it took away.
557
+ * The function is deliberately independent of the JSONL writer. Callers can
558
+ * exercise the safety predicate with a deterministic PID probe, while the
559
+ * production path uses `process.kill(pid, 0)` through `defaultIsAlive`.
508
560
  */
509
- export function reconcileActiveSessions(file, liveRunIds, now, opts = {}) {
561
+ export function shouldRetireSession(record, context) {
562
+ const recordOwner = record.shiftOwner ?? record.shiftName;
563
+ const contextOwner = context.shiftOwner ?? context.shiftName;
564
+ if (typeof recordOwner !== 'string' || recordOwner.trim() === '') {
565
+ return { retire: false, reason: 'session has no owning shift name' };
566
+ }
567
+ if (typeof contextOwner !== 'string' || contextOwner.trim() === '') {
568
+ return { retire: false, reason: 'booting shift has no stable owner key' };
569
+ }
570
+ if (recordOwner !== contextOwner) {
571
+ return {
572
+ retire: false,
573
+ reason: `session belongs to shift '${recordOwner}', not '${contextOwner}'`,
574
+ };
575
+ }
576
+ const pid = record.pid;
577
+ if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
578
+ return { retire: false, reason: 'session has no valid worker pid' };
579
+ }
580
+ const isAlive = context.isAlive ?? defaultIsAlive;
581
+ let alive;
582
+ try {
583
+ alive = isAlive(pid);
584
+ }
585
+ catch {
586
+ return { retire: false, reason: `worker pid ${String(pid)} liveness is unknown` };
587
+ }
588
+ if (alive) {
589
+ return { retire: false, reason: `worker pid ${String(pid)} is alive` };
590
+ }
591
+ if (context.harness !== undefined && context.harness !== '' && record.harness !== context.harness) {
592
+ return {
593
+ retire: false,
594
+ reason: `harness mismatch: session uses '${record.harness}', shift uses '${context.harness}'`,
595
+ };
596
+ }
597
+ return { retire: true, reason: `worker pid ${String(pid)} is confirmed dead` };
598
+ }
599
+ export function reconcileActiveSessions(file, context, now, opts = {}) {
510
600
  mkdirSync(join(file, '..'), { recursive: true });
511
601
  return withWriterLock(file, () => {
512
602
  const newest = new Map();
@@ -518,8 +608,15 @@ export function reconcileActiveSessions(file, liveRunIds, now, opts = {}) {
518
608
  for (const rec of newest.values()) {
519
609
  if (rec.status !== 'active')
520
610
  continue; // a completed turn is still resumable
521
- if (liveRunIds.has(rec.run))
522
- continue; // its worker is alive; the row is true
611
+ const decision = shouldRetireSession(rec, context);
612
+ if (!decision.retire) {
613
+ opts.debug?.(`owenloop work sessions: skipped orphan reconciliation for ${rec.workflow}/${rec.run} ` +
614
+ `step '${rec.step}': ${decision.reason}`);
615
+ if (decision.reason.startsWith('harness mismatch:')) {
616
+ (opts.warn ?? defaultWarn)(`owenloop work sessions: refusing to retire ${rec.workflow}/${rec.run} step '${rec.step}': ${decision.reason}`);
617
+ }
618
+ continue;
619
+ }
523
620
  appendSessionUnlocked(file, { ...rec, status: 'dead', updatedAt: now }, opts);
524
621
  retired.push(rec);
525
622
  }
@@ -1,4 +1,4 @@
1
- import type { AskRequest, AskResponse, GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, ReportResolutionRequest, ReportResolutionResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
1
+ import type { AnswerApprovalRequest, AnswerApprovalResponse, AskRequest, AskResponse, ListPendingApprovalsResponse, RequestApprovalRequest, RequestApprovalResponse, GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, ReportResolutionRequest, ReportResolutionResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
2
2
  export interface HubClientOptions {
3
3
  /** Hub origin, e.g. `https://hub.owenloop.dev` (no trailing slash needed). */
4
4
  origin: string;
@@ -21,6 +21,18 @@ export interface HubClient {
21
21
  * `owenloop retry <workflow> <path> --text "<answer>"`.
22
22
  */
23
23
  ask(req: AskRequest): Promise<AskResponse>;
24
+ /**
25
+ * TOOL APPROVAL — raise AND poll, one idempotent call. The worker is mid-flight
26
+ * and needs yes/no on ONE tool call; unlike `ask`, the session stays alive, the
27
+ * run does not close, and the answer comes back to the very same blocked call.
28
+ * Repeating the call with the same `tool_use_id` re-reads the existing row.
29
+ */
30
+ requestApproval(req: RequestApprovalRequest): Promise<RequestApprovalResponse>;
31
+ /** The HUMAN half — the operator CLI, never a worker. An agent token is
32
+ * refused this verb by the hub's RBAC, deliberately. */
33
+ answerApproval(req: AnswerApprovalRequest): Promise<AnswerApprovalResponse>;
34
+ /** Every approval a worker is currently blocked on, org-wide. */
35
+ listPendingApprovals(): Promise<ListPendingApprovalsResponse>;
24
36
  /**
25
37
  * Plan §6: record what this shift resolved the order's compound capability to,
26
38
  * BEFORE the harness launches. Idempotent on the hub by order id, so a
@@ -83,6 +83,9 @@ export function createHubClient(opts) {
83
83
  submit: (req) => post('submit', req),
84
84
  reject: (req) => post('reject', req),
85
85
  ask: (req) => post('ask', req),
86
+ requestApproval: (req) => post('request_approval', req),
87
+ answerApproval: (req) => post('answer_approval', req),
88
+ listPendingApprovals: () => post('list_pending_approvals', {}),
86
89
  reportResolution: (req) => post('report_resolution', req),
87
90
  whoami: () => get('whoami'),
88
91
  // Cursor is an opaque non-negative integer; omit it entirely to bootstrap
@@ -185,9 +185,9 @@ export interface OrderPacket {
185
185
  /**
186
186
  * THE COMPOSED CAPABILITIES this order was offered under, in the step's
187
187
  * authored order — `['build:deep']` for a `build` step on a `deep` run. This
188
- * is the key into the shift's `capabilityModels` map (see
189
- * `src/agent/capability-model.ts`), and therefore what decides which model and
190
- * effort run. Absent from a pre-modifier hub, which is why the worker treats
188
+ * is the key into the shift's merged crew roster (see
189
+ * `src/agent/capability-model.ts`), and therefore what decides which
190
+ * harness, model, and effort run. Absent from a pre-modifier hub, which is why the worker treats
191
191
  * an empty list as "nothing to resolve against" and refuses rather than
192
192
  * guessing.
193
193
  */
@@ -231,6 +231,23 @@ export interface OrderPacket {
231
231
  judgmentRejects: number;
232
232
  schemaRejects: number;
233
233
  reasons: ReasonEntry[];
234
+ /**
235
+ * The JSON Schema the engine will enforce on this output at commit time,
236
+ * projected off the owning produce entry by a schema-aware hub. Absent
237
+ * when the produce declares none (the common case — any JSON is accepted),
238
+ * and absent from every hub too old to project the field at all. Those two
239
+ * cases are indistinguishable here on purpose: both mean "this worker was
240
+ * told no shape", and the brief says nothing either way rather than
241
+ * claiming an output is unconstrained when it may not be.
242
+ */
243
+ schema?: unknown;
244
+ /**
245
+ * What `schema` governs — `'value'` for the submitted value itself
246
+ * (singleton produce, or one element of a map produce), `'member'` for
247
+ * each member emitted into a collection rather than the seal value the
248
+ * path names. Projected together with `schema` and meaningless without it.
249
+ */
250
+ schemaAppliesTo?: 'value' | 'member';
234
251
  /** Target-protocol reason-thread proof; the deployed hub may omit it. */
235
252
  proof?: string;
236
253
  }>;
@@ -396,6 +413,90 @@ export interface AskResponse extends HubResponse {
396
413
  ok: boolean;
397
414
  closed?: boolean;
398
415
  }
416
+ /**
417
+ * The DETERMINISTIC TOOL-APPROVAL gate — the fine-grained sibling of `ask`, and
418
+ * deliberately not the same mechanism.
419
+ *
420
+ * `ask` is a worker declaring it cannot honestly build what it OWES: it freezes
421
+ * the artifact, CLOSES the run, and its answer reaches a FRESH worker. This is a
422
+ * worker mid-flight needing yes/no on ONE tool call: the session is alive and
423
+ * stays alive, the run does not close, no attempt is burnt, and the answer comes
424
+ * back to the very same blocked call.
425
+ *
426
+ * ONE VERB SERVES BOTH RAISE AND POLL. `toolUseId` is the harness's own id for
427
+ * the blocked call, so a repeat of this request is unambiguously the same
428
+ * question rather than a new one — the hub re-reads the existing row instead of
429
+ * opening a second. A worker therefore raises and polls with identical calls and
430
+ * never has to track whether it already asked.
431
+ *
432
+ * `step` is ABSENT for the same reason it is absent on `ask` and `reject`: the
433
+ * hub derives it from the claiming run's row, so a worker cannot raise an
434
+ * approval stamped to another step.
435
+ */
436
+ export interface RequestApprovalRequest {
437
+ workflow: string;
438
+ run: string;
439
+ /** The harness's id for the blocked call. The approval's identity, with `run`. */
440
+ tool_use_id: string;
441
+ /** The tool the harness was about to invoke, e.g. `Bash`. */
442
+ tool_name: string;
443
+ /** The call's arguments. A non-string is JSON-stringified by the hub edge. */
444
+ tool_input: unknown;
445
+ /** Why the gatekeeper would not allow this on its own — written for a person. */
446
+ reason: string;
447
+ /** The harness's own one-line rendering of the prompt, when it supplies one. */
448
+ title?: string;
449
+ }
450
+ /** `pending` is the only state a worker waits on. An unrecognized stored state
451
+ * reads as `expired` hub-side, never `pending`. */
452
+ export type ApprovalState = 'pending' | 'approved' | 'denied' | 'expired';
453
+ /** One approval as the hub reports it. */
454
+ export interface ApprovalView {
455
+ workflow: string;
456
+ run: string;
457
+ toolUseId: string;
458
+ /** Derived hub-side from the claiming run — never what the caller said. */
459
+ step: string;
460
+ toolName: string;
461
+ reason: string;
462
+ title: string;
463
+ state: ApprovalState;
464
+ requestedAt: number;
465
+ decidedAt: number | null;
466
+ decidedBy: string | null;
467
+ note: string | null;
468
+ }
469
+ /**
470
+ * `ok: false` with `reason: 'not-held'` means the claim this approval belonged
471
+ * to is gone — the worker's lease ended while it waited. That is a REFUSAL, not
472
+ * a denial: nothing was written, and there is no longer anyone the answer could
473
+ * come back to.
474
+ */
475
+ export interface RequestApprovalResponse extends HubResponse {
476
+ ok: boolean;
477
+ reason?: string;
478
+ approval?: ApprovalView;
479
+ }
480
+ /** The human half. Not called by a worker — an agent token is deliberately
481
+ * refused this verb, because an agent that could answer its own approval could
482
+ * approve every call it was just refused. */
483
+ export interface AnswerApprovalRequest {
484
+ workflow: string;
485
+ run: string;
486
+ tool_use_id: string;
487
+ decision: 'approve' | 'deny';
488
+ note?: string;
489
+ }
490
+ export interface AnswerApprovalResponse extends HubResponse {
491
+ ok: boolean;
492
+ reason?: string;
493
+ approval?: ApprovalView;
494
+ }
495
+ /** Only approvals whose worker is STILL holding its lease — a question nobody
496
+ * is waiting on is not shown, because answering it would do nothing. */
497
+ export interface ListPendingApprovalsResponse extends HubResponse {
498
+ approvals: ApprovalView[];
499
+ }
399
500
  export interface WhoamiResponse extends HubResponse {
400
501
  orgId: string;
401
502
  orgName: string;
@@ -26,6 +26,7 @@ const ROLES = {
26
26
  release: () => import("./roles/release.js"),
27
27
  join: () => import("./roles/join.js"),
28
28
  sessions: () => import("./roles/sessions.js"),
29
+ approvals: () => import("./roles/approvals.js"),
29
30
  };
30
31
  export async function mainAsync(argv) {
31
32
  const [first, ...rest] = argv;
@@ -92,10 +92,11 @@ import { createConsumedVerifier } from "../consumed-verifier.js";
92
92
  import { createHubClient } from "../hub/client.js";
93
93
  import { resolveBearer } from "../credentials/resolve.js";
94
94
  import { loadSettings } from "../settings/settings.js";
95
+ import { machineRosterLayers, mergeRosterLayers } from "../settings/roster.js";
95
96
  import { adapterFor, defaultHarnessId, registeredHarnessIds } from "../harness/registry.js";
96
97
  import { parseHarnessCarrier } from "../bundle/fetch.js";
97
98
  import { normalizeStepPermissions, validateHarnessOptions } from "../harness/permissions.js";
98
- import { appendSession, latestFor, sessionsPath } from "../harness/session-store.js";
99
+ import { appendSession, latestForTask, sessionsPath, } from "../harness/session-store.js";
99
100
  import { ensureWorkDir, resolveAllowedWorkdirRoots, resolveWorkRepo, resolveWorkRoot, } from "../agent/workdir.js";
100
101
  import { resolveShiftId, resolveTarget } from "./hold.js";
101
102
  import { installSignalHandlers } from "./signals.js";
@@ -154,8 +155,6 @@ export function parseArgs(args) {
154
155
  else if (name === '--shift')
155
156
  parsed.shift = r.value;
156
157
  else if (name === '--harness') {
157
- if (r.value.trim() === '')
158
- return { error: '--harness must be a non-empty harness id' };
159
158
  parsed.harness = r.value;
160
159
  }
161
160
  else {
@@ -220,8 +219,8 @@ export function exitCodeFor(outcome) {
220
219
  * adapter at all. What it still buys is the ability for a drill to register a
221
220
  * FAKE adapter inside a real spawned child without the child reaching for a
222
221
  * real CLI. Production leaves the variable unset and this is a no-op. Drills
223
- * that use it also pin `OWENLOOP_HARNESS=fake`, because the statically
224
- * imported real adapters now occupy the front of the registry and would
222
+ * that use it select a fake adapter through a roster candidate, because the
223
+ * statically imported real adapters occupy the front of the registry and would
225
224
  * otherwise win the `defaultHarnessId()` tie-break. A failed import is
226
225
  * reported and then ignored — resolution proceeds and fails honestly with
227
226
  * `'no-harness'` if nothing ended up registered.
@@ -265,12 +264,25 @@ export async function run(args, deps = {}) {
265
264
  err(`owenloop work agent-run: ${errMsg(e)}`);
266
265
  return 1;
267
266
  }
268
- // Passed through verbatim. `loadSettings` already validated every row (shape,
269
- // effort on the ladder, effort accepted by a known model), so there is nothing
270
- // left to normalize here — and nothing to default: an absent map means the
271
- // loop refuses capability-bearing orders, which is the intended answer for a
272
- // shift that never declared what serves what.
273
- const capabilityModels = settings.capabilityModels;
267
+ // Phase 1 interim rule: choose crew rosters in the order the shift was
268
+ // started with. Phase 2 replaces this handoff with crews stamped by the hub
269
+ // on each offer. A hand-run worker and a shift started with --all see only
270
+ // the machine-global settings layer.
271
+ const servedCrews = (env['OWENLOOP_SERVE_CREWS'] ?? '')
272
+ .split(',')
273
+ .map((crew) => crew.trim())
274
+ .filter((crew) => crew !== '');
275
+ let rosters;
276
+ try {
277
+ rosters =
278
+ servedCrews.length > 0
279
+ ? servedCrews.map((crew) => mergeRosterLayers(machineRosterLayers(env, crew)))
280
+ : [mergeRosterLayers(machineRosterLayers(env, undefined))];
281
+ }
282
+ catch (e) {
283
+ err(`owenloop work agent-run: ${errMsg(e)}`);
284
+ return 1;
285
+ }
274
286
  const origin = parsed.origin ?? settings.hubOrigin;
275
287
  if (origin === undefined || origin.trim() === '') {
276
288
  err('owenloop work agent-run: no hub origin — pass --origin <url> or set hubOrigin in settings');
@@ -338,42 +350,30 @@ export async function run(args, deps = {}) {
338
350
  const client = hub;
339
351
  await loadHarnessModule(env['OWENLOOP_HARNESS_MODULE'], err);
340
352
  const shiftId = resolveShiftId(parsed.shift, env);
353
+ const shiftName = env['OWENLOOP_SHIFT_NAME'];
354
+ const shiftOwner = env['OWENLOOP_SHIFT_OWNER'];
341
355
  const holder = {
342
356
  kind: 'exec',
343
357
  id: deps.holderId ?? `${hostname()}:${process.pid}`,
344
358
  ...(shiftId !== undefined ? { shiftId } : {}),
345
359
  };
346
360
  /**
347
- * Adapter id precedence: `--harness` > `OWENLOOP_HARNESS` > the step def's
348
- * `harness` field > the first registered adapter. Every rank is a plain
349
- * string comparison — nothing here knows what any id MEANS.
361
+ * The winning roster candidate is deliberately above the debug --harness
362
+ * flag: it extends the existing rule that resolved routing wins over a
363
+ * step's authored model and effort. Every rank is a plain string comparison.
350
364
  */
351
- const envHarness = env['OWENLOOP_HARNESS'];
352
- const resolveAdapter = (stepHarness) => {
353
- let id;
354
- if (parsed.harness !== undefined) {
355
- id = parsed.harness;
356
- }
357
- else if (envHarness !== undefined) {
358
- // Definition and default selection are lower precedence. An explicit empty
359
- // environment override is invalid; it must not silently fall through.
360
- if (envHarness.trim() === '') {
361
- return {
362
- id: '<empty OWENLOOP_HARNESS>',
363
- registered: registeredHarnessIds(),
364
- };
365
- }
366
- id = envHarness;
367
- }
368
- else {
369
- id =
370
- (stepHarness !== undefined && stepHarness !== '' ? stepHarness : undefined) ??
371
- defaultHarnessId() ??
372
- '';
373
- }
365
+ const resolveAdapter = (chosenHarness, stepHarness) => {
366
+ const id = chosenHarness ??
367
+ parsed.harness ??
368
+ (stepHarness !== undefined && stepHarness !== '' ? stepHarness : undefined) ??
369
+ defaultHarnessId() ??
370
+ '';
374
371
  const adapter = id !== '' ? adapterFor(id) : undefined;
375
372
  return {
376
- id: id !== '' ? id : '<none>',
373
+ // Keep an explicit blank `--harness` visible to the refusal instead of
374
+ // silently treating it as an absent override and selecting the default.
375
+ // A roster candidate still outranks it at the line above.
376
+ id: id !== '' || parsed.harness !== undefined ? id : '<none>',
377
377
  ...(adapter !== undefined ? { adapter } : {}),
378
378
  registered: registeredHarnessIds(),
379
379
  };
@@ -495,6 +495,8 @@ export async function run(args, deps = {}) {
495
495
  origin,
496
496
  account,
497
497
  ...(shiftId !== undefined ? { shiftId } : {}),
498
+ ...(shiftName !== undefined && shiftName !== '' ? { shiftName } : {}),
499
+ ...(shiftOwner !== undefined && shiftOwner !== '' ? { shiftOwner } : {}),
498
500
  cwd: workCwd,
499
501
  // Machine policy, resolved from the SAME two sources the shift resolves it
500
502
  // from: `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (which `owenloop shift start`
@@ -505,16 +507,24 @@ export async function run(args, deps = {}) {
505
507
  allowedWorkdirRoots: resolveAllowedWorkdirRoots(env, settings.allowedWorkdirRoots, process.cwd()),
506
508
  loadStep,
507
509
  resolveAdapter,
508
- ...(capabilityModels !== undefined ? { capabilityModels } : {}),
510
+ rosters,
511
+ // Phase-1 availability means registry membership. A real binary or
512
+ // credential probe requires new HarnessAdapter contract surface.
513
+ harnessAvailable: (id) => adapterFor(id) !== undefined,
509
514
  consumedVerifier,
510
515
  appendSession: writeSession,
511
- nextAttempt: (workflow, run, step) => {
512
- const prev = latestFor(sessionsFile, workflow, run, step);
516
+ // Both readers key on the engine TASK — `(workflow, step, key)` — and not on
517
+ // `(workflow, run, step)`. The hub mints a fresh run id every time it claims
518
+ // a step, so a run-keyed lookup can only ever see records written by the
519
+ // firing that is asking: `nextAttempt` returned 1 forever and `latestSession`
520
+ // returned null forever, which made the whole resume path unreachable.
521
+ nextAttempt: (task) => {
522
+ const prev = latestForTask(sessionsFile, task);
513
523
  return prev === null ? 1 : prev.attempt + 1;
514
524
  },
515
525
  // PHASE 4: the same reader `nextAttempt` uses, handed to the loop whole so
516
526
  // it can decide resume vs cold replay. Reads only; the loop is what writes.
517
- latestSession: (workflow, run, step) => latestFor(sessionsFile, workflow, run, step),
527
+ latestSession: (task) => latestForTask(sessionsFile, task),
518
528
  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
519
529
  now: () => Date.now(),
520
530
  out,