@securecode-ai/mcp 0.5.5 → 0.5.7

package/dist/attack/architectureScoutExecutor.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Architecture scout executor — dispatches each scout action to the right
+ * tool and returns a redacted, truncated observation string.
+ *
+ * This is a SUBSET of the agent-scan executor: only the
+ * architecture-relevant tools (read_file, search_code, list_files,
+ * list_imports, get_endpoints, call_graph, read_config, check_dependencies,
+ * find_definition, find_references). Vulnerability-confirmation tools
+ * (trace_flow, check_guard, check_policy, git_*, find_tests, run_tests)
+ * are NOT available — the scout surveys architecture, it does not confirm
+ * vulnerabilities.
+ *
+ * All tools run locally (no API round-trip — the scout has no equivalent
+ * of the agent-scan check_policy that calls back to the API).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeScoutAction = executeScoutAction;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const files_1 = require("../utils/files");
+const searchCode_1 = require("../utils/searchCode");
+const listImports_1 = require("../utils/listImports");
+const listFiles_1 = require("../utils/listFiles");
+const endpointDiscovery_1 = require("../project-map/endpointDiscovery");
+const callGraphExtractor_1 = require("../project-map/callGraphExtractor");
+const dependencyChecker_1 = require("../dependency/dependencyChecker");
+const depCache_1 = require("../dependency/depCache");
+const securityConfig_1 = require("../utils/securityConfig");
+const symbolIndex_1 = require("../project-map/symbolIndex");
+const agentScanExecutor_1 = require("./agentScanExecutor");
+async function executeScoutAction(action, ctx) {
+    switch (action.type) {
+        case 'read_file': {
+            try {
+                const absPath = (0, files_1.resolveWorkspacePath)(ctx.workspaceRoot, action.path);
+                const content = fs.readFileSync(absPath, 'utf8');
+                const rel = path.relative(ctx.workspaceRoot, absPath).replace(/\\/g, '/');
+                const allLines = content.split('\n');
+                const totalLines = allLines.length;
+                if (action.startLine || action.endLine) {
+                    const start = Math.max(1, action.startLine || 1);
+                    const end = Math.min(totalLines, action.endLine || totalLines);
+                    const section = allLines.slice(start - 1, end)
+                        .map((line, i) => `${start + i}: ${line}`)
+                        .join('\n');
+                    return (0, agentScanExecutor_1.redact)(`File: ${rel} (lines ${start}-${end} of ${totalLines})\n\n${section}`);
+                }
+                if (totalLines > agentScanExecutor_1.LARGE_FILE_THRESHOLD) {
+                    const funcMap = await (0, agentScanExecutor_1.extractFunctionMap)(content, rel);
+                    if (funcMap) {
+                        return (0, agentScanExecutor_1.redact)(`File: ${rel} (${totalLines} lines — LARGE FILE)\n\nThis file is too large to show in full. Here is a function map. Use read_file with startLine/endLine to read specific sections.\n\n${funcMap}`);
+                    }
+                }
+                const numbered = allLines
+                    .map((line, i) => `${i + 1}: ${line}`)
+                    .join('\n');
+                return (0, agentScanExecutor_1.redact)(`File: ${rel} (${totalLines} lines)\n\n${numbered}`);
+            }
+            catch (e) {
+                return `Error reading file "${action.path}": ${e.message || e}`;
+            }
+        }
+        case 'search_code': {
+            try {
+                const result = await (0, searchCode_1.searchCode)(ctx.workspaceRoot, action.pattern, action.glob);
+                return (0, agentScanExecutor_1.redact)((0, searchCode_1.formatSearchResult)(result));
+            }
+            catch (e) {
+                return `Error searching for "${action.pattern}": ${e.message || e}`;
+            }
+        }
+        case 'list_files': {
+            try {
+                const files = (0, listFiles_1.listFiles)(ctx.workspaceRoot, {
+                    dir: action.path,
+                    glob: action.glob,
+                });
+                return (0, agentScanExecutor_1.truncate)((0, listFiles_1.formatFileList)(files));
+            }
+            catch (e) {
+                return `Error listing files: ${e.message || e}`;
+            }
+        }
+        case 'list_imports': {
+            try {
+                const imports = await (0, listImports_1.listImports)(ctx.workspaceRoot, action.filePath);
+                return (0, agentScanExecutor_1.truncate)((0, listImports_1.formatImports)(imports, action.filePath));
+            }
+            catch (e) {
+                return `Error listing imports for "${action.filePath}": ${e.message || e}`;
+            }
+        }
+        case 'get_endpoints': {
+            try {
+                const endpoints = await (0, endpointDiscovery_1.discoverEndpoints)(ctx.workspaceRoot, action.glob);
+                return (0, agentScanExecutor_1.truncate)((0, endpointDiscovery_1.formatEndpoints)(endpoints));
+            }
+            catch (e) {
+                return `Error discovering endpoints: ${e.message || e}`;
+            }
+        }
+        case 'call_graph': {
+            try {
+                const result = await (0, callGraphExtractor_1.getCallGraph)(ctx.workspaceRoot, action.filePath, action.functionName);
+                return (0, agentScanExecutor_1.redact)(result);
+            }
+            catch (e) {
+                return `Error extracting call graph for "${action.filePath}": ${e.message || e}`;
+            }
+        }
+        case 'read_config': {
+            try {
+                const result = await (0, securityConfig_1.readSecurityConfig)(ctx.workspaceRoot, action.configKind);
+                return (0, agentScanExecutor_1.truncate)((0, agentScanExecutor_1.redact)(result));
+            }
+            catch (e) {
+                return `Error reading ${action.configKind} config: ${e.message || e}`;
+            }
+        }
+        case 'check_dependencies': {
+            try {
+                const cache = new depCache_1.FileCacheStore(ctx.workspaceRoot);
+                const result = await (0, dependencyChecker_1.scanDependencies)({
+                    workspaceRoot: ctx.workspaceRoot,
+                    state: cache,
+                    licensePolicy: 'warn',
+                    useGhsa: true,
+                });
+                if (result.findings.length === 0) {
+                    return `No vulnerable dependencies found. Scanned ${result.packageCount} package(s) across ${result.lockfiles.length} lockfile(s).`;
+                }
+                const vulnFindings = result.findings.filter(f => !f.check_id.startsWith('dep.license.') && !f.check_id.startsWith('dep.unresolved.'));
+                const lines = [
+                    `Dependency scan: ${vulnFindings.length} vulnerable package(s) across ${result.packageCount} package(s) (${result.lockfiles.length} lockfile(s)):`,
+                    '',
+                ];
+                for (const f of vulnFindings.slice(0, 30)) {
+                    const dep = f.dependency;
+                    const sev = f.severity === 'ERROR' ? 'CRITICAL' : 'HIGH';
+                    lines.push(`  [${sev}] ${dep?.name || 'unknown'}@${dep?.installedVersion || '?'} — ${f.message}`);
+                    if (dep?.fixedVersion)
+                        lines.push(`    Fix: upgrade to ${dep.fixedVersion}`);
+                }
+                if (vulnFindings.length > 30) {
+                    lines.push(`  ... and ${vulnFindings.length - 30} more`);
+                }
+                return (0, agentScanExecutor_1.truncate)(lines.join('\n'));
+            }
+            catch (e) {
+                return `Error checking dependencies: ${e.message || e}`;
+            }
+        }
+        case 'find_definition': {
+            try {
+                const result = await (0, symbolIndex_1.findDefinition)(ctx.workspaceRoot, action.filePath, action.symbol, action.line);
+                return (0, agentScanExecutor_1.truncate)(result);
+            }
+            catch (e) {
+                return `Error finding definition of "${action.symbol}": ${e.message || e}`;
+            }
+        }
+        case 'find_references': {
+            try {
+                const result = await (0, symbolIndex_1.findReferences)(ctx.workspaceRoot, action.filePath, action.symbol, action.line);
+                return (0, agentScanExecutor_1.truncate)(result);
+            }
+            catch (e) {
+                return `Error finding references to "${action.symbol}": ${e.message || e}`;
+            }
+        }
+        case 'finish': {
+            return '';
+        }
+    }
+    return '';
+}
+//# sourceMappingURL=architectureScoutExecutor.js.map

package/dist/attack/architectureScoutExecutor.js.map

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

package/dist/attack/architectureScoutLoop.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Architecture scout loop driver — the MCP-side loop that drives the
+ * architecture-scout subagent.
+ *
+ * Mirrors agentScanLoop.ts but with architecture-scout tools and a finish
+ * action that returns an ArchitectureContext instead of vulnerability
+ * findings.
+ *
+ * Flow:
+ *   1. POST /agent/architecture/start → { runId, budget }
+ *   2. while (true):
+ *        POST /agent/architecture/step { runId, target, transcript, budget }
+ *        ← { next: action | null }
+ *        if null → done (capped or completed)
+ *        if finish → done with ArchitectureContext
+ *        execute action locally → observation
+ *        push { action, observation } into transcript
+ *   3. return result
+ *
+ * The loop inherits the system_event + protocolValidator hardening from
+ * agentScanLoop: malformed API responses are rejected, errors are surfaced
+ * as system_event(error) instead of fake read_file('__ERROR__').
+ */
+import type { ServerContext } from '../mcp/types';
+import { ARCHITECTURE_SCOUT_DEFAULTS, type ArchitectureDepth, type ArchitectureScoutResult, type ArchitectureScoutTarget } from './architectureScoutProtocol';
+export interface ArchitectureScoutOptions {
+    depth?: ArchitectureDepth;
+    signal?: AbortSignal;
+    onProgress?: (stepsTaken: number, maxSteps: number, message: string) => void;
+    /** Project map builtAt — stamped on the result context for cache invalidation. */
+    projectMapBuiltAt?: number;
+    /** Project map schema version — stamped on the result context. */
+    projectMapVersion?: number;
+}
+export declare function runArchitectureScout(ctx: ServerContext, target: ArchitectureScoutTarget, options?: ArchitectureScoutOptions): Promise<ArchitectureScoutResult>;
+export { ARCHITECTURE_SCOUT_DEFAULTS };

package/dist/attack/architectureScoutLoop.js

@@ -0,0 +1,403 @@
+"use strict";
+/**
+ * Architecture scout loop driver — the MCP-side loop that drives the
+ * architecture-scout subagent.
+ *
+ * Mirrors agentScanLoop.ts but with architecture-scout tools and a finish
+ * action that returns an ArchitectureContext instead of vulnerability
+ * findings.
+ *
+ * Flow:
+ *   1. POST /agent/architecture/start → { runId, budget }
+ *   2. while (true):
+ *        POST /agent/architecture/step { runId, target, transcript, budget }
+ *        ← { next: action | null }
+ *        if null → done (capped or completed)
+ *        if finish → done with ArchitectureContext
+ *        execute action locally → observation
+ *        push { action, observation } into transcript
+ *   3. return result
+ *
+ * The loop inherits the system_event + protocolValidator hardening from
+ * agentScanLoop: malformed API responses are rejected, errors are surfaced
+ * as system_event(error) instead of fake read_file('__ERROR__').
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARCHITECTURE_SCOUT_DEFAULTS = void 0;
+exports.runArchitectureScout = runArchitectureScout;
+const client_1 = require("../api/client");
+const architectureScoutExecutor_1 = require("./architectureScoutExecutor");
+const architectureScoutProtocol_1 = require("./architectureScoutProtocol");
+Object.defineProperty(exports, "ARCHITECTURE_SCOUT_DEFAULTS", { enumerable: true, get: function () { return architectureScoutProtocol_1.ARCHITECTURE_SCOUT_DEFAULTS; } });
+const architectureContext_1 = require("../project-map/architectureContext");
+// Re-use the agent-scan response validator shape. The architecture scout
+// step response has the same fields as AgentScanStepResponse (minus
+// systemEvent, which the scout doesn't use in v1). We validate inline
+// rather than importing the agent-scan validator (which checks agent-scan
+// action types the scout doesn't have).
+const protocolValidator_1 = require("./protocolValidator");
+// ── Inline validators (scout-specific) ──────────────────────────────────────
+//
+// The scout action types are a subset of agent-scan's, but the validator in
+// protocolValidator.ts checks the full agent-scan action union (including
+// trace_flow, check_guard, etc.). Rather than weaken that validator, we
+// validate the scout actions inline here. The start-response validator is
+// shape-compatible, so we reuse it.
+const VALID_SCOUT_ACTION_TYPES = new Set([
+    'read_file', 'search_code', 'list_files', 'list_imports',
+    'get_endpoints', 'call_graph', 'read_config', 'check_dependencies',
+    'find_definition', 'find_references', 'finish',
+]);
+function validateScoutAction(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return { ok: false, error: 'action is not an object' };
+    }
+    const a = raw;
+    const type = a.type;
+    if (typeof type !== 'string' || !VALID_SCOUT_ACTION_TYPES.has(type)) {
+        return { ok: false, error: `action.type is missing or unknown: ${String(type)}` };
+    }
+    // Light field checks for the primary tool args. The API controller does
+    // deeper validation; here we just block obviously malformed actions
+    // from reaching the executor.
+    if (type === 'read_file' && (typeof a.path !== 'string' || a.path.length === 0)) {
+        return { ok: false, error: 'read_file requires non-empty "path"' };
+    }
+    if (type === 'search_code' && (typeof a.pattern !== 'string' || a.pattern.length === 0)) {
+        return { ok: false, error: 'search_code requires non-empty "pattern"' };
+    }
+    if (type === 'list_imports' && (typeof a.filePath !== 'string' || a.filePath.length === 0)) {
+        return { ok: false, error: 'list_imports requires non-empty "filePath"' };
+    }
+    if (type === 'call_graph' && (typeof a.filePath !== 'string' || a.filePath.length === 0)) {
+        return { ok: false, error: 'call_graph requires non-empty "filePath"' };
+    }
+    if (type === 'read_config') {
+        const validKinds = new Set(['auth', 'cors', 'rate_limit', 'headers', 'env', 'all']);
+        if (typeof a.configKind !== 'string' || !validKinds.has(a.configKind)) {
+            return { ok: false, error: 'read_config requires valid "configKind"' };
+        }
+    }
+    if (type === 'find_definition' || type === 'find_references') {
+        if (typeof a.filePath !== 'string' || a.filePath.length === 0) {
+            return { ok: false, error: `${type} requires non-empty "filePath"` };
+        }
+        if (typeof a.symbol !== 'string' || a.symbol.length === 0) {
+            return { ok: false, error: `${type} requires non-empty "symbol"` };
+        }
+    }
+    if (type === 'finish') {
+        if (typeof a.summary !== 'string' || a.summary.length === 0) {
+            return { ok: false, error: 'finish requires "summary"' };
+        }
+        if (typeof a.selfCritique !== 'string' || a.selfCritique.length === 0) {
+            return { ok: false, error: 'finish requires "selfCritique"' };
+        }
+        if (typeof a.architecture !== 'object' || a.architecture === null) {
+            return { ok: false, error: 'finish requires "architecture" object' };
+        }
+    }
+    return { ok: true, value: raw };
+}
+function validateScoutStepResponse(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return { ok: false, error: 'step response is not an object' };
+    }
+    const r = raw;
+    if (r.next !== null && r.next !== undefined) {
+        const actionResult = validateScoutAction(r.next);
+        if (!actionResult.ok)
+            return { ok: false, error: `step response next: ${actionResult.error}` };
+    }
+    if (typeof r.costUsd !== 'number')
+        return { ok: false, error: 'costUsd must be a number' };
+    if (typeof r.tokens !== 'number')
+        return { ok: false, error: 'tokens must be a number' };
+    if (typeof r.degraded !== 'boolean')
+        return { ok: false, error: 'degraded must be a boolean' };
+    if (typeof r.costCapped !== 'boolean')
+        return { ok: false, error: 'costCapped must be a boolean' };
+    if (typeof r.stepsRemaining !== 'number')
+        return { ok: false, error: 'stepsRemaining must be a number' };
+    return { ok: true, value: raw };
+}
+// ── Main loop ───────────────────────────────────────────────────────────────
+async function runArchitectureScout(ctx, target, options = {}) {
+    const client = new client_1.ApiClient({ baseUrl: ctx.apiUrl, token: ctx.apiToken });
+    const depth = options.depth ?? 'standard';
+    const defaults = (0, architectureScoutProtocol_1.scoutDefaultsForDepth)(depth);
+    const budget = {
+        stepsRemaining: defaults.maxSteps,
+        costSpentUsd: 0,
+        costCapUsd: defaults.costCapUsd,
+    };
+    const startTime = Date.now();
+    const wallClockMs = defaults.wallClockMs;
+    let stepsTaken = 0;
+    let costSpentUsd = 0;
+    try {
+        const startRespRaw = await client.postJson('/agent/architecture/start', { depth }, options.signal);
+        // Re-use the agent-scan start response validator — the shape is
+        // identical (runId, budget, scanCredits, refundId).
+        const startValidation = (0, protocolValidator_1.validateStartResponse)(startRespRaw);
+        if (!startValidation.ok) {
+            return {
+                status: 'spawn_failed',
+                architecture: null,
+                transcript: [],
+                stepsUsed: 0,
+                costSpentUsd: 0,
+                error: `API returned an invalid start response: ${startValidation.error}`,
+            };
+        }
+        const startResp = startValidation.value;
+        const transcript = [];
+        const readFiles = new Set();
+        const readFileCounts = new Map();
+        const toolCallCounts = new Map();
+        const MAX_SAME_TOOL_CALL = 2;
+        let consecutiveErrors = 0;
+        while (true) {
+            if (Date.now() - startTime > wallClockMs) {
+                return {
+                    status: 'capped',
+                    architecture: null,
+                    transcript,
+                    stepsUsed: stepsTaken,
+                    costSpentUsd,
+                    summary: `Wall clock limit (${wallClockMs}ms) exceeded.`,
+                };
+            }
+            if (options.signal?.aborted) {
+                return {
+                    status: 'cancelled',
+                    architecture: null,
+                    transcript,
+                    stepsUsed: stepsTaken,
+                    costSpentUsd,
+                    summary: 'Cancelled by user.',
+                };
+            }
+            const stepReq = {
+                runId: startResp.runId,
+                target,
+                transcript,
+                budget: {
+                    stepsRemaining: budget.stepsRemaining,
+                    costSpentUsd,
+                    costCapUsd: budget.costCapUsd,
+                },
+            };
+            let stepResp;
+            try {
+                const stepRespRaw = await client.postJson('/agent/architecture/step', stepReq, options.signal);
+                const stepValidation = validateScoutStepResponse(stepRespRaw);
+                if (!stepValidation.ok) {
+                    const vErr = stepValidation.error;
+                    console.warn(`[Architecture Scout] Step ${stepsTaken + 1} returned a malformed response: ${vErr}`);
+                    consecutiveErrors++;
+                    stepsTaken++;
+                    budget.stepsRemaining--;
+                    const errMsg = `API returned a malformed step response: ${vErr}`;
+                    transcript.push({
+                        action: { type: 'finish', architecture: {}, summary: '', selfCritique: errMsg },
+                        observation: errMsg,
+                    });
+                    if (consecutiveErrors >= 3 || budget.stepsRemaining <= 0) {
+                        return {
+                            status: 'capped',
+                            architecture: null,
+                            transcript,
+                            stepsUsed: stepsTaken,
+                            costSpentUsd,
+                            summary: `Step budget exhausted after ${consecutiveErrors} consecutive malformed API responses. Last error: ${vErr}`,
+                        };
+                    }
+                    continue;
+                }
+                stepResp = stepValidation.value;
+            }
+            catch (stepErr) {
+                const errMsg = stepErr?.message || String(stepErr);
+                const apiCode = stepErr?.apiCode || '';
+                if (apiCode === 'AGENT_RUN_NOT_FOUND' || /AGENT_RUN_NOT_FOUND|Invalid or expired agent run/i.test(errMsg)) {
+                    return {
+                        status: 'spawn_failed',
+                        architecture: null,
+                        transcript,
+                        stepsUsed: stepsTaken,
+                        costSpentUsd,
+                        error: 'API server restarted mid-scout — the run was lost. Please retry.',
+                    };
+                }
+                if (options.signal?.aborted || /aborted/i.test(errMsg)) {
+                    return {
+                        status: 'cancelled',
+                        architecture: null,
+                        transcript,
+                        stepsUsed: stepsTaken,
+                        costSpentUsd,
+                        summary: 'Cancelled by user.',
+                    };
+                }
+                console.warn(`[Architecture Scout] Step ${stepsTaken + 1} error: ${errMsg}`);
+                consecutiveErrors++;
+                stepsTaken++;
+                budget.stepsRemaining--;
+                const errorMsg = `ERROR: Your previous action was rejected: ${errMsg}. Please try a DIFFERENT action with ALL required fields.`;
+                transcript.push({
+                    action: { type: 'finish', architecture: {}, summary: '', selfCritique: errorMsg },
+                    observation: errorMsg,
+                });
+                if (consecutiveErrors >= 3 || budget.stepsRemaining <= 0) {
+                    return {
+                        status: 'capped',
+                        architecture: null,
+                        transcript,
+                        stepsUsed: stepsTaken,
+                        costSpentUsd,
+                        summary: `Step budget exhausted after ${consecutiveErrors} consecutive API errors. Last error: ${errMsg}`,
+                    };
+                }
+                continue;
+            }
+            costSpentUsd += stepResp.costUsd || 0;
+            consecutiveErrors = 0;
+            if (!stepResp.next) {
+                const status = stepResp.costCapped
+                    ? 'capped'
+                    : (stepResp.degraded ? 'degraded' : 'completed');
+                return {
+                    status,
+                    architecture: null,
+                    transcript,
+                    stepsUsed: stepsTaken,
+                    costSpentUsd,
+                    summary: stepResp.costCapped
+                        ? `Cost cap ($${budget.costCapUsd.toFixed(2)}) reached.`
+                        : 'Scout completed without explicit finish.',
+                };
+            }
+            const action = stepResp.next;
+            stepsTaken++;
+            budget.stepsRemaining = stepResp.stepsRemaining;
+            if (options.onProgress) {
+                options.onProgress(stepsTaken, defaults.maxSteps, `Step ${stepsTaken}: ${describeScoutAction(action)}`);
+            }
+            if (action.type === 'finish') {
+                if (!(0, architectureScoutProtocol_1.isScoutFinishAction)(action)) {
+                    // Validator should have caught this, but double-check.
+                    return {
+                        status: 'spawn_failed',
+                        architecture: null,
+                        transcript,
+                        stepsUsed: stepsTaken,
+                        costSpentUsd,
+                        error: 'Finish action did not pass type guard.',
+                    };
+                }
+                // Stamp the context with cache/derivation metadata before
+                // returning — the LLM doesn't know these fields.
+                const ctx2 = action.architecture;
+                ctx2.version = architectureContext_1.ARCHITECTURE_CONTEXT_VERSION;
+                ctx2.depth = depth;
+                ctx2.derivedAt = Date.now();
+                ctx2.projectMapBuiltAt = options.projectMapBuiltAt ?? 0;
+                ctx2.projectMapVersion = options.projectMapVersion ?? 0;
+                if (!ctx2.completeness)
+                    ctx2.completeness = 'partial';
+                // Cap importantFiles at maxImportantFiles — the LLM may
+                // exceed the cap despite the prompt instruction.
+                if (ctx2.importantFiles && ctx2.importantFiles.length > target.maxImportantFiles) {
+                    ctx2.importantFiles = ctx2.importantFiles
+                        .sort((a, b) => b.importance - a.importance)
+                        .slice(0, target.maxImportantFiles);
+                }
+                return {
+                    status: 'completed',
+                    architecture: ctx2,
+                    transcript,
+                    stepsUsed: stepsTaken,
+                    costSpentUsd,
+                    summary: action.summary,
+                };
+            }
+            // Dedup: prevent the scout from re-reading the same file range
+            // or calling the same tool with identical args repeatedly.
+            let observation;
+            let wasBlocked = false;
+            if (action.type === 'read_file') {
+                const normalizedPath = action.path.replace(/\\/g, '/').toLowerCase();
+                const rangeKey = `${normalizedPath}:${action.startLine || 0}:${action.endLine || 0}`;
+                if (readFiles.has(rangeKey)) {
+                    observation = `File "${action.path}" (lines ${action.startLine || 'all'}-${action.endLine || 'all'}) was already read. The content is in the transcript above. Use a DIFFERENT line range or a different tool.`;
+                    wasBlocked = true;
+                }
+                else {
+                    const count = (readFileCounts.get(normalizedPath) || 0) + 1;
+                    readFileCounts.set(normalizedPath, count);
+                    readFiles.add(rangeKey);
+                    observation = await (0, architectureScoutExecutor_1.executeScoutAction)(action, ctx);
+                    if (count >= 5) {
+                        observation += `\n\nNOTE: You have read "${action.path}" ${count} times. Consider using search_code, call_graph, find_references, or finish to proceed.`;
+                    }
+                }
+            }
+            else {
+                let toolKey = '';
+                if (action.type === 'search_code')
+                    toolKey = `search_code:${action.pattern}:${action.glob || ''}`;
+                else if (action.type === 'call_graph')
+                    toolKey = `call_graph:${action.filePath}:${action.functionName || ''}`;
+                else if (action.type === 'list_imports')
+                    toolKey = `list_imports:${action.filePath}`;
+                else if (action.type === 'find_definition')
+                    toolKey = `find_definition:${action.filePath}:${action.symbol}`;
+                else if (action.type === 'find_references')
+                    toolKey = `find_references:${action.filePath}:${action.symbol}`;
+                if (toolKey) {
+                    const count = (toolCallCounts.get(toolKey) || 0) + 1;
+                    toolCallCounts.set(toolKey, count);
+                    if (count > MAX_SAME_TOOL_CALL) {
+                        observation = `You have already called this exact tool with the same arguments ${MAX_SAME_TOOL_CALL} times. Use a DIFFERENT tool, different arguments, or call finish to report your architecture context.`;
+                        wasBlocked = true;
+                    }
+                    else {
+                        observation = await (0, architectureScoutExecutor_1.executeScoutAction)(action, ctx);
+                    }
+                }
+                else {
+                    observation = await (0, architectureScoutExecutor_1.executeScoutAction)(action, ctx);
+                }
+            }
+            transcript.push({ action, observation });
+        }
+    }
+    catch (err) {
+        return {
+            status: 'spawn_failed',
+            architecture: null,
+            transcript: [],
+            stepsUsed: stepsTaken,
+            costSpentUsd,
+            error: err.message || String(err),
+        };
+    }
+}
+function describeScoutAction(action) {
+    switch (action.type) {
+        case 'read_file': return `read_file(${action.path})`;
+        case 'search_code': return `search_code("${action.pattern}")`;
+        case 'list_files': return `list_files(${action.path || 'root'})`;
+        case 'list_imports': return `list_imports(${action.filePath})`;
+        case 'get_endpoints': return `get_endpoints(${action.glob || 'all'})`;
+        case 'call_graph': return `call_graph(${action.filePath}${action.functionName ? `, fn=${action.functionName}` : ''})`;
+        case 'read_config': return `read_config(${action.configKind})`;
+        case 'check_dependencies': return 'check_dependencies';
+        case 'find_definition': return `find_definition(${action.symbol})`;
+        case 'find_references': return `find_references(${action.symbol})`;
+        case 'finish': return 'finish';
+    }
+    return 'unknown';
+}
+//# sourceMappingURL=architectureScoutLoop.js.map