@loops-adk/core 0.2.0 → 0.3.0

package/dist/{types-Cv_3ymr9.d.ts → types-CpB03Jj4.d.ts}

@@ -395,6 +395,118 @@ declare function commitJob(config: CommitJobConfig): Job;
 /** A deterministic step from a plain function — for glue, checks, side effects. */
 declare function fnJob(label: string, fn: (ctx: JobContext) => Outcome | Promise<Outcome>): Job;
 
+/**
+ * No-progress (stall) detection — the third hard stop, alongside `max` and
+ * `budget`. `max` bounds how many attempts a loop gets and `budget` bounds what
+ * they cost; neither can tell "slow but real convergence" from "the same failure
+ * five turns running". This module supplies that sensor, so a doomed loop exits
+ * at iteration N+window instead of burning everything it was given.
+ *
+ * The decision rule is NOVELTY, not change. An iteration makes progress when it
+ * reaches a state this run has never seen:
+ *
+ *   - the workspace fingerprint (HEAD + pending diff + untracked content) is new
+ *     — so an agent oscillating A→B→A gets no credit for the return trip;
+ *   - a caller-supplied `signal` value is new — the escape hatch for loops whose
+ *     progress lives outside the worktree (a queue length, a passing-test count);
+ *   - the gate confidence beats its previous best by `minConfidenceDelta` — a
+ *     high-water mark, so judge jitter around a flat score is not progress but
+ *     slow, steady improvement accumulates until it clears the bar.
+ *
+ * `window` consecutive iterations with evidence and no novelty = stalled. The
+ * default is deliberately conservative (any channel's novelty counts): a false
+ * "stalled" on work that was actually converging is worse than one more
+ * iteration. An iteration with NO evidence channel at all (no git workspace, no
+ * confidence, no signal) is indeterminate — it neither extends nor resets the
+ * stall run, and the detector reports itself inert so the loop can warn once.
+ * Gate/review reasons are deliberately NOT compared: judge prose varies between
+ * identical verdicts, so it is quoted in the report but never used as evidence.
+ */
+
+interface NoProgressConfig {
+    /** Consecutive no-progress iterations before the loop stalls out. Default 3. */
+    window?: number;
+    /**
+     * How far the gate confidence must beat its previous best to count as
+     * progress (the high-water mark). Default 0.02.
+     */
+    minConfidenceDelta?: number;
+    /**
+     * A caller-supplied progress fingerprint for state the workspace cannot see
+     * (a queue length, a passing-test count, an external resource). Returning a
+     * value this run has already produced counts as no progress; `undefined`
+     * leaves the channel out of this iteration's evidence. A throw is a bug in
+     * the definition and fails the loop, like any other guarded user code.
+     */
+    signal?: (ctx: JobContext, last: Outcome | undefined) => string | number | undefined | Promise<string | number | undefined>;
+    /**
+     * Read the workspace fingerprint each iteration (a few git subprocesses).
+     * Default true; set false when a custom `signal` is the only honest channel.
+     */
+    workspace?: boolean;
+}
+/** What `LoopConfig.noProgress` accepts: a bare window, or the full config. */
+type NoProgressInput = number | NoProgressConfig;
+/** The evidence a stalled loop carries out — on the outcome and the event. */
+interface StallReport {
+    /** The configured window that was filled. */
+    window: number;
+    /** The consecutive no-progress iterations, in order. */
+    iterations: number[];
+    /** The last gate/review reason observed — what kept failing. */
+    reason: string;
+    /** Per-channel assessment of the tripping iteration. */
+    evidence: string[];
+}
+/** One completed, non-converged iteration as the tracker sees it. */
+interface ProgressSample {
+    iteration: number;
+    /** Workspace fingerprint, when the workspace is a git repo. */
+    fingerprint?: string;
+    /** The confidence that gated this turn (review ?? until ?? body). */
+    confidence?: number;
+    /** The custom signal value, when a `signal` fn is configured. */
+    signal?: string;
+    /** The gate/review reason — reporting only, never evidence. */
+    reason?: string;
+}
+/** Resolve the `noProgress` sugar (`3` ⇒ `{ window: 3 }`) with defaults applied. */
+declare function resolveNoProgress(input: NoProgressInput | undefined): Required<Pick<NoProgressConfig, 'window' | 'minConfidenceDelta'>> & NoProgressConfig | undefined;
+/**
+ * The novelty tracker behind `LoopConfig.noProgress`. Feed it one sample per
+ * non-converged iteration; it returns a `StallReport` the moment `window`
+ * consecutive samples show evidence and no novelty.
+ */
+declare class ProgressTracker {
+    readonly window: number;
+    readonly minConfidenceDelta: number;
+    /** Every state this run has reached, namespaced by channel. */
+    private readonly seen;
+    /** Confidence high-water mark — the best score at the last progress point. */
+    private best;
+    /** The current run of consecutive no-progress iterations. */
+    private stalledRun;
+    private lastEvidence;
+    private lastReason;
+    private indeterminate;
+    private sampled;
+    constructor(cfg: {
+        window: number;
+        minConfidenceDelta: number;
+    });
+    /**
+     * Record one iteration. Returns a `StallReport` when this sample fills the
+     * window, else undefined.
+     */
+    record(sample: ProgressSample): StallReport | undefined;
+    /**
+     * True when the detector has seen a full window of samples and none carried
+     * any evidence channel — detection is configured but cannot fire. The loop
+     * uses this to warn once instead of failing silently-inert.
+     */
+    isInert(): boolean;
+}
+
 /**
  * The Environment provider — the third axis, after Engine (where the agent
  * thinks) and Workspace (where the code lives). Environment is where the code
@@ -595,6 +707,13 @@ interface Outcome {
     data?: unknown;
     /** Present when `status` is driven by a failure. */
     error?: LoopError;
+    /**
+     * Present when a loop ended `exhausted` because its `noProgress` detector
+     * tripped: the evidence that the last `window` iterations reached no state
+     * the run had not already seen. Lets a supervisor tell "stalled, re-brief it"
+     * from "ran out of runway mid-progress" without parsing the summary.
+     */
+    stall?: StallReport;
     /**
      * Structured feedback asking an earlier unit of work for another pass, and the
      * single channel for it. When `revision.target` is set, the enclosing `dag`
@@ -747,6 +866,17 @@ interface LoopConfig {
     stopOn?: ConditionInput;
     /** Iteration cap. Reached without passing => `exhausted`. */
     max?: number;
+    /**
+     * The third hard stop, alongside `max` and `budget`: end the loop `exhausted`
+     * when this many consecutive iterations make no observable progress — no
+     * workspace state the run has not already visited, no custom `signal` value
+     * not already seen, no gate confidence beating its previous best. A bare
+     * number is the window (`3` ⇒ three flat iterations); pass a `NoProgressConfig`
+     * for the full knobs. Off by default: a polling loop legitimately makes no
+     * progress until the outside world changes, so this is opt-in like `commit`.
+     * The stalled outcome carries the evidence as `Outcome.stall`.
+     */
+    noProgress?: NoProgressInput;
     /**
      * Runs when `until` is met. If it returns `pass`, the loop completes.
      * Any other status re-enters the loop — this is the "review fails, run the
@@ -881,6 +1011,12 @@ type LoopEvent = {
     path: string[];
     outcome: Outcome;
     iterations: number;
+} | {
+    kind: 'loop:stall';
+    ts: number;
+    path: string[];
+    iteration: number;
+    report: StallReport;
 } | {
     kind: 'limit:wait';
     ts: number;
@@ -976,4 +1112,4 @@ type LoopEvent = {
     code: string;
 };
 
-export { type PrInput as $, type AgentDef as A, type BudgetConfig as B, type ConditionInput as C, type DagConfig as D, type Environment as E, type FeedbackFinding as F, type GraphPosition as G, type CommitJobConfig as H, type ConditionResult as I, type Job as J, type DagNode as K, type LoopConfig as L, type EngineStreamEvent as M, type ForgeOpts as N, type Outcome as O, GhForge as P, type GroundConfig as Q, type RevisionRerun as R, type LogLevel as S, LoopError as T, type Usage as U, type LoopErrorCode as V, type Workspace as W, type MergeOptions as X, MockForge as Y, type MockForgeOptions as Z, type OutcomeStatus as _, type FeedbackDecision as a, type PrPatch as a0, type PrRef as a1, type RawPredicate as a2, type RetryPolicy as a3, SUBAGENT_TOOLS as a4, type Skill as a5, agentContract as a6, agentJob as a7, buildChecksArgs as a8, buildCreateArgs as a9, buildEditArgs as aa, buildMergeArgs as ab, buildViewArgs as ac, commitJob as ad, defineAgent as ae, defineSkill as af, fnJob as ag, fromFile as ah, isEngine as ai, isEnvironment as aj, isForge as ak, resolveSystem as al, type FeedbackSeverity as b, type FeedbackActionSeverity as c, type JobContext as d, type RevisionRequest as e, type JobMeta as f, type EngineRef as g, type Condition as h, type EngineOptions as i, type Engine as j, type EngineName as k, type AgentRequest as l, type EngineEventSink as m, type AgentResult as n, type EnvHandle as o, type LoopEvent as p, type Forge as q, type LimitPolicy as r, type AgentContractSummary as s, type AgentFailureMode as t, type AgentHumanGate as u, type AgentJobConfig as v, type AgentOutputContract as w, type AgentSkillRef as x, type AgentTier as y, Budget as z };
+export { type NoProgressInput as $, type AgentDef as A, type BudgetConfig as B, type ConditionInput as C, type DagConfig as D, type Environment as E, type FeedbackFinding as F, type GraphPosition as G, type CommitJobConfig as H, type ConditionResult as I, type Job as J, type DagNode as K, type LoopConfig as L, type EngineStreamEvent as M, type ForgeOpts as N, type Outcome as O, GhForge as P, type GroundConfig as Q, type RevisionRerun as R, type LogLevel as S, LoopError as T, type Usage as U, type LoopErrorCode as V, type Workspace as W, type MergeOptions as X, MockForge as Y, type MockForgeOptions as Z, type NoProgressConfig as _, type FeedbackDecision as a, type OutcomeStatus as a0, type PrInput as a1, type PrPatch as a2, type PrRef as a3, type ProgressSample as a4, ProgressTracker as a5, type RawPredicate as a6, type RetryPolicy as a7, SUBAGENT_TOOLS as a8, type Skill as a9, type StallReport as aa, agentContract as ab, agentJob as ac, buildChecksArgs as ad, buildCreateArgs as ae, buildEditArgs as af, buildMergeArgs as ag, buildViewArgs as ah, commitJob as ai, defineAgent as aj, defineSkill as ak, fnJob as al, fromFile as am, isEngine as an, isEnvironment as ao, isForge as ap, resolveNoProgress as aq, resolveSystem as ar, type FeedbackSeverity as b, type FeedbackActionSeverity as c, type JobContext as d, type RevisionRequest as e, type JobMeta as f, type EngineRef as g, type Condition as h, type EngineOptions as i, type Engine as j, type EngineName as k, type AgentRequest as l, type EngineEventSink as m, type AgentResult as n, type EnvHandle as o, type LoopEvent as p, type Forge as q, type LimitPolicy as r, type AgentContractSummary as s, type AgentFailureMode as t, type AgentHumanGate as u, type AgentJobConfig as v, type AgentOutputContract as w, type AgentSkillRef as x, type AgentTier as y, Budget as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loops-adk/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "author": "Jonny Neill",
   "description": "Run an agent in a convergence loop with an honest done-gate. A small, nestable loop and DAG primitive: deterministic plus agent-judge conditions, git as memory, review-restart, budgets, and a live TUI.",
@@ -74,6 +74,7 @@
     "bench:context:dry": "BENCH_DRY=1 BENCH_CB_GROUPS=bench/contextbench/groups.dry.json tsx bench/swecontextbench.ts",
     "bench:mechanism": "tsx bench/mechanism.ts",
     "example:poll": "tsx src/index.ts run examples/simple-poll.loop.ts --no-tui",
+    "example:stall": "tsx src/index.ts run examples/stall-demo.loop.ts --no-tui",
     "example:gate": "tsx src/index.ts run examples/confidence-gate.loop.ts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run typecheck"