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,344 @@
1
+ /**
2
+ * A newline-delimited JSON-RPC 2.0 client over a child process's stdio.
3
+ *
4
+ * Attribution: adapted from the kanna project's app-server client
5
+ * (`github.com/jakemor/kanna`), MIT-style license, Copyright (c) 2025 Jake Mor.
6
+ * Knowledge was ported, not source; the fuller license note (kanna's grant
7
+ * carve-out, and why it does not bind typicalday) lives in the adapter module
8
+ * that names the vendor, because this file may not.
9
+ *
10
+ * VENDOR-NEUTRAL BY MANDATE. `test/harness-isolation.test.ts` greps a vendor
11
+ * pattern over the FULL TEXT — code and comments alike — of every `.ts` under
12
+ * `src/harness/`, and allowlists only the per-harness adapter modules by exact
13
+ * path. This file is NOT on that allowlist, so it may not name a provider, a
14
+ * provider's binary, a provider's env var, or a provider's own source files
15
+ * anywhere in it. Everything here is therefore described in protocol terms.
16
+ *
17
+ * WHY IT IS HAND-ROLLED. The repo keeps a deliberately small runtime dependency
18
+ * set, and the server this drives deviates from JSON-RPC 2.0 in a way that
19
+ * breaks strict libraries anyway (see `classifyFrame`): inbound frames carry no
20
+ * `jsonrpc` member at all.
21
+ *
22
+ * TWO LAYERS, ON PURPOSE:
23
+ * - `createRpcCore` — framing, correlation, timeouts, and dispatch over an
24
+ * injected `write` sink. No process, no streams, no timers you cannot
25
+ * control. This is the layer the framing/correlation unit tests drive, so a
26
+ * framing bug fails a test that never spawned anything.
27
+ * - `startStdioRpc` — spawns the child and wires the core to its stdio.
28
+ *
29
+ * Failure stance: total on the read path. A line that is not JSON, a response
30
+ * for an id nobody is waiting on, and a notification for an unknown method are
31
+ * all REPORTED (through `onStderr`) and skipped — never thrown, because one
32
+ * stray byte on stdout must not kill a live session. Every request is
33
+ * independently timed out, because a server that silently drops an unknown
34
+ * method (which the server this was written for does) would otherwise leak the
35
+ * pending promise forever.
36
+ */
37
+ import { spawn } from 'node:child_process';
38
+ import { StringDecoder } from 'node:string_decoder';
39
+ /** A JSON-RPC `error` object, surfaced as a rejection from `request`. */
40
+ export class JsonRpcError extends Error {
41
+ code;
42
+ data;
43
+ constructor(code, message, data) {
44
+ super(message);
45
+ this.name = 'JsonRpcError';
46
+ this.code = code;
47
+ this.data = data;
48
+ }
49
+ }
50
+ const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
51
+ /** How long `dispose` waits after SIGTERM before escalating to SIGKILL. */
52
+ const KILL_GRACE_MS = 2_000;
53
+ /**
54
+ * Classify a decoded frame.
55
+ *
56
+ * DELIBERATELY DOES NOT LOOK AT `jsonrpc`. The server this client was written
57
+ * against omits the `jsonrpc` member from every inbound frame — responses
58
+ * arrive as `{id, result}`, errors as `{error, id}`, notifications as
59
+ * `{method, params, emittedAtMs}`. A validator that requires `jsonrpc === '2.0'`
60
+ * rejects 100% of real traffic, so classification keys on the presence of
61
+ * `id` / `method` / `result` / `error` only, in this order.
62
+ *
63
+ * Exported so a unit test can pin the rule directly.
64
+ */
65
+ export function classifyFrame(frame) {
66
+ const hasId = 'id' in frame && frame.id !== undefined && frame.id !== null;
67
+ if (hasId && ('result' in frame || 'error' in frame))
68
+ return 'response';
69
+ if (hasId && typeof frame.method === 'string')
70
+ return 'server-request';
71
+ if (typeof frame.method === 'string')
72
+ return 'notification';
73
+ return 'unknown';
74
+ }
75
+ /**
76
+ * A line-oriented, UTF-8-safe reader over a byte stream.
77
+ *
78
+ * `StringDecoder` is what makes a multi-byte character split across two chunks
79
+ * survive: decoding each chunk independently emits replacement characters at
80
+ * the seam. Exported so the framing tests can drive it directly.
81
+ */
82
+ export function createLineReader(onLine) {
83
+ const decoder = new StringDecoder('utf8');
84
+ let buffer = '';
85
+ return (chunk) => {
86
+ buffer += typeof chunk === 'string' ? chunk : decoder.write(chunk);
87
+ let nl = buffer.indexOf('\n');
88
+ while (nl !== -1) {
89
+ const line = buffer.slice(0, nl);
90
+ buffer = buffer.slice(nl + 1);
91
+ // `noUncheckedIndexedAccess` is on; slicing avoids indexed reads entirely.
92
+ const trimmed = line.endsWith('\r') ? line.slice(0, -1) : line;
93
+ if (trimmed.trim() !== '')
94
+ onLine(trimmed);
95
+ nl = buffer.indexOf('\n');
96
+ }
97
+ };
98
+ }
99
+ /**
100
+ * The protocol engine: framing in, correlation and dispatch out, over an
101
+ * injected `write`. Knows nothing about processes.
102
+ */
103
+ export function createRpcCore(opts) {
104
+ const requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
105
+ const pending = new Map();
106
+ let nextId = 1;
107
+ function send(msg) {
108
+ opts.write(`${JSON.stringify(msg)}\n`);
109
+ }
110
+ function handleResponse(frame) {
111
+ const id = typeof frame.id === 'number' ? frame.id : Number(frame.id);
112
+ const p = pending.get(id);
113
+ if (p === undefined) {
114
+ // A LATE response for an id that already timed out (or was never ours)
115
+ // lands here. Reporting and dropping it is required — throwing would take
116
+ // down a healthy session over a message nobody is waiting for.
117
+ opts.onStderr(`[unmatched response] id=${String(frame.id)}`);
118
+ return;
119
+ }
120
+ clearTimeout(p.timer);
121
+ pending.delete(id);
122
+ if (frame.error !== undefined && frame.error !== null) {
123
+ p.reject(new JsonRpcError(frame.error.code, frame.error.message, frame.error.data));
124
+ return;
125
+ }
126
+ p.resolve(frame.result);
127
+ }
128
+ function handleServerRequest(frame) {
129
+ const id = frame.id;
130
+ const method = frame.method;
131
+ // ALWAYS exactly one reply. `void` the promise deliberately: the reply is
132
+ // written inside it, and there is no caller to await.
133
+ void (async () => {
134
+ try {
135
+ const result = await opts.onServerRequest(method, frame.params, id);
136
+ send({ jsonrpc: '2.0', id, result: result ?? {} });
137
+ }
138
+ catch (err) {
139
+ send({
140
+ jsonrpc: '2.0',
141
+ id,
142
+ error: { code: -32603, message: err instanceof Error ? err.message : String(err) },
143
+ });
144
+ }
145
+ })();
146
+ }
147
+ const onData = createLineReader((line) => {
148
+ let frame;
149
+ try {
150
+ frame = JSON.parse(line);
151
+ }
152
+ catch {
153
+ // A stray non-JSON line is a diagnostic, not a fatal error: report it and
154
+ // keep reading so the NEXT valid line still parses.
155
+ opts.onStderr(`[non-JSON stdout] ${line}`);
156
+ return;
157
+ }
158
+ if (typeof frame !== 'object' || frame === null) {
159
+ opts.onStderr(`[non-object frame] ${line}`);
160
+ return;
161
+ }
162
+ switch (classifyFrame(frame)) {
163
+ case 'response':
164
+ handleResponse(frame);
165
+ return;
166
+ case 'server-request':
167
+ handleServerRequest(frame);
168
+ return;
169
+ case 'notification':
170
+ opts.onNotification(frame.method, frame.params);
171
+ return;
172
+ case 'unknown':
173
+ opts.onStderr(`[unclassifiable frame] ${line}`);
174
+ return;
175
+ }
176
+ });
177
+ return {
178
+ onData,
179
+ pendingCount: () => pending.size,
180
+ rejectAll(err) {
181
+ for (const [, p] of pending) {
182
+ clearTimeout(p.timer);
183
+ p.reject(err);
184
+ }
185
+ pending.clear();
186
+ },
187
+ request(method, params, timeoutMs) {
188
+ const id = nextId++;
189
+ const budget = timeoutMs ?? requestTimeoutMs;
190
+ const startedAt = Date.now();
191
+ const p = new Promise((resolve, reject) => {
192
+ // MANDATORY (not defensive): this server answers a genuinely-absent
193
+ // method with NO frame at all, so correlation alone leaks the pending
194
+ // entry forever. `unref` so a still-pending request cannot hold the
195
+ // event loop — and therefore a test runner — open.
196
+ const timer = setTimeout(() => {
197
+ pending.delete(id);
198
+ reject(new Error(`request '${method}' timed out after ${Date.now() - startedAt}ms`));
199
+ }, budget);
200
+ timer.unref();
201
+ pending.set(id, {
202
+ method,
203
+ startedAt,
204
+ resolve: resolve,
205
+ reject,
206
+ timer,
207
+ });
208
+ });
209
+ send({ jsonrpc: '2.0', id, method, ...(params !== undefined ? { params } : {}) });
210
+ return p;
211
+ },
212
+ notify(method, params) {
213
+ send({ jsonrpc: '2.0', method, ...(params !== undefined ? { params } : {}) });
214
+ },
215
+ };
216
+ }
217
+ /** Spawn `command args` and speak newline-delimited JSON-RPC to its stdio. */
218
+ export function startStdioRpc(opts) {
219
+ // `detached: true` puts the child in its OWN process group, which is the only
220
+ // thing that makes `process.kill(-pid, ...)` able to reap the grandchildren
221
+ // the child spawns on its own.
222
+ //
223
+ // ENVIRONMENT: this transport does not decide it. With no `env` option the
224
+ // child inherits this process's environment untouched, which is the recorded
225
+ // decision for the adapter that uses this transport; with one, that value is
226
+ // the child's whole environment. Either way the policy lives in the caller.
227
+ const child = spawn(opts.command, opts.args, {
228
+ ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
229
+ ...(opts.env !== undefined ? { env: opts.env } : {}),
230
+ stdio: ['pipe', 'pipe', 'pipe'],
231
+ detached: true,
232
+ });
233
+ let disposed = false;
234
+ let exited = false;
235
+ let disposePromise;
236
+ const core = createRpcCore({
237
+ ...(opts.requestTimeoutMs !== undefined ? { requestTimeoutMs: opts.requestTimeoutMs } : {}),
238
+ write: (line) => {
239
+ if (child.stdin.destroyed || child.stdin.writableEnded)
240
+ return;
241
+ child.stdin.write(line);
242
+ },
243
+ onNotification: opts.onNotification,
244
+ onServerRequest: opts.onServerRequest,
245
+ onStderr: opts.onStderr,
246
+ });
247
+ child.stdout.on('data', core.onData);
248
+ child.stdout.on('error', (err) => opts.onStderr(`[stdout error] ${err.message}`));
249
+ const readStderr = createLineReader((line) => opts.onStderr(line));
250
+ child.stderr.on('data', readStderr);
251
+ child.stderr.on('error', (err) => opts.onStderr(`[stderr error] ${err.message}`));
252
+ child.stdin.on('error', (err) => opts.onStderr(`[stdin error] ${err.message}`));
253
+ child.on('error', (err) => {
254
+ opts.onStderr(`[spawn error] ${err.message}`);
255
+ core.rejectAll(err);
256
+ });
257
+ child.on('exit', (code, signal) => {
258
+ exited = true;
259
+ core.rejectAll(new Error(`process exited (code=${String(code)}, signal=${String(signal)})`));
260
+ opts.onExit(code, signal);
261
+ });
262
+ return {
263
+ get pid() {
264
+ return child.pid;
265
+ },
266
+ request(method, params, timeoutMs) {
267
+ if (disposed || exited) {
268
+ return Promise.reject(new Error(`cannot send '${method}': the client is no longer running`));
269
+ }
270
+ return core.request(method, params, timeoutMs);
271
+ },
272
+ notify(method, params) {
273
+ if (disposed || exited)
274
+ return;
275
+ core.notify(method, params);
276
+ },
277
+ dispose() {
278
+ // Idempotent: the second call returns the same promise the first made.
279
+ if (disposePromise !== undefined)
280
+ return disposePromise;
281
+ disposed = true;
282
+ core.rejectAll(new Error('client disposed'));
283
+ disposePromise = (async () => {
284
+ if (exited)
285
+ return;
286
+ const done = new Promise((resolve) => {
287
+ if (exited) {
288
+ resolve();
289
+ return;
290
+ }
291
+ child.once('exit', () => resolve());
292
+ });
293
+ try {
294
+ child.stdin.end();
295
+ }
296
+ catch {
297
+ // a closed pipe is not an error at teardown
298
+ }
299
+ killGroup(child.pid, 'SIGTERM', opts.onStderr);
300
+ await Promise.race([done, sleepUnref(KILL_GRACE_MS)]);
301
+ if (!exited) {
302
+ killGroup(child.pid, 'SIGKILL', opts.onStderr);
303
+ await Promise.race([done, sleepUnref(KILL_GRACE_MS)]);
304
+ }
305
+ })();
306
+ return disposePromise;
307
+ },
308
+ };
309
+ }
310
+ /** A timer that cannot by itself keep the event loop alive. */
311
+ function sleepUnref(ms) {
312
+ return new Promise((resolve) => {
313
+ const t = setTimeout(resolve, ms);
314
+ t.unref();
315
+ });
316
+ }
317
+ /**
318
+ * Signal the child's whole process group, falling back to the process itself.
319
+ *
320
+ * `ESRCH` ("no such process") means it is already gone, which is the success
321
+ * case at teardown, not a failure. `EPERM` can happen when the group is gone
322
+ * but the pid was recycled; both are reported and swallowed.
323
+ */
324
+ function killGroup(pid, signal, onStderr) {
325
+ if (pid === undefined)
326
+ return;
327
+ try {
328
+ process.kill(-pid, signal);
329
+ return;
330
+ }
331
+ catch (err) {
332
+ const code = err.code;
333
+ if (code !== 'ESRCH' && code !== 'EPERM')
334
+ onStderr(`[kill group ${signal}] ${String(err)}`);
335
+ }
336
+ try {
337
+ process.kill(pid, signal);
338
+ }
339
+ catch (err) {
340
+ const code = err.code;
341
+ if (code !== 'ESRCH')
342
+ onStderr(`[kill ${signal}] ${String(err)}`);
343
+ }
344
+ }
@@ -0,0 +1,62 @@
1
+ /**
2
+ * `normalizeStepPermissions` — the PURE translation from a step def's
3
+ * harness-specific `x.<bagKey>` bag into the harness-neutral `StepPermissions`
4
+ * that every adapter reads.
5
+ *
6
+ * The type itself lives in `./contract.ts` (both adapters read it as part of the
7
+ * contract surface); only the normalizing function lives here, so the
8
+ * dependency runs one way and there is no cycle.
9
+ *
10
+ * SHAPE DECISION — this takes the ALREADY-EXTRACTED bag, not the step. If it
11
+ * took the step it would have to know which bag key to reach for, and that key
12
+ * IS a harness vendor name — putting a vendor name in a non-adapter file and
13
+ * breaking the isolation rule this phase establishes. The CALLER extracts the
14
+ * bag (Phase 3's worker today, Phase 5's normalized prepare later). Do not
15
+ * "fix" this by passing the step plus a bagKey argument: same leak, one
16
+ * indirection later.
17
+ *
18
+ * Failure stance: TOTAL. It never throws, never mutates its input, and has no
19
+ * I/O. A malformed bag normalizes to `{ extensions: {} }`. Validation is not
20
+ * this function's job — normalization runs at dispatch time where throwing would
21
+ * kill a live order. Two other layers do the validating, and BOTH report rather
22
+ * than degrade: the def parser (`parseHarnessCarrier` in `src/bundle/fetch.ts`)
23
+ * throws on a carrier it cannot read at all — including a def still carrying the
24
+ * legacy pre-`x.harness` bag key (`LEGACY_BAG_KEY`, same file) — and `owenloop
25
+ * lint` errors on a bad FIELD inside a well-formed bag.
26
+ *
27
+ * Field rules are carried over from the legacy compile layer's `KNOWN_FIELDS` /
28
+ * `RESERVED_KEYS` / `isStringOrStringArray`; the live copies now sit in this
29
+ * directory's per-harness adapter module (grep them there — `src/adapters/` was
30
+ * deleted in Phase 5, and do not trust a line number). Six of the sixteen are
31
+ * harness-neutral and get lifted; two are reserved and are stripped; the other
32
+ * eight have no neutral meaning and land in `extensions`, along with every key
33
+ * the bag carries that the known list does not mention.
34
+ */
35
+ import type { StepPermissions } from './contract.ts';
36
+ /**
37
+ * Translate one step's bag into `StepPermissions`.
38
+ *
39
+ * `bag` is the already-extracted `x.<bagKey>` object; `undefined`, `null`, an
40
+ * array, or any non-object all normalize to `{ extensions: {} }` (plus the
41
+ * step's model, when it has one).
42
+ *
43
+ * MODEL PRECEDENCE: the step's FIRST-CLASS `model` field wins over a bag-level
44
+ * `model`, carried over verbatim from the legacy frontmatter builder's
45
+ * `if (step.model !== undefined) fm['model'] = step.model`. That is today's live
46
+ * behavior and its meaning must not change — getting it backwards would silently
47
+ * alter which model live steps run under once Phase 5 routes prepare through
48
+ * this function. Note the precedence is decided on PRESENCE (a defined step
49
+ * model shadows the bag), and only then is the winner dropped if it is not a
50
+ * non-empty string.
51
+ *
52
+ * `extensions` is lossless by construction: every bag key that is neither
53
+ * lifted (the six neutral fields) nor reserved (`name`/`description`) lands
54
+ * there verbatim, including keys the known-field list has never heard of. Lint
55
+ * stays the place that warns about unknown keys.
56
+ *
57
+ * The input is never mutated; nested values are shared by reference (verbatim
58
+ * pass-through is the point).
59
+ */
60
+ export declare function normalizeStepPermissions(bag: Record<string, unknown> | undefined, step?: {
61
+ model?: string;
62
+ }): StepPermissions;
@@ -0,0 +1,93 @@
1
+ /** The six fields with a harness-neutral meaning — lifted out of the bag. */
2
+ const NEUTRAL_KEYS = ['tools', 'disallowedTools', 'permissionMode', 'maxTurns', 'model', 'effort'];
3
+ /** Generated/reserved frontmatter keys. Stripped: an adapter must never see an
4
+ * author's attempt at them. They do NOT reach `extensions`. */
5
+ const RESERVED_KEYS = ['name', 'description'];
6
+ /** Keys that never appear in `extensions`, valid or not. */
7
+ const LIFTED_OR_STRIPPED = new Set([...NEUTRAL_KEYS, ...RESERVED_KEYS]);
8
+ function isPlainMap(v) {
9
+ return typeof v === 'object' && v !== null && !Array.isArray(v);
10
+ }
11
+ /**
12
+ * Normalize a tool list. The bag legitimately accepts EITHER a comma-separated
13
+ * string or a string array. A string is split on `,` with each entry trimmed and
14
+ * empties dropped; an array is copied with non-string entries dropped. Returns
15
+ * `undefined` when nothing survives, so the key is ABSENT rather than `[]` —
16
+ * "no `tools` key" and "an empty allow-list" mean different things to a harness.
17
+ */
18
+ function toolList(v) {
19
+ let out;
20
+ if (typeof v === 'string') {
21
+ out = v.split(',').map((s) => s.trim()).filter((s) => s !== '');
22
+ }
23
+ else if (Array.isArray(v)) {
24
+ out = v.filter((e) => typeof e === 'string' && e !== '');
25
+ }
26
+ else {
27
+ return undefined;
28
+ }
29
+ return out.length > 0 ? out : undefined;
30
+ }
31
+ /** A non-empty string, verbatim and unvalidated; otherwise `undefined`. */
32
+ function nonEmptyString(v) {
33
+ return typeof v === 'string' && v !== '' ? v : undefined;
34
+ }
35
+ /** A positive integer, otherwise `undefined`. Anything else is dropped rather
36
+ * than corrected — lint already errors on it, and normalization must not throw. */
37
+ function positiveInt(v) {
38
+ return typeof v === 'number' && Number.isInteger(v) && v > 0 ? v : undefined;
39
+ }
40
+ /**
41
+ * Translate one step's bag into `StepPermissions`.
42
+ *
43
+ * `bag` is the already-extracted `x.<bagKey>` object; `undefined`, `null`, an
44
+ * array, or any non-object all normalize to `{ extensions: {} }` (plus the
45
+ * step's model, when it has one).
46
+ *
47
+ * MODEL PRECEDENCE: the step's FIRST-CLASS `model` field wins over a bag-level
48
+ * `model`, carried over verbatim from the legacy frontmatter builder's
49
+ * `if (step.model !== undefined) fm['model'] = step.model`. That is today's live
50
+ * behavior and its meaning must not change — getting it backwards would silently
51
+ * alter which model live steps run under once Phase 5 routes prepare through
52
+ * this function. Note the precedence is decided on PRESENCE (a defined step
53
+ * model shadows the bag), and only then is the winner dropped if it is not a
54
+ * non-empty string.
55
+ *
56
+ * `extensions` is lossless by construction: every bag key that is neither
57
+ * lifted (the six neutral fields) nor reserved (`name`/`description`) lands
58
+ * there verbatim, including keys the known-field list has never heard of. Lint
59
+ * stays the place that warns about unknown keys.
60
+ *
61
+ * The input is never mutated; nested values are shared by reference (verbatim
62
+ * pass-through is the point).
63
+ */
64
+ export function normalizeStepPermissions(bag, step) {
65
+ const src = isPlainMap(bag) ? bag : {};
66
+ const extensions = {};
67
+ for (const [k, v] of Object.entries(src)) {
68
+ if (LIFTED_OR_STRIPPED.has(k))
69
+ continue;
70
+ extensions[k] = v;
71
+ }
72
+ const out = { extensions };
73
+ const tools = toolList(src['tools']);
74
+ if (tools !== undefined)
75
+ out.tools = tools;
76
+ const disallowedTools = toolList(src['disallowedTools']);
77
+ if (disallowedTools !== undefined)
78
+ out.disallowedTools = disallowedTools;
79
+ const permissionMode = nonEmptyString(src['permissionMode']);
80
+ if (permissionMode !== undefined)
81
+ out.permissionMode = permissionMode;
82
+ const maxTurns = positiveInt(src['maxTurns']);
83
+ if (maxTurns !== undefined)
84
+ out.maxTurns = maxTurns;
85
+ const rawModel = step?.model !== undefined ? step.model : src['model'];
86
+ const model = nonEmptyString(rawModel);
87
+ if (model !== undefined)
88
+ out.model = model;
89
+ const effort = nonEmptyString(src['effort']);
90
+ if (effort !== undefined)
91
+ out.effort = effort;
92
+ return out;
93
+ }
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Harness registry — a RUNTIME map from adapter id to `HarnessAdapter`.
3
+ *
4
+ * It is a RUNTIME registry because adapters self-register at import time and the
5
+ * fake is registered/unregistered inside individual tests.
6
+ *
7
+ * STARTS EMPTY, ON PURPOSE. Importing an adapter module from here would be the
8
+ * only way a harness vendor name could enter this file — which the isolation
9
+ * rule forbids. WHO imports the real adapter modules so their `register(...)`
10
+ * side effect fires is a COMPOSITION ROOT's job, not this module's. There are
11
+ * two: `src/roles/agent-run.ts` and `src/roles/lint.ts`. Do not add a
12
+ * barrel/index under `src/harness/` to do it: importers name the module.
13
+ *
14
+ * Failure stance: `register` THROWS on a duplicate id, because a duplicate is a
15
+ * wiring bug at composition time, not a runtime condition a caller can recover
16
+ * from. Every read is total (`undefined` / `[]`), never throws.
17
+ */
18
+ import type { HarnessAdapter } from './contract.ts';
19
+ /**
20
+ * Register an adapter under its own `id`. Throws when that id is already taken
21
+ * — two adapters claiming one id is a wiring bug, and silently letting the
22
+ * second win would route work to whichever module happened to import last.
23
+ */
24
+ export declare function register(adapter: HarnessAdapter): void;
25
+ /**
26
+ * Remove an adapter by id; returns whether one was there. Exists so a test that
27
+ * registers a fake can clean up in `afterEach` — production code has no reason
28
+ * to unregister.
29
+ */
30
+ export declare function unregister(id: string): boolean;
31
+ /** The adapter registered under `id`, or `undefined` when none is. */
32
+ export declare function adapterFor(id: string): HarnessAdapter | undefined;
33
+ /** Every registered adapter id, in registration order. */
34
+ export declare function registeredHarnessIds(): string[];
35
+ /**
36
+ * The built-in default harness id: the FIRST id in the registry, i.e. the first
37
+ * adapter module a composition root imported.
38
+ *
39
+ * Deliberately not a hardcoded literal. A literal default would be a harness
40
+ * VENDOR NAME in neutral code, which the isolation rule forbids outright — and
41
+ * this file is under `src/harness/`, where the rule is enforced by grep. The
42
+ * import-order rule gives the same behavior without the string.
43
+ *
44
+ * Returns `undefined` when nothing is registered; the caller then fails honestly
45
+ * (`'no-harness'`) rather than guessing.
46
+ */
47
+ export declare function defaultHarnessId(): string | undefined;
@@ -0,0 +1,45 @@
1
+ /** Module-level, process-wide. One registry per process is the intent. */
2
+ const ADAPTERS = new Map();
3
+ /**
4
+ * Register an adapter under its own `id`. Throws when that id is already taken
5
+ * — two adapters claiming one id is a wiring bug, and silently letting the
6
+ * second win would route work to whichever module happened to import last.
7
+ */
8
+ export function register(adapter) {
9
+ const existing = ADAPTERS.get(adapter.id);
10
+ if (existing !== undefined) {
11
+ throw new Error(`harness adapter '${adapter.id}' is already registered`);
12
+ }
13
+ ADAPTERS.set(adapter.id, adapter);
14
+ }
15
+ /**
16
+ * Remove an adapter by id; returns whether one was there. Exists so a test that
17
+ * registers a fake can clean up in `afterEach` — production code has no reason
18
+ * to unregister.
19
+ */
20
+ export function unregister(id) {
21
+ return ADAPTERS.delete(id);
22
+ }
23
+ /** The adapter registered under `id`, or `undefined` when none is. */
24
+ export function adapterFor(id) {
25
+ return ADAPTERS.get(id);
26
+ }
27
+ /** Every registered adapter id, in registration order. */
28
+ export function registeredHarnessIds() {
29
+ return [...ADAPTERS.keys()];
30
+ }
31
+ /**
32
+ * The built-in default harness id: the FIRST id in the registry, i.e. the first
33
+ * adapter module a composition root imported.
34
+ *
35
+ * Deliberately not a hardcoded literal. A literal default would be a harness
36
+ * VENDOR NAME in neutral code, which the isolation rule forbids outright — and
37
+ * this file is under `src/harness/`, where the rule is enforced by grep. The
38
+ * import-order rule gives the same behavior without the string.
39
+ *
40
+ * Returns `undefined` when nothing is registered; the caller then fails honestly
41
+ * (`'no-harness'`) rather than guessing.
42
+ */
43
+ export function defaultHarnessId() {
44
+ return registeredHarnessIds()[0];
45
+ }