owenloop 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +98 -25
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{add.d.ts → src/add.d.ts} +12 -40
  109. package/dist/{add.js → src/add.js} +11 -176
  110. package/dist/src/cli.d.ts +147 -0
  111. package/dist/{cli.js → src/cli.js} +1643 -353
  112. package/dist/src/credentials.d.ts +280 -0
  113. package/dist/src/credentials.js +697 -0
  114. package/dist/{defs.js → src/defs.js} +59 -36
  115. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  116. package/dist/{engine.js → src/engine.js} +29 -20
  117. package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
  118. package/dist/{hub.js → src/hub.js} +531 -1
  119. package/dist/{index.d.ts → src/index.d.ts} +3 -1
  120. package/dist/{index.js → src/index.js} +2 -1
  121. package/dist/src/lock.d.ts +80 -0
  122. package/dist/src/lock.js +217 -0
  123. package/dist/src/mcp/serve.d.ts +85 -0
  124. package/dist/src/mcp/serve.js +702 -0
  125. package/dist/src/mcp/server.d.ts +132 -0
  126. package/dist/src/mcp/server.js +327 -0
  127. package/dist/{model.d.ts → src/model.d.ts} +59 -4
  128. package/dist/{model.js → src/model.js} +149 -22
  129. package/dist/{types.d.ts → src/types.d.ts} +66 -24
  130. package/dist/{util.d.ts → src/util.d.ts} +25 -0
  131. package/dist/{util.js → src/util.js} +26 -0
  132. package/dist/src/work-settings.d.ts +57 -0
  133. package/dist/src/work-settings.js +84 -0
  134. package/docs/authoring.md +102 -53
  135. package/docs/cli.md +883 -29
  136. package/docs/design.md +119 -45
  137. package/docs/embedding.md +39 -14
  138. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  139. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  140. package/examples/workflows/judges/gate-sharpness.md +39 -0
  141. package/examples/workflows/judges/security.md +34 -0
  142. package/package.json +17 -8
  143. package/dist/cli.d.ts +0 -83
  144. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  145. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  146. /package/dist/{factory.js → src/factory.js} +0 -0
  147. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  148. /package/dist/{paths.js → src/paths.js} +0 -0
  149. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  150. /package/dist/{schema.js → src/schema.js} +0 -0
  151. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  152. /package/dist/{store.js → src/store.js} +0 -0
  153. /package/dist/{types.js → src/types.js} +0 -0
  154. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  155. /package/dist/{untar.js → src/untar.js} +0 -0
@@ -0,0 +1,116 @@
1
+ /**
2
+ * Settings locate, load, and validate. This is the machine-level config
3
+ * surface for owenloop's roles, mirroring owenloop's convention (D12): a
4
+ * single JSON file at an XDG/HOME path supplying the fallback values every
5
+ * role resolves (CLI flag > env var > settings file > built-in default).
6
+ *
7
+ * C1 pinned where the file lives and how it loads; C2 added the first two
8
+ * fields; C6 fills in the full surface (dispatch cap + agents/state dirs),
9
+ * adds type validation with actionable errors, and surfaces unrecognized keys
10
+ * so typos are visible via `owenloop work settings`.
11
+ *
12
+ * HARD RULE: NO secrets ever live in this file. Credentials stay in owenloop's
13
+ * own store (the CredentialReader seam) — there is deliberately no token knob.
14
+ */
15
+ import { existsSync, readFileSync } from 'node:fs';
16
+ import { join } from 'node:path';
17
+ /** The known settings keys, in the order `owenloop work settings` prints them. */
18
+ export const KNOWN_SETTINGS_KEYS = [
19
+ 'hubOrigin',
20
+ 'cacheDir',
21
+ 'stateDir',
22
+ 'dispatchCap',
23
+ 'commandRouting',
24
+ 'maxConcurrentAgents',
25
+ 'workRoot',
26
+ 'workRepo',
27
+ ];
28
+ /**
29
+ * Resolve the settings file path from the caller's env:
30
+ * `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is set and
31
+ * non-empty, else `$HOME/.config/owenloop/settings.json`. Throws when neither
32
+ * is available rather than guessing a home directory.
33
+ */
34
+ export function settingsPath(env) {
35
+ const xdg = env.XDG_CONFIG_HOME;
36
+ if (xdg !== undefined && xdg.trim() !== '')
37
+ return join(xdg, 'owenloop', 'settings.json');
38
+ const home = env.HOME;
39
+ if (home !== undefined && home.trim() !== '')
40
+ return join(home, '.config', 'owenloop', 'settings.json');
41
+ throw new Error('cannot locate a settings directory: set HOME or XDG_CONFIG_HOME');
42
+ }
43
+ /**
44
+ * Validate a parsed settings object. Checks the TYPE of every known key
45
+ * (throwing an actionable error naming the key, expected type, received value,
46
+ * and file path on a mismatch) and collects any unrecognized keys. Unknown
47
+ * keys are retained on the returned `settings` (forward compatible) — only
48
+ * their names are reported, never fatal.
49
+ *
50
+ * `dispatchCap` must be a positive integer; `commandRouting` must be one of the
51
+ * two literals. Any other type on a known key is a hard error.
52
+ */
53
+ export function validateSettings(raw, path) {
54
+ if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
55
+ const got = Array.isArray(raw) ? 'array' : raw === null ? 'null' : typeof raw;
56
+ throw new Error(`invalid settings file at ${path}: expected a JSON object, got ${got}`);
57
+ }
58
+ const obj = raw;
59
+ const bad = (key, expected, value) => new Error(`invalid settings file at ${path}: '${key}' must be ${expected}, got ${JSON.stringify(value)}`);
60
+ for (const key of ['hubOrigin', 'cacheDir', 'stateDir', 'workRoot', 'workRepo']) {
61
+ if (key in obj && typeof obj[key] !== 'string')
62
+ throw bad(key, 'a string', obj[key]);
63
+ }
64
+ if ('dispatchCap' in obj) {
65
+ const v = obj['dispatchCap'];
66
+ if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) {
67
+ throw bad('dispatchCap', 'a positive integer', v);
68
+ }
69
+ }
70
+ if ('maxConcurrentAgents' in obj) {
71
+ const v = obj['maxConcurrentAgents'];
72
+ if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) {
73
+ throw bad('maxConcurrentAgents', 'a positive integer', v);
74
+ }
75
+ }
76
+ if ('commandRouting' in obj) {
77
+ const v = obj['commandRouting'];
78
+ if (v !== 'shift' && v !== 'manual')
79
+ throw bad('commandRouting', "'shift' or 'manual'", v);
80
+ }
81
+ const known = new Set(KNOWN_SETTINGS_KEYS);
82
+ const unrecognized = Object.keys(obj).filter((k) => !known.has(k));
83
+ return { settings: obj, unrecognized };
84
+ }
85
+ /**
86
+ * Inspect the settings file: resolve its path, whether it exists, and its
87
+ * validated contents. A missing file is not an error (`exists: false`,
88
+ * settings `{}`). Malformed JSON or an invalid known-key type throws a clear,
89
+ * path-named error. This is the single read+validate path that `loadSettings`
90
+ * and the `settings` print role share.
91
+ */
92
+ export function inspectSettings(env) {
93
+ const path = settingsPath(env);
94
+ if (!existsSync(path))
95
+ return { path, exists: false, settings: {}, unrecognized: [] };
96
+ const raw = readFileSync(path, 'utf8');
97
+ let parsed;
98
+ try {
99
+ parsed = JSON.parse(raw);
100
+ }
101
+ catch (err) {
102
+ const reason = err instanceof Error ? err.message : String(err);
103
+ throw new Error(`malformed settings file at ${path}: ${reason}`);
104
+ }
105
+ return { path, exists: true, ...validateSettings(parsed, path) };
106
+ }
107
+ /**
108
+ * Load, parse, and validate the settings file. A missing file yields `{}` (not
109
+ * an error). Malformed JSON or an invalid known-key type throws a clear error
110
+ * rather than silently defaulting — a silent default would mask config bugs.
111
+ * Every consumer that calls `loadSettings` gets known-key type validation for
112
+ * free; unknown keys pass through untouched.
113
+ */
114
+ export function loadSettings(env) {
115
+ return inspectSettings(env).settings;
116
+ }
@@ -0,0 +1,24 @@
1
+ import { type ShiftRequest, type ShiftResponse } from './protocol.ts';
2
+ export interface ShiftClientErrorOptions {
3
+ absent?: boolean;
4
+ code?: string;
5
+ }
6
+ export declare class ShiftClientError extends Error {
7
+ readonly absent: boolean;
8
+ readonly code: string | undefined;
9
+ constructor(message: string, opts?: ShiftClientErrorOptions);
10
+ }
11
+ export declare function shiftSocketPath(stateDir: string): string;
12
+ export declare function noDaemonMessage(socketPath: string): string;
13
+ /** Send one request and parse the daemon's one-line response. */
14
+ export declare function requestShift(socketPath: string, request: ShiftRequest): Promise<ShiftResponse>;
15
+ export interface ParsedNextArgs {
16
+ waitMs: number;
17
+ stateDir?: string;
18
+ error?: string;
19
+ }
20
+ export declare function parseNextArgs(args: string[]): ParsedNextArgs;
21
+ export declare function parseStateDirArgs(args: string[]): {
22
+ stateDir?: string;
23
+ error?: string;
24
+ };
@@ -0,0 +1,124 @@
1
+ /**
2
+ * Thin client for the local shift daemon's one-request-per-connection socket.
3
+ */
4
+ import { createConnection } from 'node:net';
5
+ import { join } from 'node:path';
6
+ import { DEFAULT_NEXT_WAIT_MS, MAX_REQUEST_LINE_BYTES, MAX_RESPONSE_LINE_BYTES, NO_DAEMON_SUFFIX, SHIFT_SOCKET_NAME, } from "./protocol.js";
7
+ export class ShiftClientError extends Error {
8
+ absent;
9
+ code;
10
+ constructor(message, opts = {}) {
11
+ super(message);
12
+ this.name = 'ShiftClientError';
13
+ this.absent = opts.absent ?? false;
14
+ this.code = opts.code;
15
+ }
16
+ }
17
+ export function shiftSocketPath(stateDir) {
18
+ return join(stateDir, SHIFT_SOCKET_NAME);
19
+ }
20
+ export function noDaemonMessage(socketPath) {
21
+ return `no shift daemon at ${socketPath}${NO_DAEMON_SUFFIX}`;
22
+ }
23
+ /** Send one request and parse the daemon's one-line response. */
24
+ export function requestShift(socketPath, request) {
25
+ return new Promise((resolve, reject) => {
26
+ const socket = createConnection(socketPath);
27
+ let settled = false;
28
+ let buffer = Buffer.alloc(0);
29
+ const fail = (error) => {
30
+ if (settled)
31
+ return;
32
+ settled = true;
33
+ socket.destroy();
34
+ reject(error);
35
+ };
36
+ socket.once('connect', () => {
37
+ const line = Buffer.from(`${JSON.stringify(request)}\n`, 'utf8');
38
+ if (line.length > MAX_REQUEST_LINE_BYTES) {
39
+ fail(new ShiftClientError('request is too large', { code: 'EMSGSIZE' }));
40
+ return;
41
+ }
42
+ socket.write(line);
43
+ });
44
+ socket.on('data', (chunk) => {
45
+ if (settled)
46
+ return;
47
+ buffer = Buffer.concat([buffer, chunk]);
48
+ if (buffer.length > MAX_RESPONSE_LINE_BYTES) {
49
+ fail(new ShiftClientError('daemon response is too large', { code: 'EMSGSIZE' }));
50
+ return;
51
+ }
52
+ const newline = buffer.indexOf(0x0a);
53
+ if (newline === -1)
54
+ return;
55
+ const raw = buffer.subarray(0, newline).toString('utf8');
56
+ settled = true;
57
+ socket.destroy();
58
+ try {
59
+ resolve(JSON.parse(raw));
60
+ }
61
+ catch {
62
+ reject(new ShiftClientError('daemon returned malformed JSON'));
63
+ }
64
+ });
65
+ socket.once('error', (error) => {
66
+ const code = error.code;
67
+ const absent = code === 'ENOENT' || code === 'ECONNREFUSED' || code === 'ENOTSOCK' || code === 'EPIPE';
68
+ fail(new ShiftClientError(absent ? noDaemonMessage(socketPath) : error.message, { absent, code }));
69
+ });
70
+ socket.once('close', () => {
71
+ if (!settled)
72
+ fail(new ShiftClientError('shift daemon closed the connection before replying'));
73
+ });
74
+ });
75
+ }
76
+ export function parseNextArgs(args) {
77
+ let waitMs = DEFAULT_NEXT_WAIT_MS;
78
+ let stateDir;
79
+ for (let i = 0; i < args.length; i++) {
80
+ const raw = args[i];
81
+ const name = raw.startsWith('--') && raw.includes('=') ? raw.slice(0, raw.indexOf('=')) : raw;
82
+ const readValue = () => {
83
+ const eq = raw.indexOf('=');
84
+ if (eq !== -1)
85
+ return raw.slice(eq + 1);
86
+ i++;
87
+ return args[i];
88
+ };
89
+ if (name === '--wait') {
90
+ const value = readValue();
91
+ if (value === undefined || value.trim() === '')
92
+ return { waitMs, error: 'missing value for --wait' };
93
+ const seconds = Number(value);
94
+ if (!Number.isFinite(seconds) || seconds < 0)
95
+ return { waitMs, error: `--wait must be a finite non-negative number of seconds, got '${value}'` };
96
+ waitMs = seconds * 1000;
97
+ }
98
+ else if (name === '--state-dir') {
99
+ const value = readValue();
100
+ if (value === undefined || value.trim() === '')
101
+ return { waitMs, error: 'missing value for --state-dir' };
102
+ stateDir = value;
103
+ }
104
+ else {
105
+ return { waitMs, error: `unknown option '${raw}'` };
106
+ }
107
+ }
108
+ return { waitMs, ...(stateDir !== undefined ? { stateDir } : {}) };
109
+ }
110
+ export function parseStateDirArgs(args) {
111
+ let stateDir;
112
+ for (let i = 0; i < args.length; i++) {
113
+ const raw = args[i];
114
+ const name = raw.startsWith('--') && raw.includes('=') ? raw.slice(0, raw.indexOf('=')) : raw;
115
+ if (name !== '--state-dir')
116
+ return { error: `unknown option '${raw}'` };
117
+ const eq = raw.indexOf('=');
118
+ const value = eq !== -1 ? raw.slice(eq + 1) : args[++i];
119
+ if (value === undefined || value.trim() === '')
120
+ return { error: 'missing value for --state-dir' };
121
+ stateDir = value;
122
+ }
123
+ return { ...(stateDir !== undefined ? { stateDir } : {}) };
124
+ }
@@ -0,0 +1,120 @@
1
+ import type { HubClient } from '../hub/client.ts';
2
+ import { type Liveness } from './state.ts';
3
+ import { sweepWorkDirs as sweepWorkDirsImpl } from '../agent/workdir.ts';
4
+ import type { Spawner } from './spawn.ts';
5
+ import type { ShiftEvent } from './protocol.ts';
6
+ export interface ShiftLoopOptions {
7
+ hub: HubClient;
8
+ spawner: Spawner;
9
+ /** Injected sleep — tests pass an instant/scriptable stub (no real timers). */
10
+ sleep: (ms: number) => Promise<void>;
11
+ /** Injected clock. */
12
+ now: () => number;
13
+ /** stdout sink (one line per call; newline appended). */
14
+ out: (line: string) => void;
15
+ /** stderr sink (one line per call; newline appended). */
16
+ err: (line: string) => void;
17
+ /** Local dispatch/reap observations consumed by the shift socket wrapper. */
18
+ onEvent?: (event: ShiftEvent) => void;
19
+ cacheDir: string;
20
+ stateDir: string;
21
+ /** Max concurrent in-flight orders (exec + agent-run children). */
22
+ cap: number;
23
+ /** Serve crews this shift accepts (sent to presence + whats_next). INITIAL
24
+ * value only — live-mutable via the `ShiftLoop.setShift` (MCP `clock_in`). */
25
+ serveCrews: string[];
26
+ /** Shift name for presence. INITIAL value only — live-mutable via
27
+ * `ShiftLoop.setShift` (MCP `clock_in`). */
28
+ name: string;
29
+ /**
30
+ * W7: this Shift process incarnation's self-declared id (`shf_<uuid>`)
31
+ * and process start time — carried on presence pings (attribution/
32
+ * observability only, D8/INV-82) and carried into dispatched holders/orders
33
+ * so submissions can be traced back to the Shift that produced them.
34
+ * Regenerated every restart, never persisted (D1).
35
+ */
36
+ shiftId?: string;
37
+ startedAt?: number;
38
+ /** When set, poll only this instance; else inbox-mode across all servable. */
39
+ workflow?: string;
40
+ /** Machine-level command routing (raw — validated in routing.ts). */
41
+ commandRouting?: unknown;
42
+ pollIntervalMs: number;
43
+ presenceIntervalMs: number;
44
+ /**
45
+ * Max concurrent `agent-run` children (default 4). A SECOND budget, applied
46
+ * ON TOP OF `cap` — never a replacement for it. An agent turn is long and
47
+ * memory-heavy where a command is short, so the two cannot share one number.
48
+ */
49
+ maxConcurrentAgents?: number;
50
+ /**
51
+ * PHASE 4 — the root under which per-RUN agent work directories live
52
+ * (`<workRoot>/<workflow>/<run>/`). ABSENT DISABLES THE REAPER entirely: with
53
+ * no root there is no set of directories this shift can claim to own, and a
54
+ * remover with no ownership claim is exactly what must not exist.
55
+ */
56
+ workRoot?: string;
57
+ /** PHASE 4 — when set, work dirs are git worktrees of this repo and are
58
+ * removed with `git worktree remove` rather than a plain `rm -rf`. */
59
+ workRepo?: string;
60
+ /** PHASE 4 — grace window before an idle work dir may be removed. Default
61
+ * `DEFAULT_WORK_DIR_TTL_MS` (1h), owned by `src/agent/workdir.ts`. */
62
+ workDirTtlMs?: number;
63
+ /** Bootstrap wake + exactly one sweep, then return (the e2e/demo hook). */
64
+ once?: boolean;
65
+ /** Injectable liveness probe (tests). */
66
+ isAlive?: Liveness;
67
+ /** PHASE 4 — injected in tests so the reaper can be exercised without a
68
+ * filesystem. Defaults to `sweepWorkDirs` from `src/agent/workdir.ts`. */
69
+ sweepWorkDirs?: typeof sweepWorkDirsImpl;
70
+ }
71
+ export interface ShiftLoop {
72
+ run(): Promise<number>;
73
+ stop(): void;
74
+ /**
75
+ * Run exactly one park iteration (presence → wake → sweep-if-changed →
76
+ * dispatch → reap) and return how many children it spawned. The shift daemon
77
+ * uses this seam for its loop core; the standing `run()` loop ignores the
78
+ * count. Cursor/presence state is held in the closure and persists across calls.
79
+ */
80
+ iterate(): Promise<number>;
81
+ /** Free capacity right now (cap − live in-flight). ≤ 0 ⇒ at capacity. */
82
+ freeCapacity(): number;
83
+ /** Live dispatch-cap used by status and next responses. */
84
+ getCap(): number;
85
+ /** Adjust the live dispatch cap for internal callers and tests. */
86
+ setCap(cap: number): void;
87
+ /** The shift's live identity: the presence name and the crew scope (`serve_crews`)
88
+ * the next ping and the next sweep will carry. Empty `serveCrews` means ALL of
89
+ * this identity's crews, never none. */
90
+ getShift(): {
91
+ name: string;
92
+ serveCrews: string[];
93
+ };
94
+ /** Set the live shift identity (the socket `clock_in` operation). A field left ABSENT is
95
+ * left unchanged; `serveCrews: []` explicitly means "all crews". Also makes the
96
+ * next presence ping due immediately, so the new identity reaches the hub on the
97
+ * next iterate() rather than up to presenceIntervalMs later. Returns the result. */
98
+ setShift(next: {
99
+ name?: string;
100
+ serveCrews?: string[];
101
+ }): {
102
+ name: string;
103
+ serveCrews: string[];
104
+ };
105
+ /** Record local client attendance and make the next presence ping due. */
106
+ noteAttended(at: number): void;
107
+ /** Return the last accepted attendance timestamp, if any. */
108
+ getAttendedAt(): number | undefined;
109
+ /**
110
+ * Run-ended reap (metering condition (a)): drop the in-flight record for
111
+ * `run` NOW, so its slot frees immediately instead of waiting for the next
112
+ * reconcile to notice the child exited. The shift's MCP `submit` tool calls
113
+ * an internal caller may use this when the hub reports a submit CLOSED the
114
+ * run — the one in-process end-of-run signal the shift sees. A run whose closing submit went through
115
+ * the child's own mount instead is not a problem: that child exits, and the
116
+ * next reconcile's pid probe frees the slot anyway.
117
+ */
118
+ noteRunEnded(run: string): void;
119
+ }
120
+ export declare function createShiftLoop(opts: ShiftLoopOptions): ShiftLoop;