scai 0.1.178 → 1.0.0

package/dist/agent/prompting/understand.js

@@ -0,0 +1,70 @@
+export function renderUnderstandPrompt(query, resumedContext) {
+    return [
+        "Return strict JSON only.",
+        "",
+        "Task:",
+        "- Normalize the user request.",
+        "- Classify the coarse request scope as targeted, multi-file, broad-repo, or general.",
+        "- Extract raw obvious file, folder, or target mentions without overthinking intent.",
+        "- Give one primary intent and up to three alternative intents.",
+        "- Return two to four small typed search term groups with three to six short terms each.",
+        "- Each search term group must have a kind: repo-anchor, command-path, or generic.",
+        "- Search term groups should help code search in this repo, not just describe the topic in English.",
+        "- Prefer repo-anchor groups first. Use likely repo-local identifiers, camelCase names, filenames, and symbol-like clues.",
+        "- Use command-path groups for slash commands, config files, path-like clues, and CLI entry names.",
+        "- Use generic groups only as fallback after concrete groups.",
+        "- For code-location, config, owner, or entrypoint questions, include at least one repo-anchor group.",
+        "- Prefer code-like anchors such as camelCase names, file names like package.json, and commands like /test-run when plausible.",
+        "- Only use broad fallback words like test, config, script, runner, command, or entry when they are paired with at least one concrete anchor.",
+        "- Do not guess unrelated frameworks or tools like jest, mocha, cypress, or yarn unless the user query suggests them.",
+        "- Search term groups should use terms only, not prose.",
+        "- Add ambiguity flags only when they matter.",
+        "- Treat queryScope as a coarse shape only. Do not use it to decide whether the agent should stop or ask the user.",
+        "- Classify as general when the user asks for general tool or programming knowledge that can be answered without inspecting this repository.",
+        "- Command names like git diff, bash, npm test, and docker build are not repo anchors by themselves.",
+        "- Do not classify as general when the query names this repo, this project, a file path, a symbol, a module, or quoted code that should be checked in this repo.",
+        "- If resumed context is present, use it only to resolve follow-up references like 'also', 'that file', 'did you check X', or 'what did you already inspect'.",
+        "- Preserve explicit file mentions from the new user query over older resumed-context clues.",
+        "- Do not rewrite the new user query into unrelated terms that are not present in the query or resumed context.",
+        "- Do not treat resumed context as fresh grounding for the current turn.",
+        "",
+        "Good example for a test-entry query:",
+        '[{"kind":"repo-anchor","terms":["registerDevCliCommands","testCommands","registerTestingCommands"]},{"kind":"command-path","terms":["/tests","/test-run","run-query"]},{"kind":"generic","terms":["vitest","package.json","entrypoint","register"]}]',
+        "",
+        "Bad example for the same query:",
+        '[{"kind":"generic","terms":["test","run","execute","script","entry","point"]},{"kind":"generic","terms":["package.json","npm","yarn","test","script","command"]},{"kind":"generic","terms":["jest","mocha","cypress","test","runner","config"]}]',
+        "",
+        "Good example for a loop-limit query:",
+        '[{"kind":"repo-anchor","terms":["maxTurns","turnCount"]},{"kind":"command-path","terms":["memory.ts","config","limit"]},{"kind":"generic","terms":["loop","limit","count"]}]',
+        "",
+        "General knowledge examples:",
+        '- "how do I use git bash to save a diff?" -> queryScope: "general"',
+        '- "what is recursion?" -> queryScope: "general"',
+        '- "how do I squash commits?" -> queryScope: "general"',
+        "",
+        "Repo-grounded examples:",
+        '- "how does this repo run tests?" -> queryScope: "broad-repo"',
+        `- "explain cli/src/agent/index.ts" -> queryScope: "targeted"`,
+        "",
+        "JSON shape:",
+        "{",
+        '  "normalizedQuery": "string",',
+        '  "queryScope": "targeted | multi-file | broad-repo | general",',
+        '  "explicitTargets": ["string"],',
+        '  "constraints": ["string"],',
+        '  "primaryIntent": "string",',
+        '  "alternativeIntents": ["string"],',
+        '  "searchTermGroups": [{"kind":"repo-anchor | command-path | generic","terms":["term1", "term2"]}],',
+        '  "ambiguityFlags": ["string"]',
+        "}",
+        "",
+        ...(resumedContext ? [
+            "Resumed context:",
+            JSON.stringify(resumedContext, null, 2),
+            "",
+        ] : []),
+        "User query:",
+        query,
+    ].join("\n");
+}
+//# sourceMappingURL=understand.js.map

package/dist/agent/prompting/understand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"understand.js","sourceRoot":"","sources":["../../../src/agent/prompting/understand.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,sBAAsB,CACpC,KAAa,EACb,cAA4C;IAE5C,OAAO;QACL,0BAA0B;QAC1B,EAAE;QACF,OAAO;QACP,+BAA+B;QAC/B,sFAAsF;QACtF,qFAAqF;QACrF,gEAAgE;QAChE,yFAAyF;QACzF,mFAAmF;QACnF,oGAAoG;QACpG,0HAA0H;QAC1H,mGAAmG;QACnG,8DAA8D;QAC9D,sGAAsG;QACtG,+HAA+H;QAC/H,8IAA8I;QAC9I,sHAAsH;QACtH,wDAAwD;QACxD,8CAA8C;QAC9C,mHAAmH;QACnH,6IAA6I;QAC7I,qGAAqG;QACrG,iKAAiK;QACjK,8JAA8J;QAC9J,6FAA6F;QAC7F,gHAAgH;QAChH,yEAAyE;QACzE,EAAE;QACF,sCAAsC;QACtC,sPAAsP;QACtP,EAAE;QACF,iCAAiC;QACjC,kPAAkP;QAClP,EAAE;QACF,sCAAsC;QACtC,8KAA8K;QAC9K,EAAE;QACF,6BAA6B;QAC7B,oEAAoE;QACpE,iDAAiD;QACjD,uDAAuD;QACvD,EAAE;QACF,yBAAyB;QACzB,+DAA+D;QAC/D,8DAA8D;QAC9D,EAAE;QACF,aAAa;QACb,GAAG;QACH,gCAAgC;QAChC,iEAAiE;QACjE,kCAAkC;QAClC,8BAA8B;QAC9B,8BAA8B;QAC9B,qCAAqC;QACrC,qGAAqG;QACrG,gCAAgC;QAChC,GAAG;QACH,EAAE;QACF,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;YACnB,kBAAkB;YAClB,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,EAAE;SACH,CAAC,CAAC,CAAC,EAAE,CAAC;QACP,aAAa;QACb,KAAK;KACN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC","sourcesContent":["/**\n * Owns understand prompt text for the new agent.\n *\n * Why this file exists:\n * - understand prompt ownership should stay out of runtime wiring\n * - the prompt should live under a direct new-agent owner\n * - direct imports avoid compatibility prompt files\n */\nimport type { ResumeCheckpointPromptShape } from \"../resume/checkpoint.js\";\n\nexport function renderUnderstandPrompt(\n  query: string,\n  resumedContext?: ResumeCheckpointPromptShape\n): string {\n  return [\n    \"Return strict JSON only.\",\n    \"\",\n    \"Task:\",\n    \"- Normalize the user request.\",\n    \"- Classify the coarse request scope as targeted, multi-file, broad-repo, or general.\",\n    \"- Extract raw obvious file, folder, or target mentions without overthinking intent.\",\n    \"- Give one primary intent and up to three alternative intents.\",\n    \"- Return two to four small typed search term groups with three to six short terms each.\",\n    \"- Each search term group must have a kind: repo-anchor, command-path, or generic.\",\n    \"- Search term groups should help code search in this repo, not just describe the topic in English.\",\n    \"- Prefer repo-anchor groups first. Use likely repo-local identifiers, camelCase names, filenames, and symbol-like clues.\",\n    \"- Use command-path groups for slash commands, config files, path-like clues, and CLI entry names.\",\n    \"- Use generic groups only as fallback after concrete groups.\",\n    \"- For code-location, config, owner, or entrypoint questions, include at least one repo-anchor group.\",\n    \"- Prefer code-like anchors such as camelCase names, file names like package.json, and commands like /test-run when plausible.\",\n    \"- Only use broad fallback words like test, config, script, runner, command, or entry when they are paired with at least one concrete anchor.\",\n    \"- Do not guess unrelated frameworks or tools like jest, mocha, cypress, or yarn unless the user query suggests them.\",\n    \"- Search term groups should use terms only, not prose.\",\n    \"- Add ambiguity flags only when they matter.\",\n    \"- Treat queryScope as a coarse shape only. Do not use it to decide whether the agent should stop or ask the user.\",\n    \"- Classify as general when the user asks for general tool or programming knowledge that can be answered without inspecting this repository.\",\n    \"- Command names like git diff, bash, npm test, and docker build are not repo anchors by themselves.\",\n    \"- Do not classify as general when the query names this repo, this project, a file path, a symbol, a module, or quoted code that should be checked in this repo.\",\n    \"- If resumed context is present, use it only to resolve follow-up references like 'also', 'that file', 'did you check X', or 'what did you already inspect'.\",\n    \"- Preserve explicit file mentions from the new user query over older resumed-context clues.\",\n    \"- Do not rewrite the new user query into unrelated terms that are not present in the query or resumed context.\",\n    \"- Do not treat resumed context as fresh grounding for the current turn.\",\n    \"\",\n    \"Good example for a test-entry query:\",\n    '[{\"kind\":\"repo-anchor\",\"terms\":[\"registerDevCliCommands\",\"testCommands\",\"registerTestingCommands\"]},{\"kind\":\"command-path\",\"terms\":[\"/tests\",\"/test-run\",\"run-query\"]},{\"kind\":\"generic\",\"terms\":[\"vitest\",\"package.json\",\"entrypoint\",\"register\"]}]',\n    \"\",\n    \"Bad example for the same query:\",\n    '[{\"kind\":\"generic\",\"terms\":[\"test\",\"run\",\"execute\",\"script\",\"entry\",\"point\"]},{\"kind\":\"generic\",\"terms\":[\"package.json\",\"npm\",\"yarn\",\"test\",\"script\",\"command\"]},{\"kind\":\"generic\",\"terms\":[\"jest\",\"mocha\",\"cypress\",\"test\",\"runner\",\"config\"]}]',\n    \"\",\n    \"Good example for a loop-limit query:\",\n    '[{\"kind\":\"repo-anchor\",\"terms\":[\"maxTurns\",\"turnCount\"]},{\"kind\":\"command-path\",\"terms\":[\"memory.ts\",\"config\",\"limit\"]},{\"kind\":\"generic\",\"terms\":[\"loop\",\"limit\",\"count\"]}]',\n    \"\",\n    \"General knowledge examples:\",\n    '- \"how do I use git bash to save a diff?\" -> queryScope: \"general\"',\n    '- \"what is recursion?\" -> queryScope: \"general\"',\n    '- \"how do I squash commits?\" -> queryScope: \"general\"',\n    \"\",\n    \"Repo-grounded examples:\",\n    '- \"how does this repo run tests?\" -> queryScope: \"broad-repo\"',\n    `- \"explain cli/src/agent/index.ts\" -> queryScope: \"targeted\"`,\n    \"\",\n    \"JSON shape:\",\n    \"{\",\n    '  \"normalizedQuery\": \"string\",',\n    '  \"queryScope\": \"targeted | multi-file | broad-repo | general\",',\n    '  \"explicitTargets\": [\"string\"],',\n    '  \"constraints\": [\"string\"],',\n    '  \"primaryIntent\": \"string\",',\n    '  \"alternativeIntents\": [\"string\"],',\n    '  \"searchTermGroups\": [{\"kind\":\"repo-anchor | command-path | generic\",\"terms\":[\"term1\", \"term2\"]}],',\n    '  \"ambiguityFlags\": [\"string\"]',\n    \"}\",\n    \"\",\n    ...(resumedContext ? [\n      \"Resumed context:\",\n      JSON.stringify(resumedContext, null, 2),\n      \"\",\n    ] : []),\n    \"User query:\",\n    query,\n  ].join(\"\\n\");\n}\n"]}

package/dist/agent/read/freshness.js

@@ -0,0 +1,29 @@
+/**
+ * Checks whether stored read evidence is still fresh for the current query.
+ *
+ * Why this file exists:
+ * - policy should consume freshness facts, not perform file I/O directly
+ * - read freshness rules should stay close to read evidence behavior
+ */
+import fs from "fs";
+import { computeContentFingerprint, hasFreshAgentReadEvidence } from "../../utils/fileEvidenceCache.js";
+export function hasFreshReadForPath(memory, filePath, options = {}) {
+    const evidence = memory.evidence.fileReads[filePath];
+    if (!evidence || !fs.existsSync(filePath)) {
+        return false;
+    }
+    const actualMode = evidence.readMode ?? "full";
+    if (options.mode && actualMode !== options.mode) {
+        return false;
+    }
+    const code = fs.readFileSync(filePath, "utf-8");
+    if (actualMode === "full") {
+        return evidence.contentFingerprint === computeContentFingerprint(code);
+    }
+    return hasFreshAgentReadEvidence({
+        evidence,
+        code,
+        query: memory.task.normalizedQuery,
+    });
+}
+//# sourceMappingURL=freshness.js.map

package/dist/agent/read/freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.js","sourceRoot":"","sources":["../../../src/agent/read/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,OAAO,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAMxG,MAAM,UAAU,mBAAmB,CAAC,MAAmB,EAAE,QAAgB,EAAE,UAA4B,EAAE;IACvG,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACrD,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,IAAI,MAAM,CAAC;IAC/C,IAAI,OAAO,CAAC,IAAI,IAAI,UAAU,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,OAAO,QAAQ,CAAC,kBAAkB,KAAK,yBAAyB,CAAC,IAAI,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,yBAAyB,CAAC;QAC/B,QAAQ;QACR,IAAI;QACJ,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,eAAe;KACnC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Checks whether stored read evidence is still fresh for the current query.\n *\n * Why this file exists:\n * - policy should consume freshness facts, not perform file I/O directly\n * - read freshness rules should stay close to read evidence behavior\n */\nimport fs from \"fs\";\nimport type { AgentMemory, AgentReadEvidence } from \"../types.js\";\nimport { computeContentFingerprint, hasFreshAgentReadEvidence } from \"../../utils/fileEvidenceCache.js\";\n\ninterface FreshReadOptions {\n  mode?: AgentReadEvidence[\"readMode\"];\n}\n\nexport function hasFreshReadForPath(memory: AgentMemory, filePath: string, options: FreshReadOptions = {}): boolean {\n  const evidence = memory.evidence.fileReads[filePath];\n  if (!evidence || !fs.existsSync(filePath)) {\n    return false;\n  }\n  const actualMode = evidence.readMode ?? \"full\";\n  if (options.mode && actualMode !== options.mode) {\n    return false;\n  }\n  const code = fs.readFileSync(filePath, \"utf-8\");\n  if (actualMode === \"full\") {\n    return evidence.contentFingerprint === computeContentFingerprint(code);\n  }\n  return hasFreshAgentReadEvidence({\n    evidence,\n    code,\n    query: memory.task.normalizedQuery,\n  });\n}\n"]}

package/dist/agent/read/fullReadPrompt.js

@@ -0,0 +1,43 @@
+/**
+ * Builds the full-read model prompt for one grounded file understanding pass.
+ *
+ * Why this file exists:
+ * - full-read prompt shaping should stay inside the read area
+ * - read execution should not also own prompt wording details
+ * - fallback and prompt output should target the same read evidence shape
+ */
+export function buildFullReadPrompt(query, filePath, code) {
+    return [
+        "Return strict JSON only.",
+        "",
+        "You are doing one grounded file read for the modular agent runtime.",
+        "The goal is to understand the file itself, not to plan edits.",
+        "",
+        "Task query:",
+        query,
+        "",
+        `File path: ${filePath}`,
+        "",
+        "Return JSON:",
+        "{",
+        '  "summary": "short plain summary",',
+        '  "relevanceExplanation": "why this file matters to the query",',
+        '  "role": "primary | supporting | contextual",',
+        '  "keySymbols": ["symbol"],',
+        '  "excerpts": [',
+        '    { "description": "why this code matters", "startLine": 1, "endLine": 5, "symbols": ["name"], "code": "actual code" }',
+        "  ],",
+        '  "risks": ["constraint or uncertainty"]',
+        "}",
+        "",
+        "Rules:",
+        "- Prefer complete functions, configuration blocks, or object literals as excerpts.",
+        "- Keep excerpts directly grounded in the file text.",
+        "- Do not propose changes.",
+        "- If evidence is weak, say so in risks.",
+        "",
+        "Code excerpt:",
+        code,
+    ].join("\n");
+}
+//# sourceMappingURL=fullReadPrompt.js.map

package/dist/agent/read/fullReadPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fullReadPrompt.js","sourceRoot":"","sources":["../../../src/agent/read/fullReadPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,QAAgB,EAAE,IAAY;IAC/E,OAAO;QACL,0BAA0B;QAC1B,EAAE;QACF,qEAAqE;QACrE,+DAA+D;QAC/D,EAAE;QACF,aAAa;QACb,KAAK;QACL,EAAE;QACF,cAAc,QAAQ,EAAE;QACxB,EAAE;QACF,cAAc;QACd,GAAG;QACH,qCAAqC;QACrC,iEAAiE;QACjE,gDAAgD;QAChD,6BAA6B;QAC7B,iBAAiB;QACjB,0HAA0H;QAC1H,MAAM;QACN,0CAA0C;QAC1C,GAAG;QACH,EAAE;QACF,QAAQ;QACR,oFAAoF;QACpF,qDAAqD;QACrD,2BAA2B;QAC3B,yCAAyC;QACzC,EAAE;QACF,eAAe;QACf,IAAI;KACL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC","sourcesContent":["/**\n * Builds the full-read model prompt for one grounded file understanding pass.\n *\n * Why this file exists:\n * - full-read prompt shaping should stay inside the read area\n * - read execution should not also own prompt wording details\n * - fallback and prompt output should target the same read evidence shape\n */\n\nexport function buildFullReadPrompt(query: string, filePath: string, code: string): string {\n  return [\n    \"Return strict JSON only.\",\n    \"\",\n    \"You are doing one grounded file read for the modular agent runtime.\",\n    \"The goal is to understand the file itself, not to plan edits.\",\n    \"\",\n    \"Task query:\",\n    query,\n    \"\",\n    `File path: ${filePath}`,\n    \"\",\n    \"Return JSON:\",\n    \"{\",\n    '  \"summary\": \"short plain summary\",',\n    '  \"relevanceExplanation\": \"why this file matters to the query\",',\n    '  \"role\": \"primary | supporting | contextual\",',\n    '  \"keySymbols\": [\"symbol\"],',\n    '  \"excerpts\": [',\n    '    { \"description\": \"why this code matters\", \"startLine\": 1, \"endLine\": 5, \"symbols\": [\"name\"], \"code\": \"actual code\" }',\n    \"  ],\",\n    '  \"risks\": [\"constraint or uncertainty\"]',\n    \"}\",\n    \"\",\n    \"Rules:\",\n    \"- Prefer complete functions, configuration blocks, or object literals as excerpts.\",\n    \"- Keep excerpts directly grounded in the file text.\",\n    \"- Do not propose changes.\",\n    \"- If evidence is weak, say so in risks.\",\n    \"\",\n    \"Code excerpt:\",\n    code,\n  ].join(\"\\n\");\n}\n"]}

package/dist/agent/read/index.js

@@ -0,0 +1,140 @@
+/**
+ * Owns the canonical read path for the modular agent runtime.
+ *
+ * Why this file exists:
+ * - the new agent should have one read entrypoint area
+ * - read execution should stay separate from policy decisions about when to triage or fully read
+ * - target resolution, freshness, prompts, and fallback shaping belong together
+ * - policy should call read-owned path checks instead of touching the file system directly
+ */
+import fs from "fs";
+import { generate } from "../../lib/generate.js";
+import { buildDeterministicFullReadFallback, selectCodeForFullReadPrompt, summarizeFileRead, } from "./summarizeReadEvidence.js";
+import { canReadExplicitTarget, resolveExplicitFileTarget, resolveReadTarget, UnresolvedAgentTargetError, } from "./targetResolution.js";
+import { hasFreshReadForPath } from "./freshness.js";
+import { buildFullReadPrompt } from "./fullReadPrompt.js";
+import { loadPersistedFullRead, savePersistedFullRead } from "./persistence.js";
+const MAX_FULL_READ_CODE_CHARS = 9000;
+export { canReadExplicitTarget, hasFreshReadForPath, resolveExplicitFileTarget, resolveReadTarget, summarizeFileRead, UnresolvedAgentTargetError, };
+function isHardTarget(memory, filePath) {
+    return memory.task.hardFileTargets.includes(filePath);
+}
+function parseStructuredReadResponse(raw) {
+    const trimmed = raw.trim();
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidate = fenced?.[1]?.trim() || trimmed;
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        return {};
+    }
+}
+function chooseFullReadRole(value, fallback) {
+    return value === "primary" || value === "supporting" || value === "contextual"
+        ? value
+        : fallback;
+}
+function normalizeStringList(values, limit) {
+    if (!Array.isArray(values)) {
+        return undefined;
+    }
+    return values.map((value) => String(value ?? "").trim()).filter(Boolean).slice(0, limit);
+}
+function normalizeExcerpts(excerpts, fallback) {
+    if (!Array.isArray(excerpts)) {
+        return fallback;
+    }
+    return excerpts
+        .filter((excerpt) => {
+        return typeof excerpt?.code === "string" && excerpt.code.trim().length > 0;
+    })
+        .slice(0, 3);
+}
+function mergeFullReadEvidence(base, parsed) {
+    return {
+        ...base,
+        readMode: "full",
+        summary: typeof parsed.summary === "string" && parsed.summary.trim().length > 0
+            ? parsed.summary.trim().slice(0, 240)
+            : base.summary,
+        relevanceExplanation: typeof parsed.relevanceExplanation === "string" && parsed.relevanceExplanation.trim().length > 0
+            ? parsed.relevanceExplanation.trim()
+            : base.relevanceExplanation,
+        role: chooseFullReadRole(parsed.role, base.role),
+        excerpts: normalizeExcerpts(parsed.excerpts, base.excerpts),
+        risks: normalizeStringList(parsed.risks, 4) ?? base.risks,
+        keySymbols: normalizeStringList(parsed.keySymbols, 8) ?? base.keySymbols,
+    };
+}
+function resolveReadPriority(searchScore, triageScore) {
+    if (typeof triageScore !== "number") {
+        return undefined;
+    }
+    if (typeof searchScore === "number") {
+        return Number((searchScore + triageScore).toFixed(2));
+    }
+    return triageScore;
+}
+function updateCandidateMetadata(memory, filePath, evidence) {
+    var _a;
+    (_a = memory.evidence).candidateMetadata ?? (_a.candidateMetadata = {});
+    const existing = memory.evidence.candidateMetadata[filePath] ?? {};
+    const readPriority = resolveReadPriority(existing.searchScore, evidence.triageScore);
+    memory.evidence.candidateMetadata[filePath] = {
+        ...existing,
+        ...(typeof evidence.triageScore === "number" ? { triageScore: evidence.triageScore } : {}),
+        ...(typeof readPriority === "number" ? { readPriority } : {}),
+        lastUpdatedAt: evidence.recordedAt,
+    };
+}
+function storeReadEvidence(memory, filePath, evidence) {
+    memory.evidence.fileReads[filePath] = evidence;
+    if (!memory.evidence.candidateFiles.includes(filePath)) {
+        memory.evidence.candidateFiles.push(filePath);
+    }
+    updateCandidateMetadata(memory, filePath, evidence);
+    return evidence;
+}
+export async function triageAgentFile(memory, rawTarget) {
+    const targetPath = resolveReadTarget(memory, rawTarget);
+    const code = fs.readFileSync(targetPath, "utf-8");
+    const evidence = summarizeFileRead(targetPath, code, memory.task.normalizedQuery, {
+        readMode: "triage",
+        hardTarget: isHardTarget(memory, targetPath),
+        explicitTargets: memory.task.explicitTargets,
+    });
+    return storeReadEvidence(memory, targetPath, evidence);
+}
+export async function readAgentFile(memory, rawTarget) {
+    const targetPath = resolveReadTarget(memory, rawTarget);
+    const code = fs.readFileSync(targetPath, "utf-8");
+    const persisted = loadPersistedFullRead(targetPath, code);
+    if (persisted) {
+        return storeReadEvidence(memory, targetPath, persisted);
+    }
+    const base = buildDeterministicFullReadFallback(targetPath, code, memory.task.normalizedQuery, {
+        hardTarget: isHardTarget(memory, targetPath),
+        explicitTargets: memory.task.explicitTargets,
+    });
+    const prompt = buildFullReadPrompt(memory.task.normalizedQuery, targetPath, selectCodeForFullReadPrompt(code, memory.task.normalizedQuery, MAX_FULL_READ_CODE_CHARS));
+    try {
+        const response = await generate({ query: memory.task.initialQuery, content: prompt }, {
+            caller: "agent.read-file",
+            inputContext: {
+                query: memory.task.normalizedQuery,
+                filePath: targetPath,
+                hardTarget: isHardTarget(memory, targetPath),
+            },
+        });
+        const parsed = parseStructuredReadResponse(String(response?.data ?? ""));
+        const evidence = mergeFullReadEvidence(base, parsed);
+        savePersistedFullRead(evidence);
+        return storeReadEvidence(memory, targetPath, evidence);
+    }
+    catch {
+        savePersistedFullRead(base);
+        return storeReadEvidence(memory, targetPath, base);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/agent/read/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/read/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Owns the canonical read path for the modular agent runtime.\n *\n * Why this file exists:\n * - the new agent should have one read entrypoint area\n * - read execution should stay separate from policy decisions about when to triage or fully read\n * - target resolution, freshness, prompts, and fallback shaping belong together\n * - policy should call read-owned path checks instead of touching the file system directly\n */\nimport fs from \"fs\";\nimport type { AgentMemory, AgentReadEvidence } from \"../types.js\";\nimport { generate } from \"../../lib/generate.js\";\nimport {\n  buildDeterministicFullReadFallback,\n  selectCodeForFullReadPrompt,\n  summarizeFileRead,\n} from \"./summarizeReadEvidence.js\";\nimport {\n  canReadExplicitTarget,\n  resolveExplicitFileTarget,\n  resolveReadTarget,\n  UnresolvedAgentTargetError,\n} from \"./targetResolution.js\";\nimport { hasFreshReadForPath } from \"./freshness.js\";\nimport { buildFullReadPrompt } from \"./fullReadPrompt.js\";\nimport { loadPersistedFullRead, savePersistedFullRead } from \"./persistence.js\";\n\nconst MAX_FULL_READ_CODE_CHARS = 9000;\n\nexport {\n  canReadExplicitTarget,\n  hasFreshReadForPath,\n  resolveExplicitFileTarget,\n  resolveReadTarget,\n  summarizeFileRead,\n  UnresolvedAgentTargetError,\n};\n\nfunction isHardTarget(memory: AgentMemory, filePath: string): boolean {\n  return memory.task.hardFileTargets.includes(filePath);\n}\n\nfunction parseStructuredReadResponse(raw: string): Partial<AgentReadEvidence> {\n  const trimmed = raw.trim();\n  const fenced = trimmed.match(/```(?:json)?\\s*([\\s\\S]*?)```/i);\n  const candidate = fenced?.[1]?.trim() || trimmed;\n  try {\n    return JSON.parse(candidate) as Partial<AgentReadEvidence>;\n  } catch {\n    return {};\n  }\n}\n\nfunction chooseFullReadRole(value: unknown, fallback: AgentReadEvidence[\"role\"]): AgentReadEvidence[\"role\"] {\n  return value === \"primary\" || value === \"supporting\" || value === \"contextual\"\n    ? value\n    : fallback;\n}\n\nfunction normalizeStringList(values: unknown, limit: number): string[] | undefined {\n  if (!Array.isArray(values)) {\n    return undefined;\n  }\n  return values.map((value) => String(value ?? \"\").trim()).filter(Boolean).slice(0, limit);\n}\n\nfunction normalizeExcerpts(\n  excerpts: unknown,\n  fallback: AgentReadEvidence[\"excerpts\"]\n): AgentReadEvidence[\"excerpts\"] {\n  if (!Array.isArray(excerpts)) {\n    return fallback;\n  }\n  return excerpts\n    .filter((excerpt): excerpt is NonNullable<AgentReadEvidence[\"excerpts\"]>[number] => {\n      return typeof excerpt?.code === \"string\" && excerpt.code.trim().length > 0;\n    })\n    .slice(0, 3);\n}\n\nfunction mergeFullReadEvidence(base: AgentReadEvidence, parsed: Partial<AgentReadEvidence>): AgentReadEvidence {\n  return {\n    ...base,\n    readMode: \"full\",\n    summary: typeof parsed.summary === \"string\" && parsed.summary.trim().length > 0\n      ? parsed.summary.trim().slice(0, 240)\n      : base.summary,\n    relevanceExplanation: typeof parsed.relevanceExplanation === \"string\" && parsed.relevanceExplanation.trim().length > 0\n      ? parsed.relevanceExplanation.trim()\n      : base.relevanceExplanation,\n    role: chooseFullReadRole(parsed.role, base.role),\n    excerpts: normalizeExcerpts(parsed.excerpts, base.excerpts),\n    risks: normalizeStringList(parsed.risks, 4) ?? base.risks,\n    keySymbols: normalizeStringList(parsed.keySymbols, 8) ?? base.keySymbols,\n  };\n}\n\nfunction resolveReadPriority(searchScore: number | undefined, triageScore: number | undefined): number | undefined {\n  if (typeof triageScore !== \"number\") {\n    return undefined;\n  }\n  if (typeof searchScore === \"number\") {\n    return Number((searchScore + triageScore).toFixed(2));\n  }\n  return triageScore;\n}\n\nfunction updateCandidateMetadata(memory: AgentMemory, filePath: string, evidence: AgentReadEvidence): void {\n  memory.evidence.candidateMetadata ??= {};\n  const existing = memory.evidence.candidateMetadata[filePath] ?? {};\n  const readPriority = resolveReadPriority(existing.searchScore, evidence.triageScore);\n  memory.evidence.candidateMetadata[filePath] = {\n    ...existing,\n    ...(typeof evidence.triageScore === \"number\" ? { triageScore: evidence.triageScore } : {}),\n    ...(typeof readPriority === \"number\" ? { readPriority } : {}),\n    lastUpdatedAt: evidence.recordedAt,\n  };\n}\n\nfunction storeReadEvidence(memory: AgentMemory, filePath: string, evidence: AgentReadEvidence): AgentReadEvidence {\n  memory.evidence.fileReads[filePath] = evidence;\n  if (!memory.evidence.candidateFiles.includes(filePath)) {\n    memory.evidence.candidateFiles.push(filePath);\n  }\n  updateCandidateMetadata(memory, filePath, evidence);\n  return evidence;\n}\n\nexport async function triageAgentFile(memory: AgentMemory, rawTarget: string): Promise<AgentReadEvidence> {\n  const targetPath = resolveReadTarget(memory, rawTarget);\n  const code = fs.readFileSync(targetPath, \"utf-8\");\n  const evidence = summarizeFileRead(targetPath, code, memory.task.normalizedQuery, {\n    readMode: \"triage\",\n    hardTarget: isHardTarget(memory, targetPath),\n    explicitTargets: memory.task.explicitTargets,\n  });\n  return storeReadEvidence(memory, targetPath, evidence);\n}\n\nexport async function readAgentFile(memory: AgentMemory, rawTarget: string): Promise<AgentReadEvidence> {\n  const targetPath = resolveReadTarget(memory, rawTarget);\n  const code = fs.readFileSync(targetPath, \"utf-8\");\n  const persisted = loadPersistedFullRead(targetPath, code);\n  if (persisted) {\n    return storeReadEvidence(memory, targetPath, persisted);\n  }\n  const base = buildDeterministicFullReadFallback(targetPath, code, memory.task.normalizedQuery, {\n    hardTarget: isHardTarget(memory, targetPath),\n    explicitTargets: memory.task.explicitTargets,\n  });\n  const prompt = buildFullReadPrompt(\n    memory.task.normalizedQuery,\n    targetPath,\n    selectCodeForFullReadPrompt(code, memory.task.normalizedQuery, MAX_FULL_READ_CODE_CHARS)\n  );\n\n  try {\n    const response = await generate({ query: memory.task.initialQuery, content: prompt }, {\n      caller: \"agent.read-file\",\n      inputContext: {\n        query: memory.task.normalizedQuery,\n        filePath: targetPath,\n        hardTarget: isHardTarget(memory, targetPath),\n      },\n    });\n    const parsed = parseStructuredReadResponse(String(response?.data ?? \"\"));\n    const evidence = mergeFullReadEvidence(base, parsed);\n    savePersistedFullRead(evidence);\n    return storeReadEvidence(memory, targetPath, evidence);\n  } catch {\n    savePersistedFullRead(base);\n    return storeReadEvidence(memory, targetPath, base);\n  }\n}\n"]}

package/dist/agent/read/persistence.js

@@ -0,0 +1,88 @@
+/**
+ * Persists reusable full-read evidence for the modular agent by file content hash.
+ *
+ * Why this file exists:
+ * - full reads are expensive and should be reused across later runs when file bytes did not change
+ * - the new agent needs one small owner for read persistence instead of mixing DB logic into the loop
+ * - reuse rules for persisted reads should stay content-based and separate from older query-based cache rules
+ */
+import fs from "fs";
+import { createHash } from "crypto";
+import { getDbForRepo } from "../../db/client.js";
+function withPersistedReadDb(fn) {
+    try {
+        const db = getDbForRepo();
+        return fn(db);
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizePersistedFullRead(payload, filePath) {
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    const evidence = payload;
+    const summary = typeof evidence.summary === "string" ? evidence.summary : undefined;
+    const recordedAt = typeof evidence.recordedAt === "string" ? evidence.recordedAt : undefined;
+    if (!summary || !recordedAt) {
+        return undefined;
+    }
+    return {
+        ...evidence,
+        filePath,
+        readMode: "full",
+        summary,
+        snippets: Array.isArray(evidence.snippets) ? evidence.snippets.map((snippet) => String(snippet)) : [],
+        matchedTerms: Array.isArray(evidence.matchedTerms) ? evidence.matchedTerms.map((term) => String(term)) : [],
+        relevantContext: Array.isArray(evidence.relevantContext)
+            ? evidence.relevantContext.filter((item) => {
+                return typeof item?.kind === "string" && typeof item?.text === "string";
+            })
+            : [],
+        recordedAt,
+    };
+}
+export function computeReadContentHash(code) {
+    return createHash("sha1").update(code).digest("hex").slice(0, 12);
+}
+export function loadPersistedFullRead(filePath, code) {
+    const row = withPersistedReadDb((db) => db.prepare(`
+    SELECT file_path, content_hash, read_mode, payload_json
+    FROM agent_file_reads
+    WHERE file_path = ? AND read_mode = 'full'
+  `).get(filePath));
+    if (!row) {
+        return undefined;
+    }
+    const currentHash = computeReadContentHash(code);
+    if (row.content_hash !== currentHash) {
+        return undefined;
+    }
+    try {
+        return normalizePersistedFullRead(JSON.parse(row.payload_json), filePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function savePersistedFullRead(evidence) {
+    const now = new Date().toISOString();
+    const code = fs.readFileSync(evidence.filePath, "utf-8");
+    const contentHash = computeReadContentHash(code);
+    withPersistedReadDb((db) => db.prepare(`
+    INSERT INTO agent_file_reads (
+      file_path,
+      content_hash,
+      read_mode,
+      payload_json,
+      created_at,
+      updated_at
+    ) VALUES (?, ?, 'full', ?, ?, ?)
+    ON CONFLICT(file_path, read_mode) DO UPDATE SET
+      content_hash = excluded.content_hash,
+      payload_json = excluded.payload_json,
+      updated_at = excluded.updated_at
+  `).run(evidence.filePath, contentHash, JSON.stringify(evidence), now, now));
+}
+//# sourceMappingURL=persistence.js.map

package/dist/agent/read/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../../src/agent/read/persistence.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Persists reusable full-read evidence for the modular agent by file content hash.\n *\n * Why this file exists:\n * - full reads are expensive and should be reused across later runs when file bytes did not change\n * - the new agent needs one small owner for read persistence instead of mixing DB logic into the loop\n * - reuse rules for persisted reads should stay content-based and separate from older query-based cache rules\n */\nimport fs from \"fs\";\nimport { createHash } from \"crypto\";\nimport { getDbForRepo } from \"../../db/client.js\";\nimport type { AgentReadEvidence } from \"../types.js\";\nimport type { Database as DatabaseType } from \"better-sqlite3\";\n\ninterface PersistedFullReadRow {\n  file_path: string;\n  content_hash: string;\n  read_mode: string;\n  payload_json: string;\n}\n\nfunction withPersistedReadDb<T>(fn: (db: DatabaseType) => T): T | undefined {\n  try {\n    const db = getDbForRepo();\n    return fn(db);\n  } catch {\n    return undefined;\n  }\n}\n\nfunction normalizePersistedFullRead(payload: unknown, filePath: string): AgentReadEvidence | undefined {\n  if (!payload || typeof payload !== \"object\") {\n    return undefined;\n  }\n  const evidence = payload as Partial<AgentReadEvidence>;\n  const summary = typeof evidence.summary === \"string\" ? evidence.summary : undefined;\n  const recordedAt = typeof evidence.recordedAt === \"string\" ? evidence.recordedAt : undefined;\n  if (!summary || !recordedAt) {\n    return undefined;\n  }\n  return {\n    ...evidence,\n    filePath,\n    readMode: \"full\",\n    summary,\n    snippets: Array.isArray(evidence.snippets) ? evidence.snippets.map((snippet) => String(snippet)) : [],\n    matchedTerms: Array.isArray(evidence.matchedTerms) ? evidence.matchedTerms.map((term) => String(term)) : [],\n    relevantContext: Array.isArray(evidence.relevantContext)\n      ? evidence.relevantContext.filter((item): item is AgentReadEvidence[\"relevantContext\"][number] => {\n        return typeof item?.kind === \"string\" && typeof item?.text === \"string\";\n      })\n      : [],\n    recordedAt,\n  };\n}\n\nexport function computeReadContentHash(code: string): string {\n  return createHash(\"sha1\").update(code).digest(\"hex\").slice(0, 12);\n}\n\nexport function loadPersistedFullRead(filePath: string, code: string): AgentReadEvidence | undefined {\n  const row = withPersistedReadDb((db) => db.prepare(`\n    SELECT file_path, content_hash, read_mode, payload_json\n    FROM agent_file_reads\n    WHERE file_path = ? AND read_mode = 'full'\n  `).get(filePath) as PersistedFullReadRow | undefined);\n  if (!row) {\n    return undefined;\n  }\n  const currentHash = computeReadContentHash(code);\n  if (row.content_hash !== currentHash) {\n    return undefined;\n  }\n  try {\n    return normalizePersistedFullRead(JSON.parse(row.payload_json), filePath);\n  } catch {\n    return undefined;\n  }\n}\n\nexport function savePersistedFullRead(evidence: AgentReadEvidence): void {\n  const now = new Date().toISOString();\n  const code = fs.readFileSync(evidence.filePath, \"utf-8\");\n  const contentHash = computeReadContentHash(code);\n  withPersistedReadDb((db) => db.prepare(`\n    INSERT INTO agent_file_reads (\n      file_path,\n      content_hash,\n      read_mode,\n      payload_json,\n      created_at,\n      updated_at\n    ) VALUES (?, ?, 'full', ?, ?, ?)\n    ON CONFLICT(file_path, read_mode) DO UPDATE SET\n      content_hash = excluded.content_hash,\n      payload_json = excluded.payload_json,\n      updated_at = excluded.updated_at\n  `).run(\n    evidence.filePath,\n    contentHash,\n    JSON.stringify(evidence),\n    now,\n    now\n  ));\n}\n"]}