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,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ONE place the bearer-token resolution / refuse / dev-override logic lives,
|
|
3
|
+
* so all five roles share identical precedence instead of re-deriving it:
|
|
4
|
+
*
|
|
5
|
+
* 1. `OWENLOOP_TOKEN` (trimmed, non-empty) — an EXPLICIT dev-only override.
|
|
6
|
+
* When set, it is used verbatim and the store + account are skipped.
|
|
7
|
+
* 2. Otherwise read the `agent:<account>` slot from owenloop's store:
|
|
8
|
+
* - a `Credential` → its bearer token (`credentialToToken`).
|
|
9
|
+
* - `null` → refuse (code 2): no Scoped Identity key for this origin/account,
|
|
10
|
+
* naming a runnable `owenloop login` connect command.
|
|
11
|
+
* - a THROW → error (code 1): a genuine read failure (bad origin /
|
|
12
|
+
* external-command failure), surfaced with its message.
|
|
13
|
+
*
|
|
14
|
+
* The refuse (code 2) is a refuse-to-start precondition, mirroring the old
|
|
15
|
+
* "no token" exit code, so existing exit-code assertions stay valid — only the
|
|
16
|
+
* message text changes. owenloop stays read-only w.r.t. credentials.
|
|
17
|
+
*/
|
|
18
|
+
import { OwenloopCredentialReader } from "./owenloop.js";
|
|
19
|
+
import { credentialToToken } from "./reader.js";
|
|
20
|
+
/**
|
|
21
|
+
* The owenloop `--as <slot>` argument for an account: `agent` for the default
|
|
22
|
+
* account, `agent:<account>` otherwise. Grounded from owenloop's `--as`
|
|
23
|
+
* semantics (`human` | `agent` | `agent:<account>`).
|
|
24
|
+
*/
|
|
25
|
+
export function slotArg(account) {
|
|
26
|
+
return account === 'default' ? 'agent' : `agent:${account}`;
|
|
27
|
+
}
|
|
28
|
+
export async function resolveBearer(args) {
|
|
29
|
+
const { origin, account, env } = args;
|
|
30
|
+
// 1. Dev-only override: explicit OWENLOOP_TOKEN bypasses the store + account.
|
|
31
|
+
const override = env['OWENLOOP_TOKEN']?.trim();
|
|
32
|
+
if (override !== undefined && override !== '') {
|
|
33
|
+
return { ok: true, token: override };
|
|
34
|
+
}
|
|
35
|
+
// 2. The store: read ONLY the agent:<account> slot (never human).
|
|
36
|
+
let cred;
|
|
37
|
+
try {
|
|
38
|
+
cred = await new OwenloopCredentialReader({ account, env }).read(origin);
|
|
39
|
+
}
|
|
40
|
+
catch (err) {
|
|
41
|
+
const detail = err instanceof Error ? err.message : String(err);
|
|
42
|
+
return {
|
|
43
|
+
ok: false,
|
|
44
|
+
code: 1,
|
|
45
|
+
message: `credential read failed for ${origin} (account "${account}"): ${detail}`,
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
if (cred === null) {
|
|
49
|
+
return {
|
|
50
|
+
ok: false,
|
|
51
|
+
code: 2,
|
|
52
|
+
message: `no Scoped Identity key for ${origin} (account "${account}") — run: owenloop login --hub ${origin} --as ${slotArg(account)}`,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
return { ok: true, token: credentialToToken(cred) };
|
|
56
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { HubClient } from '../hub/client.ts';
|
|
2
|
+
import type { ContactHolder } from '../hub/types.ts';
|
|
3
|
+
import type { CommandRunner } from './runner.ts';
|
|
4
|
+
/** Discriminated result of an exec run; the role maps these to exit codes. */
|
|
5
|
+
export type ExecOutcome = 'submitted' | 'completed' | 'misroute' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'submit-rejected' | 'submit-failed' | 'stopped';
|
|
6
|
+
export interface ExecLoopOptions {
|
|
7
|
+
hub: HubClient;
|
|
8
|
+
runner: CommandRunner;
|
|
9
|
+
workflow: string;
|
|
10
|
+
run: string;
|
|
11
|
+
/** The exec process holder tag `{kind:'exec', id}` — id is `<hostname>:<pid>`. */
|
|
12
|
+
holder: ContactHolder;
|
|
13
|
+
/** cwd for the command when the order packet carries no `workdir`. */
|
|
14
|
+
cwd: string;
|
|
15
|
+
sleep: (ms: number) => Promise<void>;
|
|
16
|
+
now: () => number;
|
|
17
|
+
random?: () => number;
|
|
18
|
+
out: (line: string) => void;
|
|
19
|
+
err: (line: string) => void;
|
|
20
|
+
heartbeatIntervalMs?: number;
|
|
21
|
+
jumpToleranceMs?: number;
|
|
22
|
+
failureWindowMs?: number;
|
|
23
|
+
}
|
|
24
|
+
export interface ExecLoop {
|
|
25
|
+
run(): Promise<ExecOutcome>;
|
|
26
|
+
/** Final breath: kill the command group and release. Wired to SIGINT/SIGTERM. */
|
|
27
|
+
stop(reason?: string): void;
|
|
28
|
+
}
|
|
29
|
+
export declare function createExecLoop(opts: ExecLoopOptions): ExecLoop;
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The exec orchestration core (C5) — the detached, self-leasing command worker.
|
|
3
|
+
*
|
|
4
|
+
* A command order the shift (C3) dispatched becomes a detached `owenloop work exec`
|
|
5
|
+
* process. This core drives its whole life against the hub, every side effect
|
|
6
|
+
* injected (hub client, command runner, sleep/clock, output sinks) so tests run
|
|
7
|
+
* it with a fake hub + fake runner and no real timers or child processes:
|
|
8
|
+
*
|
|
9
|
+
* 1. FIRST CONTACT — starts the shared lease loop (`src/lease/loop.ts`) with the
|
|
10
|
+
* exec holder tag `{kind:'exec', id}` (the B3 drain exemption: exec-held
|
|
11
|
+
* claims survive a session drain). The loop's first `get_order` beats the
|
|
12
|
+
* lease and delivers the order packet via `onOrder`; the loop then keeps the
|
|
13
|
+
* lease warm underneath everything below.
|
|
14
|
+
* 2. VALIDATE — a `null` packet, a missing/blank `command`, a non-`command`
|
|
15
|
+
* executor, or a missing/empty `owes` is a MISROUTE (plan decision 3): not exec's to
|
|
16
|
+
* fail (a Step Agent could legitimately run it), so a targeted release, no
|
|
17
|
+
* submit, exit 1.
|
|
18
|
+
* 3. RUN + RACE — the runner shells the command out while the lease loop runs.
|
|
19
|
+
* Whichever settles first wins (plan decision 9):
|
|
20
|
+
* - command settles (any exit code, or a machinery error) ⇒ build a
|
|
21
|
+
* receipt and `submit` it to every owed path, then stop the lease
|
|
22
|
+
* WITHOUT release (the run just closed). Exit 0 — delivering the receipt
|
|
23
|
+
* IS the job, even for a failing command (the exit code carries truth).
|
|
24
|
+
* - lease goes terminal first (lease-lost / ownership-error / unreachable /
|
|
25
|
+
* the engine closed the run) ⇒ kill the command's process group, NO
|
|
26
|
+
* submit (a submit would race the re-offer), exit 1.
|
|
27
|
+
* 4. FINAL BREATH — a SIGINT/SIGTERM aimed at exec itself is an operator killing
|
|
28
|
+
* the work (drain only exempts exec from the SESSION's death): `stop()` kills
|
|
29
|
+
* the command group and takes a targeted release, exit 1 (plan decision 1).
|
|
30
|
+
* Killed work NEVER gets a receipt — even when the TERM'd command settles
|
|
31
|
+
* before the release round-trip resolves the lease (the common ordering),
|
|
32
|
+
* the submit path checks `signalled` and bails to `killed`.
|
|
33
|
+
*
|
|
34
|
+
* The role (`src/roles/exec.ts`) maps each `ExecOutcome` to an exit code.
|
|
35
|
+
*/
|
|
36
|
+
import { createHash } from 'node:crypto';
|
|
37
|
+
import { createLeaseLoop } from "../lease/loop.js";
|
|
38
|
+
import { buildReceipt } from "./receipt.js";
|
|
39
|
+
/** sha256 of the empty byte string — the hash for a run with no captured output. */
|
|
40
|
+
const EMPTY_HASH = createHash('sha256').digest('hex');
|
|
41
|
+
function errMsg(e) {
|
|
42
|
+
return e instanceof Error ? e.message : String(e);
|
|
43
|
+
}
|
|
44
|
+
export function createExecLoop(opts) {
|
|
45
|
+
const { hub, runner, workflow } = opts;
|
|
46
|
+
const runId = opts.run;
|
|
47
|
+
let running;
|
|
48
|
+
let signalled = false;
|
|
49
|
+
let leasePromise;
|
|
50
|
+
let resolveOrder;
|
|
51
|
+
const orderReady = new Promise((r) => {
|
|
52
|
+
resolveOrder = r;
|
|
53
|
+
});
|
|
54
|
+
const lease = createLeaseLoop({
|
|
55
|
+
hub,
|
|
56
|
+
workflow,
|
|
57
|
+
run: runId,
|
|
58
|
+
role: 'exec',
|
|
59
|
+
holder: opts.holder,
|
|
60
|
+
onOrder: (res) => resolveOrder?.(res),
|
|
61
|
+
sleep: opts.sleep,
|
|
62
|
+
now: opts.now,
|
|
63
|
+
out: opts.out,
|
|
64
|
+
err: opts.err,
|
|
65
|
+
...(opts.random !== undefined ? { random: opts.random } : {}),
|
|
66
|
+
...(opts.heartbeatIntervalMs !== undefined ? { heartbeatIntervalMs: opts.heartbeatIntervalMs } : {}),
|
|
67
|
+
...(opts.jumpToleranceMs !== undefined ? { jumpToleranceMs: opts.jumpToleranceMs } : {}),
|
|
68
|
+
...(opts.failureWindowMs !== undefined ? { failureWindowMs: opts.failureWindowMs } : {}),
|
|
69
|
+
});
|
|
70
|
+
/** A CommandResult standing in for a runner that threw before producing one. */
|
|
71
|
+
function machineryFailure(e) {
|
|
72
|
+
const t = opts.now();
|
|
73
|
+
return {
|
|
74
|
+
exitCode: null,
|
|
75
|
+
error: errMsg(e),
|
|
76
|
+
outputHash: `sha256:${EMPTY_HASH}`,
|
|
77
|
+
stdoutBytes: 0,
|
|
78
|
+
stderrBytes: 0,
|
|
79
|
+
outputTail: '',
|
|
80
|
+
startedAt: t,
|
|
81
|
+
finishedAt: t,
|
|
82
|
+
durationMs: 0,
|
|
83
|
+
};
|
|
84
|
+
}
|
|
85
|
+
/** A first-contact / no-hold lease outcome → exec outcome. */
|
|
86
|
+
function mapNoHold(o) {
|
|
87
|
+
switch (o) {
|
|
88
|
+
case 'completed':
|
|
89
|
+
return 'completed';
|
|
90
|
+
case 'ownership-error':
|
|
91
|
+
return 'ownership-error';
|
|
92
|
+
case 'hub-unreachable':
|
|
93
|
+
return 'hub-unreachable';
|
|
94
|
+
case 'lease-lost':
|
|
95
|
+
return 'lease-lost';
|
|
96
|
+
case 'stopped':
|
|
97
|
+
return signalled ? 'killed' : 'stopped';
|
|
98
|
+
case 'released':
|
|
99
|
+
case 'release-failed':
|
|
100
|
+
// stop() with release fired before the hold was ever established.
|
|
101
|
+
return 'killed';
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
/** A lease outcome observed while the command was running (exit 1 always). */
|
|
105
|
+
function mapLeaseDuringRun(o) {
|
|
106
|
+
if (o === 'ownership-error')
|
|
107
|
+
return 'ownership-error';
|
|
108
|
+
if (o === 'hub-unreachable')
|
|
109
|
+
return 'hub-unreachable';
|
|
110
|
+
return 'lease-lost';
|
|
111
|
+
}
|
|
112
|
+
/** Build the receipt and submit it to every owed path. */
|
|
113
|
+
async function submitReceipt(result, order) {
|
|
114
|
+
if (signalled) {
|
|
115
|
+
// The operator killed the work and the command settled before the lease
|
|
116
|
+
// (the release HTTP round-trip is slower than a TERM'd child dying), so
|
|
117
|
+
// the done branch won the race. Plan decision 1: NO receipt for killed
|
|
118
|
+
// work — a submit here would race the release/re-offer. stop() already
|
|
119
|
+
// took the targeted release; just wait for it.
|
|
120
|
+
opts.err(`owenloop work exec: signalled — killed work gets no receipt, released ${workflow}/${runId}`);
|
|
121
|
+
await leasePromise;
|
|
122
|
+
return 'killed';
|
|
123
|
+
}
|
|
124
|
+
const receipt = buildReceipt(result, {
|
|
125
|
+
command: order.command ?? '',
|
|
126
|
+
orchestrator: opts.holder.id,
|
|
127
|
+
workflow,
|
|
128
|
+
run: runId,
|
|
129
|
+
step: order.step,
|
|
130
|
+
});
|
|
131
|
+
for (const owe of order.owes) {
|
|
132
|
+
let res;
|
|
133
|
+
try {
|
|
134
|
+
res = await hub.submit({ workflow, run: runId, path: owe.path, value: receipt, holder: opts.holder });
|
|
135
|
+
}
|
|
136
|
+
catch (e) {
|
|
137
|
+
opts.err(`owenloop work exec: submit to ${owe.path} failed: ${errMsg(e)}`);
|
|
138
|
+
lease.stop('submit-failed'); // targeted release (idempotent) — best effort
|
|
139
|
+
await leasePromise;
|
|
140
|
+
return 'submit-failed';
|
|
141
|
+
}
|
|
142
|
+
const outcome = res.outcome;
|
|
143
|
+
if (outcome !== 'green' && outcome !== 'submitted') {
|
|
144
|
+
opts.err(`owenloop work exec: submit to ${owe.path} rejected (${outcome ?? 'unknown'}): ${res.text}`);
|
|
145
|
+
// born-rejected ⇒ the claim is already gone, no release; otherwise a
|
|
146
|
+
// targeted release is idempotent and harmless.
|
|
147
|
+
lease.stop('submit-rejected', outcome === 'born-rejected' ? { release: false } : undefined);
|
|
148
|
+
await leasePromise;
|
|
149
|
+
return 'submit-rejected';
|
|
150
|
+
}
|
|
151
|
+
opts.out(`owenloop work exec: submitted receipt to ${owe.path} (${outcome})`);
|
|
152
|
+
}
|
|
153
|
+
// Every owed path landed — the run has closed, so stop WITHOUT releasing.
|
|
154
|
+
lease.stop('submitted', { release: false });
|
|
155
|
+
await leasePromise;
|
|
156
|
+
return 'submitted';
|
|
157
|
+
}
|
|
158
|
+
async function run() {
|
|
159
|
+
leasePromise = lease.run();
|
|
160
|
+
// First contact race: the order arrives (hold established), or the lease
|
|
161
|
+
// resolves terminally before we ever established it.
|
|
162
|
+
const first = await Promise.race([
|
|
163
|
+
orderReady.then((res) => ({ t: 'order', res })),
|
|
164
|
+
leasePromise.then((o) => ({ t: 'lease', o })),
|
|
165
|
+
]);
|
|
166
|
+
if (first.t === 'lease')
|
|
167
|
+
return mapNoHold(first.o);
|
|
168
|
+
const order = first.res.order;
|
|
169
|
+
const command = order?.command;
|
|
170
|
+
if (order === null ||
|
|
171
|
+
typeof command !== 'string' ||
|
|
172
|
+
command === '' ||
|
|
173
|
+
(order.executor !== undefined && order.executor !== 'command') ||
|
|
174
|
+
!Array.isArray(order.owes) ||
|
|
175
|
+
order.owes.length === 0) {
|
|
176
|
+
opts.err(`owenloop work exec: ${workflow}/${runId} is not a runnable command order (misroute) — releasing`);
|
|
177
|
+
lease.stop('misroute'); // targeted release — not exec's to fail
|
|
178
|
+
await leasePromise;
|
|
179
|
+
return 'misroute';
|
|
180
|
+
}
|
|
181
|
+
// Run the command and race it against the lease going terminal.
|
|
182
|
+
let cmd;
|
|
183
|
+
try {
|
|
184
|
+
cmd = runner.start(command, { cwd: order.workdir ?? opts.cwd });
|
|
185
|
+
}
|
|
186
|
+
catch (e) {
|
|
187
|
+
return submitReceipt(machineryFailure(e), order);
|
|
188
|
+
}
|
|
189
|
+
running = cmd;
|
|
190
|
+
opts.out(`owenloop work exec: running ${workflow}/${runId} (step '${order.step}')`);
|
|
191
|
+
const outcome = await Promise.race([
|
|
192
|
+
cmd.done.then((r) => ({ t: 'done', r })).catch((e) => ({ t: 'done', r: machineryFailure(e) })),
|
|
193
|
+
leasePromise.then((o) => ({ t: 'lease', o })),
|
|
194
|
+
]);
|
|
195
|
+
if (outcome.t === 'lease') {
|
|
196
|
+
await cmd.kill(); // no receipt — a submit now would race the re-offer
|
|
197
|
+
if (signalled) {
|
|
198
|
+
opts.err(`owenloop work exec: signalled mid-run — killed the command group, released ${workflow}/${runId}`);
|
|
199
|
+
return 'killed';
|
|
200
|
+
}
|
|
201
|
+
opts.err(`owenloop work exec: lease ${outcome.o} while the command ran — killed the command, no receipt submitted`);
|
|
202
|
+
return mapLeaseDuringRun(outcome.o);
|
|
203
|
+
}
|
|
204
|
+
return submitReceipt(outcome.r, order);
|
|
205
|
+
}
|
|
206
|
+
function stop(reason) {
|
|
207
|
+
if (signalled)
|
|
208
|
+
return;
|
|
209
|
+
signalled = true;
|
|
210
|
+
if (running !== undefined)
|
|
211
|
+
void running.kill();
|
|
212
|
+
lease.stop(reason ?? 'signal'); // release:true — hand the killed order back
|
|
213
|
+
}
|
|
214
|
+
return { run, stop };
|
|
215
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The command receipt (C5, plan decision 8) — the audit record exec submits for
|
|
3
|
+
* a command order. It IS the result contract: the hub `submit` verb has no
|
|
4
|
+
* failure channel, so a receipt is submitted for EVERY finished command — a
|
|
5
|
+
* non-zero `exitCode` (or `exitCode: null` + `error` for machinery failure)
|
|
6
|
+
* carries the truth, and exec still exits 0 because its job (deliver the
|
|
7
|
+
* receipt) succeeded. Pure construction so it is trivially asserted in tests.
|
|
8
|
+
*/
|
|
9
|
+
import type { CommandResult } from './runner.ts';
|
|
10
|
+
/** The submitted artifact value for a command order. */
|
|
11
|
+
export interface CommandReceipt {
|
|
12
|
+
kind: 'command-receipt';
|
|
13
|
+
command: string;
|
|
14
|
+
exitCode: number | null;
|
|
15
|
+
signal?: string;
|
|
16
|
+
error?: string;
|
|
17
|
+
outputHash: string;
|
|
18
|
+
stdoutBytes: number;
|
|
19
|
+
stderrBytes: number;
|
|
20
|
+
outputTail: string;
|
|
21
|
+
startedAt: number;
|
|
22
|
+
finishedAt: number;
|
|
23
|
+
durationMs: number;
|
|
24
|
+
/** The holder id of the exec process that ran it (`<hostname>:<pid>`). */
|
|
25
|
+
orchestrator: string;
|
|
26
|
+
workflow: string;
|
|
27
|
+
run: string;
|
|
28
|
+
step: string;
|
|
29
|
+
}
|
|
30
|
+
export interface ReceiptContext {
|
|
31
|
+
command: string;
|
|
32
|
+
orchestrator: string;
|
|
33
|
+
workflow: string;
|
|
34
|
+
run: string;
|
|
35
|
+
step: string;
|
|
36
|
+
}
|
|
37
|
+
/** Fold a raw `CommandResult` and its order context into the submitted receipt. */
|
|
38
|
+
export declare function buildReceipt(result: CommandResult, ctx: ReceiptContext): CommandReceipt;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/** Fold a raw `CommandResult` and its order context into the submitted receipt. */
|
|
2
|
+
export function buildReceipt(result, ctx) {
|
|
3
|
+
return {
|
|
4
|
+
kind: 'command-receipt',
|
|
5
|
+
command: ctx.command,
|
|
6
|
+
exitCode: result.exitCode,
|
|
7
|
+
...(result.signal !== undefined ? { signal: result.signal } : {}),
|
|
8
|
+
...(result.error !== undefined ? { error: result.error } : {}),
|
|
9
|
+
outputHash: result.outputHash,
|
|
10
|
+
stdoutBytes: result.stdoutBytes,
|
|
11
|
+
stderrBytes: result.stderrBytes,
|
|
12
|
+
outputTail: result.outputTail,
|
|
13
|
+
startedAt: result.startedAt,
|
|
14
|
+
finishedAt: result.finishedAt,
|
|
15
|
+
durationMs: result.durationMs,
|
|
16
|
+
orchestrator: ctx.orchestrator,
|
|
17
|
+
workflow: ctx.workflow,
|
|
18
|
+
run: ctx.run,
|
|
19
|
+
step: ctx.step,
|
|
20
|
+
};
|
|
21
|
+
}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/** The raw execution facts a run produces; the loop wraps these into a receipt. */
|
|
2
|
+
export interface CommandResult {
|
|
3
|
+
/** The command's exit code, or `null` when killed by signal / machinery failed. */
|
|
4
|
+
exitCode: number | null;
|
|
5
|
+
/** The signal that terminated the command, when it was signalled. */
|
|
6
|
+
signal?: string;
|
|
7
|
+
/** Set only on execution-machinery failure (spawn/cwd/error) — not a non-zero exit. */
|
|
8
|
+
error?: string;
|
|
9
|
+
/**
|
|
10
|
+
* `sha256:<hex>` over full stdout bytes then full stderr bytes, or — when
|
|
11
|
+
* out-of-order stderr overflowed the 1 MiB buffer cap — the two-part
|
|
12
|
+
* `sha256:<stdout hex>+<stderr hex>` (each stream hashed fully on its own).
|
|
13
|
+
*/
|
|
14
|
+
outputHash: string;
|
|
15
|
+
stdoutBytes: number;
|
|
16
|
+
stderrBytes: number;
|
|
17
|
+
/** Last ≤4 KiB of combined stdout+stderr, decoded lossily as UTF-8. */
|
|
18
|
+
outputTail: string;
|
|
19
|
+
startedAt: number;
|
|
20
|
+
finishedAt: number;
|
|
21
|
+
durationMs: number;
|
|
22
|
+
}
|
|
23
|
+
/** A command that is running (or has failed to start). */
|
|
24
|
+
export interface RunningCommand {
|
|
25
|
+
/** Resolves once the command settles (any exit code, kill, or machinery error). */
|
|
26
|
+
done: Promise<CommandResult>;
|
|
27
|
+
/** Idempotently take down the command's process group (TERM → grace → KILL). */
|
|
28
|
+
kill(): Promise<void>;
|
|
29
|
+
}
|
|
30
|
+
/** The runner seam. Injected into the exec loop; faked in the loop's tests. */
|
|
31
|
+
export interface CommandRunner {
|
|
32
|
+
start(command: string, opts: {
|
|
33
|
+
cwd: string;
|
|
34
|
+
}): RunningCommand;
|
|
35
|
+
}
|
|
36
|
+
/** The fully-resolved spawn arguments — pure data, asserted directly in tests. */
|
|
37
|
+
export interface CommandPlan {
|
|
38
|
+
command: string;
|
|
39
|
+
args: string[];
|
|
40
|
+
options: {
|
|
41
|
+
cwd: string;
|
|
42
|
+
detached: true;
|
|
43
|
+
stdio: ['ignore', 'pipe', 'pipe'];
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Build the argv + options for a detached `/bin/sh -c <command>`. Pure — no
|
|
48
|
+
* spawn, no I/O — so tests assert the shape without launching anything. POSIX
|
|
49
|
+
* `/bin/sh` keeps the default runner portable (ubuntu-latest CI, macOS dev).
|
|
50
|
+
*/
|
|
51
|
+
export declare function buildCommandPlan(command: string, cwd: string): CommandPlan;
|
|
52
|
+
export interface DefaultRunnerOptions {
|
|
53
|
+
/** SIGTERM→SIGKILL grace on a group kill (default 5_000). */
|
|
54
|
+
graceMs?: number;
|
|
55
|
+
/** Clock seam (default `Date.now`). */
|
|
56
|
+
now?: () => number;
|
|
57
|
+
/** Timer seam for the kill grace (default real `setTimeout`). */
|
|
58
|
+
sleep?: (ms: number) => Promise<void>;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* The default command runner: spawns `/bin/sh -c <command>` in its own process
|
|
62
|
+
* group and captures a bounded result. Every timing/timer seam is injectable so
|
|
63
|
+
* the kill-grace path is testable without wall-clock waits.
|
|
64
|
+
*/
|
|
65
|
+
export declare function createDefaultRunner(opts?: DefaultRunnerOptions): CommandRunner;
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The command-runner seam (C5, plan decision 7).
|
|
3
|
+
*
|
|
4
|
+
* exec's one job that actually touches the machine: shell out the order's opaque
|
|
5
|
+
* `command` string, capture its result, and — on a kill — take down the whole
|
|
6
|
+
* process group. It is a SEAM so the exec loop's tests drive a fake runner and
|
|
7
|
+
* never spawn a real child; only `exec-runner.test.ts` exercises the default
|
|
8
|
+
* impl, against harmless fixtures in a test-created temp cwd.
|
|
9
|
+
*
|
|
10
|
+
* The default runner spawns `/bin/sh -c <command>` DETACHED (its own process
|
|
11
|
+
* group, so a group-kill reaches every descendant the command forks) with
|
|
12
|
+
* stdout/stderr piped. It captures:
|
|
13
|
+
* - `outputHash`: sha256 over the FULL stdout bytes then the FULL stderr bytes
|
|
14
|
+
* (in that order): `sha256:<hex>`. To hash the full streams in that order
|
|
15
|
+
* with bounded live memory, stdout is fed to the hash as it arrives and
|
|
16
|
+
* stderr chunks that arrive before stdout ends are buffered, then flushed in
|
|
17
|
+
* order. That out-of-order buffer is CAPPED at 1 MiB (a long command
|
|
18
|
+
* streaming progress to stderr while stdout stays open would otherwise
|
|
19
|
+
* buffer its entire stderr — an OOM vector). On overflow the capture
|
|
20
|
+
* degrades deterministically to the two-part form
|
|
21
|
+
* `sha256:<sha256(full stdout)>+<sha256(full stderr)>` — both streams still
|
|
22
|
+
* fully hashed, only the interleaved ordering claim is dropped, and the
|
|
23
|
+
* hash string itself says which form it is. Memory stays bounded either way.
|
|
24
|
+
* - `outputTail`: the last 4 KiB of the combined (stdout-then-stderr) output,
|
|
25
|
+
* decoded lossily as UTF-8 — enough for a human to eyeball a failure without
|
|
26
|
+
* bloating the submitted receipt (each retained tail buffer is itself capped
|
|
27
|
+
* at 1 MiB). Binary / no-trailing-newline output is fine: the tail is a lossy
|
|
28
|
+
* excerpt, the hash is over raw bytes.
|
|
29
|
+
*
|
|
30
|
+
* Execution-machinery failure (spawn ENOENT, a missing cwd, an `error` event)
|
|
31
|
+
* resolves — never rejects — with `exitCode: null` and an `error` string, so the
|
|
32
|
+
* exec loop can submit a receipt for it (plan decision 2) rather than crashing.
|
|
33
|
+
*/
|
|
34
|
+
import { spawn } from 'node:child_process';
|
|
35
|
+
import { createHash } from 'node:crypto';
|
|
36
|
+
const RETAIN_CAP_BYTES = 1024 * 1024; // 1 MiB retained per stream (for the tail)
|
|
37
|
+
const TAIL_BYTES = 4096; // last 4 KiB of combined output kept in the receipt
|
|
38
|
+
const DEFAULT_GRACE_MS = 5_000; // SIGTERM → grace → SIGKILL on a group kill
|
|
39
|
+
/**
|
|
40
|
+
* Build the argv + options for a detached `/bin/sh -c <command>`. Pure — no
|
|
41
|
+
* spawn, no I/O — so tests assert the shape without launching anything. POSIX
|
|
42
|
+
* `/bin/sh` keeps the default runner portable (ubuntu-latest CI, macOS dev).
|
|
43
|
+
*/
|
|
44
|
+
export function buildCommandPlan(command, cwd) {
|
|
45
|
+
return {
|
|
46
|
+
command: '/bin/sh',
|
|
47
|
+
args: ['-c', command],
|
|
48
|
+
options: { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] },
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
/** Append `chunk` to a rolling tail buffer keeping only its last `cap` bytes. */
|
|
52
|
+
function appendTail(buf, chunk, cap) {
|
|
53
|
+
const next = buf.length === 0 ? chunk : Buffer.concat([buf, chunk]);
|
|
54
|
+
return next.length > cap ? next.subarray(next.length - cap) : next;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* The default command runner: spawns `/bin/sh -c <command>` in its own process
|
|
58
|
+
* group and captures a bounded result. Every timing/timer seam is injectable so
|
|
59
|
+
* the kill-grace path is testable without wall-clock waits.
|
|
60
|
+
*/
|
|
61
|
+
export function createDefaultRunner(opts = {}) {
|
|
62
|
+
const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
|
|
63
|
+
const now = opts.now ?? Date.now;
|
|
64
|
+
const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
|
|
65
|
+
return {
|
|
66
|
+
start(command, startOpts) {
|
|
67
|
+
const startedAt = now();
|
|
68
|
+
const plan = buildCommandPlan(command, startOpts.cwd);
|
|
69
|
+
const hash = createHash('sha256'); // stdout-then-stderr, the ordered form
|
|
70
|
+
const stderrHash = createHash('sha256'); // stderr alone — the degraded fallback
|
|
71
|
+
let stdoutBytes = 0;
|
|
72
|
+
let stderrBytes = 0;
|
|
73
|
+
let stdoutTail = Buffer.alloc(0);
|
|
74
|
+
let stderrTail = Buffer.alloc(0);
|
|
75
|
+
let stdoutEnded = false;
|
|
76
|
+
// stderr that arrived before stdout ended, held to preserve the ordered
|
|
77
|
+
// hash — CAPPED: on overflow we drop it and degrade to the two-part hash
|
|
78
|
+
// (`hash` then covers stdout only; `stderrHash` always covers all stderr).
|
|
79
|
+
const pendingStderr = [];
|
|
80
|
+
let pendingStderrBytes = 0;
|
|
81
|
+
let degraded = false;
|
|
82
|
+
let settled = false;
|
|
83
|
+
let resolveDone;
|
|
84
|
+
const done = new Promise((r) => {
|
|
85
|
+
resolveDone = r;
|
|
86
|
+
});
|
|
87
|
+
const finish = (exitCode, signal, error) => {
|
|
88
|
+
if (settled)
|
|
89
|
+
return;
|
|
90
|
+
settled = true;
|
|
91
|
+
// Flush any stderr that arrived before stdout ended, preserving the
|
|
92
|
+
// stdout-then-stderr hash ordering (a no-op when degraded — dropped).
|
|
93
|
+
if (!degraded)
|
|
94
|
+
for (const c of pendingStderr)
|
|
95
|
+
hash.update(c);
|
|
96
|
+
pendingStderr.length = 0;
|
|
97
|
+
pendingStderrBytes = 0;
|
|
98
|
+
const finishedAt = now();
|
|
99
|
+
const combined = Buffer.concat([stdoutTail, stderrTail]);
|
|
100
|
+
const tail = combined.length > TAIL_BYTES ? combined.subarray(combined.length - TAIL_BYTES) : combined;
|
|
101
|
+
resolveDone({
|
|
102
|
+
exitCode,
|
|
103
|
+
...(signal !== null ? { signal } : {}),
|
|
104
|
+
...(error !== undefined ? { error } : {}),
|
|
105
|
+
outputHash: degraded
|
|
106
|
+
? `sha256:${hash.digest('hex')}+${stderrHash.digest('hex')}`
|
|
107
|
+
: `sha256:${hash.digest('hex')}`,
|
|
108
|
+
stdoutBytes,
|
|
109
|
+
stderrBytes,
|
|
110
|
+
outputTail: tail.toString('utf8'),
|
|
111
|
+
startedAt,
|
|
112
|
+
finishedAt,
|
|
113
|
+
durationMs: finishedAt - startedAt,
|
|
114
|
+
});
|
|
115
|
+
};
|
|
116
|
+
let child;
|
|
117
|
+
try {
|
|
118
|
+
child = spawn(plan.command, plan.args, plan.options);
|
|
119
|
+
}
|
|
120
|
+
catch (e) {
|
|
121
|
+
finish(null, null, e instanceof Error ? e.message : String(e));
|
|
122
|
+
return { done, kill: async () => { } };
|
|
123
|
+
}
|
|
124
|
+
child.stdout?.on('data', (chunk) => {
|
|
125
|
+
hash.update(chunk);
|
|
126
|
+
stdoutBytes += chunk.length;
|
|
127
|
+
stdoutTail = appendTail(stdoutTail, chunk, RETAIN_CAP_BYTES);
|
|
128
|
+
});
|
|
129
|
+
child.stdout?.on('end', () => {
|
|
130
|
+
stdoutEnded = true;
|
|
131
|
+
if (!degraded)
|
|
132
|
+
for (const c of pendingStderr)
|
|
133
|
+
hash.update(c);
|
|
134
|
+
pendingStderr.length = 0;
|
|
135
|
+
pendingStderrBytes = 0;
|
|
136
|
+
});
|
|
137
|
+
child.stderr?.on('data', (chunk) => {
|
|
138
|
+
stderrHash.update(chunk); // always — this is the degraded fallback
|
|
139
|
+
if (!degraded) {
|
|
140
|
+
if (stdoutEnded) {
|
|
141
|
+
hash.update(chunk);
|
|
142
|
+
}
|
|
143
|
+
else if (pendingStderrBytes + chunk.length > RETAIN_CAP_BYTES) {
|
|
144
|
+
// Out-of-order stderr overflowed the cap: drop the held chunks and
|
|
145
|
+
// degrade — `hash` stays stdout-only, `stderrHash` has everything.
|
|
146
|
+
degraded = true;
|
|
147
|
+
pendingStderr.length = 0;
|
|
148
|
+
pendingStderrBytes = 0;
|
|
149
|
+
}
|
|
150
|
+
else {
|
|
151
|
+
pendingStderr.push(chunk);
|
|
152
|
+
pendingStderrBytes += chunk.length;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
stderrBytes += chunk.length;
|
|
156
|
+
stderrTail = appendTail(stderrTail, chunk, RETAIN_CAP_BYTES);
|
|
157
|
+
});
|
|
158
|
+
child.on('error', (e) => finish(null, null, e.message));
|
|
159
|
+
child.on('close', (code, signal) => finish(code, signal));
|
|
160
|
+
const kill = async () => {
|
|
161
|
+
if (settled || child.pid === undefined)
|
|
162
|
+
return;
|
|
163
|
+
const pid = child.pid;
|
|
164
|
+
try {
|
|
165
|
+
process.kill(-pid, 'SIGTERM'); // negative pid → the whole process group
|
|
166
|
+
}
|
|
167
|
+
catch {
|
|
168
|
+
// Group already gone (raced the close) — nothing to signal.
|
|
169
|
+
return;
|
|
170
|
+
}
|
|
171
|
+
// Grace, then a hard SIGKILL if it is still alive.
|
|
172
|
+
await Promise.race([done, sleep(graceMs)]);
|
|
173
|
+
if (settled)
|
|
174
|
+
return;
|
|
175
|
+
try {
|
|
176
|
+
process.kill(-pid, 'SIGKILL');
|
|
177
|
+
}
|
|
178
|
+
catch {
|
|
179
|
+
// Gone between the grace and now — fine.
|
|
180
|
+
}
|
|
181
|
+
};
|
|
182
|
+
return { done, kill };
|
|
183
|
+
},
|
|
184
|
+
};
|
|
185
|
+
}
|