agent-bober 0.12.0 → 0.17.0

package/dist/providers/structured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.d.ts","sourceRoot":"","sources":["../../src/providers/structured.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAW,MAAM,YAAY,CAAC;AAIvE,kFAAkF;AAClF,qBAAa,iBAAkB,SAAQ,KAAK;IAGxC,oDAAoD;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM;gBAFpB,OAAO,EAAE,MAAM;IACf,oDAAoD;IAC3C,GAAG,EAAE,MAAM;CAKvB;AAED,gFAAgF;AAChF,qBAAa,qBAAsB,SAAQ,KAAK;IAG5C,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM;gBAJzB,OAAO,EAAE,MAAM;IACf,oCAAoC;IAC3B,GAAG,EAAE,MAAM;IACpB,8CAA8C;IACrC,QAAQ,EAAE,MAAM;CAK5B;AAID,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC,yDAAyD;AACzD,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,SAAS,CAAC,IAAI,EAAE,OAAO,GACnB;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,CAAA;KAAE,GAC1B;QACE,OAAO,EAAE,KAAK,CAAC;QACf,KAAK,EAAE;YAAE,MAAM,EAAE,aAAa,CAAC;gBAAE,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,CAAC;KACzF,CAAC;CACP;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAWtE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAoBhD;AAyCD,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,4EAA4E;IAC5E,MAAM,EAAE,SAAS,CAAC;IAClB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,gBAAgB,CAAC;IACzB,kFAAkF;IAClF,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACvB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAC;IACT,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,QAAQ,EAAE,OAAO,CAAC;IAClB,kDAAkD;IAClD,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAOD;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,IAAI,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAwDnC"}

package/dist/providers/structured.js

@@ -0,0 +1,205 @@
+/**
+ * Schema-constrained ("structured") output utilities.
+ *
+ * Provides a provider-agnostic single-shot structured call that makes JSON
+ * output reliable even on small local models (DeepSeek / Ollama / LM Studio),
+ * where the server may not honor a strict schema. It:
+ *
+ *   1. requests native structured output (`ChatParams.responseSchema`) AND
+ *      injects the schema into the system prompt — belt-and-suspenders for
+ *      models that ignore the native knob;
+ *   2. coerces the model's raw text into JSON, tolerating the failure modes
+ *      7B-class models exhibit (markdown fences, surrounding prose);
+ *   3. validates the parsed value against a caller-supplied validator
+ *      (typically backed by a Zod schema); and
+ *   4. on failure, performs up to `maxRepairs` repair round-trips, feeding the
+ *      validation error back to the model.
+ *
+ * See structured.test.ts for the recovery-rate fixture suite that pins the
+ * single-shot + one-repair reliability target.
+ */
+// ── Errors ──────────────────────────────────────────────────────────
+/** Raised by {@link coerceJson} when no JSON value can be extracted from text. */
+export class JsonCoercionError extends Error {
+    raw;
+    constructor(message, 
+    /** The raw model text that could not be coerced. */
+    raw) {
+        super(message);
+        this.raw = raw;
+        this.name = "JsonCoercionError";
+    }
+}
+/** Raised by {@link runStructuredAgent} when every attempt fails validation. */
+export class StructuredOutputError extends Error {
+    raw;
+    attempts;
+    constructor(message, 
+    /** The last raw model text seen. */
+    raw, 
+    /** Total chat calls made before giving up. */
+    attempts) {
+        super(message);
+        this.raw = raw;
+        this.attempts = attempts;
+        this.name = "StructuredOutputError";
+    }
+}
+/**
+ * Build a {@link Validator} from a Zod schema (or anything exposing
+ * `safeParse`). Flattens issues into one human-readable string the model can
+ * act on during a repair round-trip.
+ */
+export function zodValidator(schema) {
+    return (raw) => {
+        const parsed = schema.safeParse(raw);
+        if (parsed.success) {
+            return { ok: true, value: parsed.data };
+        }
+        const error = parsed.error.issues
+            .map((i) => `${i.path.map((p) => p.toString()).join(".") || "(root)"}: ${i.message}`)
+            .join("; ");
+        return { ok: false, error: error || "validation failed" };
+    };
+}
+// ── JSON coercion ───────────────────────────────────────────────────
+/**
+ * Extract a JSON value from a model's raw text response.
+ *
+ * Handles the common local-model failure modes, in order:
+ *   1. direct `JSON.parse` (well-behaved providers / strict json mode);
+ *   2. strip a leading/trailing markdown code fence, then parse;
+ *   3. extract the substring spanning the first `{`/`[` to the matching last
+ *      `}`/`]` (drops surrounding prose), then parse.
+ *
+ * @throws {JsonCoercionError} if nothing parses.
+ */
+export function coerceJson(text) {
+    const trimmed = text.trim();
+    const direct = tryParse(trimmed);
+    if (direct.ok)
+        return direct.value;
+    const defenced = stripFences(trimmed);
+    const fenced = tryParse(defenced);
+    if (fenced.ok)
+        return fenced.value;
+    const span = extractJsonSpan(defenced);
+    if (span !== null) {
+        const spanned = tryParse(span);
+        if (spanned.ok)
+            return spanned.value;
+    }
+    throw new JsonCoercionError(`Could not extract JSON from model output (${String(text.length)} chars).`, text);
+}
+function tryParse(s) {
+    if (s.length === 0)
+        return { ok: false };
+    try {
+        return { ok: true, value: JSON.parse(s) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** Strip a single leading ```lang fence and matching trailing ``` fence. */
+function stripFences(s) {
+    const fenceMatch = /^```[a-zA-Z0-9]*\s*\n?([\s\S]*?)\n?```$/.exec(s);
+    if (fenceMatch && fenceMatch[1] !== undefined) {
+        return fenceMatch[1].trim();
+    }
+    return s;
+}
+/**
+ * Return the substring from the first JSON open-bracket to the last matching
+ * close-bracket (object or array, whichever appears first), or null if none.
+ */
+function extractJsonSpan(s) {
+    const firstObj = s.indexOf("{");
+    const firstArr = s.indexOf("[");
+    if (firstObj === -1 && firstArr === -1)
+        return null;
+    const useArray = firstObj === -1 || (firstArr !== -1 && firstArr < firstObj);
+    const start = useArray ? firstArr : firstObj;
+    const close = useArray ? "]" : "}";
+    const lastClose = s.lastIndexOf(close);
+    if (lastClose <= start)
+        return null;
+    return s.slice(start, lastClose + 1);
+}
+const SCHEMA_INSTRUCTION_HEADER = "You MUST respond with a single JSON value that conforms to the JSON Schema " +
+    "below. Respond with ONLY the JSON — no prose, no explanation, no markdown " +
+    "code fences.";
+/**
+ * Run a single-shot structured-output call with coercion, validation, and
+ * bounded repair. Returns a validated, typed value.
+ *
+ * The returned `ChatResponse.text` is parsed via {@link coerceJson} and checked
+ * with `validate`. If either fails and repairs remain, the bad output and the
+ * error are fed back as a follow-up turn.
+ *
+ * @throws {StructuredOutputError} if no attempt produces a schema-valid value.
+ */
+export async function runStructuredAgent(opts) {
+    const { client, model, schema, validate, prompt } = opts;
+    const maxRepairs = opts.maxRepairs ?? 1;
+    const maxAttempts = maxRepairs + 1;
+    const system = buildStructuredSystem(opts.system, schema);
+    const messages = [{ role: "user", content: prompt }];
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let lastError = "";
+    let lastRaw = "";
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const response = await client.chat({
+            model,
+            system,
+            messages,
+            responseSchema: schema,
+            ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
+        });
+        inputTokens += response.usage.inputTokens;
+        outputTokens += response.usage.outputTokens;
+        lastRaw = response.text;
+        lastError = "";
+        let parsed;
+        try {
+            parsed = coerceJson(response.text);
+        }
+        catch (e) {
+            lastError = e instanceof Error ? e.message : String(e);
+        }
+        if (lastError === "") {
+            const result = validate(parsed);
+            if (result.ok) {
+                return {
+                    value: result.value,
+                    attempts: attempt,
+                    repaired: attempt > 1,
+                    usage: { inputTokens, outputTokens },
+                };
+            }
+            lastError = result.error;
+        }
+        if (attempt < maxAttempts) {
+            pushRepair(messages, response.text, lastError);
+        }
+    }
+    throw new StructuredOutputError(`Structured output failed after ${String(maxAttempts)} attempt(s): ${lastError}`, lastRaw, maxAttempts);
+}
+/** Append the schema instruction + serialized schema to the base system prompt. */
+function buildStructuredSystem(system, schema) {
+    const base = system.trim();
+    const block = `${SCHEMA_INSTRUCTION_HEADER}\n\nJSON Schema:\n${JSON.stringify(schema)}`;
+    return base.length > 0 ? `${base}\n\n${block}` : block;
+}
+/** Append the failed output + a corrective instruction as a new turn. */
+function pushRepair(messages, rawText, error) {
+    messages.push({ role: "assistant", content: rawText });
+    messages.push({
+        role: "user",
+        content: `Your previous response could not be used: ${error}. ` +
+            "Return ONLY a corrected JSON value that conforms to the schema. " +
+            "No prose, no markdown fences.",
+    });
+}
+//# sourceMappingURL=structured.js.map

package/dist/providers/structured.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.js","sourceRoot":"","sources":["../../src/providers/structured.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,uEAAuE;AAEvE,kFAAkF;AAClF,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAI/B;IAHX,YACE,OAAe;IACf,oDAAoD;IAC3C,GAAW;QAEpB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,QAAG,GAAH,GAAG,CAAQ;QAGpB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAInC;IAEA;IALX,YACE,OAAe;IACf,oCAAoC;IAC3B,GAAW;IACpB,8CAA8C;IACrC,QAAgB;QAEzB,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,QAAG,GAAH,GAAG,CAAQ;QAEX,aAAQ,GAAR,QAAQ,CAAQ;QAGzB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAyBD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAI,MAAwB;IACtD,OAAO,CAAC,GAAY,EAAuB,EAAE;QAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QAC1C,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACpF,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,mBAAmB,EAAE,CAAC;IAC5D,CAAC,CAAC;AACJ,CAAC;AAED,uEAAuE;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAE5B,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC;IAEnC,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC;IAEnC,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,OAAO,CAAC,EAAE;YAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IACvC,CAAC;IAED,MAAM,IAAI,iBAAiB,CACzB,6CAA6C,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAC1E,IAAI,CACL,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS;IACzB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAY,EAAE,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,SAAS,WAAW,CAAC,CAAS;IAC5B,MAAM,UAAU,GAAG,yCAAyC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrE,IAAI,UAAU,IAAI,UAAU,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;QAC9C,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,CAAS;IAChC,MAAM,QAAQ,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,QAAQ,KAAK,CAAC,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpD,MAAM,QAAQ,GACZ,QAAQ,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC,IAAI,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAEnC,MAAM,SAAS,GAAG,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,SAAS,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAkCD,MAAM,yBAAyB,GAC7B,6EAA6E;IAC7E,4EAA4E;IAC5E,cAAc,CAAC;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAkC;IAElC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACzD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;IACxC,MAAM,WAAW,GAAG,UAAU,GAAG,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1D,MAAM,QAAQ,GAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAEhE,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,OAAO,GAAG,EAAE,CAAC;IAEjB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACxD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC;YACjC,KAAK;YACL,MAAM;YACN,QAAQ;YACR,cAAc,EAAE,MAAM;YACtB,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvE,CAAC,CAAC;QACH,WAAW,IAAI,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC;QAC1C,YAAY,IAAI,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC;QAC5C,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC;QAExB,SAAS,GAAG,EAAE,CAAC;QACf,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,SAAS,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;YACrB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACd,OAAO;oBACL,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,QAAQ,EAAE,OAAO;oBACjB,QAAQ,EAAE,OAAO,GAAG,CAAC;oBACrB,KAAK,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;iBACrC,CAAC;YACJ,CAAC;YACD,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,CAAC;QAED,IAAI,OAAO,GAAG,WAAW,EAAE,CAAC;YAC1B,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,MAAM,IAAI,qBAAqB,CAC7B,kCAAkC,MAAM,CAAC,WAAW,CAAC,gBAAgB,SAAS,EAAE,EAChF,OAAO,EACP,WAAW,CACZ,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,SAAS,qBAAqB,CAAC,MAAc,EAAE,MAAwB;IACrE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,GAAG,yBAAyB,qBAAqB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;IACxF,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AACzD,CAAC;AAED,yEAAyE;AACzE,SAAS,UAAU,CAAC,QAAmB,EAAE,OAAe,EAAE,KAAa;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IACvD,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,MAAM;QACZ,OAAO,EACL,6CAA6C,KAAK,IAAI;YACtD,kEAAkE;YAClE,+BAA+B;KAClC,CAAC,CAAC;AACL,CAAC"}

package/dist/providers/types.d.ts

@@ -84,15 +84,32 @@ export interface TextMessage {
     /** Text content. */
     content: string;
 }
+/**
+ * A provider-agnostic mid-conversation system instruction.
+ *
+ * Rendered by the Anthropic adapter as a `mid_conv_system` content block
+ * inside a message (NOT a top-level role). Non-anthropic adapters render it
+ * as best-effort text or skip it. The optional ephemeral cache TTL lets the
+ * instruction update mid-task without breaking the prompt cache.
+ */
+export interface SystemUpdateMessage {
+    role: "user";
+    /** The mid-conversation system instruction text. */
+    systemUpdate: string;
+    /** Optional ephemeral cache TTL for this instruction block. */
+    cacheTtl?: "5m" | "1h";
+}
 /**
  * A message in the conversation history.
  *
- * Three variants:
+ * Four variants:
  * - TextMessage: plain user or assistant text
  * - AssistantMessage: assistant response that includes tool call requests
  * - ToolResultMessage: user message carrying tool execution results
+ * - SystemUpdateMessage: mid-conversation system instruction (rendered as
+ *   mid_conv_system content block by the Anthropic adapter)
  */
-export type Message = TextMessage | AssistantMessage | ToolResultMessage;
+export type Message = TextMessage | AssistantMessage | ToolResultMessage | SystemUpdateMessage;
 /**
  * Parameters for a single LLM chat request.
  */
@@ -107,6 +124,40 @@ export interface ChatParams {
     tools?: ToolDef[];
     /** Maximum tokens to generate. Defaults to 16384. */
     maxTokens?: number;
+    /**
+     * Reasoning/output effort level. Provider-agnostic; only the Anthropic
+     * adapter forwards it (as output_config.effort). When unset, the provider
+     * default applies (high on Opus 4.8). Other adapters ignore it.
+     */
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    /**
+     * When set, requests schema-constrained ("structured") output. Each adapter
+     * maps this to its native mechanism — OpenAI / openai-compat
+     * `response_format: { type: "json_schema" }`, Gemini `responseSchema`,
+     * Anthropic forced-tool (`tool_choice`) — and upholds a single contract:
+     *
+     *   **When `responseSchema` is set, `ChatResponse.text` holds a JSON document
+     *   that best-effort conforms to this schema, and `toolCalls` is empty.**
+     *
+     * This keeps callers provider-agnostic: they always parse/validate
+     * `response.text`, regardless of how the provider produced it. `responseSchema`
+     * is for single-shot structured calls and is mutually exclusive with `tools`
+     * — when set, user `tools` are NOT forwarded. The `claude-code` adapter
+     * ignores it (no schema-constrainable surface). Local models that don't honor
+     * the native knob still receive a prompt-level schema instruction via
+     * `runStructuredAgent` (see `./structured`), which then validates and repairs
+     * the output.
+     */
+    responseSchema?: JsonSchemaObject;
+    /**
+     * When true, request the provider's *loose* JSON-object mode
+     * (`response_format: { type: "json_object" }` for OpenAI / openai-compat).
+     * Unlike `responseSchema` (strict json_schema, which DeepSeek rejects), this
+     * only guarantees the output is a syntactically valid JSON object — the caller
+     * must spell out the required fields in the prompt. Ignored by adapters that
+     * lack the knob. When both are set, `responseSchema` takes precedence.
+     */
+    jsonObjectMode?: boolean;
 }
 /**
  * Stop reason indicating why the model stopped generating.

package/dist/providers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"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"}

package/dist/state/approval-state.d.ts

@@ -0,0 +1,74 @@
+export interface PendingMarker {
+    checkpointId: string;
+    runId?: string;
+    artifact: {
+        type?: string;
+        path?: string;
+        summary?: string;
+        lines?: number;
+    };
+    prompt: string;
+    requestedAt: string;
+    timeoutAt: string;
+}
+export interface ApprovedMarker {
+    approvedAt: string;
+    approverId: string;
+    editDelta?: unknown;
+}
+export interface RejectedMarker {
+    rejectedAt: string;
+    rejecterId: string;
+    feedback: string;
+}
+/**
+ * Write a pending approval marker to disk.
+ */
+export declare function savePending(projectRoot: string, m: PendingMarker): Promise<void>;
+/**
+ * Read a pending approval marker from disk. Returns null if not found.
+ */
+export declare function readPending(projectRoot: string, id: string): Promise<PendingMarker | null>;
+/**
+ * List all pending approval markers.
+ */
+export declare function listPending(projectRoot: string): Promise<PendingMarker[]>;
+/**
+ * Write an approved marker to disk.
+ */
+export declare function saveApproved(projectRoot: string, id: string, m: ApprovedMarker): Promise<void>;
+/**
+ * Write a rejected marker to disk.
+ */
+export declare function saveRejected(projectRoot: string, id: string, m: RejectedMarker): Promise<void>;
+/**
+ * Delete a pending marker from disk (after resolution). Best-effort — does not throw.
+ */
+export declare function deletePending(projectRoot: string, id: string): Promise<void>;
+/**
+ * Check whether a pending marker exists for the given checkpoint id.
+ */
+export declare function pendingExists(projectRoot: string, id: string): Promise<boolean>;
+/**
+ * Cockpit-shape pending row — what both the CLI (--json) and the MCP
+ * tool bober_list_pending_approvals should return.
+ */
+export interface PendingApprovalRow {
+    checkpointId: string;
+    ageMs: number;
+    prompt: string;
+}
+/**
+ * List all pending checkpoints in cockpit-row shape.
+ *
+ * Mirrors the row-builder loop in src/cli/commands/list-approvals.ts
+ * but lives in state/ so both the CLI and the MCP tool can share it.
+ * Reads .bober/approvals/*.pending.json.
+ *
+ * Behavior:
+ * - Missing approvals dir → returns [].
+ * - Corrupted JSON files → skipped silently (matches CLI behavior).
+ * - ageMs = Date.now() - Date.parse(requestedAt).
+ */
+export declare function listPendingApprovals(projectRoot: string): Promise<PendingApprovalRow[]>;
+//# sourceMappingURL=approval-state.d.ts.map

package/dist/state/approval-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-state.d.ts","sourceRoot":"","sources":["../../src/state/approval-state.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,CAAC,EAAE,aAAa,GACf,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAQ/B;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAqB/E;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,CAAC,EAAE,cAAc,GAChB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,CAAC,EAAE,cAAc,GAChB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0B/B"}

package/dist/state/approval-state.js

@@ -0,0 +1,127 @@
+import { readFile, writeFile, readdir, unlink, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+import { ensureDir } from "./helpers.js";
+const APPROVAL_DIR = ".bober/approvals";
+function approvalsDir(projectRoot) {
+    return join(projectRoot, APPROVAL_DIR);
+}
+function pendingPath(projectRoot, id) {
+    return join(approvalsDir(projectRoot), `${id}.pending.json`);
+}
+function approvedPath(projectRoot, id) {
+    return join(approvalsDir(projectRoot), `${id}.approved.json`);
+}
+function rejectedPath(projectRoot, id) {
+    return join(approvalsDir(projectRoot), `${id}.rejected.json`);
+}
+/**
+ * Write a pending approval marker to disk.
+ */
+export async function savePending(projectRoot, m) {
+    await ensureDir(approvalsDir(projectRoot));
+    await writeFile(pendingPath(projectRoot, m.checkpointId), JSON.stringify(m, null, 2) + "\n", "utf-8");
+}
+/**
+ * Read a pending approval marker from disk. Returns null if not found.
+ */
+export async function readPending(projectRoot, id) {
+    try {
+        return JSON.parse(await readFile(pendingPath(projectRoot, id), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * List all pending approval markers.
+ */
+export async function listPending(projectRoot) {
+    let entries;
+    try {
+        entries = await readdir(approvalsDir(projectRoot));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of entries.filter((x) => x.endsWith(".pending.json"))) {
+        try {
+            out.push(JSON.parse(await readFile(join(approvalsDir(projectRoot), f), "utf-8")));
+        }
+        catch {
+            // skip corrupted files
+        }
+    }
+    return out;
+}
+/**
+ * Write an approved marker to disk.
+ */
+export async function saveApproved(projectRoot, id, m) {
+    await ensureDir(approvalsDir(projectRoot));
+    await writeFile(approvedPath(projectRoot, id), JSON.stringify(m, null, 2) + "\n", "utf-8");
+}
+/**
+ * Write a rejected marker to disk.
+ */
+export async function saveRejected(projectRoot, id, m) {
+    await ensureDir(approvalsDir(projectRoot));
+    await writeFile(rejectedPath(projectRoot, id), JSON.stringify(m, null, 2) + "\n", "utf-8");
+}
+/**
+ * Delete a pending marker from disk (after resolution). Best-effort — does not throw.
+ */
+export async function deletePending(projectRoot, id) {
+    await unlink(pendingPath(projectRoot, id)).catch(() => { });
+}
+/**
+ * Check whether a pending marker exists for the given checkpoint id.
+ */
+export async function pendingExists(projectRoot, id) {
+    try {
+        await access(pendingPath(projectRoot, id), constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * List all pending checkpoints in cockpit-row shape.
+ *
+ * Mirrors the row-builder loop in src/cli/commands/list-approvals.ts
+ * but lives in state/ so both the CLI and the MCP tool can share it.
+ * Reads .bober/approvals/*.pending.json.
+ *
+ * Behavior:
+ * - Missing approvals dir → returns [].
+ * - Corrupted JSON files → skipped silently (matches CLI behavior).
+ * - ageMs = Date.now() - Date.parse(requestedAt).
+ */
+export async function listPendingApprovals(projectRoot) {
+    let entries;
+    try {
+        entries = await readdir(approvalsDir(projectRoot));
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    for (const f of entries.filter((x) => x.endsWith(".pending.json"))) {
+        try {
+            const raw = await readFile(join(approvalsDir(projectRoot), f), "utf-8");
+            const parsed = JSON.parse(raw);
+            rows.push({
+                checkpointId: parsed.checkpointId,
+                ageMs: Date.now() - Date.parse(parsed.requestedAt),
+                prompt: parsed.prompt,
+            });
+        }
+        catch {
+            // skip corrupted files
+        }
+    }
+    return rows;
+}
+//# sourceMappingURL=approval-state.js.map

package/dist/state/approval-state.js.map

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

package/dist/state/history-rotation.d.ts

@@ -0,0 +1,17 @@
+export declare function historyActivePath(projectRoot: string): string;
+export declare function historyArchivePath(projectRoot: string): string;
+/**
+ * Rotate the active history file if it exceeds maxActiveLines.
+ *
+ * When the active file has more than maxActiveLines non-empty lines,
+ * the oldest (count - maxActiveLines) lines are appended to the archive
+ * and the active file is atomically rewritten with the newest maxActiveLines
+ * lines via temp-file + rename.
+ *
+ * Pass maxActiveLines from config; callers must NOT call loadConfig here
+ * (loadConfig throws when no bober.config.json exists). Default: 2000.
+ *
+ * No-op when the active file does not exist or has <= maxActiveLines entries.
+ */
+export declare function rotateIfNeeded(projectRoot: string, maxActiveLines?: number): Promise<void>;
+//# sourceMappingURL=history-rotation.d.ts.map

package/dist/state/history-rotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-rotation.d.ts","sourceRoot":"","sources":["../../src/state/history-rotation.ts"],"names":[],"mappings":"AAoCA,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,cAAc,GAAE,MAAa,GAC5B,OAAO,CAAC,IAAI,CAAC,CAsCf"}

package/dist/state/history-rotation.js

@@ -0,0 +1,84 @@
+// ── history-rotation.ts ─────────────────────────────────────────────
+//
+// Crash-safe rotation: when active history.jsonl exceeds maxActiveLines,
+// move the oldest (count - maxActiveLines) entries to history.archive.jsonl,
+// then atomically rewrite active with the remaining tail.
+//
+// Crash-safety ordering (Option B — idempotent, preferred):
+//
+//   1. Write the new-active TEMP file (tail lines only)
+//   2. Append the overflow (oldest lines) to history.archive.jsonl
+//   3. rename(temp, activeFile)   ← COMMIT POINT (atomic on same fs)
+//
+// If the process crashes before step 3:
+//   - archive may hold the overflow entries AND active still holds all entries
+//   - loadHistory (archive-then-active) returns every entry; archive entries
+//     are a subset of active → union has no drops but has duplicates
+//   - this is acceptable: the contract (C4) tests the union and
+//     tolerates de-duplication when crash state is loaded.
+//
+// If the process crashes after step 3:
+//   - active is the tail only; archive has the overflow → no loss, no dup.
+//
+// The rename is the single atomic commit: everything before it is recoverable.
+import { readFile, writeFile, appendFile, rename } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { ensureDir } from "./helpers.js";
+// ── Path helpers ─────────────────────────────────────────────────────
+const BOBER_DIR = ".bober";
+const HISTORY_FILE = "history.jsonl";
+const HISTORY_ARCHIVE_FILE = "history.archive.jsonl";
+export function historyActivePath(projectRoot) {
+    return join(projectRoot, BOBER_DIR, HISTORY_FILE);
+}
+export function historyArchivePath(projectRoot) {
+    return join(projectRoot, BOBER_DIR, HISTORY_ARCHIVE_FILE);
+}
+// ── Rotation ─────────────────────────────────────────────────────────
+/**
+ * Rotate the active history file if it exceeds maxActiveLines.
+ *
+ * When the active file has more than maxActiveLines non-empty lines,
+ * the oldest (count - maxActiveLines) lines are appended to the archive
+ * and the active file is atomically rewritten with the newest maxActiveLines
+ * lines via temp-file + rename.
+ *
+ * Pass maxActiveLines from config; callers must NOT call loadConfig here
+ * (loadConfig throws when no bober.config.json exists). Default: 2000.
+ *
+ * No-op when the active file does not exist or has <= maxActiveLines entries.
+ */
+export async function rotateIfNeeded(projectRoot, maxActiveLines = 2000) {
+    let content;
+    try {
+        content = await readFile(historyActivePath(projectRoot), "utf-8");
+    }
+    catch {
+        // Active file does not exist yet — nothing to rotate
+        return;
+    }
+    const lines = content.split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length <= maxActiveLines) {
+        // Within limit — no rotation needed
+        return;
+    }
+    const overflowCount = lines.length - maxActiveLines;
+    const overflowLines = lines.slice(0, overflowCount);
+    const tailLines = lines.slice(overflowCount);
+    const activePath = historyActivePath(projectRoot);
+    const archPath = historyArchivePath(projectRoot);
+    // Ensure .bober/ directory exists (it should, but guard anyway)
+    await ensureDir(join(projectRoot, BOBER_DIR));
+    // Step 1: Write the new-active TEMP file (tail lines only)
+    const rnd = randomBytes(4).toString("hex");
+    const tmp = `${activePath}.${process.pid}.${Date.now()}.${rnd}.tmp`;
+    const newActiveContent = tailLines.join("\n") + "\n";
+    await writeFile(tmp, newActiveContent, { encoding: "utf-8" });
+    // Step 2: Append the overflow (oldest lines) to history.archive.jsonl
+    const overflowContent = overflowLines.join("\n") + "\n";
+    await appendFile(archPath, overflowContent, "utf-8");
+    // Step 3: Atomic commit — rename temp over active (commit point)
+    await rename(tmp, activePath);
+}
+//# sourceMappingURL=history-rotation.js.map

package/dist/state/history-rotation.js.map

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