owenloop 0.5.4 → 0.5.5

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 (37) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/dist/packages/work/src/agent/brief.js +57 -1
  3. package/dist/packages/work/src/agent/loop.d.ts +10 -1
  4. package/dist/packages/work/src/agent/loop.js +25 -0
  5. package/dist/packages/work/src/agent/workdir.d.ts +22 -0
  6. package/dist/packages/work/src/agent/workdir.js +80 -0
  7. package/dist/packages/work/src/exec/loop.d.ts +13 -1
  8. package/dist/packages/work/src/exec/loop.js +31 -0
  9. package/dist/packages/work/src/harness/claude.js +7 -1
  10. package/dist/packages/work/src/hold/mcp.d.ts +11 -2
  11. package/dist/packages/work/src/hold/mcp.js +69 -2
  12. package/dist/packages/work/src/hub/client.d.ts +8 -1
  13. package/dist/packages/work/src/hub/client.js +1 -0
  14. package/dist/packages/work/src/hub/types.d.ts +29 -0
  15. package/dist/packages/work/src/roles/agent-run.js +9 -1
  16. package/dist/packages/work/src/roles/exec.js +9 -0
  17. package/dist/packages/work/src/roles/shift.js +9 -1
  18. package/dist/packages/work/src/settings/settings.d.ts +20 -1
  19. package/dist/packages/work/src/settings/settings.js +23 -1
  20. package/dist/packages/work/src/shift/runtime.d.ts +7 -0
  21. package/dist/packages/work/src/shift/runtime.js +29 -4
  22. package/dist/packages/work/src/shift/spawn.d.ts +12 -2
  23. package/dist/packages/work/src/shift/spawn.js +16 -3
  24. package/dist/src/cli.js +54 -1
  25. package/dist/src/engine.d.ts +46 -1
  26. package/dist/src/engine.js +72 -0
  27. package/dist/src/index.d.ts +1 -1
  28. package/dist/src/index.js +1 -1
  29. package/dist/src/model.d.ts +29 -5
  30. package/dist/src/model.js +63 -14
  31. package/dist/src/types.d.ts +8 -2
  32. package/docs/cli.md +34 -0
  33. package/package.json +1 -1
  34. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  35. package/plugins/claude-code/plugin/.mcp.json +1 -1
  36. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  37. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/dist/src/model.js CHANGED
@@ -110,16 +110,39 @@ export function isStalled(a, cap) {
110
110
  export function isSchemaStalled(a, cap) {
111
111
  return !!a && cap > 0 && a.acceptance === 'rejected' && a.schemaRejects >= cap;
112
112
  }
113
+ /** Reason kinds that hold an artifact: the producer is not auto-eligible to re-fire. */
114
+ const HOLDING_KINDS = new Set(['invalidated-irreversible', 'question']);
113
115
  /**
114
- * True if the artifact is held (non-idempotent escalate) — rejected-and-held,
115
- * producer not auto-eligible to re-fire. Detected by the last reasons entry
116
- * having kind='invalidated-irreversible'. A retry call appends a 'structural'
117
- * entry, which clears the held condition automatically.
116
+ * True if the artifact is held — rejected-and-held, producer not auto-eligible
117
+ * to re-fire. Detected by the last reasons entry having a holding kind. A retry
118
+ * call appends a 'structural' entry, which clears the held condition
119
+ * automatically, so `retry --text '<answer>'` is the release for both kinds.
120
+ *
121
+ * TWO WAYS IN, ONE WAY OUT.
122
+ * - `invalidated-irreversible`: the engine held it because an input moved under
123
+ * a non-idempotent producer.
124
+ * - `question`: the producing STEP held it, via `Engine.ask`, because it could
125
+ * not proceed honestly and needs a human. Without this second kind an agent
126
+ * has no way to stop: its only alternatives are to submit something it does
127
+ * not believe (which greens and silently poisons every downstream step) or to
128
+ * end its turn without submitting (which re-arms the step into a retry storm
129
+ * whose every worker fails identically). Both were observed in production.
118
130
  */
119
131
  export function isHeld(a) {
120
132
  if (!a || a.acceptance !== 'rejected')
121
133
  return false;
122
- return a.reasons.length > 0 && a.reasons[a.reasons.length - 1].kind === 'invalidated-irreversible';
134
+ return a.reasons.length > 0 && HOLDING_KINDS.has(a.reasons[a.reasons.length - 1].kind);
135
+ }
136
+ /**
137
+ * The open question on a held artifact, if it is held by `ask`. Returns the
138
+ * question text so an operator-facing read can print WHAT is being asked
139
+ * instead of only that something is stuck — the whole point of the channel.
140
+ */
141
+ export function openQuestion(a) {
142
+ if (!a || a.acceptance !== 'rejected' || a.reasons.length === 0)
143
+ return undefined;
144
+ const last = a.reasons[a.reasons.length - 1];
145
+ return last.kind === 'question' ? last.text : undefined;
123
146
  }
124
147
  /**
125
148
  * §7 escalation trigger: has this artifact been judgment-rejected at least
@@ -962,18 +985,34 @@ export function workflowStatus(def, arts) {
962
985
  ? 'validation'
963
986
  : last.kind === 'invalidated-irreversible'
964
987
  ? 'invalidated-irreversible'
965
- : 'structural'
988
+ : last.kind === 'question'
989
+ ? 'question'
990
+ : 'structural'
966
991
  : 'unbuilt';
967
992
  const prod = stepByName(def, a.producer);
968
993
  const producePat = prod && produceOwning(prod, a.path);
969
994
  // Held artifacts (isHeld) surface as stalled: true — they require human intervention.
970
- const stalled = !!prod &&
971
- (isStalled(a, effectiveMaxAttempts(prod, producePat)) ||
972
- isSchemaStalled(a, effectiveMaxSchemaFailures(prod, producePat)) ||
973
- isHeld(a));
995
+ //
996
+ // `isHeld` is deliberately OUTSIDE the `prod &&` guard that the two counter
997
+ // caps sit inside. Those caps are read off a producer STEP, so they are
998
+ // meaningless without one — but held-ness is read off the artifact's own
999
+ // reason thread and is just as real for a `producer: human` input. Keeping
1000
+ // it inside the guard meant a human-produced artifact could never be
1001
+ // reported stalled no matter how many times it was rejected, so a run
1002
+ // waiting on a PERSON was indistinguishable from any other owed row. That
1003
+ // is the single thing an operator most needs told.
1004
+ const stalled = isHeld(a) ||
1005
+ (!!prod &&
1006
+ (isStalled(a, effectiveMaxAttempts(prod, producePat)) ||
1007
+ isSchemaStalled(a, effectiveMaxSchemaFailures(prod, producePat))));
974
1008
  const entry = { path: a.path, acceptance: a.acceptance, kind, stalled };
975
1009
  if (last)
976
1010
  entry.reason = last.text;
1011
+ // The question text is already in `reason`, but a caller filtering for
1012
+ // "what is waiting on me" should not have to infer it from a kind string.
1013
+ const q = openQuestion(a);
1014
+ if (q !== undefined)
1015
+ entry.question = q;
977
1016
  debts.push(entry);
978
1017
  }
979
1018
  debts.sort((x, y) => x.path.localeCompare(y.path));
@@ -1173,15 +1212,25 @@ export function buildTrace(def, artifacts, runs) {
1173
1212
  if (e.action === 'retry')
1174
1213
  totalRetries++;
1175
1214
  }
1176
- // Check stall: need the producer step's caps
1215
+ // Check stall. Two independent sources, and they are checked separately
1216
+ // on purpose:
1217
+ // 1. The two counter caps — read off the PRODUCER STEP, so they can only
1218
+ // be evaluated when there is a producer step to read them off.
1219
+ // 2. Held-ness — read off the artifact's own reason thread, so it is
1220
+ // just as true for a `producer: human` input. Checking it inside the
1221
+ // `if (producerStep)` block (as this did until 2026-08-15) meant an
1222
+ // artifact a PERSON owes could never appear in `stalledArtifacts`,
1223
+ // which is exactly the row a trace reader is looking for.
1224
+ let stalled = isHeld(art);
1177
1225
  const producerStep = def.steps.find((l) => l.name === art.producer);
1178
- if (producerStep) {
1226
+ if (!stalled && producerStep) {
1179
1227
  const producePat = produceOwning(producerStep, art.path);
1180
1228
  const stallJ = isStalled(art, effectiveMaxAttempts(producerStep, producePat));
1181
1229
  const stallS = isSchemaStalled(art, effectiveMaxSchemaFailures(producerStep, producePat));
1182
- if (stallJ || stallS)
1183
- stalledArtifacts.push(art.path);
1230
+ stalled = stallJ || stallS;
1184
1231
  }
1232
+ if (stalled)
1233
+ stalledArtifacts.push(art.path);
1185
1234
  const bio = {
1186
1235
  path: art.path,
1187
1236
  producer: art.producer,
@@ -31,9 +31,15 @@ export type Author = 'engine' | 'human' | string;
31
31
  * - `invalidated-irreversible`: the artifact was rejected-and-held because its inputs
32
32
  * moved and its producer step declared `effect: { idempotent: false, onInvalidate: 'escalate' }`.
33
33
  * The producer is NOT auto-eligible to re-fire; a human must intervene (retry / fix upstream).
34
+ * - `question`: the producing step ASKED a human and stopped, via `Engine.ask`.
35
+ * Holds exactly like `invalidated-irreversible` — the producer is not auto-eligible,
36
+ * so the step does not spin re-answering its own unanswered question — but it is a
37
+ * separate kind because the CAUSE is different and the audit trail should say so:
38
+ * nothing moved upstream, an agent decided it could not proceed honestly.
39
+ * Counts toward NO stall budget. A question is not a failed attempt.
34
40
  */
35
- export type RejectKind = 'judgment' | 'structural' | 'validation' | 'invalidated-irreversible' | 'exclusive';
36
- export type ReasonAction = 'reject' | 'retract' | 'skip' | 'reopen' | 'retry' | 'born-rejected' | 'schema-reject' | 'pinned';
41
+ export type RejectKind = 'judgment' | 'structural' | 'validation' | 'invalidated-irreversible' | 'question' | 'exclusive';
42
+ export type ReasonAction = 'reject' | 'retract' | 'skip' | 'reopen' | 'retry' | 'ask' | 'born-rejected' | 'schema-reject' | 'pinned';
37
43
  /** A JSON Schema, as authored in a definition: an object, or a boolean (allow/deny all). */
38
44
  export type JsonSchema = Record<string, unknown> | boolean;
39
45
  /** One entry in an artifact's append-only reason thread (design §4). */
package/docs/cli.md CHANGED
@@ -189,6 +189,7 @@ The same directory holds `credentials.json`, `allowed_signers`, `org-root.pub`,
189
189
  owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]
190
190
  [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]
191
191
  [--cache-dir <p>] [--state-dir <p>] [--log-dir <p>] [--log-max-age <ms>]
192
+ [--work-root <dir>]...
192
193
  ```
193
194
 
194
195
  At least one named crew is required unless `--all` is present. `--all` and
@@ -209,6 +210,7 @@ one loop sweep and exits instead of keeping the foreground daemon running.
209
210
  | `--cache-dir <p>` | cache root; precedence is flag, then `OWENLOOP_CACHE_DIR`, then `settings.cacheDir`, then `$XDG_CACHE_HOME/owenloop`, then `$HOME/.cache/owenloop` |
210
211
  | `--state-dir <p>` | socket and child-state root; precedence is flag, then `OWENLOOP_STATE_DIR`, then `settings.stateDir`, then `$XDG_STATE_HOME/owenloop/exec`, then `$HOME/.local/state/owenloop/exec`; the socket is `shift.sock` inside this directory |
211
212
  | `--log-dir <p>` | where `shift.log` and each `<run>.log` are written; precedence is flag, then `OWENLOOP_SHIFT_LOG_DIR`, then `settings.shiftLogDir`, then the resolved state directory |
213
+ | `--work-root <dir>` | **repeatable.** restrict this machine to orders whose working directory is inside one of these roots; precedence is the flags, then `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (a `:`-separated list), then `settings.allowedWorkdirRoots`. Each rung REPLACES the one below it rather than extending it. No rung set anywhere ⇒ **no restriction**, which is the default |
212
214
  | `--log-max-age <ms>` | worker-log retention, swept once at startup; precedence is flag, then `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`, then `settings.shiftLogMaxAgeMs`, then `1209600000` (14 days). `0` reaps every completed run's log at the next startup; there is no value that disables the sweep, and `shift.log` is never reaped |
213
215
 
214
216
  **On-disk logs.** A running shift appends its dispatch record to
@@ -219,6 +221,38 @@ dispatch: the shift reports it once on stderr and serves with logging disabled.
219
221
  Full field-by-field contract, retention rules, and uploader notes in
220
222
  [`docs/shift-logs.md`](shift-logs.md).
221
223
 
224
+ **Where a shift will do work.** A shift is not bound to a project: it is an
225
+ orchestrator that runs whatever its crews are offered. `--work-root` is how the
226
+ person who owns the machine bounds that — it is a **local** policy, declared at
227
+ the shift, and the hub is never asked and never informed in advance.
228
+
229
+ The check happens in the WORKER, not in dispatch. The shift's `whats_next` sweep
230
+ receives a `WorkOrder`, which carries no working directory at all; only the
231
+ `OrderPacket` a worker fetches with `get_order` has one. So `owenloop work exec`
232
+ and `owenloop work agent-run` each resolve the roots themselves — from
233
+ `OWENLOOP_ALLOWED_WORKDIR_ROOTS`, which the shift exports into every child it
234
+ spawns, or from the settings file when run by hand — and refuse there.
235
+
236
+ A refusal is a **release**, not a failure. The order is valid; this machine is
237
+ simply not configured to host that tree. The worker releases its claim, exits
238
+ non-zero, and writes one line to `<log-dir>/<run>.log` naming the directory and
239
+ the roots. The order returns to the hub's pickup window, where a machine that
240
+ *is* configured for that tree can take it.
241
+
242
+ Only a workdir the ORDER names is checked. A step that declares neither
243
+ `workdir:` nor `workdirFrom:` falls back to a directory the operator already
244
+ controls — the shift's own launch directory for a command step, or
245
+ `<workRoot>/<workflow>/<run>/` for an agent step — and is never denied.
246
+
247
+ `--work-root` is not `--work-root`'s neighbour `workRoot`. `workRoot` (settings,
248
+ `OWENLOOP_WORK_ROOT`) is the ONE directory owenloop **creates** per-run
249
+ directories under. `--work-root` / `allowedWorkdirRoots` is the SET of
250
+ directories an order is **allowed to name**. Neither derives from the other.
251
+
252
+ ```bash
253
+ owenloop shift start build --work-root ~/code --work-root /srv/work
254
+ ```
255
+
222
256
  **One harness per shift.** A shift has no per-order harness switch and no
223
257
  `--harness` flag. It never puts `--harness` on a worker's command line; each
224
258
  `agent-run` child resolves its own adapter, in this order:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.4",
3
+ "version": "0.5.5",
4
4
  "description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "typicalday",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.4",
3
+ "version": "0.5.5",
4
4
  "description": "Claude Code driver for owenloop — cross-harness shift and conduct skills driven by the owenloop CLI, plus one hub control-plane MCP server backing an author skill and a fallback worker, for conducting and authoring workflows against your hosted owenloop server.",
5
5
  "author": {
6
6
  "name": "Typical Day"
@@ -7,7 +7,7 @@
7
7
  "mcp"
8
8
  ],
9
9
  "env": {
10
- "OWENLOOP_PLUGIN_VERSION": "0.5.4"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.5"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.4",
3
+ "version": "0.5.5",
4
4
  "description": "Codex plugin for the owenloop workflow engine.",
5
5
  "skills": "./skills/",
6
6
  "mcpServers": "./.mcp.json"
@@ -6,7 +6,7 @@
6
6
  "mcp"
7
7
  ],
8
8
  "env": {
9
- "OWENLOOP_PLUGIN_VERSION": "0.5.4"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.5"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",