@cleocode/core 2026.6.15 → 2026.6.17

package/dist/selfimprove/fix-gen-context.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Bounded file-content loader for the fix-gen stage (T11988).
+ *
+ * The self-improvement fix-gen stage builds a prompt for the LLM
+ * ({@link "./fix-gen.js".buildFixGenPrompt}). Without file context the model
+ * can only see the regression diff entries (e.g.
+ * `op tasks.show (#0) at data/task/status: actual="pending" expected="active"`)
+ * and rationally responds `NO_PATCH` because it cannot locate the responsible code.
+ *
+ * This module resolves the relevant source files for each regressing op-coordinate
+ * via the static map ({@link "./op-source-map.js"}) and reads their content with a
+ * **hard context budget** so the prompt stays bounded regardless of file size.
+ *
+ * ## Budget model
+ *
+ * Two independent byte-level caps:
+ *
+ *   - `perFileBudget` (default {@link DEFAULT_PER_FILE_BUDGET}): the maximum bytes
+ *     read from any single file. Files larger than this are truncated at a
+ *     newline boundary and a `<… TRUNCATED …>` marker is appended.
+ *   - `totalBudget` (default {@link DEFAULT_TOTAL_BUDGET}): the maximum total bytes
+ *     across ALL included files. Files are added in order (handler files first, then
+ *     core files); once the total would be exceeded the remaining files are
+ *     summarised as a path-only `<file listed but not loaded — budget exhausted>` stub.
+ *
+ * The caller embeds the resolved {@link LoadedFileContext} into the prompt. The LLM
+ * prompt builder ({@link "./fix-gen.js".buildFixGenPrompt}) inserts the file blocks
+ * between the regression description and the "produce the diff" instruction, giving
+ * the model concrete code to work from.
+ *
+ * Import-time side-effect-free: no logger init, no native handles.
+ *
+ * @module @cleocode/core/selfimprove/fix-gen-context
+ * @epic T11889
+ * @task T11988
+ */
+/**
+ * Per-file byte cap (default): any single file is truncated to at most 24 KB
+ * before being included in the prompt. Chosen to comfortably fit a large-ish
+ * handler or core module without overwhelming the model context.
+ */
+export declare const DEFAULT_PER_FILE_BUDGET = 24576;
+/**
+ * Total byte cap (default): the combined content of all included files must not
+ * exceed 65 KB. Keeps the combined code context section to a model-digestible
+ * slice of the context window even when multiple files are included.
+ */
+export declare const DEFAULT_TOTAL_BUDGET = 65536;
+/** Options for {@link loadFileContext}. */
+export interface LoadFileContextOptions {
+    /**
+     * Absolute project root. Source files are resolved relative to this path.
+     * Must be set to the actual repo root for the paths from the op-source-map
+     * to resolve correctly.
+     */
+    readonly projectRoot: string;
+    /**
+     * The op-coordinates whose source files should be loaded (e.g. `['tasks.show']`).
+     * Resolved via {@link collectOpSourceFiles}.
+     */
+    readonly opCoords: readonly string[];
+    /**
+     * Per-file byte budget (defaults to {@link DEFAULT_PER_FILE_BUDGET}).
+     * Files exceeding this are truncated with a `<… TRUNCATED …>` marker.
+     */
+    readonly perFileBudget?: number;
+    /**
+     * Total byte budget for all files combined
+     * (defaults to {@link DEFAULT_TOTAL_BUDGET}).
+     * Files whose content would push the total over budget are listed but not
+     * loaded (their path is emitted as a stub).
+     */
+    readonly totalBudget?: number;
+}
+/** A single file included in the context (content loaded or stubbed). */
+export interface FileContextEntry {
+    /** Repo-relative path (as returned by the op-source-map). */
+    readonly repoRelativePath: string;
+    /**
+     * File content (possibly truncated if `truncated` is `true`). `null` when the
+     * file was skipped due to the total budget being exhausted or a read error.
+     */
+    readonly content: string | null;
+    /**
+     * `true` when the file was truncated at the per-file budget; the loaded
+     * `content` ends with a `<… TRUNCATED …>` marker.
+     */
+    readonly truncated: boolean;
+    /**
+     * `true` when the total budget was exhausted before this file was loaded. The
+     * file appears in the context list but its `content` is `null`.
+     */
+    readonly budgetExhausted: boolean;
+    /**
+     * `true` when the file could not be read (missing, permission error, etc.).
+     * The file appears in the context list with `content: null`.
+     */
+    readonly readError: boolean;
+}
+/** Resolved file context for a set of op-coordinates. */
+export interface LoadedFileContext {
+    /** The resolved file entries (handler files first, then core files). */
+    readonly entries: readonly FileContextEntry[];
+    /** Total bytes of loaded content (across all non-skipped entries). */
+    readonly totalBytes: number;
+    /** Number of files that were truncated due to the per-file budget. */
+    readonly truncatedCount: number;
+    /** Number of files that were skipped due to the total budget. */
+    readonly budgetSkippedCount: number;
+    /** Number of files that could not be read. */
+    readonly errorCount: number;
+}
+/**
+ * Truncate `content` to at most `maxBytes` bytes, cutting at a newline boundary
+ * wherever possible, and appending a marker.
+ *
+ * Operates on raw bytes via `Buffer` so multi-byte characters don't produce
+ * partial surrogate pairs in the truncated output.
+ *
+ * @param content - The full file content string.
+ * @param maxBytes - The per-file byte cap.
+ * @returns `{ text, truncated }` — the (possibly shortened) string and a flag.
+ * @internal
+ */
+export declare function truncateToByteLimit(content: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Load bounded file content for the op-coordinates in a fix-gen request.
+ *
+ * Resolves the handler + core files for each `opCoord` via
+ * {@link collectOpSourceFiles}, reads them against `projectRoot`, applies the
+ * per-file and total byte budgets, and returns a structured
+ * {@link LoadedFileContext} describing every entry (loaded, truncated, skipped, or
+ * errored). NEVER throws — read errors produce `{ content: null, readError: true }`.
+ *
+ * @param opts - See {@link LoadFileContextOptions}.
+ * @returns The resolved {@link LoadedFileContext}.
+ *
+ * @example
+ * ```ts
+ * const ctx = loadFileContext({
+ *   projectRoot: '/repo',
+ *   opCoords: ['tasks.show'],
+ * });
+ * // ctx.entries[0].repoRelativePath  === 'packages/cleo/src/dispatch/domains/tasks.ts'
+ * // ctx.entries[1].repoRelativePath  === 'packages/core/src/tasks/show.ts'
+ * // ctx.totalBytes                   <= DEFAULT_TOTAL_BUDGET
+ * ```
+ */
+export declare function loadFileContext(opts: LoadFileContextOptions): LoadedFileContext;
+/**
+ * Render a {@link LoadedFileContext} as the file-context section of a fix-gen
+ * prompt.
+ *
+ * Produces a human-readable block listing each file with its content (or a stub
+ * explaining why the content was omitted). Suitable for direct embedding in the
+ * LLM user-turn after the regression description.
+ *
+ * @param ctx - The loaded file context.
+ * @returns A string ready for embedding in the prompt (empty string when no files).
+ *
+ * @example
+ * ```ts
+ * const section = renderFileContextSection(ctx);
+ * // --- packages/core/src/tasks/show.ts ---
+ * // <content or stub>
+ * ```
+ */
+export declare function renderFileContextSection(ctx: LoadedFileContext): string;
+//# sourceMappingURL=fix-gen-context.d.ts.map

package/dist/selfimprove/fix-gen-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-gen-context.d.ts","sourceRoot":"","sources":["../../src/selfimprove/fix-gen-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAQH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAI3C,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAatC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CAmF/E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAgBvE"}

package/dist/selfimprove/fix-gen-context.js

@@ -0,0 +1,218 @@
+/**
+ * Bounded file-content loader for the fix-gen stage (T11988).
+ *
+ * The self-improvement fix-gen stage builds a prompt for the LLM
+ * ({@link "./fix-gen.js".buildFixGenPrompt}). Without file context the model
+ * can only see the regression diff entries (e.g.
+ * `op tasks.show (#0) at data/task/status: actual="pending" expected="active"`)
+ * and rationally responds `NO_PATCH` because it cannot locate the responsible code.
+ *
+ * This module resolves the relevant source files for each regressing op-coordinate
+ * via the static map ({@link "./op-source-map.js"}) and reads their content with a
+ * **hard context budget** so the prompt stays bounded regardless of file size.
+ *
+ * ## Budget model
+ *
+ * Two independent byte-level caps:
+ *
+ *   - `perFileBudget` (default {@link DEFAULT_PER_FILE_BUDGET}): the maximum bytes
+ *     read from any single file. Files larger than this are truncated at a
+ *     newline boundary and a `<… TRUNCATED …>` marker is appended.
+ *   - `totalBudget` (default {@link DEFAULT_TOTAL_BUDGET}): the maximum total bytes
+ *     across ALL included files. Files are added in order (handler files first, then
+ *     core files); once the total would be exceeded the remaining files are
+ *     summarised as a path-only `<file listed but not loaded — budget exhausted>` stub.
+ *
+ * The caller embeds the resolved {@link LoadedFileContext} into the prompt. The LLM
+ * prompt builder ({@link "./fix-gen.js".buildFixGenPrompt}) inserts the file blocks
+ * between the regression description and the "produce the diff" instruction, giving
+ * the model concrete code to work from.
+ *
+ * Import-time side-effect-free: no logger init, no native handles.
+ *
+ * @module @cleocode/core/selfimprove/fix-gen-context
+ * @epic T11889
+ * @task T11988
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { collectOpSourceFiles } from './op-source-map.js';
+// ── Budget constants ────────────────────────────────────────────────────────
+/**
+ * Per-file byte cap (default): any single file is truncated to at most 24 KB
+ * before being included in the prompt. Chosen to comfortably fit a large-ish
+ * handler or core module without overwhelming the model context.
+ */
+export const DEFAULT_PER_FILE_BUDGET = 24_576; // 24 KB
+/**
+ * Total byte cap (default): the combined content of all included files must not
+ * exceed 65 KB. Keeps the combined code context section to a model-digestible
+ * slice of the context window even when multiple files are included.
+ */
+export const DEFAULT_TOTAL_BUDGET = 65_536; // 64 KB
+// ── Implementation ───────────────────────────────────────────────────────────
+/**
+ * Truncate `content` to at most `maxBytes` bytes, cutting at a newline boundary
+ * wherever possible, and appending a marker.
+ *
+ * Operates on raw bytes via `Buffer` so multi-byte characters don't produce
+ * partial surrogate pairs in the truncated output.
+ *
+ * @param content - The full file content string.
+ * @param maxBytes - The per-file byte cap.
+ * @returns `{ text, truncated }` — the (possibly shortened) string and a flag.
+ * @internal
+ */
+export function truncateToByteLimit(content, maxBytes) {
+    const buf = Buffer.from(content, 'utf8');
+    if (buf.length <= maxBytes) {
+        return { text: content, truncated: false };
+    }
+    // Cut at a newline boundary within the budget to avoid broken lines.
+    let cutAt = maxBytes;
+    while (cutAt > 0 && buf[cutAt] !== 0x0a /* '\n' */) {
+        cutAt--;
+    }
+    if (cutAt === 0)
+        cutAt = maxBytes; // no newline found — hard cut
+    const truncated = buf.slice(0, cutAt).toString('utf8');
+    return { text: `${truncated}\n<… TRUNCATED at ${maxBytes} bytes …>`, truncated: true };
+}
+/**
+ * Load bounded file content for the op-coordinates in a fix-gen request.
+ *
+ * Resolves the handler + core files for each `opCoord` via
+ * {@link collectOpSourceFiles}, reads them against `projectRoot`, applies the
+ * per-file and total byte budgets, and returns a structured
+ * {@link LoadedFileContext} describing every entry (loaded, truncated, skipped, or
+ * errored). NEVER throws — read errors produce `{ content: null, readError: true }`.
+ *
+ * @param opts - See {@link LoadFileContextOptions}.
+ * @returns The resolved {@link LoadedFileContext}.
+ *
+ * @example
+ * ```ts
+ * const ctx = loadFileContext({
+ *   projectRoot: '/repo',
+ *   opCoords: ['tasks.show'],
+ * });
+ * // ctx.entries[0].repoRelativePath  === 'packages/cleo/src/dispatch/domains/tasks.ts'
+ * // ctx.entries[1].repoRelativePath  === 'packages/core/src/tasks/show.ts'
+ * // ctx.totalBytes                   <= DEFAULT_TOTAL_BUDGET
+ * ```
+ */
+export function loadFileContext(opts) {
+    const perFileBudget = opts.perFileBudget ?? DEFAULT_PER_FILE_BUDGET;
+    const totalBudget = opts.totalBudget ?? DEFAULT_TOTAL_BUDGET;
+    // Resolve the unique set of source files for all op-coords.
+    const { handlerFiles, coreFiles } = collectOpSourceFiles(opts.opCoords);
+    // Handler files first (they contain the dispatch glue the model needs to locate
+    // where to apply the fix); core modules follow (they contain the business logic).
+    const allRelPaths = [...handlerFiles, ...coreFiles];
+    const entries = [];
+    let totalBytes = 0;
+    let truncatedCount = 0;
+    let budgetSkippedCount = 0;
+    let errorCount = 0;
+    for (const relPath of allRelPaths) {
+        const absPath = join(opts.projectRoot, relPath);
+        // Total budget exhausted — list the file but do not load it.
+        if (totalBytes >= totalBudget) {
+            entries.push({
+                repoRelativePath: relPath,
+                content: null,
+                truncated: false,
+                budgetExhausted: true,
+                readError: false,
+            });
+            budgetSkippedCount++;
+            continue;
+        }
+        // Read the file, gracefully handling any IO error.
+        let raw;
+        try {
+            raw = readFileSync(absPath, 'utf8');
+        }
+        catch {
+            entries.push({
+                repoRelativePath: relPath,
+                content: null,
+                truncated: false,
+                budgetExhausted: false,
+                readError: true,
+            });
+            errorCount++;
+            continue;
+        }
+        // Apply per-file budget.
+        const { text, truncated } = truncateToByteLimit(raw, perFileBudget);
+        const textBytes = Buffer.byteLength(text, 'utf8');
+        // If adding this file would bust the total budget, use a shorter slice that
+        // fits, then mark the file as budget-exhausted.
+        const remaining = totalBudget - totalBytes;
+        if (textBytes > remaining) {
+            const { text: fitted, truncated: fTrunc } = truncateToByteLimit(raw, remaining);
+            const fittedBytes = Buffer.byteLength(fitted, 'utf8');
+            entries.push({
+                repoRelativePath: relPath,
+                content: fittedBytes > 0 ? fitted : null,
+                truncated: fTrunc || truncated,
+                budgetExhausted: true,
+                readError: false,
+            });
+            totalBytes += fittedBytes;
+            truncatedCount += fTrunc || truncated ? 1 : 0;
+            budgetSkippedCount++;
+            continue;
+        }
+        entries.push({
+            repoRelativePath: relPath,
+            content: text,
+            truncated,
+            budgetExhausted: false,
+            readError: false,
+        });
+        totalBytes += textBytes;
+        if (truncated)
+            truncatedCount++;
+    }
+    return { entries, totalBytes, truncatedCount, budgetSkippedCount, errorCount };
+}
+/**
+ * Render a {@link LoadedFileContext} as the file-context section of a fix-gen
+ * prompt.
+ *
+ * Produces a human-readable block listing each file with its content (or a stub
+ * explaining why the content was omitted). Suitable for direct embedding in the
+ * LLM user-turn after the regression description.
+ *
+ * @param ctx - The loaded file context.
+ * @returns A string ready for embedding in the prompt (empty string when no files).
+ *
+ * @example
+ * ```ts
+ * const section = renderFileContextSection(ctx);
+ * // --- packages/core/src/tasks/show.ts ---
+ * // <content or stub>
+ * ```
+ */
+export function renderFileContextSection(ctx) {
+    if (ctx.entries.length === 0)
+        return '';
+    const lines = ['Relevant source files (bounded — apply the diff against these):'];
+    for (const entry of ctx.entries) {
+        lines.push('');
+        lines.push(`--- ${entry.repoRelativePath} ---`);
+        if (entry.readError) {
+            lines.push('<file not readable — patch by path only>');
+        }
+        else if (entry.budgetExhausted && entry.content === null) {
+            lines.push('<file listed but not loaded — context budget exhausted>');
+        }
+        else if (entry.content !== null) {
+            lines.push(entry.content);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=fix-gen-context.js.map

package/dist/selfimprove/fix-gen-context.js.map

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

package/dist/selfimprove/fix-gen.d.ts

@@ -39,6 +39,7 @@
  */
 import type { Logger } from 'pino';
 import type { DiffEntry } from './envelope-diff.js';
+import { type LoadedFileContext, type LoadFileContextOptions } from './fix-gen-context.js';
 /**
  * The structured request handed to a {@link FixGenerator}. Carries only what the
  * generator needs to draft a patch: the DHQ identity, the scenario, the
@@ -66,6 +67,19 @@ export interface FixGenRepoContext {
     readonly projectRoot: string;
     /** Optional one-line summary of what the scenario exercises. */
     readonly summary?: string;
+    /**
+     * Optional override for the file-context loading options (per-file budget,
+     * total budget). When absent the defaults from {@link "./fix-gen-context.js"}
+     * apply ({@link DEFAULT_PER_FILE_BUDGET} / {@link DEFAULT_TOTAL_BUDGET}).
+     *
+     * Setting `perFileBudget: 0` and `totalBudget: 0` effectively disables file
+     * context injection (the prompt degrades to the regression-only view — the model
+     * may still produce NO_PATCH, which is the honest outcome when context is
+     * insufficient).
+     *
+     * @task T11988
+     */
+    readonly contextBudget?: Pick<LoadFileContextOptions, 'perFileBudget' | 'totalBudget'>;
 }
 /** A generated patch, or an explicit "no usable patch" signal. */
 export type FixGenOutput = {
@@ -80,6 +94,13 @@ export type FixGenOutput = {
     readonly kind: 'none';
     /** Machine-stable reason for the absence. */
     readonly reason: string;
+    /**
+     * Credential-redacted, byte-bounded excerpt of the raw model reply (when the
+     * reason is `'model-declined'`). Absent for failure modes that have no reply
+     * (e.g. `'no-credential-resolved'`). Callers that log or persist this field
+     * MUST NOT additionally redact — it is pre-sanitized by the generator.
+     */
+    readonly rawReply?: string;
 };
 /**
  * The injectable fix-generation port (the LLM seam).
@@ -112,6 +133,14 @@ export type FixGenResult = {
     readonly kind: 'skipped';
     /** Machine-stable reason recorded on the DHQ evidence. */
     readonly reason: string;
+    /**
+     * Credential-redacted, byte-bounded excerpt of the raw model reply for
+     * `'model-declined'` and `'fixgen-not-a-diff'` outcomes. Absent for
+     * generator errors and other failure modes that have no usable reply text.
+     * Persisted on the DHQ evidence row so the loop operator can diagnose the
+     * model's actual output without re-running.
+     */
+    readonly replyExcerpt?: string;
 };
 /**
  * Options for {@link generateFixPatch}.
@@ -158,17 +187,44 @@ export declare function fixPatchPath(scenario: string, cwd?: string): string;
 export declare function looksLikeUnifiedDiff(text: string): boolean;
 /**
  * Build the system + user prompt the real generator sends to the LLM. Pure
- * (no IO) so it is unit-testable in isolation. The prompt is deliberately strict:
- * "respond with ONLY a unified diff" — anything else fails
- * {@link looksLikeUnifiedDiff} downstream and degrades to "no patch".
+ * (no IO) so it is unit-testable in isolation when an explicit `fileContext` is
+ * passed; the default path calls {@link loadFileContext} to resolve the relevant
+ * source files for each regressing op-coordinate (IO-bearing path used in
+ * production).
+ *
+ * The prompt is deliberately strict: "respond with ONLY a unified diff" — anything
+ * else fails {@link looksLikeUnifiedDiff} downstream and degrades to "no patch".
+ * When file context is available it is embedded between the regression description
+ * and the "produce the diff" instruction so the model can locate the responsible
+ * code. When context is absent (unmapped op or budget exhausted) the model is
+ * explicitly told it may respond `NO_PATCH` — this keeps the prompt honest.
  *
  * @param request - The fix-generation request.
+ * @param fileContext - Optional pre-loaded file context (injected for pure unit
+ *   tests). When absent, {@link loadFileContext} is called with the request's
+ *   `repoContext.projectRoot` and the op-coordinates from `regressions`.
  * @returns The `{ system, user }` prompt pair.
+ *
+ * @task T11988
  */
-export declare function buildFixGenPrompt(request: FixGenRequest): {
+export declare function buildFixGenPrompt(request: FixGenRequest, fileContext?: LoadedFileContext): {
     system: string;
     user: string;
 };
+/**
+ * Produce a credential-redacted, byte-bounded excerpt of a raw model reply for
+ * safe logging and DHQ evidence attachment.
+ *
+ * The excerpt is at most {@link REPLY_EXCERPT_MAX_BYTES} UTF-8 bytes. When the
+ * reply is longer a `…[truncated <N> bytes]` marker replaces the tail so the
+ * caller can distinguish a genuinely-short reply from a truncated one. The
+ * returned string is already passed through {@link redact} so no downstream
+ * scrubbing is needed.
+ *
+ * @param reply - The raw model reply text.
+ * @returns A scrubbed, bounded excerpt string.
+ */
+export declare function truncateReply(reply: string): string;
 /**
  * Run the fix-generation stage: ask the injected {@link FixGenerator} for a patch,
  * validate it as a unified diff, and write it to the egress-expected patch path.

package/dist/selfimprove/fix-gen.d.ts.map

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