@loops-adk/core 0.1.0 → 0.1.1

package/README.md

@@ -447,6 +447,19 @@ The error taxonomy backs this: an engine classifies a throttle into a `RATE_LIMI
 
 Every mode ends with a summary: result, per-loop iterations, review tallies, token usage by model, and any errors.
 
+## Supervise a running loop
+
+Run with `--supervise` and the loop registers itself under `~/.loops/runs/`, writing its live state there as it goes. Another process reads it with no daemon and no socket, because the filesystem is the channel (the same bet the rest of the library makes).
+
+```bash
+loops run build.loop.ts --supervise   # in one terminal
+loops list                             # in another: every supervised run, with state and iteration
+loops status <runId>                   # its shape plus where it is now: iteration, last gate verdict, tokens
+loops tail <runId>                     # stream its events live
+```
+
+`list` marks a run dead if its process is gone. The read side is also on the public surface (`listRuns`, `readRunStatus`, `runEventsPath`), so an agent supervising a fleet of loops, killing the ones that drift and kicking work back into the ones that hit a problem, reads the same files. Out-of-process control (pause, abort, and kickback from outside) is the next step.
+
 ## What `loops` is (and isn't)
 
 `loops` is a **fresh-context loop primitive**, not a durable workflow engine. The design bet is that **the workspace is the state**: progress _and its reasoning_ live in git (the Ledger), so each iteration can start clean and still know what came before. If the process dies mid-run, you re-run against the same workspace (the worktree holds the files, the scratch files hold the why, the log holds the milestones) and continue. You lose the bookkeeping, not the work.
@@ -464,7 +477,9 @@ It deliberately does **not** do durable mid-run replay (re-running a half-finish
 - [x] **Ledger**, git-memory core: the scratch files (working memory + handoff), grounding, milestone commits
 - [x] Worktree isolation (branches-as-teams) with `--no-ff` land-back
 - [x] Environment axis: provider interface + offline mock
-- [ ] Publish to npm (with a built `dist` + `exports`)
+- [x] Publish to npm (`@loops-adk/core`, built `dist` + types, CI release)
+- [x] Supervision: a file-based run registry with `loops list` / `status` / `tail`
+- [ ] Out-of-process control: `pause` / `abort` / `kickback` a running loop from outside
 - [ ] Optional `wip:` autosave tier (per-iteration recovery, squashed on convergence)
 - [ ] No-progress / stall detection: the third hard stop, alongside `max` and `budget`
 - [ ] `cost per accepted change` as a first-class reported metric

package/bin/loops.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // Thin launcher. Registers tsx's ESM loader globally so the CLI can transform a
 // user's `.loop.ts` recipe from any repo (the run-from-anywhere contract), then
-// hands off to the CLI. In a published install loops' own code is the built
-// `dist/`; running from source (this repo, no build step) falls back to the
-// TypeScript entry, which the same tsx loader transforms.
+// hands off to the CLI. From a checkout the TypeScript source is the entry (the
+// no-build-step dev path); a published install ships no `src`, so it falls back
+// to the built `dist`. Source wins so a stale `dist` never shadows live code.
 import { existsSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -11,6 +11,6 @@ import { register } from 'tsx/esm/api';
 
 register();
 const here = dirname(fileURLToPath(import.meta.url));
-const dist = join(here, '..', 'dist', 'index.js');
-const entry = existsSync(dist) ? dist : join(here, '..', 'src', 'index.ts');
+const src = join(here, '..', 'src', 'index.ts');
+const entry = existsSync(src) ? src : join(here, '..', 'dist', 'index.js');
 await import(pathToFileURL(entry).href);

package/dist/api.d.ts

@@ -903,6 +903,12 @@ interface RunOptions {
     recordTo?: string;
     /** Snapshot the shared run state here at each loop/dag/job boundary. */
     checkpoint?: string;
+    /**
+     * Register this run in the global registry (`~/.loops/runs/<runId>`) and write
+     * its live state there, so another process can `loops list` / `status` / `tail`
+     * it. Off by default — opt in to make a run observable from outside.
+     */
+    supervise?: boolean;
     /** Restore shared run state written by a prior `checkpoint` before starting. */
     resumeFrom?: string;
     /**
@@ -930,11 +936,74 @@ interface RunResult {
         spent: number;
         remaining: number;
     };
+    /** The registry id, when the run was supervised. */
+    runId?: string;
 }
 declare function run(job: Job, options?: RunOptions): Promise<RunResult>;
 /** Process exit code mapped from a terminal outcome. */
 declare function exitCodeFor(outcome: Outcome): number;
 
+/**
+ * Out-of-process supervision. A supervised run registers itself under a global
+ * registry (`~/.loops/runs/<runId>/`) and writes its live state there as it goes:
+ *
+ *   - `status.json`: a snapshot rewritten at each boundary: the run's shape (the
+ *     static `JobMeta`) plus where it is right now (path, iteration, last gate
+ *     verdict and confidence, last outcome, token usage, terminal status at end).
+ *   - `events.jsonl`: the event stream appended live (the same record `recordTo`
+ *     writes, here automatically and in the registry).
+ *
+ * A separate process (a human `loops list/status/tail`, or an agent over MCP)
+ * reads those files. No daemon, no socket: the filesystem is the channel, which
+ * is the same "the workspace is the state" bet the rest of the library makes.
+ * Liveness is a pid check, so a crashed run is distinguishable from a live one.
+ */
+
+/** The registry root. `LOOPS_HOME` overrides `~/.loops` (used to isolate tests). */
+declare function runsHome(): string;
+interface RunLive {
+    path: string[];
+    iteration: number;
+    lastGate?: {
+        which: string;
+        met: boolean;
+        confidence?: number;
+        reason: string;
+    };
+    lastOutcome?: {
+        status: string;
+        summary?: string;
+    };
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        calls: number;
+    };
+}
+interface RunStatus {
+    runId: string;
+    pid: number;
+    cwd: string;
+    title: string;
+    startedAt: number;
+    updatedAt: number;
+    endedAt?: number;
+    /** Stored disposition: `running` until the run ends, then the terminal status. */
+    status: 'running' | Outcome['status'];
+    /** Whether the owning process is still alive: computed on read, not stored. */
+    alive?: boolean;
+    shape?: JobMeta;
+    live: RunLive;
+}
+/** Read one run's status, with `alive` computed from its pid. */
+declare function readRunStatus(runId: string): RunStatus | undefined;
+/** All known runs, newest first. */
+declare function listRuns(): RunStatus[];
+/** Path to a run's appended event stream (for tailing). */
+declare function runEventsPath(runId: string): string;
+/** A compact one-line rendering of an event, for `loops tail`. */
+declare function formatEvent(event: LoopEvent): string;
+
 /**
  * Public API. A loop-definition file imports from here and `export default`s a
  * `Job` (usually a `loop(...)` or `dag(...)`). The CLI runs that default export.
@@ -946,4 +1015,4 @@ declare function exitCodeFor(outcome: Outcome): number;
 /** Identity helper that pins the type of a default export to `Job`. */
 declare function defineJob(job: Job): Job;
 
-export { type AgentCheckConfig, AgentDef, AgentRequest, AgentResult, BudgetConfig, type CommitInput, type CommitRecord, type CompactOptions, Condition, ConditionInput, type ConsolidateJobConfig, type ConsolidateOptions, DagConfig, EXIT_PAUSED, Engine, type EngineFactory, EngineName, EngineOptions, EngineRef, EngineRegistry, EnvHandle, Environment, Forge, type GroundOptions, type IsolatedOptions, Job, JobContext, JobMeta, type LedgerEntry, LimitPolicy, type LogQuery, LoopConfig, LoopEvent, type MergeJobConfig, type MergeResult, type MergeSynthesisConfig, type MergeSynthesisResult, MockEngine, type MockEnvOptions, MockEnvironment, type MockResponder, Outcome, type PromptNote, type PullRequestJobConfig, type PushJobConfig, type PushOptions, type PushResult, type RetrieveOptions, type RunOptions, type RunResult, Stats, type StatsSnapshot, type TournamentConfig, Usage, Workspace, type WorktreeHandle, addWorktree, agentCheck, all, always, any, appendLedger, appendPrompt, bodyPassed, commandSucceeds, commit, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, dag, defineJob, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, forgeChecks, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isRepo, isolated, jobMeta, ledgerPath, log, loop, mergeAbort, mergeBranch, mergeJob, mergeNoCommit, mergeSynthesis, minConfidence, mockVerdict, never, not, parallel, predicate, promptPath, pullRequestJob, push, pushJob, quorum, readLedger, readPrompt, removeWorktree, renderPlan, resetLedger, resetPrompt, retrieveLedger, run, sequence, stageAll, toCondition, tournament };
+export { type AgentCheckConfig, AgentDef, AgentRequest, AgentResult, BudgetConfig, type CommitInput, type CommitRecord, type CompactOptions, Condition, ConditionInput, type ConsolidateJobConfig, type ConsolidateOptions, DagConfig, EXIT_PAUSED, Engine, type EngineFactory, EngineName, EngineOptions, EngineRef, EngineRegistry, EnvHandle, Environment, Forge, type GroundOptions, type IsolatedOptions, Job, JobContext, JobMeta, type LedgerEntry, LimitPolicy, type LogQuery, LoopConfig, LoopEvent, type MergeJobConfig, type MergeResult, type MergeSynthesisConfig, type MergeSynthesisResult, MockEngine, type MockEnvOptions, MockEnvironment, type MockResponder, Outcome, type PromptNote, type PullRequestJobConfig, type PushJobConfig, type PushOptions, type PushResult, type RetrieveOptions, type RunLive, type RunOptions, type RunResult, type RunStatus, Stats, type StatsSnapshot, type TournamentConfig, Usage, Workspace, type WorktreeHandle, addWorktree, agentCheck, all, always, any, appendLedger, appendPrompt, bodyPassed, commandSucceeds, commit, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, dag, defineJob, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, forgeChecks, formatEvent, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isRepo, isolated, jobMeta, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeJob, mergeNoCommit, mergeSynthesis, minConfidence, mockVerdict, never, not, parallel, predicate, promptPath, pullRequestJob, push, pushJob, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, retrieveLedger, run, runEventsPath, runsHome, sequence, stageAll, toCondition, tournament };

package/dist/api.js

@@ -1,5 +1,5 @@
-import { mergeNoCommit, stageAll, commit, mergeAbort, log, setMeta, jobMeta, isRepo, addWorktree, childContext, composeCommitBody, mergeBranch, removeWorktree, deleteBranch, push, consolidate, toCondition, GhForge } from './chunk-3BPU34DE.js';
-export { Budget, EXIT_PAUSED, EngineRegistry, GhForge, MockForge, Stats, addWorktree, agentCheck, agentJob, all, always, any, appendLedger, appendPrompt, bodyPassed, buildChecksArgs, buildCreateArgs, buildEditArgs, buildMergeArgs, buildViewArgs, commandSucceeds, commit, commitJob, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, defineAgent, defineSkill, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, fnJob, forgeChecks, fromFile, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, jobMeta, kickback, ledgerPath, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, not, predicate, promptPath, push, quorum, readLedger, readPrompt, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveSystem, retrieveLedger, run, stageAll, toCondition } from './chunk-3BPU34DE.js';
+import { mergeNoCommit, stageAll, commit, mergeAbort, log, setMeta, jobMeta, isRepo, addWorktree, childContext, composeCommitBody, mergeBranch, removeWorktree, deleteBranch, push, consolidate, toCondition, GhForge } from './chunk-6BDWTFOS.js';
+export { Budget, EXIT_PAUSED, EngineRegistry, GhForge, MockForge, Stats, addWorktree, agentCheck, agentJob, all, always, any, appendLedger, appendPrompt, bodyPassed, buildChecksArgs, buildCreateArgs, buildEditArgs, buildMergeArgs, buildViewArgs, commandSucceeds, commit, commitJob, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, defineAgent, defineSkill, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, fnJob, forgeChecks, formatEvent, fromFile, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, jobMeta, kickback, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, not, predicate, promptPath, push, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveSystem, retrieveLedger, run, runEventsPath, runsHome, stageAll, toCondition } from './chunk-6BDWTFOS.js';
 import './chunk-JFTXJ7I2.js';
 export { SUBAGENT_TOOLS, isEngine } from './chunk-XC46B4FD.js';
 import './chunk-Y2SD7GBL.js';