@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/loop/autonomous-agent.js

@@ -0,0 +1,91 @@
+// src/agents/loop/autonomous-agent.ts
+//
+// Tideline Step 31/32 — the live self-driving autonomous run.
+//
+// Drives a real agent across MULTIPLE turns toward a task until it's done or a
+// guard fires, on top of the `runAutonomousLoop` engine. The done-model is the
+// one validated against a mature autonomous agent (see the loop-runner notes):
+//   • OBJECTIVE doneChecks (preferred — verifiable: tests pass, file exists), OR
+//   • the agent emits a COMPLETION MARKER (the pragmatic terminator for
+//     open-ended tasks), bounded by
+//   • the guards (max-iterations / no-progress) so a stuck/over-eager agent
+//     always stops — never an infinite or self-deluded loop.
+//
+// `runTurn` is the SEAM: the live caller injects the real turn-runner (it runs
+// one Brigade turn and returns the assistant's visible text); tests inject a
+// scripted fake, so ALL the control logic here is unit-tested without a model.
+import { slopIndex } from "../quality/slop-index.js";
+import { runAutonomousLoop } from "./loop-runner.js";
+/** Default completion sentinel the agent emits when it considers the task done.
+ *  Distinctive + unlikely to appear incidentally in prose. */
+export const DEFAULT_COMPLETION_MARKER = "<<BRIGADE_TASK_COMPLETE>>";
+/**
+ * The autonomous-mode instructions to prepend to the agent's context: keep
+ * acting across turns, and emit the marker ONLY when genuinely finished.
+ */
+export function autonomousModePrompt(marker = DEFAULT_COMPLETION_MARKER) {
+    return [
+        "You are running AUTONOMOUSLY — you will be re-prompted to CONTINUE until the task is finished or a limit is reached.",
+        "Each turn, take a concrete next action toward the task (use tools; don't just describe what you would do).",
+        `When — and ONLY when — the task is genuinely complete (and you've verified it, e.g. the change is written / the test passes), emit this exact marker on its own line:`,
+        marker,
+        "Do not emit the marker while work remains. If you're blocked, say why and what you'd need, then emit the marker (the run will end and report it).",
+    ].join("\n");
+}
+const CONTINUE_PROMPT = "Continue the task. If it is fully complete and verified, emit the completion marker now; otherwise take the next concrete step.";
+/**
+ * Run an autonomous agent to completion. Returns the loop result: `done` +
+ * `stopReason` ("completed" via marker, "done" via doneChecks, or a guard
+ * reason), the per-turn outputs, and how many slop rewrites fired.
+ */
+export function runAutonomousAgent(opts) {
+    const marker = opts.completionMarker ?? DEFAULT_COMPLETION_MARKER;
+    // CODE Slop-Index completion gate (Step 33): when the agent claims done, score
+    // the diff it produced; veto the marker (keep working) if it's too sloppy. Empty
+    // diff ⇒ score 0 ⇒ accept, so non-code tasks pass straight through.
+    const slopGate = opts.slopGate;
+    const completionGate = slopGate
+        ? async () => {
+            const files = await slopGate.getChangedFiles();
+            if (files.length === 0)
+                return { accept: true };
+            const { score, flags } = slopIndex(files);
+            const threshold = slopGate.threshold ?? 0.6;
+            if (score <= threshold)
+                return { accept: true };
+            return {
+                accept: false,
+                reason: `the code you wrote scores ${(score * 100).toFixed(0)}% on the slop index (${flags.join("; ") || "low quality"}) — clean it up before finishing`,
+            };
+        }
+        : undefined;
+    return runAutonomousLoop(async (ctx) => {
+        const base = ctx.iteration === 0 ? opts.task : CONTINUE_PROMPT;
+        const prompt = ctx.lastSlop
+            ? `${base}\n\n(Your previous reply was flagged as low-quality — ${ctx.lastSlop}. Redo it concretely.)`
+            : base;
+        const output = await opts.runTurn(prompt, {
+            iteration: ctx.iteration,
+            ...(ctx.lastSlop ? { lastSlop: ctx.lastSlop } : {}),
+        });
+        return {
+            output,
+            // No-progress signal: identical visible output across turns ⇒ stuck.
+            fingerprint: output.trim().slice(0, 200),
+            action: ctx.iteration === 0 ? "task" : "continue",
+        };
+    }, {
+        budget: {
+            maxIterations: opts.maxIterations ?? 25,
+            ...(opts.maxMs !== undefined ? { maxMs: opts.maxMs } : {}),
+        },
+        completionMarker: marker,
+        noProgressPatience: opts.noProgressPatience ?? 3,
+        maxRepairs: 1,
+        ...(opts.doneChecks ? { doneChecks: opts.doneChecks } : {}),
+        ...(completionGate ? { completionGate } : {}),
+        ...(opts.slopThreshold !== undefined ? { slopThreshold: opts.slopThreshold } : {}),
+        ...(opts.now ? { now: opts.now } : {}),
+    });
+}
+//# sourceMappingURL=autonomous-agent.js.map

package/dist/agents/loop/autonomous-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonomous-agent.js","sourceRoot":"","sources":["../../../src/agents/loop/autonomous-agent.ts"],"names":[],"mappings":"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"}

package/dist/agents/loop/loop-guards.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Loop-engineering guards — deterministic safety rails for autonomous, long-
+ * horizon agent loops. The principle (project-wide): an autonomous loop stops on
+ * OBJECTIVE signals — a budget hit, no progress, repetition, or a VERIFIABLE
+ * done-check — NEVER the agent's own "I'm done". Generic + injectable so the live
+ * agent loop wires them without each guard knowing Brigade internals.
+ *
+ * Composed by {@link LoopController}: call `tick()` once per iteration with the
+ * observed state; it returns the first stop reason or `{ stop: false }`.
+ */
+export interface StopDecision {
+    stop: boolean;
+    reason?: string;
+}
+/** Hard caps — the non-negotiable floor (iterations · tokens · wall-time). */
+export declare class LoopBudget {
+    private readonly limits;
+    private readonly now;
+    private iters;
+    private tokens;
+    private readonly start;
+    constructor(limits: {
+        maxIterations?: number;
+        maxMs?: number;
+        maxTokens?: number;
+    }, now?: () => number);
+    /** Record one iteration (+ optional tokens spent this iteration). */
+    tick(tokensDelta?: number): void;
+    get iterations(): number;
+    get tokensSpent(): number;
+    exceeded(): StopDecision;
+}
+/** No-progress: stop if the state fingerprint is unchanged for `patience`
+ *  consecutive iterations (catches silent failures — tool calls happen but
+ *  nothing changes). */
+export declare class NoProgressGuard {
+    private readonly patience;
+    private last;
+    private stale;
+    constructor(patience: number);
+    observe(fingerprint: string): StopDecision;
+}
+/** Repetition: stop if the same action fingerprint recurs `maxRepeats` times
+ *  within the last `window` actions (catches "called a broken tool 400×"). */
+export declare class RepetitionGuard {
+    private readonly opts;
+    private readonly recent;
+    constructor(opts: {
+        window: number;
+        maxRepeats: number;
+    });
+    observe(actionFingerprint: string): StopDecision;
+}
+/** A verifiable done-check (tests pass, typecheck clean, file exists …). */
+export type DoneCheck = {
+    name: string;
+    check: () => boolean | Promise<boolean>;
+};
+/**
+ * INDEPENDENT termination — the loop is done ONLY when EVERY verifiable check
+ * passes (objective signals, not the agent's self-assessment). Returns the first
+ * failing check so the loop knows what's left. `[]` ⇒ never auto-done (the loop
+ * relies on budget/no-progress instead).
+ */
+export declare function evaluateDone(checks: readonly DoneCheck[]): Promise<{
+    done: boolean;
+    failing?: string;
+}>;
+/** Composes the guards. One `tick()` per loop iteration → the first stop reason. */
+export declare class LoopController {
+    private readonly budget;
+    private readonly noProgress?;
+    private readonly repetition?;
+    constructor(opts: {
+        budget: {
+            maxIterations?: number;
+            maxMs?: number;
+            maxTokens?: number;
+        };
+        noProgressPatience?: number;
+        repetition?: {
+            window: number;
+            maxRepeats: number;
+        };
+    }, now?: () => number);
+    /** Call once per iteration. `fingerprint` = state hash (for no-progress);
+     *  `action` = the action taken (for repetition); `tokens` = tokens spent. */
+    tick(obs?: {
+        fingerprint?: string;
+        action?: string;
+        tokens?: number;
+    }): StopDecision;
+    get iterations(): number;
+}
+//# sourceMappingURL=loop-guards.d.ts.map

package/dist/agents/loop/loop-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-guards.d.ts","sourceRoot":"","sources":["../../../src/agents/loop/loop-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAGD,8EAA8E;AAC9E,qBAAa,UAAU;IAKrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IALrB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEb,MAAM,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EACtE,GAAG,GAAE,MAAM,MAAyB;IActD,qEAAqE;IACrE,IAAI,CAAC,WAAW,SAAI,GAAG,IAAI;IAI3B,IAAI,UAAU,IAAI,MAAM,CAEvB;IACD,IAAI,WAAW,IAAI,MAAM,CAExB;IACD,QAAQ,IAAI,YAAY;CAaxB;AAED;;wBAEwB;AACxB,qBAAa,eAAe;IAGf,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,KAAK,CAAK;gBACW,QAAQ,EAAE,MAAM;IAK7C,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY;CAY1C;AAED;8EAC8E;AAC9E,qBAAa,eAAe;IAEf,OAAO,CAAC,QAAQ,CAAC,IAAI;IADjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBACV,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAWzE,OAAO,CAAC,iBAAiB,EAAE,MAAM,GAAG,YAAY;CAShD;AAED,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC;AAElF;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAW7G;AAED,oFAAoF;AACpF,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAkB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAkB;gBAE7C,IAAI,EAAE;QACL,MAAM,EAAE;YAAE,aAAa,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,UAAU,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC;KACpD,EACD,GAAG,GAAE,MAAM,MAAyB;IAMrC;iFAC6E;IAC7E,IAAI,CAAC,GAAG,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,YAAY;IAcxF,IAAI,UAAU,IAAI,MAAM,CAEvB;CACD"}

package/dist/agents/loop/loop-guards.js

@@ -0,0 +1,169 @@
+/**
+ * Loop-engineering guards — deterministic safety rails for autonomous, long-
+ * horizon agent loops. The principle (project-wide): an autonomous loop stops on
+ * OBJECTIVE signals — a budget hit, no progress, repetition, or a VERIFIABLE
+ * done-check — NEVER the agent's own "I'm done". Generic + injectable so the live
+ * agent loop wires them without each guard knowing Brigade internals.
+ *
+ * Composed by {@link LoopController}: call `tick()` once per iteration with the
+ * observed state; it returns the first stop reason or `{ stop: false }`.
+ */
+const GO = { stop: false };
+/** Hard caps — the non-negotiable floor (iterations · tokens · wall-time). */
+export class LoopBudget {
+    limits;
+    now;
+    iters = 0;
+    tokens = 0;
+    start;
+    constructor(limits, now = () => Date.now()) {
+        this.limits = limits;
+        this.now = now;
+        const { maxIterations, maxMs, maxTokens } = limits;
+        if (maxIterations !== undefined && maxIterations < 1) {
+            throw new Error(`LoopBudget: maxIterations (${maxIterations}) must be >= 1`);
+        }
+        if (maxMs !== undefined && maxMs < 1) {
+            throw new Error(`LoopBudget: maxMs (${maxMs}) must be >= 1`);
+        }
+        if (maxTokens !== undefined && maxTokens < 1) {
+            throw new Error(`LoopBudget: maxTokens (${maxTokens}) must be >= 1`);
+        }
+        this.start = now();
+    }
+    /** Record one iteration (+ optional tokens spent this iteration). */
+    tick(tokensDelta = 0) {
+        this.iters += 1;
+        this.tokens += Number.isFinite(tokensDelta) ? Math.max(0, tokensDelta) : 0;
+    }
+    get iterations() {
+        return this.iters;
+    }
+    get tokensSpent() {
+        return this.tokens;
+    }
+    exceeded() {
+        const { maxIterations, maxMs, maxTokens } = this.limits;
+        if (maxIterations !== undefined && this.iters >= maxIterations) {
+            return { stop: true, reason: `iteration cap (${maxIterations}) reached` };
+        }
+        if (maxTokens !== undefined && this.tokens >= maxTokens) {
+            return { stop: true, reason: `token budget (${maxTokens}) reached` };
+        }
+        if (maxMs !== undefined && this.now() - this.start >= maxMs) {
+            return { stop: true, reason: `time budget (${maxMs}ms) reached` };
+        }
+        return GO;
+    }
+}
+/** No-progress: stop if the state fingerprint is unchanged for `patience`
+ *  consecutive iterations (catches silent failures — tool calls happen but
+ *  nothing changes). */
+export class NoProgressGuard {
+    patience;
+    last;
+    stale = 0;
+    constructor(patience) {
+        this.patience = patience;
+        if (patience < 1) {
+            throw new Error(`NoProgressGuard: patience (${patience}) must be >= 1`);
+        }
+    }
+    observe(fingerprint) {
+        if (fingerprint === this.last) {
+            this.stale += 1;
+            if (this.stale >= this.patience) {
+                return { stop: true, reason: `no progress for ${this.patience} iterations` };
+            }
+        }
+        else {
+            this.last = fingerprint;
+            this.stale = 0;
+        }
+        return GO;
+    }
+}
+/** Repetition: stop if the same action fingerprint recurs `maxRepeats` times
+ *  within the last `window` actions (catches "called a broken tool 400×"). */
+export class RepetitionGuard {
+    opts;
+    recent = [];
+    constructor(opts) {
+        this.opts = opts;
+        if (opts.window < 1) {
+            throw new Error(`RepetitionGuard: window (${opts.window}) must be >= 1`);
+        }
+        if (opts.maxRepeats < 1) {
+            throw new Error(`RepetitionGuard: maxRepeats (${opts.maxRepeats}) must be >= 1`);
+        }
+        if (opts.maxRepeats > opts.window) {
+            throw new Error(`RepetitionGuard: maxRepeats (${opts.maxRepeats}) cannot exceed window (${opts.window}) — the guard would never trip`);
+        }
+    }
+    observe(actionFingerprint) {
+        this.recent.push(actionFingerprint);
+        if (this.recent.length > this.opts.window)
+            this.recent.shift();
+        const count = this.recent.filter((a) => a === actionFingerprint).length;
+        if (count >= this.opts.maxRepeats) {
+            return { stop: true, reason: `action repeated ${count}× in the last ${this.recent.length}` };
+        }
+        return GO;
+    }
+}
+/**
+ * INDEPENDENT termination — the loop is done ONLY when EVERY verifiable check
+ * passes (objective signals, not the agent's self-assessment). Returns the first
+ * failing check so the loop knows what's left. `[]` ⇒ never auto-done (the loop
+ * relies on budget/no-progress instead).
+ */
+export async function evaluateDone(checks) {
+    for (const c of checks) {
+        let ok = false;
+        try {
+            ok = await c.check();
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok)
+            return { done: false, failing: c.name };
+    }
+    return { done: checks.length > 0 };
+}
+/** Composes the guards. One `tick()` per loop iteration → the first stop reason. */
+export class LoopController {
+    budget;
+    noProgress;
+    repetition;
+    constructor(opts, now = () => Date.now()) {
+        this.budget = new LoopBudget(opts.budget, now);
+        if (opts.noProgressPatience !== undefined)
+            this.noProgress = new NoProgressGuard(opts.noProgressPatience);
+        if (opts.repetition !== undefined)
+            this.repetition = new RepetitionGuard(opts.repetition);
+    }
+    /** Call once per iteration. `fingerprint` = state hash (for no-progress);
+     *  `action` = the action taken (for repetition); `tokens` = tokens spent. */
+    tick(obs = {}) {
+        this.budget.tick(obs.tokens ?? 0);
+        const overBudget = this.budget.exceeded();
+        if (overBudget.stop)
+            return overBudget;
+        if (obs.fingerprint !== undefined && this.noProgress) {
+            const np = this.noProgress.observe(obs.fingerprint);
+            if (np.stop)
+                return np;
+        }
+        if (obs.action !== undefined && this.repetition) {
+            const rep = this.repetition.observe(obs.action);
+            if (rep.stop)
+                return rep;
+        }
+        return GO;
+    }
+    get iterations() {
+        return this.budget.iterations;
+    }
+}
+//# sourceMappingURL=loop-guards.js.map

package/dist/agents/loop/loop-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-guards.js","sourceRoot":"","sources":["../../../src/agents/loop/loop-guards.ts"],"names":[],"mappings":"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"}

package/dist/agents/loop/loop-runner.d.ts

@@ -0,0 +1,72 @@
+import { type DoneCheck } from "./loop-guards.js";
+export interface LoopStepResult {
+    output: string;
+    /** State hash for the no-progress guard. */
+    fingerprint?: string;
+    /** Action label for the repetition guard. */
+    action?: string;
+    /** Tokens spent this step (for the budget). */
+    tokens?: number;
+}
+export interface AutonomousLoopOpts {
+    budget: {
+        maxIterations?: number;
+        maxMs?: number;
+        maxTokens?: number;
+    };
+    noProgressPatience?: number;
+    repetition?: {
+        window: number;
+        maxRepeats: number;
+    };
+    /** INDEPENDENT termination checks — done only when ALL pass. The PREFERRED
+     *  terminator when the task has a verifiable goal (tests pass, file exists, a
+     *  tool succeeded) — objective signals, not the agent's self-assessment. */
+    doneChecks?: DoneCheck[];
+    /** Completion sentinel — when a step's output CONTAINS this string, the agent
+     *  has signalled the task is done (the common autonomous-agent "emit a
+     *  FINAL-OUTPUT marker when finished" pattern). The pragmatic terminator for
+     *  open-ended tasks with no objective check; still bounded by the budget caps
+     *  below (the marker is an early-out, NOT a runaway guard — a misbehaving
+     *  agent that never emits it still stops at maxIterations). */
+    completionMarker?: string;
+    /** Optional QUALITY gate run when the completion marker is seen: returns whether
+     *  to ACCEPT the completion. A veto (accept:false) rejects the marker for this
+     *  turn — the loop keeps going (still budget-bounded), feeding `reason` back as
+     *  a steer — so the agent can't "finish" on a low-quality artifact (e.g. a
+     *  high-slop code diff, the Step-33 code Slop-Index). Only consulted alongside
+     *  completionMarker. */
+    completionGate?: (output: string) => Promise<CompletionGateResult> | CompletionGateResult;
+    /** Slop density threshold for the post-generation gate (default detectSlop's). */
+    slopThreshold?: number;
+    /** Bounded slop-repair retries per step (default 1). */
+    maxRepairs?: number;
+    now?: () => number;
+}
+export interface CompletionGateResult {
+    /** Accept the completion marker (terminate) or veto it (keep working). */
+    accept: boolean;
+    /** When vetoing, a short reason fed back to the next turn as a steer. */
+    reason?: string;
+}
+export interface AutonomousLoopResult {
+    iterations: number;
+    stopReason: string;
+    done: boolean;
+    outputs: string[];
+    slopRepairs: number;
+    /** Times the completion marker was REJECTED by the completion gate. */
+    completionVetoes: number;
+}
+/**
+ * Run an autonomous loop. `step` is invoked once per iteration; when its output
+ * trips the slop gate it is re-run up to `maxRepairs` times (with the slop
+ * summary as a hint) before being accepted. Terminates on the FIRST of: an
+ * independent done-check passing, or a guard (budget / no-progress / repetition).
+ */
+export declare function runAutonomousLoop(step: (ctx: {
+    iteration: number;
+    repair: number;
+    lastSlop?: string;
+}) => Promise<LoopStepResult> | LoopStepResult, opts: AutonomousLoopOpts): Promise<AutonomousLoopResult>;
+//# sourceMappingURL=loop-runner.d.ts.map

package/dist/agents/loop/loop-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-runner.d.ts","sourceRoot":"","sources":["../../../src/agents/loop/loop-runner.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,SAAS,EAAmD,MAAM,kBAAkB,CAAC;AAEnG,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD;;gFAE4E;IAC5E,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;;;mEAK+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;4BAKwB;IACxB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,GAAG,oBAAoB,CAAC;IAC1F,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACpC,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACtC,IAAI,EAAE,CAAC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,EACjH,IAAI,EAAE,kBAAkB,GACtB,OAAO,CAAC,oBAAoB,CAAC,CAkG/B"}

package/dist/agents/loop/loop-runner.js

@@ -0,0 +1,114 @@
+// src/agents/loop/loop-runner.ts
+//
+// Tideline Steps 31/32 — the autonomous-loop orchestration primitive.
+//
+// Drives a `step` function under the loop guards: each iteration runs the step,
+// gates its output through the TEXT slop detector with a BOUNDED repair retry
+// (the post-generation hook), ticks the LoopController (budget / no-progress /
+// repetition), and stops only when evaluateDone's INDEPENDENT checks pass OR a
+// guard fires — never on the agent's own say-so. This is the harness Step 31
+// wires into agent-loop.ts (slop-gate as a post-generation hook; the controller
+// driving an autonomous run); built standalone so the control logic is testable
+// without a live gateway. The `step` callback IS the agent turn (or a planner/
+// executor stage for the Plan-and-Execute shape of Step 32).
+import { detectSlop, summarizeSlop } from "../quality/slop-detector.js";
+import { evaluateDone, LoopController } from "./loop-guards.js";
+/**
+ * Run an autonomous loop. `step` is invoked once per iteration; when its output
+ * trips the slop gate it is re-run up to `maxRepairs` times (with the slop
+ * summary as a hint) before being accepted. Terminates on the FIRST of: an
+ * independent done-check passing, or a guard (budget / no-progress / repetition).
+ */
+export async function runAutonomousLoop(step, opts) {
+    const controller = new LoopController({
+        budget: opts.budget,
+        ...(opts.noProgressPatience !== undefined ? { noProgressPatience: opts.noProgressPatience } : {}),
+        ...(opts.repetition ? { repetition: opts.repetition } : {}),
+    }, opts.now);
+    const maxRepairs = opts.maxRepairs ?? 1;
+    if (!Number.isInteger(maxRepairs) || maxRepairs < 0) {
+        throw new Error(`runAutonomousLoop: maxRepairs must be a non-negative integer (got ${opts.maxRepairs})`);
+    }
+    // A runaway-prevention primitive must not itself be able to run forever: refuse
+    // to start without at least one terminating condition.
+    const b = opts.budget;
+    const hasBudgetCap = b.maxIterations !== undefined || b.maxMs !== undefined || b.maxTokens !== undefined;
+    const hasDoneCheck = !!opts.doneChecks && opts.doneChecks.length > 0;
+    if (!hasBudgetCap && !hasDoneCheck) {
+        throw new Error("runAutonomousLoop needs a terminating condition: set a budget cap (maxIterations / maxMs / maxTokens) and/or doneChecks");
+    }
+    const slopOpts = opts.slopThreshold !== undefined ? { threshold: opts.slopThreshold } : {};
+    const outputs = [];
+    let slopRepairs = 0;
+    let completionVetoes = 0;
+    let stopReason = "budget";
+    let done = false;
+    // A gate-veto steer carried from the PREVIOUS iteration into the next turn's
+    // prompt (reuses the slop-repair `lastSlop` channel — same "fix it, then go on"
+    // semantics). Consumed once at the top of the loop.
+    let pendingSteer;
+    for (;;) {
+        // Post-generation slop gate with bounded repair. Tokens from EVERY step
+        // invocation (initial + each repair) accumulate so repair attempts can't
+        // bypass the token budget.
+        const startSteer = pendingSteer;
+        pendingSteer = undefined;
+        let result = await step({ iteration: controller.iterations, repair: 0, ...(startSteer ? { lastSlop: startSteer } : {}) });
+        let totalTokens = result.tokens ?? 0;
+        let repair = 0;
+        let lastSlop;
+        while (repair < maxRepairs) {
+            const verdict = detectSlop(result.output, slopOpts);
+            if (!verdict.isSlop)
+                break;
+            lastSlop = summarizeSlop(verdict);
+            repair++;
+            slopRepairs++;
+            result = await step({ iteration: controller.iterations, repair, ...(lastSlop ? { lastSlop } : {}) });
+            totalTokens += result.tokens ?? 0;
+        }
+        outputs.push(result.output);
+        // Completion marker — the agent's explicit "task done" signal (an early-out
+        // before the guards). Objective doneChecks below still take precedence when
+        // configured; this is the terminator for open-ended tasks that have none.
+        // An optional completion GATE can VETO the marker (e.g. a high-slop diff):
+        // the run then keeps going (still budget-bounded) with the reason steered in.
+        if (opts.completionMarker && result.output.includes(opts.completionMarker)) {
+            const gate = opts.completionGate ? await opts.completionGate(result.output) : { accept: true };
+            if (gate.accept) {
+                done = true;
+                stopReason = "completed";
+                break;
+            }
+            completionVetoes++;
+            pendingSteer = gate.reason ?? "the result did not pass the completion quality gate — improve it before finishing";
+        }
+        const decision = controller.tick({
+            ...(result.fingerprint !== undefined ? { fingerprint: result.fingerprint } : {}),
+            ...(result.action !== undefined ? { action: result.action } : {}),
+            tokens: totalTokens,
+        });
+        if (decision.stop) {
+            // A non-budget (no-progress/repetition) guard must not MASK a genuinely
+            // completed turn: if the independent checks pass, report "done".
+            if (hasDoneCheck && (await evaluateDone(opts.doneChecks)).done) {
+                done = true;
+                stopReason = "done";
+            }
+            else {
+                stopReason = decision.reason ?? "guard";
+            }
+            break;
+        }
+        if (opts.doneChecks && opts.doneChecks.length > 0) {
+            const d = await evaluateDone(opts.doneChecks);
+            if (d.done) {
+                done = true;
+                stopReason = "done";
+                break;
+            }
+        }
+    }
+    return { iterations: controller.iterations, stopReason, done, outputs, slopRepairs, completionVetoes };
+}
+//# sourceMappingURL=loop-runner.js.map

package/dist/agents/loop/loop-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-runner.js","sourceRoot":"","sources":["../../../src/agents/loop/loop-runner.ts"],"names":[],"mappings":"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"}

package/dist/agents/memory/auto-recall.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Auto-recall — proactively surface relevant memories into the turn's context
+ * BEFORE the model runs, so it doesn't have to remember to call recall_memory.
+ *
+ * Design (scalable): a hybrid (BM25 primary + vector recovery) recall of the
+ * structured fact store for the user's message, injecting the top-N facts as an
+ * untrusted-context block. Zero extra model calls, sub-millisecond, and
+ * recalled facts are reinforced (accessCount) for decay — so frequently-
+ * useful facts stay alive. We deliberately avoid the per-turn cost of a
+ * dedicated recall subagent (an extra LLM call per turn), and we
+ * deliberately avoid the opposite extreme of pull-only with no auto-
+ * injection at all. MEMORY.md is already always-injected (persona layer)
+ * and daily notes remain available via the recall_memory tool (pull).
+ *
+ * The block is injected as an EPHEMERAL suffix (below the cache boundary,
+ * per-turn) since it depends on the specific user message.
+ *
+ * Routing: when the active `MemoryCapability` is Brigade's default backend
+ * we reach straight into the `FactStore` so we can pass `markAccessed: false`
+ * (auto-recall is a PASSIVE injection — only the explicit `recall_memory`
+ * tool reinforces decay; otherwise every turn would count as a "hit"). When
+ * a plugin backend is active we route through `capability.search` — the
+ * plugin owns ranking + reinforcement semantics, the block stays untrusted.
+ */
+import type { MemoryCapability } from "../extensions/types.js";
+import { type MemoryRecordOrigin, type RecordOriginFilter } from "./records.js";
+/**
+ * Resolve the SAFE auto-recall origin for a turn, or `undefined` to SKIP
+ * auto-recall (fail CLOSED). Owner turns recall owner-scope; a channel-routed
+ * peer recalls their own session scope; a non-owner turn with NO channel route
+ * gets NOTHING — auto-recall must never fall back to owner-scope for an
+ * unidentified peer (that would surface the operator's private memory into a
+ * stranger's pre-model context). Callers MUST skip `buildAutoRecallBlock` when
+ * this returns `undefined` — do NOT pass undefined to it (that means whole-store).
+ */
+export declare function resolveAutoRecallOrigin(args: {
+    senderIsOwner: boolean;
+    channelApprovalRoute?: {
+        channelId: string;
+        conversationId: string;
+        accountId?: string;
+    };
+    sessionKey: string;
+}): MemoryRecordOrigin | undefined;
+/**
+ * Build the auto-recall context block for a user message, or `undefined` when
+ * nothing relevant is stored.
+ *
+ * The fact text is attacker-influenceable — facts come from `write_memory`
+ * (model-authored) and post-turn extraction (distilled from user/pasted text),
+ * so a fact could contain "ignore prior instructions…". We therefore wrap the
+ * facts in an `<untrusted-memory>` block (HTML-escapes `<`/`>`, defangs nested
+ * tags) — NOT a bare markdown bullet list. The model is told to treat it
+ * as background data, not instructions.
+ *
+ * Two overloaded entry shapes:
+ *   - `buildAutoRecallBlock(workspaceDir, query)` — legacy file-store path
+ *     (sync, returns immediately).
+ *   - `buildAutoRecallBlock(capability, query)` — capability-aware path
+ *     (production agent loop passes the resolved `MemoryCapability`). Async
+ *     because plugin backends may need to await a network/db round-trip.
+ */
+export declare function buildAutoRecallBlock(workspaceDir: string, query: string, opts?: {
+    origin?: RecordOriginFilter;
+}): string | undefined;
+export declare function buildAutoRecallBlock(capability: MemoryCapability, query: string, opts?: {
+    origin?: RecordOriginFilter;
+}): Promise<string | undefined>;
+//# sourceMappingURL=auto-recall.d.ts.map

package/dist/agents/memory/auto-recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-recall.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/auto-recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK/D,OAAO,EAAa,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAK3F;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC7C,aAAa,EAAE,OAAO,CAAC;IACvB,oBAAoB,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzF,UAAU,EAAE,MAAM,CAAC;CACnB,GAAG,kBAAkB,GAAG,SAAS,CAajC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CACnC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAAE,GACpC,MAAM,GAAG,SAAS,CAAC;AACtB,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAAE,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC"}