owenloop 0.5.1 → 0.5.3

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 (88) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +9 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +21 -0
  4. package/dist/packages/work/src/agent/brief.js +42 -1
  5. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  6. package/dist/packages/work/src/agent/capability-model.js +148 -0
  7. package/dist/packages/work/src/agent/loop.d.ts +47 -4
  8. package/dist/packages/work/src/agent/loop.js +83 -53
  9. package/dist/packages/work/src/exec/loop.d.ts +17 -0
  10. package/dist/packages/work/src/exec/loop.js +195 -34
  11. package/dist/packages/work/src/exec/runner.js +15 -5
  12. package/dist/packages/work/src/harness/claude.js +69 -9
  13. package/dist/packages/work/src/harness/codex.js +56 -8
  14. package/dist/packages/work/src/harness/contract.d.ts +65 -1
  15. package/dist/packages/work/src/harness/contract.js +56 -0
  16. package/dist/packages/work/src/harness/session-store.d.ts +3 -1
  17. package/dist/packages/work/src/harness/session-store.js +46 -22
  18. package/dist/packages/work/src/hold/mcp.js +9 -2
  19. package/dist/packages/work/src/hub/client.d.ts +7 -1
  20. package/dist/packages/work/src/hub/client.js +1 -0
  21. package/dist/packages/work/src/hub/types.d.ts +71 -3
  22. package/dist/packages/work/src/roles/agent-run.js +8 -9
  23. package/dist/packages/work/src/roles/hold.d.ts +2 -0
  24. package/dist/packages/work/src/roles/hold.js +39 -8
  25. package/dist/packages/work/src/roles/settings.js +18 -6
  26. package/dist/packages/work/src/roles/shift.js +13 -1
  27. package/dist/packages/work/src/settings/settings.d.ts +60 -7
  28. package/dist/packages/work/src/settings/settings.js +69 -22
  29. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  30. package/dist/packages/work/src/shift/logretention.js +407 -0
  31. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  32. package/dist/packages/work/src/shift/logsink.js +98 -0
  33. package/dist/packages/work/src/shift/loop.d.ts +18 -1
  34. package/dist/packages/work/src/shift/loop.js +250 -12
  35. package/dist/packages/work/src/shift/protocol.d.ts +124 -1
  36. package/dist/packages/work/src/shift/protocol.js +14 -0
  37. package/dist/packages/work/src/shift/runtime.d.ts +14 -0
  38. package/dist/packages/work/src/shift/runtime.js +229 -6
  39. package/dist/packages/work/src/shift/server.d.ts +13 -0
  40. package/dist/packages/work/src/shift/server.js +61 -36
  41. package/dist/packages/work/src/shift/spawn.d.ts +78 -5
  42. package/dist/packages/work/src/shift/spawn.js +158 -12
  43. package/dist/packages/work/src/shift/state.d.ts +25 -0
  44. package/dist/packages/work/src/shift/state.js +29 -5
  45. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  46. package/dist/packages/work/src/shift/truncate.js +73 -0
  47. package/dist/packages/work/src/submit-proof.d.ts +31 -6
  48. package/dist/packages/work/src/submit-proof.js +33 -7
  49. package/dist/packages/work/src/submit-value.d.ts +48 -0
  50. package/dist/packages/work/src/submit-value.js +118 -0
  51. package/dist/packages/work/src/usage.d.ts +1 -1
  52. package/dist/packages/work/src/usage.js +11 -0
  53. package/dist/src/bundle/runtime.d.ts +1 -1
  54. package/dist/src/bundle/runtime.js +9 -0
  55. package/dist/src/capabilities.d.ts +93 -0
  56. package/dist/src/capabilities.js +101 -0
  57. package/dist/src/cli.js +37 -11
  58. package/dist/src/crypto/records.d.ts +3 -0
  59. package/dist/src/crypto/records.js +11 -0
  60. package/dist/src/defs.js +192 -4
  61. package/dist/src/engine.d.ts +112 -3
  62. package/dist/src/engine.js +224 -28
  63. package/dist/src/hub.d.ts +27 -11
  64. package/dist/src/hub.js +24 -18
  65. package/dist/src/index.d.ts +3 -1
  66. package/dist/src/index.js +4 -1
  67. package/dist/src/mcp/serve.js +11 -4
  68. package/dist/src/model.d.ts +36 -0
  69. package/dist/src/model.js +46 -0
  70. package/dist/src/schemas/index.d.ts +17 -0
  71. package/dist/src/schemas/order.v1.schema.json +17 -3
  72. package/dist/src/store.d.ts +33 -1
  73. package/dist/src/store.js +57 -4
  74. package/dist/src/types.d.ts +102 -2
  75. package/docs/agent-runner.md +26 -1
  76. package/docs/authoring.md +7 -0
  77. package/docs/bundles.md +103 -3
  78. package/docs/cli.md +127 -9
  79. package/docs/crypto.md +23 -7
  80. package/docs/shift-logs.md +642 -0
  81. package/docs/wire-contracts.md +34 -19
  82. package/package.json +1 -1
  83. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  84. package/plugins/claude-code/plugin/.mcp.json +1 -1
  85. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  86. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  87. package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
  88. package/dist/packages/work/src/agent/model-policy.js +0 -138
package/dist/src/model.js CHANGED
@@ -121,6 +121,52 @@ export function isHeld(a) {
121
121
  return false;
122
122
  return a.reasons.length > 0 && a.reasons[a.reasons.length - 1].kind === 'invalidated-irreversible';
123
123
  }
124
+ /**
125
+ * §7 escalation trigger: has this artifact been judgment-rejected at least
126
+ * `after` times in the CURRENT rejection episode?
127
+ *
128
+ * Reads `judgmentRejects`, the same counter `isStalled` reads and the same one
129
+ * `retry` zeroes — so "current episode" needs no separate bookkeeping: a human
130
+ * `retry` resets the counter and the trigger goes false again by itself.
131
+ *
132
+ * The state this tests is derived, never stored. Every offer of the step
133
+ * re-evaluates it, so the transition cannot half-apply, cannot be lost, and
134
+ * cannot be applied twice to one offer. It is deliberately independent of
135
+ * `acceptance`: unlike `isStalled` (which describes a FROZEN artifact and must
136
+ * only be true while it is sitting rejected), this describes the routing of the
137
+ * NEXT offer, and by the time that offer is built the artifact has been re-armed
138
+ * to `owed`.
139
+ *
140
+ * `after` comes from the step's authored `escalation.after`. Install validation
141
+ * (`defs.ts` R2) guarantees `after < effectiveMaxAttempts`, so there is always a
142
+ * window between "escalate" and "freeze" in which the escalated attempt runs.
143
+ */
144
+ export function isEscalated(a, after) {
145
+ return !!a && a.judgmentRejects >= after;
146
+ }
147
+ /**
148
+ * Which rejection episode this artifact is in: 0 before any human `retry`, 1
149
+ * after the first, and so on.
150
+ *
151
+ * `retry` is the only lever that ends an episode (it zeroes `judgmentRejects`),
152
+ * and it appends a `'retry'` entry to the append-only reason thread — so
153
+ * counting those entries yields a monotonic episode ordinal with no new column
154
+ * and no new state to keep consistent.
155
+ *
156
+ * Used to key an escalation's ONE history record per episode. It is not used to
157
+ * decide anything: the trigger above reads the counter, which is authoritative.
158
+ * If the thread and the counter ever disagreed, the ordinal would only mislabel
159
+ * a history row, never change routing.
160
+ */
161
+ export function rejectionEpisode(a) {
162
+ if (!a)
163
+ return 0;
164
+ let n = 0;
165
+ for (const r of a.reasons)
166
+ if (r.action === 'retry')
167
+ n++;
168
+ return n;
169
+ }
124
170
  /** Resolve the effective maxAttempts for a specific produce, falling back to
125
171
  * the owning step's default (§6). `produce` may be undefined if the artifact
126
172
  * couldn't be matched to a produce pattern (defensive; should not happen for
@@ -571,6 +571,23 @@ export declare const WIRE_SCHEMAS: {
571
571
  type: string;
572
572
  enum: string[];
573
573
  };
574
+ capabilities: {
575
+ type: string;
576
+ description: string;
577
+ items: {
578
+ type: string;
579
+ minLength: number;
580
+ };
581
+ };
582
+ modifier: {
583
+ type: string;
584
+ minLength: number;
585
+ description: string;
586
+ };
587
+ escalated: {
588
+ const: boolean;
589
+ description: string;
590
+ };
574
591
  };
575
592
  };
576
593
  };
@@ -69,8 +69,8 @@
69
69
  "path": { "type": "string" },
70
70
  "version": {
71
71
  "type": "integer",
72
- "minimum": 0,
73
- "description": "Current committed artifact version captured by the engine at claim time."
72
+ "minimum": 1,
73
+ "description": "Target version this claim's next successful producer commit lands (committed version + 1), issued by the engine inside the claim transaction. A producer signs this version in its submission proof and the downstream consumer checks the proof against it."
74
74
  },
75
75
  "judgmentRejects": { "type": "integer", "minimum": 0 },
76
76
  "schemaRejects": { "type": "integer", "minimum": 0 },
@@ -101,6 +101,20 @@
101
101
  }
102
102
  },
103
103
  "consumesProof": { "type": "string" },
104
- "cause": { "type": "string", "enum": ["inputsGreen", "allGreen", "idle"] }
104
+ "cause": { "type": "string", "enum": ["inputsGreen", "allGreen", "idle"] },
105
+ "capabilities": {
106
+ "type": "array",
107
+ "description": "The composed routing capabilities this order was offered under: each authored step capability, suffixed ':<modifier>' where a modifier applied. A snapshot of the offer — a claimed order is never recomposed.",
108
+ "items": { "type": "string", "minLength": 1 }
109
+ },
110
+ "modifier": {
111
+ "type": "string",
112
+ "minLength": 1,
113
+ "description": "The modifier that composed 'capabilities'. Normally the run's modifier; on an escalated re-offer, the escalating step's target. Absent means the order was offered on bare capabilities."
114
+ },
115
+ "escalated": {
116
+ "const": true,
117
+ "description": "Present only when 'modifier' is the step's escalation target rather than the run's own modifier — a recovery re-offer after escalation.after judgment rejections. Absent on every ordinary offer; never false."
118
+ }
105
119
  }
106
120
  }
@@ -13,7 +13,7 @@
13
13
  * and (de)serialized at the boundary so callers always see real objects.
14
14
  */
15
15
  import { DatabaseSync } from 'node:sqlite';
16
- import type { ArtifactData, ArtifactHistory, RunData, TaskData, WorkflowData, WorkflowDef } from './types.ts';
16
+ import type { ArtifactData, ArtifactHistory, Author, RunData, TaskData, WorkflowData, WorkflowDef } from './types.ts';
17
17
  export interface ArtifactRow extends ArtifactData {
18
18
  id: string;
19
19
  updatedAt: number;
@@ -120,6 +120,38 @@ export declare class Store {
120
120
  key?: string;
121
121
  }): ArtifactRow;
122
122
  private insertArtifactEvent;
123
+ /**
124
+ * Append one engine-authored history record for an artifact, WITHOUT touching
125
+ * the artifact row.
126
+ *
127
+ * `putArtifact` already writes an event per lifecycle change, but only when
128
+ * the artifact's own data changed. Some engine decisions are about an
129
+ * artifact without changing it — the escalation transition is the first: the
130
+ * routing of the next offer changes, the artifact does not. Those need a
131
+ * record too, and this is the only way to write one.
132
+ *
133
+ * **Idempotent by construction.** The row id is derived from
134
+ * `(workflow, path, version, dedupe)` and the insert is
135
+ * `ON CONFLICT(id) DO NOTHING`, so a caller that recomputes the same decision
136
+ * on every tick — as the escalation rule does, since it is derived state and
137
+ * not a stored flag — writes exactly one row. The caller owns `dedupe`: make
138
+ * it identify the EPISODE, not the moment.
139
+ *
140
+ * Pass `version: 0` for a record that belongs to the artifact as a whole
141
+ * rather than to one produced version; `getArtifactHistory` surfaces those in
142
+ * its artifact-level `events` bucket. Detail goes in `metadata`.
143
+ */
144
+ recordArtifactEvent(event: {
145
+ workflow: string;
146
+ path: string;
147
+ version: number;
148
+ action: string;
149
+ actor: Author;
150
+ dedupe: string;
151
+ timestamp: number;
152
+ reason?: string;
153
+ metadata?: Record<string, unknown>;
154
+ }): void;
123
155
  /** Returns history for exactly one artifact; list/status reads stay projection-only. */
124
156
  getArtifactHistory(workflow: string, path: string): ArtifactHistory | undefined;
125
157
  deleteArtifact(workflow: string, path: string): void;
package/dist/src/store.js CHANGED
@@ -28,6 +28,7 @@ CREATE TABLE IF NOT EXISTS workflow (
28
28
  def TEXT NOT NULL,
29
29
  title TEXT,
30
30
  params TEXT NOT NULL DEFAULT '{}',
31
+ modifier TEXT,
31
32
  created_at INTEGER NOT NULL
32
33
  );
33
34
 
@@ -144,8 +145,13 @@ CREATE TABLE IF NOT EXISTS meta (
144
145
  * driver ticks cannot each insert a child for the same `calls:` step.
145
146
  *
146
147
  * Bumped to '9' for immutable artifact payload/version and lifecycle-event history.
148
+ *
149
+ * Bumped to '10' for the routing modifier: the `workflow` table gains a
150
+ * nullable `modifier` column (see `migrate()`). Additive and un-backfilled —
151
+ * NULL on every existing row means "unmodified run", which is the correct
152
+ * reading of an instance created before modifiers existed.
147
153
  */
148
- const SCHEMA_VERSION = '9';
154
+ const SCHEMA_VERSION = '10';
149
155
  /** Thrown by the `Store` constructor when the on-disk `schema_version` is
150
156
  * newer than this binary's `SCHEMA_VERSION` — the operator needs to
151
157
  * upgrade their owenloop install to open this database. */
@@ -358,6 +364,11 @@ function mapWorkflow(r) {
358
364
  out.defSnapshot = defSnapshot;
359
365
  if (r.def_hash !== null)
360
366
  out.defHash = r.def_hash;
367
+ // NULL (a pre-modifier row, or a run started without one) maps to absent,
368
+ // never to an empty string — 'unmodified run' and 'modifier ""' must not
369
+ // become the same thing downstream, where '' would compose 'build:'.
370
+ if (r.modifier !== null)
371
+ out.modifier = r.modifier;
361
372
  return out;
362
373
  }
363
374
  // ---- the store ---------------------------------------------------------------
@@ -506,6 +517,14 @@ export class Store {
506
517
  if (!wfCols.some((c) => c.name === 'def_hash')) {
507
518
  this.db.exec(`ALTER TABLE workflow ADD COLUMN def_hash TEXT`);
508
519
  }
520
+ // Routing modifier: the ONE modifier this instance carries, set once at
521
+ // creation and never written again. NULL on every pre-existing row, which
522
+ // is exactly right — an instance created before modifiers existed is an
523
+ // unmodified run and every step is offered on bare capabilities. No
524
+ // backfill: there is no value to invent.
525
+ if (!wfCols.some((c) => c.name === 'modifier')) {
526
+ this.db.exec(`ALTER TABLE workflow ADD COLUMN modifier TEXT`);
527
+ }
509
528
  // Only a genuine pre-v8 -> v8 upgrade may backfill the current projection's
510
529
  // reason thread. Re-opening an already-v8 database must not manufacture a
511
530
  // second copy of its lifecycle events (even though the legacy keys differ
@@ -562,9 +581,9 @@ export class Store {
562
581
  const at = nowMs();
563
582
  this.db
564
583
  .prepare(`INSERT INTO workflow
565
- (id, def, title, params, produced_by_wf, produced_by_path, def_snapshot, def_hash, created_at)
566
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
567
- .run(id, data.def, data.title ?? null, JSON.stringify(data.params ?? {}), producedBy?.parentWf ?? null, producedBy?.parentPath ?? null, toJson(data.defSnapshot), data.defHash ?? null, at);
584
+ (id, def, title, params, produced_by_wf, produced_by_path, def_snapshot, def_hash, modifier, created_at)
585
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
586
+ .run(id, data.def, data.title ?? null, JSON.stringify(data.params ?? {}), producedBy?.parentWf ?? null, producedBy?.parentPath ?? null, toJson(data.defSnapshot), data.defHash ?? null, data.modifier ?? null, at);
568
587
  return this.getWorkflow(id);
569
588
  }
570
589
  /**
@@ -717,6 +736,40 @@ export class Store {
717
736
  this.db.prepare(`INSERT INTO artifact_event (id, workflow, path, version, action, actor, reason, kind, metadata, created_at)
718
737
  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO NOTHING`).run(id, event.workflow, event.path, event.version, event.action, event.actor, event.reason ?? null, event.kind ?? null, toJson(event.metadata), event.timestamp);
719
738
  }
739
+ /**
740
+ * Append one engine-authored history record for an artifact, WITHOUT touching
741
+ * the artifact row.
742
+ *
743
+ * `putArtifact` already writes an event per lifecycle change, but only when
744
+ * the artifact's own data changed. Some engine decisions are about an
745
+ * artifact without changing it — the escalation transition is the first: the
746
+ * routing of the next offer changes, the artifact does not. Those need a
747
+ * record too, and this is the only way to write one.
748
+ *
749
+ * **Idempotent by construction.** The row id is derived from
750
+ * `(workflow, path, version, dedupe)` and the insert is
751
+ * `ON CONFLICT(id) DO NOTHING`, so a caller that recomputes the same decision
752
+ * on every tick — as the escalation rule does, since it is derived state and
753
+ * not a stored flag — writes exactly one row. The caller owns `dedupe`: make
754
+ * it identify the EPISODE, not the moment.
755
+ *
756
+ * Pass `version: 0` for a record that belongs to the artifact as a whole
757
+ * rather than to one produced version; `getArtifactHistory` surfaces those in
758
+ * its artifact-level `events` bucket. Detail goes in `metadata`.
759
+ */
760
+ recordArtifactEvent(event) {
761
+ this.insertArtifactEvent({
762
+ workflow: event.workflow,
763
+ path: event.path,
764
+ version: event.version,
765
+ action: event.action,
766
+ actor: event.actor,
767
+ timestamp: event.timestamp,
768
+ key: event.dedupe,
769
+ ...(event.reason !== undefined ? { reason: event.reason } : {}),
770
+ ...(event.metadata !== undefined ? { metadata: event.metadata } : {}),
771
+ });
772
+ }
720
773
  /** Returns history for exactly one artifact; list/status reads stay projection-only. */
721
774
  getArtifactHistory(workflow, path) {
722
775
  const current = this.getArtifact(workflow, path);
@@ -156,6 +156,39 @@ export interface Order {
156
156
  worker?: string;
157
157
  /** The artifact stem this order's judge step is verdicting, when present. */
158
158
  judge?: string;
159
+ /**
160
+ * The COMPOSED routing capabilities this order was offered under — the
161
+ * step's authored capabilities each suffixed with the run's modifier
162
+ * (`wise` → `wise:deep`), or the authored names verbatim when the run
163
+ * carries no modifier. Absent when the step authored none.
164
+ *
165
+ * This is the value a claiming crew's bindings are matched against and the
166
+ * value the shift's settings map is keyed by. It is a snapshot of the offer:
167
+ * an already-claimed order is never recomposed, so re-reading it later
168
+ * always shows what the claim was actually judged on.
169
+ */
170
+ capabilities?: string[];
171
+ /**
172
+ * The modifier this order was composed with. Normally the run's modifier;
173
+ * on an escalated re-offer, the step's escalation target instead (the run's
174
+ * own modifier is left alone). Carried separately from `capabilities` so a
175
+ * brief can surface the requested depth without re-parsing a compound.
176
+ */
177
+ modifier?: string;
178
+ /**
179
+ * `true` when `modifier` above is the step's ESCALATION TARGET rather than
180
+ * the run's own modifier — i.e. this offer is a recovery re-offer made
181
+ * after the step's produce accumulated `escalation.after` judgment
182
+ * rejections. Absent on every ordinary offer.
183
+ *
184
+ * The engine decides the transition; this flag is how the decision reaches
185
+ * the layer that acts on it, instead of that layer re-deriving it by
186
+ * diffing `modifier` against the run record. The hub reads it to apply the
187
+ * escalation wait policy (wait-then-fallback, even where the deployment
188
+ * default is `forever`); a brief reads it to tell the worker it is on the
189
+ * recovery path.
190
+ */
191
+ escalated?: true;
159
192
  /** Opaque config object for a non-agent/non-command worker type (or
160
193
  * alongside a command). Carried through untouched, contents never read. */
161
194
  spec?: Record<string, unknown>;
@@ -173,7 +206,11 @@ export interface Order {
173
206
  /** the owed outputs and their accumulated reason threads (the feedback channel) */
174
207
  owes: Array<{
175
208
  path: string;
176
- /** Current committed artifact version captured by the engine at claim time. */
209
+ /** The target version this claim's next successful producer commit lands
210
+ * (committed version + 1), issued by the engine inside the claim
211
+ * transaction. This is the version a producer signs in a submission
212
+ * proof and a downstream consumer checks it against. Absent when the hub
213
+ * is not version-aware, which leaves the producer submit unsigned. */
177
214
  version?: number;
178
215
  judgmentRejects: number;
179
216
  schemaRejects: number;
@@ -212,6 +249,16 @@ export interface WorkflowData {
212
249
  def: string;
213
250
  title?: string;
214
251
  params?: Record<string, string>;
252
+ /**
253
+ * The ONE modifier this run carries, validated against the def's declared
254
+ * `modifiers` set when the run is created and immutable thereafter — no
255
+ * step, worker or judge can write it (only `start_run` sets it; escalation
256
+ * overrides it per-offer without changing it here).
257
+ *
258
+ * Absent = an unmodified run: every step is offered on bare capabilities.
259
+ * Deletes with the run, like the rest of the row.
260
+ */
261
+ modifier?: string;
215
262
  /** Instance-to-definition pinning (§28): the compiled def this instance was
216
263
  * created against, snapshotted verbatim as JSON. Absent on rows created
217
264
  * before this feature shipped — those instances fall back to today's
@@ -294,6 +341,13 @@ export interface ProducePattern {
294
341
  * (or additionally alongside `command`). Shape-checked as a plain map
295
342
  * only (mirrors `x:`'s asExtension contract) — contents never read. */
296
343
  spec?: Record<string, unknown>;
344
+ /** Routing capabilities for this judge's synthesized step. Omitted =
345
+ * INHERIT the producing step's `capabilities`, so a judge routes to the
346
+ * same grade of crew as the work it judges instead of being claimable by
347
+ * anyone. Set explicitly to route a judge somewhere else; an explicit
348
+ * empty list is not accepted (it would reopen the def-silent hole
349
+ * deliberately, which no author means to do). */
350
+ capabilities?: string[];
297
351
  }>;
298
352
  }
299
353
  /**
@@ -319,6 +373,27 @@ export interface EffectDef {
319
373
  onInvalidate?: 'pin' | 'escalate' | string;
320
374
  }
321
375
  /** A step (step) definition. */
376
+ /**
377
+ * A step's escalation rule (def-authored, engine-applied).
378
+ *
379
+ * There is NO rung order anywhere in this system — `modifier` is an explicit
380
+ * target drawn from the def's declared `modifiers` set, never "the next one
381
+ * up". Escalation therefore cannot be expressed as arithmetic on a ladder, and
382
+ * nothing here is comparable to anything else.
383
+ *
384
+ * `after` must be strictly less than the effective `maxAttempts` of every
385
+ * produce on the owning step. At `judgmentRejects >= maxAttempts` the engine
386
+ * freezes the artifact (`model.ts` `isStalled`), so an escalation authored at
387
+ * or past that threshold would re-offer a step that can never run again —
388
+ * deterministically dead. `validateDef` rejects it rather than accepting a
389
+ * rule that silently does nothing.
390
+ */
391
+ export interface EscalationDef {
392
+ /** Judgment-reject count that triggers the escalated re-offer. */
393
+ after: number;
394
+ /** Target modifier, a member of the def's declared `modifiers` set. */
395
+ modifier: string;
396
+ }
322
397
  export interface StepDef {
323
398
  name: string;
324
399
  /** Inputs this step reads — and, by the same declaration, the artifacts it has
@@ -384,8 +459,19 @@ export interface StepDef {
384
459
  /** A2: opaque routing capabilities for peer-orchestrator claim filtering. A tick
385
460
  * caller passing a capability filter only claims steps whose capabilities intersect it;
386
461
  * absent (or empty, normalized to absent at parse) = claimable by any caller.
387
- * Distinct from `executor`/`executors` (executor-kind), which this never touches. */
462
+ * Distinct from `executor`/`executors` (executor-kind), which this never touches.
463
+ *
464
+ * AUTHORED NAMES ONLY — never a compound. A `:` is rejected at parse
465
+ * (`buildStep`) because the suffix position is engine-owned: the engine
466
+ * composes `<capability>:<modifier>` at offer time (see
467
+ * `WorkflowDef.modifiers` and `Order.capabilities`). */
388
468
  capabilities?: string[];
469
+ /** Per-step escalation rule: after `after` judgment rejections of this
470
+ * step's produced artifact, the engine re-offers THIS step composed with
471
+ * `modifier` instead of the run's modifier. Step-scoped — the run's own
472
+ * modifier is never changed. Absent = the step never escalates and
473
+ * rejections run the normal retry path until the stall brake. */
474
+ escalation?: EscalationDef;
389
475
  /** A3 (REL-8): per-step OPT-IN max total lease lifetime override in
390
476
  * milliseconds — the cap on `claimedAt + maxLease` past which renewals can no
391
477
  * longer keep a lease fresh. Overrides the engine `maxLeaseMs`; when both are
@@ -423,6 +509,20 @@ export interface WorkflowDef {
423
509
  * that are expanded at load time by `expandIncludes`; the engine always sees a flat list.
424
510
  */
425
511
  steps: StepDef[];
512
+ /**
513
+ * The def's declared modifier vocabulary — an UNORDERED SET of plain names
514
+ * (e.g. `[express, standard, deep]`). The engine attaches no meaning, no
515
+ * order and no arithmetic to these values; it only checks membership.
516
+ *
517
+ * A run may carry ONE of them (`WorkflowData.modifier`, set at start and
518
+ * never changed afterwards). At offer time the engine composes each of a
519
+ * step's capabilities with it — `wise` + `deep` → `wise:deep` — and that
520
+ * compound is what a crew binding is matched against.
521
+ *
522
+ * Absent = this def cannot receive a modifier at all, and every step is
523
+ * offered on its bare capabilities exactly as before this feature existed.
524
+ */
525
+ modifiers?: string[];
426
526
  /** Workflow-level public outputs / embedding interface (design doc §5.2).
427
527
  * Declared stems are intentional leaves: lint-exempt from dead-end warnings.
428
528
  * A stem listed here that no step produces is a hard validateDef error. */
@@ -38,6 +38,7 @@ x:
38
38
  - `tools: []` is an explicit empty allow-list and disables all built-in tools on adapters that support tool lists.
39
39
  - `filesystem` is one of `read-only`, `workspace-write`, or `unrestricted`.
40
40
  - `network` is one of `owenloop-only` or `unrestricted`.
41
+ - `permissionMode` accepts each adapter's own vocabulary, plus three neutral values: `ask`, `auto-safe`, and `full-access`.
41
42
  - `tools` and `disallowedTools` must not overlap.
42
43
  - Invalid types, invalid closed-set values, generated `name`/`description` fields, and the legacy `x.claude-code` carrier are definition errors.
43
44
  - Unknown `x.harness` keys remain opaque extension data. The selected adapter may interpret or warn about those keys.
@@ -58,6 +59,10 @@ A cache created by an older CLI may contain `filesystem` or `network` under `per
58
59
  | `network: owenloop-only` | supported through isolated settings, skills, MCP, and built-in tools | refused |
59
60
  | `network: unrestricted` | supported | supported with `filesystem: unrestricted`, or with an omitted filesystem field and legacy sandbox `workspace-write` / `danger-full-access`; legacy sandbox `read-only` is refused because Codex has no independent read-only network control |
60
61
  | `maxTurns` | enforced by the SDK | refused; Codex app-server has no thread or turn limit parameter |
62
+ | `permissionMode: ask` | translated to `default` | translated to `approvalPolicy: untrusted` |
63
+ | `permissionMode: auto-safe` | translated to `auto`, without the danger companion flag | translated to `approvalPolicy: on-request` |
64
+ | `permissionMode: full-access` | translated to `bypassPermissions` plus the SDK's `allowDangerouslySkipPermissions` companion flag | translated to `approvalPolicy: never` |
65
+ | another adapter's `permissionMode` value | refused; the Claude Code adapter accepts only its own SDK union plus the three neutral values | refused; the Codex adapter accepts only `untrusted`, `on-request`, `never`, plus the three neutral values |
61
66
 
62
67
  Codex refusal of explicit `filesystem: read-only` and `filesystem: workspace-write` is intentional and runs before both cold start and resume. Codex app-server loads configuration from thread, project, global/managed, and persisted session layers. The pinned Codex version has no reliable switch that isolates every layer, and some layers can introduce host processes, providers, endpoints, MCP servers, or additional writable roots outside the thread sandbox. Partial filtering would claim a boundary the adapter cannot prove, so the adapter starts no app-server process and the worker releases the held claim.
63
68
 
@@ -65,7 +70,27 @@ Codex also refuses every defined `maxTurns` value before both cold start and res
65
70
 
66
71
  An omitted `filesystem` field preserves the existing Codex default sandbox behavior. `filesystem: unrestricted` preserves the existing explicit `danger-full-access` behavior. The legacy adapter extension `sandbox` remains available with `read-only`, `workspace-write`, or `danger-full-access` for backward compatibility, but `sandbox` is a vendor-specific pass-through rather than Owenloop's neutral filesystem guarantee. A workflow that requires an enforceable neutral read-only policy must select the Claude Code adapter.
67
72
 
68
- The worker-created `owenloop` MCP mount still wins any `mcp_servers.owenloop` name clash. The default unrestricted mount registers `get_order`, `submit`, and `reject`. Codex approval policy still accepts only `untrusted`, `on-request`, or `never`.
73
+ The worker-created `owenloop` MCP mount still wins any `mcp_servers.owenloop` name clash. The default unrestricted mount registers `get_order`, `submit`, and `reject`. Codex approval policy still accepts only `untrusted`, `on-request`, or `never` as vendor values.
74
+
75
+ ## Neutral approval modes
76
+
77
+ `permissionMode` names how much a step may do before a human is consulted. It is the one neutral field whose values were vendor-specific: Claude Code's never-prompt mode is `bypassPermissions` and Codex's is `never`, and each adapter refuses the other's. A step that must never prompt therefore had to name one vendor's word, which pinned the step to that vendor exactly as an explicit `id:` would.
78
+
79
+ The neutral vocabulary is three positions on one axis, and both shipped harnesses draw all three distinctions themselves:
80
+
81
+ | Neutral value | What is the gate | Claude Code | Codex |
82
+ |---|---|---|---|
83
+ | `ask` | a human, before anything beyond trivially safe reads | `default` | `untrusted` |
84
+ | `auto-safe` | a model-side classifier; it proceeds on ordinary work and consults a human only when an action is potentially dangerous | `auto` | `on-request` |
85
+ | `full-access` | nothing; the harness never consults a human and a failed action is reported back to the model | `bypassPermissions` + `allowDangerouslySkipPermissions` | `never` |
86
+
87
+ `auto-safe` is not a milder `full-access`. It can still stop and ask, which is the whole point of it, so an adapter must never map it onto a never-ask mode. The two exist separately so a definition states the choice rather than having it inferred.
88
+
89
+ `ask` and `auto-safe` are meaningful only where something can answer a prompt. In a Shift-dispatched run nothing can today, so a prompt is a stall: the Step Agent stops mid-turn, submits nothing, and the hub re-arms the step into a retry storm whose every worker dies in the same place. That is a reason for a definition author to choose `full-access` for headless steps, not a reason for an adapter to silently upgrade one value into another.
90
+
91
+ For each neutral value an adapter must either map it onto the vendor mode with the same meaning, or refuse it in preflight. Refusal is a legitimate answer and fails closed: the worker releases its claim and starts no model process. Mapping a value onto a mode that grants more than the value describes is never legitimate.
92
+
93
+ Each adapter still accepts its own vendor vocabulary and still refuses the other's, so no already-published definition changes meaning. A definition that uses a neutral value must declare the `neutral-approval-modes.v1` runtime feature. On a CLI that predates the feature, both shipped adapters refuse the neutral value as out-of-vocabulary and the step fails closed, but the message names a bad permission mode rather than an old runtime; the feature declaration moves that diagnosis to the bundle compatibility check, before any order is offered.
69
94
 
70
95
  The Claude Code adapter refuses a `read-only` allow-list containing anything outside `Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, and the born-bound control tools. With `network: owenloop-only`, the allowed read-only built-ins narrow to `Read`, `Glob`, and `Grep`; `WebFetch` and `WebSearch` remain available only with `network: unrestricted`. The Claude Code adapter refuses an `owenloop-only` allow-list containing Bash, web tools, skills, agent delegation, or any unaudited tool. The Claude Code adapter also refuses authored external MCP tool names because the current option surface cannot prove an exact per-tool allow-list for an external server.
71
96
 
package/docs/authoring.md CHANGED
@@ -197,6 +197,13 @@ interpreted by the engine beyond that. All three (`executor`, `command`,
197
197
  like `model` and `workdir`. See [`docs/design.md` §27.4](design.md) for the
198
198
  full contract.
199
199
 
200
+ A command step's `consumes:` reach the command through its environment, not its
201
+ working directory: `owenloop work exec` sets `OWENLOOP_CONSUMES` with the JSON
202
+ inline, or `OWENLOOP_CONSUMES_FILE` with a path to it once that JSON exceeds
203
+ 64 KiB. See [`docs/bundles.md` § Consumed inputs for command
204
+ steps](bundles.md#consumed-inputs-for-command-steps) for the reader snippet and
205
+ the omitted-key rule.
206
+
200
207
  ## `capabilities:` — logical capability tags
201
208
 
202
209
  `capabilities:` is an optional list of strings on a step naming what that step
package/docs/bundles.md CHANGED
@@ -195,9 +195,11 @@ ambient values, so a nested agent receives its own identity rather than a
195
195
  stale parent value.
196
196
 
197
197
  Run identity is safe to expose because the engine derives it from the worker's
198
- own `--order` argument. Consumed artifact values are attacker-influenceable and
199
- are not exposed, and command text is not interpolated; no consume-side gate
200
- exists for either capability.
198
+ own `--order` argument. Consumed artifact values are attacker-influenceable, so
199
+ they reach a command child only through the environment block described in
200
+ [Consumed inputs for command steps](#consumed-inputs-for-command-steps), and
201
+ only after the consume-side gate below has admitted them. Command text is still
202
+ never interpolated with a consumed value.
201
203
 
202
204
  `OWENLOOP_BUNDLE_DIR` is read-only. Workers must never write into the directory.
203
205
  The workflow store is content-addressed and verifies the installed object again
@@ -206,6 +208,104 @@ fails the digest or file-integrity check instead of executing the modified
206
208
  bundle. Mount or copy enforcement is not part of the current contract;
207
209
  documentation is the enforcement boundary for now.
208
210
 
211
+ ## Consumed inputs for command steps
212
+
213
+ A command step reads its consumed inputs from the environment, not from its
214
+ working directory. Exactly one of two variables is set on every command spawn,
215
+ and the other is removed:
216
+
217
+ | Variable | Set when | Value |
218
+ | --- | --- | --- |
219
+ | `OWENLOOP_CONSUMES` | the serialized inputs are **at or under** 65536 bytes (`CONSUMES_INLINE_MAX_BYTES`) | `JSON.stringify(order.consumes)`, inline |
220
+ | `OWENLOOP_CONSUMES_FILE` | the serialized inputs are **strictly larger** | absolute path to a `0600` UTF-8 file holding that same JSON |
221
+
222
+ The threshold is measured as `Buffer.byteLength(json, 'utf8')`, so a payload of
223
+ multi-byte characters is sized by its real byte length. Both variables are
224
+ always resolved, never left to inheritance: a shift launched from inside another
225
+ command step already carries its parent order's values, and a stale
226
+ `OWENLOOP_CONSUMES_FILE` would name a directory that no longer exists.
227
+
228
+ Because exactly one is present, the presence of `OWENLOOP_CONSUMES_FILE` is the
229
+ whole discriminator. A reader is four lines:
230
+
231
+ ```js
232
+ const raw = process.env.OWENLOOP_CONSUMES_FILE
233
+ ? readFileSync(process.env.OWENLOOP_CONSUMES_FILE, 'utf8')
234
+ : process.env.OWENLOOP_CONSUMES;
235
+ const consumes = JSON.parse(raw ?? '{}');
236
+ ```
237
+
238
+ Rules a script can rely on:
239
+
240
+ - The JSON parses to the raw `order.consumes` object with no wrapper, version
241
+ field, or metadata — the same shape the `get_order` MCP tool serves an agent
242
+ step under `order.consumes`.
243
+ - A step with no consumed inputs still gets `OWENLOOP_CONSUMES`, holding `{}`.
244
+ Absent therefore means exactly one thing: read `OWENLOOP_CONSUMES_FILE`.
245
+ - An input a step declares but that was never produced is an **omitted key**,
246
+ not a `null`. Test presence with `'key' in consumes`.
247
+ - The overflow file lives in a private temp directory that owenloop removes
248
+ after the command exits. Read it during the run; do not stash the path.
249
+
250
+ These values are attacker-influenceable artifact data, which is why they travel
251
+ only in the environment block. Owenloop never puts a consumed value in argv or
252
+ in command text, and a command step's text is passed to `/bin/sh -c` exactly as
253
+ authored in the verified bundle. Delivery is gated: `resolveCommand` runs
254
+ consume-side verification under its hard rule and refuses the whole order when
255
+ the consumed evidence is absent, unverifiable, or invalid, so the environment
256
+ block is built only for an order whose inputs already verified.
257
+
258
+ ## Working directory for command steps
259
+
260
+ An order carries a `workdir` when its step declared `workdir:` or
261
+ `workdirFrom:`. A command step that declared neither still runs, and the
262
+ command inherits the directory the operator was standing in when they ran
263
+ `owenloop shift start`. Nothing is enforced today: a future release will
264
+ require a step to declare that inheritance explicitly.
265
+
266
+ **Where the fallback is recorded.** When it fires, `owenloop work exec` writes
267
+ one warning per spawn naming the step, the workflow and run ids, and the
268
+ resolved absolute path. That warning goes to the exec worker's own stderr.
269
+
270
+ Where the exec worker's stderr goes depends on how the worker was started:
271
+
272
+ | How the step ran | Where the warning lands |
273
+ | --- | --- |
274
+ | `owenloop work exec <workflow>/<run>` run directly | the operator's terminal, on stderr |
275
+ | dispatched by `owenloop shift start` | `<log-dir>/<run>.log`, on disk |
276
+
277
+ Under shift dispatch, `createDefaultSpawner` in
278
+ `packages/work/src/shift/spawn.ts` opens `<log-dir>/<run>.log` for append and
279
+ hands that one file descriptor to the worker's stdio slots 1 and 2 — the same
280
+ redirection a shell writes as `2>&1`. The file outlives both the worker and the
281
+ shift. See [`docs/shift-logs.md`](shift-logs.md) for the directory layout,
282
+ `--log-dir` resolution, and retention.
283
+
284
+ The receipt still does not carry the warning, and that is by design rather than
285
+ a gap: the receipt captures the **command's** streams, and this warning is the
286
+ **exec worker's** own. One destination each, no duplication.
287
+
288
+ Two consequences worth stating separately:
289
+
290
+ - Do not read the absence of a warning **in a terminal** during a shift as
291
+ evidence that a step resolved a `workdir` — under shift dispatch the warning
292
+ was never going to appear in a terminal. Read `<log-dir>/<run>.log`, or read
293
+ the order's `workdir` field.
294
+ - If the shift could not open a log (no writable log directory), the warning is
295
+ discarded exactly as it was before on-disk logging existed. The shift reports
296
+ that condition once on its own stderr and keeps dispatching.
297
+
298
+ Delivering this warning to a channel an operator can actually read was the
299
+ blocker on turning the fallback into a hard error. That half is now done. The
300
+ enforcement release — making a command step that declares neither `workdir:`
301
+ nor `workdirFrom:` fail instead of warn — remains a separate decision and has
302
+ not been made.
303
+
304
+ This section is about command steps only. An agent step resolves its working
305
+ directory through a different ladder (`packages/work/src/agent/workdir.ts`):
306
+ `OrderPacket.workdir`, then a per-run directory under the work root, then the
307
+ process cwd. It does not use the fallback described here.
308
+
209
309
  ## API results
210
310
 
211
311
  `packBundle(sourceDir)` returns: