owenloop 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +98 -25
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{add.d.ts → src/add.d.ts} +12 -40
  109. package/dist/{add.js → src/add.js} +11 -176
  110. package/dist/src/cli.d.ts +147 -0
  111. package/dist/{cli.js → src/cli.js} +1643 -353
  112. package/dist/src/credentials.d.ts +280 -0
  113. package/dist/src/credentials.js +697 -0
  114. package/dist/{defs.js → src/defs.js} +59 -36
  115. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  116. package/dist/{engine.js → src/engine.js} +29 -20
  117. package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
  118. package/dist/{hub.js → src/hub.js} +531 -1
  119. package/dist/{index.d.ts → src/index.d.ts} +3 -1
  120. package/dist/{index.js → src/index.js} +2 -1
  121. package/dist/src/lock.d.ts +80 -0
  122. package/dist/src/lock.js +217 -0
  123. package/dist/src/mcp/serve.d.ts +85 -0
  124. package/dist/src/mcp/serve.js +702 -0
  125. package/dist/src/mcp/server.d.ts +132 -0
  126. package/dist/src/mcp/server.js +327 -0
  127. package/dist/{model.d.ts → src/model.d.ts} +59 -4
  128. package/dist/{model.js → src/model.js} +149 -22
  129. package/dist/{types.d.ts → src/types.d.ts} +66 -24
  130. package/dist/{util.d.ts → src/util.d.ts} +25 -0
  131. package/dist/{util.js → src/util.js} +26 -0
  132. package/dist/src/work-settings.d.ts +57 -0
  133. package/dist/src/work-settings.js +84 -0
  134. package/docs/authoring.md +102 -53
  135. package/docs/cli.md +883 -29
  136. package/docs/design.md +119 -45
  137. package/docs/embedding.md +39 -14
  138. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  139. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  140. package/examples/workflows/judges/gate-sharpness.md +39 -0
  141. package/examples/workflows/judges/security.md +34 -0
  142. package/package.json +17 -8
  143. package/dist/cli.d.ts +0 -83
  144. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  145. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  146. /package/dist/{factory.js → src/factory.js} +0 -0
  147. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  148. /package/dist/{paths.js → src/paths.js} +0 -0
  149. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  150. /package/dist/{schema.js → src/schema.js} +0 -0
  151. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  152. /package/dist/{store.js → src/store.js} +0 -0
  153. /package/dist/{types.js → src/types.js} +0 -0
  154. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  155. /package/dist/{untar.js → src/untar.js} +0 -0
@@ -0,0 +1,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 {};