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
package/dist/src/lock.js
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Generic advisory FILE LOCK — an exclusive-create lockfile with liveness-aware
|
|
3
|
+
* staleness, used to serialize a filesystem critical section across owenloop
|
|
4
|
+
* processes.
|
|
5
|
+
*
|
|
6
|
+
* Extracted verbatim (logic-identical) from `src/add.ts`'s per-project install
|
|
7
|
+
* lock: `add.ts` now consumes it through thin `acquireInstallLock` /
|
|
8
|
+
* `releaseInstallLock` wrappers that preserve the old names, types, and the
|
|
9
|
+
* "owenloop add" timeout wording; `src/credentials.ts` uses it to serialize the
|
|
10
|
+
* OAuth refresh-and-persist critical section (`credentials.lock`). The only
|
|
11
|
+
* behavioral addition during the move is the optional `label` (used in the
|
|
12
|
+
* timeout message) so each caller names itself.
|
|
13
|
+
*
|
|
14
|
+
* Depends only on node builtins so the library barrel (`src/index.ts` →
|
|
15
|
+
* `credentials.ts` → here) never drags the `add`/`untar` graph into its runtime
|
|
16
|
+
* closure.
|
|
17
|
+
*/
|
|
18
|
+
import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
|
|
19
|
+
import { dirname } from 'node:path';
|
|
20
|
+
import { randomBytes } from 'node:crypto';
|
|
21
|
+
import { hostname } from 'node:os';
|
|
22
|
+
import { setTimeout as sleep } from 'node:timers/promises';
|
|
23
|
+
/** Default wait/stale/poll timings for a file lock (overridable per acquire). */
|
|
24
|
+
const LOCK_WAIT_MS = 10_000;
|
|
25
|
+
const LOCK_STALE_MS = 10 * 60_000;
|
|
26
|
+
const LOCK_POLL_MS = 100;
|
|
27
|
+
/**
|
|
28
|
+
* Thrown by `acquireFileLock` when it gives up after `waitMs` on a lock a live
|
|
29
|
+
* owner still holds. A subclass of `Error` (not a plain `Error`) so a caller can
|
|
30
|
+
* `instanceof`-distinguish a clean timeout from a real filesystem failure (an
|
|
31
|
+
* EACCES/EROFS from the exclusive create) and map only the timeout to its own
|
|
32
|
+
* domain error — while `.message` stays byte-identical to the pre-extraction
|
|
33
|
+
* plain-`Error` message the `add` tests assert on.
|
|
34
|
+
*/
|
|
35
|
+
export class FileLockTimeoutError extends Error {
|
|
36
|
+
lockPath;
|
|
37
|
+
holderPid;
|
|
38
|
+
waitMs;
|
|
39
|
+
constructor(message, lockPath, holderPid, waitMs) {
|
|
40
|
+
super(message);
|
|
41
|
+
this.name = 'FileLockTimeoutError';
|
|
42
|
+
this.lockPath = lockPath;
|
|
43
|
+
this.holderPid = holderPid;
|
|
44
|
+
this.waitMs = waitMs;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
/** `true` if a process with `pid` exists (signal 0 probes without delivering). */
|
|
48
|
+
function defaultIsPidAlive(pid) {
|
|
49
|
+
try {
|
|
50
|
+
process.kill(pid, 0);
|
|
51
|
+
return true;
|
|
52
|
+
}
|
|
53
|
+
catch (e) {
|
|
54
|
+
// EPERM: the process exists but we may not signal it — treat as alive.
|
|
55
|
+
// ESRCH (and anything else): no such process — dead.
|
|
56
|
+
return e.code === 'EPERM';
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
/** Read the lock file's raw bytes, or `null` if it is gone/unreadable. */
|
|
60
|
+
function readLockRaw(lockPath) {
|
|
61
|
+
try {
|
|
62
|
+
return readFileSync(lockPath, 'utf8');
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
return null;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
/** Parse raw lock bytes into a holder, or `null` if absent/unparseable. */
|
|
69
|
+
function parseLockHolder(raw) {
|
|
70
|
+
if (raw === null)
|
|
71
|
+
return null;
|
|
72
|
+
try {
|
|
73
|
+
return JSON.parse(raw);
|
|
74
|
+
}
|
|
75
|
+
catch {
|
|
76
|
+
return null;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/** Read + parse the lock file in one step (fresh read). Used off the hot loop. */
|
|
80
|
+
function readLockHolder(lockPath) {
|
|
81
|
+
return parseLockHolder(readLockRaw(lockPath));
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Decide whether the lock described by `holder` (parsed from a raw read) may be
|
|
85
|
+
* reclaimed, given the current host. Liveness-aware, not age-based:
|
|
86
|
+
*
|
|
87
|
+
* 1. `statSync` fails — the lock vanished mid-judgment → treat as reclaimable
|
|
88
|
+
* (the acquire loop re-verifies and simply retries the exclusive create).
|
|
89
|
+
* 2. Holder records a `host` that differs from ours → NOT stale, ever. A
|
|
90
|
+
* foreign PID space means `process.kill(pid, 0)` proves nothing; a shared
|
|
91
|
+
* filesystem could be locked by another machine. Held; caller refuses.
|
|
92
|
+
* 3. Holder has a numeric `pid` and either matches our host or omits `host`
|
|
93
|
+
* (a legacy same-machine payload) → stale iff that pid is dead. Age never
|
|
94
|
+
* reclaims a live-pid lock — this is the core safety policy.
|
|
95
|
+
* 4. Unparseable, or parses without a numeric pid → fail closed: held until
|
|
96
|
+
* `now() - mtimeMs > staleMs` (age is the only abandonment signal left).
|
|
97
|
+
*/
|
|
98
|
+
function lockIsStale(lockPath, holder, staleMs, isPidAlive, now, currentHost) {
|
|
99
|
+
let mtimeMs;
|
|
100
|
+
try {
|
|
101
|
+
mtimeMs = statSync(lockPath).mtimeMs;
|
|
102
|
+
}
|
|
103
|
+
catch {
|
|
104
|
+
// Vanished between the EEXIST and here — someone else reclaimed it; retry.
|
|
105
|
+
return true;
|
|
106
|
+
}
|
|
107
|
+
// Case 2: recorded on a different host — its pid tells us nothing. Held.
|
|
108
|
+
if (holder && typeof holder.host === 'string' && holder.host !== currentHost) {
|
|
109
|
+
return false;
|
|
110
|
+
}
|
|
111
|
+
// Case 3: same host (or legacy no-host payload) with a numeric pid — liveness decides.
|
|
112
|
+
if (holder && typeof holder.pid === 'number') {
|
|
113
|
+
return !isPidAlive(holder.pid);
|
|
114
|
+
}
|
|
115
|
+
// Case 4: no attributable live owner — age is the only abandonment signal.
|
|
116
|
+
return now() - mtimeMs > staleMs;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Acquire the file lock at `lockPath` (an exclusive-create of the file,
|
|
120
|
+
* `openSync(..,'wx')` — the O_EXCL create is the real serialization point). The
|
|
121
|
+
* payload carries an ownership token, the owner pid, a start timestamp, and the
|
|
122
|
+
* host. If another process holds it: reclaim it only when liveness-aware
|
|
123
|
+
* staleness says its owner is gone (see `lockIsStale`), otherwise poll until it
|
|
124
|
+
* frees, and if it does not free within `waitMs` throw a `FileLockTimeoutError`.
|
|
125
|
+
* Always pair with `releaseFileLock` in a `finally`.
|
|
126
|
+
*/
|
|
127
|
+
export async function acquireFileLock(lockPath, opts = {}) {
|
|
128
|
+
const waitMs = opts.waitMs ?? LOCK_WAIT_MS;
|
|
129
|
+
const staleMs = opts.staleMs ?? LOCK_STALE_MS;
|
|
130
|
+
const pollMs = opts.pollMs ?? LOCK_POLL_MS;
|
|
131
|
+
const isPidAlive = opts.isPidAlive ?? defaultIsPidAlive;
|
|
132
|
+
const now = opts.now ?? Date.now;
|
|
133
|
+
const host = (opts.hostname ?? hostname)();
|
|
134
|
+
const label = opts.label ?? 'owenloop process';
|
|
135
|
+
mkdirSync(dirname(lockPath), { recursive: true });
|
|
136
|
+
const deadline = now() + waitMs;
|
|
137
|
+
for (;;) {
|
|
138
|
+
try {
|
|
139
|
+
const fd = openSync(lockPath, 'wx');
|
|
140
|
+
const token = randomBytes(16).toString('hex');
|
|
141
|
+
try {
|
|
142
|
+
writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: now(), token, host }));
|
|
143
|
+
}
|
|
144
|
+
finally {
|
|
145
|
+
closeSync(fd);
|
|
146
|
+
}
|
|
147
|
+
return { lockPath, acquired: true, token };
|
|
148
|
+
}
|
|
149
|
+
catch (e) {
|
|
150
|
+
if (e.code !== 'EEXIST')
|
|
151
|
+
throw e;
|
|
152
|
+
}
|
|
153
|
+
// Judge staleness from a single captured raw read...
|
|
154
|
+
const raw = readLockRaw(lockPath);
|
|
155
|
+
const holder = parseLockHolder(raw);
|
|
156
|
+
if (lockIsStale(lockPath, holder, staleMs, isPidAlive, now, host)) {
|
|
157
|
+
// ...then re-verify the bytes are unchanged immediately before deleting.
|
|
158
|
+
// Between judging stale and rmSync a third process could reclaim and
|
|
159
|
+
// re-create the lock; deleting then would destroy a *fresh* owner's lock.
|
|
160
|
+
// Residual window is a few syscalls (read-compare-delete) rather than the
|
|
161
|
+
// poll interval — and the `wx` create below is the true arbiter: if two
|
|
162
|
+
// reclaimers race, one wins the create and the other loops on EEXIST. A
|
|
163
|
+
// rename-based reclaim was rejected: POSIX rename clobbers its target, so
|
|
164
|
+
// any "rename back on mismatch" arm can itself destroy a newer lock.
|
|
165
|
+
const raw2 = readLockRaw(lockPath);
|
|
166
|
+
if (raw2 !== null && raw2 === raw) {
|
|
167
|
+
rmSync(lockPath, { force: true });
|
|
168
|
+
continue; // reclaimed — retry the exclusive create
|
|
169
|
+
}
|
|
170
|
+
// Bytes changed under us, or the lock is stat-able but unreadable (a
|
|
171
|
+
// root-owned 0600 lock: statSync needs only dir perms, readFileSync
|
|
172
|
+
// EACCES → raw/raw2 null). Do NOT delete — fall through to the deadline
|
|
173
|
+
// check and poll sleep below. Never `continue` here: with an unreadable,
|
|
174
|
+
// backdated lock this branch would otherwise spin sleeplessly, starving
|
|
175
|
+
// the event loop and never enforcing `waitMs`.
|
|
176
|
+
}
|
|
177
|
+
if (now() >= deadline) {
|
|
178
|
+
throw new FileLockTimeoutError(inProgressMessage(lockPath, holder, waitMs, label), lockPath, typeof holder?.pid === 'number' ? holder.pid : undefined, waitMs);
|
|
179
|
+
}
|
|
180
|
+
await sleep(pollMs);
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
/** Build the clear "another … is in progress" timeout error text, with graceful fallbacks. */
|
|
184
|
+
function inProgressMessage(lockPath, holder, waitMs, label) {
|
|
185
|
+
const who = typeof holder?.pid === 'number' ? `pid ${holder.pid}` : 'another process';
|
|
186
|
+
// Lock content is untrusted input: a finite `startedAt` outside the ECMAScript
|
|
187
|
+
// Date range (|t| > 8.64e15 ms) makes `new Date(t).toISOString()` throw
|
|
188
|
+
// RangeError. Only render held-since when the value is a valid time value;
|
|
189
|
+
// otherwise omit it (same graceful fallback as an absent startedAt).
|
|
190
|
+
const heldSince = typeof holder?.startedAt === 'number' &&
|
|
191
|
+
Number.isFinite(holder.startedAt) &&
|
|
192
|
+
Math.abs(holder.startedAt) <= 8.64e15
|
|
193
|
+
? `, held since ${new Date(holder.startedAt).toISOString()}`
|
|
194
|
+
: '';
|
|
195
|
+
const s = Math.round(waitMs / 1000);
|
|
196
|
+
return `another ${label} is in progress (${who}${heldSince}) — holds ${lockPath}; timed out waiting after ${s}s`;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Release a lock acquired by `acquireFileLock`. Token-checked and best-effort: a
|
|
200
|
+
* no-op if not acquired, if the lock is already gone/unparseable, or if its
|
|
201
|
+
* token no longer matches this handle (someone else legitimately re-acquired it
|
|
202
|
+
* — deleting would steal *their* lock). Never throws; it runs in a `finally` and
|
|
203
|
+
* must not mask the real error.
|
|
204
|
+
*/
|
|
205
|
+
export function releaseFileLock(handle) {
|
|
206
|
+
if (!handle.acquired)
|
|
207
|
+
return;
|
|
208
|
+
try {
|
|
209
|
+
const holder = readLockHolder(handle.lockPath);
|
|
210
|
+
if (!holder || holder.token !== handle.token)
|
|
211
|
+
return;
|
|
212
|
+
rmSync(handle.lockPath, { force: true });
|
|
213
|
+
}
|
|
214
|
+
catch {
|
|
215
|
+
// Already reclaimed/replaced, or an unexpected fs error — swallow.
|
|
216
|
+
}
|
|
217
|
+
}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `owenloop mcp` — the owenloop-cli-mcp stdio control-plane surface (O2).
|
|
3
|
+
*
|
|
4
|
+
* TWO-PLANE MODEL (identity-and-setup-model doc, §5/§6/§8, in the
|
|
5
|
+
* owenloop-service repo): owenloop runs two distinct planes. The HUMAN control
|
|
6
|
+
* plane is the everyday operator surface — starting runs, answering gates,
|
|
7
|
+
* pushing defs — and it authenticates as the logged-in human. The AGENT plane
|
|
8
|
+
* is what a Step Agent uses with its own `olp_` bearer. This module
|
|
9
|
+
* serves the HUMAN plane to a local MCP host (Claude Code) over stdio: it reads
|
|
10
|
+
* newline-delimited JSON-RPC 2.0 on stdin, translates each `tools/call` into one
|
|
11
|
+
* authenticated HTTPS request to the hub's `/api/*` REST mirror, and writes the
|
|
12
|
+
* JSON-RPC reply on stdout. It is spawned by hosts, never run by a human at a
|
|
13
|
+
* prompt.
|
|
14
|
+
*
|
|
15
|
+
* The model doc's cardinal rule (§6): the MODEL must never see a live token.
|
|
16
|
+
* Two consequences are load-bearing here:
|
|
17
|
+
* 1. Every hub call reads the stored `human` credential fresh and refreshes it
|
|
18
|
+
* through O1's locked path (`ensureFreshOAuth`/`refreshOAuth` in
|
|
19
|
+
* `src/credentials.ts`); the bearer only ever rides the `Authorization`
|
|
20
|
+
* header, never a tool result. The server holds NO credential state between
|
|
21
|
+
* calls — its only state is the resolved origin and the fixed tool list.
|
|
22
|
+
* 2. `create_agent` MINTS an `olp_` agent token and writes it straight to the
|
|
23
|
+
* local store (`storeCredential`, slot `agent:<name>`, caller-chosen scopes,
|
|
24
|
+
* default `['work']`);
|
|
25
|
+
* the token is NEVER returned in a tool result, printed, or logged. The
|
|
26
|
+
* mint response body carries the plaintext in TWO fields (`data.token` AND
|
|
27
|
+
* the human `text` "Store this secret now…"), so the handler builds its
|
|
28
|
+
* result object FROM SCRATCH (`{name, crews, stored:true}`) and never
|
|
29
|
+
* passes any field of the raw body outbound.
|
|
30
|
+
*
|
|
31
|
+
* The transport core is in `./server.ts` (a copy of owenloop's; see its header).
|
|
32
|
+
* Everything owenloop-specific — origin resolution, the authenticated hub
|
|
33
|
+
* client, the tool registrations, the enrollment capability gate, and the
|
|
34
|
+
* command body — lives here.
|
|
35
|
+
*/
|
|
36
|
+
import type { CredentialIO } from '../credentials.ts';
|
|
37
|
+
import type { LineStream } from './server.ts';
|
|
38
|
+
/**
|
|
39
|
+
* The IO surface `runMcpCommand` needs — a strict subset of the CLI's `CliIO`,
|
|
40
|
+
* which structurally satisfies it, so `dispatchMcp` passes its `io` unchanged.
|
|
41
|
+
* `stdinStream` is the injectable transport (tests feed a `PassThrough`; the
|
|
42
|
+
* command falls back to `process.stdin`).
|
|
43
|
+
*/
|
|
44
|
+
export interface McpIo extends CredentialIO {
|
|
45
|
+
out: (line: string) => void;
|
|
46
|
+
err: (line: string) => void;
|
|
47
|
+
stdinStream?: LineStream;
|
|
48
|
+
}
|
|
49
|
+
/** The exit-2 ambiguity outcome; the caller prints `message` to stderr and returns 2. */
|
|
50
|
+
type OriginResolution = {
|
|
51
|
+
origin: string;
|
|
52
|
+
} | {
|
|
53
|
+
exitCode: 2;
|
|
54
|
+
message: string;
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* Resolve the hub origin this server binds to, precedence:
|
|
58
|
+
* 1. `--hub <origin>` flag,
|
|
59
|
+
* 2. `OWENLOOP_HUB` env,
|
|
60
|
+
* 3. if the FILE credential backend holds exactly ONE hub with a valid `human`
|
|
61
|
+
* slot, use it,
|
|
62
|
+
* 4. else exit 2 with a message naming BOTH remedies.
|
|
63
|
+
*
|
|
64
|
+
* Rungs 1–2 normalize the origin (a malformed value throws a `CliError` → the
|
|
65
|
+
* command's exit-1 path via `mainAsync`'s catch, matching every other command).
|
|
66
|
+
* Rung 3 is file-backend-only because only the file backend can enumerate
|
|
67
|
+
* (`listStoredHubOrigins`); `null` (cannot enumerate — keychain/external), `[]`
|
|
68
|
+
* (nothing stored), and length>1 (ambiguous) each get a tailored exit-2 message.
|
|
69
|
+
*
|
|
70
|
+
* DELIBERATELY there is NO silent production fallback (the CLI's `resolveHub`
|
|
71
|
+
* `DEFAULT_HUB` rung): a control-plane server must never bind to a hub the
|
|
72
|
+
* operator did not name.
|
|
73
|
+
*/
|
|
74
|
+
export declare function resolveMcpOrigin(io: McpIo, hubFlag: string | undefined): OriginResolution;
|
|
75
|
+
/**
|
|
76
|
+
* Run the `owenloop mcp` command: resolve the origin, decide the enrollment
|
|
77
|
+
* gate, build the tool list, construct the JSON-RPC server, and pump stdin until
|
|
78
|
+
* EOF. Returns the process exit code: 2 on an origin-ambiguity (message to
|
|
79
|
+
* stderr, nothing to stdout — stdout is the protocol channel), else 0 on stdin
|
|
80
|
+
* EOF. A malformed `--hub`/`OWENLOOP_HUB` throws a `CliError` (exit-1 path).
|
|
81
|
+
*/
|
|
82
|
+
export declare function runMcpCommand(io: McpIo, opts: {
|
|
83
|
+
hubFlag?: string;
|
|
84
|
+
}): Promise<number>;
|
|
85
|
+
export {};
|