bare-agent 0.42.0 → 0.44.0

package/src/complexity.js

@@ -89,6 +89,11 @@ const MAX_ASSESS_LEN = 4000;
  * Assess the complexity of a goal/prompt from its text alone (no LLM).
  * @param {string} prompt - The goal to classify.
  * @returns {ComplexityResult}
+ * @when you want a fast, no-LLM read of how hard a goal is (simple/medium/complex/critical) to decide whether to invoke the Planner
+ * @fails never throws — pure text scoring; non-string/blank input scores lowest. Keyword lists are frozen and a critical-safety override always wins.
+ * @example
+ *   const { level, needsPlanning } = assessComplexity(goal);
+ *   if (needsPlanning) await planner.plan(goal);
  */
 function assessComplexity(prompt) {
   if (typeof prompt !== 'string' || !prompt.trim()) {
@@ -169,6 +174,10 @@ function assessComplexity(prompt) {
  * non-string / blank input is `false`.
  * @param {string} prompt - The goal to test.
  * @returns {boolean}
+ * @when you want the durable critical-safety floor alone (security/production/compliance/financial) to gate extra scrutiny, without the full scorer
+ * @fails never throws — deterministic override; non-string/blank input is false. This floor is non-overridable by design.
+ * @example
+ *   if (isCritical(goal)) verdict = await evaluator.evaluate(goal, result, { contract });
  */
 function isCritical(prompt) {
   if (typeof prompt !== 'string' || !prompt.trim()) return false;

package/src/context-units.d.ts

@@ -32,6 +32,10 @@ export function fromUnits(units: Array<Record<string, any>>): Array<Record<strin
  * error (incl. HaltError) is left to the Loop's own fail-open / HaltError handling — not swallowed here.
  * @param {(units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)} assembleUnits
  * @returns {(msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>}
+ * @when you want to adapt a litectx-style neutral-unit assemble(units, ctx) verb into the Loop's assemble(msgs, ctx) context-assembly seam
+ * @fails fail-open — any unexpected return shape sends the original msgs unchanged; a thrown error (incl. HaltError) is left to the Loop's own handling.
+ * @example
+ *   const loop = new Loop({ provider, assemble: unitAssembler(litectx.assemble) });
  */
 export function unitAssembler(assembleUnits: (units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)): (msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>;
 /**
@@ -67,6 +71,10 @@ export function unitAssembler(assembleUnits: (units: Array<Record<string, any>>,
  *   `({ key, content, unit }) => void|Promise` (REQUIRED; the harvest policy point). `policy` — litectx
  *   TrimPolicy: `{ keepLastN }` or `{ maxTokens }` (maxTokens wins). Both verbs are runtime-checked.
  * @returns {((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & { flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void> }}
+ * @when you want to adapt litectx's trim(units, policy) verb into the Loop's destructive trim(msgs, ctx) seam — harvest-before-evict with an F2 residual .flush
+ * @fails throws if the trim/onHarvest verbs are missing (runtime-checked); the fold is fail-open and a HaltError propagates. `.flush` drains the residual harvest.
+ * @example
+ *   const loop = new Loop({ provider, trim: unitTrimmer({ trim: litectx.trim, onHarvest, policy: { keepLastN: 20 } }) });
  */
 export function unitTrimmer(opts?: {
     trim?: Function;
@@ -93,6 +101,10 @@ export function unitTrimmer(opts?: {
  * distinct turns). Normal provider ids (`call_…`) round-trip unchanged through the escape.
  * @param {Record<string, any>} unit - a unit from {@link toUnits} (its `_msgs` backing is read).
  * @returns {string}
+ * @when you need the stable content-address for a transcript unit (the key harvest-before-evict writes under) — a collision-resistant 64-bit id
+ * @fails never throws; normal provider ids round-trip unchanged, and two near-independent hash streams avoid 32-bit birthday collisions.
+ * @example
+ *   const key = harvestKey(unit); // stable id for this turn's harvest
  */
 export function harvestKey(unit: Record<string, any>): string;
 /** chars/4 token estimate over a list of messages (matches poc2 / the Loop's own heuristic). */

package/src/context-units.js

@@ -207,6 +207,10 @@ function fromUnits(units) {
  * error (incl. HaltError) is left to the Loop's own fail-open / HaltError handling — not swallowed here.
  * @param {(units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)} assembleUnits
  * @returns {(msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>}
+ * @when you want to adapt a litectx-style neutral-unit assemble(units, ctx) verb into the Loop's assemble(msgs, ctx) context-assembly seam
+ * @fails fail-open — any unexpected return shape sends the original msgs unchanged; a thrown error (incl. HaltError) is left to the Loop's own handling.
+ * @example
+ *   const loop = new Loop({ provider, assemble: unitAssembler(litectx.assemble) });
  */
 function unitAssembler(assembleUnits) {
   if (typeof assembleUnits !== 'function') {
@@ -240,6 +244,10 @@ function unitAssembler(assembleUnits) {
  * distinct turns). Normal provider ids (`call_…`) round-trip unchanged through the escape.
  * @param {Record<string, any>} unit - a unit from {@link toUnits} (its `_msgs` backing is read).
  * @returns {string}
+ * @when you need the stable content-address for a transcript unit (the key harvest-before-evict writes under) — a collision-resistant 64-bit id
+ * @fails never throws; normal provider ids round-trip unchanged, and two near-independent hash streams avoid 32-bit birthday collisions.
+ * @example
+ *   const key = harvestKey(unit); // stable id for this turn's harvest
  */
 function harvestKey(unit) {
   const back = (unit && unit._msgs) || [];
@@ -296,6 +304,10 @@ function harvestKey(unit) {
  *   `({ key, content, unit }) => void|Promise` (REQUIRED; the harvest policy point). `policy` — litectx
  *   TrimPolicy: `{ keepLastN }` or `{ maxTokens }` (maxTokens wins). Both verbs are runtime-checked.
  * @returns {((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & { flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void> }}
+ * @when you want to adapt litectx's trim(units, policy) verb into the Loop's destructive trim(msgs, ctx) seam — harvest-before-evict with an F2 residual .flush
+ * @fails throws if the trim/onHarvest verbs are missing (runtime-checked); the fold is fail-open and a HaltError propagates. `.flush` drains the residual harvest.
+ * @example
+ *   const loop = new Loop({ provider, trim: unitTrimmer({ trim: litectx.trim, onHarvest, policy: { keepLastN: 20 } }) });
  */
 function unitTrimmer(opts) {
   const { trim, onHarvest, policy = {} } = opts || {};

package/src/evaluator.d.ts

@@ -114,7 +114,15 @@ export type EvaluateOptions = {
  * Built flagged-and-deletable per D11 — opt-in by import; calibrate the rubric/prompt from execution traces.
  */
 export class Evaluator {
-    /** @param {EvaluatorOptions} [options] */
+    /**
+     * @param {EvaluatorOptions} [options]
+     * @when you need to judge an output against a goal or contract — deterministically (predicate), by LLM rubric, or with a tool-running critic that exercises the live artifact
+     * @fails never throws for a bad grade — returns a Verdict {status: satisfied|needs_revision|failed}; a provider HaltError propagates clean. Judge tokens forward via onLlmResult.
+     * @example
+     *   const evaluator = new Evaluator({ provider });
+     *   const verdict = await evaluator.evaluate(goal, result, { rubric });
+     *   if (!verdict.pass) revise(verdict.critique);
+     */
     constructor(options?: EvaluatorOptions);
     provider: import("../types").Provider | null;
     prompt: string;

package/src/evaluator.js

@@ -108,7 +108,15 @@ Output your FINAL answer as ONLY this JSON, no markdown, no prose:
  * Built flagged-and-deletable per D11 — opt-in by import; calibrate the rubric/prompt from execution traces.
  */
 class Evaluator {
-  /** @param {EvaluatorOptions} [options] */
+  /**
+   * @param {EvaluatorOptions} [options]
+   * @when you need to judge an output against a goal or contract — deterministically (predicate), by LLM rubric, or with a tool-running critic that exercises the live artifact
+   * @fails never throws for a bad grade — returns a Verdict {status: satisfied|needs_revision|failed}; a provider HaltError propagates clean. Judge tokens forward via onLlmResult.
+   * @example
+   *   const evaluator = new Evaluator({ provider });
+   *   const verdict = await evaluator.evaluate(goal, result, { rubric });
+   *   if (!verdict.pass) revise(verdict.critique);
+   */
   constructor(options = /** @type {EvaluatorOptions} */ ({})) {
     this.provider = options.provider || null;
     this.prompt = options.prompt || GRADER_PROMPT;

package/src/judge-calibration.d.ts

@@ -129,6 +129,11 @@ export function gradeRun(runs: Array<{
  *   a separate admission gate — a leak in any style blocks admission even at a passing clear-case floor.
  * @param {(payload:object)=>any} [opts.onLlmResult] - Budget hook forwarded to each judge call.
  * @returns {Promise<ReturnType<typeof gradeRun> & { reps:number, floor:number, totalCostUsd:number|null, unpricedCalls:number, injectionBattery: { styles: Array<{label:string, usable:number, broke:number, resisted:boolean}>, allResisted:boolean, leaks:number } }>}
+ * @when you are admitting an LLM tier to the judge role and need to grade it against the frozen clear-case battery and resist every injection style before trusting it
+ * @fails never fabricates a pass — a leak in any injection style blocks admission even above the clear-case floor, and the negative control must fail the set. HaltError propagates clean.
+ * @example
+ *   const report = await calibrate({ provider, reps: 5, floor: 7 });
+ *   if (!report.injectionBattery.allResisted) reject('injection leak');
  */
 export function calibrate(opts?: {
     provider: import("../types").Provider;

package/src/judge-calibration.js

@@ -125,6 +125,11 @@ function gradeRun(runs, floor) {
  *   a separate admission gate — a leak in any style blocks admission even at a passing clear-case floor.
  * @param {(payload:object)=>any} [opts.onLlmResult] - Budget hook forwarded to each judge call.
  * @returns {Promise<ReturnType<typeof gradeRun> & { reps:number, floor:number, totalCostUsd:number|null, unpricedCalls:number, injectionBattery: { styles: Array<{label:string, usable:number, broke:number, resisted:boolean}>, allResisted:boolean, leaks:number } }>}
+ * @when you are admitting an LLM tier to the judge role and need to grade it against the frozen clear-case battery and resist every injection style before trusting it
+ * @fails never fabricates a pass — a leak in any injection style blocks admission even above the clear-case floor, and the negative control must fail the set. HaltError propagates clean.
+ * @example
+ *   const report = await calibrate({ provider, reps: 5, floor: 7 });
+ *   if (!report.injectionBattery.allResisted) reject('injection leak');
  */
 async function calibrate(opts = /** @type {any} */ ({})) {
   const provider = opts.provider;

package/src/judge.d.ts

@@ -157,6 +157,11 @@ export type JudgeVerdict = {
  * @throws {ValidationError} on bad inputs (missing request/artifact/provider) — stamped `context.lib='bare-agent'`
  *   at the throw site (contract 4: typed attribution, never sniffed from prose).
  * @throws {HaltError} propagated clean from the provider (a governance halt is not a judge failure).
+ * @when you need a decisive honored/broke verdict on whether one egress artifact honored the verbatim request — a return-time integrity check
+ * @fails throws ValidationError on bad inputs; HaltError propagates clean. Cannot-confirm-honored floors to `broke`; truncation/parse-error are distinct flagged outcomes, never laundered to honored.
+ * @example
+ *   const { verdict, where } = await judge({ request, artifact, provider });
+ *   if (verdict === 'broke') flag(where);
  */
 export function judge(options?: JudgeOptions): Promise<JudgeVerdict>;
 /**

package/src/judge.js

@@ -145,6 +145,11 @@ function normalizeWhere(where) {
  * @throws {ValidationError} on bad inputs (missing request/artifact/provider) — stamped `context.lib='bare-agent'`
  *   at the throw site (contract 4: typed attribution, never sniffed from prose).
  * @throws {HaltError} propagated clean from the provider (a governance halt is not a judge failure).
+ * @when you need a decisive honored/broke verdict on whether one egress artifact honored the verbatim request — a return-time integrity check
+ * @fails throws ValidationError on bad inputs; HaltError propagates clean. Cannot-confirm-honored floors to `broke`; truncation/parse-error are distinct flagged outcomes, never laundered to honored.
+ * @example
+ *   const { verdict, where } = await judge({ request, artifact, provider });
+ *   if (verdict === 'broke') flag(where);
  */
 async function judge(options = /** @type {JudgeOptions} */ ({})) {
   const { request, artifact, provider } = options;

package/src/loop.d.ts

@@ -105,6 +105,12 @@ export class Loop {
      * tool outcomes to `gate.record` (via wireGate) and never kill the loop on error.
      * @param {LoopOptions} options
      * @throws {Error} `[Loop] requires a provider` — when options.provider is missing.
+     * @when you are running a model think/act/observe cycle and need round accounting, tool dispatch, spin guards, and a governance chokepoint
+     * @fails returns the last assistant text with an `error` tag on any bound (halt/deny-streak/truncation/provider error); throws only if constructed without a provider. A policy HaltError exits clean.
+     * @example
+     *   const loop = new Loop({ provider, policy });
+     *   const { text, error, metrics } = await loop.run(messages, tools);
+     *   if (error) handle(error);
      */
     constructor(options?: LoopOptions);
     provider: import("../types").Provider;
@@ -161,7 +167,7 @@ export class Loop {
      *   thunk is re-evaluated each round (D4/eval-assist F2) so a tool set that grows mid-run — e.g. a skill
      *   unlocking its tools — is offered on the next round; a static array is resolved once at wire time.
      * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
      *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
      *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
      *   dangling assistant `tool_calls` from the halted round are paired with
@@ -199,6 +205,10 @@ export class Loop {
         model: string | null;
         msgs: Message[];
         metrics: RunMetrics;
+        malformedToolCall?: {
+            name: string | undefined;
+            error: string;
+        };
         temperatureDropped?: boolean;
     }>;
     _warnedTruncated: boolean | undefined;
@@ -228,7 +238,7 @@ export class Loop {
      * @param {string} text - User message.
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
      * @param {Record<string, any>} [options={}] - Per-run overrides.
-     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
      */
     chat(text: string, tools?: ToolDef[], options?: Record<string, any>): Promise<{
         text: string;
@@ -240,6 +250,10 @@ export class Loop {
         model: string | null;
         msgs: Message[];
         metrics: RunMetrics;
+        malformedToolCall?: {
+            name: string | undefined;
+            error: string;
+        };
         temperatureDropped?: boolean;
     }>;
     /**

package/src/loop.js

@@ -273,6 +273,12 @@ class Loop {
    * tool outcomes to `gate.record` (via wireGate) and never kill the loop on error.
    * @param {LoopOptions} options
    * @throws {Error} `[Loop] requires a provider` — when options.provider is missing.
+   * @when you are running a model think/act/observe cycle and need round accounting, tool dispatch, spin guards, and a governance chokepoint
+   * @fails returns the last assistant text with an `error` tag on any bound (halt/deny-streak/truncation/provider error); throws only if constructed without a provider. A policy HaltError exits clean.
+   * @example
+   *   const loop = new Loop({ provider, policy });
+   *   const { text, error, metrics } = await loop.run(messages, tools);
+   *   if (error) handle(error);
    */
   constructor(options = /** @type {LoopOptions} */ ({})) {
     if (!options.provider) throw new Error('[Loop] requires a provider');
@@ -449,7 +455,7 @@ class Loop {
    *   thunk is re-evaluated each round (D4/eval-assist F2) so a tool set that grows mid-run — e.g. a skill
    *   unlocking its tools — is offered on the next round; a static array is resolved once at wire time.
    * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
    *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
    *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
    *   dangling assistant `tool_calls` from the halted round are paired with
@@ -547,6 +553,14 @@ class Loop {
     // RESPONSE, not the provider object — a wrapped/fallback provider can lose `.model`). Surfaced on
     // every return so a caller reads which model produced the result without the onLlmResult side channel.
     let lastModel = null;
+    // BA-27: the most recent round's malformed-tool-call marker, or null. A model can emit a tool call
+    // whose arguments are syntactically-broken JSON; the provider returns NO usable tool calls plus this
+    // marker (rather than throwing and losing the billed round). Surfaced on the run's return like
+    // lastStopReason, so a Loop caller (e.g. the bareloop adopter — which reads run(), not generate())
+    // can tell "the model sent a broken call" apart from "the model sent no call at all" — both present
+    // as `toolCalls: []`. Reset each completed round; a malformed round always terminates the run (no
+    // usable call to continue with), so it can only be non-null on the round that returns.
+    let lastMalformedToolCall = null;
     // BA-10: sticky across rounds — true if ANY round's `temperature` was dropped by the model (400,
     // unsupported/deprecated) and retried without it. Surfaced on the result so an upstream receipt
     // (recurse's refineLeaf) can report the EFFECTIVE temperature rather than the ignored request.
@@ -583,7 +597,7 @@ class Loop {
         sealDanglingToolCalls(msgs, `[halted:${stuckTag}]`);
         this._reportError('stuck', new Error(`tool "${tc.name}" failed ${identicalErrors} times with identical arguments`), { rule: stuckTag, attempts: identicalErrors });
         this._safeEmit({ type: 'loop:done', data: { text: lastText, stuck: true, rule: stuckTag, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: stuckTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: stuckTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
       return null;
     };
@@ -830,7 +844,7 @@ class Loop {
         this._reportError('provider', err, { round });
         if (this.throwOnError) throw err;
         // BA-5: a mid-run provider failure must not erase the work of the rounds that succeeded.
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       lastUsage = result.usage || lastUsage;
@@ -843,6 +857,9 @@ class Loop {
       // path reads lastStopReason). Non-string / absent ⇒ null (the provider's pre-BA-6 degrade).
       lastStopReason = typeof result.stopReason === 'string' ? result.stopReason : null;
       if (typeof result.model === 'string' && result.model) lastModel = result.model;
+      // BA-27: capture (and reset) this round's malformed-tool-call marker for surfacing on the return.
+      lastMalformedToolCall = (result.malformedToolCall && typeof result.malformedToolCall === 'object')
+        ? result.malformedToolCall : null;
       if (result.temperatureDropped) temperatureDropped = true;
       // Publish the latest measured usage to ctx (non-enumerable, fail-open) so a transcript-bound seam —
       // e.g. F2 stash auto-compaction — can read EXACT provider-counted `inputTokens` to gauge context
@@ -927,7 +944,7 @@ class Loop {
         sealDanglingToolCalls(msgs, `[halted:${session.error}]`);
         this._reportError('session', new Error(`provider session terminated: ${session.error}`), { rule: session.error, sessionTurns: session.turns ?? null });
         this._safeEmit({ type: 'loop:done', data: { text: lastText, rule: session.error, sessionTurns: session.turns ?? null, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: session.error, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: session.error, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // BA-13: classify this round's terminal signal against the neutral stop-reason vocabulary. BA-6
@@ -992,7 +1009,7 @@ class Loop {
           msgs.push({ role: 'assistant', content: result.text });
         }
         this._safeEmit({ type: 'loop:done', data: { text: lastText, ...(terminal === 'truncated' && { truncated: true }), terminal, stopReason: lastStopReason, droppedToolCalls: dropped, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: errorTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: errorTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // No tool calls — LLM gave a final text response
@@ -1012,7 +1029,7 @@ class Loop {
           try { await flush(msgs, ctx); }
           catch (err) { if (err instanceof HaltError) throw err; this._reportError('trim-flush', err, { round }); }
         }
-        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // Execute tool calls
@@ -1121,7 +1138,7 @@ class Loop {
               sealDanglingToolCalls(msgs, `[halted:${denyTag}]`);
               this._reportError('denied', new Error(`policy denied ${consecutiveDenials} consecutive tool calls (${tc.name})`), { rule: denyTag, denials: consecutiveDenials });
               this._safeEmit({ type: 'loop:done', data: { text: lastText, denied: true, rule: denyTag, cost: totalCost } });
-              return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+              return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
             }
             continue;
           }
@@ -1195,7 +1212,7 @@ class Loop {
         // BA-5: the rule tag survives on `error`; so does the work. A halt is how a bounded attempt is
         // SUPPOSED to end — the caller reads `error` to know it was bounded and `text` to learn from it.
         this._safeEmit({ type: 'loop:done', data: { text: lastText, halted: true, rule, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
       throw err;
     }
@@ -1225,20 +1242,20 @@ class Loop {
             const rule = err.rule || 'unknown';
             this._reportError('halt', err, { rule, reason: err.decision?.reason ?? null });
             this._safeEmit({ type: 'loop:done', data: { text: lastText, halted: true, rule, cost: totalCost } });
-            return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+            return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
           }
           this._reportError('trim-flush', err, { phase: 'stop' });
         }
       }
       this._safeEmit({ type: 'loop:done', data: { text: lastText, stopped: true, cost: totalCost } });
-      return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+      return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
     }
 
     // Hard safety limit — should never fire under normal usage; bareguard's
     // limits.maxTurns (or the LLM's natural completion) ends the loop first.
     const warning = `[Loop] hit internal safety limit of ${HARD_ROUND_LIMIT} rounds. Wire bareguard for proper governance — see bare-agent/bareguard.`;
     this._safeEmit({ type: 'loop:done', data: { text: lastText, warning, cost: totalCost } });
-    return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+    return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
   }
 
   /**
@@ -1311,7 +1328,7 @@ class Loop {
    * @param {string} text - User message.
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
    * @param {Record<string, any>} [options={}] - Per-run overrides.
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
    */
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });

package/src/mcp-bridge.d.ts

@@ -92,6 +92,11 @@ export type RpcClient = {
  *   of this hook also opts default discovery into the project-cwd `./.mcp.json`,
  *   since each command is then vetted regardless of source.
  * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, close: Function}>}
+ * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution
+ * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); returns tools plus a close() to shut servers down.
+ * @example
+ *   const { tools, close } = await createMCPBridge();
+ *   const loop = new Loop({ provider, tools });
  */
 export function createMCPBridge(opts?: {
     bridgePath?: string | undefined;
@@ -120,6 +125,10 @@ export function createMCPBridge(opts?: {
  * @param {{ includeProjectConfig?: boolean }} [opts] - When no explicit `configPaths` are given,
  *   set `includeProjectConfig: true` to also scan `./.mcp.json`. Default false — see PROJECT_CONFIG_PATH.
  * @returns {Map<string, ServerDef>}
+ * @when you want to find configured MCP servers from the trusted $HOME/IDE config paths (or explicit paths) — discovery without invoking them
+ * @fails honors explicit configPaths verbatim and scans trusted defaults otherwise; returns a Map and never executes a server command.
+ * @example
+ *   const servers = discoverServers();
  */
 export function discoverServers(configPaths?: string[], { includeProjectConfig }?: {
     includeProjectConfig?: boolean;
@@ -142,5 +151,9 @@ export function discoverServers(configPaths?: string[], { includeProjectConfig }
  * @param {ToolDef[]} tools - The bulk-loaded, name-prefixed tools array.
  * @param {string} [discoveredAt] - ISO timestamp from .mcp-bridge.json.
  * @returns {ToolDef[]} [mcp_discover, mcp_invoke]
+ * @when you want the two bulk MCP meta-tools (mcp_discover, mcp_invoke) instead of exposing every discovered tool individually — one gate-check per invocation
+ * @fails returns [mcp_discover, mcp_invoke]; a tool name does not travel as action.type (a deliberate v0.9 trade for one gate-check per call).
+ * @example
+ *   const metaTools = buildMetaTools(tools);
  */
 export function buildMetaTools(tools: ToolDef[], discoveredAt?: string): ToolDef[];

package/src/mcp-bridge.js

@@ -80,6 +80,10 @@ const TRUSTED_CONFIG_PATHS = [
  * @param {{ includeProjectConfig?: boolean }} [opts] - When no explicit `configPaths` are given,
  *   set `includeProjectConfig: true` to also scan `./.mcp.json`. Default false — see PROJECT_CONFIG_PATH.
  * @returns {Map<string, ServerDef>}
+ * @when you want to find configured MCP servers from the trusted $HOME/IDE config paths (or explicit paths) — discovery without invoking them
+ * @fails honors explicit configPaths verbatim and scans trusted defaults otherwise; returns a Map and never executes a server command.
+ * @example
+ *   const servers = discoverServers();
  */
 function discoverServers(configPaths, { includeProjectConfig = false } = {}) {
   let paths;
@@ -523,6 +527,10 @@ function buildSystemContext(servers, tools, denied) {
  * @param {ToolDef[]} tools - The bulk-loaded, name-prefixed tools array.
  * @param {string} [discoveredAt] - ISO timestamp from .mcp-bridge.json.
  * @returns {ToolDef[]} [mcp_discover, mcp_invoke]
+ * @when you want the two bulk MCP meta-tools (mcp_discover, mcp_invoke) instead of exposing every discovered tool individually — one gate-check per invocation
+ * @fails returns [mcp_discover, mcp_invoke]; a tool name does not travel as action.type (a deliberate v0.9 trade for one gate-check per call).
+ * @example
+ *   const metaTools = buildMetaTools(tools);
  */
 function buildMetaTools(tools, discoveredAt) {
   // Catalog descriptors: same info the LLM would see for bulk-loaded tools,
@@ -637,6 +645,11 @@ function buildMetaTools(tools, discoveredAt) {
  *   of this hook also opts default discovery into the project-cwd `./.mcp.json`,
  *   since each command is then vetted regardless of source.
  * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, close: Function}>}
+ * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution
+ * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); returns tools plus a close() to shut servers down.
+ * @example
+ *   const { tools, close } = await createMCPBridge();
+ *   const loop = new Loop({ provider, tools });
  */
 async function createMCPBridge(opts = {}) {
   if ('policy' in opts) {

package/src/memory.d.ts

@@ -19,6 +19,11 @@ export class Memory {
     /**
      * @param {{ store?: Store }} [options] - Store backend (must implement store/search/get/delete).
      * @throws {Error} `[Memory] requires options.store` — when options.store is missing.
+     * @when you want thin store-backed memory (store/search/get/delete) an agent can write to and recall from, over any swappable backend
+     * @fails throws if constructed without a store; recall/store metering is opt-in via ctx. All persistence delegates to the backend.
+     * @example
+     *   const memory = new Memory({ store: new JsonFile({ path: './mem.json' }) });
+     *   await memory.store({ text: 'a durable fact' });
      */
     constructor(options?: {
         store?: Store;

package/src/memory.js

@@ -21,6 +21,11 @@ class Memory {
   /**
    * @param {{ store?: Store }} [options] - Store backend (must implement store/search/get/delete).
    * @throws {Error} `[Memory] requires options.store` — when options.store is missing.
+   * @when you want thin store-backed memory (store/search/get/delete) an agent can write to and recall from, over any swappable backend
+   * @fails throws if constructed without a store; recall/store metering is opt-in via ctx. All persistence delegates to the backend.
+   * @example
+   *   const memory = new Memory({ store: new JsonFile({ path: './mem.json' }) });
+   *   await memory.store({ text: 'a durable fact' });
    */
   constructor(options = {}) {
     if (!options.store) throw new Error('[Memory] requires options.store');

package/src/planner.d.ts

@@ -46,6 +46,12 @@ export class Planner {
     /**
      * @param {PlannerOptions} options
      * @throws {Error} `[Planner] requires a provider` — when options.provider is missing.
+     * @when you need to turn a goal into an ordered step DAG for an LLM to execute — optionally forcing exactly N independent steps for fan-out
+     * @fails throws if constructed without a provider; a plan call's HaltError (governance cap) propagates clean. Plan-call usage forwards via onLlmResult.
+     * @example
+     *   const planner = new Planner({ provider });
+     *   const steps = await planner.plan('ship the release', { count: 4 });
+     *   await runPlan(steps, ctx);
      */
     constructor(options?: PlannerOptions);
     provider: import("../types").Provider;

package/src/planner.js

@@ -39,6 +39,12 @@ class Planner {
   /**
    * @param {PlannerOptions} options
    * @throws {Error} `[Planner] requires a provider` — when options.provider is missing.
+   * @when you need to turn a goal into an ordered step DAG for an LLM to execute — optionally forcing exactly N independent steps for fan-out
+   * @fails throws if constructed without a provider; a plan call's HaltError (governance cap) propagates clean. Plan-call usage forwards via onLlmResult.
+   * @example
+   *   const planner = new Planner({ provider });
+   *   const steps = await planner.plan('ship the release', { count: 4 });
+   *   await runPlan(steps, ctx);
    */
   constructor(options = /** @type {PlannerOptions} */ ({})) {
     if (!options.provider) throw new Error('[Planner] requires a provider');

package/src/provider-anthropic.d.ts

@@ -62,6 +62,10 @@ export class AnthropicProvider {
     /**
      * @param {AnthropicOptions} [options]
      * @throws {Error} `[AnthropicProvider] requires apiKey` — when apiKey is missing.
+     * @when you want Claude models as the Loop's provider — native Messages API with opt-in prompt caching and thinking-block passthrough
+     * @fails throws on a missing apiKey; normalizes stopReason and usage (usage:null when the API omits it); a socket idle/deadline/transport cut rejects with a retryable Timeout/ProviderError.
+     * @example
+     *   const provider = new AnthropicProvider({ apiKey, model: 'claude-sonnet-5' });
      */
     constructor(options?: AnthropicOptions);
     apiKey: string;

package/src/provider-anthropic.js

@@ -41,6 +41,10 @@ class AnthropicProvider {
   /**
    * @param {AnthropicOptions} [options]
    * @throws {Error} `[AnthropicProvider] requires apiKey` — when apiKey is missing.
+   * @when you want Claude models as the Loop's provider — native Messages API with opt-in prompt caching and thinking-block passthrough
+   * @fails throws on a missing apiKey; normalizes stopReason and usage (usage:null when the API omits it); a socket idle/deadline/transport cut rejects with a retryable Timeout/ProviderError.
+   * @example
+   *   const provider = new AnthropicProvider({ apiKey, model: 'claude-sonnet-5' });
    */
   constructor(options = {}) {
     if (!options.apiKey) throw new Error('[AnthropicProvider] requires apiKey');

package/src/provider-clipipe.d.ts

@@ -123,6 +123,10 @@ export class CLIPipeProvider {
      * Provider that pipes prompts to a CLI command via stdin and reads stdout.
      * @param {CLIPipeOptions} [options]
      * @throws {Error} `[CLIPipeProvider] requires command` — when options.command is missing.
+     * @when you want to drive a CLI (e.g. the claude CLI) as the Loop's provider — native MCP tools or a JSON emulation envelope
+     * @fails throws on a missing command; in native mode it owns its own cycle (ownsCycle), so per-round Loop seams are refused at construction rather than left silently dead.
+     * @example
+     *   const provider = new CLIPipeProvider({ command: 'claude' });
      */
     constructor(options?: CLIPipeOptions);
     command: string;

package/src/provider-clipipe.js

@@ -112,6 +112,10 @@ class CLIPipeProvider {
    * Provider that pipes prompts to a CLI command via stdin and reads stdout.
    * @param {CLIPipeOptions} [options]
    * @throws {Error} `[CLIPipeProvider] requires command` — when options.command is missing.
+   * @when you want to drive a CLI (e.g. the claude CLI) as the Loop's provider — native MCP tools or a JSON emulation envelope
+   * @fails throws on a missing command; in native mode it owns its own cycle (ownsCycle), so per-round Loop seams are refused at construction rather than left silently dead.
+   * @example
+   *   const provider = new CLIPipeProvider({ command: 'claude' });
    */
   constructor(options = {}) {
     if (!options.command) throw new Error('[CLIPipeProvider] requires command');

package/src/provider-fallback.d.ts

@@ -27,6 +27,10 @@ export class FallbackProvider {
      * @param {Provider[]} providers - Ordered list of providers with generate().
      * @param {FallbackOptions} [options={}]
      * @throws {Error} `[FallbackProvider] requires at least one provider` — when providers is empty.
+     * @when you want to try several providers in order, failing over to the next when one errors — resilience across tiers or vendors
+     * @fails throws if given no providers; returns the first provider's success, else propagates the last provider's error.
+     * @example
+     *   const provider = new FallbackProvider([primary, backup]);
      */
     constructor(providers: Provider[], options?: FallbackOptions);
     providers: import("../types").Provider[];

package/src/provider-fallback.js

@@ -17,6 +17,10 @@ class FallbackProvider {
    * @param {Provider[]} providers - Ordered list of providers with generate().
    * @param {FallbackOptions} [options={}]
    * @throws {Error} `[FallbackProvider] requires at least one provider` — when providers is empty.
+   * @when you want to try several providers in order, failing over to the next when one errors — resilience across tiers or vendors
+   * @fails throws if given no providers; returns the first provider's success, else propagates the last provider's error.
+   * @example
+   *   const provider = new FallbackProvider([primary, backup]);
    */
   constructor(providers, options = {}) {
     if (!Array.isArray(providers) || providers.length === 0) {

package/src/provider-gemini.d.ts

@@ -45,7 +45,13 @@ export type GeminiOptions = {
  * cache-read tier populates with no opt-in.
  */
 export class GeminiProvider {
-    /** @param {GeminiOptions} [options] */
+    /**
+     * @param {GeminiOptions} [options]
+     * @when you want Gemini models as the Loop's provider — native generateContent with implicit prompt caching
+     * @fails throws on a missing apiKey; normalizes stopReason (promoting a complete tool call) and usage; a socket idle/deadline/transport cut rejects with a retryable error.
+     * @example
+     *   const provider = new GeminiProvider({ apiKey, model: 'gemini-2.5-pro' });
+     */
     constructor(options?: GeminiOptions);
     apiKey: string | undefined;
     model: string;

package/src/provider-gemini.js

@@ -40,7 +40,13 @@ function isLoopbackHost(hostname) {
  * cache-read tier populates with no opt-in.
  */
 class GeminiProvider {
-  /** @param {GeminiOptions} [options] */
+  /**
+   * @param {GeminiOptions} [options]
+   * @when you want Gemini models as the Loop's provider — native generateContent with implicit prompt caching
+   * @fails throws on a missing apiKey; normalizes stopReason (promoting a complete tool call) and usage; a socket idle/deadline/transport cut rejects with a retryable error.
+   * @example
+   *   const provider = new GeminiProvider({ apiKey, model: 'gemini-2.5-pro' });
+   */
   constructor(options = {}) {
     this.apiKey = options.apiKey?.trim();
     this.model = options.model || 'gemini-2.5-flash';

package/src/provider-ollama.d.ts

@@ -28,6 +28,10 @@ export type OllamaOptions = {
 export class OllamaProvider {
     /**
      * @param {OllamaOptions} [options]
+     * @when you want local models via Ollama as the Loop's provider — no API key, self-hosted
+     * @fails normalizes stopReason (promoting a complete tool call) and usage; a malformed tool-call JSON returns no usable calls with usage metered; a socket idle/deadline cut rejects with a retryable error.
+     * @example
+     *   const provider = new OllamaProvider({ model: 'llama3' });
      */
     constructor(options?: OllamaOptions);
     model: string;