owenloop 0.5.1 → 0.5.2

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 (81) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +9 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +21 -0
  4. package/dist/packages/work/src/agent/brief.js +42 -1
  5. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  6. package/dist/packages/work/src/agent/capability-model.js +148 -0
  7. package/dist/packages/work/src/agent/loop.d.ts +47 -4
  8. package/dist/packages/work/src/agent/loop.js +83 -53
  9. package/dist/packages/work/src/exec/loop.d.ts +17 -0
  10. package/dist/packages/work/src/exec/loop.js +195 -34
  11. package/dist/packages/work/src/exec/runner.js +15 -5
  12. package/dist/packages/work/src/harness/session-store.d.ts +3 -1
  13. package/dist/packages/work/src/harness/session-store.js +46 -22
  14. package/dist/packages/work/src/hold/mcp.js +9 -2
  15. package/dist/packages/work/src/hub/client.d.ts +7 -1
  16. package/dist/packages/work/src/hub/client.js +1 -0
  17. package/dist/packages/work/src/hub/types.d.ts +71 -3
  18. package/dist/packages/work/src/roles/agent-run.js +8 -9
  19. package/dist/packages/work/src/roles/hold.d.ts +2 -0
  20. package/dist/packages/work/src/roles/hold.js +39 -8
  21. package/dist/packages/work/src/roles/settings.js +18 -6
  22. package/dist/packages/work/src/roles/shift.js +13 -1
  23. package/dist/packages/work/src/settings/settings.d.ts +60 -7
  24. package/dist/packages/work/src/settings/settings.js +69 -22
  25. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  26. package/dist/packages/work/src/shift/logretention.js +407 -0
  27. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  28. package/dist/packages/work/src/shift/logsink.js +98 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +18 -1
  30. package/dist/packages/work/src/shift/loop.js +250 -12
  31. package/dist/packages/work/src/shift/protocol.d.ts +124 -1
  32. package/dist/packages/work/src/shift/protocol.js +14 -0
  33. package/dist/packages/work/src/shift/runtime.d.ts +14 -0
  34. package/dist/packages/work/src/shift/runtime.js +229 -6
  35. package/dist/packages/work/src/shift/server.d.ts +13 -0
  36. package/dist/packages/work/src/shift/server.js +61 -36
  37. package/dist/packages/work/src/shift/spawn.d.ts +78 -5
  38. package/dist/packages/work/src/shift/spawn.js +158 -12
  39. package/dist/packages/work/src/shift/state.d.ts +25 -0
  40. package/dist/packages/work/src/shift/state.js +29 -5
  41. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  42. package/dist/packages/work/src/shift/truncate.js +73 -0
  43. package/dist/packages/work/src/submit-proof.d.ts +31 -6
  44. package/dist/packages/work/src/submit-proof.js +33 -7
  45. package/dist/packages/work/src/submit-value.d.ts +48 -0
  46. package/dist/packages/work/src/submit-value.js +118 -0
  47. package/dist/packages/work/src/usage.d.ts +1 -1
  48. package/dist/packages/work/src/usage.js +11 -0
  49. package/dist/src/capabilities.d.ts +93 -0
  50. package/dist/src/capabilities.js +101 -0
  51. package/dist/src/cli.js +14 -9
  52. package/dist/src/crypto/records.d.ts +3 -0
  53. package/dist/src/crypto/records.js +11 -0
  54. package/dist/src/defs.js +192 -4
  55. package/dist/src/engine.d.ts +112 -3
  56. package/dist/src/engine.js +224 -28
  57. package/dist/src/hub.d.ts +27 -11
  58. package/dist/src/hub.js +24 -18
  59. package/dist/src/index.d.ts +3 -1
  60. package/dist/src/index.js +4 -1
  61. package/dist/src/mcp/serve.js +11 -4
  62. package/dist/src/model.d.ts +36 -0
  63. package/dist/src/model.js +46 -0
  64. package/dist/src/schemas/index.d.ts +17 -0
  65. package/dist/src/schemas/order.v1.schema.json +17 -3
  66. package/dist/src/store.d.ts +33 -1
  67. package/dist/src/store.js +57 -4
  68. package/dist/src/types.d.ts +102 -2
  69. package/docs/authoring.md +7 -0
  70. package/docs/bundles.md +103 -3
  71. package/docs/cli.md +127 -9
  72. package/docs/crypto.md +23 -7
  73. package/docs/shift-logs.md +642 -0
  74. package/docs/wire-contracts.md +34 -19
  75. package/package.json +1 -1
  76. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  77. package/plugins/claude-code/plugin/.mcp.json +1 -1
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
  81. package/dist/packages/work/src/agent/model-policy.js +0 -138
@@ -1,4 +1,4 @@
1
- import type { GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
1
+ import type { 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,12 @@ 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
+ * Plan §6: record what this shift resolved the order's compound capability to,
19
+ * BEFORE the harness launches. Idempotent on the hub by order id, so a
20
+ * re-dispatch no-ops rather than overwriting the first (pre-spend) record.
21
+ */
22
+ reportResolution(req: ReportResolutionRequest): Promise<ReportResolutionResponse>;
17
23
  whoami(): Promise<WhoamiResponse>;
18
24
  /** B5 cheap wake pre-check; `cursor` rides the query string only when set. */
19
25
  wake(cursor?: number): Promise<WakeResponse>;
@@ -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
+ reportResolution: (req) => post('report_resolution', req),
85
86
  whoami: () => get('whoami'),
86
87
  // Cursor is an opaque non-negative integer; omit it entirely to bootstrap
87
88
  // (the hub treats missing/invalid as a `changed: true` first sweep).
@@ -31,7 +31,13 @@ export interface WorkOrder {
31
31
  consumedFingerprint?: Record<string, number>;
32
32
  owes?: Array<{
33
33
  path: string;
34
- /** Claim-time committed version when a version-aware hub projects it. */
34
+ /**
35
+ * The TARGET version for this owed output when a version-aware hub
36
+ * projects it: the version the next successful producer commit lands
37
+ * (claim-time committed version + 1), NOT the currently-committed one.
38
+ * It is what a producer signs in its submission proof and what a
39
+ * downstream consumer checks that proof against.
40
+ */
35
41
  version?: number;
36
42
  judgmentRejects: number;
37
43
  schemaRejects: number;
@@ -176,6 +182,29 @@ export interface OrderPacket {
176
182
  outputs: string[];
177
183
  /** Opaque location hint — the worker's cwd when set. */
178
184
  workdir?: string;
185
+ /**
186
+ * THE COMPOSED CAPABILITIES this order was offered under, in the step's
187
+ * authored order — `['build:deep']` for a `build` step on a `deep` run. This
188
+ * is the key into the shift's `capabilityModels` map (see
189
+ * `src/agent/capability-model.ts`), and therefore what decides which model and
190
+ * effort run. Absent from a pre-modifier hub, which is why the worker treats
191
+ * an empty list as "nothing to resolve against" and refuses rather than
192
+ * guessing.
193
+ */
194
+ capabilities?: string[];
195
+ /** The run's routing modifier (`deep`), as the caller asked for at start_run. */
196
+ modifier?: string;
197
+ /**
198
+ * `true` when the engine re-offered this step at its escalation target instead
199
+ * of the run's own modifier. The worker does not act on it; it goes in the
200
+ * brief so the agent knows it is on the recovery path.
201
+ */
202
+ escalated?: boolean;
203
+ /**
204
+ * DEPRECATED, and no longer read by the agent loop. The def's authored tier
205
+ * name (`strong`) from the pre-modifier scheme. The hub still projects it for
206
+ * older workers; this one resolves from `capabilities` alone.
207
+ */
179
208
  model?: string;
180
209
  /** Worker kind; `'command'` for command orders, absent means agent. */
181
210
  worker?: string;
@@ -186,12 +215,18 @@ export interface OrderPacket {
186
215
  consumes: Record<string, unknown>;
187
216
  /** Claim-time consumed versions when a compatible hub preserves the map. */
188
217
  consumedFingerprint?: Record<string, number>;
189
- /** Target-protocol proof map; the deployed hub currently omits this field. */
218
+ /** Serialized submission proof for the consumed values, projected by a
219
+ * proof-aware hub. Absent from any hub that does not store submit proofs;
220
+ * consume-side verification then reports the artifact as unproven. */
190
221
  consumesProof?: string;
191
222
  /** The owed outputs and their reason threads. */
192
223
  owes: Array<{
193
224
  path: string;
194
- /** Claim-time committed version when a version-aware hub projects it. */
225
+ /** Target version for this output's next successful commit (claim-time
226
+ * committed version + 1), issued by a version-aware hub inside the claim
227
+ * transaction. This is what a producer signs in its submission proof.
228
+ * Absent from a hub that is not version-aware, which leaves the producer
229
+ * submit unsigned. */
195
230
  version?: number;
196
231
  judgmentRejects: number;
197
232
  schemaRejects: number;
@@ -223,6 +258,39 @@ export interface HeartbeatRequest {
223
258
  holder?: ContactHolder;
224
259
  }
225
260
  export type HeartbeatResponse = HubResponse;
261
+ /**
262
+ * Which settings row served the order, mirroring hub-core's `ResolutionMatch`.
263
+ * `refused` is a real, reportable outcome: the shift found no row and will not
264
+ * launch anything, and that is exactly the fact worth recording.
265
+ */
266
+ export type ResolutionMatch = 'exact' | 'bare' | 'refused';
267
+ export interface ResolutionPayload {
268
+ /** The settings key that matched (`build:deep`, or `build` on a bare match). */
269
+ capability: string;
270
+ match: ResolutionMatch;
271
+ /** Absent on `refused`, and on a command order, which selects no model. */
272
+ model?: string;
273
+ effort?: string;
274
+ harness?: string;
275
+ }
276
+ export interface ReportResolutionRequest {
277
+ workflow: string;
278
+ run: string;
279
+ resolution: ResolutionPayload;
280
+ }
281
+ /**
282
+ * The hub is idempotent by order id: `recorded: false` means a report for this
283
+ * run already stood and was left unchanged. `claimed` is the live lease state,
284
+ * disclosed and never enforced — a `false` here means the order is no longer
285
+ * this worker's to run.
286
+ */
287
+ export interface ReportResolutionResponse extends HubResponse {
288
+ workflow: string;
289
+ run: string;
290
+ step: string;
291
+ recorded: boolean;
292
+ claimed: boolean;
293
+ }
226
294
  export type ReleaseRequest = {
227
295
  session: string;
228
296
  } | {
@@ -87,7 +87,6 @@ import "../harnesses.js";
87
87
  import { hostname } from 'node:os';
88
88
  import { resolveCacheDir } from "../bundle/cache.js";
89
89
  import { createAgentRunLoop } from "../agent/loop.js";
90
- import { createModelPolicy } from "../agent/model-policy.js";
91
90
  import { createDefaultStoreInstructionResolver } from "../exec/instructions.js";
92
91
  import { createConsumedVerifier } from "../consumed-verifier.js";
93
92
  import { createHubClient } from "../hub/client.js";
@@ -199,6 +198,7 @@ export function exitCodeFor(outcome) {
199
198
  case 'no-template':
200
199
  case 'no-harness':
201
200
  case 'incompatible-harness-policy':
201
+ case 'unresolvable-capability':
202
202
  case 'unverified-consumed':
203
203
  case 'session-store-failed':
204
204
  case 'no-submit':
@@ -264,13 +264,12 @@ export async function run(args, deps = {}) {
264
264
  err(`owenloop work agent-run: ${errMsg(e)}`);
265
265
  return 1;
266
266
  }
267
- const modelPolicy = createModelPolicy({
268
- ...(settings.tierMap !== undefined ? { tierMap: settings.tierMap } : {}),
269
- ...(settings.escalateAt !== undefined ? { escalateAt: settings.escalateAt } : {}),
270
- ...(settings.escalationExtensionKey !== undefined
271
- ? { escalationExtensionKey: settings.escalationExtensionKey }
272
- : {}),
273
- });
267
+ // Passed through verbatim. `loadSettings` already validated every row (shape,
268
+ // effort on the ladder, effort accepted by a known model), so there is nothing
269
+ // left to normalize here — and nothing to default: an absent map means the
270
+ // loop refuses capability-bearing orders, which is the intended answer for a
271
+ // shift that never declared what serves what.
272
+ const capabilityModels = settings.capabilityModels;
274
273
  const origin = parsed.origin ?? settings.hubOrigin;
275
274
  if (origin === undefined || origin.trim() === '') {
276
275
  err('owenloop work agent-run: no hub origin — pass --origin <url> or set hubOrigin in settings');
@@ -498,7 +497,7 @@ export async function run(args, deps = {}) {
498
497
  cwd: workCwd,
499
498
  loadStep,
500
499
  resolveAdapter,
501
- modelPolicy,
500
+ ...(capabilityModels !== undefined ? { capabilityModels } : {}),
502
501
  consumedVerifier,
503
502
  appendSession: writeSession,
504
503
  nextAttempt: (workflow, run, step) => {
@@ -15,6 +15,8 @@ interface ParsedArgs {
15
15
  ignoreStdin: boolean;
16
16
  mcp: boolean;
17
17
  mcpTools?: HoldMcpToolName[];
18
+ /** Never hand the claim back — another process is the holder of record. */
19
+ neverRelease?: boolean;
18
20
  error?: string;
19
21
  }
20
22
  /** Parse `--flag value` and `--flag=value`; unknown flags are an error. */
@@ -29,6 +29,17 @@
29
29
  * closed at spawn (backgrounded/detached use), pass `--ignore-stdin` so hold
30
30
  * does not final-breath at birth.
31
31
  *
32
+ * HOLDER OF RECORD: by default this process IS the holder — its final breath
33
+ * releases the claim. `--never-release` says the opposite: some OTHER process
34
+ * holds the claim and this one is only along for the ride. `owenloop work
35
+ * agent-run` is the case that matters — it claims the order under its own
36
+ * `exec` lease loop and spawns `hold --mcp --never-release` purely to serve the
37
+ * agent's tool calls. There, a stop is a fact about this child (its stdin
38
+ * closed, it got a signal), never a fact about the order, so releasing would
39
+ * strip a live agent of the claim it is still working under. With
40
+ * `--never-release` every stop path skips the release and the loop settles as
41
+ * `stopped`; the holder of record decides the order's fate.
42
+ *
32
43
  * Origin/credential resolution mirrors `shift`: origin `--origin` → settings;
33
44
  * the bearer comes from owenloop's store via `resolveBearer`, reading the
34
45
  * `agent:<account>` slot for `--as <account>` (default `default`, so a hand-run
@@ -88,6 +99,9 @@ export function parseArgs(args) {
88
99
  case '--mcp':
89
100
  parsed.mcp = true;
90
101
  break;
102
+ case '--never-release':
103
+ parsed.neverRelease = true;
104
+ break;
91
105
  case '--order':
92
106
  case '--workflow':
93
107
  case '--session':
@@ -278,12 +292,29 @@ export async function run(args, deps = {}) {
278
292
  const shiftId = resolveShiftId(parsed.shift, env);
279
293
  const holder = resolveHolder(parsed.session, env, { shiftId });
280
294
  const hub = deps.hub ?? createHubClient({ origin, getToken: async () => token });
295
+ // --never-release: this hold is NOT the holder of record. `owenloop work
296
+ // agent-run` already claimed the order with its own `exec` lease loop and
297
+ // spawned this process only to serve the MCP tool surface (see
298
+ // `agent/brief.ts` buildOwenloopMcp). Under that parent, a stop of ANY kind —
299
+ // stdin EOF, SIGINT, SIGTERM — is a transport or lifecycle event for THIS
300
+ // child, not evidence that the order is finished, so it must never call
301
+ // `release`. Doing so hands the claim back while the agent is still working:
302
+ // the hub marks the run unclaimed, the mount's terminal guard fast-fails every
303
+ // subsequent get_order/submit, the agent dies empty-handed, and the shift
304
+ // re-dispatches the same order to a fresh worker that repeats the whole cycle.
305
+ // Every stop path below therefore routes through `stopOpts`/`stopTarget`.
306
+ const stopOpts = parsed.neverRelease === true ? { release: false } : undefined;
307
+ const stopTarget = (l) => ({
308
+ stop: (reason) => l.stop(reason, stopOpts),
309
+ });
281
310
  // --mcp: run the born-bound work-holder as a stdio MCP server. The default
282
311
  // registers get_order/submit/reject; --mcp-tools selects an exact positive
283
312
  // subset. The lease loop stays warm underneath. stdout is the JSON-RPC
284
313
  // channel, so every diagnostic (and the loop's own lines) goes to stderr;
285
- // stdin is the transport, and its EOF (the session died) fires the final
286
- // breath.
314
+ // stdin is the transport, and its EOF ends the mount. Whether that EOF also
315
+ // releases the claim depends on `--never-release` (see stopOpts above): a
316
+ // human-launched `hold --mcp` is the holder of record and releases; the
317
+ // `agent-run` child is not and does not.
287
318
  if (parsed.mcp) {
288
319
  const mount = createHoldMcp({
289
320
  hub,
@@ -310,9 +341,9 @@ export async function run(args, deps = {}) {
310
341
  write: (msg) => void process.stdout.write(`${JSON.stringify(msg)}\n`),
311
342
  err,
312
343
  });
313
- installSignalHandlers(mount.loop, deps.signalHost ?? process, err, {
344
+ installSignalHandlers(stopTarget(mount.loop), deps.signalHost ?? process, err, {
314
345
  role: 'hold',
315
- drainNote: 'final breath',
346
+ drainNote: parsed.neverRelease === true ? 'stopping (claim stays with the holder of record)' : 'final breath',
316
347
  stopReason: 'signal',
317
348
  });
318
349
  // The MCP server must keep answering until the TRANSPORT ends, not until
@@ -327,7 +358,7 @@ export async function run(args, deps = {}) {
327
358
  const stdin = (deps.stdin ?? process.stdin);
328
359
  const eof = new Promise((resolve) => {
329
360
  pumpStdin(stdin, server, () => {
330
- mount.loop.stop('stdin-eof');
361
+ mount.loop.stop('stdin-eof', stopOpts);
331
362
  resolve();
332
363
  });
333
364
  });
@@ -350,13 +381,13 @@ export async function run(args, deps = {}) {
350
381
  ...(parsed.jumpToleranceMs !== undefined ? { jumpToleranceMs: parsed.jumpToleranceMs } : {}),
351
382
  holder,
352
383
  });
353
- installSignalHandlers(loop, deps.signalHost ?? process, err, {
384
+ installSignalHandlers(stopTarget(loop), deps.signalHost ?? process, err, {
354
385
  role: 'hold',
355
- drainNote: 'final breath',
386
+ drainNote: parsed.neverRelease === true ? 'stopping (claim stays with the holder of record)' : 'final breath',
356
387
  stopReason: 'signal',
357
388
  });
358
389
  if (!parsed.ignoreStdin) {
359
- watchStdinEof(deps.stdin ?? process.stdin, () => loop.stop('stdin-eof'));
390
+ watchStdinEof(deps.stdin ?? process.stdin, () => loop.stop('stdin-eof', stopOpts));
360
391
  }
361
392
  const outcome = await loop.run();
362
393
  return exitCodeFor(outcome);
@@ -12,16 +12,19 @@
12
12
  * the file is malformed JSON or a known key has the wrong type · 2 on stray
13
13
  * args (there are no options in v1).
14
14
  */
15
- import { DEFAULT_TIER_MAP } from "../agent/model-policy.js";
16
15
  import { inspectSettings, KNOWN_SETTINGS_KEYS } from "../settings/settings.js";
17
- /** Built-in defaults shown for knobs absent from the file (else `unset`). */
16
+ /**
17
+ * Built-in defaults shown for knobs absent from the file (else `unset`).
18
+ *
19
+ * `capabilityModels` is deliberately absent: it HAS no built-in default. A shift
20
+ * with no row for an order's capability refuses that order rather than falling
21
+ * back to some default model, so printing a default here would describe
22
+ * behaviour that does not exist.
23
+ */
18
24
  const DEFAULT_NOTE = {
19
25
  dispatchCap: '3',
20
26
  commandRouting: 'shift',
21
27
  defPolicy: 'warn',
22
- tierMap: JSON.stringify(DEFAULT_TIER_MAP),
23
- escalateAt: '3',
24
- escalationExtensionKey: 'delivery',
25
28
  };
26
29
  function errMsg(err) {
27
30
  return err instanceof Error ? err.message : String(err);
@@ -43,7 +46,7 @@ export async function run(args, deps = {}) {
43
46
  err(`owenloop work settings: ${errMsg(e)}`);
44
47
  return 1;
45
48
  }
46
- const { path, exists, settings, unrecognized } = inspection;
49
+ const { path, exists, settings, unrecognized, warnings } = inspection;
47
50
  out(`settings file: ${path}`);
48
51
  out(`exists: ${exists ? 'yes' : 'no'}`);
49
52
  out('');
@@ -63,6 +66,15 @@ export async function run(args, deps = {}) {
63
66
  out('');
64
67
  out(`unrecognized keys (ignored — likely typos): ${unrecognized.join(', ')}`);
65
68
  }
69
+ // Warnings are keys owenloop still recognizes but no longer acts on. They do
70
+ // not fail the load and so do not change the exit code; a shift that starts on
71
+ // this file starts fine. They print because the alternative is the operator
72
+ // continuing to believe a dead knob does something.
73
+ if (warnings.length > 0) {
74
+ out('');
75
+ for (const warning of warnings)
76
+ out(`warning: ${warning}`);
77
+ }
66
78
  return 0;
67
79
  }
68
80
  /** Render a settings value for display: strings bare, everything else JSON. */
@@ -14,6 +14,7 @@ function usage() {
14
14
  process.stderr.write('usage: owenloop shift start <crew...> [--all] [--origin <url>] [--as <account>] [--name <n>]\n' +
15
15
  ' [--cap <n>] [--max-agents <n>] [--poll-interval <ms>] [--once]\n' +
16
16
  ' [--cache-dir <p>] [--state-dir <p>]\n' +
17
+ ' [--log-dir <p>] [--log-max-age <ms>]\n' +
17
18
  ' owenloop shift next [--wait <seconds>] [--state-dir <p>]\n' +
18
19
  ' owenloop shift status [--state-dir <p>]\n' +
19
20
  ' owenloop shift end [--state-dir <p>]\n');
@@ -27,7 +28,10 @@ function intValue(raw, flag) {
27
28
  }
28
29
  function parseStartArgs(args) {
29
30
  const parsed = { crews: [] };
30
- const valueFlags = new Set(['--origin', '--as', '--name', '--cap', '--max-agents', '--poll-interval', '--cache-dir', '--state-dir']);
31
+ const valueFlags = new Set([
32
+ '--origin', '--as', '--name', '--cap', '--max-agents', '--poll-interval',
33
+ '--cache-dir', '--state-dir', '--log-dir', '--log-max-age',
34
+ ]);
31
35
  for (let i = 0; i < args.length; i++) {
32
36
  const raw = args[i];
33
37
  const name = raw.startsWith('--') && raw.includes('=') ? raw.slice(0, raw.indexOf('=')) : raw;
@@ -57,6 +61,14 @@ function parseStartArgs(args) {
57
61
  parsed.cacheDir = value;
58
62
  else if (name === '--state-dir')
59
63
  parsed.stateDir = value;
64
+ else if (name === '--log-dir')
65
+ parsed.logDir = value;
66
+ else if (name === '--log-max-age') {
67
+ const n = intValue(value, '--log-max-age');
68
+ if (typeof n !== 'number')
69
+ return { crews: parsed.crews, error: n };
70
+ parsed.logMaxAgeMs = n;
71
+ }
60
72
  else if (name === '--cap') {
61
73
  const n = intValue(value, '--cap');
62
74
  if (typeof n !== 'number')
@@ -1,3 +1,4 @@
1
+ import { type CapabilityModelRow } from '../agent/capability-model.ts';
1
2
  /**
2
3
  * The settings surface — every knob optional, a missing file loading as `{}`.
3
4
  * Each field is the lowest-precedence fallback for a role option (a CLI flag
@@ -10,6 +11,10 @@
10
11
  * (below `OWENLOOP_STATE_DIR`).
11
12
  * - `dispatchCap` — shift max in-flight exec children; below `--cap`,
12
13
  * above the built-in default of 3. A positive integer.
14
+ * - `shiftLogDir` — where `shift.log` and `<run>.log` are written; below
15
+ * `--log-dir` and `OWENLOOP_SHIFT_LOG_DIR`, above the state dir.
16
+ * - `shiftLogMaxAgeMs` — worker-log retention in ms; below `--log-max-age`
17
+ * and `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`, above the 14-day default.
13
18
  * - `commandRouting` — who runs `executor: 'command'` steps this machine sees.
14
19
  * - `defPolicy` — local publication trust policy (`warn` by default).
15
20
  */
@@ -22,6 +27,24 @@ export interface Settings {
22
27
  stateDir?: string;
23
28
  /** Shift dispatch cap (positive integer); fallback below `--cap`, default 3. */
24
29
  dispatchCap?: number;
30
+ /**
31
+ * Directory holding the shift's own `shift.log` and each worker's `<run>.log`.
32
+ * Fallback below `--log-dir` and `OWENLOOP_SHIFT_LOG_DIR`; defaults to the
33
+ * resolved `stateDir`, which puts `<run>.log` beside its `<run>.json`.
34
+ */
35
+ shiftLogDir?: string;
36
+ /**
37
+ * How long a worker's `<run>.log` is kept, in milliseconds. Fallback below
38
+ * `--log-max-age` and `OWENLOOP_SHIFT_LOG_MAX_AGE_MS`; defaults to 14 days.
39
+ *
40
+ * A NON-NEGATIVE integer, unlike `dispatchCap`, which must be positive: `0`
41
+ * is meaningful here and means "reap every worker log whose run has
42
+ * completed, at the next shift startup".
43
+ *
44
+ * Applies ONLY to per-worker `<run>.log` files. `shift.log` is never reaped
45
+ * and never rotated — see `docs/shift-logs.md`.
46
+ */
47
+ shiftLogMaxAgeMs?: number;
25
48
  /**
26
49
  * Who runs `executor: 'command'` steps this machine sees: `'shift'` (default)
27
50
  * lets the shift auto-dispatch them; `'manual'` leaves them for a human/
@@ -76,15 +99,31 @@ export interface Settings {
76
99
  * of the MACHINE running the shift, not of the workflow.
77
100
  */
78
101
  workRepo?: string;
79
- /** Quality-tier to concrete model mapping; merged over the built-in map. */
80
- tierMap?: Record<string, string>;
81
- /** Reject count at which the default retry policy escalates. */
82
- escalateAt?: number;
83
- /** Extension namespace containing an authored escalation object. */
84
- escalationExtensionKey?: string;
102
+ /**
103
+ * How THIS machine serves each capability: a flat map from capability to
104
+ * `{model, effort}`, keyed by the composed capability (`wise:deep`) or by the
105
+ * bare name (`wise`). See `src/agent/capability-model.ts` for the lookup rule
106
+ * and for why this replaced `tierMap`/`tierProfiles` outright.
107
+ *
108
+ * Carry a bare row per capability the shift's crews serve. The bare row is
109
+ * what makes a hub name-match fallback order resolvable — the hub can stamp
110
+ * `wise:deep` on an order claimed by a crew bound only to `wise:standard`,
111
+ * and that shift has no `wise:deep` row by construction.
112
+ */
113
+ capabilityModels?: Record<string, CapabilityModelRow>;
85
114
  }
86
115
  /** The known settings keys, in the order `owenloop work settings` prints them. */
87
- export declare const KNOWN_SETTINGS_KEYS: readonly ["hubOrigin", "cacheDir", "stateDir", "dispatchCap", "commandRouting", "defPolicy", "artifactPolicy", "maxConcurrentAgents", "workRoot", "workRepo", "tierMap", "escalateAt", "escalationExtensionKey"];
116
+ export declare const KNOWN_SETTINGS_KEYS: readonly ["hubOrigin", "cacheDir", "stateDir", "dispatchCap", "shiftLogDir", "shiftLogMaxAgeMs", "commandRouting", "defPolicy", "artifactPolicy", "maxConcurrentAgents", "workRoot", "workRepo", "capabilityModels"];
117
+ /**
118
+ * Keys owenloop still RECOGNIZES but no longer acts on. Each one produces a
119
+ * warning naming what replaced it, and is excluded from `unrecognized` so the
120
+ * same key is not also reported as a likely typo.
121
+ *
122
+ * Distinct from `tierMap`/`tierProfiles`, which are a hard error: ignoring
123
+ * those would leave the shift with no capability map and refuse every order,
124
+ * whereas ignoring these changes nothing about how a shift runs.
125
+ */
126
+ export declare const RETIRED_IGNORED_KEYS: readonly ["escalateAt", "escalationExtensionKey"];
88
127
  /**
89
128
  * A validated load: the typed `settings` (unknown keys retained for forward
90
129
  * compatibility — consumers ignore them), plus the list of keys that are NOT
@@ -94,6 +133,20 @@ export interface ValidatedSettings {
94
133
  settings: Settings;
95
134
  /** Keys present in the file that owenloop does not recognize. */
96
135
  unrecognized: string[];
136
+ /**
137
+ * Non-fatal findings from validation, in the order they were noticed.
138
+ *
139
+ * A SEPARATE CHANNEL FROM `unrecognized` because it answers a different
140
+ * question. `unrecognized` says "owenloop does not know this key at all,
141
+ * probably a typo"; a warning says "the key is known, but something about it
142
+ * is worth your attention" — today, only `RETIRED_IGNORED_KEYS`: a key
143
+ * owenloop still recognizes and no longer acts on.
144
+ *
145
+ * Callers decide what to do with these. `owenloop work settings` prints them;
146
+ * the shift prints them once at startup. Nothing here ever blocks a load —
147
+ * anything that should block throws instead.
148
+ */
149
+ warnings: string[];
97
150
  }
98
151
  /** The result of inspecting the settings file: where it is, whether it exists, and its validated contents. */
99
152
  export interface SettingsInspection extends ValidatedSettings {
@@ -14,22 +14,33 @@
14
14
  */
15
15
  import { existsSync, readFileSync } from 'node:fs';
16
16
  import { join } from 'node:path';
17
+ import { validateCapabilityModels } from "../agent/capability-model.js";
17
18
  /** The known settings keys, in the order `owenloop work settings` prints them. */
18
19
  export const KNOWN_SETTINGS_KEYS = [
19
20
  'hubOrigin',
20
21
  'cacheDir',
21
22
  'stateDir',
22
23
  'dispatchCap',
24
+ 'shiftLogDir',
25
+ 'shiftLogMaxAgeMs',
23
26
  'commandRouting',
24
27
  'defPolicy',
25
28
  'artifactPolicy',
26
29
  'maxConcurrentAgents',
27
30
  'workRoot',
28
31
  'workRepo',
29
- 'tierMap',
30
- 'escalateAt',
31
- 'escalationExtensionKey',
32
+ 'capabilityModels',
32
33
  ];
34
+ /**
35
+ * Keys owenloop still RECOGNIZES but no longer acts on. Each one produces a
36
+ * warning naming what replaced it, and is excluded from `unrecognized` so the
37
+ * same key is not also reported as a likely typo.
38
+ *
39
+ * Distinct from `tierMap`/`tierProfiles`, which are a hard error: ignoring
40
+ * those would leave the shift with no capability map and refuse every order,
41
+ * whereas ignoring these changes nothing about how a shift runs.
42
+ */
43
+ export const RETIRED_IGNORED_KEYS = ['escalateAt', 'escalationExtensionKey'];
33
44
  /**
34
45
  * Resolve the settings file path from the caller's env:
35
46
  * `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is set and
@@ -61,11 +72,20 @@ export function validateSettings(raw, path) {
61
72
  throw new Error(`invalid settings file at ${path}: expected a JSON object, got ${got}`);
62
73
  }
63
74
  const obj = raw;
75
+ const warnings = [];
64
76
  const bad = (key, expected, value) => new Error(`invalid settings file at ${path}: '${key}' must be ${expected}, got ${JSON.stringify(value)}`);
65
- for (const key of ['hubOrigin', 'cacheDir', 'stateDir', 'workRoot', 'workRepo']) {
77
+ for (const key of ['hubOrigin', 'cacheDir', 'stateDir', 'shiftLogDir', 'workRoot', 'workRepo']) {
66
78
  if (key in obj && typeof obj[key] !== 'string')
67
79
  throw bad(key, 'a string', obj[key]);
68
80
  }
81
+ if ('shiftLogMaxAgeMs' in obj) {
82
+ // NON-NEGATIVE, not positive: 0 means "reap every completed run's log at the
83
+ // next startup", which is a legitimate setting on a disk-constrained host.
84
+ const v = obj['shiftLogMaxAgeMs'];
85
+ if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
86
+ throw bad('shiftLogMaxAgeMs', 'a non-negative integer', v);
87
+ }
88
+ }
69
89
  if ('dispatchCap' in obj) {
70
90
  const v = obj['dispatchCap'];
71
91
  if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) {
@@ -78,26 +98,49 @@ export function validateSettings(raw, path) {
78
98
  throw bad('maxConcurrentAgents', 'a positive integer', v);
79
99
  }
80
100
  }
81
- if ('tierMap' in obj) {
82
- const v = obj['tierMap'];
101
+ // RETIRED KEYS ARE A HARD ERROR, NOT AN IGNORED ONE. A file still naming
102
+ // `tierMap` or `tierProfiles` describes a routing scheme that no longer
103
+ // exists; passing it over as an unrecognized key would start the shift with
104
+ // NO capability map at all, and every agent order would then be refused at
105
+ // dispatch with a message about capabilities the operator never wrote.
106
+ for (const retired of ['tierMap', 'tierProfiles']) {
107
+ if (retired in obj) {
108
+ throw new Error(`invalid settings file at ${path}: '${retired}' was removed — tiers are replaced by ` +
109
+ `'capabilityModels', a flat map from capability to { model, effort } ` +
110
+ `(e.g. {"capabilityModels": {"wise:deep": {"model": "<model-id>", "effort": "xhigh"}}}). ` +
111
+ `Depth now rides on the capability's modifier suffix, not on a tier rung.`);
112
+ }
113
+ }
114
+ if ('capabilityModels' in obj) {
115
+ const v = obj['capabilityModels'];
83
116
  if (typeof v !== 'object' || v === null || Array.isArray(v)) {
84
- throw bad('tierMap', 'an object whose values are non-empty strings', v);
117
+ throw bad('capabilityModels', 'an object of { model, effort } per capability', v);
85
118
  }
86
- for (const value of Object.values(v)) {
87
- if (typeof value !== 'string' || value.trim() === '')
88
- throw bad('tierMap', 'an object whose values are non-empty strings', v);
119
+ // Row shape and effort validity are checked at LOAD, not at resolution: a
120
+ // shift whose map is wrong should fail when it starts, not on the first
121
+ // order that happens to land on the broken row, hours later.
122
+ try {
123
+ validateCapabilityModels(v);
89
124
  }
90
- }
91
- if ('escalateAt' in obj) {
92
- const v = obj['escalateAt'];
93
- if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) {
94
- throw bad('escalateAt', 'a positive integer', v);
125
+ catch (e) {
126
+ throw new Error(`invalid settings file at ${path}: ${e instanceof Error ? e.message : String(e)}`);
95
127
  }
96
128
  }
97
- if ('escalationExtensionKey' in obj) {
98
- const v = obj['escalationExtensionKey'];
99
- if (typeof v !== 'string' || v.trim() === '') {
100
- throw bad('escalationExtensionKey', 'a non-empty string', v);
129
+ // RETIRED, BUT ONLY A WARNING — a different case from `tierMap` above, and the
130
+ // difference is what happens if the key is silently ignored.
131
+ //
132
+ // These two configured the WORKER-LOCAL escalation that bumped an order's
133
+ // model after N judgment rejections. Escalation is now entirely the engine's:
134
+ // it re-offers the step composed with the def's `escalation.modifier`, and the
135
+ // shift resolves that new compound like any other. So a file still carrying
136
+ // these describes a mechanism that no longer runs — but escalation itself
137
+ // still happens, correctly, without them. Ignoring them changes no behavior;
138
+ // it only leaves the operator believing a knob does something. A warning says
139
+ // exactly that, and does not stop a shift from starting.
140
+ for (const retired of RETIRED_IGNORED_KEYS) {
141
+ if (retired in obj) {
142
+ warnings.push(`'${retired}' no longer does anything and is ignored — retry escalation moved into the engine, ` +
143
+ `which re-offers a rejected step at the def's 'escalation.modifier'. Remove the key.`);
101
144
  }
102
145
  }
103
146
  if ('commandRouting' in obj) {
@@ -117,9 +160,13 @@ export function validateSettings(raw, path) {
117
160
  throw bad('artifactPolicy', "'enforce', 'warn', or 'off'", v);
118
161
  }
119
162
  }
120
- const known = new Set(KNOWN_SETTINGS_KEYS);
163
+ // The retired-but-warned keys count as KNOWN for this purpose. They are not
164
+ // typos — owenloop recognizes them perfectly well and has already said, in a
165
+ // warning, that they no longer take effect. Listing them again under
166
+ // "unrecognized keys (ignored — likely typos)" would contradict that.
167
+ const known = new Set([...KNOWN_SETTINGS_KEYS, ...RETIRED_IGNORED_KEYS]);
121
168
  const unrecognized = Object.keys(obj).filter((k) => !known.has(k));
122
- return { settings: obj, unrecognized };
169
+ return { settings: obj, unrecognized, warnings };
123
170
  }
124
171
  /**
125
172
  * Inspect the settings file: resolve its path, whether it exists, and its
@@ -131,7 +178,7 @@ export function validateSettings(raw, path) {
131
178
  export function inspectSettings(env) {
132
179
  const path = settingsPath(env);
133
180
  if (!existsSync(path))
134
- return { path, exists: false, settings: {}, unrecognized: [] };
181
+ return { path, exists: false, settings: {}, unrecognized: [], warnings: [] };
135
182
  const raw = readFileSync(path, 'utf8');
136
183
  let parsed;
137
184
  try {