taskflow-core 0.1.5 → 0.1.6

package/dist/jsonc.js

@@ -0,0 +1,108 @@
+/**
+ * Zero-dependency JSONC (JSON with Comments) strip + parse.
+ *
+ * Flow definition files are hand-authored, and authors want to annotate them
+ * with `//` line comments and `/* block *​/` comments just like jsonc/JSON5.
+ * Standard `JSON.parse` rejects comments outright. This module strips comments
+ * (only those OUTSIDE string literals) and trailing commas before parsing, so
+ * a flow `.json` file may legally contain comments.
+ *
+ * Scope: this is used ONLY for user-authored flow definition files
+ * (readFlowFile). It must NOT be used to parse LLM/subagent output — that path
+ * (safeParse) stays strict by design, since model output is untrusted and we
+ * want structural failures to surface.
+ *
+ * The algorithm is a single linear scan that tracks whether the cursor is
+ * inside a string literal (respecting `\"` escapes). Comments are replaced
+ * with spaces so that line/column numbers in any error message stay aligned
+ * with the original source. Trailing commas before a closing brace/bracket
+ * (like `{"a": 1,}` or `[1, 2,]`) are also removed — a common hand-editing
+ * convenience that JSON.parse rejects.
+ */
+/** Strip JSONC comments (// line and block) and trailing commas. Exported for testing. */
+export function stripJsonComments(input) {
+    let out = "";
+    let i = 0;
+    const n = input.length;
+    while (i < n) {
+        const ch = input[i];
+        const next = input[i + 1];
+        // String literal — copy verbatim, honoring escape sequences. A `//` or
+        // `/*` that appears inside a string is part of the value, not a comment,
+        // and a `,` inside a string is not a trailing comma.
+        if (ch === '"') {
+            out += ch;
+            i++;
+            while (i < n) {
+                const c = input[i];
+                if (c === "\\" && i + 1 < n) {
+                    // Keep the escape char and the escaped char together.
+                    out += c + input[i + 1];
+                    i += 2;
+                    continue;
+                }
+                out += c;
+                i++;
+                if (c === '"')
+                    break;
+            }
+            continue;
+        }
+        // Line comment `// ... \n` — drop it (do not emit a space, so line
+        // numbers stay aligned with the original source).
+        if (ch === "/" && next === "/") {
+            while (i < n && input[i] !== "\n")
+                i++;
+            continue;
+        }
+        // Block comment `/* ... */` — replace with a single space so that
+        // positions of the surrounding tokens are preserved.
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < n && !(input[i] === "*" && input[i + 1] === "/"))
+                i++;
+            i += 2; // consume the closing */
+            out += " ";
+            continue;
+        }
+        // Trailing comma: skip the comma when the next non-whitespace char is
+        // a closing brace or bracket. Only checked outside string literals.
+        // Newlines between the comma and the closer are preserved so that
+        // line numbers stay aligned with the original source.
+        if (ch === ",") {
+            let j = i + 1;
+            let sawNewline = false;
+            while (j < n) {
+                const c = input[j];
+                if (c === " " || c === "\t" || c === "\r") {
+                    j++;
+                }
+                else if (c === "\n") {
+                    sawNewline = true;
+                    j++;
+                }
+                else {
+                    break;
+                }
+            }
+            if (j < n && (input[j] === "}" || input[j] === "]")) {
+                if (sawNewline)
+                    out += "\n";
+                i = j;
+                continue;
+            }
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+/**
+ * Parse a JSONC string (JSON with comments and trailing commas allowed) into a
+ * value of type T. Throws the same SyntaxError `JSON.parse` would throw for any
+ * other structural problem, so callers can wrap it in try/catch as usual.
+ */
+export function parseJsonc(input) {
+    return JSON.parse(stripJsonComments(input));
+}
+//# sourceMappingURL=jsonc.js.map

package/dist/jsonc.js.map

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

package/dist/library/meta.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Library — auto-derived structural metadata.
+ *
+ * Computed at save time (zero tokens, deterministic) and re-derived live at
+ * search time (RFC §5.2.2 staleness). No embedding logic here — that's Phase 2.
+ *
+ * Refs: docs/rfc-library-reuse.md §3.2 (phaseSignature), §3.3 (generality).
+ */
+import type { Taskflow } from "../schema.ts";
+import type { FlowMeta } from "./types.ts";
+/** Topological phase-type signature, e.g. "agent→map→gate→reduce".
+ *  Parallel same-layer phases joined with "+". Uses topoLayers() for
+ *  deterministic ordering. */
+export declare function computePhaseSignature(def: Taskflow): string;
+export declare function countPhases(def: Taskflow): number;
+/** Distinct agent names referenced across phases (sorted, stable). */
+export declare function extractAgentUsage(def: Taskflow): string[];
+/** generality ∈ [0,1]. RFC §3.3 (v2 formula, A8 fix):
+ *  uses literalTokenRatio = literalChars/(literalChars+placeholderChars)
+ *  so verbose-but-parameterized flows aren't structurally penalized. */
+export declare function computeGenerality(def: Taskflow): number;
+/** Build a fresh FlowMeta from a def + optional agent-provided fields.
+ *  Used at save time. reuseCount starts at 0; version starts at 1. */
+export declare function deriveMeta(def: Taskflow, opts: {
+    purpose?: string;
+    tags?: string[];
+    notes?: string;
+    derivedFrom?: string;
+    prevMeta?: FlowMeta;
+}): FlowMeta;
+//# sourceMappingURL=meta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/library/meta.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;8BAE8B;AAC9B,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAM3D;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEjD;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,EAAE,CAazD;AAkFD;;wEAEwE;AACxE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAYvD;AAED;sEACsE;AACtE,wBAAgB,UAAU,CACzB,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,GACpG,QAAQ,CAsBV"}

package/dist/library/meta.js

@@ -0,0 +1,154 @@
+/**
+ * Library — auto-derived structural metadata.
+ *
+ * Computed at save time (zero tokens, deterministic) and re-derived live at
+ * search time (RFC §5.2.2 staleness). No embedding logic here — that's Phase 2.
+ *
+ * Refs: docs/rfc-library-reuse.md §3.2 (phaseSignature), §3.3 (generality).
+ */
+import { topoLayers } from "../schema.js";
+/** Topological phase-type signature, e.g. "agent→map→gate→reduce".
+ *  Parallel same-layer phases joined with "+". Uses topoLayers() for
+ *  deterministic ordering. */
+export function computePhaseSignature(def) {
+    if (!Array.isArray(def.phases) || def.phases.length === 0)
+        return "";
+    const layers = topoLayers(def.phases);
+    return layers
+        .map((layer) => layer.map((p) => p.type ?? "agent").join("+"))
+        .join("→");
+}
+export function countPhases(def) {
+    return Array.isArray(def.phases) ? def.phases.length : 0;
+}
+/** Distinct agent names referenced across phases (sorted, stable). */
+export function extractAgentUsage(def) {
+    if (!Array.isArray(def.phases))
+        return [];
+    const set = new Set();
+    for (const p of def.phases) {
+        if (typeof p.agent === "string" && p.agent.trim())
+            set.add(p.agent.trim());
+        // parallel branches
+        if (Array.isArray(p.branches)) {
+            for (const b of p.branches ?? []) {
+                if (b && typeof b.agent === "string" && b.agent.trim())
+                    set.add(b.agent.trim());
+            }
+        }
+    }
+    return Array.from(set).sort();
+}
+const PLACEHOLDER_RE = /\{(args|steps|item|previous|loop|reflexion)(\.[^}]{1,200})?\}/g;
+function accountContent(def) {
+    const acc = {
+        literalChars: 0,
+        placeholderChars: 0,
+        placeholderRefs: 0,
+        argCount: 0,
+        hasDescription: typeof def.description === "string" && def.description.trim().length > 0,
+        productionKnobs: 0,
+    };
+    // args
+    if (def.args && typeof def.args === "object") {
+        acc.argCount = Object.keys(def.args).length;
+    }
+    // production knobs (cap 0.15, each +0.05)
+    if (def.budget)
+        acc.productionKnobs += 0.05;
+    if (def.concurrency && typeof def.concurrency === "number")
+        acc.productionKnobs += 0.05;
+    let sawRetry = false;
+    let sawExpect = false;
+    if (Array.isArray(def.phases)) {
+        for (const p of def.phases) {
+            if (p.retry)
+                sawRetry = true;
+            if (p.expect)
+                sawExpect = true;
+        }
+    }
+    if (sawRetry)
+        acc.productionKnobs += 0.05;
+    if (sawExpect)
+        acc.productionKnobs += 0.05;
+    acc.productionKnobs = Math.min(0.15, acc.productionKnobs);
+    // scan phase string fields for literals vs placeholders
+    const scan = (s) => {
+        if (typeof s !== "string")
+            return;
+        PLACEHOLDER_RE.lastIndex = 0;
+        let m;
+        let lastEnd = 0;
+        let placeholderCharsThis = 0;
+        let placeholderRefsThis = 0;
+        while ((m = PLACEHOLDER_RE.exec(s)) !== null) {
+            // literal chunk before this placeholder
+            acc.literalChars += m.index - lastEnd;
+            placeholderCharsThis += m[0].length;
+            placeholderRefsThis += 1;
+            lastEnd = m.index + m[0].length;
+        }
+        acc.literalChars += s.length - lastEnd;
+        acc.placeholderChars += placeholderCharsThis;
+        acc.placeholderRefs += placeholderRefsThis;
+    };
+    if (Array.isArray(def.phases)) {
+        for (const p of def.phases) {
+            scan(p.task);
+            scan(p.over);
+            scan(p.run);
+            scan(p.input);
+            // parallel branch tasks
+            if (Array.isArray(p.branches)) {
+                for (const b of p.branches ?? []) {
+                    scan(b?.task);
+                }
+            }
+        }
+    }
+    return acc;
+}
+/** generality ∈ [0,1]. RFC §3.3 (v2 formula, A8 fix):
+ *  uses literalTokenRatio = literalChars/(literalChars+placeholderChars)
+ *  so verbose-but-parameterized flows aren't structurally penalized. */
+export function computeGenerality(def) {
+    const a = accountContent(def);
+    const totalChars = a.literalChars + a.placeholderChars;
+    const literalTokenRatio = totalChars > 0 ? a.literalChars / totalChars : 1;
+    let g = 0.4 * (1 - literalTokenRatio) +
+        0.3 * Math.min(1, a.argCount / 3) +
+        0.3 * (a.hasDescription ? 0.3 : 0) +
+        a.productionKnobs;
+    if (g < 0)
+        g = 0;
+    if (g > 1)
+        g = 1;
+    return Math.round(g * 100) / 100;
+}
+/** Build a fresh FlowMeta from a def + optional agent-provided fields.
+ *  Used at save time. reuseCount starts at 0; version starts at 1. */
+export function deriveMeta(def, opts) {
+    const now = Date.now();
+    const prev = opts.prevMeta;
+    return {
+        schemaVersion: 1,
+        purpose: opts.purpose,
+        tags: opts.tags,
+        notes: opts.notes,
+        phaseSignature: computePhaseSignature(def),
+        phaseCount: countPhases(def),
+        agentUsage: extractAgentUsage(def),
+        generality: computeGenerality(def),
+        reuseCount: prev?.reuseCount ?? 0,
+        lastUsedAt: prev?.lastUsedAt ?? null,
+        createdAt: prev?.createdAt ?? now,
+        version: prev ? prev.version + 1 : 1,
+        derivedFrom: opts.derivedFrom,
+        embedding: prev?.embedding ?? null,
+        embeddingModel: prev?.embeddingModel,
+        embeddingDim: prev?.embeddingDim,
+        embeddedAt: prev?.embeddedAt ?? null,
+    };
+}
+//# sourceMappingURL=meta.js.map

package/dist/library/meta.js.map

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

package/dist/library/search.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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, readMeta } from "../store.ts";
+import type { Taskflow } from "../schema.ts";
+import type { LibraryDeps, ResolvedCandidate, SearchInput, SearchResponse } from "./types.ts";
+/** Standard Levenshtein edit distance (insert/delete/replace cost 1).
+ *  O(m·n) DP; signature strings are short (<50 chars) so cost is negligible. */
+export declare function levenshtein(a: string, b: string): number;
+/** 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 declare function resolveCandidate(def: Taskflow, scope: "user" | "project", name: string, sidecar: ReturnType<typeof readMeta>): ResolvedCandidate;
+/** Search the library. Returns ranked top-N. Degrades to structural/keyword
+ *  when no embedder is configured or structureOnly is requested. */
+export declare function searchLibrary(deps: LibraryDeps, input: SearchInput): Promise<SearchResponse>;
+/** Pure cosine similarity. Zero-dep. Accepts non-normalized vectors. */
+export declare function cosine(a: number[], b: number[]): number;
+/** 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.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/library/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAa,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAO7C,OAAO,KAAK,EACX,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,cAAc,EAEd,MAAM,YAAY,CAAC;AAMpB;gFACgF;AAChF,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAmBxD;AAMD;;uEAEuE;AACvE,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,GAClC,iBAAiB,CAwCnB;AAiHD;oEACoE;AACpE,wBAAsB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAoFlG;AAED,wEAAwE;AACxE,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAgBvD;AAED;;;;uDAIuD;AACvD,OAAO,EAAE,OAAO,EAAE,CAAC"}

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