owenloop 0.4.1 → 0.5.0
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/CHANGELOG.md +26 -0
- package/README.md +58 -31
- package/bin/owenloop.mjs +2 -2
- package/dist/packages/work/src/agent/brief.d.ts +172 -0
- package/dist/packages/work/src/agent/brief.js +193 -0
- package/dist/packages/work/src/agent/loop.d.ts +135 -0
- package/dist/packages/work/src/agent/loop.js +542 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +90 -0
- package/dist/packages/work/src/bundle/cache.js +324 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
- package/dist/packages/work/src/bundle/fetch.js +325 -0
- package/dist/packages/work/src/bundle/types.d.ts +160 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/loop.d.ts +29 -0
- package/dist/packages/work/src/exec/loop.js +215 -0
- package/dist/packages/work/src/exec/receipt.d.ts +38 -0
- package/dist/packages/work/src/exec/receipt.js +21 -0
- package/dist/packages/work/src/exec/runner.d.ts +65 -0
- package/dist/packages/work/src/exec/runner.js +185 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +127 -0
- package/dist/packages/work/src/harness/claude.d.ts +128 -0
- package/dist/packages/work/src/harness/claude.js +635 -0
- package/dist/packages/work/src/harness/codex.d.ts +110 -0
- package/dist/packages/work/src/harness/codex.js +896 -0
- package/dist/packages/work/src/harness/contract.d.ts +283 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +90 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
- package/dist/packages/work/src/harness/permissions.d.ts +62 -0
- package/dist/packages/work/src/harness/permissions.js +93 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +163 -0
- package/dist/packages/work/src/harness/session-store.js +319 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +55 -0
- package/dist/packages/work/src/hold/mcp.js +149 -0
- package/dist/packages/work/src/hub/client.d.ts +22 -0
- package/dist/packages/work/src/hub/client.js +78 -0
- package/dist/packages/work/src/hub/types.d.ts +290 -0
- package/dist/packages/work/src/hub/types.js +28 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
- package/dist/packages/work/src/roles/agent-run.js +447 -0
- package/dist/packages/work/src/roles/exec.d.ts +40 -0
- package/dist/packages/work/src/roles/exec.js +203 -0
- package/dist/packages/work/src/roles/hold.d.ts +68 -0
- package/dist/packages/work/src/roles/hold.js +324 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +59 -0
- package/dist/packages/work/src/roles/lint.js +200 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +66 -0
- package/dist/packages/work/src/roles/shift.d.ts +12 -0
- package/dist/packages/work/src/roles/shift.js +228 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +120 -0
- package/dist/packages/work/src/settings/settings.js +116 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +120 -0
- package/dist/packages/work/src/shift/loop.js +468 -0
- package/dist/packages/work/src/shift/protocol.d.ts +91 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +43 -0
- package/dist/packages/work/src/shift/runtime.js +274 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +86 -0
- package/dist/packages/work/src/shift/spawn.js +100 -0
- package/dist/packages/work/src/shift/state.d.ts +77 -0
- package/dist/packages/work/src/shift/state.js +162 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/{cli.d.ts → src/cli.d.ts} +18 -3
- package/dist/{cli.js → src/cli.js} +770 -114
- package/dist/{credentials.d.ts → src/credentials.d.ts} +18 -12
- package/dist/{credentials.js → src/credentials.js} +14 -12
- package/dist/{defs.js → src/defs.js} +36 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +14 -14
- package/dist/{hub.d.ts → src/hub.d.ts} +205 -10
- package/dist/{hub.js → src/hub.js} +370 -12
- package/dist/{index.d.ts → src/index.d.ts} +1 -1
- package/dist/{index.js → src/index.js} +1 -1
- package/dist/{mcp → src/mcp}/serve.d.ts +5 -4
- package/dist/{mcp → src/mcp}/serve.js +168 -31
- package/dist/{mcp → src/mcp}/server.d.ts +6 -9
- package/dist/{mcp → src/mcp}/server.js +6 -9
- package/dist/{model.js → src/model.js} +1 -1
- package/dist/{types.d.ts → src/types.d.ts} +18 -18
- package/dist/{util.d.ts → src/util.d.ts} +3 -2
- package/dist/{util.js → src/util.js} +3 -2
- package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
- package/dist/{owenwork.js → src/work-settings.js} +27 -27
- package/docs/authoring.md +93 -53
- package/docs/cli.md +597 -76
- package/docs/design.md +33 -33
- package/docs/embedding.md +10 -9
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +17 -8
- /package/dist/{add.d.ts → src/add.d.ts} +0 -0
- /package/dist/{add.js → src/add.js} +0 -0
- /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
- /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
- /package/dist/{factory.js → src/factory.js} +0 -0
- /package/dist/{lock.d.ts → src/lock.d.ts} +0 -0
- /package/dist/{lock.js → src/lock.js} +0 -0
- /package/dist/{model.d.ts → src/model.d.ts} +0 -0
- /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
- /package/dist/{paths.js → src/paths.js} +0 -0
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
- /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
- /package/dist/{untar.js → src/untar.js} +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,32 @@ All notable changes to this project are documented here. The format is based on
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
|
|
5
5
|
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
+
## [0.5.0](https://github.com/typicalday/owenloop/compare/v0.4.1...v0.5.0) (2026-08-04)
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
### ⚠ BREAKING CHANGES
|
|
11
|
+
|
|
12
|
+
* **cli:** fold owenwork execution CLI into owenloop work ([#91](https://github.com/typicalday/owenloop/issues/91))
|
|
13
|
+
* **cli:** `owenloop binding rm` now requires a `<pool>` argument (`owenloop binding rm <label> <pool>`), and both `binding new` and `binding rm` print new stdout shapes. `binding new` no longer reports `previousPool`; scripts that read it must use `alreadyBound` / `boundPoolCount` instead. The CLI now requires a hub serving `add_label_binding` and `remove_label_binding`.
|
|
14
|
+
|
|
15
|
+
### Features
|
|
16
|
+
|
|
17
|
+
* add durable shift daemon ([#92](https://github.com/typicalday/owenloop/issues/92)) ([2c68808](https://github.com/typicalday/owenloop/commit/2c6880891d904067071904a3cfda8461ffc2587d))
|
|
18
|
+
* **cli,mcp:** selectable scopes for agent-identity minting ([#83](https://github.com/typicalday/owenloop/issues/83)) ([f9b7a55](https://github.com/typicalday/owenloop/commit/f9b7a559e9ab8f27bdaf15cf26dd6dcc8968c6a4))
|
|
19
|
+
* **cli:** fold owenwork execution CLI into owenloop work ([#91](https://github.com/typicalday/owenloop/issues/91)) ([1ed865a](https://github.com/typicalday/owenloop/commit/1ed865ae6d03cbb176d81e26f2ecce60a5cebd1c))
|
|
20
|
+
* **cli:** migrate binding commands to many-to-many label bindings ([6ba3cc2](https://github.com/typicalday/owenloop/commit/6ba3cc254f8874f8cb734d596b1b6d267c4b5946))
|
|
21
|
+
* **cli:** owenloop binding new|rm|list — label→pool bindings + author docs ([#85](https://github.com/typicalday/owenloop/issues/85)) ([c561861](https://github.com/typicalday/owenloop/commit/c561861c208d96d576997939e33063db8de1670b))
|
|
22
|
+
* **cli:** owenloop pool new|rm|list, pool member add|rm ([#88](https://github.com/typicalday/owenloop/issues/88)) ([8ad5fab](https://github.com/typicalday/owenloop/commit/8ad5fabc454650fed6f006b8b3b55d001d102d85))
|
|
23
|
+
* **mcp:** add pool tools (list_pools/create_pool/add_pool_member/remove_pool_member) ([#89](https://github.com/typicalday/owenloop/issues/89)) ([be2d667](https://github.com/typicalday/owenloop/commit/be2d6678d7da6de14bdb1a90f99c5077f1b95c86))
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
### Bug Fixes
|
|
27
|
+
|
|
28
|
+
* **cli:** unify add/push/check's definite-defect predicate via shared helper ([#81](https://github.com/typicalday/owenloop/issues/81)) ([0a43b99](https://github.com/typicalday/owenloop/commit/0a43b99bf3f7b615d74fe4f3780b775adf8c12a8))
|
|
29
|
+
* correct three vocabulary defects found in post-merge audit ([b43f5f6](https://github.com/typicalday/owenloop/commit/b43f5f696d74e35244ed7a355dcf106ad386f53b))
|
|
30
|
+
* **mcp:** sync presence_ping/list_conductors doc-text with hub behavior (W9.4) ([#87](https://github.com/typicalday/owenloop/issues/87)) ([72fc488](https://github.com/typicalday/owenloop/commit/72fc488c2fab055e64951482ff625483bdb927f1))
|
|
31
|
+
* repair and promote compile-dev-playbook, drop stray FUNDING.yml ([#99](https://github.com/typicalday/owenloop/issues/99)) ([7c78094](https://github.com/typicalday/owenloop/commit/7c780945841eb41467d508cac864b3262d5a8f38))
|
|
32
|
+
|
|
7
33
|
## [0.4.1](https://github.com/typicalday/owenloop/compare/v0.4.0...v0.4.1) (2026-07-22)
|
|
8
34
|
|
|
9
35
|
|
package/README.md
CHANGED
|
@@ -48,11 +48,11 @@ steps:
|
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
You don't drive this by hand. An orchestrator — an agent skill, a plain
|
|
51
|
-
`while` loop, your own code — ticks the engine, hands each job to
|
|
51
|
+
`while` loop, your own code — ticks the engine, hands each job to a Step Agent,
|
|
52
52
|
and reports results back. Here's what the engine enforces as that loop runs:
|
|
53
53
|
|
|
54
54
|
1. **The writer cannot start early.** The first tick emits exactly one order —
|
|
55
|
-
the researcher's. There is no writer job to hand out, so no eager
|
|
55
|
+
the researcher's. There is no writer job to hand out, so no eager Step Agent can
|
|
56
56
|
write a report from findings that don't exist. The hope version is a
|
|
57
57
|
prompt: *"wait until research is complete before writing."*
|
|
58
58
|
|
|
@@ -63,7 +63,7 @@ and reports results back. Here's what the engine enforces as that loop runs:
|
|
|
63
63
|
|
|
64
64
|
3. **The report can't approve itself.** When the writer commits `report`, it
|
|
65
65
|
lands in `submitted`, not done. The reviewer is a separate order to a
|
|
66
|
-
separate
|
|
66
|
+
separate Step Agent — one that never saw the writer's reasoning. A rejection
|
|
67
67
|
re-arms the writer with the reviewer's reasons attached to its next job.
|
|
68
68
|
The hope version: *"review your work before finishing"* — the fox
|
|
69
69
|
auditing the henhouse.
|
|
@@ -140,7 +140,7 @@ Two things make this more than running steps in dependency order:
|
|
|
140
140
|
the inputs it was built from are still green and unchanged. Re-run an early step and
|
|
141
141
|
everything built on it quietly falls back to a debt — no code required to invalidate it.
|
|
142
142
|
- **Rejections carry reasons.** When a reviewer rejects an output, the text rides along.
|
|
143
|
-
The next job for the producer shows *why* it's being asked again, so the
|
|
143
|
+
The next job for the producer shows *why* it's being asked again, so the Step Agent has
|
|
144
144
|
the feedback in hand. (Three flavors: a reviewer's **judgment**, the engine's own
|
|
145
145
|
**schema** refusal of a malformed value, and **structural** knock-backs from a
|
|
146
146
|
change cascading downstream.)
|
|
@@ -158,7 +158,7 @@ Two things make this more than running steps in dependency order:
|
|
|
158
158
|
*width* — a producer can emit any number of elements — but the wiring graph
|
|
159
159
|
itself (which steps exist, what each consumes and produces) is fixed when
|
|
160
160
|
the definition loads, not mutable while an instance runs.
|
|
161
|
-
- **Not a command runner.** `
|
|
161
|
+
- **Not a command runner.** `executor:`/`command:` declare which kind of
|
|
162
162
|
executor an order is for and carry a command string through untouched —
|
|
163
163
|
the engine never shells out, executes, or interprets it. Actually running
|
|
164
164
|
anything is always the dispatcher's job, on the other side of `tick`.
|
|
@@ -247,7 +247,7 @@ to a human, or run a compensating step instead of silently re-firing. See
|
|
|
247
247
|
|
|
248
248
|
`model: fast | standard | strong | strongest` declares intent, not a vendor
|
|
249
249
|
id — the engine passes it through untouched to whatever dispatches your
|
|
250
|
-
|
|
250
|
+
Step Agents. A portable workflow says "this step needs strong judgment"; the
|
|
251
251
|
host binds that to whatever model it runs on. `strong` is a high-capability
|
|
252
252
|
workhorse tier, not the host's single most capable model — that's what the
|
|
253
253
|
opt-in `strongest` tier is for, reserved for the rare step where nothing less
|
|
@@ -256,17 +256,17 @@ will do. See
|
|
|
256
256
|
|
|
257
257
|
### Worker dispatch
|
|
258
258
|
|
|
259
|
-
`
|
|
259
|
+
`executor: agent | command | …` declares which kind of executor a step's order
|
|
260
260
|
is for — the default (`agent`, silent when omitted) is unaffected; every
|
|
261
261
|
def written before this feature stays byte for byte the same. Opt a step
|
|
262
|
-
into `
|
|
262
|
+
into `executor: command` and give it a `command:` string to switch it to a
|
|
263
263
|
deterministic executor instead of an LLM — the engine never runs it, only
|
|
264
264
|
carries it through on the order for your dispatcher to branch on. An
|
|
265
265
|
optional `spec:` map carries further opaque config (a timeout, a working
|
|
266
266
|
directory), and a judge entry accepts the same fields, so a quality gate can
|
|
267
267
|
be a script's exit code instead of a verdict. See
|
|
268
|
-
[`docs/authoring.md`](docs/authoring.md#
|
|
269
|
-
[`command-
|
|
268
|
+
[`docs/authoring.md`](docs/authoring.md#executor--declaring-the-executor) and
|
|
269
|
+
[`command-executor.yaml`](examples/workflows/command-executor.yaml).
|
|
270
270
|
|
|
271
271
|
### Event subscription — for embedding
|
|
272
272
|
|
|
@@ -295,14 +295,12 @@ looks like:
|
|
|
295
295
|
- **Your own harness** — a `while` loop, a cron job, a CI stage: tick, run
|
|
296
296
|
each order with whatever executes your work (an agent CLI, an API call, a
|
|
297
297
|
script), report, repeat. Fully deterministic dispatch if you want it —
|
|
298
|
-
see [Embedding it](#embedding-it) for the in-process version.
|
|
299
|
-
|
|
300
|
-
ships no host harness of its own.
|
|
301
|
-
- **An agent as the orchestrator** — point any tool-using agent (Claude Code,
|
|
298
|
+
see [Embedding it](#embedding-it) for the in-process version. The root `owenloop shift` command is the standing Shift runtime — the engine core still ships no host harness of its own.
|
|
299
|
+
- **A Prime Agent as the orchestrator** — point any tool-using agent (Claude Code,
|
|
302
300
|
Codex, Gemini CLI, anything that can run a shell command) at the CLI and
|
|
303
301
|
tell it to drive the instance to done. A slash command or skill that wraps
|
|
304
302
|
this turns "run the release workflow" into one line.
|
|
305
|
-
- **
|
|
303
|
+
- **A Prime Agent structuring its own work, inline** — mid-task, the Prime Agent authors
|
|
306
304
|
a throwaway workflow, drives itself through it, and deletes it: the engine
|
|
307
305
|
as scratch discipline rather than standing infrastructure.
|
|
308
306
|
|
|
@@ -323,14 +321,14 @@ patterns ready-made:
|
|
|
323
321
|
|
|
324
322
|
## Quick start
|
|
325
323
|
|
|
326
|
-
Install the owenloop skills for whatever
|
|
324
|
+
Install the owenloop skills for whatever Prime Agent you use — Claude Code, Codex,
|
|
327
325
|
Cursor, and most others:
|
|
328
326
|
|
|
329
327
|
```sh
|
|
330
328
|
npx skills add typicalday/owenloop
|
|
331
329
|
```
|
|
332
330
|
|
|
333
|
-
Then ask your
|
|
331
|
+
Then ask your Prime Agent for what you want:
|
|
334
332
|
|
|
335
333
|
> Use owenloop-author to build me a workflow that researches a topic, writes
|
|
336
334
|
> a report, and doesn't accept it until an independent reviewer signs off —
|
|
@@ -342,17 +340,40 @@ fresh subagent, relaying knock-backs, and escalating stalls to you. Already
|
|
|
342
340
|
have a def? *"Conduct the report workflow"* hands it to
|
|
343
341
|
[`owenloop-conduct`](skills/owenloop-conduct/SKILL.md). The engine itself
|
|
344
342
|
arrives via `npx owenloop` (Node ≥ 22.13 required) — no clone, no build, no
|
|
345
|
-
environment variables, no CLI verbs to memorize.
|
|
343
|
+
environment variables, no CLI verbs to memorize. The same package also includes
|
|
344
|
+
the execution-side companion; use `owenloop work <subcommand>` for lower-level
|
|
345
|
+
execution tasks. There is no separate `owenwork` package or binary.
|
|
346
|
+
|
|
347
|
+
For a foreground local shift, start the daemon in one terminal. Run the client
|
|
348
|
+
commands from another terminal:
|
|
349
|
+
|
|
350
|
+
```sh
|
|
351
|
+
# Terminal 1: foreground daemon
|
|
352
|
+
owenloop shift start alpha
|
|
353
|
+
|
|
354
|
+
# Terminal 2: client calls
|
|
355
|
+
owenloop shift next
|
|
356
|
+
owenloop shift status
|
|
357
|
+
owenloop shift end
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
`shift start` requires at least one named crew unless you pass `--all`
|
|
361
|
+
explicitly; `--all` serves all Crews for the Scoped Identity. `shift next` waits
|
|
362
|
+
up to 90 seconds by default. For flags, JSON output, daemon behavior, and exit
|
|
363
|
+
codes, see the [`shift` reference](docs/cli.md#shift--foreground-daemon-and-client).
|
|
346
364
|
|
|
347
365
|
**Want to see or drive the machinery yourself?** Everything above goes
|
|
348
366
|
through the same small CLI (`create`, `tick`, `green`, `reject`, …).
|
|
349
367
|
[`docs/cli.md`](docs/cli.md) has the full command reference and a hand-driven
|
|
350
368
|
walkthrough of a pipeline — including a rejection knock-back and a stall —
|
|
351
|
-
and [`examples/workflows`](examples/workflows) has
|
|
369
|
+
and [`examples/workflows`](examples/workflows) has seventeen runnable defs, from a
|
|
352
370
|
minimal review loop ([`delivery`](examples/workflows/delivery.yaml)) to a
|
|
353
|
-
full production line ([`ship`](examples/workflows/ship.yaml))
|
|
371
|
+
full production line ([`ship`](examples/workflows/ship.yaml)), a
|
|
354
372
|
collections-heavy research pipeline
|
|
355
|
-
([`research`](examples/workflows/research.yaml))
|
|
373
|
+
([`research`](examples/workflows/research.yaml)), and a compiler that turns
|
|
374
|
+
live vendor docs into a new gate-checked def
|
|
375
|
+
([`compile-dev-playbook`](examples/workflows/compile-dev-playbook.yaml)).
|
|
376
|
+
Full YAML grammar:
|
|
356
377
|
[`docs/authoring.md`](docs/authoring.md). Driving it from your own code:
|
|
357
378
|
[Embedding it](#embedding-it).
|
|
358
379
|
|
|
@@ -360,7 +381,7 @@ Want someone else's workflow defs instead of writing your own?
|
|
|
360
381
|
`owenloop add <owner>/<repo>` fetches a public GitHub repo's `workflows/**`,
|
|
361
382
|
validates every def, and installs them locally with pinned provenance — see
|
|
362
383
|
the `add` entry in [`docs/cli.md`](docs/cli.md). An installed def's steps later
|
|
363
|
-
run with your
|
|
384
|
+
run with your Step Agents' full privileges and owenloop never executes them itself,
|
|
364
385
|
so install only sources you trust, and pin a commit SHA (`@<sha>`) for anything
|
|
365
386
|
you re-add — the [trust model](docs/cli.md#add--installing-shared-workflow-defs-from-github)
|
|
366
387
|
is spelled out there.
|
|
@@ -371,17 +392,23 @@ goes into the macOS Keychain or a `0600` file, never the repo, and is verified
|
|
|
371
392
|
against the hub before it's ever stored), `owenloop connect` binds the project
|
|
372
393
|
to a hub, and `owenloop push` publishes your defs — idempotent against the
|
|
373
394
|
hub's own def hashes, so an unchanged re-push is a no-op. `owenloop agent new
|
|
374
|
-
<name>` mints
|
|
395
|
+
<name>` mints a Scoped Identity on the hub and stores its token in slot
|
|
375
396
|
`agent:<name>` without ever printing it. See the
|
|
376
397
|
[Hub](docs/cli.md#hub-login--connect--push--logout) section in `docs/cli.md`.
|
|
377
398
|
|
|
378
|
-
Setting up a machine from scratch? `owenloop setup`
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
399
|
+
Setting up a machine from scratch? `owenloop setup` may sign you in as a human
|
|
400
|
+
and, when needed, mint or rekey and store a Scoped Identity. Setup writes only
|
|
401
|
+
`hubOrigin` into the execution settings file, preserving the other keys. The
|
|
402
|
+
file is `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is
|
|
403
|
+
set to a non-blank value; otherwise `$HOME/.config/owenloop/settings.json`. For
|
|
404
|
+
a non-default account,
|
|
405
|
+
setup only prints the `OWENLOOP_ACCOUNT=<name>` instruction. Setup probes the
|
|
406
|
+
Claude Code plugin and, when it is missing, prints the manual commands
|
|
407
|
+
`claude plugin marketplace add owenloop` and
|
|
408
|
+
`claude plugin install owenloop@owenloop`; setup does not install the plugin.
|
|
409
|
+
`owenloop doctor` is the read-only counterpart: it checks each piece and prints a
|
|
410
|
+
`✓`/`✗` line with the remedy. See [`setup`](docs/cli.md#setup--onboard-a-machine)
|
|
411
|
+
and [`doctor`](docs/cli.md#doctor--check-a-machines-install) in `docs/cli.md`.
|
|
385
412
|
|
|
386
413
|
Driving the hub from an MCP host instead? `owenloop mcp` serves the hub control
|
|
387
414
|
plane to a local MCP host (Claude Code) over stdio — MCP hosts spawn it, you
|
|
@@ -483,7 +510,7 @@ const wf = engine.createInstance('delivery', {
|
|
|
483
510
|
provide: { proposal: { text: 'add dark mode' } },
|
|
484
511
|
});
|
|
485
512
|
|
|
486
|
-
// the
|
|
513
|
+
// the Step Agent loop: tick → run → report
|
|
487
514
|
const { orders } = engine.tick(wf);
|
|
488
515
|
for (const order of orders) {
|
|
489
516
|
const result = await runYourAgent(order); // ← your domain
|
package/bin/owenloop.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// Thin shim: all real logic lives in src/cli.ts (so it stays testable) and is
|
|
3
|
-
// shipped compiled to dist/cli.js. Node cannot type-strip files under
|
|
3
|
+
// shipped compiled to dist/src/cli.js. Node cannot type-strip files under
|
|
4
4
|
// node_modules, so the published package runs plain JS, not TypeScript source.
|
|
5
|
-
import { mainAsync } from '../dist/cli.js';
|
|
5
|
+
import { mainAsync } from '../dist/src/cli.js';
|
|
6
6
|
|
|
7
7
|
mainAsync(process.argv.slice(2)).then((code) => process.exit(code));
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Brief rendering + the born-bound work-holder MCP mount, for the `agent-run`
|
|
3
|
+
* worker (Phase 3).
|
|
4
|
+
*
|
|
5
|
+
* Two pure functions, no I/O:
|
|
6
|
+
*
|
|
7
|
+
* - `renderBrief(templateContent, spec)` — the SAME four-token substitution the
|
|
8
|
+
* legacy stamp path performs when it writes a per-order Step Agent file,
|
|
9
|
+
* minus the file. The worker hands the result straight to
|
|
10
|
+
* `HarnessAdapter.start` as `StartArgs.brief`.
|
|
11
|
+
* - `buildOwenloopMcp(spec)` — the `{command, args}` stdio mount for owenloop's
|
|
12
|
+
* own work-holder MCP surface, byte-identical to the `mcpServers.owenloop`
|
|
13
|
+
* literal the legacy host adapter injects into stamped frontmatter today.
|
|
14
|
+
*
|
|
15
|
+
* WHY THE TOKENS ARE DECLARED HERE AND NOT IMPORTED (plan D4): the legacy
|
|
16
|
+
* host-adapter module under `src/adapters/` is what Phase 5 deletes, and it is
|
|
17
|
+
* vendor-named. Importing from it would point new code at a module on its way
|
|
18
|
+
* out. The duplication is deliberate and `test/agent-brief.test.ts` asserts the
|
|
19
|
+
* two sets are equal strings, so it cannot drift silently.
|
|
20
|
+
*
|
|
21
|
+
* Phase 4 adds a third pure function, `renderRejection` — see its own header.
|
|
22
|
+
*
|
|
23
|
+
* CREDENTIAL STANCE: `buildOwenloopMcp` puts NO credential in argv. The mount
|
|
24
|
+
* carries `--as <account>` — a Scoped Identity *selector*, not a secret — and
|
|
25
|
+
* the mounted work-holder resolves its own bearer from owenloop's credential
|
|
26
|
+
* store. `test/agent-brief.test.ts` asserts this. `renderRejection` reads only
|
|
27
|
+
* `OrderPacket.owes`, which carries no credential either, and
|
|
28
|
+
* `test/agent-rejection.test.ts` asserts that too. The separate, environmental
|
|
29
|
+
* `OWENLOOP_TOKEN` inheritance problem — Phase 3 pointed it at Phase 4, Phase 4
|
|
30
|
+
* re-deferred it — is CLOSED as of Phase 6: `filterOwenloopEnv`
|
|
31
|
+
* (`src/harness/child-env.ts`) is an allowlist over the `OWENLOOP_*` namespace,
|
|
32
|
+
* both adapters pass their child `env` through it, and `agent-run` stopped
|
|
33
|
+
* honouring the override on its own side in the same commit so the two sides
|
|
34
|
+
* cannot authenticate as different principals. See `docs/agent-runner.md`.
|
|
35
|
+
*/
|
|
36
|
+
import type { OrderPacket } from '../hub/types.ts';
|
|
37
|
+
/** The composite `<workflow>/<run>` order id token. */
|
|
38
|
+
export declare const ORDER_TOKEN = "__OWENLOOP_ORDER__";
|
|
39
|
+
/** The hub origin token. */
|
|
40
|
+
export declare const ORIGIN_TOKEN = "__OWENLOOP_ORIGIN__";
|
|
41
|
+
/** The Scoped Identity account token. */
|
|
42
|
+
export declare const ACCOUNT_TOKEN = "__OWENLOOP_ACCOUNT__";
|
|
43
|
+
/** The dispatching Shift's self-declared id token (advisory only). */
|
|
44
|
+
export declare const SHIFT_TOKEN = "__OWENLOOP_SHIFT__";
|
|
45
|
+
/**
|
|
46
|
+
* Everything the four-token substitution and the MCP mount need.
|
|
47
|
+
*
|
|
48
|
+
* `run` is the BARE run id; it composes with `workflow` into the
|
|
49
|
+
* `<workflow>/<run>` composite every hub verb wants. `shiftId` is advisory
|
|
50
|
+
* attribution only (D8/INV-82) and absent resolves to the empty string.
|
|
51
|
+
*/
|
|
52
|
+
export interface BriefSpec {
|
|
53
|
+
workflow: string;
|
|
54
|
+
run: string;
|
|
55
|
+
origin: string;
|
|
56
|
+
account: string;
|
|
57
|
+
shiftId?: string;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Substitute the four dispatch tokens into a step template.
|
|
61
|
+
*
|
|
62
|
+
* `split(...).join(...)` rather than a regex replace, mirroring the legacy
|
|
63
|
+
* stamp exactly: it replaces every occurrence and treats the token as a literal
|
|
64
|
+
* (no accidental `$&` expansion from template text the author controls).
|
|
65
|
+
*/
|
|
66
|
+
export declare function renderBrief(templateContent: string, spec: BriefSpec): string;
|
|
67
|
+
/**
|
|
68
|
+
* The born-bound work-holder mount handed to `HarnessAdapter.start` as
|
|
69
|
+
* `StartArgs.owenloopMcp`. The adapter mounts it verbatim and never builds it.
|
|
70
|
+
*
|
|
71
|
+
* `--shift=<cid>` is ONE argv element, not two. An absent cid then degrades
|
|
72
|
+
* to the single well-formed string `"--shift="` instead of a dangling flag
|
|
73
|
+
* with no value or a null array entry, which is what `hold`'s parser expects.
|
|
74
|
+
* (The shape originated with the deleted stamp path, which had to survive a YAML
|
|
75
|
+
* args array; it is kept because it is still the correct, unambiguous form.)
|
|
76
|
+
*/
|
|
77
|
+
export declare function buildOwenloopMcp(spec: BriefSpec): {
|
|
78
|
+
command: string;
|
|
79
|
+
args: string[];
|
|
80
|
+
};
|
|
81
|
+
/**
|
|
82
|
+
* What `renderRejection` produced, plus the watermark the caller must persist.
|
|
83
|
+
*
|
|
84
|
+
* `message` is `''` EXACTLY WHEN nothing new needed saying. The caller treats
|
|
85
|
+
* that as "cold-start with the ordinary brief", never as "resume with an empty
|
|
86
|
+
* message" — a resume that says nothing spends a whole turn to communicate
|
|
87
|
+
* nothing.
|
|
88
|
+
*
|
|
89
|
+
* `deliveredReasonAt` is the largest `ReasonEntry.at` included in `message`, or
|
|
90
|
+
* `undefined` when `message` is empty. It becomes `SessionRecord.deliveredReasonAt`
|
|
91
|
+
* on the row written for the attempt this message opened.
|
|
92
|
+
*/
|
|
93
|
+
export interface RejectionDelta {
|
|
94
|
+
message: string;
|
|
95
|
+
deliveredReasonAt?: number;
|
|
96
|
+
/** How many reason entries the message actually carries. Lets a caller log or
|
|
97
|
+
* assert the delta size without re-parsing the rendered text. */
|
|
98
|
+
count: number;
|
|
99
|
+
}
|
|
100
|
+
/** Options for `renderRejection`. */
|
|
101
|
+
export interface RejectionSpec {
|
|
102
|
+
/** The re-offered packet. Only `owes` is read. */
|
|
103
|
+
packet: Pick<OrderPacket, 'owes'>;
|
|
104
|
+
/**
|
|
105
|
+
* The `at` of the newest reason ALREADY delivered into this session, from the
|
|
106
|
+
* last `SessionRecord` for this `(workflow, run, step)`. Absent means nothing
|
|
107
|
+
* has been delivered yet, so every reason is new — which is the correct read
|
|
108
|
+
* for a record written before Phase 4 added the field.
|
|
109
|
+
*/
|
|
110
|
+
deliveredReasonAt?: number;
|
|
111
|
+
/**
|
|
112
|
+
* Restrict rendering to these owed paths. Absent renders a section for EVERY
|
|
113
|
+
* owed path that has new reasons, which is what a re-offer owing several paths
|
|
114
|
+
* needs (one section per path, still delta-only, still one watermark).
|
|
115
|
+
*/
|
|
116
|
+
paths?: readonly string[];
|
|
117
|
+
}
|
|
118
|
+
/** Rough token budget for the cold-replay brief, per the Phase 4 plan. */
|
|
119
|
+
export declare const REPLAY_TOKEN_BUDGET = 100000;
|
|
120
|
+
/** chars/4 — the cheap, deliberately approximate token estimate. Nothing here
|
|
121
|
+
* needs a real tokenizer: the cap exists to avoid a pathological brief, not to
|
|
122
|
+
* hit a byte-exact ceiling. */
|
|
123
|
+
export declare function estimateTokens(text: string): number;
|
|
124
|
+
/**
|
|
125
|
+
* Render the REJECTION DELTA — the whole point of Phase 4.
|
|
126
|
+
*
|
|
127
|
+
* THE CENTRAL DESIGN POINT: this message is SHORT, and it deliberately does NOT
|
|
128
|
+
* contain the brief. The session being resumed already holds the original brief,
|
|
129
|
+
* the file reads, the tool results and the prior submission — that is the entire
|
|
130
|
+
* reason the worker resumes instead of restarting. Re-sending the brief would
|
|
131
|
+
* spend exactly the tokens this phase exists to save, and would leave the model
|
|
132
|
+
* with two copies of its instructions and no way to tell which is current.
|
|
133
|
+
*
|
|
134
|
+
* WHAT IT MAY NOT CONTAIN, and why each is named rather than left to judgement:
|
|
135
|
+
* - `brief` / `material.templateContent` / `packet.prompt` — see above.
|
|
136
|
+
* - `packet.consumes` and any submit hint — the resumed session already has them.
|
|
137
|
+
* - any credential material. `OrderPacket.owes` carries none, and this function
|
|
138
|
+
* reads nothing else, so the property holds by construction rather than by
|
|
139
|
+
* filtering. `test/agent-rejection.test.ts` asserts it anyway.
|
|
140
|
+
*
|
|
141
|
+
* REASON SELECTION, restated from `docs/agent-runner.md` (c): the reasons come
|
|
142
|
+
* from `OrderPacket.owes[].reasons`, filtered to `at > deliveredReasonAt` and, when
|
|
143
|
+
* `spec.paths` is given, to those owed paths. NEVER from `WorkOrder.feedback` —
|
|
144
|
+
* that is the flattened `whats_next` shape, it carries no `at`, and a shape with
|
|
145
|
+
* no timestamp cannot be diffed against a watermark.
|
|
146
|
+
*
|
|
147
|
+
* PURE: packet + watermark in, string out. No I/O, no clock, no harness.
|
|
148
|
+
*/
|
|
149
|
+
export declare function renderRejection(spec: RejectionSpec): RejectionDelta;
|
|
150
|
+
/**
|
|
151
|
+
* Assemble a COLD-REPLAY brief: the ordinary rendered brief plus the same
|
|
152
|
+
* rejection body as a trailing section.
|
|
153
|
+
*
|
|
154
|
+
* Used when resume is impossible (no prior session, a different harness, a dead
|
|
155
|
+
* session, a reaped cwd, a `replay`-tier adapter, or the provider rejecting the
|
|
156
|
+
* resume with `ResumeUnavailableError`). The session is gone, so the brief has to
|
|
157
|
+
* come back — but the reasons still have to arrive, or the fresh agent repeats
|
|
158
|
+
* the rejected submission verbatim.
|
|
159
|
+
*
|
|
160
|
+
* THE CAP. The assembled text is held to roughly `REPLAY_TOKEN_BUDGET` tokens by
|
|
161
|
+
* a chars/4 estimate. When it is over, WHOLE reason entries are dropped from the
|
|
162
|
+
* OLDEST end first and the message says how many were dropped. Never a mid-entry
|
|
163
|
+
* truncation: the kanna `handoff.ts` rule — never orphan a tool result from its
|
|
164
|
+
* call — generalizes here to "never emit half a structured item", because half a
|
|
165
|
+
* reason reads as a complete but different instruction.
|
|
166
|
+
*
|
|
167
|
+
* The BRIEF is never trimmed. If the brief alone exceeds the budget, the brief
|
|
168
|
+
* wins and the rejection section is reduced to as many of the NEWEST reasons as
|
|
169
|
+
* still fit, possibly none — losing the brief would leave the agent with no task
|
|
170
|
+
* at all, which is strictly worse than losing old reasons.
|
|
171
|
+
*/
|
|
172
|
+
export declare function renderReplayBrief(brief: string, spec: RejectionSpec): string;
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
/** The composite `<workflow>/<run>` order id token. */
|
|
2
|
+
export const ORDER_TOKEN = '__OWENLOOP_ORDER__';
|
|
3
|
+
/** The hub origin token. */
|
|
4
|
+
export const ORIGIN_TOKEN = '__OWENLOOP_ORIGIN__';
|
|
5
|
+
/** The Scoped Identity account token. */
|
|
6
|
+
export const ACCOUNT_TOKEN = '__OWENLOOP_ACCOUNT__';
|
|
7
|
+
/** The dispatching Shift's self-declared id token (advisory only). */
|
|
8
|
+
export const SHIFT_TOKEN = '__OWENLOOP_SHIFT__';
|
|
9
|
+
/** The composite order id — the only form the hub verbs accept. */
|
|
10
|
+
function composite(spec) {
|
|
11
|
+
return `${spec.workflow}/${spec.run}`;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Substitute the four dispatch tokens into a step template.
|
|
15
|
+
*
|
|
16
|
+
* `split(...).join(...)` rather than a regex replace, mirroring the legacy
|
|
17
|
+
* stamp exactly: it replaces every occurrence and treats the token as a literal
|
|
18
|
+
* (no accidental `$&` expansion from template text the author controls).
|
|
19
|
+
*/
|
|
20
|
+
export function renderBrief(templateContent, spec) {
|
|
21
|
+
return templateContent
|
|
22
|
+
.split(ORDER_TOKEN)
|
|
23
|
+
.join(composite(spec))
|
|
24
|
+
.split(ORIGIN_TOKEN)
|
|
25
|
+
.join(spec.origin)
|
|
26
|
+
.split(ACCOUNT_TOKEN)
|
|
27
|
+
.join(spec.account)
|
|
28
|
+
.split(SHIFT_TOKEN)
|
|
29
|
+
.join(spec.shiftId ?? '');
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* The born-bound work-holder mount handed to `HarnessAdapter.start` as
|
|
33
|
+
* `StartArgs.owenloopMcp`. The adapter mounts it verbatim and never builds it.
|
|
34
|
+
*
|
|
35
|
+
* `--shift=<cid>` is ONE argv element, not two. An absent cid then degrades
|
|
36
|
+
* to the single well-formed string `"--shift="` instead of a dangling flag
|
|
37
|
+
* with no value or a null array entry, which is what `hold`'s parser expects.
|
|
38
|
+
* (The shape originated with the deleted stamp path, which had to survive a YAML
|
|
39
|
+
* args array; it is kept because it is still the correct, unambiguous form.)
|
|
40
|
+
*/
|
|
41
|
+
export function buildOwenloopMcp(spec) {
|
|
42
|
+
return {
|
|
43
|
+
command: 'owenloop',
|
|
44
|
+
args: [
|
|
45
|
+
'work',
|
|
46
|
+
'hold',
|
|
47
|
+
'--order',
|
|
48
|
+
composite(spec),
|
|
49
|
+
'--origin',
|
|
50
|
+
spec.origin,
|
|
51
|
+
'--as',
|
|
52
|
+
spec.account,
|
|
53
|
+
`--shift=${spec.shiftId ?? ''}`,
|
|
54
|
+
'--mcp',
|
|
55
|
+
],
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
/** Rough token budget for the cold-replay brief, per the Phase 4 plan. */
|
|
59
|
+
export const REPLAY_TOKEN_BUDGET = 100_000;
|
|
60
|
+
/** chars/4 — the cheap, deliberately approximate token estimate. Nothing here
|
|
61
|
+
* needs a real tokenizer: the cap exists to avoid a pathological brief, not to
|
|
62
|
+
* hit a byte-exact ceiling. */
|
|
63
|
+
export function estimateTokens(text) {
|
|
64
|
+
return Math.ceil(text.length / 4);
|
|
65
|
+
}
|
|
66
|
+
/** One rendered reason line. `kind`/`by` are attribution the model needs to weigh
|
|
67
|
+
* a reason; `text` is the reason itself. */
|
|
68
|
+
function reasonLine(index, r) {
|
|
69
|
+
return `${index}. [${r.kind}, by ${r.by}] ${r.text}`;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Render the REJECTION DELTA — the whole point of Phase 4.
|
|
73
|
+
*
|
|
74
|
+
* THE CENTRAL DESIGN POINT: this message is SHORT, and it deliberately does NOT
|
|
75
|
+
* contain the brief. The session being resumed already holds the original brief,
|
|
76
|
+
* the file reads, the tool results and the prior submission — that is the entire
|
|
77
|
+
* reason the worker resumes instead of restarting. Re-sending the brief would
|
|
78
|
+
* spend exactly the tokens this phase exists to save, and would leave the model
|
|
79
|
+
* with two copies of its instructions and no way to tell which is current.
|
|
80
|
+
*
|
|
81
|
+
* WHAT IT MAY NOT CONTAIN, and why each is named rather than left to judgement:
|
|
82
|
+
* - `brief` / `material.templateContent` / `packet.prompt` — see above.
|
|
83
|
+
* - `packet.consumes` and any submit hint — the resumed session already has them.
|
|
84
|
+
* - any credential material. `OrderPacket.owes` carries none, and this function
|
|
85
|
+
* reads nothing else, so the property holds by construction rather than by
|
|
86
|
+
* filtering. `test/agent-rejection.test.ts` asserts it anyway.
|
|
87
|
+
*
|
|
88
|
+
* REASON SELECTION, restated from `docs/agent-runner.md` (c): the reasons come
|
|
89
|
+
* from `OrderPacket.owes[].reasons`, filtered to `at > deliveredReasonAt` and, when
|
|
90
|
+
* `spec.paths` is given, to those owed paths. NEVER from `WorkOrder.feedback` —
|
|
91
|
+
* that is the flattened `whats_next` shape, it carries no `at`, and a shape with
|
|
92
|
+
* no timestamp cannot be diffed against a watermark.
|
|
93
|
+
*
|
|
94
|
+
* PURE: packet + watermark in, string out. No I/O, no clock, no harness.
|
|
95
|
+
*/
|
|
96
|
+
export function renderRejection(spec) {
|
|
97
|
+
const since = spec.deliveredReasonAt;
|
|
98
|
+
const wanted = spec.paths === undefined ? undefined : new Set(spec.paths);
|
|
99
|
+
const sections = [];
|
|
100
|
+
let newest;
|
|
101
|
+
let count = 0;
|
|
102
|
+
for (const owed of spec.packet.owes) {
|
|
103
|
+
if (wanted !== undefined && !wanted.has(owed.path))
|
|
104
|
+
continue;
|
|
105
|
+
const fresh = owed.reasons.filter((r) => since === undefined || r.at > since);
|
|
106
|
+
// A schema reject with no text is a real shape: the owed entry exists, the
|
|
107
|
+
// reason thread is empty. Filtering to nothing here is what makes the caller
|
|
108
|
+
// cold-start rather than resume with a bare "you were rejected".
|
|
109
|
+
if (fresh.length === 0)
|
|
110
|
+
continue;
|
|
111
|
+
const lines = fresh.map((r, i) => reasonLine(i + 1, r));
|
|
112
|
+
sections.push(`Your submission for \`${owed.path}\` was rejected. Reasons:\n\n${lines.join('\n')}`);
|
|
113
|
+
count += fresh.length;
|
|
114
|
+
for (const r of fresh) {
|
|
115
|
+
if (newest === undefined || r.at > newest)
|
|
116
|
+
newest = r.at;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
if (sections.length === 0)
|
|
120
|
+
return { message: '', count: 0 };
|
|
121
|
+
const message = [
|
|
122
|
+
...sections,
|
|
123
|
+
'Revise and submit again to the same path with the same tool. Do not start over —\n' +
|
|
124
|
+
'keep everything you already have that was not called out above.',
|
|
125
|
+
].join('\n\n');
|
|
126
|
+
return { message, count, ...(newest !== undefined ? { deliveredReasonAt: newest } : {}) };
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Assemble a COLD-REPLAY brief: the ordinary rendered brief plus the same
|
|
130
|
+
* rejection body as a trailing section.
|
|
131
|
+
*
|
|
132
|
+
* Used when resume is impossible (no prior session, a different harness, a dead
|
|
133
|
+
* session, a reaped cwd, a `replay`-tier adapter, or the provider rejecting the
|
|
134
|
+
* resume with `ResumeUnavailableError`). The session is gone, so the brief has to
|
|
135
|
+
* come back — but the reasons still have to arrive, or the fresh agent repeats
|
|
136
|
+
* the rejected submission verbatim.
|
|
137
|
+
*
|
|
138
|
+
* THE CAP. The assembled text is held to roughly `REPLAY_TOKEN_BUDGET` tokens by
|
|
139
|
+
* a chars/4 estimate. When it is over, WHOLE reason entries are dropped from the
|
|
140
|
+
* OLDEST end first and the message says how many were dropped. Never a mid-entry
|
|
141
|
+
* truncation: the kanna `handoff.ts` rule — never orphan a tool result from its
|
|
142
|
+
* call — generalizes here to "never emit half a structured item", because half a
|
|
143
|
+
* reason reads as a complete but different instruction.
|
|
144
|
+
*
|
|
145
|
+
* The BRIEF is never trimmed. If the brief alone exceeds the budget, the brief
|
|
146
|
+
* wins and the rejection section is reduced to as many of the NEWEST reasons as
|
|
147
|
+
* still fit, possibly none — losing the brief would leave the agent with no task
|
|
148
|
+
* at all, which is strictly worse than losing old reasons.
|
|
149
|
+
*/
|
|
150
|
+
export function renderReplayBrief(brief, spec) {
|
|
151
|
+
const full = renderRejection(spec);
|
|
152
|
+
if (full.message === '')
|
|
153
|
+
return brief;
|
|
154
|
+
const join = (body, dropped) => {
|
|
155
|
+
const note = dropped > 0
|
|
156
|
+
? `\n\n(${dropped} older rejection reason${dropped === 1 ? '' : 's'} omitted to fit the context budget.)`
|
|
157
|
+
: '';
|
|
158
|
+
return `${brief}\n\n---\n\n${body}${note}`;
|
|
159
|
+
};
|
|
160
|
+
let assembled = join(full.message, 0);
|
|
161
|
+
if (estimateTokens(assembled) <= REPLAY_TOKEN_BUDGET)
|
|
162
|
+
return assembled;
|
|
163
|
+
// Over budget: re-render with progressively fewer reasons, oldest dropped
|
|
164
|
+
// first. `ordered` is every candidate entry in ascending `at`, so slicing off
|
|
165
|
+
// the FRONT drops the oldest and keeps whole entries.
|
|
166
|
+
const since = spec.deliveredReasonAt;
|
|
167
|
+
const wanted = spec.paths === undefined ? undefined : new Set(spec.paths);
|
|
168
|
+
const ordered = spec.packet.owes
|
|
169
|
+
.filter((o) => wanted === undefined || wanted.has(o.path))
|
|
170
|
+
.flatMap((o) => o.reasons)
|
|
171
|
+
.filter((r) => since === undefined || r.at > since)
|
|
172
|
+
.sort((a, b) => a.at - b.at);
|
|
173
|
+
for (let drop = 1; drop <= ordered.length; drop += 1) {
|
|
174
|
+
const keep = new Set(ordered.slice(drop));
|
|
175
|
+
const trimmed = renderRejection({
|
|
176
|
+
...spec,
|
|
177
|
+
packet: {
|
|
178
|
+
owes: spec.packet.owes.map((o) => ({ ...o, reasons: o.reasons.filter((r) => keep.has(r)) })),
|
|
179
|
+
},
|
|
180
|
+
// The watermark filter already ran; re-applying it is harmless but the
|
|
181
|
+
// `keep` set is now the authority on which entries survive.
|
|
182
|
+
...(since !== undefined ? { deliveredReasonAt: since } : {}),
|
|
183
|
+
});
|
|
184
|
+
if (trimmed.message === '')
|
|
185
|
+
break;
|
|
186
|
+
assembled = join(trimmed.message, drop);
|
|
187
|
+
if (estimateTokens(assembled) <= REPLAY_TOKEN_BUDGET)
|
|
188
|
+
return assembled;
|
|
189
|
+
}
|
|
190
|
+
// Everything was dropped and it still does not fit — the brief alone is over
|
|
191
|
+
// budget. Return the brief: an agent with a task and no reasons can still work.
|
|
192
|
+
return brief;
|
|
193
|
+
}
|