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
|
@@ -9,6 +9,8 @@
|
|
|
9
9
|
* unit-testable and `cli.ts` doesn't widen its export surface just to reuse
|
|
10
10
|
* `Args`/`CliError`/etc.
|
|
11
11
|
*/
|
|
12
|
+
import { releaseFileLock } from './lock.ts';
|
|
13
|
+
import type { AcquireFileLockOpts, FileLockHandle } from './lock.ts';
|
|
12
14
|
/**
|
|
13
15
|
* Returns `undefined` if `relPath` is safe to `join()` under a destination
|
|
14
16
|
* directory, else a human-readable reason it must be rejected. This is
|
|
@@ -234,49 +236,19 @@ export declare function finalizeInstallCommit(handle: InstallCommitHandle): void
|
|
|
234
236
|
* happened" state to reconcile (the park is one atomic rename).
|
|
235
237
|
*/
|
|
236
238
|
export declare function rollbackInstallCommit(handle: InstallCommitHandle): void;
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
token?: string;
|
|
242
|
-
}
|
|
243
|
-
export interface AcquireLockOpts {
|
|
244
|
-
/** Max time to wait for a live lock before failing cleanly (default 10s). */
|
|
245
|
-
waitMs?: number;
|
|
246
|
-
/**
|
|
247
|
-
* Age (by mtime) past which an *unparseable/abandoned* lock may be reclaimed
|
|
248
|
-
* (default 10m). Age NEVER reclaims a lock whose recorded pid is alive on
|
|
249
|
-
* this host — it only governs the fail-closed fallback for a lock we cannot
|
|
250
|
-
* attribute to a live owner (unparseable payload, or one without a pid).
|
|
251
|
-
*/
|
|
252
|
-
staleMs?: number;
|
|
253
|
-
/** Poll interval while waiting on a live lock (default 100ms). */
|
|
254
|
-
pollMs?: number;
|
|
255
|
-
/** Liveness probe for the holder pid — injectable so tests are deterministic. */
|
|
256
|
-
isPidAlive?: (pid: number) => boolean;
|
|
257
|
-
/** Clock — injectable so tests are deterministic. */
|
|
258
|
-
now?: () => number;
|
|
259
|
-
/** Current hostname — injectable so cross-host tests are deterministic (default `os.hostname`). */
|
|
260
|
-
hostname?: () => string;
|
|
261
|
-
}
|
|
239
|
+
/** The install lock handle — now the generic `FileLockHandle` from `lock.ts`. */
|
|
240
|
+
export type InstallLockHandle = FileLockHandle;
|
|
241
|
+
/** The install lock acquire options — now the generic `AcquireFileLockOpts` from `lock.ts`. */
|
|
242
|
+
export type AcquireLockOpts = AcquireFileLockOpts;
|
|
262
243
|
/**
|
|
263
|
-
* Acquire the per-project install lock at `lockPath
|
|
264
|
-
*
|
|
265
|
-
*
|
|
266
|
-
*
|
|
267
|
-
* staleness says its owner is gone (see `lockIsStale`), otherwise poll until it
|
|
268
|
-
* frees, and if it does not free within `waitMs` fail cleanly with a clear
|
|
269
|
-
* in-progress message. Always pair with `releaseInstallLock` in a `finally`.
|
|
244
|
+
* Acquire the per-project install lock at `lockPath`. A 1-line adapter over the
|
|
245
|
+
* generic `acquireFileLock`, pinning `label` so the timeout message reads
|
|
246
|
+
* "another owenloop add is in progress …" byte-for-byte as before. Always pair
|
|
247
|
+
* with `releaseInstallLock` in a `finally`.
|
|
270
248
|
*/
|
|
271
249
|
export declare function acquireInstallLock(lockPath: string, opts?: AcquireLockOpts): Promise<InstallLockHandle>;
|
|
272
|
-
/**
|
|
273
|
-
|
|
274
|
-
* best-effort: a no-op if not acquired, if the lock is already gone/unparseable,
|
|
275
|
-
* or if its token no longer matches this handle (someone else legitimately
|
|
276
|
-
* re-acquired it — deleting would steal *their* lock). Never throws; it runs in
|
|
277
|
-
* `dispatchAdd`'s `finally` and must not mask the real error.
|
|
278
|
-
*/
|
|
279
|
-
export declare function releaseInstallLock(handle: InstallLockHandle): void;
|
|
250
|
+
/** Release a lock acquired by `acquireInstallLock` — the generic `releaseFileLock`. */
|
|
251
|
+
export declare const releaseInstallLock: typeof releaseFileLock;
|
|
280
252
|
/** Journal filename under `.owenloop/` (sibling of `installed.json`/`add.lock`). */
|
|
281
253
|
export declare const ADD_JOURNAL_FILENAME = "add.journal";
|
|
282
254
|
/**
|
|
@@ -9,11 +9,10 @@
|
|
|
9
9
|
* unit-testable and `cli.ts` doesn't widen its export surface just to reuse
|
|
10
10
|
* `Args`/`CliError`/etc.
|
|
11
11
|
*/
|
|
12
|
-
import {
|
|
12
|
+
import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
|
|
13
13
|
import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
|
|
14
|
-
import { createHash
|
|
15
|
-
import {
|
|
16
|
-
import { setTimeout as sleep } from 'node:timers/promises';
|
|
14
|
+
import { createHash } from 'node:crypto';
|
|
15
|
+
import { acquireFileLock, releaseFileLock } from "./lock.js";
|
|
17
16
|
/** Max length for an in-archive relative path we are willing to join and write. */
|
|
18
17
|
const MAX_ARCHIVE_PATH_LENGTH = 1024;
|
|
19
18
|
/**
|
|
@@ -427,181 +426,17 @@ export function rollbackInstallCommit(handle) {
|
|
|
427
426
|
if (handle.oldName)
|
|
428
427
|
renameSync(handle.oldName.parkedAt, handle.oldName.originalPath);
|
|
429
428
|
}
|
|
430
|
-
// ---- per-project install lock ----------------------------------------------
|
|
431
|
-
/** Default wait/stale/poll timings for the install lock (overridable in tests). */
|
|
432
|
-
const LOCK_WAIT_MS = 10_000;
|
|
433
|
-
const LOCK_STALE_MS = 10 * 60_000;
|
|
434
|
-
const LOCK_POLL_MS = 100;
|
|
435
|
-
/** `true` if a process with `pid` exists (signal 0 probes without delivering). */
|
|
436
|
-
function defaultIsPidAlive(pid) {
|
|
437
|
-
try {
|
|
438
|
-
process.kill(pid, 0);
|
|
439
|
-
return true;
|
|
440
|
-
}
|
|
441
|
-
catch (e) {
|
|
442
|
-
// EPERM: the process exists but we may not signal it — treat as alive.
|
|
443
|
-
// ESRCH (and anything else): no such process — dead.
|
|
444
|
-
return e.code === 'EPERM';
|
|
445
|
-
}
|
|
446
|
-
}
|
|
447
|
-
/** Read the lock file's raw bytes, or `null` if it is gone/unreadable. */
|
|
448
|
-
function readLockRaw(lockPath) {
|
|
449
|
-
try {
|
|
450
|
-
return readFileSync(lockPath, 'utf8');
|
|
451
|
-
}
|
|
452
|
-
catch {
|
|
453
|
-
return null;
|
|
454
|
-
}
|
|
455
|
-
}
|
|
456
|
-
/** Parse raw lock bytes into a holder, or `null` if absent/unparseable. */
|
|
457
|
-
function parseLockHolder(raw) {
|
|
458
|
-
if (raw === null)
|
|
459
|
-
return null;
|
|
460
|
-
try {
|
|
461
|
-
return JSON.parse(raw);
|
|
462
|
-
}
|
|
463
|
-
catch {
|
|
464
|
-
return null;
|
|
465
|
-
}
|
|
466
|
-
}
|
|
467
|
-
/** Read + parse the lock file in one step (fresh read). Used off the hot loop. */
|
|
468
|
-
function readLockHolder(lockPath) {
|
|
469
|
-
return parseLockHolder(readLockRaw(lockPath));
|
|
470
|
-
}
|
|
471
429
|
/**
|
|
472
|
-
*
|
|
473
|
-
*
|
|
474
|
-
*
|
|
475
|
-
*
|
|
476
|
-
* (the acquire loop re-verifies and simply retries the exclusive create).
|
|
477
|
-
* 2. Holder records a `host` that differs from ours → NOT stale, ever. A
|
|
478
|
-
* foreign PID space means `process.kill(pid, 0)` proves nothing; a shared
|
|
479
|
-
* filesystem could be locked by another machine. Held; caller refuses.
|
|
480
|
-
* 3. Holder has a numeric `pid` and either matches our host or omits `host`
|
|
481
|
-
* (a legacy same-machine payload) → stale iff that pid is dead. Age never
|
|
482
|
-
* reclaims a live-pid lock — this is the core safety policy.
|
|
483
|
-
* 4. Unparseable, or parses without a numeric pid → fail closed: held until
|
|
484
|
-
* `now() - mtimeMs > staleMs` (age is the only abandonment signal left).
|
|
430
|
+
* Acquire the per-project install lock at `lockPath`. A 1-line adapter over the
|
|
431
|
+
* generic `acquireFileLock`, pinning `label` so the timeout message reads
|
|
432
|
+
* "another owenloop add is in progress …" byte-for-byte as before. Always pair
|
|
433
|
+
* with `releaseInstallLock` in a `finally`.
|
|
485
434
|
*/
|
|
486
|
-
function
|
|
487
|
-
|
|
488
|
-
try {
|
|
489
|
-
mtimeMs = statSync(lockPath).mtimeMs;
|
|
490
|
-
}
|
|
491
|
-
catch {
|
|
492
|
-
// Vanished between the EEXIST and here — someone else reclaimed it; retry.
|
|
493
|
-
return true;
|
|
494
|
-
}
|
|
495
|
-
// Case 2: recorded on a different host — its pid tells us nothing. Held.
|
|
496
|
-
if (holder && typeof holder.host === 'string' && holder.host !== currentHost) {
|
|
497
|
-
return false;
|
|
498
|
-
}
|
|
499
|
-
// Case 3: same host (or legacy no-host payload) with a numeric pid — liveness decides.
|
|
500
|
-
if (holder && typeof holder.pid === 'number') {
|
|
501
|
-
return !isPidAlive(holder.pid);
|
|
502
|
-
}
|
|
503
|
-
// Case 4: no attributable live owner — age is the only abandonment signal.
|
|
504
|
-
return now() - mtimeMs > staleMs;
|
|
505
|
-
}
|
|
506
|
-
/**
|
|
507
|
-
* Acquire the per-project install lock at `lockPath` (an exclusive-create of the
|
|
508
|
-
* file, `openSync(..,'wx')` — the O_EXCL create is the real serialization point).
|
|
509
|
-
* The payload carries an ownership token, the owner pid, a start timestamp, and
|
|
510
|
-
* the host. If another process holds it: reclaim it only when liveness-aware
|
|
511
|
-
* staleness says its owner is gone (see `lockIsStale`), otherwise poll until it
|
|
512
|
-
* frees, and if it does not free within `waitMs` fail cleanly with a clear
|
|
513
|
-
* in-progress message. Always pair with `releaseInstallLock` in a `finally`.
|
|
514
|
-
*/
|
|
515
|
-
export async function acquireInstallLock(lockPath, opts = {}) {
|
|
516
|
-
const waitMs = opts.waitMs ?? LOCK_WAIT_MS;
|
|
517
|
-
const staleMs = opts.staleMs ?? LOCK_STALE_MS;
|
|
518
|
-
const pollMs = opts.pollMs ?? LOCK_POLL_MS;
|
|
519
|
-
const isPidAlive = opts.isPidAlive ?? defaultIsPidAlive;
|
|
520
|
-
const now = opts.now ?? Date.now;
|
|
521
|
-
const host = (opts.hostname ?? hostname)();
|
|
522
|
-
mkdirSync(dirname(lockPath), { recursive: true });
|
|
523
|
-
const deadline = now() + waitMs;
|
|
524
|
-
for (;;) {
|
|
525
|
-
try {
|
|
526
|
-
const fd = openSync(lockPath, 'wx');
|
|
527
|
-
const token = randomBytes(16).toString('hex');
|
|
528
|
-
try {
|
|
529
|
-
writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: now(), token, host }));
|
|
530
|
-
}
|
|
531
|
-
finally {
|
|
532
|
-
closeSync(fd);
|
|
533
|
-
}
|
|
534
|
-
return { lockPath, acquired: true, token };
|
|
535
|
-
}
|
|
536
|
-
catch (e) {
|
|
537
|
-
if (e.code !== 'EEXIST')
|
|
538
|
-
throw e;
|
|
539
|
-
}
|
|
540
|
-
// Judge staleness from a single captured raw read...
|
|
541
|
-
const raw = readLockRaw(lockPath);
|
|
542
|
-
const holder = parseLockHolder(raw);
|
|
543
|
-
if (lockIsStale(lockPath, holder, staleMs, isPidAlive, now, host)) {
|
|
544
|
-
// ...then re-verify the bytes are unchanged immediately before deleting.
|
|
545
|
-
// Between judging stale and rmSync a third process could reclaim and
|
|
546
|
-
// re-create the lock; deleting then would destroy a *fresh* owner's lock.
|
|
547
|
-
// Residual window is a few syscalls (read-compare-delete) rather than the
|
|
548
|
-
// poll interval — and the `wx` create below is the true arbiter: if two
|
|
549
|
-
// reclaimers race, one wins the create and the other loops on EEXIST. A
|
|
550
|
-
// rename-based reclaim was rejected: POSIX rename clobbers its target, so
|
|
551
|
-
// any "rename back on mismatch" arm can itself destroy a newer lock.
|
|
552
|
-
const raw2 = readLockRaw(lockPath);
|
|
553
|
-
if (raw2 !== null && raw2 === raw) {
|
|
554
|
-
rmSync(lockPath, { force: true });
|
|
555
|
-
continue; // reclaimed — retry the exclusive create
|
|
556
|
-
}
|
|
557
|
-
// Bytes changed under us, or the lock is stat-able but unreadable (a
|
|
558
|
-
// root-owned 0600 lock: statSync needs only dir perms, readFileSync
|
|
559
|
-
// EACCES → raw/raw2 null). Do NOT delete — fall through to the deadline
|
|
560
|
-
// check and poll sleep below. Never `continue` here: with an unreadable,
|
|
561
|
-
// backdated lock this branch would otherwise spin sleeplessly, starving
|
|
562
|
-
// the event loop and never enforcing `waitMs`.
|
|
563
|
-
}
|
|
564
|
-
if (now() >= deadline) {
|
|
565
|
-
throw new Error(inProgressMessage(lockPath, holder, waitMs));
|
|
566
|
-
}
|
|
567
|
-
await sleep(pollMs);
|
|
568
|
-
}
|
|
569
|
-
}
|
|
570
|
-
/** Build the clear "another add is in progress" timeout error, with graceful fallbacks. */
|
|
571
|
-
function inProgressMessage(lockPath, holder, waitMs) {
|
|
572
|
-
const who = typeof holder?.pid === 'number' ? `pid ${holder.pid}` : 'another process';
|
|
573
|
-
// Lock content is untrusted input: a finite `startedAt` outside the ECMAScript
|
|
574
|
-
// Date range (|t| > 8.64e15 ms) makes `new Date(t).toISOString()` throw
|
|
575
|
-
// RangeError. Only render held-since when the value is a valid time value;
|
|
576
|
-
// otherwise omit it (same graceful fallback as an absent startedAt).
|
|
577
|
-
const heldSince = typeof holder?.startedAt === 'number' &&
|
|
578
|
-
Number.isFinite(holder.startedAt) &&
|
|
579
|
-
Math.abs(holder.startedAt) <= 8.64e15
|
|
580
|
-
? `, held since ${new Date(holder.startedAt).toISOString()}`
|
|
581
|
-
: '';
|
|
582
|
-
const s = Math.round(waitMs / 1000);
|
|
583
|
-
return `another owenloop add is in progress (${who}${heldSince}) — holds ${lockPath}; timed out waiting after ${s}s`;
|
|
584
|
-
}
|
|
585
|
-
/**
|
|
586
|
-
* Release a lock acquired by `acquireInstallLock`. Token-checked and
|
|
587
|
-
* best-effort: a no-op if not acquired, if the lock is already gone/unparseable,
|
|
588
|
-
* or if its token no longer matches this handle (someone else legitimately
|
|
589
|
-
* re-acquired it — deleting would steal *their* lock). Never throws; it runs in
|
|
590
|
-
* `dispatchAdd`'s `finally` and must not mask the real error.
|
|
591
|
-
*/
|
|
592
|
-
export function releaseInstallLock(handle) {
|
|
593
|
-
if (!handle.acquired)
|
|
594
|
-
return;
|
|
595
|
-
try {
|
|
596
|
-
const holder = readLockHolder(handle.lockPath);
|
|
597
|
-
if (!holder || holder.token !== handle.token)
|
|
598
|
-
return;
|
|
599
|
-
rmSync(handle.lockPath, { force: true });
|
|
600
|
-
}
|
|
601
|
-
catch {
|
|
602
|
-
// Already reclaimed/replaced, or an unexpected fs error — swallow.
|
|
603
|
-
}
|
|
435
|
+
export function acquireInstallLock(lockPath, opts = {}) {
|
|
436
|
+
return acquireFileLock(lockPath, { label: 'owenloop add', ...opts });
|
|
604
437
|
}
|
|
438
|
+
/** Release a lock acquired by `acquireInstallLock` — the generic `releaseFileLock`. */
|
|
439
|
+
export const releaseInstallLock = releaseFileLock;
|
|
605
440
|
// ---- crash-recovery journal ------------------------------------------------
|
|
606
441
|
//
|
|
607
442
|
// A process that dies (crash, SIGKILL — see docs/cli.md on power-loss limits)
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The owenloop CLI — a thin, scriptable surface over the engine.
|
|
3
|
+
*
|
|
4
|
+
* Every data command prints JSON to stdout, so a *wiring* (the Step Agent/automation
|
|
5
|
+
* that actually runs orders) can drive the engine programmatically: `tick` to
|
|
6
|
+
* pull orders, run them, then `green` / `emit` / `seal` / `reject` / `close` to
|
|
7
|
+
* report outcomes. The engine itself is domain-neutral; this binary just maps
|
|
8
|
+
* argv to engine calls.
|
|
9
|
+
*
|
|
10
|
+
* owenloop defs list available workflow definitions
|
|
11
|
+
* owenloop add <owner>/<repo>[@ref] fetch, validate, and install a repo's workflow defs (public repos)
|
|
12
|
+
* owenloop create <def> [--provide n=json] [--title t] start an instance
|
|
13
|
+
* owenloop provide <wf> <name> [--value json] supply an owed input
|
|
14
|
+
* owenloop tick <wf> [--now ms] pull eligible orders
|
|
15
|
+
* owenloop reap <wf> [--now] run the reaper; --now forces every claim stale (TTL 0)
|
|
16
|
+
* owenloop runs <wf> [--open] list this instance's runs (+ claim state for open ones)
|
|
17
|
+
* owenloop status <wf> derive debts / eligible / blocked
|
|
18
|
+
* owenloop status --all every instance's status in one call (fleet read)
|
|
19
|
+
* owenloop wait <wf> --until eligible|done [--timeout <dur>] block until engine state matches
|
|
20
|
+
* owenloop show <wf> dump raw artifacts (debugging)
|
|
21
|
+
* owenloop list list instances
|
|
22
|
+
* owenloop green <wf> <run> <path> [--value json] [--terminal]
|
|
23
|
+
* owenloop emit <wf> <run> --items '[{...},{...}]'
|
|
24
|
+
* owenloop seal <wf> <run> [--value json]
|
|
25
|
+
* owenloop reject <wf> <path> --by <author> --text <msg>
|
|
26
|
+
* owenloop retract <wf> <path> --by <author> --text <msg>
|
|
27
|
+
* owenloop skip <wf> <path> --by <author> --text <msg>
|
|
28
|
+
* owenloop retry <wf> <path> [--by <author>] [--text <guidance>] clear a stall
|
|
29
|
+
* owenloop close <wf> <run> [--outcome ok|no_work|failed|skipped] [--summary s]
|
|
30
|
+
* owenloop delete <wf> [--recursive]
|
|
31
|
+
*
|
|
32
|
+
* Global: --db <path> (env OWENLOOP_DB), --defs <dir> (env OWENLOOP_DEFS).
|
|
33
|
+
*/
|
|
34
|
+
import type { CheckReport } from './types.ts';
|
|
35
|
+
import type { LineStream } from './mcp/server.ts';
|
|
36
|
+
import type { AgentIdentitySummary, Keychain } from './hub.ts';
|
|
37
|
+
export type { Keychain } from './hub.ts';
|
|
38
|
+
export interface CliIO {
|
|
39
|
+
cwd: string;
|
|
40
|
+
env: Record<string, string | undefined>;
|
|
41
|
+
out: (line: string) => void;
|
|
42
|
+
err: (line: string) => void;
|
|
43
|
+
/** Injectable for hermetic tests — the network-touching verbs (`add`, hub commands) use this. */
|
|
44
|
+
fetch?: typeof globalThis.fetch;
|
|
45
|
+
/** Open a URL in the user's browser (login). Default: fire-and-forget `open`/`xdg-open`/`start`. */
|
|
46
|
+
openUrl?: (url: string) => void;
|
|
47
|
+
/**
|
|
48
|
+
* OS keychain backend for credential storage. The backend is chosen ONCE per
|
|
49
|
+
* process (see `credentialBackend`), then used for read/write/delete
|
|
50
|
+
* consistently: a `security`-backed keychain on macOS, else the 0600 file
|
|
51
|
+
* store. `undefined` here — non-mac, or `OWENLOOP_NO_KEYCHAIN=1` — selects
|
|
52
|
+
* the file backend. A keychain write failure is a hard error, never a silent
|
|
53
|
+
* file fallback (REL-6).
|
|
54
|
+
*/
|
|
55
|
+
keychain?: Keychain;
|
|
56
|
+
/** Read a secret from stdin (`login --with-token`). Default: drain `process.stdin`. */
|
|
57
|
+
readStdin?: () => Promise<string>;
|
|
58
|
+
/**
|
|
59
|
+
* The newline-delimited transport `owenloop mcp` pumps JSON-RPC frames from.
|
|
60
|
+
* Injectable for hermetic tests (a `PassThrough`); `undefined` here so the
|
|
61
|
+
* command falls back to `process.stdin`. Only the `mcp` verb reads it.
|
|
62
|
+
*/
|
|
63
|
+
stdinStream?: LineStream;
|
|
64
|
+
/**
|
|
65
|
+
* Ask the user a question and read a line back. Used only by `setup`'s
|
|
66
|
+
* interactive branches (name-this-agent, succession choice). Default: a
|
|
67
|
+
* `node:readline/promises` interface over `process.stdin`/`process.stderr` —
|
|
68
|
+
* the question and echo go to STDERR so stdout stays a clean machine-parseable
|
|
69
|
+
* JSON document (the repo's diagnostics-to-stderr convention). Injectable so
|
|
70
|
+
* tests script answers without a TTY.
|
|
71
|
+
*/
|
|
72
|
+
prompt?: (question: string) => Promise<string>;
|
|
73
|
+
/**
|
|
74
|
+
* Run a local command and capture its result — used ONLY by `setup`/`doctor`'s
|
|
75
|
+
* Claude Code plugin probe (`claude plugin list`). Default: a `spawnSync`
|
|
76
|
+
* wrapper with `shell: false` (never interpolates argv into a shell) that
|
|
77
|
+
* never inherits stdio. Injectable so tests model the plugin state without a
|
|
78
|
+
* real `claude` binary.
|
|
79
|
+
*/
|
|
80
|
+
runCommand?: (cmd: string, args: string[]) => {
|
|
81
|
+
status: number | null;
|
|
82
|
+
stdout: string;
|
|
83
|
+
stderr: string;
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
export declare const USAGE = "owenloop \u2014 a dataflow workflow engine\n\nUsage: owenloop <command> [args] [--db <path>] [--defs <dir>]\n\nCommands:\n defs list available workflow definitions\n add <owner>/<repo>[@ref] fetch, validate, and install a repo's workflow defs (public repos)\n add --recover finish or undo a crash-interrupted install (offline; no network)\n login [--hub <url>] [--with-token] [--as <slot>] authenticate the CLI against a hub, verified via whoami (loopback OAuth, or --with-token from stdin)\n logout [--hub <url>] [--as <slot>] delete the stored credential for a hub in one slot\n connect [--hub <url>] [--as <slot>] bind this project to a hub and verify the stored credential (whoami)\n push [<defName>...] [--force] [--dry-run] [--as <slot>] publish local workflow defs to the bound hub (server-diffed, idempotent)\n --as names the credential slot: human (default), agent, or agent:<account>\n agent new <name> [--crews <a,b>] [--scopes <a,b>] [--shift] [--hub <url>] mint a new Scoped Identity on the hub and store its token in slot agent:<name> (the token is never printed; --shift = --scopes work,run)\n capability bind <capability> <crew> [--hub <url>] add a crew to a workflow capability on the hub org \u2014 a capability may bind many crews (admin; human credential)\n capability unbind <capability> <crew> [--hub <url>] remove one (capability, crew) route\n capability list [--hub <url>] list the hub org's capability routes\n crew list [--hub <url>] list the hub org's crews with their members (includes the orphan crew once one exists)\n crew new <name> --kind personal|shared [--owner <memberId>] [--hub <url>] create a crew on the hub org (admin, or own personal crew; human credential)\n crew rm <crewId> [--hub <url>] delete a crew; work stamped to it moves to the org's orphan crew\n crew member add <crewId> <principalKind> <principalId> [--hub <url>] add a member or agent to a crew\n crew member rm <crewId> <principalId> [--hub <url>] remove a principal from a crew\n setup [--hub <url>] [--new-agent <name> | --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>] converge this machine's install: human login, agent credential, owenloop settings, plugin (idempotent)\n doctor [--hub <url>] check this machine's owenloop install and report each piece (read-only)\n mcp [--hub <url>] serve the hub control plane over stdio MCP (spawned by MCP hosts, not run by humans)\n work <subcommand> [args] run execution-side shift/hold/exec/agent-run/... commands\n shift start|next|status|end [args] run and attend a local Unix-socket shift daemon\n lint [<def-name>] check def(s) for wiring problems\n check <def> [--format text|json] [--max-depth N] [--max-states N] [--max-collection N] [--assume-provided] [--strict-inputs]\n bounded reachability check (stall states, true deadlocks, stuck, dead steps, declared invariants)\n create <def> [--title t] [--provide name=json ...] [--param k=v ...]\n provide <wf> <name> [--value json] supply an owed (seedOwed) input\n adopt <wf> re-pin an instance to the current def (\u00A728); settles new debts\n tick <wf> [--now <ms>] [--shallow] [--capability <c>]... pull eligible orders (deep: also from calls: children; --shallow for this instance only; --capability filters to matching-capability steps)\n reap <wf> [--now] run the reaper; --now forces every claim stale (TTL 0)\n runs <wf> [--open] list this instance's runs (+ claim state for open ones)\n order <wf> <run> print the order packet issued at claim time (persisted in the claim txn)\n status <wf> derive debts / eligible / blocked\n status --all every instance's status in one call (fleet read)\n wait <wf> --until eligible|done [--timeout <dur>] block until engine state matches\n show <wf> dump raw artifacts\n trace <wf> [--format text] causal timeline + artifact biographies\n graph <def-or-wf> [--format dot|mermaid|json] wiring graph (+ live overlay if wf id)\n list list workflow instances\n green <wf> <run> <path> [--value json] [--terminal]\n emit <wf> <run> --items '[{...}]' accrete collection elements\n seal <wf> <run> [--value json] signal a collection is complete\n reject <wf> <path> --by <author> --text <msg>\n retract <wf> <path> --by <author> --text <msg>\n skip <wf> <path> --by <author> --text <msg>\n retry <wf> <path> [--by <author>] [--text <guidance>] clear a \u00A76 stall\n heartbeat <wf> <run> [--now <ms>] touch liveness timestamp on an open run\n close <wf> <run> [--outcome ok|no_work|failed|skipped] [--summary s]\n delete <wf> [--recursive] refuse if children exist unless --recursive (cascades)\n\nEnvironment: OWENLOOP_DB, OWENLOOP_DEFS";
|
|
87
|
+
/**
|
|
88
|
+
* The single "definite defect" predicate over a modelCheck `report`, shared by
|
|
89
|
+
* `check`, `add` (dispatchAdd) and `push` (dispatchPush) so all three
|
|
90
|
+
* accept-or-reject a def identically. A pure function of the report object — it
|
|
91
|
+
* does NOT read or change how any caller seeded its modelCheck (add/push seed
|
|
92
|
+
* `assumeProvided: true`; check seeds `assumeProvided: !strictInputs`).
|
|
93
|
+
*
|
|
94
|
+
* invariant violations and structurally-dead steps are ALWAYS definite (sound
|
|
95
|
+
* regardless of bounds); a true deadlock counts ONLY when the search was
|
|
96
|
+
* exhaustive (`!bounded`) because a tight maxCollectionSize cap can manufacture
|
|
97
|
+
* a spurious one. `unreachedSteps` is deliberately EXCLUDED — it is a bounds
|
|
98
|
+
* artifact ("raise --max-states/--max-depth"), never a definite defect.
|
|
99
|
+
*/
|
|
100
|
+
export declare function hasDefiniteCheckDefect(report: CheckReport): boolean;
|
|
101
|
+
/**
|
|
102
|
+
* Single source of truth for the `--options` each command accepts, consulted by
|
|
103
|
+
* `preflight` before any side effect. Unknown-OPTION rejection AND
|
|
104
|
+
* unknown-COMMAND detection both derive from this table: a developer who adds a
|
|
105
|
+
* new `dispatch`/`ASYNC_COMMANDS` case without a matching entry here gets
|
|
106
|
+
* `unknown command` on the very first invocation, so the command cannot run
|
|
107
|
+
* until its flags are declared. That is the forcing function that stops the
|
|
108
|
+
* silently-dropped-flag hole (a misspelled `push --dryrn` doing a real push)
|
|
109
|
+
* from reappearing — keep this table in lockstep with the dispatch verbs and
|
|
110
|
+
* the USAGE string. All names are long-form: this CLI has no short options
|
|
111
|
+
* (`-h` reaches dispatch as a positional). Values are audited against every
|
|
112
|
+
* `last/all/flag/needOpt/numOpt` call site.
|
|
113
|
+
*/
|
|
114
|
+
export declare const COMMAND_OPTIONS: ReadonlyMap<string, ReadonlySet<string>>;
|
|
115
|
+
/**
|
|
116
|
+
* Coerce a raw string (a hostname) into a valid agent account name, or `''` when
|
|
117
|
+
* nothing usable survives. Lowercase; drop every character outside the account
|
|
118
|
+
* body class `[a-z0-9._-]`; strip leading non-alphanumerics (the account MUST
|
|
119
|
+
* start alphanumeric); clamp to 64 chars. A suggestion only — never parsed or
|
|
120
|
+
* matched (§2); the user may accept it or type any valid label.
|
|
121
|
+
*/
|
|
122
|
+
export declare function sanitizeAgentName(raw: string): string;
|
|
123
|
+
/**
|
|
124
|
+
* The identity's last-active instant in epoch-ms: `max` of its two non-null
|
|
125
|
+
* timestamps (`lastUsedAt`, the rekey-surviving token-level max; `lastContactAt`,
|
|
126
|
+
* the identity-level any-protocol contact), or `null` when both are absent. Both
|
|
127
|
+
* recording paths are monotone, so `max` is the correct "most recent activity".
|
|
128
|
+
*/
|
|
129
|
+
export declare function lastActiveMs(identity: AgentIdentitySummary): number | null;
|
|
130
|
+
/**
|
|
131
|
+
* Render an elapsed-time delta (ms) as a short relative string: `just now`,
|
|
132
|
+
* `<n>m ago`, `<n>h ago`, `<n>d ago`. A `null` delta (no recorded activity)
|
|
133
|
+
* renders `never`. Negative deltas (clock skew) clamp to `just now`.
|
|
134
|
+
*/
|
|
135
|
+
export declare function formatLastActive(deltaMs: number | null): string;
|
|
136
|
+
/**
|
|
137
|
+
* Async entry point that adds network I/O for `add` and the hub commands on top
|
|
138
|
+
* of the otherwise fully-synchronous engine/CLI (see the doc comment on
|
|
139
|
+
* `sleepMs` above and README "sync end to end"). `main`/`dispatch` stay sync and
|
|
140
|
+
* unchanged — this wraps them, routing only the network-touching verbs through
|
|
141
|
+
* the async path, so every existing command and test keeps working exactly as
|
|
142
|
+
* before.
|
|
143
|
+
*/
|
|
144
|
+
export declare const ASYNC_COMMANDS: Set<string>;
|
|
145
|
+
export declare function mainAsync(argv: string[], io?: CliIO): Promise<number>;
|
|
146
|
+
/** Run the synchronous engine CLI. The `work` and `shift` namespaces are async-only. */
|
|
147
|
+
export declare function main(argv: string[], io?: CliIO): number;
|