owenloop 0.5.3 → 0.5.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +6 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +6 -0
  4. package/dist/packages/work/src/agent/brief.js +102 -2
  5. package/dist/packages/work/src/agent/loop.d.ts +10 -1
  6. package/dist/packages/work/src/agent/loop.js +28 -0
  7. package/dist/packages/work/src/agent/workdir.d.ts +22 -0
  8. package/dist/packages/work/src/agent/workdir.js +80 -0
  9. package/dist/packages/work/src/exec/loop.d.ts +13 -1
  10. package/dist/packages/work/src/exec/loop.js +184 -9
  11. package/dist/packages/work/src/harness/child-env.js +8 -0
  12. package/dist/packages/work/src/harness/claude.js +25 -6
  13. package/dist/packages/work/src/harness/codex.js +7 -0
  14. package/dist/packages/work/src/harness/contract.d.ts +22 -3
  15. package/dist/packages/work/src/harness/contract.js +22 -3
  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 +32 -5
  25. package/dist/packages/work/src/settings/settings.js +37 -12
  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 +257 -7
  31. package/dist/src/config-dir.d.ts +62 -0
  32. package/dist/src/config-dir.js +87 -0
  33. package/dist/src/crypto/trust-roots.d.ts +8 -4
  34. package/dist/src/crypto/trust-roots.js +18 -12
  35. package/dist/src/defs.js +57 -16
  36. package/dist/src/engine.d.ts +46 -1
  37. package/dist/src/engine.js +97 -3
  38. package/dist/src/hub.d.ts +5 -1
  39. package/dist/src/hub.js +7 -8
  40. package/dist/src/index.d.ts +1 -1
  41. package/dist/src/index.js +1 -1
  42. package/dist/src/model.d.ts +29 -5
  43. package/dist/src/model.js +63 -14
  44. package/dist/src/paths.d.ts +47 -4
  45. package/dist/src/paths.js +36 -5
  46. package/dist/src/types.d.ts +8 -2
  47. package/dist/src/work-settings.d.ts +8 -5
  48. package/dist/src/work-settings.js +15 -12
  49. package/docs/authoring.md +40 -13
  50. package/docs/bundles.md +9 -0
  51. package/docs/cli.md +155 -24
  52. package/docs/crypto.md +8 -8
  53. package/docs/design.md +20 -2
  54. package/docs/embedding.md +5 -4
  55. package/docs/wire-contracts.md +3 -2
  56. package/package.json +1 -1
  57. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  58. package/plugins/claude-code/plugin/.mcp.json +1 -1
  59. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  60. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
@@ -108,6 +108,14 @@ export const ADMITTED_OWENLOOP_KEYS = new Set([
108
108
  'OWENLOOP_NO_KEYCHAIN',
109
109
  // `holdSession` — src/roles/hold.ts. The fallback when `--session` is absent.
110
110
  'OWENLOOP_SESSION',
111
+ // `owenloopConfigDir` — src/config-dir.ts. Scopes owenloop's OWN config
112
+ // directory (`settings.json`, `credentials.json`, `allowed_signers`) without
113
+ // touching `XDG_CONFIG_HOME`, which the rest of the operator's toolchain also
114
+ // reads. A path, not credential material — but the credential FILE backend
115
+ // resolves under it (`readStoredCredential` → `configDir` → src/hub.ts), so a
116
+ // mount that does not see this variable falls back to `XDG_CONFIG_HOME` and
117
+ // reads a DIFFERENT credential store than the shift that spawned it.
118
+ 'OWENLOOP_CONFIG_DIR',
111
119
  ]);
112
120
  /** The namespace this filter governs. Nothing outside it is ever touched. */
113
121
  const NAMESPACE = 'OWENLOOP_';
@@ -186,11 +186,24 @@ const PERMISSION_MODES = [
186
186
  * `canUseTool` callback — a human decision point — and denies when no callback
187
187
  * is wired. That is the "human is the gate" position.
188
188
  * - `auto-safe` → `auto`. `auto` is the SDK's model-classifier mode: it decides
189
- * per call and escalates the ones it judges dangerous. NOT `acceptEdits`,
190
- * which auto-approves filesystem operations by category and applies no
191
- * judgment to anything else, and NOT `dontAsk`, which DENIES an unapproved
192
- * tool rather than consulting anyone — silently narrower than what the step
193
- * asked for.
189
+ * per call, with no prompt. NOT `acceptEdits`, which auto-approves filesystem
190
+ * operations by category and applies no judgment to anything else, and NOT
191
+ * `dontAsk`, which DENIES an unapproved tool rather than consulting anyone —
192
+ * silently narrower than what the step asked for.
193
+ *
194
+ * MEASURED against SDK 0.3.220, `canUseTool` wired throughout: the classifier
195
+ * consulted the host on NONE of five probe commands, and emitted no
196
+ * `permission_denied` system message for any of them. Four ran, including
197
+ * `rm -rf` on an ABSOLUTE path outside the session cwd (verified by the
198
+ * target directory being gone afterwards), a `curl` to the public internet,
199
+ * and a read of a file under `$HOME` outside cwd.
200
+ *
201
+ * So `auto` does not, in practice, escalate to whoever hosts the session.
202
+ * Wiring `canUseTool` does not give `auto-safe` a human exception path — the
203
+ * callback is simply never reached. Anything that needs a person in the loop
204
+ * has to run under `ask`, whose `default` mode does route to the callback
205
+ * (measured on the same SDK build, including calls originating inside a
206
+ * subagent, which arrive carrying that subagent's `agentID`).
194
207
  * - `full-access` → `bypassPermissions`. The only SDK mode that runs tools with
195
208
  * no prompt at all, and the one the companion flag below exists for.
196
209
  *
@@ -245,7 +258,13 @@ const OWENLOOP_ONLY_NETWORK_TOOLS = new Set([
245
258
  * unrestricted-network readers. */
246
259
  const READ_ONLY_OWENLOOP_ONLY_NETWORK_TOOLS = [...READ_ONLY_TOOLS]
247
260
  .filter((tool) => OWENLOOP_ONLY_NETWORK_TOOLS.has(tool));
248
- const BORN_BOUND_OWENLOOP_TOOL_NAMES = ['get_order', 'submit'];
261
+ // The tools a born-bound step agent gets no matter how restricted it is.
262
+ // `ask` is here for the same reason `submit` is: without it a restricted agent
263
+ // has no legal way to END. It could previously only submit (fabricating when it
264
+ // did not know) or fall silent (re-arming the step into a retry storm). `ask` is
265
+ // about the agent's OWN owed artifact, so unlike `reject` it grants no authority
266
+ // over anyone else's work and there is no reason to withhold it under isolation.
267
+ const BORN_BOUND_OWENLOOP_TOOL_NAMES = ['get_order', 'submit', 'ask'];
249
268
  const BORN_BOUND_OWENLOOP_TOOLS = BORN_BOUND_OWENLOOP_TOOL_NAMES.map((name) => `mcp__owenloop__${name}`);
250
269
  const RESTRICTED_OWENLOOP_DENIED_TOOLS = ['mcp__owenloop__reject'];
251
270
  const OWENLOOP_CONTROL_TOOLS = new Set([
@@ -264,6 +264,13 @@ function isPlainMap(v) {
264
264
  * keeps this list a complete statement of what the child needs.
265
265
  */
266
266
  const MOUNT_ENV_KEEP = ['HOME', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME'];
267
+ /**
268
+ * `OWENLOOP_CONFIG_DIR` rides the `OWENLOOP_*` allowlist below rather than this
269
+ * list, but it belongs to the same job: without it a mount whose parent scoped
270
+ * owenloop's config with `OWENLOOP_CONFIG_DIR` would fall back to
271
+ * `XDG_CONFIG_HOME` and read a DIFFERENT settings file than the shift that
272
+ * spawned it.
273
+ */
267
274
  /**
268
275
  * The environment for the owenloop mount, forwarded from THIS process.
269
276
  *
@@ -138,9 +138,28 @@ export interface StepPermissions {
138
138
  * - `full-access` — nothing is gated. The harness never consults a human, and
139
139
  * a failed action is simply reported back to the model.
140
140
  *
141
- * `auto-safe` is NOT a milder `full-access`: it can still stop and ask. A
142
- * headless step that must not stall wants `full-access`, and the two exist
143
- * separately so that choice is stated rather than inferred.
141
+ * `auto-safe` is NOT a milder `full-access`: the position it names still has a
142
+ * human exception path. A headless step that must not stall wants
143
+ * `full-access`, and the two exist separately so that choice is stated rather
144
+ * than inferred.
145
+ *
146
+ * WHAT `auto-safe` COSTS YOU TODAY, MEASURED. The three positions above
147
+ * describe the vocabulary, not a guarantee about how far any given classifier
148
+ * actually goes before it consults someone. On one shipped adapter the
149
+ * classifier was probed with five actions — among them a recursive delete on an
150
+ * absolute path outside the session working directory, an outbound network
151
+ * request, and a read of a file outside that directory — and it consulted the
152
+ * host on none of them and reported no auto-denial for any of them; four ran.
153
+ * On the other, the position that maps to `auto-safe` keys its judgment on
154
+ * filesystem access being restricted, so a step that also declares
155
+ * `filesystem: unrestricted` moves it close to `full-access` as well.
156
+ *
157
+ * The practical consequence for a definition author: choosing `auto-safe`
158
+ * because you want a person consulted on the dangerous cases may get you
159
+ * neither the prompt nor a record that one was skipped. Choose `ask` when a
160
+ * human decision genuinely has to happen, and `full-access` when it genuinely
161
+ * must not. Treat `auto-safe` as the classifier's own judgment with no
162
+ * guaranteed appeal, not as a supervised `full-access`.
144
163
  *
145
164
  * `ask` and `auto-safe` are meaningful only where something can answer a
146
165
  * prompt. In a Shift-dispatched run nothing can, so a prompt is a stall: the
@@ -24,9 +24,28 @@
24
24
  * - `full-access` — nothing is gated. The harness never consults a human, and
25
25
  * a failed action is simply reported back to the model.
26
26
  *
27
- * `auto-safe` is NOT a milder `full-access`: it can still stop and ask. A
28
- * headless step that must not stall wants `full-access`, and the two exist
29
- * separately so that choice is stated rather than inferred.
27
+ * `auto-safe` is NOT a milder `full-access`: the position it names still has a
28
+ * human exception path. A headless step that must not stall wants
29
+ * `full-access`, and the two exist separately so that choice is stated rather
30
+ * than inferred.
31
+ *
32
+ * WHAT `auto-safe` COSTS YOU TODAY, MEASURED. The three positions above
33
+ * describe the vocabulary, not a guarantee about how far any given classifier
34
+ * actually goes before it consults someone. On one shipped adapter the
35
+ * classifier was probed with five actions — among them a recursive delete on an
36
+ * absolute path outside the session working directory, an outbound network
37
+ * request, and a read of a file outside that directory — and it consulted the
38
+ * host on none of them and reported no auto-denial for any of them; four ran.
39
+ * On the other, the position that maps to `auto-safe` keys its judgment on
40
+ * filesystem access being restricted, so a step that also declares
41
+ * `filesystem: unrestricted` moves it close to `full-access` as well.
42
+ *
43
+ * The practical consequence for a definition author: choosing `auto-safe`
44
+ * because you want a person consulted on the dangerous cases may get you
45
+ * neither the prompt nor a record that one was skipped. Choose `ask` when a
46
+ * human decision genuinely has to happen, and `full-access` when it genuinely
47
+ * must not. Treat `auto-safe` as the classifier's own judgment with no
48
+ * guaranteed appeal, not as a supervised `full-access`.
30
49
  *
31
50
  * `ask` and `auto-safe` are meaningful only where something can answer a
32
51
  * prompt. In a Shift-dispatched run nothing can, so a prompt is a stall: the
@@ -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
@@ -154,10 +173,18 @@ export interface SettingsInspection extends ValidatedSettings {
154
173
  exists: boolean;
155
174
  }
156
175
  /**
157
- * Resolve the settings file path from the caller's env:
158
- * `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is set and
159
- * non-empty, else `$HOME/.config/owenloop/settings.json`. Throws when neither
160
- * is available rather than guessing a home directory.
176
+ * Resolve the settings file path from the caller's env, through the one shared
177
+ * ladder in `src/config-dir.ts`: `$OWENLOOP_CONFIG_DIR/settings.json` when
178
+ * `OWENLOOP_CONFIG_DIR` is set and non-blank (it must be absolute), else
179
+ * `$XDG_CONFIG_HOME/owenloop/settings.json`, else
180
+ * `$HOME/.config/owenloop/settings.json`. Throws when no rung yields a value
181
+ * rather than guessing a home directory.
182
+ *
183
+ * `OWENLOOP_CONFIG_DIR` is the variable an operator running SEVERAL shifts on
184
+ * one machine should reach for. Setting `XDG_CONFIG_HOME` per shift also works,
185
+ * but a shift spreads its whole environment into every worker and every command
186
+ * step's child, so relocating `XDG_CONFIG_HOME` relocates the config of `gh`,
187
+ * `git`, `gcloud`, and everything else those steps shell out to.
161
188
  */
162
189
  export declare function settingsPath(env: Record<string, string | undefined>): string;
163
190
  /**
@@ -13,7 +13,8 @@
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
+ import { owenloopConfigDir } from "../../../../src/config-dir.js";
17
18
  import { validateCapabilityModels } from "../agent/capability-model.js";
18
19
  /** The known settings keys, in the order `owenloop work settings` prints them. */
19
20
  export const KNOWN_SETTINGS_KEYS = [
@@ -29,6 +30,7 @@ export const KNOWN_SETTINGS_KEYS = [
29
30
  'maxConcurrentAgents',
30
31
  'workRoot',
31
32
  'workRepo',
33
+ 'allowedWorkdirRoots',
32
34
  'capabilityModels',
33
35
  ];
34
36
  /**
@@ -42,19 +44,21 @@ export const KNOWN_SETTINGS_KEYS = [
42
44
  */
43
45
  export const RETIRED_IGNORED_KEYS = ['escalateAt', 'escalationExtensionKey'];
44
46
  /**
45
- * Resolve the settings file path from the caller's env:
46
- * `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is set and
47
- * non-empty, else `$HOME/.config/owenloop/settings.json`. Throws when neither
48
- * is available rather than guessing a home directory.
47
+ * Resolve the settings file path from the caller's env, through the one shared
48
+ * ladder in `src/config-dir.ts`: `$OWENLOOP_CONFIG_DIR/settings.json` when
49
+ * `OWENLOOP_CONFIG_DIR` is set and non-blank (it must be absolute), else
50
+ * `$XDG_CONFIG_HOME/owenloop/settings.json`, else
51
+ * `$HOME/.config/owenloop/settings.json`. Throws when no rung yields a value
52
+ * rather than guessing a home directory.
53
+ *
54
+ * `OWENLOOP_CONFIG_DIR` is the variable an operator running SEVERAL shifts on
55
+ * one machine should reach for. Setting `XDG_CONFIG_HOME` per shift also works,
56
+ * but a shift spreads its whole environment into every worker and every command
57
+ * step's child, so relocating `XDG_CONFIG_HOME` relocates the config of `gh`,
58
+ * `git`, `gcloud`, and everything else those steps shell out to.
49
59
  */
50
60
  export function settingsPath(env) {
51
- const xdg = env.XDG_CONFIG_HOME;
52
- if (xdg !== undefined && xdg.trim() !== '')
53
- return join(xdg, 'owenloop', 'settings.json');
54
- const home = env.HOME;
55
- if (home !== undefined && home.trim() !== '')
56
- return join(home, '.config', 'owenloop', 'settings.json');
57
- throw new Error('cannot locate a settings directory: set HOME or XDG_CONFIG_HOME');
61
+ return join(owenloopConfigDir(env), 'settings.json');
58
62
  }
59
63
  /**
60
64
  * Validate a parsed settings object. Checks the TYPE of every known key
@@ -111,6 +115,27 @@ export function validateSettings(raw, path) {
111
115
  `Depth now rides on the capability's modifier suffix, not on a tier rung.`);
112
116
  }
113
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
+ }
114
139
  if ('capabilityModels' in obj) {
115
140
  const v = obj['capabilityModels'];
116
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. */