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
@@ -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
- export interface InstallLockHandle {
238
- lockPath: string;
239
- acquired: boolean;
240
- /** Per-acquisition ownership token — present when `acquired`; proof of ownership for release. */
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` (an exclusive-create of the
264
- * file, `openSync(..,'wx')` — the O_EXCL create is the real serialization point).
265
- * The payload carries an ownership token, the owner pid, a start timestamp, and
266
- * the host. If another process holds it: reclaim it only when liveness-aware
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
- * Release a lock acquired by `acquireInstallLock`. Token-checked and
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 { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
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, randomBytes } from 'node:crypto';
15
- import { hostname } from 'node:os';
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
- * Decide whether the lock described by `holder` (parsed from a raw read) may be
473
- * reclaimed, given the current host. Liveness-aware, not age-based:
474
- *
475
- * 1. `statSync` fails — the lock vanished mid-judgment → treat as reclaimable
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 lockIsStale(lockPath, holder, staleMs, isPidAlive, now, currentHost) {
487
- let mtimeMs;
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;