@cleocode/core 2026.6.14 → 2026.6.17

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

@@ -0,0 +1,285 @@
+/**
+ * Fix-generation stage for the self-improvement loop (T11889 · T11975).
+ *
+ * This is the missing autonomous link the v1 loop explicitly stubbed out
+ * ("NO autonomous fix-gen in v1", see {@link "./run-loop.js"}): given a detected
+ * regression (an open `selfimprove_dhq` + its envelope-diff) plus minimal repo
+ * context, it asks the LLM to PROPOSE a unified-diff patch and writes that patch
+ * to the path the draft-PR egress ({@link "./draft-pr.js".openDraftPr}) already
+ * `existsSync`-checks: `<cwd>/selfimprove-<scenario>.patch`. Once the patch is on
+ * disk the existing egress guard opens ONE DRAFT PR — closing the
+ * DHQ → fix → draft-PR pipeline end-to-end.
+ *
+ * ## Hard safety posture (unchanged from v1 — P5 spec §B.7)
+ *
+ *   - **LLM ONLY via the E9 chokepoint.** The real generator
+ *     ({@link createLlmFixGenerator}) resolves its model strictly through
+ *     {@link "../llm/system-resolver.js".resolveLLMForSystem} → {@link ModelRunner}
+ *     (Gate-13). It constructs NO raw provider client, reads NO `*_API_KEY` env,
+ *     and hardcodes no model id — the resolver/registry is the SSoT. The
+ *     plaintext token is materialized only at the wire boundary (E10).
+ *   - **Draft-PR-ONLY, never auto-merge.** This module produces a PATCH FILE only;
+ *     the egress that consumes it always opens a `--draft` PR against a feature
+ *     branch (never `main`). This module performs NO git/gh action.
+ *   - **Graceful degrade, never a rogue mutation.** Every failure (no credential,
+ *     LLM error, empty / non-unified-diff output) returns a typed
+ *     {@link FixGenResult} of kind `'skipped'` and writes NO patch file — so the
+ *     existing egress guard (`existsSync` on the patch path) simply skips the PR.
+ *     This function NEVER throws.
+ *   - **Injectable seam.** The LLM dependency is the {@link FixGenerator} port;
+ *     unit tests inject a deterministic fake that returns a canned patch, so NO
+ *     real LLM is reached in tests.
+ *
+ * CORE-first: this engine lives in `core` and owns the `FixGenerator` port TYPE.
+ * Import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/fix-gen
+ * @epic T11889
+ * @task T11975
+ */
+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
+ * regression diff, and a minimal slice of repo context.
+ */
+export interface FixGenRequest {
+    /** The stable `'DHQ-###'` handle of the open regression. */
+    readonly dhqId: string;
+    /** The scenario whose replay diverged from the golden. */
+    readonly scenario: string;
+    /** The idempotency hash tying this request to ONE open DHQ row. */
+    readonly questionHash: string;
+    /** The structured regression entries (the evidence) from the envelope diff. */
+    readonly regressions: readonly DiffEntry[];
+    /**
+     * Minimal repo context the generator may use to ground the patch (e.g. the
+     * project root, a short description). Kept small on purpose — the loop does NOT
+     * stuff the whole repo into the prompt.
+     */
+    readonly repoContext: FixGenRepoContext;
+}
+/** Minimal repo context grounding a fix-generation request. */
+export interface FixGenRepoContext {
+    /** Absolute project root the patch is generated against. */
+    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 = {
+    /** The generator produced a candidate unified-diff patch. */
+    readonly kind: 'patch';
+    /** The raw unified-diff text (validated by {@link generateFixPatch}). */
+    readonly diff: string;
+    /** The model id that produced it (for audit). */
+    readonly model: string;
+} | {
+    /** The generator produced no usable patch (degrade — never an error throw). */
+    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).
+ *
+ * The real implementation ({@link createLlmFixGenerator}) drives the E9 chokepoint;
+ * tests inject a deterministic fake returning a canned patch. A `FixGenerator`
+ * MUST NOT throw — it encodes "no patch" as `{ kind: 'none', reason }`.
+ */
+export interface FixGenerator {
+    /**
+     * Propose a unified-diff patch for one regression.
+     *
+     * @param request - The structured {@link FixGenRequest}.
+     * @returns A {@link FixGenOutput} — a candidate patch or an explicit "none".
+     */
+    propose(request: FixGenRequest): Promise<FixGenOutput>;
+}
+/** The terminal outcome of {@link generateFixPatch}. */
+export type FixGenResult = {
+    /** A validated patch was written to {@link FixGenResultWritten.patchPath}. */
+    readonly kind: 'written';
+    /** Absolute path the patch was written to. */
+    readonly patchPath: string;
+    /** Byte length of the written patch. */
+    readonly bytes: number;
+    /** The model id that produced the patch. */
+    readonly model: string;
+} | {
+    /** No patch was written; the egress guard will skip the PR. */
+    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}.
+ */
+export interface GenerateFixPatchOptions {
+    /** The structured fix-generation request. */
+    readonly request: FixGenRequest;
+    /** The injected generator (real LLM impl or a test fake). */
+    readonly generator: FixGenerator;
+    /**
+     * Working directory the patch path is resolved against — MUST match the `cwd`
+     * the downstream {@link "./draft-pr.js".openDraftPr} uses, so the file it writes
+     * is the file the egress finds.
+     */
+    readonly cwd?: string;
+    /** Injectable logger (defaults to the module logger). */
+    readonly logger?: Logger;
+}
+/**
+ * Compute the patch path the draft-PR egress expects for a scenario:
+ * `<cwd>/selfimprove-<scenario>.patch`. The scenario is sanitized to a safe file
+ * stem so a hostile scenario name cannot escape the cwd.
+ *
+ * @param scenario - The scenario name.
+ * @param cwd - The working directory to resolve against (defaults to `process.cwd`).
+ * @returns The absolute patch path.
+ */
+export declare function fixPatchPath(scenario: string, cwd?: string): string;
+/**
+ * Is `text` a plausible unified diff?
+ *
+ * A real `git apply`-able patch always carries at least one of the canonical
+ * unified-diff markers ({@link UNIFIED_DIFF_MARKERS}). An LLM that returns prose,
+ * an apology, or an empty string fails this guard, so the loop degrades to "no
+ * patch" rather than writing junk the egress would then fail to `git apply`.
+ *
+ * This is a cheap structural sniff, NOT a full parse — the authoritative
+ * applicability check is `git apply` inside the egress (which fails the PR cut on
+ * a bad patch, never `main`).
+ *
+ * @param text - Candidate patch text.
+ * @returns `true` when the text looks like a unified diff.
+ */
+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 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, 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.
+ *
+ * This function NEVER throws and NEVER mutates anything but the single patch file.
+ * On ANY degrade path — generator returns `'none'`, the generator throws, or the
+ * returned text is not a unified diff — it writes NO file and returns
+ * `{ kind: 'skipped', reason }`, so the downstream `existsSync` egress guard
+ * simply skips the PR. The caller records the `reason` on the DHQ evidence.
+ *
+ * @param opts - See {@link GenerateFixPatchOptions}.
+ * @returns A {@link FixGenResult}.
+ *
+ * @example
+ * ```ts
+ * const res = await generateFixPatch({
+ *   request: { dhqId: 'DHQ-abcd1234', scenario, questionHash, regressions, repoContext },
+ *   generator: createLlmFixGenerator(),
+ *   cwd: projectRoot,
+ * });
+ * if (res.kind === 'written') { // openDraftPr will now find selfimprove-<scenario>.patch }
+ * ```
+ */
+export declare function generateFixPatch(opts: GenerateFixPatchOptions): Promise<FixGenResult>;
+/**
+ * Construct the REAL fix generator — the one that drives the E9 LLM chokepoint.
+ *
+ * Resolution funnels through {@link resolveLLMForSystem}(`'task-executor'`) →
+ * {@link ModelRunner.build} → `session.send` (ONE non-streaming completion).
+ * It constructs NO raw provider client, reads NO API-key env, and hardcodes no
+ * model id (Gate-13). The plaintext credential is materialized ONLY at the
+ * `ModelRunner` wire boundary (E10) via the sealed handle. When no credential is
+ * reachable it returns `{ kind: 'none' }` — the loop degrades to "no patch", no
+ * PR. This function constructs nothing at call time (lazy dynamic imports keep the
+ * module import-time side-effect-free + the E9 deps off the hot import path).
+ *
+ * @param opts - Optional project root threaded into the resolver.
+ * @returns A {@link FixGenerator} backed by the E9 chokepoint.
+ *
+ * @example
+ * ```ts
+ * const gen = createLlmFixGenerator({ projectRoot });
+ * const out = await gen.propose(request); // resolves model via E9, never raw client
+ * ```
+ */
+export declare function createLlmFixGenerator(opts?: {
+    projectRoot?: string;
+}): FixGenerator;
+/**
+ * Strip a single surrounding markdown code fence (```diff … ```), if present, so a
+ * model that wraps its diff still yields an applyable patch. A bare diff passes
+ * through untouched.
+ *
+ * @param text - Candidate patch text (already trimmed).
+ * @returns The fence-stripped text.
+ */
+export declare function stripCodeFences(text: string): string;
+//# sourceMappingURL=fix-gen.d.ts.map

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

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