crewhaus 0.1.8 → 0.2.0

package/dist/faq.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Item #55 — distill repeated user questions into an auto-discovered FAQ skill.
+ *
+ * `crewhaus faq distill` clusters recurring `user_message` questions across
+ * sessions (deterministic token clustering — the same greedy-jaccard approach
+ * `graders suggest` uses, no model call), pairs each cluster with its best-rated
+ * answer (the up-rated turn's output), and emits a SKILL.md FAQ skill into
+ * `.crewhaus/skills/faq/` so `@crewhaus/skills-registry` auto-discovers it —
+ * its name + description go into the prompt and the body loads on demand when
+ * the model invokes the `Skill` tool (the registry is lazy, not eager).
+ *
+ * Everything here is pure + deterministic so it is unit-testable; the FS access
+ * and PII/secret redaction wiring live in `apps/cli/src/index.ts`. Both the
+ * harvested ANSWER and the representative QUESTION are user/model text that may
+ * carry pasted credentials, so the caller redacts BOTH (via
+ * `SYNTHESIZE_PII_DETECTORS`) before they land in the skill body (#55 F4).
+ *
+ * The emitted SKILL.md is guaranteed valid per skills-registry's `parseSkillFile`
+ * (leading `---` frontmatter with `name` + `description`, then the FAQ body).
+ */
+import type { FeedbackRecord, LoggedEvent, SessionTurn } from "./feedback";
+/** One recurring-question cluster paired with its best answer. */
+export type FaqEntry = {
+    /** The representative (most-frequent-token, then shortest) question. */
+    readonly question: string;
+    /** The best-rated answer for the cluster (already redacted by the caller). */
+    readonly answer: string;
+    /** How many distinct sessions asked a question in this cluster. */
+    readonly sessionCount: number;
+    /** How many questions total fell into this cluster. */
+    readonly occurrences: number;
+};
+export type ClusterOptions = {
+    /** Jaccard overlap at/above which a question joins a cluster's seed. Default 0.5. */
+    readonly threshold?: number;
+    /** Minimum number of DISTINCT sessions that must ask a clustered question
+     *  for it to become an FAQ entry. Default 2 (recurring across sessions — a
+     *  one-off, or a single session that repeats itself, is not an FAQ). */
+    readonly minOccurrences?: number;
+    /** Normalized rating at/above which an answer is "good". Default 0.7. */
+    readonly minScore?: number;
+    /** Redactor for answers (async). Identity by default. */
+    readonly redact?: (text: string) => Promise<string>;
+};
+/**
+ * Build the FAQ entries from per-session turns + feedback. Deterministic:
+ * questions are clustered greedily by normalized-token Jaccard overlap in a
+ * stable visit order; each cluster keeps its best-rated answer (highest score,
+ * ties broken by session/turn order). Only clusters asked in ≥ `minOccurrences`
+ * DISTINCT sessions (#55 F9) AND with a qualifying answer (score ≥ `minScore`)
+ * become entries. Entries come back most-recurring-first.
+ */
+export declare function distillFaq(turnsBySession: ReadonlyArray<SessionTurn>, feedback: ReadonlyArray<FeedbackRecord>, opts?: ClusterOptions): Promise<FaqEntry[]>;
+/** Derive `SessionTurn`s from many sessions' event logs. Convenience wrapper so
+ *  the CLI and tests build the clustering input the same way. */
+export declare function turnsFromSessions(perSession: ReadonlyArray<{
+    sessionId: string;
+    events: ReadonlyArray<LoggedEvent>;
+}>): SessionTurn[];
+/**
+ * Render a valid SKILL.md for the FAQ. Frontmatter carries `name` +
+ * `description` (the required pair skills-registry enforces) plus `triggers`;
+ * the body is the Q→A list. Guaranteed to parse via `parseSkillFile`.
+ */
+export declare function buildFaqSkill(entries: ReadonlyArray<FaqEntry>, opts?: {
+    name?: string;
+    harnessName?: string;
+}): string;

package/dist/faq.js

@@ -0,0 +1,168 @@
+/**
+ * Item #55 — distill repeated user questions into an auto-discovered FAQ skill.
+ *
+ * `crewhaus faq distill` clusters recurring `user_message` questions across
+ * sessions (deterministic token clustering — the same greedy-jaccard approach
+ * `graders suggest` uses, no model call), pairs each cluster with its best-rated
+ * answer (the up-rated turn's output), and emits a SKILL.md FAQ skill into
+ * `.crewhaus/skills/faq/` so `@crewhaus/skills-registry` auto-discovers it —
+ * its name + description go into the prompt and the body loads on demand when
+ * the model invokes the `Skill` tool (the registry is lazy, not eager).
+ *
+ * Everything here is pure + deterministic so it is unit-testable; the FS access
+ * and PII/secret redaction wiring live in `apps/cli/src/index.ts`. Both the
+ * harvested ANSWER and the representative QUESTION are user/model text that may
+ * carry pasted credentials, so the caller redacts BOTH (via
+ * `SYNTHESIZE_PII_DETECTORS`) before they land in the skill body (#55 F4).
+ *
+ * The emitted SKILL.md is guaranteed valid per skills-registry's `parseSkillFile`
+ * (leading `---` frontmatter with `name` + `description`, then the FAQ body).
+ */
+import { deriveTurns, mergeFeedback, normalizeRating } from "./feedback";
+import { normalizeEvidenceTokens } from "./graders-suggest";
+function jaccard(a, b) {
+    let intersection = 0;
+    for (const t of a)
+        if (b.has(t))
+            intersection += 1;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Build the FAQ entries from per-session turns + feedback. Deterministic:
+ * questions are clustered greedily by normalized-token Jaccard overlap in a
+ * stable visit order; each cluster keeps its best-rated answer (highest score,
+ * ties broken by session/turn order). Only clusters asked in ≥ `minOccurrences`
+ * DISTINCT sessions (#55 F9) AND with a qualifying answer (score ≥ `minScore`)
+ * become entries. Entries come back most-recurring-first.
+ */
+export async function distillFaq(turnsBySession, feedback, opts = {}) {
+    const threshold = opts.threshold ?? 0.5;
+    const minOccurrences = opts.minOccurrences ?? 2;
+    const minScore = opts.minScore ?? 0.7;
+    const redact = opts.redact ?? (async (t) => t);
+    // Rating lookup keyed by session#turn.
+    const scoreByKey = new Map();
+    for (const fb of mergeFeedback(feedback)) {
+        const s = normalizeRating(fb);
+        if (s !== undefined)
+            scoreByKey.set(`${fb.sessionId}#${fb.turnNumber}`, s);
+    }
+    const records = turnsBySession
+        .filter((t) => t.input.trim() !== "")
+        .map((t) => ({
+        sessionId: t.sessionId,
+        turnNumber: t.turnNumber,
+        question: t.input.trim(),
+        answer: t.output,
+        score: scoreByKey.get(`${t.sessionId}#${t.turnNumber}`),
+    }))
+        .sort((a, b) => a.sessionId.localeCompare(b.sessionId) ||
+        a.turnNumber - b.turnNumber ||
+        a.question.localeCompare(b.question));
+    const clusters = [];
+    for (const rec of records) {
+        const tokens = new Set(normalizeEvidenceTokens(rec.question));
+        if (tokens.size === 0)
+            continue;
+        let bestIdx = -1;
+        let bestOverlap = 0;
+        for (let i = 0; i < clusters.length; i += 1) {
+            const overlap = jaccard(tokens, clusters[i].seed);
+            if (overlap > bestOverlap) {
+                bestOverlap = overlap;
+                bestIdx = i;
+            }
+        }
+        if (bestIdx >= 0 && bestOverlap >= threshold) {
+            const c = clusters[bestIdx];
+            c.items.push(rec);
+            c.tokenSets.push(tokens);
+        }
+        else {
+            clusters.push({ seed: tokens, items: [rec], tokenSets: [tokens] });
+        }
+    }
+    const entries = [];
+    for (const c of clusters) {
+        // #55 F9 — "recurring" means asked across DISTINCT sessions, not the same
+        // session twice. Gate on the distinct-session count so two questions from
+        // one session don't manufacture an FAQ entry at minOccurrences:2.
+        const sessionCount = new Set(c.items.map((i) => i.sessionId)).size;
+        if (sessionCount < minOccurrences)
+            continue;
+        // Best answer: highest-scored qualifying turn (stable tie-break by order).
+        const qualifying = c.items
+            .filter((i) => i.score !== undefined && i.score >= minScore && i.answer.trim() !== "")
+            .sort((a, b) => (b.score ?? 0) - (a.score ?? 0) ||
+            a.sessionId.localeCompare(b.sessionId) ||
+            a.turnNumber - b.turnNumber);
+        const best = qualifying[0];
+        if (best === undefined)
+            continue;
+        // Representative question: the shortest question in the cluster (most
+        // canonical phrasing), stable tie-break. #55 F4 — the representative
+        // question is a raw user turn rendered as a Markdown heading in SKILL.md,
+        // so it is redacted with the SAME redactor as the answer (a question can
+        // paste a secret/email just as an answer can).
+        const rawQuestion = [...c.items]
+            .map((i) => i.question)
+            .sort((a, b) => a.length - b.length || a.localeCompare(b))[0];
+        const question = (await redact(rawQuestion)).trim();
+        const answer = (await redact(best.answer)).trim();
+        if (question === "" || answer === "")
+            continue;
+        entries.push({
+            question,
+            answer,
+            sessionCount,
+            occurrences: c.items.length,
+        });
+    }
+    return entries.sort((a, b) => b.occurrences - a.occurrences || a.question.localeCompare(b.question));
+}
+/** Derive `SessionTurn`s from many sessions' event logs. Convenience wrapper so
+ *  the CLI and tests build the clustering input the same way. */
+export function turnsFromSessions(perSession) {
+    const turns = [];
+    for (const { sessionId, events } of perSession) {
+        for (const t of deriveTurns(events))
+            turns.push({ ...t, sessionId });
+    }
+    return turns;
+}
+/** YAML-escape a scalar for the SKILL.md frontmatter (JSON is a YAML subset). */
+function yamlScalar(s) {
+    return JSON.stringify(s);
+}
+/**
+ * Render a valid SKILL.md for the FAQ. Frontmatter carries `name` +
+ * `description` (the required pair skills-registry enforces) plus `triggers`;
+ * the body is the Q→A list. Guaranteed to parse via `parseSkillFile`.
+ */
+export function buildFaqSkill(entries, opts = {}) {
+    const name = opts.name ?? "faq";
+    const label = opts.harnessName ?? "this harness";
+    const description = `Frequently asked questions for ${label}, distilled from recurring user questions and their best-rated answers. Consult before answering common questions.`;
+    const triggers = ["faq", "frequently asked", "common question", "how do i"];
+    const bodyLines = [
+        `# FAQ — ${label}`,
+        "",
+        "These are recurring user questions paired with the answers users rated best. Prefer these answers for matching questions.",
+        "",
+    ];
+    entries.forEach((e, i) => {
+        bodyLines.push(`## Q${i + 1}: ${e.question}`);
+        bodyLines.push("");
+        bodyLines.push(e.answer);
+        bodyLines.push("");
+    });
+    const frontmatter = [
+        "---",
+        `name: ${yamlScalar(name)}`,
+        `description: ${yamlScalar(description)}`,
+        `triggers: ${JSON.stringify(triggers)}`,
+        "---",
+    ].join("\n");
+    return `${frontmatter}\n${bodyLines.join("\n")}`;
+}

package/dist/feedback.d.ts

@@ -165,6 +165,11 @@ export type GraderSpecObject = {
     name: string;
     type: "regex";
     pattern: string;
+} | {
+    name: string;
+    type: "json_path";
+    path: string;
+    expected?: unknown;
 } | {
     name: string;
     type: "llm_judge";
@@ -234,6 +239,8 @@ export declare function buildJudgeRubricGrader(positiveComments: ReadonlyArray<s
 /** One SampleSchema-valid JSON object per line (round-trips through loadJsonl). */
 export declare function samplesToJsonl(samples: ReadonlyArray<Sample>): string;
 /** Emit a GradersConfigSchema-valid graders.yaml. Scalars are JSON-encoded so
- *  arbitrary substrings/tool names stay YAML-safe (JSON is a YAML subset). */
-export declare function gradersConfigToYaml(config: GradersConfigObject): string;
+ *  arbitrary substrings/tool names stay YAML-safe (JSON is a YAML subset).
+ *  `headerLines` replaces the distill provenance header (each line must be a
+ *  full `# …` YAML comment). */
+export declare function gradersConfigToYaml(config: GradersConfigObject, headerLines?: ReadonlyArray<string>): string;
 export {};

package/dist/feedback.js

@@ -557,14 +557,19 @@ function commonToken(answers) {
 export function samplesToJsonl(samples) {
     return `${samples.map((s) => JSON.stringify(s)).join("\n")}\n`;
 }
+/** The default graders.yaml header — distill's provenance note. Callers with
+ *  a different provenance (scaffold-evals item 13, graders suggest item 4)
+ *  pass their own header lines instead. */
+const DISTILL_GRADERS_HEADER = [
+    "# Synthesized by `crewhaus distill` from user ratings.",
+    "# Exactly one grader — stacking graders hard-ANDs their scores (see eval-grader `all`).",
+];
 /** Emit a GradersConfigSchema-valid graders.yaml. Scalars are JSON-encoded so
- *  arbitrary substrings/tool names stay YAML-safe (JSON is a YAML subset). */
-export function gradersConfigToYaml(config) {
-    const lines = [
-        "# Synthesized by `crewhaus distill` from user ratings.",
-        "# Exactly one grader — stacking graders hard-ANDs their scores (see eval-grader `all`).",
-        "graders:",
-    ];
+ *  arbitrary substrings/tool names stay YAML-safe (JSON is a YAML subset).
+ *  `headerLines` replaces the distill provenance header (each line must be a
+ *  full `# …` YAML comment). */
+export function gradersConfigToYaml(config, headerLines = DISTILL_GRADERS_HEADER) {
+    const lines = [...headerLines, "graders:"];
     for (const g of config.graders) {
         lines.push(`  - name: ${JSON.stringify(g.name)}`);
         lines.push(`    type: ${g.type}`);
@@ -577,6 +582,11 @@ export function gradersConfigToYaml(config) {
             if (g.case_insensitive !== undefined)
                 lines.push(`    case_insensitive: ${g.case_insensitive}`);
         }
+        else if (g.type === "json_path") {
+            lines.push(`    path: ${JSON.stringify(g.path)}`);
+            if (g.expected !== undefined)
+                lines.push(`    expected: ${JSON.stringify(g.expected)}`);
+        }
         else if (g.type === "llm_judge") {
             lines.push("    rubric:");
             lines.push("      criteria:");

package/dist/fewshot.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Item #54 — harvest up-rated turns into a golden few-shot pool.
+ *
+ * `crewhaus fewshot harvest` mines POSITIVELY-rated conversation turns (the
+ * same `user_feedback` ratings `distill` consumes) into a curated pool of
+ * input→good-output few-shot examples. The pool is a versioned, provenance-
+ * tagged JSONL under `.crewhaus/fewshot/<spec>.jsonl`; `crewhaus optimize
+ * --few-shot <file>` injects the top-K examples into the agent prompt as
+ * in-context demonstrations, and `agent.instructions` can carry them at
+ * compile time via `formatFewShotForPrompt`.
+ *
+ * Everything here is pure + deterministic (stable ordering, id-based dedupe)
+ * so it is unit-testable; all filesystem access + the model/redactor wiring
+ * lives in `apps/cli/src/index.ts` (mirrors `feedback.ts` / `dataset-mine.ts`).
+ * The harvested OUTPUT text is the rated assistant answer (or the user's
+ * correction), so it is PII/secret-redacted before it lands in the pool: the
+ * caller threads a redactor built from `SYNTHESIZE_PII_DETECTORS` (the shared
+ * secret/API-key + DEFAULT_PII detector set) so a pasted credential never
+ * survives into the pool or the optimizer meta-prompt.
+ */
+import type { FeedbackRecord, SessionTurn } from "./feedback";
+/** Schema version of a persisted few-shot pool line. */
+export declare const FEWSHOT_SCHEMA_VERSION: 1;
+/** One curated few-shot example: an input paired with a known-good output. */
+export type FewShotExample = {
+    readonly schemaVersion: 1;
+    /** Stable id: `${sessionId}_t${turnNumber}` — the join key, dedupes reruns. */
+    readonly id: string;
+    readonly input: string;
+    readonly output: string;
+    /** [0,1] normalized rating that qualified this turn (or 1 for a correction). */
+    readonly score: number;
+    /** Provenance for audit + optimizer trust. */
+    readonly provenance: {
+        readonly sessionId: string;
+        readonly turnNumber: number;
+        /** "rating" (up-rated answer) | "correction" (user-supplied better answer). */
+        readonly source: "rating" | "correction";
+        readonly rater?: string;
+    };
+};
+export type HarvestOptions = {
+    /** Normalized score at/above which a rated turn qualifies. Default 0.7. */
+    readonly minScore?: number;
+    /** Async redactor applied to the harvested OUTPUT (and correction). The CLI
+     *  passes a `SYNTHESIZE_PII_DETECTORS`-backed redactor; tests pass a stub. */
+    readonly redact?: (text: string) => Promise<string>;
+};
+export type HarvestStats = {
+    readonly totalFeedback: number;
+    readonly qualified: number;
+    readonly skippedUnmatched: number;
+    readonly skippedEmpty: number;
+};
+export type HarvestResult = {
+    readonly examples: FewShotExample[];
+    readonly stats: HarvestStats;
+};
+/**
+ * Harvest positively-rated turns into few-shot examples. A turn qualifies when
+ * its merged rating normalizes to ≥ `minScore`, OR it carries a `correction`
+ * (the user's own better answer — always gold). The example OUTPUT is the
+ * correction when present, else the assistant's answer; empty answers are
+ * skipped. Deterministic: examples are sorted by (score desc, id asc) and
+ * deduped by id, so re-harvesting the same feedback is idempotent.
+ */
+export declare function harvestFewShot(turns: ReadonlyArray<SessionTurn>, feedback: ReadonlyArray<FeedbackRecord>, opts?: HarvestOptions): Promise<HarvestResult>;
+/** Narrow an arbitrary parsed JSON value to a persisted FewShotExample. */
+export declare function isFewShotExample(value: unknown): value is FewShotExample;
+/**
+ * Merge a freshly-harvested pool into an existing one, deduping by id (the
+ * newer example wins so re-runs refresh outputs without duplicating). Returns
+ * the deterministically-ordered union.
+ */
+export declare function mergePools(existing: ReadonlyArray<FewShotExample>, fresh: ReadonlyArray<FewShotExample>): FewShotExample[];
+/** Serialize a pool to JSONL (one example per line). */
+export declare function poolToJsonl(examples: ReadonlyArray<FewShotExample>): string;
+/**
+ * Render the top-K examples as an in-context few-shot block for the system
+ * prompt / `agent.instructions`. Empty input → "" so callers append
+ * unconditionally. `k` caps how many examples are injected (default 5).
+ */
+export declare function formatFewShotForPrompt(examples: ReadonlyArray<FewShotExample>, k?: number): string;

package/dist/fewshot.js

@@ -0,0 +1,158 @@
+/**
+ * Item #54 — harvest up-rated turns into a golden few-shot pool.
+ *
+ * `crewhaus fewshot harvest` mines POSITIVELY-rated conversation turns (the
+ * same `user_feedback` ratings `distill` consumes) into a curated pool of
+ * input→good-output few-shot examples. The pool is a versioned, provenance-
+ * tagged JSONL under `.crewhaus/fewshot/<spec>.jsonl`; `crewhaus optimize
+ * --few-shot <file>` injects the top-K examples into the agent prompt as
+ * in-context demonstrations, and `agent.instructions` can carry them at
+ * compile time via `formatFewShotForPrompt`.
+ *
+ * Everything here is pure + deterministic (stable ordering, id-based dedupe)
+ * so it is unit-testable; all filesystem access + the model/redactor wiring
+ * lives in `apps/cli/src/index.ts` (mirrors `feedback.ts` / `dataset-mine.ts`).
+ * The harvested OUTPUT text is the rated assistant answer (or the user's
+ * correction), so it is PII/secret-redacted before it lands in the pool: the
+ * caller threads a redactor built from `SYNTHESIZE_PII_DETECTORS` (the shared
+ * secret/API-key + DEFAULT_PII detector set) so a pasted credential never
+ * survives into the pool or the optimizer meta-prompt.
+ */
+import { mergeFeedback, normalizeRating } from "./feedback";
+/** Schema version of a persisted few-shot pool line. */
+export const FEWSHOT_SCHEMA_VERSION = 1;
+function turnKey(sessionId, turnNumber) {
+    return `${sessionId}#${turnNumber}`;
+}
+/**
+ * Harvest positively-rated turns into few-shot examples. A turn qualifies when
+ * its merged rating normalizes to ≥ `minScore`, OR it carries a `correction`
+ * (the user's own better answer — always gold). The example OUTPUT is the
+ * correction when present, else the assistant's answer; empty answers are
+ * skipped. Deterministic: examples are sorted by (score desc, id asc) and
+ * deduped by id, so re-harvesting the same feedback is idempotent.
+ */
+export async function harvestFewShot(turns, feedback, opts = {}) {
+    const minScore = opts.minScore ?? 0.7;
+    const redact = opts.redact ?? (async (t) => t);
+    const turnByKey = new Map();
+    for (const t of turns)
+        turnByKey.set(turnKey(t.sessionId, t.turnNumber), t);
+    const merged = mergeFeedback(feedback);
+    const byId = new Map();
+    let qualified = 0;
+    let skippedUnmatched = 0;
+    let skippedEmpty = 0;
+    for (const fb of merged) {
+        const turn = turnByKey.get(turnKey(fb.sessionId, fb.turnNumber));
+        if (turn === undefined) {
+            skippedUnmatched += 1;
+            continue;
+        }
+        const score = normalizeRating(fb);
+        const isCorrection = fb.correction !== undefined && fb.correction.trim() !== "";
+        const isPositive = (score !== undefined && score >= minScore) || isCorrection;
+        if (!isPositive)
+            continue;
+        const rawOutput = isCorrection ? fb.correction : turn.output;
+        if (rawOutput.trim() === "") {
+            skippedEmpty += 1;
+            continue;
+        }
+        const input = await redact(turn.input);
+        const output = await redact(rawOutput);
+        if (output.trim() === "") {
+            skippedEmpty += 1;
+            continue;
+        }
+        qualified += 1;
+        const id = `${fb.sessionId}_t${fb.turnNumber}`;
+        byId.set(id, {
+            schemaVersion: FEWSHOT_SCHEMA_VERSION,
+            id,
+            input,
+            output,
+            score: isCorrection ? 1 : (score ?? 1),
+            provenance: {
+                sessionId: fb.sessionId,
+                turnNumber: fb.turnNumber,
+                source: isCorrection ? "correction" : "rating",
+                ...(fb.rater !== undefined ? { rater: fb.rater } : {}),
+            },
+        });
+    }
+    const examples = [...byId.values()].sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return {
+        examples,
+        stats: {
+            totalFeedback: merged.length,
+            qualified,
+            skippedUnmatched,
+            skippedEmpty,
+        },
+    };
+}
+/** Narrow an arbitrary parsed JSON value to a persisted FewShotExample. */
+export function isFewShotExample(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (v["schemaVersion"] !== 1)
+        return false;
+    if (typeof v["id"] !== "string")
+        return false;
+    if (typeof v["input"] !== "string" || typeof v["output"] !== "string")
+        return false;
+    if (typeof v["score"] !== "number" || !Number.isFinite(v["score"]))
+        return false;
+    const p = v["provenance"];
+    if (typeof p !== "object" || p === null)
+        return false;
+    const pr = p;
+    return typeof pr["sessionId"] === "string" && typeof pr["turnNumber"] === "number";
+}
+/**
+ * Merge a freshly-harvested pool into an existing one, deduping by id (the
+ * newer example wins so re-runs refresh outputs without duplicating). Returns
+ * the deterministically-ordered union.
+ */
+export function mergePools(existing, fresh) {
+    const byId = new Map();
+    for (const e of existing)
+        byId.set(e.id, e);
+    for (const e of fresh)
+        byId.set(e.id, e);
+    return [...byId.values()].sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+/** Serialize a pool to JSONL (one example per line). */
+export function poolToJsonl(examples) {
+    return `${examples.map((e) => JSON.stringify(e)).join("\n")}\n`;
+}
+const FEWSHOT_CLOSE_TAG_RE = /<\s*\/\s*few_shot_examples\s*>/gi;
+/**
+ * #54 F5 — delimiter safety. An example's input/output is user/model text and
+ * can be adversarially shaped, so before interpolating it into the
+ * `<few_shot_examples>` block we neutralize any embedded closing tag: a
+ * `</few_shot_examples>` inside an example would otherwise let a poisoned
+ * example terminate the block early and inject trailing instructions. The
+ * closing tag is rewritten to an inert `<\/few_shot_examples>` (content
+ * preserved for the model, but no longer parses as the real delimiter).
+ * Redaction of secrets/PII already runs upstream — this is purely structural.
+ */
+function escapeFewShotContent(text) {
+    return text.replace(FEWSHOT_CLOSE_TAG_RE, "<\\/few_shot_examples>");
+}
+/**
+ * Render the top-K examples as an in-context few-shot block for the system
+ * prompt / `agent.instructions`. Empty input → "" so callers append
+ * unconditionally. `k` caps how many examples are injected (default 5).
+ */
+export function formatFewShotForPrompt(examples, k = 5) {
+    const top = examples.slice(0, Math.max(0, k));
+    if (top.length === 0)
+        return "";
+    const blocks = top
+        .map((e, i) => `Example ${i + 1}:\nUser: ${escapeFewShotContent(e.input)}\nAssistant: ${escapeFewShotContent(e.output)}`)
+        .join("\n\n");
+    return `<few_shot_examples>\nThese are examples of responses users rated highly. Follow their style and quality:\n\n${blocks}\n</few_shot_examples>`;
+}