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.
Files changed (44) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/dist/packages/work/src/agent/brief.d.ts +28 -4
  3. package/dist/packages/work/src/agent/brief.js +170 -2
  4. package/dist/packages/work/src/agent/loop.d.ts +10 -1
  5. package/dist/packages/work/src/agent/loop.js +60 -3
  6. package/dist/packages/work/src/agent/workdir.d.ts +22 -0
  7. package/dist/packages/work/src/agent/workdir.js +80 -0
  8. package/dist/packages/work/src/exec/loop.d.ts +13 -1
  9. package/dist/packages/work/src/exec/loop.js +31 -0
  10. package/dist/packages/work/src/harness/claude.d.ts +24 -0
  11. package/dist/packages/work/src/harness/claude.js +131 -23
  12. package/dist/packages/work/src/harness/contract.d.ts +25 -20
  13. package/dist/packages/work/src/harness/contract.js +25 -20
  14. package/dist/packages/work/src/harness/gatekeeper.d.ts +124 -0
  15. package/dist/packages/work/src/harness/gatekeeper.js +208 -0
  16. package/dist/packages/work/src/hold/mcp.d.ts +11 -2
  17. package/dist/packages/work/src/hold/mcp.js +69 -2
  18. package/dist/packages/work/src/hub/client.d.ts +8 -1
  19. package/dist/packages/work/src/hub/client.js +1 -0
  20. package/dist/packages/work/src/hub/types.d.ts +29 -0
  21. package/dist/packages/work/src/roles/agent-run.js +9 -1
  22. package/dist/packages/work/src/roles/exec.js +9 -0
  23. package/dist/packages/work/src/roles/shift.js +9 -1
  24. package/dist/packages/work/src/settings/settings.d.ts +20 -1
  25. package/dist/packages/work/src/settings/settings.js +23 -1
  26. package/dist/packages/work/src/shift/runtime.d.ts +7 -0
  27. package/dist/packages/work/src/shift/runtime.js +29 -4
  28. package/dist/packages/work/src/shift/spawn.d.ts +12 -2
  29. package/dist/packages/work/src/shift/spawn.js +16 -3
  30. package/dist/src/cli.js +54 -1
  31. package/dist/src/engine.d.ts +46 -1
  32. package/dist/src/engine.js +72 -0
  33. package/dist/src/index.d.ts +1 -1
  34. package/dist/src/index.js +1 -1
  35. package/dist/src/model.d.ts +29 -5
  36. package/dist/src/model.js +63 -14
  37. package/dist/src/types.d.ts +8 -2
  38. package/docs/agent-runner.md +17 -5
  39. package/docs/cli.md +34 -0
  40. package/package.json +1 -1
  41. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  42. package/plugins/claude-code/plugin/.mcp.json +1 -1
  43. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  44. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
@@ -0,0 +1,208 @@
1
+ /**
2
+ * The tool-call gatekeeper: the decision an adapter makes when its harness asks
3
+ * "may this tool call run?".
4
+ *
5
+ * WHY THIS EXISTS. `permissionMode` names three positions — `ask` (a human is
6
+ * the gate), `auto-safe` (a classifier is the gate, a human is the exception
7
+ * path), `full-access` (nothing is gated). Until this module, only the third
8
+ * one was real:
9
+ *
10
+ * - `ask` mapped to the SDK's `default` mode, which routes every unapproved
11
+ * tool call to a `canUseTool` callback and DENIES when no callback is wired.
12
+ * No callback was wired anywhere in this codebase. So `ask` denied everything,
13
+ * silently and finally: the agent saw a bare tool error, nobody was prompted,
14
+ * and nothing was recorded. That is the mechanism behind a planner step
15
+ * reporting that every read of its own target repository was blocked.
16
+ * - `auto-safe` mapped to the SDK's `auto` mode, whose model-side classifier was
17
+ * measured (SDK 0.3.220, callback wired throughout) to consult the host on
18
+ * NONE of five probe actions and to auto-deny none of them: four ran,
19
+ * including a recursive delete on an absolute path outside the session working
20
+ * directory, an outbound network request, and a read under `$HOME`. `auto`
21
+ * never reaches the callback at all, so no amount of host-side wiring gives it
22
+ * an exception path.
23
+ *
24
+ * The practical response to both was to write `permissionMode: full-access` on
25
+ * every step, because it was the only value whose behavior matched its name.
26
+ * That is a workflow author turning permissions off to get work done, which is
27
+ * the failure this module exists to end.
28
+ *
29
+ * WHAT THIS MODULE DECIDES, AND WHAT IT DOES NOT. It answers one question per
30
+ * tool call — allow it, or escalate it — against a stated policy. It does NOT
31
+ * decide what escalation means: the adapter owns that, because the useful
32
+ * answers differ by deployment. Today every adapter denies an escalated call
33
+ * with guidance routing the agent to the `ask` MCP tool, which puts the question
34
+ * to a person through the hub. A worker that can block on a hub-side approval
35
+ * gate would instead wait here and resolve the original call. Keeping that
36
+ * choice out of this module is what lets the second shape land without
37
+ * reopening the classification.
38
+ *
39
+ * HONESTY ABOUT THE CLASSIFIER. Two of the three checks below are decidable and
40
+ * one is not. Path containment is decidable: a resolved path either is or is not
41
+ * inside the tree this step was given. A shell command is not — no pattern list
42
+ * decides whether an arbitrary `bash -c` string is safe, and this one does not
43
+ * pretend to. `dangerousCommand` is a DENY-LIST of high-signal, rarely-legitimate
44
+ * patterns. It catches the measured probes and the ordinary footguns; a
45
+ * deliberately obfuscated command gets past it. The deny-list is kept short on
46
+ * purpose: under `classifier` policy a false positive stops real work in a
47
+ * headless run, and the honest posture for a mode documented as "proceeds on
48
+ * ordinary work" is to allow what it cannot judge. A step whose commands must
49
+ * genuinely all be reviewed should say `permissionMode: ask`, which escalates
50
+ * every shell call without consulting the deny-list at all.
51
+ */
52
+ import { isAbsolute, relative, resolve } from 'node:path';
53
+ const ALLOW = { decision: 'allow' };
54
+ /**
55
+ * Tools that read without mutating anything. Under `human-gate` these are the
56
+ * "trivially safe reads" the `ask` position exempts — but only inside the
57
+ * step's own directory; a read of an arbitrary absolute path is exactly the
58
+ * probe that ran unchallenged under `auto`.
59
+ */
60
+ const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'NotebookRead']);
61
+ /**
62
+ * Where each tool names a filesystem path. Only tools whose path argument is a
63
+ * plain string are listed: containment is checked where it can be checked, and
64
+ * a tool absent from this table simply is not path-checked rather than being
65
+ * guessed at.
66
+ */
67
+ const PATH_ARGS = Object.freeze({
68
+ Read: ['file_path'],
69
+ Write: ['file_path'],
70
+ Edit: ['file_path'],
71
+ NotebookRead: ['notebook_path'],
72
+ NotebookEdit: ['notebook_path'],
73
+ Glob: ['path'],
74
+ Grep: ['path'],
75
+ });
76
+ /**
77
+ * The owenloop MCP mount, which is ALWAYS allowed under every policy.
78
+ *
79
+ * This is not a convenience. `submit` is how a step discharges what it owes and
80
+ * `ask` is how it escalates to a person — including how it escalates a call this
81
+ * very gatekeeper just refused. Gating either one makes an escalated step unable
82
+ * to report that it is stuck, which converts a recoverable stall into a silent
83
+ * one. The mount is worker-owned and its surface is fixed at four tools
84
+ * (`get_order`, `submit`, `reject`, `ask`), none of which touch the filesystem
85
+ * or the network beyond the hub, so there is nothing here for a human to weigh.
86
+ */
87
+ const OWENLOOP_MCP_PREFIX = 'mcp__owenloop__';
88
+ /**
89
+ * Shell patterns the deny-list escalates. Each entry has to clear a high bar:
90
+ * genuinely destructive or exfiltrating, AND essentially never legitimate in a
91
+ * step doing repository work. Anything that merely LOOKS alarming but has an
92
+ * ordinary use in this pipeline is deliberately absent — `git push --force`, for
93
+ * one, is routine on a step's own branch, and escalating it would stop real work
94
+ * every run in exchange for no safety.
95
+ */
96
+ const DANGEROUS_COMMAND_PATTERNS = Object.freeze([
97
+ { pattern: /\b(?:sudo|doas)\b/u, what: 'runs a command as another user' },
98
+ {
99
+ pattern: /\brm\s+(?:-[a-zA-Z]*[rR][a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*[rR])\b/u,
100
+ what: 'is a recursive force-delete',
101
+ },
102
+ { pattern: /\bdd\b[^\n]*\bof=\/dev\//u, what: 'writes directly to a device' },
103
+ { pattern: /\b(?:mkfs(?:\.\w+)?|diskutil\s+erase\w*)\b/u, what: 'erases or formats a volume' },
104
+ { pattern: /\bchown\b/u, what: 'changes file ownership' },
105
+ { pattern: /\bchmod\s+(?:[0-7]*777|a\+[rwx]*w)/u, what: 'makes a file world-writable' },
106
+ {
107
+ pattern: /\b(?:curl|wget)\b[^\n]*(?:\s-X\s*(?:POST|PUT|PATCH|DELETE)\b|\s--(?:data|upload-file|post-file)\b|\s-d\s)/u,
108
+ what: 'sends data to a remote host',
109
+ },
110
+ {
111
+ pattern: /\b(?:crontab|launchctl|systemctl|schtasks)\b/u,
112
+ what: 'changes what runs on this machine outside this step',
113
+ },
114
+ {
115
+ pattern: /(?:>>?\s*)(?:~|\$HOME)?\/?\.(?:zshrc|bashrc|bash_profile|zprofile|profile)\b/u,
116
+ what: 'writes to a shell startup file',
117
+ },
118
+ ]);
119
+ /** Every string in a model-authored argument bag, at the top level. Enough for
120
+ * the path table (whose arguments are all top-level strings) without walking an
121
+ * arbitrary nested value. */
122
+ function stringArg(input, key) {
123
+ const v = input[key];
124
+ return typeof v === 'string' && v !== '' ? v : undefined;
125
+ }
126
+ /**
127
+ * Whether `candidate` resolves inside `root`.
128
+ *
129
+ * Resolved against `root` first, so a relative path means what the harness will
130
+ * mean by it. The `..` test is on the RELATIVE result rather than on the input
131
+ * string: `a/../../b` contains no leading `..` but lands outside, and a string
132
+ * test would pass it.
133
+ */
134
+ export function isInside(root, candidate) {
135
+ const absRoot = resolve(root);
136
+ const absCandidate = isAbsolute(candidate) ? resolve(candidate) : resolve(absRoot, candidate);
137
+ if (absCandidate === absRoot)
138
+ return true;
139
+ const rel = relative(absRoot, absCandidate);
140
+ return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
141
+ }
142
+ /**
143
+ * The first deny-list pattern this command matches, or `undefined`.
144
+ *
145
+ * Exported for the tests, which assert the list's shape directly: the value of a
146
+ * deny-list is entirely in which patterns are on it, so those assertions are the
147
+ * documentation of what it does and does not claim to catch.
148
+ */
149
+ export function dangerousCommand(command) {
150
+ for (const { pattern, what } of DANGEROUS_COMMAND_PATTERNS) {
151
+ if (pattern.test(command))
152
+ return what;
153
+ }
154
+ return undefined;
155
+ }
156
+ /**
157
+ * Judge one tool call.
158
+ *
159
+ * ORDER MATTERS. The owenloop mount is cleared first so no later rule can strand
160
+ * a step's ability to submit or escalate. The harness's own `blockedPath` is
161
+ * consulted next because it is authoritative and covers cases this module cannot
162
+ * see. Only then does policy divide: `human-gate` escalates everything but a
163
+ * contained read, `classifier` runs the two checks it can actually decide.
164
+ */
165
+ export function classifyToolCall(call, policy) {
166
+ if (call.toolName.startsWith(OWENLOOP_MCP_PREFIX))
167
+ return ALLOW;
168
+ if (policy === 'deny-unapproved') {
169
+ return { decision: 'escalate', reason: `permissionMode denies unapproved tool calls` };
170
+ }
171
+ // The harness saw something this module did not — trust it.
172
+ if (call.blockedPath !== undefined && call.blockedPath !== '') {
173
+ return {
174
+ decision: 'escalate',
175
+ reason: `the harness flagged \`${call.blockedPath}\` as outside the directories this step may touch`,
176
+ };
177
+ }
178
+ const paths = (PATH_ARGS[call.toolName] ?? [])
179
+ .map((key) => stringArg(call.input, key))
180
+ .filter((p) => p !== undefined);
181
+ for (const p of paths) {
182
+ if (!isInside(call.workdir, p)) {
183
+ return {
184
+ decision: 'escalate',
185
+ reason: `\`${p}\` is outside this step's working directory (\`${call.workdir}\`)`,
186
+ };
187
+ }
188
+ }
189
+ if (policy === 'human-gate') {
190
+ // Every path this tool named is contained, or it named none. A read is the
191
+ // one thing `ask` lets through; anything that can mutate or reach the
192
+ // network is what the position exists to put in front of a person.
193
+ if (READ_ONLY_TOOLS.has(call.toolName))
194
+ return ALLOW;
195
+ return {
196
+ decision: 'escalate',
197
+ reason: `permissionMode is \`ask\`, so \`${call.toolName}\` needs a person's approval`,
198
+ };
199
+ }
200
+ const command = stringArg(call.input, 'command');
201
+ if (call.toolName === 'Bash' && command !== undefined) {
202
+ const what = dangerousCommand(command);
203
+ if (what !== undefined) {
204
+ return { decision: 'escalate', reason: `the command ${what}` };
205
+ }
206
+ }
207
+ return ALLOW;
208
+ }
@@ -4,7 +4,7 @@
4
4
  * A born-bound work-holder: the D2 stamped Step Agent's frontmatter declares
5
5
  * `mcpServers.owenloop = owenloop work hold --order <wf>/<run> --origin <url> --mcp`,
6
6
  * so when the Step Agent session boots it launches THIS as a stdio MCP server. The
7
- * server exposes three bare tools the model uses to do its order:
7
+ * server exposes four bare tools the model uses to do its order:
8
8
  * - `get_order` → the order packet (prompt, inputs, owed outputs) for the run
9
9
  * this holder is bound to. No ids are arguments — they came in on argv, never
10
10
  * through the model.
@@ -14,6 +14,15 @@
14
14
  * - `reject` → invalidate a consumed artifact through the claiming step's
15
15
  * server-derived authority; the client never supplies `by`. A CLOSED reject
16
16
  * also stops the lease loop without releasing the already-closed claim.
17
+ * - `ask` → stop and escalate to a human about an OWED output path. The
18
+ * third exit. `submit` and `reject` both assume the worker can finish; until
19
+ * `ask` existed a worker that genuinely could not had only two moves, and
20
+ * both damaged the run: submit something it did not believe (greens a
21
+ * fabrication that every downstream step then builds on), or end its turn
22
+ * silently (the task re-arms and a fresh worker relearns the same blocker
23
+ * until the stall cap). `ask` holds the artifact with no counter movement
24
+ * and surfaces the question to an operator, who answers with
25
+ * `owenloop retry <workflow> <path> --text "<answer>"`.
17
26
  *
18
27
  * Underneath the tools, the SAME lease loop the CLI `hold` runs keeps the order's
19
28
  * lease warm: `createHoldMcp` builds the loop with `onOrder` wired to capture the
@@ -33,7 +42,7 @@ import { type SubmissionKeyManager } from '../submit-proof.ts';
33
42
  import type { SshProcessAdapter } from '../../../../src/crypto/ssh.ts';
34
43
  import type { ConsumedVerifier } from '../consumed-verifier.ts';
35
44
  import { type HoldLoop } from './loop.ts';
36
- export declare const HOLD_MCP_TOOL_NAMES: readonly ["get_order", "submit", "reject"];
45
+ export declare const HOLD_MCP_TOOL_NAMES: readonly ["get_order", "submit", "reject", "ask"];
37
46
  export type HoldMcpToolName = (typeof HOLD_MCP_TOOL_NAMES)[number];
38
47
  export interface HoldMcpDeps {
39
48
  hub: HubClient;
@@ -4,7 +4,7 @@
4
4
  * A born-bound work-holder: the D2 stamped Step Agent's frontmatter declares
5
5
  * `mcpServers.owenloop = owenloop work hold --order <wf>/<run> --origin <url> --mcp`,
6
6
  * so when the Step Agent session boots it launches THIS as a stdio MCP server. The
7
- * server exposes three bare tools the model uses to do its order:
7
+ * server exposes four bare tools the model uses to do its order:
8
8
  * - `get_order` → the order packet (prompt, inputs, owed outputs) for the run
9
9
  * this holder is bound to. No ids are arguments — they came in on argv, never
10
10
  * through the model.
@@ -14,6 +14,15 @@
14
14
  * - `reject` → invalidate a consumed artifact through the claiming step's
15
15
  * server-derived authority; the client never supplies `by`. A CLOSED reject
16
16
  * also stops the lease loop without releasing the already-closed claim.
17
+ * - `ask` → stop and escalate to a human about an OWED output path. The
18
+ * third exit. `submit` and `reject` both assume the worker can finish; until
19
+ * `ask` existed a worker that genuinely could not had only two moves, and
20
+ * both damaged the run: submit something it did not believe (greens a
21
+ * fabrication that every downstream step then builds on), or end its turn
22
+ * silently (the task re-arms and a fresh worker relearns the same blocker
23
+ * until the stall cap). `ask` holds the artifact with no counter movement
24
+ * and surfaces the question to an operator, who answers with
25
+ * `owenloop retry <workflow> <path> --text "<answer>"`.
17
26
  *
18
27
  * Underneath the tools, the SAME lease loop the CLI `hold` runs keeps the order's
19
28
  * lease warm: `createHoldMcp` builds the loop with `onOrder` wired to capture the
@@ -30,7 +39,7 @@ import { textResult } from "../mcp/server.js";
30
39
  import { buildSubmitProof } from "../submit-proof.js";
31
40
  import { normalizeSubmitValue } from "../submit-value.js";
32
41
  import { createHoldLoop } from "./loop.js";
33
- export const HOLD_MCP_TOOL_NAMES = ['get_order', 'submit', 'reject'];
42
+ export const HOLD_MCP_TOOL_NAMES = ['get_order', 'submit', 'reject', 'ask'];
34
43
  function errMsg(e) {
35
44
  return e instanceof Error ? e.message : String(e);
36
45
  }
@@ -261,10 +270,68 @@ export function createHoldMcp(deps) {
261
270
  }
262
271
  },
263
272
  };
273
+ const askTool = {
274
+ name: 'ask',
275
+ description: 'Stop and ask a human about an output path you OWE, when you cannot produce it honestly — a required input is missing, wrong, or contradictory, or the order asks for a decision only a person can make. Use this INSTEAD of submitting a guess and INSTEAD of ending your turn without submitting: a guess greens and poisons every step downstream, and ending silently just re-runs this same step until it burns its retry budget. Asking does not count as a failure and costs you no attempts. The step is held until a human answers; your run ends here.',
276
+ inputSchema: {
277
+ type: 'object',
278
+ required: ['path', 'question'],
279
+ properties: {
280
+ path: {
281
+ type: 'string',
282
+ description: 'The owed output path you are blocked on (one of the `owes` paths from get_order).',
283
+ },
284
+ question: {
285
+ type: 'string',
286
+ description: 'The specific question for the human. State what decision or fact you need, not just that you are stuck — this is the whole message they receive.',
287
+ },
288
+ context: {
289
+ type: 'string',
290
+ description: 'Optional: what you already tried, what you read, and why it was not enough. Saves the human from reconstructing it from logs.',
291
+ },
292
+ },
293
+ additionalProperties: false,
294
+ },
295
+ handler: async (args) => {
296
+ const gone = terminalGuard();
297
+ if (gone !== undefined)
298
+ return gone;
299
+ const path = args['path'];
300
+ const question = args['question'];
301
+ const context = args['context'];
302
+ if (typeof path !== 'string' || path.trim() === '') {
303
+ return textResult({ error: 'ask requires a non-empty string "path"' }, true);
304
+ }
305
+ if (typeof question !== 'string' || question.trim() === '') {
306
+ return textResult({ error: 'ask requires a non-empty string "question"' }, true);
307
+ }
308
+ if (context !== undefined && typeof context !== 'string') {
309
+ return textResult({ error: 'ask "context" must be a string when present' }, true);
310
+ }
311
+ try {
312
+ const res = await hub.ask({
313
+ workflow,
314
+ run,
315
+ path,
316
+ question,
317
+ ...(typeof context === 'string' && context.trim() !== '' ? { context } : {}),
318
+ });
319
+ // Asking ENDS the run. Same shape as submit/reject's closed branch:
320
+ // stop without releasing, because the hub already closed the claim.
321
+ if (res.closed === true)
322
+ loop.stop('asked', { release: false });
323
+ return textResult({ ok: res.ok, closed: res.closed ?? false, text: res.text });
324
+ }
325
+ catch (e) {
326
+ return textResult({ error: errMsg(e) }, true);
327
+ }
328
+ },
329
+ };
264
330
  const registrations = {
265
331
  get_order: getOrderTool,
266
332
  submit: submitTool,
267
333
  reject: rejectTool,
334
+ ask: askTool,
268
335
  };
269
336
  const selected = deps.tools ?? HOLD_MCP_TOOL_NAMES;
270
337
  return { tools: selected.map((name) => registrations[name]), loop };
@@ -1,4 +1,4 @@
1
- import type { GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, ReportResolutionRequest, ReportResolutionResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
1
+ import type { AskRequest, AskResponse, GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, ReportResolutionRequest, ReportResolutionResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
2
2
  export interface HubClientOptions {
3
3
  /** Hub origin, e.g. `https://hub.owenloop.dev` (no trailing slash needed). */
4
4
  origin: string;
@@ -14,6 +14,13 @@ export interface HubClient {
14
14
  release(req: ReleaseRequest): Promise<ReleaseResponse>;
15
15
  submit(req: SubmitRequest): Promise<SubmitResponse>;
16
16
  reject(req: RejectRequest): Promise<RejectResponse>;
17
+ /**
18
+ * ESCALATION: the worker stops and asks a human about an artifact it OWES.
19
+ * Distinct from `reject`, which is a verdict on somebody else's delivered
20
+ * work. Holds the artifact (no counter moves) until a human answers with
21
+ * `owenloop retry <workflow> <path> --text "<answer>"`.
22
+ */
23
+ ask(req: AskRequest): Promise<AskResponse>;
17
24
  /**
18
25
  * Plan §6: record what this shift resolved the order's compound capability to,
19
26
  * BEFORE the harness launches. Idempotent on the hub by order id, so a
@@ -82,6 +82,7 @@ export function createHubClient(opts) {
82
82
  release: (req) => post('release', req),
83
83
  submit: (req) => post('submit', req),
84
84
  reject: (req) => post('reject', req),
85
+ ask: (req) => post('ask', req),
85
86
  reportResolution: (req) => post('report_resolution', req),
86
87
  whoami: () => get('whoami'),
87
88
  // Cursor is an opaque non-negative integer; omit it entirely to bootstrap
@@ -367,6 +367,35 @@ export interface RejectResponse extends HubResponse {
367
367
  ok: boolean;
368
368
  closed?: boolean;
369
369
  }
370
+ /**
371
+ * ESCALATION: the claiming worker cannot honestly build what it owes and stops
372
+ * to ask a person. `path` is one of the order's OWED paths — unlike `reject`,
373
+ * whose `path` is somebody else's delivered work, this is the worker's own debt.
374
+ *
375
+ * `by` is absent for the same reason it is absent on `reject`: the hub derives
376
+ * the actor from the claiming run's step, so a worker cannot ask on another
377
+ * step's behalf. `question` is what the human is being asked; `context` is
378
+ * optional supporting detail (what the worker already tried, which files it
379
+ * read) that rides the same reason-thread entry so the answering human does not
380
+ * have to reconstruct it from logs.
381
+ */
382
+ export interface AskRequest {
383
+ workflow: string;
384
+ run: string;
385
+ path: string;
386
+ question: string;
387
+ context?: string;
388
+ }
389
+ /**
390
+ * The ask verb's flattened envelope. `closed` reports whether the escalation
391
+ * closed the worker's run — it does, always: a worker that has asked has
392
+ * nothing further to do on this order, and holding the lease open would only
393
+ * let it expire into a reap.
394
+ */
395
+ export interface AskResponse extends HubResponse {
396
+ ok: boolean;
397
+ closed?: boolean;
398
+ }
370
399
  export interface WhoamiResponse extends HubResponse {
371
400
  orgId: string;
372
401
  orgName: string;
@@ -96,7 +96,7 @@ import { adapterFor, defaultHarnessId, registeredHarnessIds } from "../harness/r
96
96
  import { parseHarnessCarrier } from "../bundle/fetch.js";
97
97
  import { normalizeStepPermissions, validateHarnessOptions } from "../harness/permissions.js";
98
98
  import { appendSession, latestFor, sessionsPath } from "../harness/session-store.js";
99
- import { ensureWorkDir, resolveWorkRepo, resolveWorkRoot } from "../agent/workdir.js";
99
+ import { ensureWorkDir, resolveAllowedWorkdirRoots, resolveWorkRepo, resolveWorkRoot, } from "../agent/workdir.js";
100
100
  import { resolveShiftId, resolveTarget } from "./hold.js";
101
101
  import { installSignalHandlers } from "./signals.js";
102
102
  const DEFAULT_INTERVAL_MS = 60_000;
@@ -195,6 +195,7 @@ export function exitCodeFor(outcome) {
195
195
  case 'completed':
196
196
  return 0;
197
197
  case 'misroute':
198
+ case 'workdir-denied':
198
199
  case 'no-template':
199
200
  case 'no-harness':
200
201
  case 'incompatible-harness-policy':
@@ -495,6 +496,13 @@ export async function run(args, deps = {}) {
495
496
  account,
496
497
  ...(shiftId !== undefined ? { shiftId } : {}),
497
498
  cwd: workCwd,
499
+ // Machine policy, resolved from the SAME two sources the shift resolves it
500
+ // from: `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (which `owenloop shift start`
501
+ // exports when the operator passed `--work-root`) then the settings file.
502
+ // Resolved against `process.cwd()`, not `workCwd`: a relative root in the
503
+ // env means "relative to where this process was launched", and `workCwd`
504
+ // may be a directory owenloop just created under the cache root.
505
+ allowedWorkdirRoots: resolveAllowedWorkdirRoots(env, settings.allowedWorkdirRoots, process.cwd()),
498
506
  loadStep,
499
507
  resolveAdapter,
500
508
  ...(capabilityModels !== undefined ? { capabilityModels } : {}),
@@ -34,6 +34,7 @@
34
34
  import { hostname } from 'node:os';
35
35
  import { createHubClient } from "../hub/client.js";
36
36
  import { resolveBearer } from "../credentials/resolve.js";
37
+ import { resolveAllowedWorkdirRoots } from "../agent/workdir.js";
37
38
  import { loadSettings } from "../settings/settings.js";
38
39
  import { createExecLoop } from "../exec/loop.js";
39
40
  import { createDefaultStoreInstructionResolver } from "../exec/instructions.js";
@@ -121,6 +122,7 @@ export function exitCodeFor(outcome) {
121
122
  case 'judge-rejected':
122
123
  return 0;
123
124
  case 'misroute':
125
+ case 'workdir-denied':
124
126
  case 'unresolved-instructions':
125
127
  case 'killed':
126
128
  case 'lease-lost':
@@ -173,6 +175,12 @@ export async function run(args, deps = {}) {
173
175
  return 2;
174
176
  }
175
177
  const cwd = deps.cwd ?? process.cwd();
178
+ // Machine policy, resolved from the SAME two sources the shift resolves it
179
+ // from: `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (which `owenloop shift start` exports
180
+ // when the operator passed `--work-root`) then the settings file. An
181
+ // independently launched `owenloop work exec` therefore honours the settings
182
+ // file on its own, with no shift involved.
183
+ const allowedWorkdirRoots = resolveAllowedWorkdirRoots(env, settings.allowedWorkdirRoots, cwd);
176
184
  let instructions = deps.instructions;
177
185
  if (instructions === undefined) {
178
186
  try {
@@ -208,6 +216,7 @@ export async function run(args, deps = {}) {
208
216
  holder,
209
217
  instructions,
210
218
  cwd,
219
+ allowedWorkdirRoots,
211
220
  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
212
221
  now: () => Date.now(),
213
222
  out,
@@ -15,6 +15,7 @@ function usage() {
15
15
  ' [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]\n' +
16
16
  ' [--cache-dir <p>] [--state-dir <p>]\n' +
17
17
  ' [--log-dir <p>] [--log-max-age <ms>]\n' +
18
+ ' [--work-root <dir>]... restrict this shift to these directories\n' +
18
19
  ' owenloop shift next [--wait <seconds>] [--state-dir <p>]\n' +
19
20
  ' owenloop shift status [--state-dir <p>]\n' +
20
21
  ' owenloop shift end [--state-dir <p>]\n');
@@ -30,7 +31,7 @@ function parseStartArgs(args) {
30
31
  const parsed = { crews: [] };
31
32
  const valueFlags = new Set([
32
33
  '--origin', '--as', '--name', '--cap', '--max-agents', '--poll-interval',
33
- '--cache-dir', '--state-dir', '--log-dir', '--log-max-age',
34
+ '--cache-dir', '--state-dir', '--log-dir', '--log-max-age', '--work-root',
34
35
  ]);
35
36
  for (let i = 0; i < args.length; i++) {
36
37
  const raw = args[i];
@@ -87,6 +88,13 @@ function parseStartArgs(args) {
87
88
  return { crews: parsed.crews, error: n };
88
89
  parsed.pollIntervalMs = n;
89
90
  }
91
+ else if (name === '--work-root') {
92
+ // REPEATABLE — one directory per occurrence. See `ParsedArgs.workRoots`
93
+ // in `src/shift/runtime.ts` for why this accumulates instead of taking
94
+ // a separated list, and `src/agent/workdir.ts` for how this differs
95
+ // from the singular `workRoot` setting.
96
+ (parsed.workRoots ??= []).push(value);
97
+ }
90
98
  continue;
91
99
  }
92
100
  if (raw.startsWith('-'))
@@ -99,6 +99,25 @@ export interface Settings {
99
99
  * of the MACHINE running the shift, not of the workflow.
100
100
  */
101
101
  workRepo?: string;
102
+ /**
103
+ * The directories a shift on THIS machine may accept as an order's working
104
+ * directory. Absolute paths; a directory permits itself and everything under
105
+ * it.
106
+ *
107
+ * NOT `workRoot` (above) UNDER A DIFFERENT NAME. `workRoot` is a directory
108
+ * owenloop writes per-run subdirectories INTO. This is a list of directories
109
+ * a HUB-SUPPLIED `OrderPacket.workdir` is allowed to name. See
110
+ * `src/agent/workdir.ts` for the side-by-side table and the full rationale.
111
+ *
112
+ * UNSET OR EMPTY MEANS NO RESTRICTION, which is what every shift running
113
+ * today does. Default-closed would refuse work on upgrade, silently, on
114
+ * machines whose operator never asked for a boundary.
115
+ *
116
+ * Overridden by `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (PATH-style, `:`-separated)
117
+ * and by `owenloop shift start --work-root <dir>` (repeatable). The override
118
+ * REPLACES this list; it does not extend it.
119
+ */
120
+ allowedWorkdirRoots?: string[];
102
121
  /**
103
122
  * How THIS machine serves each capability: a flat map from capability to
104
123
  * `{model, effort}`, keyed by the composed capability (`wise:deep`) or by the
@@ -113,7 +132,7 @@ export interface Settings {
113
132
  capabilityModels?: Record<string, CapabilityModelRow>;
114
133
  }
115
134
  /** The known settings keys, in the order `owenloop work settings` prints them. */
116
- export declare const KNOWN_SETTINGS_KEYS: readonly ["hubOrigin", "cacheDir", "stateDir", "dispatchCap", "shiftLogDir", "shiftLogMaxAgeMs", "commandRouting", "defPolicy", "artifactPolicy", "maxConcurrentAgents", "workRoot", "workRepo", "capabilityModels"];
135
+ export declare const KNOWN_SETTINGS_KEYS: readonly ["hubOrigin", "cacheDir", "stateDir", "dispatchCap", "shiftLogDir", "shiftLogMaxAgeMs", "commandRouting", "defPolicy", "artifactPolicy", "maxConcurrentAgents", "workRoot", "workRepo", "allowedWorkdirRoots", "capabilityModels"];
117
136
  /**
118
137
  * Keys owenloop still RECOGNIZES but no longer acts on. Each one produces a
119
138
  * warning naming what replaced it, and is excluded from `unrecognized` so the
@@ -13,7 +13,7 @@
13
13
  * own store (the CredentialReader seam) — there is deliberately no token knob.
14
14
  */
15
15
  import { existsSync, readFileSync } from 'node:fs';
16
- import { join } from 'node:path';
16
+ import { isAbsolute, join } from 'node:path';
17
17
  import { owenloopConfigDir } from "../../../../src/config-dir.js";
18
18
  import { validateCapabilityModels } from "../agent/capability-model.js";
19
19
  /** The known settings keys, in the order `owenloop work settings` prints them. */
@@ -30,6 +30,7 @@ export const KNOWN_SETTINGS_KEYS = [
30
30
  'maxConcurrentAgents',
31
31
  'workRoot',
32
32
  'workRepo',
33
+ 'allowedWorkdirRoots',
33
34
  'capabilityModels',
34
35
  ];
35
36
  /**
@@ -114,6 +115,27 @@ export function validateSettings(raw, path) {
114
115
  `Depth now rides on the capability's modifier suffix, not on a tier rung.`);
115
116
  }
116
117
  }
118
+ if ('allowedWorkdirRoots' in obj) {
119
+ // ABSOLUTE PATHS ONLY, and that is the one rule worth a hard error rather
120
+ // than a warning. A relative entry would resolve against whatever directory
121
+ // the shift process happened to start in — the very "wherever the shift was
122
+ // launched" assumption this key exists to remove — so a boundary written
123
+ // relatively would move with the launch directory and permit a different
124
+ // set of paths on every start.
125
+ const v = obj['allowedWorkdirRoots'];
126
+ if (!Array.isArray(v) || v.some((entry) => typeof entry !== 'string')) {
127
+ throw bad('allowedWorkdirRoots', 'an array of absolute directory paths', v);
128
+ }
129
+ for (const entry of v) {
130
+ if (entry.trim() === '') {
131
+ throw bad('allowedWorkdirRoots', 'an array of NON-EMPTY absolute directory paths', v);
132
+ }
133
+ if (!isAbsolute(entry)) {
134
+ throw new Error(`invalid settings file at ${path}: 'allowedWorkdirRoots' entry ${JSON.stringify(entry)} must be an ` +
135
+ `absolute path — a relative root would resolve against whatever directory the shift was launched in`);
136
+ }
137
+ }
138
+ }
117
139
  if ('capabilityModels' in obj) {
118
140
  const v = obj['capabilityModels'];
119
141
  if (typeof v !== 'object' || v === null || Array.isArray(v)) {
@@ -35,6 +35,13 @@ export interface ParsedArgs {
35
35
  logDir?: string;
36
36
  /** `--log-max-age` — worker-log retention in milliseconds. `0` reaps eagerly. */
37
37
  logMaxAgeMs?: number;
38
+ /**
39
+ * `--work-root <dir>` — REPEATABLE. Each occurrence adds one directory the
40
+ * shift may accept as an order's working directory; passing none leaves the
41
+ * shift unrestricted. Distinct from `settings.workRoot` (singular), which is
42
+ * where owenloop CREATES per-run directories — see `src/agent/workdir.ts`.
43
+ */
44
+ workRoots?: string[];
38
45
  error?: string;
39
46
  }
40
47
  /** Parse shift's internal `--flag value` and `--flag=value` forms. */