owenloop 0.5.25 → 0.5.27

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.
package/docs/bundles.md CHANGED
@@ -107,6 +107,8 @@ This Owenloop release advertises exactly these feature identifiers:
107
107
 
108
108
  - `harness-policy-enforcement.v1`
109
109
  - `native-judge-policy-inheritance.v1`
110
+ - `neutral-approval-modes.v1`
111
+ - `command-payload-file.v1`
110
112
 
111
113
  The running version comes from Owenloop's production `packageVersion()` source. A production build that cannot read a valid package version uses the `0.0.0` sentinel. The sentinel fails every declared `minVersion`, including `minVersion: "0.0.0"`, and the refusal tells the operator to install or upgrade Owenloop. The sentinel may still satisfy a feature-only declaration because feature support is evaluated independently.
112
114
 
@@ -298,6 +300,70 @@ run; only an accepted artifact with a declared bind can do that.
298
300
  An agent prompt can read the same value as `${MODIFIER}`. Unknown placeholders
299
301
  remain unchanged; when an order has no modifier, `${MODIFIER}` remains literal.
300
302
 
303
+ ## Returning a payload from a command step
304
+
305
+ A command step's accepted artifact is its whole `CommandReceipt`. To put a value
306
+ of its own inside that receipt — the thing a downstream `from: payload.value`
307
+ bind reads — a command has two ways to say it, and it must pick exactly one.
308
+
309
+ | Transport | How | Ceiling |
310
+ | --- | --- | --- |
311
+ | stdout marker | print one line beginning `##owenloop:payload## ` followed by JSON | 64 KiB of JSON text (`PAYLOAD_MAX_BYTES`) |
312
+ | payload file | write JSON to the path in `OWENLOOP_PAYLOAD_FILE` | 24 MB (`PAYLOAD_FILE_MAX_BYTES`) |
313
+
314
+ The marker is the older channel and is unchanged. The file exists because the
315
+ marker's ceiling is a *transport* limit on a single stdout line, while the hub
316
+ has always stored an artifact above 64 KiB in object storage up to its own
317
+ 25 MB cap. A result between those two numbers had nowhere to go: the runner
318
+ dropped the marker line and the step submitted a receipt with no payload.
319
+
320
+ `OWENLOOP_PAYLOAD_FILE` is set on **every** command spawn, not only when a
321
+ result is expected to be large, and it is always resolved rather than inherited
322
+ — a shift launched from inside another command step already carries its parent
323
+ order's value, and reading it would attribute one step's result to another. The
324
+ runner creates the private `0700` directory but **not** the file; the command
325
+ creates it, or leaves it absent.
326
+
327
+ ```sh
328
+ # Either of these is a complete producer.
329
+ echo "##owenloop:payload## $(jq -nc '{value:"deep"}')"
330
+ jq -nc '{value:"deep"}' > "$OWENLOOP_PAYLOAD_FILE"
331
+ ```
332
+
333
+ Rules a script can rely on:
334
+
335
+ - **Absent or empty means no payload.** A path that was never written, an empty
336
+ file, and a file holding only whitespace are all read as "this command
337
+ returned nothing", not as an error. That is what lets every existing
338
+ marker-only command keep working with the variable set.
339
+ - **Using both transports is refused by name.** If the file holds anything and a
340
+ marker line was also printed, neither is published: the receipt carries a
341
+ `payloadError` naming the conflict and both byte counts, and no `payload`.
342
+ Two statements of the result are a bug in the command, and picking one of them
343
+ would publish a value the author did not choose.
344
+ - **The reject directive works identically through either transport.** A payload
345
+ of the shape `{"reject":{"path":"...","text":"..."}}` sends the worker's
346
+ reject, from the file exactly as from the marker.
347
+ - **Over the cap is an error, not a truncation.** The size is taken from the
348
+ open descriptor before any bytes are read; over-cap produces a `payloadError`
349
+ naming the size and the cap, and no `payload`.
350
+ - **Anything that is not a regular file is an error.** A directory, a symbolic
351
+ link, or a device at that path produces a `payloadError` rather than being
352
+ read through. Only ENOENT is the ordinary absence.
353
+ - **The file lives only as long as the command.** It is in a private temp
354
+ directory that owenloop removes after the command exits, including when the
355
+ command is killed because the lease was lost. Write it during the run; do not
356
+ stash the path.
357
+
358
+ A definition whose command writes that file **must** declare the
359
+ `command-payload-file.v1` runtime feature. On a CLI that predates it the
360
+ variable is simply unset, and the natural defensive spelling
361
+ `> "${OWENLOOP_PAYLOAD_FILE:-/dev/null}"` then exits zero having written the
362
+ result to `/dev/null`. Nothing reports an error; the first sign of trouble is a
363
+ downstream bind failing at the hub, one step away from the cause. The feature
364
+ declaration moves that diagnosis to the bundle compatibility check, before any
365
+ order is offered.
366
+
301
367
  ## Working directory for command steps
302
368
 
303
369
  An order carries a `workdir` when its step declared `workdir:` or
package/docs/cli.md CHANGED
@@ -739,8 +739,12 @@ be parsed or the resolved value was invalid.
739
739
 
740
740
  The helper prints the selected word as ordinary stdout. A command artifact is
741
741
  submitted as the full `CommandReceipt`; if a workflow binds a field inside a
742
- command payload, the command must emit the `##owenloop:payload##` JSON marker and
743
- the bind must name that field (for example, `from: payload.value`).
742
+ command payload, the command must return that payload and the bind must name
743
+ the field (for example, `from: payload.value`). A command returns a payload
744
+ either by printing an `##owenloop:payload##` JSON marker line, capped at 64 KiB,
745
+ or by writing the JSON to the path in `OWENLOOP_PAYLOAD_FILE`, capped at 24 MB.
746
+ Doing both is refused by name rather than resolved by precedence. See
747
+ [Returning a payload from a command step](bundles.md#returning-a-payload-from-a-command-step).
744
748
 
745
749
  ### `work agent-run` — the only Step Agent dispatcher
746
750
 
package/docs/design.md CHANGED
@@ -1003,9 +1003,15 @@ with code `0`. A nonzero exit sends the worker's `reject` request for
1003
1003
  `order.judge` and submits no receipt. A signal or machinery failure has no
1004
1004
  verdict, so the worker issues neither verb and the reap path re-offers the order.
1005
1005
 
1006
- Command receipts may also carry a bounded JSON payload emitted by a stdout line
1007
- beginning with `##owenloop:payload##`. The last marker line wins, and the 64 KiB
1008
- JSON-text cap protects the runner because the runner does not buffer full stdout.
1006
+ Command receipts may also carry a bounded JSON payload, returned either by a
1007
+ stdout line beginning with `##owenloop:payload##` or by writing the JSON to the
1008
+ path the worker offers in `OWENLOOP_PAYLOAD_FILE`. The last marker line wins,
1009
+ and the marker's 64 KiB JSON-text cap protects the runner because the runner
1010
+ does not buffer full stdout. That cap is a property of the transport rather than
1011
+ of the result, which is why the file exists: it carries up to 24 MB, below the
1012
+ hub's own artifact cap. Returning a payload through both transports in one run
1013
+ is refused by name instead of resolved by precedence, because two statements of
1014
+ the result are an error in the command rather than a choice for the worker.
1009
1015
  A valid plain-step payload reject is delivered BEFORE any owed receipt is
1010
1016
  submitted. The hub refuses a reject from a run whose claim has closed, and a
1011
1017
  step's last owed submit is what closes it — so the reverse order made every
package/docs/routing.md CHANGED
@@ -564,8 +564,9 @@ from the run's stored value again — whatever the last accepted bind left there
564
564
  accepted artifact value is the whole `CommandReceipt`. The short form
565
565
  `bind: modifier` is shorthand for `{to: modifier, from: modifier}`. A
566
566
  `CommandReceipt` has no top-level `modifier` key, so that derived path does
567
- not resolve and the submit is refused. Have the command emit a payload marker —
568
- `##owenloop:payload##{"value":"deep"}` — and bind `from: payload.value`.
567
+ not resolve and the submit is refused. Have the command return a payload —
568
+ either the marker `##owenloop:payload##{"value":"deep"}` on stdout or the same
569
+ JSON written to `$OWENLOOP_PAYLOAD_FILE` — and bind `from: payload.value`.
569
570
 
570
571
  > **Not shipped.** The routing plan also calls for a hub-side routing alert of
571
572
  > kind `modifier-changed`, raised on each sync so an operator sees it. It exists
@@ -379,7 +379,10 @@ implemented at the consuming driver boundary and never delegated to the hub.
379
379
 
380
380
  ## Command payload and worker reject contracts
381
381
 
382
- A command worker may emit one payload marker line on stdout:
382
+ A command worker returns a payload through one of two transports, and the
383
+ receipt records exactly one of `payload` or `payloadError` either way.
384
+
385
+ The first is a marker line on stdout:
383
386
 
384
387
  ```text
385
388
  ##owenloop:payload## {"...json..."}
@@ -390,6 +393,24 @@ beginning of the line. A marker in the middle of a line is not a match. The JSON
390
393
  text after the marker is capped at 64 KiB. A missing marker leaves `payload`
391
394
  out of the `CommandReceipt`; malformed or over-cap JSON produces
392
395
  `payloadError` and no `payload`, while leaving the command exit code unchanged.
396
+
397
+ The second is a file. The worker sets `OWENLOOP_PAYLOAD_FILE` on every command
398
+ spawn to an absolute path inside a private `0700` directory it creates and
399
+ removes around the command's lifetime, and the command may write its JSON there
400
+ instead. The file's size is taken from the open descriptor before any bytes are
401
+ read and is capped at 24 MB, which is below the hub's artifact cap so that a
402
+ payload the worker accepts is one the hub can store. A path that does not exist,
403
+ holds nothing, or holds only whitespace is read as an absent payload — that is
404
+ what keeps a marker-only command working with the variable set. Anything at the
405
+ path that is not a regular file, and any read or parse failure, produces
406
+ `payloadError` and no `payload`. The worker opens the path without following
407
+ symbolic links and without blocking, so a path replaced mid-run cannot stall it.
408
+
409
+ Supplying both transports in one run is a refusal, not a precedence rule: the
410
+ receipt carries a `payloadError` naming the conflict and both byte counts, and
411
+ no `payload`. A definition whose command writes the file must declare the
412
+ `command-payload-file.v1` runtime feature, because an older worker leaves the
413
+ variable unset and the payload is then written nowhere without any error.
393
414
  When the hub supplies authoritative output-version metadata and the driver can
394
415
  sign, the parsed payload is part of the receipt value covered by the DSSE
395
416
  submission proof. Current successful producer command receipts are unsigned
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.25",
3
+ "version": "0.5.27",
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.25",
3
+ "version": "0.5.27",
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.25"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.27"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.25",
3
+ "version": "0.5.27",
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.25"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.27"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",