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.
- package/CHANGELOG.md +45 -0
- package/README.md +98 -25
- package/bin/owenloop.mjs +2 -2
- package/dist/packages/work/src/agent/brief.d.ts +172 -0
- package/dist/packages/work/src/agent/brief.js +193 -0
- package/dist/packages/work/src/agent/loop.d.ts +135 -0
- package/dist/packages/work/src/agent/loop.js +542 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +90 -0
- package/dist/packages/work/src/bundle/cache.js +324 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
- package/dist/packages/work/src/bundle/fetch.js +325 -0
- package/dist/packages/work/src/bundle/types.d.ts +160 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/loop.d.ts +29 -0
- package/dist/packages/work/src/exec/loop.js +215 -0
- package/dist/packages/work/src/exec/receipt.d.ts +38 -0
- package/dist/packages/work/src/exec/receipt.js +21 -0
- package/dist/packages/work/src/exec/runner.d.ts +65 -0
- package/dist/packages/work/src/exec/runner.js +185 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +127 -0
- package/dist/packages/work/src/harness/claude.d.ts +128 -0
- package/dist/packages/work/src/harness/claude.js +635 -0
- package/dist/packages/work/src/harness/codex.d.ts +110 -0
- package/dist/packages/work/src/harness/codex.js +896 -0
- package/dist/packages/work/src/harness/contract.d.ts +283 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +90 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
- package/dist/packages/work/src/harness/permissions.d.ts +62 -0
- package/dist/packages/work/src/harness/permissions.js +93 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +163 -0
- package/dist/packages/work/src/harness/session-store.js +319 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +55 -0
- package/dist/packages/work/src/hold/mcp.js +149 -0
- package/dist/packages/work/src/hub/client.d.ts +22 -0
- package/dist/packages/work/src/hub/client.js +78 -0
- package/dist/packages/work/src/hub/types.d.ts +290 -0
- package/dist/packages/work/src/hub/types.js +28 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
- package/dist/packages/work/src/roles/agent-run.js +447 -0
- package/dist/packages/work/src/roles/exec.d.ts +40 -0
- package/dist/packages/work/src/roles/exec.js +203 -0
- package/dist/packages/work/src/roles/hold.d.ts +68 -0
- package/dist/packages/work/src/roles/hold.js +324 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +59 -0
- package/dist/packages/work/src/roles/lint.js +200 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +66 -0
- package/dist/packages/work/src/roles/shift.d.ts +12 -0
- package/dist/packages/work/src/roles/shift.js +228 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +120 -0
- package/dist/packages/work/src/settings/settings.js +116 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +120 -0
- package/dist/packages/work/src/shift/loop.js +468 -0
- package/dist/packages/work/src/shift/protocol.d.ts +91 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +43 -0
- package/dist/packages/work/src/shift/runtime.js +274 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +86 -0
- package/dist/packages/work/src/shift/spawn.js +100 -0
- package/dist/packages/work/src/shift/state.d.ts +77 -0
- package/dist/packages/work/src/shift/state.js +162 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/{add.d.ts → src/add.d.ts} +12 -40
- package/dist/{add.js → src/add.js} +11 -176
- package/dist/src/cli.d.ts +147 -0
- package/dist/{cli.js → src/cli.js} +1643 -353
- package/dist/src/credentials.d.ts +280 -0
- package/dist/src/credentials.js +697 -0
- package/dist/{defs.js → src/defs.js} +59 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +29 -20
- package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
- package/dist/{hub.js → src/hub.js} +531 -1
- package/dist/{index.d.ts → src/index.d.ts} +3 -1
- package/dist/{index.js → src/index.js} +2 -1
- package/dist/src/lock.d.ts +80 -0
- package/dist/src/lock.js +217 -0
- package/dist/src/mcp/serve.d.ts +85 -0
- package/dist/src/mcp/serve.js +702 -0
- package/dist/src/mcp/server.d.ts +132 -0
- package/dist/src/mcp/server.js +327 -0
- package/dist/{model.d.ts → src/model.d.ts} +59 -4
- package/dist/{model.js → src/model.js} +149 -22
- package/dist/{types.d.ts → src/types.d.ts} +66 -24
- package/dist/{util.d.ts → src/util.d.ts} +25 -0
- package/dist/{util.js → src/util.js} +26 -0
- package/dist/src/work-settings.d.ts +57 -0
- package/dist/src/work-settings.js +84 -0
- package/docs/authoring.md +102 -53
- package/docs/cli.md +883 -29
- package/docs/design.md +119 -45
- package/docs/embedding.md +39 -14
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +17 -8
- package/dist/cli.d.ts +0 -83
- /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
- /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
- /package/dist/{factory.js → src/factory.js} +0 -0
- /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
- /package/dist/{paths.js → src/paths.js} +0 -0
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
- /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
- /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
|
+
}
|