owenloop 0.5.4 → 0.5.6
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 +16 -0
- package/dist/packages/work/src/agent/brief.d.ts +28 -4
- package/dist/packages/work/src/agent/brief.js +170 -2
- package/dist/packages/work/src/agent/loop.d.ts +10 -1
- package/dist/packages/work/src/agent/loop.js +60 -3
- package/dist/packages/work/src/agent/workdir.d.ts +22 -0
- package/dist/packages/work/src/agent/workdir.js +80 -0
- package/dist/packages/work/src/exec/loop.d.ts +13 -1
- package/dist/packages/work/src/exec/loop.js +31 -0
- package/dist/packages/work/src/harness/claude.d.ts +24 -0
- package/dist/packages/work/src/harness/claude.js +131 -23
- package/dist/packages/work/src/harness/contract.d.ts +25 -20
- package/dist/packages/work/src/harness/contract.js +25 -20
- package/dist/packages/work/src/harness/gatekeeper.d.ts +124 -0
- package/dist/packages/work/src/harness/gatekeeper.js +208 -0
- package/dist/packages/work/src/hold/mcp.d.ts +11 -2
- package/dist/packages/work/src/hold/mcp.js +69 -2
- package/dist/packages/work/src/hub/client.d.ts +8 -1
- package/dist/packages/work/src/hub/client.js +1 -0
- package/dist/packages/work/src/hub/types.d.ts +29 -0
- package/dist/packages/work/src/roles/agent-run.js +9 -1
- package/dist/packages/work/src/roles/exec.js +9 -0
- package/dist/packages/work/src/roles/shift.js +9 -1
- package/dist/packages/work/src/settings/settings.d.ts +20 -1
- package/dist/packages/work/src/settings/settings.js +23 -1
- package/dist/packages/work/src/shift/runtime.d.ts +7 -0
- package/dist/packages/work/src/shift/runtime.js +29 -4
- package/dist/packages/work/src/shift/spawn.d.ts +12 -2
- package/dist/packages/work/src/shift/spawn.js +16 -3
- package/dist/src/cli.js +54 -1
- package/dist/src/engine.d.ts +46 -1
- package/dist/src/engine.js +72 -0
- package/dist/src/index.d.ts +1 -1
- package/dist/src/index.js +1 -1
- package/dist/src/model.d.ts +29 -5
- package/dist/src/model.js +63 -14
- package/dist/src/types.d.ts +8 -2
- package/docs/agent-runner.md +17 -5
- package/docs/cli.md +34 -0
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,22 @@ 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.6](https://github.com/typicalday/owenloop/compare/v0.5.5...v0.5.6) (2026-08-15)
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* gate tool calls so ask actually asks and auto-safe actually classifies ([#171](https://github.com/typicalday/owenloop/issues/171)) ([f1e95f5](https://github.com/typicalday/owenloop/commit/f1e95f5990f73399c5542cf2d103e16761792a64))
|
|
13
|
+
* tell every step agent where its inputs are and how much rope is left ([#169](https://github.com/typicalday/owenloop/issues/169)) ([47d0485](https://github.com/typicalday/owenloop/commit/47d0485f44ac893c9d2870f7afe31b8a4c42ca92))
|
|
14
|
+
|
|
15
|
+
## [0.5.5](https://github.com/typicalday/owenloop/compare/v0.5.4...v0.5.5) (2026-08-15)
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
### Features
|
|
19
|
+
|
|
20
|
+
* give every step agent a channel to ask a human ([#168](https://github.com/typicalday/owenloop/issues/168)) ([fa9e5f0](https://github.com/typicalday/owenloop/commit/fa9e5f08d3a9f55c6e95cc504966a6389ec699c4))
|
|
21
|
+
* let a shift operator declare where work may happen ([#166](https://github.com/typicalday/owenloop/issues/166)) ([71e9412](https://github.com/typicalday/owenloop/commit/71e9412c534ba826490dc62464989b47a6f551fe))
|
|
22
|
+
|
|
7
23
|
## [0.5.4](https://github.com/typicalday/owenloop/compare/v0.5.3...v0.5.4) (2026-08-15)
|
|
8
24
|
|
|
9
25
|
|
|
@@ -70,11 +70,35 @@ export interface BriefSpec {
|
|
|
70
70
|
*/
|
|
71
71
|
escalated?: boolean;
|
|
72
72
|
/**
|
|
73
|
-
* The owed
|
|
74
|
-
*
|
|
75
|
-
*
|
|
73
|
+
* The owed outputs for this order, in packet order. Feeds the submit contract
|
|
74
|
+
* (which names every path) and the attempt history (which reads the two reject
|
|
75
|
+
* counters); absent or empty renders neither.
|
|
76
|
+
*
|
|
77
|
+
* The caller is responsible for the FALLBACK: `packet.owes` is the hub's live
|
|
78
|
+
* answer to "what does this order still owe" and is the right source, but a
|
|
79
|
+
* hub old enough to project no `owes` array at all leaves it empty while
|
|
80
|
+
* `packet.outputs` still names the same paths. See `agent/loop.ts` — an empty
|
|
81
|
+
* list here silently deletes both contracts, which is the exact failure they
|
|
82
|
+
* were written to close.
|
|
76
83
|
*/
|
|
77
|
-
owes?: readonly
|
|
84
|
+
owes?: readonly OwedBrief[];
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* One owed output as the brief sees it: the path, plus how many times a prior
|
|
88
|
+
* submission to it was knocked back.
|
|
89
|
+
*
|
|
90
|
+
* Both counters are optional because a hub that does not project them is not a
|
|
91
|
+
* hub reporting zero — it is a hub with nothing to say, and the attempt history
|
|
92
|
+
* stays silent rather than telling an agent on its fourth attempt that this is
|
|
93
|
+
* its first.
|
|
94
|
+
*/
|
|
95
|
+
export interface OwedBrief {
|
|
96
|
+
path: string;
|
|
97
|
+
/** Consumer/judge verdicts against a submitted value (`packet.owes[].judgmentRejects`). */
|
|
98
|
+
judgmentRejects?: number;
|
|
99
|
+
/** Engine refusals of a malformed value against the path's declared JSON
|
|
100
|
+
* Schema (`packet.owes[].schemaRejects`). */
|
|
101
|
+
schemaRejects?: number;
|
|
78
102
|
}
|
|
79
103
|
/**
|
|
80
104
|
* Substitute the four dispatch tokens into a step template.
|
|
@@ -11,6 +11,12 @@ export const SHIFT_TOKEN = '__OWENLOOP_SHIFT__';
|
|
|
11
11
|
function composite(spec) {
|
|
12
12
|
return `${spec.workflow}/${spec.run}`;
|
|
13
13
|
}
|
|
14
|
+
/** The owed paths worth naming: every non-empty `path`, in packet order. An
|
|
15
|
+
* empty string is not a path a `submit` or `ask` call could be made against, so
|
|
16
|
+
* it is dropped here once rather than guarded at each use. */
|
|
17
|
+
function owedPaths(spec) {
|
|
18
|
+
return (spec.owes ?? []).map((o) => o.path).filter((p) => p !== '');
|
|
19
|
+
}
|
|
14
20
|
/**
|
|
15
21
|
* Substitute the four dispatch tokens into a step template.
|
|
16
22
|
*
|
|
@@ -28,9 +34,120 @@ export function renderBrief(templateContent, spec) {
|
|
|
28
34
|
.join(spec.account)
|
|
29
35
|
.split(SHIFT_TOKEN)
|
|
30
36
|
.join(spec.shiftId ?? '');
|
|
31
|
-
const blocks = [
|
|
37
|
+
const blocks = [
|
|
38
|
+
renderRoutingLine(spec),
|
|
39
|
+
renderInputContract(spec),
|
|
40
|
+
renderSubmitContract(spec),
|
|
41
|
+
renderAttemptHistory(spec),
|
|
42
|
+
renderEscalationContract(spec),
|
|
43
|
+
substituted,
|
|
44
|
+
];
|
|
32
45
|
return blocks.filter((b) => b !== '').join('\n\n');
|
|
33
46
|
}
|
|
47
|
+
/**
|
|
48
|
+
* Where this order's INPUTS are, stated to every agent on every run.
|
|
49
|
+
*
|
|
50
|
+
* WHY THIS EXISTS. The brief and the mounted work-holder are two halves of one
|
|
51
|
+
* order and nothing ever joined them. The brief is a rendered template; the
|
|
52
|
+
* order's actual data — the resolved `consumes` map, the owed paths, each path's
|
|
53
|
+
* reason thread — lives on the hub behind `get_order`, a tool the agent is
|
|
54
|
+
* mounted with and was never told about. So an agent whose template says "review
|
|
55
|
+
* the plan" has no stated way to obtain the plan, and the two things it does
|
|
56
|
+
* instead are both silent: it looks in its working directory and finds nothing,
|
|
57
|
+
* or it writes what a plan would plausibly say. Observed live: a planner whose
|
|
58
|
+
* working directory was empty produced a confident, fully-fabricated plan, and a
|
|
59
|
+
* builder began executing it. The working-directory half of that run was a
|
|
60
|
+
* separate defect and is fixed; this half is not, and it is the half that turns
|
|
61
|
+
* "I have no inputs" into fiction rather than into a question.
|
|
62
|
+
*
|
|
63
|
+
* WHEN IT RENDERS. On the same condition as the submit and escalation contracts
|
|
64
|
+
* — the order owes at least one named path — even though `get_order` itself
|
|
65
|
+
* takes no arguments and could always be stated. Two reasons, both concrete:
|
|
66
|
+
* this block's closing sentence sends the agent to `ask`, and `ask` is only
|
|
67
|
+
* described when there is an owed path for it to name, so an unconditional
|
|
68
|
+
* version would point at a section that is not there; and an order owing nothing
|
|
69
|
+
* has no work to orient for. The tool it names is always mounted — every agent
|
|
70
|
+
* order gets the full work-holder surface, because `buildOwenloopMcp` passes no
|
|
71
|
+
* tool selector.
|
|
72
|
+
*
|
|
73
|
+
* WHY IT RANKS `get_order` ABOVE THE BRIEF. The brief is rendered once at
|
|
74
|
+
* dispatch and is a summary; the packet is live and authoritative, and on a
|
|
75
|
+
* re-offer it carries reason threads this text cannot. Telling the agent which
|
|
76
|
+
* of the two wins removes the judgement call.
|
|
77
|
+
*
|
|
78
|
+
* WHY THE LAST LINE POINTS AT `ask`. Naming the source of inputs without saying
|
|
79
|
+
* what to do when an input is missing from it just relocates the guess.
|
|
80
|
+
*
|
|
81
|
+
* Vendor-neutral by construction: names owenloop's own tool and mount, no
|
|
82
|
+
* harness. `test/vendor-gate.test.ts` enforces this.
|
|
83
|
+
*/
|
|
84
|
+
function renderInputContract(spec) {
|
|
85
|
+
if (owedPaths(spec).length === 0)
|
|
86
|
+
return '';
|
|
87
|
+
return [
|
|
88
|
+
'Before you start: call the `get_order` tool on the mounted `owenloop` MCP server. It takes no arguments and returns THIS order in full — the inputs you were given (`consumes`), the exact output paths you owe, and each path\'s reason thread, including why any previous attempt was rejected.',
|
|
89
|
+
'That packet is authoritative. This brief is a summary of it, rendered once when the order was dispatched; where the two disagree, the packet is right.',
|
|
90
|
+
'If something you need is not in what `get_order` returns and you cannot recover it by working — reading the repository, re-reading your inputs, running a read-only command — then it was not given to you. Do not invent it and do not proceed on an assumption: use `ask` (below).',
|
|
91
|
+
].join('\n');
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* How much rope is left, stated only when some has already been used.
|
|
95
|
+
*
|
|
96
|
+
* WHY THIS EXISTS, GIVEN THE REJECTION DELTA ALREADY SHIPS. `renderRejection` /
|
|
97
|
+
* `renderReplayBrief` tell a re-offered agent WHAT was wrong with its last
|
|
98
|
+
* submission. Neither tells it that the retrying is BOUNDED. Those are different
|
|
99
|
+
* facts and they drive different behaviour: the reasons make an agent revise,
|
|
100
|
+
* and revising is right up until the point where the blocker is not something
|
|
101
|
+
* revision can fix — at which point the agent needs to know that grinding out
|
|
102
|
+
* one more attempt is not free. Without a count, every attempt looks like the
|
|
103
|
+
* first one, so an agent has no reason to ever switch from retrying to asking,
|
|
104
|
+
* and the step burns its whole budget rediscovering the same blocker. The
|
|
105
|
+
* counter is the input to that decision and the packet has carried it all along.
|
|
106
|
+
*
|
|
107
|
+
* WHY IT DOES NOT NAME THE CAP. The cap is `maxAttempts` / `maxSchemaFailures`,
|
|
108
|
+
* resolved per-produce from the def (`model.ts`'s `effectiveMaxAttempts`), and
|
|
109
|
+
* the order packet does not carry it. Rendering a guessed number would be worse
|
|
110
|
+
* than rendering none: an agent told it has "2 of 5" left when it has 2 of 3
|
|
111
|
+
* will keep grinding. So this states the counts, which are true, and states that
|
|
112
|
+
* the budget is finite, which is also true, and states neither more precisely
|
|
113
|
+
* than the packet allows.
|
|
114
|
+
*
|
|
115
|
+
* WHY IT SEPARATES THE TWO COUNTERS. They mean opposite things to the agent. A
|
|
116
|
+
* judgment reject is a reader disagreeing with the CONTENT of a value that was
|
|
117
|
+
* otherwise well-formed. A schema reject is the engine refusing the SHAPE before
|
|
118
|
+
* anybody read it — rewriting the content again cannot help, and the fix is the
|
|
119
|
+
* structure of what was submitted. Reporting them as one number would send an
|
|
120
|
+
* agent to revise prose that was never read.
|
|
121
|
+
*
|
|
122
|
+
* Silent when every counter is zero or absent: a first attempt has no history,
|
|
123
|
+
* and "0 previous rejections" is a sentence that costs tokens to say nothing.
|
|
124
|
+
*/
|
|
125
|
+
function renderAttemptHistory(spec) {
|
|
126
|
+
const lines = [];
|
|
127
|
+
for (const owed of spec.owes ?? []) {
|
|
128
|
+
if (owed.path === '')
|
|
129
|
+
continue;
|
|
130
|
+
const judgment = owed.judgmentRejects ?? 0;
|
|
131
|
+
const schema = owed.schemaRejects ?? 0;
|
|
132
|
+
if (judgment === 0 && schema === 0)
|
|
133
|
+
continue;
|
|
134
|
+
const parts = [];
|
|
135
|
+
if (judgment > 0) {
|
|
136
|
+
parts.push(`${judgment} rejected on judgment (a reader disagreed with the value — see its reason thread via \`get_order\`)`);
|
|
137
|
+
}
|
|
138
|
+
if (schema > 0) {
|
|
139
|
+
parts.push(`${schema} rejected on schema (the value did not match the declared shape — the fix is the STRUCTURE of what you submit, not its wording)`);
|
|
140
|
+
}
|
|
141
|
+
lines.push(`- \`${owed.path}\`: ${parts.join('; ')}.`);
|
|
142
|
+
}
|
|
143
|
+
if (lines.length === 0)
|
|
144
|
+
return '';
|
|
145
|
+
return [
|
|
146
|
+
'Attempt history for this order — previous submissions that were knocked back:',
|
|
147
|
+
...lines,
|
|
148
|
+
'This retrying is bounded. After enough rejections on a path the engine stops re-arming this step entirely and it sits until a person intervenes, so a further attempt that repeats the last one costs a real attempt and gains nothing. If you now believe the blocker is something another attempt cannot fix, `ask` instead of resubmitting.',
|
|
149
|
+
].join('\n');
|
|
150
|
+
}
|
|
34
151
|
/**
|
|
35
152
|
* How an order is COMPLETED, stated to every agent on every run.
|
|
36
153
|
*
|
|
@@ -62,7 +179,7 @@ export function renderBrief(templateContent, spec) {
|
|
|
62
179
|
* `src/harness/` that names a vendor.
|
|
63
180
|
*/
|
|
64
181
|
function renderSubmitContract(spec) {
|
|
65
|
-
const owed = (spec
|
|
182
|
+
const owed = owedPaths(spec);
|
|
66
183
|
// Nothing owed, nothing to say — the same stance the routing line takes on an
|
|
67
184
|
// absent modifier. A contract with no path to name would have to write
|
|
68
185
|
// `<path>` into its own example, which teaches the shape of the call while
|
|
@@ -75,6 +192,57 @@ function renderSubmitContract(spec) {
|
|
|
75
192
|
'Printing that value as text, or inside a code fence, does NOT submit it — the turn ends, the hub records nothing, and this order is re-offered from scratch. Wherever this brief says "green <path> with <value>", it means exactly this tool call.',
|
|
76
193
|
].join('\n');
|
|
77
194
|
}
|
|
195
|
+
/**
|
|
196
|
+
* What an agent does when it CANNOT complete the order, stated to every agent on
|
|
197
|
+
* every run, right after the submit contract.
|
|
198
|
+
*
|
|
199
|
+
* WHY THIS EXISTS. The submit contract closes one hole (an agent that finished
|
|
200
|
+
* but did not know how to say so). This closes the opposite one: an agent that
|
|
201
|
+
* did NOT finish and has no legal way to say so. Until `ask` shipped there were
|
|
202
|
+
* exactly two exits from a step, and a blocked agent had to pick the less
|
|
203
|
+
* damaging:
|
|
204
|
+
* - Submit anyway. The artifact goes green on a value the agent does not
|
|
205
|
+
* believe, and every downstream step builds on it. Observed on a real run:
|
|
206
|
+
* a planner that could read nothing produced a confident, fictional plan and
|
|
207
|
+
* a builder started executing it.
|
|
208
|
+
* - End the turn without submitting. The lease lapses, the task re-arms, and a
|
|
209
|
+
* fresh worker starts from the identical missing information. It repeats
|
|
210
|
+
* until the stall cap, spending a full model run per attempt to relearn the
|
|
211
|
+
* same blocker, and no human is ever told.
|
|
212
|
+
* Neither reaches a person. Both were watched happening. The tool is the fix and
|
|
213
|
+
* this paragraph is what makes the tool reachable — a mounted tool nobody is
|
|
214
|
+
* told about is dead code.
|
|
215
|
+
*
|
|
216
|
+
* WHY IT NAMES THE COST. Models are heavily biased toward producing an answer,
|
|
217
|
+
* and an escalation path that reads as failure will not be taken. So the text
|
|
218
|
+
* states the two facts that make asking the correct move rather than the
|
|
219
|
+
* cowardly one: it costs no attempts, and guessing is worse than asking.
|
|
220
|
+
*
|
|
221
|
+
* WHY IT STATES THE BAR. "Ask whenever unsure" would turn every ambiguity into a
|
|
222
|
+
* human interrupt and the channel would be ignored within a day. The bar is
|
|
223
|
+
* concrete: ask when the missing thing cannot be recovered by working — reading
|
|
224
|
+
* the repo, running a read-only command, re-reading the inputs — because those
|
|
225
|
+
* are exactly the cases where another attempt cannot help.
|
|
226
|
+
*
|
|
227
|
+
* Rendered only when the order owes something, for the same reason the submit
|
|
228
|
+
* contract is: `ask` takes an owed path as its argument, and a contract that has
|
|
229
|
+
* to write `<path>` into its own example teaches the call shape while leaving
|
|
230
|
+
* the one argument that matters unanswered.
|
|
231
|
+
*
|
|
232
|
+
* Vendor-neutral by construction — names owenloop's own tool and mount only.
|
|
233
|
+
*/
|
|
234
|
+
function renderEscalationContract(spec) {
|
|
235
|
+
const owed = owedPaths(spec);
|
|
236
|
+
if (owed.length === 0)
|
|
237
|
+
return '';
|
|
238
|
+
return [
|
|
239
|
+
`If you CANNOT produce what this order asks for, do not guess and do not end your turn silently — call the \`ask\` tool on the same \`owenloop\` MCP server and stop.`,
|
|
240
|
+
`Example: \`ask({"path": "${owed[0]}", "question": "<the specific decision or fact you need from a person>", "context": "<what you already tried>"})\`.`,
|
|
241
|
+
'Ask when the thing you are missing cannot be recovered by working: a required input is absent, wrong, or contradicts another input; the order asks for a judgment only the operator can make; or you cannot reach something the order depends on. Do NOT ask for anything you could resolve by reading the repository, re-reading your inputs, or running a read-only command — do that first.',
|
|
242
|
+
'Asking costs you nothing: it is not a failed attempt, it consumes none of this step\'s retry budget, and it is the correct outcome when the honest answer is "I do not know". Submitting a value you do not believe is worse than asking — it goes green and every later step builds on it. Ending your turn without submitting is worse than asking — this step simply re-runs with the same information missing, and no person is ever told.',
|
|
243
|
+
'After you ask, your run is over. A human answers on the same artifact and a fresh attempt starts with their answer attached.',
|
|
244
|
+
].join('\n');
|
|
245
|
+
}
|
|
78
246
|
/**
|
|
79
247
|
* The run's depth, stated to the agent in one line, PREPENDED rather than
|
|
80
248
|
* substituted into a token.
|
|
@@ -6,7 +6,7 @@ import type { HarnessAdapter } from '../harness/contract.ts';
|
|
|
6
6
|
import { type SessionRecord } from '../harness/session-store.ts';
|
|
7
7
|
import { type CapabilityModelMap, type CapabilityResolution } from './capability-model.ts';
|
|
8
8
|
/** Discriminated result of one worker life; the role maps these to exit codes. */
|
|
9
|
-
export type AgentRunOutcome = 'submitted' | 'completed' | 'misroute' | 'no-template' | 'no-harness' | 'incompatible-harness-policy' | 'unresolvable-capability' | 'unverified-consumed' | 'session-store-failed' | 'no-submit' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'stopped';
|
|
9
|
+
export type AgentRunOutcome = 'submitted' | 'completed' | 'misroute' | 'workdir-denied' | 'no-template' | 'no-harness' | 'incompatible-harness-policy' | 'unresolvable-capability' | 'unverified-consumed' | 'session-store-failed' | 'no-submit' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'stopped';
|
|
10
10
|
/**
|
|
11
11
|
* Locate the normalized step spec for an order. Injected because the lookup is
|
|
12
12
|
* I/O (the verified workflow store) and because resolving the local definition
|
|
@@ -52,6 +52,15 @@ export interface AgentRunLoopOptions {
|
|
|
52
52
|
shiftId?: string;
|
|
53
53
|
/** cwd for the step agent when the order packet carries no `workdir`. */
|
|
54
54
|
cwd: string;
|
|
55
|
+
/**
|
|
56
|
+
* The directories this MACHINE's operator declared as places work may happen,
|
|
57
|
+
* already resolved to absolute paths by `resolveAllowedWorkdirRoots`.
|
|
58
|
+
*
|
|
59
|
+
* NOT `workRoot`. `workRoot` is the single directory owenloop CREATES worktrees
|
|
60
|
+
* under; this is the set of directories an ORDER is permitted to name as its
|
|
61
|
+
* cwd. UNSET or EMPTY means NO RESTRICTION.
|
|
62
|
+
*/
|
|
63
|
+
allowedWorkdirRoots?: string[];
|
|
55
64
|
loadStep: StepLoader;
|
|
56
65
|
resolveAdapter: AdapterResolver;
|
|
57
66
|
/**
|
|
@@ -57,6 +57,7 @@
|
|
|
57
57
|
* back would waste a whole re-offer cycle to learn something already known.
|
|
58
58
|
*/
|
|
59
59
|
import { existsSync } from 'node:fs';
|
|
60
|
+
import { isWorkdirAllowed } from "./workdir.js";
|
|
60
61
|
import { createLeaseLoop } from "../lease/loop.js";
|
|
61
62
|
import { isResumeUnavailable } from "../harness/contract.js";
|
|
62
63
|
import { preflightStepPermissions } from "../harness/permissions.js";
|
|
@@ -70,6 +71,40 @@ export const DEFAULT_SUBMIT_GRACE_MS = 15_000;
|
|
|
70
71
|
function errMsg(e) {
|
|
71
72
|
return e instanceof Error ? e.message : String(e);
|
|
72
73
|
}
|
|
74
|
+
/**
|
|
75
|
+
* The owed outputs the brief renders its submit contract, attempt history and
|
|
76
|
+
* escalation contract from.
|
|
77
|
+
*
|
|
78
|
+
* `packet.owes` is the RIGHT source and is used whenever it has anything in it:
|
|
79
|
+
* it is the hub's live answer to "what does this order still owe", so on a
|
|
80
|
+
* re-offer where some paths are already paid it names only the ones left, and it
|
|
81
|
+
* is the only source carrying the reject counters.
|
|
82
|
+
*
|
|
83
|
+
* THE FALLBACK, and why it is not defensive noise. `owes` reaching this function
|
|
84
|
+
* empty is a real, reachable state, not a can't-happen: the hub's order
|
|
85
|
+
* projection (`projectReferenceOrder`) is a deliberate allow-list that emits
|
|
86
|
+
* `owes: []` for any persisted row whose `owes` is not an array — every order
|
|
87
|
+
* written before the engine emitted the field. `packet.outputs` is projected
|
|
88
|
+
* from the same row and names the same paths, minus the counters. Preferring an
|
|
89
|
+
* empty `owes` over a populated `outputs` would render a brief with NO submit
|
|
90
|
+
* contract and NO escalation contract — silently reproducing, on exactly the old
|
|
91
|
+
* runs least able to cope with it, the defect both contracts exist to close. So:
|
|
92
|
+
* fall back to the paths, and let the attempt history stay silent because there
|
|
93
|
+
* are genuinely no counters to report.
|
|
94
|
+
*
|
|
95
|
+
* An order that owes nothing under BOTH fields renders neither contract, which
|
|
96
|
+
* is correct — there is no path for `submit` or `ask` to name.
|
|
97
|
+
*/
|
|
98
|
+
function briefOwes(packet) {
|
|
99
|
+
if (packet.owes.length > 0) {
|
|
100
|
+
return packet.owes.map((owed) => ({
|
|
101
|
+
path: owed.path,
|
|
102
|
+
judgmentRejects: owed.judgmentRejects,
|
|
103
|
+
schemaRejects: owed.schemaRejects,
|
|
104
|
+
}));
|
|
105
|
+
}
|
|
106
|
+
return packet.outputs.map((path) => ({ path }));
|
|
107
|
+
}
|
|
73
108
|
/**
|
|
74
109
|
* Resolve an order's composed capabilities against this machine's map.
|
|
75
110
|
*
|
|
@@ -363,6 +398,30 @@ export function createAgentRunLoop(opts) {
|
|
|
363
398
|
}
|
|
364
399
|
stepName = packet.step;
|
|
365
400
|
recordCwd = packet.workdir ?? opts.cwd;
|
|
401
|
+
// MACHINE POLICY. The operator who started this shift named the directories
|
|
402
|
+
// work may happen in (`owenloop shift start --work-root`, or
|
|
403
|
+
// `allowedWorkdirRoots` in settings). This worker is one of only two
|
|
404
|
+
// processes that ever sees `OrderPacket.workdir` — the shift's `whats_next`
|
|
405
|
+
// sweep receives a `WorkOrder`, which carries no such field — so the check
|
|
406
|
+
// belongs here and cannot be hoisted into dispatch.
|
|
407
|
+
//
|
|
408
|
+
// RELEASED, not failed, and BEFORE the step spec is loaded or any provider
|
|
409
|
+
// session is opened. Declining work this machine was not configured to host
|
|
410
|
+
// is not a failure of the work: the targeted release returns the order to
|
|
411
|
+
// the hub's pickup window, where a differently-configured machine can take
|
|
412
|
+
// it. `misroute` takes the same shape for the same reason.
|
|
413
|
+
//
|
|
414
|
+
// ONLY an order-NAMED workdir is checked. When the packet names none this
|
|
415
|
+
// worker uses `<workRoot>/<workflow>/<run>/` — a directory owenloop ITSELF
|
|
416
|
+
// created under the operator's own cache root — and denying that would deny
|
|
417
|
+
// every agent order on a machine that declared any root at all.
|
|
418
|
+
if (packet.workdir !== undefined &&
|
|
419
|
+
!isWorkdirAllowed(packet.workdir, opts.allowedWorkdirRoots ?? [])) {
|
|
420
|
+
const roots = (opts.allowedWorkdirRoots ?? []).join(', ');
|
|
421
|
+
opts.err(`owenloop work agent-run: step '${packet.step}' (${order}) names workdir '${packet.workdir}', ` +
|
|
422
|
+
`which is outside every work root this machine declared (${roots}) — releasing for the pickup window`);
|
|
423
|
+
return releaseWith('workdir-denied', 'workdir-denied');
|
|
424
|
+
}
|
|
366
425
|
// The step spec. No bundle / no spec ⇒ we cannot brief anybody; release so
|
|
367
426
|
// the order lapses back through the hub's pickup window.
|
|
368
427
|
let material;
|
|
@@ -402,9 +461,7 @@ export function createAgentRunLoop(opts) {
|
|
|
402
461
|
// statement about the RUN, and a shift has no say in it.
|
|
403
462
|
...(packet.modifier !== undefined ? { modifier: packet.modifier } : {}),
|
|
404
463
|
...(packet.escalated === true ? { escalated: true } : {}),
|
|
405
|
-
|
|
406
|
-
// contract names the right paths on a re-offer where some are already paid.
|
|
407
|
-
owes: packet.owes.map((owed) => owed.path),
|
|
464
|
+
owes: briefOwes(packet),
|
|
408
465
|
};
|
|
409
466
|
// Permissions arrive PRE-NORMALIZED in the spec. `prepare` ran
|
|
410
467
|
// `normalizeStepPermissions` over the step's `x.harness` options at cache
|
|
@@ -22,6 +22,28 @@ export declare function resolveWorkRepo(env: Record<string, string | undefined>,
|
|
|
22
22
|
* run's directory and must never be removed.
|
|
23
23
|
*/
|
|
24
24
|
export declare function isUnderWorkRoot(dir: string, workRoot: string): boolean;
|
|
25
|
+
/**
|
|
26
|
+
* Resolve the declared roots: `OWENLOOP_ALLOWED_WORKDIR_ROOTS` >
|
|
27
|
+
* `settings.allowedWorkdirRoots` > none. Mirrors `resolveWorkRoot`'s precedence
|
|
28
|
+
* shape, so there is one rule to remember across this file.
|
|
29
|
+
*
|
|
30
|
+
* The env var is PATH-style `:`-separated because it names a list of
|
|
31
|
+
* directories and that is the convention every operator already knows for one.
|
|
32
|
+
* It REPLACES the settings list rather than adding to it — a narrowing override
|
|
33
|
+
* that could only ever widen would not be a usable safety control.
|
|
34
|
+
*
|
|
35
|
+
* Every entry is resolved to an absolute path against `cwd`, so a relative
|
|
36
|
+
* declaration means what the operator saw when they typed it.
|
|
37
|
+
*/
|
|
38
|
+
export declare function resolveAllowedWorkdirRoots(env: Record<string, string | undefined>, settingsRoots: string[] | undefined, cwd: string): string[];
|
|
39
|
+
/**
|
|
40
|
+
* Is `workdir` inside (or equal to) one of `roots`?
|
|
41
|
+
*
|
|
42
|
+
* An EMPTY `roots` returns true for every path — that is the unrestricted
|
|
43
|
+
* default, not an accident, and it is why callers can pass the resolved list
|
|
44
|
+
* unconditionally instead of branching on whether the operator declared one.
|
|
45
|
+
*/
|
|
46
|
+
export declare function isWorkdirAllowed(workdir: string, roots: string[]): boolean;
|
|
25
47
|
export interface EnsureWorkDirOptions {
|
|
26
48
|
workRoot: string;
|
|
27
49
|
workflow: string;
|
|
@@ -81,6 +81,86 @@ export function isUnderWorkRoot(dir, workRoot) {
|
|
|
81
81
|
const rel = relative(resolve(workRoot), resolve(dir));
|
|
82
82
|
return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
|
|
83
83
|
}
|
|
84
|
+
/**
|
|
85
|
+
* ── OPERATOR-DECLARED WORKDIR ROOTS ─────────────────────────────────────────
|
|
86
|
+
*
|
|
87
|
+
* A SEPARATE MECHANISM FROM `workRoot` ABOVE, and the two are easy to confuse,
|
|
88
|
+
* so state the difference once:
|
|
89
|
+
*
|
|
90
|
+
* | | `workRoot` (singular) | `allowedWorkdirRoots` (plural) |
|
|
91
|
+
* |---|---|---|
|
|
92
|
+
* | what it is | a directory owenloop WRITES INTO | a list of directories orders may NAME |
|
|
93
|
+
* | who supplies the path | this machine's operator | the run, via `OrderPacket.workdir` |
|
|
94
|
+
* | what it does | holds `<workflow>/<run>/` per-run dirs | permits or refuses a cwd |
|
|
95
|
+
* | unset means | default to `<cacheDir>/work` | NO RESTRICTION |
|
|
96
|
+
*
|
|
97
|
+
* WHY THIS EXISTS. `OrderPacket.workdir` is an opaque location hint the HUB
|
|
98
|
+
* supplies and the worker obeys (`src/exec/loop.ts`, `src/agent/loop.ts`). Since
|
|
99
|
+
* a def may set it from a declared INPUT — `workdirFrom: target.path`, the
|
|
100
|
+
* grammar owenloop 0.5.4 added — the string can originate with whoever started
|
|
101
|
+
* the run, and a shift is not project-bound. So without a local check, a run on
|
|
102
|
+
* the hub picks any absolute path on the operator's machine as a working
|
|
103
|
+
* directory.
|
|
104
|
+
*
|
|
105
|
+
* The boundary belongs to the MACHINE'S OWNER, not to the hub: the person who
|
|
106
|
+
* starts a shift decides which directories that shift may work in. That is why
|
|
107
|
+
* the declaration is a `shift start` flag / settings key / env var and never a
|
|
108
|
+
* def field, a hub policy, or anything a run can influence.
|
|
109
|
+
*
|
|
110
|
+
* DEFAULT-OPEN, DELIBERATELY. An empty list means every path is allowed, which
|
|
111
|
+
* preserves the behaviour of every shift running today. Making it default-closed
|
|
112
|
+
* would break every existing shift on upgrade, and — worse — would do so as a
|
|
113
|
+
* silent refusal of work the hub believes was accepted.
|
|
114
|
+
*
|
|
115
|
+
* INCLUSIVE OF THE ROOT ITSELF, unlike `isUnderWorkRoot`. An operator who
|
|
116
|
+
* declares `/Users/alex/code/dev` means "this project", and `target.path` for
|
|
117
|
+
* that project IS that exact directory. `isUnderWorkRoot` excludes `dir ===
|
|
118
|
+
* root` because there it guards a DELETION and the root must survive; here it
|
|
119
|
+
* guards a cwd, and there is nothing to protect the root from.
|
|
120
|
+
*/
|
|
121
|
+
/** Split a PATH-style (`:`-separated) list of directories, dropping empties. */
|
|
122
|
+
function splitRootList(raw) {
|
|
123
|
+
return raw
|
|
124
|
+
.split(':')
|
|
125
|
+
.map((entry) => entry.trim())
|
|
126
|
+
.filter((entry) => entry !== '');
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Resolve the declared roots: `OWENLOOP_ALLOWED_WORKDIR_ROOTS` >
|
|
130
|
+
* `settings.allowedWorkdirRoots` > none. Mirrors `resolveWorkRoot`'s precedence
|
|
131
|
+
* shape, so there is one rule to remember across this file.
|
|
132
|
+
*
|
|
133
|
+
* The env var is PATH-style `:`-separated because it names a list of
|
|
134
|
+
* directories and that is the convention every operator already knows for one.
|
|
135
|
+
* It REPLACES the settings list rather than adding to it — a narrowing override
|
|
136
|
+
* that could only ever widen would not be a usable safety control.
|
|
137
|
+
*
|
|
138
|
+
* Every entry is resolved to an absolute path against `cwd`, so a relative
|
|
139
|
+
* declaration means what the operator saw when they typed it.
|
|
140
|
+
*/
|
|
141
|
+
export function resolveAllowedWorkdirRoots(env, settingsRoots, cwd) {
|
|
142
|
+
const override = env['OWENLOOP_ALLOWED_WORKDIR_ROOTS'];
|
|
143
|
+
const raw = override !== undefined && override.trim() !== ''
|
|
144
|
+
? splitRootList(override)
|
|
145
|
+
: (settingsRoots ?? []).map((entry) => entry.trim()).filter((entry) => entry !== '');
|
|
146
|
+
return raw.map((entry) => resolve(cwd, entry));
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Is `workdir` inside (or equal to) one of `roots`?
|
|
150
|
+
*
|
|
151
|
+
* An EMPTY `roots` returns true for every path — that is the unrestricted
|
|
152
|
+
* default, not an accident, and it is why callers can pass the resolved list
|
|
153
|
+
* unconditionally instead of branching on whether the operator declared one.
|
|
154
|
+
*/
|
|
155
|
+
export function isWorkdirAllowed(workdir, roots) {
|
|
156
|
+
if (roots.length === 0)
|
|
157
|
+
return true;
|
|
158
|
+
const target = resolve(workdir);
|
|
159
|
+
return roots.some((root) => {
|
|
160
|
+
const rel = relative(resolve(root), target);
|
|
161
|
+
return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
|
|
162
|
+
});
|
|
163
|
+
}
|
|
84
164
|
function defaultRunGit(args, cwd) {
|
|
85
165
|
const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
|
|
86
166
|
return { status: r.status, output: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() };
|
|
@@ -22,7 +22,7 @@ import type { SshProcessAdapter } from '../../../../src/crypto/ssh.ts';
|
|
|
22
22
|
*/
|
|
23
23
|
export declare const CONSUMES_INLINE_MAX_BYTES = 65536;
|
|
24
24
|
/** Discriminated result of an exec run; the role maps these to exit codes. */
|
|
25
|
-
export type ExecOutcome = 'submitted' | 'completed' | 'misroute' | 'unresolved-instructions' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'submit-rejected' | 'submit-failed' | 'rejected' | 'judge-rejected' | 'judge-no-verdict' | 'reject-failed' | 'stopped';
|
|
25
|
+
export type ExecOutcome = 'submitted' | 'completed' | 'misroute' | 'workdir-denied' | 'unresolved-instructions' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'submit-rejected' | 'submit-failed' | 'rejected' | 'judge-rejected' | 'judge-no-verdict' | 'reject-failed' | 'stopped';
|
|
26
26
|
export interface ExecLoopOptions {
|
|
27
27
|
hub: HubClient;
|
|
28
28
|
runner: CommandRunner;
|
|
@@ -40,6 +40,18 @@ export interface ExecLoopOptions {
|
|
|
40
40
|
instructions: InstructionResolver;
|
|
41
41
|
/** cwd for the command when the order packet carries no `workdir`. */
|
|
42
42
|
cwd: string;
|
|
43
|
+
/**
|
|
44
|
+
* The directories this MACHINE's operator declared as places work may happen,
|
|
45
|
+
* already resolved to absolute paths by `resolveAllowedWorkdirRoots`.
|
|
46
|
+
*
|
|
47
|
+
* NOT `workRoot`. `workRoot` is the single directory owenloop CREATES worktrees
|
|
48
|
+
* under; this is the set of directories an ORDER is permitted to name as its
|
|
49
|
+
* cwd. They answer different questions and neither derives from the other.
|
|
50
|
+
*
|
|
51
|
+
* UNSET or EMPTY means NO RESTRICTION — the pre-existing behaviour, and the
|
|
52
|
+
* only default that does not break every shift already running.
|
|
53
|
+
*/
|
|
54
|
+
allowedWorkdirRoots?: string[];
|
|
43
55
|
sleep: (ms: number) => Promise<void>;
|
|
44
56
|
now: () => number;
|
|
45
57
|
random?: () => number;
|
|
@@ -45,6 +45,7 @@ import { createHash } from 'node:crypto';
|
|
|
45
45
|
import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
|
|
46
46
|
import { tmpdir } from 'node:os';
|
|
47
47
|
import { join, resolve } from 'node:path';
|
|
48
|
+
import { isWorkdirAllowed } from "../agent/workdir.js";
|
|
48
49
|
import { createLeaseLoop } from "../lease/loop.js";
|
|
49
50
|
import { parsePayloadLine } from "./payload.js";
|
|
50
51
|
import { buildReceipt } from "./receipt.js";
|
|
@@ -507,6 +508,36 @@ export function createExecLoop(opts) {
|
|
|
507
508
|
await leasePromise;
|
|
508
509
|
return 'misroute';
|
|
509
510
|
}
|
|
511
|
+
// MACHINE POLICY, checked before any instruction is resolved and long before
|
|
512
|
+
// anything is spawned. The operator who started this shift named the
|
|
513
|
+
// directories work may happen in (`owenloop shift start --work-root`, or
|
|
514
|
+
// `allowedWorkdirRoots` in settings); an order naming anything else is
|
|
515
|
+
// refused HERE, in the worker, because the worker is the only process that
|
|
516
|
+
// ever sees `OrderPacket.workdir` — the shift's `whats_next` sweep receives
|
|
517
|
+
// a `WorkOrder`, which has no such field.
|
|
518
|
+
//
|
|
519
|
+
// RELEASED, not failed. This is not a defect in the order and not a failure
|
|
520
|
+
// of the work: it is one machine declining work it was not configured to
|
|
521
|
+
// host. A targeted release returns the order to the hub's pickup window so a
|
|
522
|
+
// differently-configured machine can take it, exactly like `misroute`.
|
|
523
|
+
// Submitting a failure receipt instead would kill a run that is perfectly
|
|
524
|
+
// valid somewhere else.
|
|
525
|
+
//
|
|
526
|
+
// ONLY an order-NAMED workdir is checked. An order that declares none
|
|
527
|
+
// inherits this worker's own launch directory, which the operator chose
|
|
528
|
+
// themselves when they started the shift — bounding an operator's own
|
|
529
|
+
// choice by the operator's own roots protects nobody and would deny every
|
|
530
|
+
// step that legitimately declares no workdir.
|
|
531
|
+
if (order.workdir !== undefined &&
|
|
532
|
+
!isWorkdirAllowed(order.workdir, opts.allowedWorkdirRoots ?? [])) {
|
|
533
|
+
const roots = (opts.allowedWorkdirRoots ?? []).join(', ');
|
|
534
|
+
opts.err(`owenloop work exec: step '${order.step}' (${workflow}/${runId}) names workdir ` +
|
|
535
|
+
`'${order.workdir}', which is outside every work root this machine declared (${roots}) — ` +
|
|
536
|
+
'releasing for the pickup window');
|
|
537
|
+
lease.stop('workdir-denied'); // targeted release — local policy, not a failure
|
|
538
|
+
await leasePromise;
|
|
539
|
+
return 'workdir-denied';
|
|
540
|
+
}
|
|
510
541
|
let resolvedCommand;
|
|
511
542
|
let resolvedBundleDir;
|
|
512
543
|
try {
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { Options, Query, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
|
|
2
|
+
import type { GatePolicy } from './gatekeeper.ts';
|
|
2
3
|
import type { AgentEvent, HarnessAdapter, HarnessSessionRef, StartArgs, StepPermissions } from './contract.ts';
|
|
3
4
|
/**
|
|
4
5
|
* Build the environment the harness child runs under.
|
|
@@ -65,6 +66,29 @@ export declare function allowApiBillingFrom(source: Record<string, string | unde
|
|
|
65
66
|
* and the `PATH` searched are the same ones the child will see.
|
|
66
67
|
*/
|
|
67
68
|
export declare function resolveExecutable(source: Record<string, string | undefined>): string | undefined;
|
|
69
|
+
/**
|
|
70
|
+
* How hard the gatekeeper gates, from the mode the step ACTUALLY AUTHORED.
|
|
71
|
+
*
|
|
72
|
+
* Derived from the authored string rather than from the translated SDK mode
|
|
73
|
+
* because the translation is deliberately lossy in exactly the place that
|
|
74
|
+
* matters: `ask` and `auto-safe` both become `default`, and the whole difference
|
|
75
|
+
* between them now lives here.
|
|
76
|
+
*
|
|
77
|
+
* WHY AN UNSET MODE CLASSIFIES RATHER THAN DENYING. A step that names no
|
|
78
|
+
* `permissionMode` gets the SDK's own `default`, which routes to the callback.
|
|
79
|
+
* Before a callback existed that meant the SDK denied every unapproved call —
|
|
80
|
+
* silently, finally, with nobody prompted and nothing recorded. Treating the
|
|
81
|
+
* unset case as `classifier` is not a widening of what those steps were promised;
|
|
82
|
+
* it is the first time they get anything at all. The same reasoning covers a
|
|
83
|
+
* step that named the vendor's `default` or `acceptEdits`.
|
|
84
|
+
*
|
|
85
|
+
* `dontAsk` is the one value that keeps its narrow meaning: it is documented as
|
|
86
|
+
* "deny if not pre-approved", so it maps to the policy that denies rather than
|
|
87
|
+
* being folded into the classifier. The SDK short-circuits that mode before the
|
|
88
|
+
* callback, so this is a statement of intent more than a live path — but a
|
|
89
|
+
* future SDK that does route it must not find it silently widened here.
|
|
90
|
+
*/
|
|
91
|
+
export declare function gatePolicyFor(authoredMode: string | undefined): GatePolicy;
|
|
68
92
|
/** Everything `buildClaudeOptions` reads for either cold start or resume. */
|
|
69
93
|
export interface ClaudeOptionInputs {
|
|
70
94
|
cwd: string;
|