taskflow-core 0.1.4 → 0.1.6

package/dist/library/search.js

@@ -0,0 +1,298 @@
+/**
+ * Library — search ranking (structural + keyword; Phase 1).
+ *
+ * Phase 2 adds the embedding/cosine path; the seam (LibraryDeps.embedder) is
+ * already in place but left unused here. When no embedder is configured OR
+ * structureOnly is set, search degrades to keyword + structural ranking.
+ *
+ * Refs: docs/rfc-library-reuse.md §5.2 (blend), §5.2.1 (structScore),
+ * §5.2.2 (staleness), §5.3 (why/reuseHint templates).
+ */
+import { getFlow, listFlows, readMeta } from "../store.js";
+import { computeGenerality, computePhaseSignature, countPhases, extractAgentUsage, } from "./meta.js";
+// ---------------------------------------------------------------------------
+// Levenshtein (RFC §5.2.1)
+// ---------------------------------------------------------------------------
+/** Standard Levenshtein edit distance (insert/delete/replace cost 1).
+ *  O(m·n) DP; signature strings are short (<50 chars) so cost is negligible. */
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const m = a.length;
+    const n = b.length;
+    // Two rolling rows; allocate fresh each call (signatures are tiny).
+    let prev = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        const curr = new Array(n + 1);
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        prev = curr;
+    }
+    return prev[n];
+}
+// ---------------------------------------------------------------------------
+// Candidate resolution (RFC §5.2.2 staleness detection)
+// ---------------------------------------------------------------------------
+/** Resolve a saved flow + its sidecar into a candidate whose structural fields
+ *  are ALWAYS freshly derived from the current def, and whose embedding is only
+ *  trusted when the sidecar's phaseSignature matches the fresh one. */
+export function resolveCandidate(def, scope, name, sidecar) {
+    const freshSig = computePhaseSignature(def);
+    const freshGen = computeGenerality(def);
+    const freshAgents = extractAgentUsage(def);
+    const freshCount = countPhases(def);
+    if (!sidecar) {
+        return {
+            name,
+            scope,
+            def,
+            phaseSignature: freshSig,
+            phaseCount: freshCount,
+            agentUsage: freshAgents,
+            generality: freshGen,
+            reuseCount: 0,
+            version: 1,
+            embedding: null,
+            embeddingStale: true,
+        };
+    }
+    const sigMatch = sidecar.phaseSignature === freshSig;
+    return {
+        name,
+        scope,
+        def,
+        phaseSignature: freshSig,
+        phaseCount: freshCount,
+        agentUsage: freshAgents,
+        generality: freshGen,
+        purpose: sidecar.purpose,
+        tags: sidecar.tags,
+        notes: sidecar.notes,
+        reuseCount: sidecar.reuseCount ?? 0,
+        version: sidecar.version ?? 1,
+        derivedFrom: sidecar.derivedFrom,
+        embedding: sigMatch ? sidecar.embedding ?? null : null,
+        embeddingStale: !sigMatch,
+    };
+}
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+/** structScore ∈ [0,1]. RFC §5.2.1: 0.7*sigSim + 0.3*countPenalty. */
+function computeStructScore(query, cand) {
+    let sigSim = 0;
+    if (cand.phaseSignature && query.phaseSignature) {
+        const d = levenshtein(query.phaseSignature, cand.phaseSignature);
+        const denom = Math.max(query.phaseSignature.length, cand.phaseSignature.length, 1);
+        sigSim = 1 - d / denom;
+        if (sigSim < 0)
+            sigSim = 0;
+    }
+    let countPenalty = 0;
+    if (query.phaseCount > 0 && cand.phaseCount > 0) {
+        const diff = Math.abs(query.phaseCount - cand.phaseCount);
+        countPenalty = 1 - Math.min(1, diff / Math.max(query.phaseCount, cand.phaseCount));
+    }
+    return 0.7 * sigSim + 0.3 * countPenalty;
+}
+/** textScore ∈ [0,1]. Token-overlap between query and the flow's text fields
+ *  (name + purpose + tags + phase task text). CJK-aware: queries tokenized on
+ *  whitespace AND matched as substrings, so a Chinese query token like "鉴权"
+ *  still matches a purpose containing "...缺少鉴权检查..." (which whitespace
+ *  alone would never split out). */
+function computeTextScore(queryTokens, cand) {
+    if (queryTokens.length === 0)
+        return 0;
+    const fieldText = ((cand.name ?? "") +
+        " " +
+        (cand.purpose ?? "") +
+        " " +
+        (cand.tags ?? []).join(" ") +
+        " " +
+        cand.phaseTaskText).toLowerCase();
+    if (!fieldText.trim())
+        return 0;
+    // Substring match per query token (CJK-friendly). Longer tokens weigh more
+    // (they carry more signal) so e.g. a 2-char Chinese term counts more than a
+    // 2-char English one only marginally; this keeps the [0,1] shape intuitive.
+    let hits = 0;
+    for (const t of queryTokens) {
+        if (!t)
+            continue;
+        if (fieldText.includes(t))
+            hits++;
+    }
+    return hits / queryTokens.length;
+}
+function tokenize(query) {
+    return query
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((t) => t.length > 1);
+}
+function phaseTaskText(def) {
+    if (!Array.isArray(def.phases))
+        return "";
+    const parts = [];
+    for (const p of def.phases) {
+        if (typeof p.task === "string")
+            parts.push(p.task);
+        if (Array.isArray(p.branches)) {
+            for (const b of p.branches ?? []) {
+                if (b?.task)
+                    parts.push(b.task);
+            }
+        }
+    }
+    return parts.join(" ");
+}
+// ---------------------------------------------------------------------------
+// why / reuseHint templates (RFC §5.3, Tier 1, zero-token)
+// ---------------------------------------------------------------------------
+function buildWhy(s) {
+    const hits = [];
+    if ((s.searchMode === "semantic" || s.searchMode === "mixed") && s.semScore != null && s.semScore > 0.7) {
+        hits.push(`语义命中(sem=${s.semScore.toFixed(2)})`);
+    }
+    if (s.structScore > 0.8)
+        hits.push(`结构一致(struct=${s.structScore.toFixed(2)})`);
+    if (s.textScore > 0.3)
+        hits.push(`关键词匹配(text=${s.textScore.toFixed(2)})`);
+    return hits.length > 0 ? hits.join(" + ") : "低分命中，建议检查";
+}
+function buildReuseHint(r) {
+    if (r.score >= 0.8)
+        return `直接复用${r.argCount > 0 ? `，注意 ${r.argCount} 个 args 参数` : ""}`;
+    if (r.score >= 0.5)
+        return `结构相似，建议 copy + 泛化后使用`;
+    return `低相关度，建议从头编写或大幅改写`;
+}
+// ---------------------------------------------------------------------------
+// searchLibrary
+// ---------------------------------------------------------------------------
+function argCountOf(def) {
+    return def.args && typeof def.args === "object" ? Object.keys(def.args).length : 0;
+}
+/** Search the library. Returns ranked top-N. Degrades to structural/keyword
+ *  when no embedder is configured or structureOnly is requested. */
+export async function searchLibrary(deps, input) {
+    const limit = Math.min(20, Math.max(1, input.limit ?? 5));
+    const minScore = input.minScore ?? 0;
+    const scope = input.scope ?? deps.settings.scope ?? "both";
+    // gather candidates
+    const flows = listFlows(deps.cwd).filter((f) => {
+        if (scope === "both")
+            return true;
+        return f.scope === scope;
+    });
+    const queryTokens = tokenize(input.query);
+    // embed the query if an embedder is available and not structureOnly
+    let queryVec = null;
+    const hasEmbedder = !!deps.embedder && !input.structureOnly;
+    if (hasEmbedder && deps.embedder) {
+        try {
+            queryVec = await deps.embedder.embed(input.query);
+        }
+        catch {
+            queryVec = null; // degrade
+        }
+    }
+    const scored = [];
+    for (const f of flows) {
+        const sidecar = readMeta(deps.cwd, f.name);
+        const cand = resolveCandidate(f.def, f.scope, f.name, sidecar);
+        const qShape = {
+            phaseSignature: input.phaseSignatureHint ?? "",
+            phaseCount: input.phaseCountHint ?? 0,
+        };
+        const structScore = computeStructScore(qShape, cand);
+        const textScore = computeTextScore(queryTokens, {
+            name: cand.name,
+            purpose: cand.purpose,
+            tags: cand.tags,
+            phaseTaskText: phaseTaskText(cand.def),
+        });
+        let score;
+        let semScore;
+        const hasVectors = queryVec != null && cand.embedding != null && !cand.embeddingStale;
+        if (hasVectors && queryVec && cand.embedding) {
+            semScore = cosine(queryVec, cand.embedding);
+            score = 0.6 * semScore + 0.25 * structScore + 0.15 * textScore;
+        }
+        else {
+            score = 0.6 * textScore + 0.4 * structScore;
+        }
+        if (score < minScore)
+            continue;
+        if (score <= 0)
+            continue; // zero-relevance results are noise; don't surface them
+        scored.push({ cand, score: Math.round(score * 100) / 100, semScore, structScore, textScore });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    const top = scored.slice(0, limit);
+    const withVectors = top.filter((s) => s.cand.embedding != null && !s.cand.embeddingStale).length;
+    let searchMode;
+    if (input.structureOnly || !deps.embedder || withVectors === 0)
+        searchMode = "structural";
+    else if (withVectors === top.length)
+        searchMode = "semantic";
+    else
+        searchMode = "mixed";
+    const results = top.map((s) => ({
+        name: s.cand.name,
+        scope: s.cand.scope,
+        purpose: s.cand.purpose,
+        tags: s.cand.tags,
+        phaseSignature: s.cand.phaseSignature,
+        phaseCount: s.cand.phaseCount,
+        generality: s.cand.generality,
+        reuseCount: s.cand.reuseCount,
+        version: s.cand.version,
+        score: s.score,
+        why: buildWhy({ semScore: s.semScore, structScore: s.structScore, textScore: s.textScore, searchMode }),
+        reuseHint: buildReuseHint({ score: s.score, argCount: argCountOf(s.cand.def) }),
+    }));
+    return {
+        results,
+        searchMode,
+        embedder: deps.embedder?.model,
+        counts: { scanned: flows.length, withVectors },
+    };
+}
+/** Pure cosine similarity. Zero-dep. Accepts non-normalized vectors. */
+export function cosine(a, b) {
+    const n = Math.min(a.length, b.length);
+    if (n === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < n; i++) {
+        const x = a[i];
+        const y = b[i];
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            continue;
+        dot += x * y;
+        normA += x * x;
+        normB += y * y;
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+/** Bump reuseCount for a flow by name (RFC §6 reuse flywheel).
+ *  Phase 1: structural-only; the caller (tool handler) decides whether to
+ *  bump based on a `reusedFromSearch` flag. Returns the new count or null if
+ *  the flow has no sidecar yet. The actual sidecar write is done by
+ *  `bumpReuseInSidecar` in store.ts under withLock. */
+export { getFlow };
+//# sourceMappingURL=search.js.map

package/dist/library/search.js.map

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

package/dist/library/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Library — reusable-flow asset layer types.
+ *
+ * The library lets taskflow accumulate, retrieve, and iteratively generalize
+ * saved flows. Phase 1 (this module) defines the data shapes and the
+ * host-neutral interfaces; the runtime logic (meta derivation, search ranking)
+ * lives in `meta.ts` / `search.ts`, and persistence (sidecar `.meta.json`)
+ * lives in `store.ts`.
+ *
+ * Design refs: docs/rfc-library-reuse.md (§3 data format, §4 embedder, §5
+ * search). Embedding support is Phase 2 — Phase 1 ships with structural /
+ * keyword search only and every embedding field is optional.
+ */
+import type { Taskflow } from "../schema.ts";
+/** Library-side settings, nested under `settings.json → taskflow.library`. */
+export interface LibrarySettings {
+    /** Master switch. Default true. When false, search/save-meta are no-ops. */
+    enabled: boolean;
+    /** Which scopes to search: "project" | "user" | "both" (default both). */
+    scope: "project" | "user" | "both";
+    /** Optional blend weights for mixed search ranking (Phase 2). */
+    searchWeights?: {
+        semantic: number;
+        structural: number;
+        textual: number;
+    };
+    /** Optional Phase-3 auto-prune threshold. */
+    maxFlows?: number;
+}
+export declare const DEFAULT_LIBRARY_SETTINGS: LibrarySettings;
+/** The sidecar `.meta.json` record. Persisted next to a flow file. */
+export interface FlowMeta {
+    schemaVersion: 1;
+    /** Agent-provided (optional). */
+    purpose?: string;
+    tags?: string[];
+    notes?: string;
+    /** Auto-derived at save time. */
+    phaseSignature: string;
+    phaseCount: number;
+    agentUsage: string[];
+    generality: number;
+    argShape?: Record<string, string>;
+    /** Reuse flywheel. */
+    reuseCount: number;
+    lastUsedAt: number | null;
+    createdAt: number;
+    version: number;
+    derivedFrom?: string;
+    /** Embedding (Phase 2; always optional / may be null). */
+    embeddingModel?: string;
+    embeddingDim?: number;
+    embedding?: number[] | null;
+    embeddedAt?: number | null;
+}
+/** A candidate resolved for search: live-derived structural fields + trusted
+ *  sidecar fields (purpose/tags/...) + embedding gated on signature match.
+ *  (RFC §5.2.2 staleness detection.) */
+export interface ResolvedCandidate {
+    name: string;
+    scope: "user" | "project";
+    def: Taskflow;
+    phaseSignature: string;
+    phaseCount: number;
+    agentUsage: string[];
+    generality: number;
+    purpose?: string;
+    tags?: string[];
+    notes?: string;
+    reuseCount: number;
+    version: number;
+    derivedFrom?: string;
+    embedding: number[] | null;
+    embeddingStale: boolean;
+}
+export interface SearchResult {
+    name: string;
+    scope: "user" | "project";
+    purpose?: string;
+    tags?: string[];
+    phaseSignature: string;
+    phaseCount: number;
+    generality: number;
+    reuseCount: number;
+    version: number;
+    score: number;
+    why: string;
+    reuseHint: string;
+}
+export interface SearchResponse {
+    results: SearchResult[];
+    searchMode: "semantic" | "structural" | "mixed";
+    embedder?: string;
+    counts: {
+        scanned: number;
+        withVectors: number;
+    };
+}
+/** Input to searchLibrary(). */
+export interface SearchInput {
+    query: string;
+    limit?: number;
+    structureOnly?: boolean;
+    minScore?: number;
+    scope?: "project" | "user" | "both";
+    phaseSignatureHint?: string;
+    phaseCountHint?: number;
+}
+/** The minimal host-neutral dependency the library functions need.
+ *  Embedder is Phase 2; Phase 1 leaves it undefined and search degrades to
+ *  structural/keyword (RFC §4.3, A2: stays OUT of RuntimeDeps). */
+export interface LibraryDeps {
+    embedder?: {
+        embed(text: string): Promise<number[]>;
+        readonly model: string;
+        readonly dim: number;
+    };
+    settings: LibrarySettings;
+    cwd: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/library/types.js

@@ -0,0 +1,18 @@
+/**
+ * Library — reusable-flow asset layer types.
+ *
+ * The library lets taskflow accumulate, retrieve, and iteratively generalize
+ * saved flows. Phase 1 (this module) defines the data shapes and the
+ * host-neutral interfaces; the runtime logic (meta derivation, search ranking)
+ * lives in `meta.ts` / `search.ts`, and persistence (sidecar `.meta.json`)
+ * lives in `store.ts`.
+ *
+ * Design refs: docs/rfc-library-reuse.md (§3 data format, §4 embedder, §5
+ * search). Embedding support is Phase 2 — Phase 1 ships with structural /
+ * keyword search only and every embedding field is optional.
+ */
+export const DEFAULT_LIBRARY_SETTINGS = {
+    enabled: true,
+    scope: "both",
+};
+//# sourceMappingURL=types.js.map

package/dist/library/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/library/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgBH,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACxD,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,MAAM;CACb,CAAC"}

package/dist/reflexion.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Reflexion memory for loop phases — pure helpers.
+ *
+ * When a loop phase sets `reflexion: true`, each iteration i > 1 receives a
+ * `{reflexion}` placeholder carrying a structured failure summary of the
+ * immediately-prior iteration: what happened (contract violation / subagent
+ * error / until-not-met), the precise diagnostics, and a truncated output
+ * snippet. The model iterates WITH the failure signal instead of re-guessing
+ * from a bare output (Reflexion, Shinn et al. 2023 — as a declarative field).
+ *
+ * Pure and total: assembly never throws on any input (the runtime additionally
+ * wraps the call fail-open — a reflexion bug must never sink the phase).
+ */
+/** Cap on the assembled reflexion block (chars). Keeps the injected context
+ *  from crowding out the actual task in the iteration prompt. */
+export declare const REFLEXION_MAX_CHARS = 2000;
+/** What iteration 1 sees: there is no prior iteration to reflect on. */
+export declare const REFLEXION_SENTINEL = "_(first iteration \u2014 no prior feedback yet)_";
+/** How the prior iteration ended, for the summary headline. */
+export type ReflexionOutcome = "until-not-met" | "contract-violation" | "subagent-error";
+export interface ReflexionInput {
+    /** 1-based index of the PRIOR iteration being summarized. */
+    iteration: number;
+    outcome: ReflexionOutcome;
+    /** The prior iteration's raw output (or error-bearing output on failure). */
+    output?: string;
+    /** errorMessage of a failed prior iteration (contract diagnostics live here). */
+    errorMessage?: string;
+    /** The loop's `until` expression (shown when outcome is until-not-met). */
+    until?: string;
+}
+/**
+ * Build the reflexion summary block injected into the next iteration's prompt.
+ * Sections are conditional — no empty headings. Total: never throws.
+ */
+export declare function buildReflexionSummary(input: ReflexionInput, maxChars?: number): string;
+/**
+ * Pull the per-path diagnostics out of a runOne contract-violation
+ * errorMessage ("Output contract violated:\n- $.score: …\n- …").
+ * Returns [] for any other error shape.
+ */
+export declare function extractContractDiagnostics(errorMessage?: string): string[];
+/** True when the errorMessage carries a contract violation (classification
+ *  for ReflexionInput.outcome). */
+export declare function isContractViolation(errorMessage?: string): boolean;
+//# sourceMappingURL=reflexion.d.ts.map

package/dist/reflexion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflexion.d.ts","sourceRoot":"","sources":["../src/reflexion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;iEACiE;AACjE,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,qDAAgD,CAAC;AAEhF,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,GACzB,eAAe,GACf,oBAAoB,GACpB,gBAAgB,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC9B,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,GAAE,MAA4B,GAAG,MAAM,CAkC3G;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAO1E;AAED;mCACmC;AACnC,wBAAgB,mBAAmB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAElE"}

package/dist/reflexion.js

@@ -0,0 +1,100 @@
+/**
+ * Reflexion memory for loop phases — pure helpers.
+ *
+ * When a loop phase sets `reflexion: true`, each iteration i > 1 receives a
+ * `{reflexion}` placeholder carrying a structured failure summary of the
+ * immediately-prior iteration: what happened (contract violation / subagent
+ * error / until-not-met), the precise diagnostics, and a truncated output
+ * snippet. The model iterates WITH the failure signal instead of re-guessing
+ * from a bare output (Reflexion, Shinn et al. 2023 — as a declarative field).
+ *
+ * Pure and total: assembly never throws on any input (the runtime additionally
+ * wraps the call fail-open — a reflexion bug must never sink the phase).
+ */
+/** Cap on the assembled reflexion block (chars). Keeps the injected context
+ *  from crowding out the actual task in the iteration prompt. */
+export const REFLEXION_MAX_CHARS = 2000;
+/** What iteration 1 sees: there is no prior iteration to reflect on. */
+export const REFLEXION_SENTINEL = "_(first iteration — no prior feedback yet)_";
+/**
+ * Build the reflexion summary block injected into the next iteration's prompt.
+ * Sections are conditional — no empty headings. Total: never throws.
+ */
+export function buildReflexionSummary(input, maxChars = REFLEXION_MAX_CHARS) {
+    const lines = [`## Reflexion: iteration ${input.iteration} (prior)`];
+    switch (input.outcome) {
+        case "contract-violation":
+            lines.push("- Outcome: FAILED — output contract violated");
+            break;
+        case "subagent-error":
+            lines.push("- Outcome: FAILED — subagent error");
+            break;
+        case "until-not-met":
+            lines.push("- Outcome: succeeded, but the stop condition was not met");
+            if (input.until)
+                lines.push(`- Stop condition still false: \`${oneLine(input.until, 200)}\``);
+            break;
+    }
+    const diags = extractContractDiagnostics(input.errorMessage);
+    if (diags.length > 0) {
+        lines.push("- Contract diagnostics:");
+        for (const d of diags)
+            lines.push(`  - ${oneLine(d, 200)}`);
+    }
+    else if (input.outcome !== "until-not-met" && input.errorMessage) {
+        lines.push(`- Error: ${oneLine(input.errorMessage, 400)}`);
+    }
+    lines.push("- Fix the issues above in this iteration.");
+    const head = lines.join("\n");
+    const output = (input.output ?? "").trim();
+    if (!output)
+        return truncateBlock(head, maxChars);
+    // Fit the output snippet into whatever budget the headline left over.
+    const frame = "\n- Prior output (truncated):\n```\n";
+    const close = "\n```";
+    const budget = maxChars - head.length - frame.length - close.length;
+    if (budget < 40)
+        return truncateBlock(head, maxChars); // no room for a useful snippet
+    const snippet = truncateMiddle(output, budget);
+    return `${head}${frame}${snippet}${close}`;
+}
+/**
+ * Pull the per-path diagnostics out of a runOne contract-violation
+ * errorMessage ("Output contract violated:\n- $.score: …\n- …").
+ * Returns [] for any other error shape.
+ */
+export function extractContractDiagnostics(errorMessage) {
+    if (!errorMessage || !errorMessage.startsWith("Output contract violated"))
+        return [];
+    return errorMessage
+        .split("\n")
+        .slice(1)
+        .map((l) => l.replace(/^-\s*/, "").trim())
+        .filter((l) => l.length > 0);
+}
+/** True when the errorMessage carries a contract violation (classification
+ *  for ReflexionInput.outcome). */
+export function isContractViolation(errorMessage) {
+    return typeof errorMessage === "string" && errorMessage.startsWith("Output contract violated");
+}
+/** Keep first ~60% and last ~30% of an over-budget string (errors often sit
+ *  at the end; intent at the start). */
+function truncateMiddle(s, budget) {
+    if (s.length <= budget)
+        return s;
+    const marker = `\n…[truncated ${s.length - budget} chars]…\n`;
+    const usable = budget - marker.length;
+    if (usable < 20)
+        return s.slice(0, Math.max(0, budget));
+    const headLen = Math.floor(usable * 0.65);
+    const tailLen = usable - headLen;
+    return s.slice(0, headLen) + marker + s.slice(s.length - tailLen);
+}
+function truncateBlock(s, maxChars) {
+    return s.length <= maxChars ? s : `${s.slice(0, maxChars - 1)}…`;
+}
+function oneLine(s, max) {
+    const flat = s.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+//# sourceMappingURL=reflexion.js.map

package/dist/reflexion.js.map

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