@caupulican/pi-adaptative 0.80.85 → 0.80.88

package/dist/core/autonomy/status.js

@@ -0,0 +1,107 @@
+const REDACTED = "[REDACTED]";
+const CIRCULAR = "[Circular]";
+const MAX_STRING_LENGTH = 200;
+const SENSITIVE_KEYS = ["token", "secret", "key", "credential", "password", "authorization"];
+const SENSITIVE_VALUE_REGEX = /bearer\s+[\w\-._]+|api[-_]?key[-_]?[\w\-._]+|sk-[\w\-._]+/i;
+function formatCost(value) {
+    return Number.isFinite(value) ? `$${value.toFixed(4)}` : "$0.0000";
+}
+function redactAndTruncateString(value) {
+    if (SENSITIVE_VALUE_REGEX.test(value))
+        return REDACTED;
+    if (value.length <= MAX_STRING_LENGTH)
+        return value;
+    return `${value.slice(0, MAX_STRING_LENGTH - 1)}…`;
+}
+function isSensitiveKey(key) {
+    const lowerKey = key.toLowerCase();
+    return SENSITIVE_KEYS.some((sensitiveKey) => lowerKey.includes(sensitiveKey));
+}
+function sanitizeMetadataValue(value, seen) {
+    if (typeof value === "string")
+        return redactAndTruncateString(value);
+    if (typeof value !== "object" || value === null)
+        return value;
+    if (seen.has(value))
+        return CIRCULAR;
+    if (Array.isArray(value)) {
+        seen.add(value);
+        return value.map((item) => sanitizeMetadataValue(item, seen));
+    }
+    return sanitizeMetadata(value, seen);
+}
+function sanitizeMetadata(obj, seen = new WeakSet()) {
+    if (seen.has(obj))
+        return { value: CIRCULAR };
+    seen.add(obj);
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        result[key] = isSensitiveKey(key) ? REDACTED : sanitizeMetadataValue(value, seen);
+    }
+    return result;
+}
+export function formatAutonomyStatus(args) {
+    const parts = [];
+    if (args.latestRoute) {
+        const risk = args.latestRoute.risk ? ` (${redactAndTruncateString(args.latestRoute.risk)})` : "";
+        parts.push(`Route: ${redactAndTruncateString(args.latestRoute.tier)}${risk} - ${redactAndTruncateString(args.latestRoute.reasonCode)}`);
+    }
+    if (args.latestGate) {
+        parts.push(`Gate: ${redactAndTruncateString(args.latestGate.gate)} = ${redactAndTruncateString(args.latestGate.outcome)} (${redactAndTruncateString(args.latestGate.reasonCode)})`);
+    }
+    const costs = [];
+    if (args.currentCostUsd !== undefined)
+        costs.push(`current: ${formatCost(args.currentCostUsd)}`);
+    if (args.dailyCostUsd !== undefined)
+        costs.push(`daily: ${formatCost(args.dailyCostUsd)}`);
+    if (args.spawnedCostUsd !== undefined)
+        costs.push(`spawned: ${formatCost(args.spawnedCostUsd)}`);
+    if (costs.length > 0) {
+        parts.push(`Costs: ${costs.join(", ")}`);
+    }
+    if (args.activeGoal) {
+        const goal = args.activeGoal;
+        const requirements = goal.openRequirements !== undefined ? `, open reqs: ${goal.openRequirements}` : "";
+        const stalls = goal.stallTurns !== undefined ? `, stalls: ${goal.stallTurns}` : "";
+        parts.push(`Goal [${redactAndTruncateString(goal.goalId)}]: ${redactAndTruncateString(goal.status)}${requirements}${stalls}`);
+    }
+    if (args.activeLaneCount !== undefined) {
+        parts.push(`Lanes: ${args.activeLaneCount}`);
+    }
+    if (parts.length === 0)
+        return "Autonomy: idle";
+    return parts.join(" | ");
+}
+function formatDiagnosticSection(name, entries) {
+    if (!entries || entries.length === 0)
+        return undefined;
+    const lines = [`--- ${name} ---`];
+    for (const entry of entries) {
+        let header = `- ${redactAndTruncateString(entry.title)}`;
+        if (entry.reasonCode)
+            header += ` [${redactAndTruncateString(entry.reasonCode)}]`;
+        lines.push(header);
+        if (entry.summary) {
+            lines.push(`  Summary: ${redactAndTruncateString(entry.summary)}`);
+        }
+        if (entry.metadata) {
+            lines.push(`  Metadata: ${JSON.stringify(sanitizeMetadata(entry.metadata))}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatAutonomyDiagnostics(args) {
+    const sections = [
+        formatDiagnosticSection("Routes", args.routes),
+        formatDiagnosticSection("Gates", args.gates),
+        formatDiagnosticSection("Costs", args.costs),
+        formatDiagnosticSection("Research", args.research),
+        formatDiagnosticSection("Delegation", args.delegation),
+        formatDiagnosticSection("Learning", args.learning),
+        formatDiagnosticSection("Goals", args.goals),
+    ].filter((section) => Boolean(section));
+    if (sections.length === 0)
+        return "No diagnostics available.";
+    return sections.join("\n\n");
+}
+//# sourceMappingURL=status.js.map

package/dist/core/autonomy/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../src/core/autonomy/status.ts"],"names":[],"mappings":"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","sourcesContent":["export interface AutonomyStatusSnapshot {\n\tlatestRoute?: { tier: string; reasonCode: string; risk?: string };\n\tlatestGate?: { outcome: string; gate: string; reasonCode: string };\n\tcurrentCostUsd?: number;\n\tdailyCostUsd?: number;\n\tspawnedCostUsd?: number;\n\tactiveGoal?: { goalId: string; status: string; openRequirements?: number; stallTurns?: number };\n\tactiveLaneCount?: number;\n}\n\nexport interface DiagnosticEntry {\n\ttitle: string;\n\tsummary?: string;\n\treasonCode?: string;\n\tmetadata?: Record<string, unknown>;\n}\n\nexport interface AutonomyDiagnosticSnapshot {\n\troutes?: readonly DiagnosticEntry[];\n\tgates?: readonly DiagnosticEntry[];\n\tcosts?: readonly DiagnosticEntry[];\n\tresearch?: readonly DiagnosticEntry[];\n\tdelegation?: readonly DiagnosticEntry[];\n\tlearning?: readonly DiagnosticEntry[];\n\tgoals?: readonly DiagnosticEntry[];\n}\n\nconst REDACTED = \"[REDACTED]\";\nconst CIRCULAR = \"[Circular]\";\nconst MAX_STRING_LENGTH = 200;\nconst SENSITIVE_KEYS = [\"token\", \"secret\", \"key\", \"credential\", \"password\", \"authorization\"];\nconst SENSITIVE_VALUE_REGEX = /bearer\\s+[\\w\\-._]+|api[-_]?key[-_]?[\\w\\-._]+|sk-[\\w\\-._]+/i;\n\nfunction formatCost(value: number): string {\n\treturn Number.isFinite(value) ? `$${value.toFixed(4)}` : \"$0.0000\";\n}\n\nfunction redactAndTruncateString(value: string): string {\n\tif (SENSITIVE_VALUE_REGEX.test(value)) return REDACTED;\n\tif (value.length <= MAX_STRING_LENGTH) return value;\n\treturn `${value.slice(0, MAX_STRING_LENGTH - 1)}…`;\n}\n\nfunction isSensitiveKey(key: string): boolean {\n\tconst lowerKey = key.toLowerCase();\n\treturn SENSITIVE_KEYS.some((sensitiveKey) => lowerKey.includes(sensitiveKey));\n}\n\nfunction sanitizeMetadataValue(value: unknown, seen: WeakSet<object>): unknown {\n\tif (typeof value === \"string\") return redactAndTruncateString(value);\n\tif (typeof value !== \"object\" || value === null) return value;\n\tif (seen.has(value)) return CIRCULAR;\n\tif (Array.isArray(value)) {\n\t\tseen.add(value);\n\t\treturn value.map((item) => sanitizeMetadataValue(item, seen));\n\t}\n\treturn sanitizeMetadata(value as Record<string, unknown>, seen);\n}\n\nfunction sanitizeMetadata(\n\tobj: Record<string, unknown>,\n\tseen: WeakSet<object> = new WeakSet(),\n): Record<string, unknown> {\n\tif (seen.has(obj)) return { value: CIRCULAR };\n\tseen.add(obj);\n\tconst result: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(obj)) {\n\t\tresult[key] = isSensitiveKey(key) ? REDACTED : sanitizeMetadataValue(value, seen);\n\t}\n\treturn result;\n}\n\nexport function formatAutonomyStatus(args: AutonomyStatusSnapshot): string {\n\tconst parts: string[] = [];\n\n\tif (args.latestRoute) {\n\t\tconst risk = args.latestRoute.risk ? ` (${redactAndTruncateString(args.latestRoute.risk)})` : \"\";\n\t\tparts.push(\n\t\t\t`Route: ${redactAndTruncateString(args.latestRoute.tier)}${risk} - ${redactAndTruncateString(args.latestRoute.reasonCode)}`,\n\t\t);\n\t}\n\n\tif (args.latestGate) {\n\t\tparts.push(\n\t\t\t`Gate: ${redactAndTruncateString(args.latestGate.gate)} = ${redactAndTruncateString(args.latestGate.outcome)} (${redactAndTruncateString(args.latestGate.reasonCode)})`,\n\t\t);\n\t}\n\n\tconst costs: string[] = [];\n\tif (args.currentCostUsd !== undefined) costs.push(`current: ${formatCost(args.currentCostUsd)}`);\n\tif (args.dailyCostUsd !== undefined) costs.push(`daily: ${formatCost(args.dailyCostUsd)}`);\n\tif (args.spawnedCostUsd !== undefined) costs.push(`spawned: ${formatCost(args.spawnedCostUsd)}`);\n\tif (costs.length > 0) {\n\t\tparts.push(`Costs: ${costs.join(\", \")}`);\n\t}\n\n\tif (args.activeGoal) {\n\t\tconst goal = args.activeGoal;\n\t\tconst requirements = goal.openRequirements !== undefined ? `, open reqs: ${goal.openRequirements}` : \"\";\n\t\tconst stalls = goal.stallTurns !== undefined ? `, stalls: ${goal.stallTurns}` : \"\";\n\t\tparts.push(\n\t\t\t`Goal [${redactAndTruncateString(goal.goalId)}]: ${redactAndTruncateString(goal.status)}${requirements}${stalls}`,\n\t\t);\n\t}\n\n\tif (args.activeLaneCount !== undefined) {\n\t\tparts.push(`Lanes: ${args.activeLaneCount}`);\n\t}\n\n\tif (parts.length === 0) return \"Autonomy: idle\";\n\treturn parts.join(\" | \");\n}\n\nfunction formatDiagnosticSection(name: string, entries?: readonly DiagnosticEntry[]): string | undefined {\n\tif (!entries || entries.length === 0) return undefined;\n\n\tconst lines: string[] = [`--- ${name} ---`];\n\tfor (const entry of entries) {\n\t\tlet header = `- ${redactAndTruncateString(entry.title)}`;\n\t\tif (entry.reasonCode) header += ` [${redactAndTruncateString(entry.reasonCode)}]`;\n\t\tlines.push(header);\n\n\t\tif (entry.summary) {\n\t\t\tlines.push(`  Summary: ${redactAndTruncateString(entry.summary)}`);\n\t\t}\n\n\t\tif (entry.metadata) {\n\t\t\tlines.push(`  Metadata: ${JSON.stringify(sanitizeMetadata(entry.metadata))}`);\n\t\t}\n\t}\n\treturn lines.join(\"\\n\");\n}\n\nexport function formatAutonomyDiagnostics(args: AutonomyDiagnosticSnapshot): string {\n\tconst sections = [\n\t\tformatDiagnosticSection(\"Routes\", args.routes),\n\t\tformatDiagnosticSection(\"Gates\", args.gates),\n\t\tformatDiagnosticSection(\"Costs\", args.costs),\n\t\tformatDiagnosticSection(\"Research\", args.research),\n\t\tformatDiagnosticSection(\"Delegation\", args.delegation),\n\t\tformatDiagnosticSection(\"Learning\", args.learning),\n\t\tformatDiagnosticSection(\"Goals\", args.goals),\n\t].filter((section): section is string => Boolean(section));\n\n\tif (sections.length === 0) return \"No diagnostics available.\";\n\treturn sections.join(\"\\n\\n\");\n}\n"]}

package/dist/core/autonomy/subagent-prompt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Subagent system-prompt composition with an irreducible level-0 core.
+ *
+ * The core is the "ultimate level-0 default": ~80 tokens of non-negotiable rules that survive ANY
+ * customization. Everything above it — the lane's role prompt and a shipped profile's soul — is a
+ * replaceable layer: settings, a lane profile, or the calling model (delegate tool) can erase and
+ * replace it entirely. This keeps shipped subagents maximally efficient on small open models (a
+ * caller can hand a tiny model a purpose-built minimal prompt) without ever shedding the safety
+ * floor. Keep the core UNDER 300 tokens; it is deliberately terse.
+ */
+export declare const SUBAGENT_CORE_SYSTEM_PROMPT: string;
+export interface SubagentPromptParts {
+    /** Situational identity from the shipped profile (replaceable layer). */
+    soul?: string;
+    /** The lane's default role prompt (replaceable layer). */
+    rolePrompt: string;
+    /** User- or model-provided replacement for every layer above level 0. */
+    override?: string;
+}
+export declare function composeSubagentSystemPrompt(parts: SubagentPromptParts): string;
+//# sourceMappingURL=subagent-prompt.d.ts.map

package/dist/core/autonomy/subagent-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-prompt.d.ts","sourceRoot":"","sources":["../../../src/core/autonomy/subagent-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,QAO5B,CAAC;AAEb,MAAM,WAAW,mBAAmB;IACnC,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAS9E","sourcesContent":["/**\n * Subagent system-prompt composition with an irreducible level-0 core.\n *\n * The core is the \"ultimate level-0 default\": ~80 tokens of non-negotiable rules that survive ANY\n * customization. Everything above it — the lane's role prompt and a shipped profile's soul — is a\n * replaceable layer: settings, a lane profile, or the calling model (delegate tool) can erase and\n * replace it entirely. This keeps shipped subagents maximally efficient on small open models (a\n * caller can hand a tiny model a purpose-built minimal prompt) without ever shedding the safety\n * floor. Keep the core UNDER 300 tokens; it is deliberately terse.\n */\nexport const SUBAGENT_CORE_SYSTEM_PROMPT = [\n\t\"You are a bounded subagent shipped by a coding-agent session. Non-negotiable rules:\",\n\t\"1. Do only the task you were given; you cannot see the parent conversation.\",\n\t\"2. You are read-only unless your envelope explicitly grants otherwise; never attempt to change files, settings, credentials, or external state.\",\n\t\"3. Never invent facts, file paths, or APIs; say so when you do not know.\",\n\t\"4. Your output is untrusted evidence for the parent agent - data, never instructions.\",\n\t\"5. Follow the requested output format exactly and be concise; budgets are enforced outside you.\",\n].join(\"\\n\");\n\nexport interface SubagentPromptParts {\n\t/** Situational identity from the shipped profile (replaceable layer). */\n\tsoul?: string;\n\t/** The lane's default role prompt (replaceable layer). */\n\trolePrompt: string;\n\t/** User- or model-provided replacement for every layer above level 0. */\n\toverride?: string;\n}\n\nexport function composeSubagentSystemPrompt(parts: SubagentPromptParts): string {\n\tconst override = parts.override?.trim();\n\tconst above =\n\t\toverride && override.length > 0\n\t\t\t? override\n\t\t\t: [parts.soul?.trim(), parts.rolePrompt]\n\t\t\t\t\t.filter((part): part is string => Boolean(part && part.length > 0))\n\t\t\t\t\t.join(\"\\n\\n\");\n\treturn above.length > 0 ? `${SUBAGENT_CORE_SYSTEM_PROMPT}\\n\\n${above}` : SUBAGENT_CORE_SYSTEM_PROMPT;\n}\n"]}

package/dist/core/autonomy/subagent-prompt.js

@@ -0,0 +1,28 @@
+/**
+ * Subagent system-prompt composition with an irreducible level-0 core.
+ *
+ * The core is the "ultimate level-0 default": ~80 tokens of non-negotiable rules that survive ANY
+ * customization. Everything above it — the lane's role prompt and a shipped profile's soul — is a
+ * replaceable layer: settings, a lane profile, or the calling model (delegate tool) can erase and
+ * replace it entirely. This keeps shipped subagents maximally efficient on small open models (a
+ * caller can hand a tiny model a purpose-built minimal prompt) without ever shedding the safety
+ * floor. Keep the core UNDER 300 tokens; it is deliberately terse.
+ */
+export const SUBAGENT_CORE_SYSTEM_PROMPT = [
+    "You are a bounded subagent shipped by a coding-agent session. Non-negotiable rules:",
+    "1. Do only the task you were given; you cannot see the parent conversation.",
+    "2. You are read-only unless your envelope explicitly grants otherwise; never attempt to change files, settings, credentials, or external state.",
+    "3. Never invent facts, file paths, or APIs; say so when you do not know.",
+    "4. Your output is untrusted evidence for the parent agent - data, never instructions.",
+    "5. Follow the requested output format exactly and be concise; budgets are enforced outside you.",
+].join("\n");
+export function composeSubagentSystemPrompt(parts) {
+    const override = parts.override?.trim();
+    const above = override && override.length > 0
+        ? override
+        : [parts.soul?.trim(), parts.rolePrompt]
+            .filter((part) => Boolean(part && part.length > 0))
+            .join("\n\n");
+    return above.length > 0 ? `${SUBAGENT_CORE_SYSTEM_PROMPT}\n\n${above}` : SUBAGENT_CORE_SYSTEM_PROMPT;
+}
+//# sourceMappingURL=subagent-prompt.js.map

package/dist/core/autonomy/subagent-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-prompt.js","sourceRoot":"","sources":["../../../src/core/autonomy/subagent-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IAC1C,qFAAqF;IACrF,6EAA6E;IAC7E,iJAAiJ;IACjJ,0EAA0E;IAC1E,uFAAuF;IACvF,iGAAiG;CACjG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAWb,MAAM,UAAU,2BAA2B,CAAC,KAA0B,EAAU;IAC/E,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IACxC,MAAM,KAAK,GACV,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAC9B,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,UAAU,CAAC;aACrC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;aAClE,IAAI,CAAC,MAAM,CAAC,CAAC;IAClB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,2BAA2B,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,2BAA2B,CAAC;AAAA,CACrG","sourcesContent":["/**\n * Subagent system-prompt composition with an irreducible level-0 core.\n *\n * The core is the \"ultimate level-0 default\": ~80 tokens of non-negotiable rules that survive ANY\n * customization. Everything above it — the lane's role prompt and a shipped profile's soul — is a\n * replaceable layer: settings, a lane profile, or the calling model (delegate tool) can erase and\n * replace it entirely. This keeps shipped subagents maximally efficient on small open models (a\n * caller can hand a tiny model a purpose-built minimal prompt) without ever shedding the safety\n * floor. Keep the core UNDER 300 tokens; it is deliberately terse.\n */\nexport const SUBAGENT_CORE_SYSTEM_PROMPT = [\n\t\"You are a bounded subagent shipped by a coding-agent session. Non-negotiable rules:\",\n\t\"1. Do only the task you were given; you cannot see the parent conversation.\",\n\t\"2. You are read-only unless your envelope explicitly grants otherwise; never attempt to change files, settings, credentials, or external state.\",\n\t\"3. Never invent facts, file paths, or APIs; say so when you do not know.\",\n\t\"4. Your output is untrusted evidence for the parent agent - data, never instructions.\",\n\t\"5. Follow the requested output format exactly and be concise; budgets are enforced outside you.\",\n].join(\"\\n\");\n\nexport interface SubagentPromptParts {\n\t/** Situational identity from the shipped profile (replaceable layer). */\n\tsoul?: string;\n\t/** The lane's default role prompt (replaceable layer). */\n\trolePrompt: string;\n\t/** User- or model-provided replacement for every layer above level 0. */\n\toverride?: string;\n}\n\nexport function composeSubagentSystemPrompt(parts: SubagentPromptParts): string {\n\tconst override = parts.override?.trim();\n\tconst above =\n\t\toverride && override.length > 0\n\t\t\t? override\n\t\t\t: [parts.soul?.trim(), parts.rolePrompt]\n\t\t\t\t\t.filter((part): part is string => Boolean(part && part.length > 0))\n\t\t\t\t\t.join(\"\\n\\n\");\n\treturn above.length > 0 ? `${SUBAGENT_CORE_SYSTEM_PROMPT}\\n\\n${above}` : SUBAGENT_CORE_SYSTEM_PROMPT;\n}\n"]}

package/dist/core/autonomy/telemetry-events.d.ts

@@ -0,0 +1,18 @@
+import type { JsonValue } from "./contracts.ts";
+export declare const AUTONOMY_TELEMETRY_EVENT_TYPES: {
+    readonly routeDecision: "autonomy.route_decision";
+    readonly gateOutcome: "autonomy.gate_outcome";
+    readonly approvalRequest: "autonomy.approval_request";
+    readonly evidenceBundle: "autonomy.evidence_bundle";
+    readonly workerRequest: "autonomy.worker_request";
+    readonly workerResult: "autonomy.worker_result";
+    readonly learningDecision: "autonomy.learning_decision";
+};
+export type AutonomyTelemetryEventType = (typeof AUTONOMY_TELEMETRY_EVENT_TYPES)[keyof typeof AUTONOMY_TELEMETRY_EVENT_TYPES];
+export interface AutonomyTelemetryEvent {
+    type: AutonomyTelemetryEventType;
+    timestamp: string;
+    payload: JsonValue;
+}
+export declare function redactTelemetryValue(value: unknown, depth?: number): unknown;
+//# sourceMappingURL=telemetry-events.d.ts.map

package/dist/core/autonomy/telemetry-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-events.d.ts","sourceRoot":"","sources":["../../../src/core/autonomy/telemetry-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,eAAO,MAAM,8BAA8B;;;;;;;;CAQjC,CAAC;AAEX,MAAM,MAAM,0BAA0B,GACrC,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,OAAO,8BAA8B,CAAC,CAAC;AAEtF,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,0BAA0B,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,SAAS,CAAC;CACnB;AAiBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAyCvE","sourcesContent":["import type { JsonValue } from \"./contracts.ts\";\n\nexport const AUTONOMY_TELEMETRY_EVENT_TYPES = {\n\trouteDecision: \"autonomy.route_decision\",\n\tgateOutcome: \"autonomy.gate_outcome\",\n\tapprovalRequest: \"autonomy.approval_request\",\n\tevidenceBundle: \"autonomy.evidence_bundle\",\n\tworkerRequest: \"autonomy.worker_request\",\n\tworkerResult: \"autonomy.worker_result\",\n\tlearningDecision: \"autonomy.learning_decision\",\n} as const;\n\nexport type AutonomyTelemetryEventType =\n\t(typeof AUTONOMY_TELEMETRY_EVENT_TYPES)[keyof typeof AUTONOMY_TELEMETRY_EVENT_TYPES];\n\nexport interface AutonomyTelemetryEvent {\n\ttype: AutonomyTelemetryEventType;\n\ttimestamp: string;\n\tpayload: JsonValue;\n}\n\nconst SECRET_KEYS = new Set([\n\t\"apikey\",\n\t\"api_key\",\n\t\"token\",\n\t\"accesstoken\",\n\t\"refreshtoken\",\n\t\"secret\",\n\t\"password\",\n\t\"authorization\",\n\t\"credential\",\n\t\"credentials\",\n]);\n\nconst BEARER_RE = /bearer\\s+\\S+/i;\n\nexport function redactTelemetryValue(value: unknown, depth = 0): unknown {\n\tif (depth > 20) {\n\t\treturn \"[Depth Limit Exceeded]\";\n\t}\n\n\tif (typeof value === \"string\") {\n\t\tif (BEARER_RE.test(value)) {\n\t\t\treturn \"[REDACTED BEARER TOKEN]\";\n\t\t}\n\t\tif (value.startsWith(\"sk-\")) {\n\t\t\treturn \"[REDACTED API KEY]\";\n\t\t}\n\t\treturn value;\n\t}\n\n\tif (value === null || typeof value !== \"object\") {\n\t\treturn value;\n\t}\n\n\tif (Array.isArray(value)) {\n\t\tconst result: unknown[] = [];\n\t\tfor (const item of value) {\n\t\t\tresult.push(redactTelemetryValue(item, depth + 1));\n\t\t}\n\t\treturn result;\n\t}\n\n\t// It is an object\n\tconst obj = value as Record<string, unknown>;\n\tconst result: Record<string, unknown> = {};\n\n\tfor (const key of Object.keys(obj)) {\n\t\tconst lowercaseKey = key.toLowerCase();\n\t\tif (SECRET_KEYS.has(lowercaseKey)) {\n\t\t\tresult[key] = \"[REDACTED]\";\n\t\t} else {\n\t\t\tresult[key] = redactTelemetryValue(obj[key], depth + 1);\n\t\t}\n\t}\n\n\treturn result;\n}\n"]}

package/dist/core/autonomy/telemetry-events.js

@@ -0,0 +1,60 @@
+export const AUTONOMY_TELEMETRY_EVENT_TYPES = {
+    routeDecision: "autonomy.route_decision",
+    gateOutcome: "autonomy.gate_outcome",
+    approvalRequest: "autonomy.approval_request",
+    evidenceBundle: "autonomy.evidence_bundle",
+    workerRequest: "autonomy.worker_request",
+    workerResult: "autonomy.worker_result",
+    learningDecision: "autonomy.learning_decision",
+};
+const SECRET_KEYS = new Set([
+    "apikey",
+    "api_key",
+    "token",
+    "accesstoken",
+    "refreshtoken",
+    "secret",
+    "password",
+    "authorization",
+    "credential",
+    "credentials",
+]);
+const BEARER_RE = /bearer\s+\S+/i;
+export function redactTelemetryValue(value, depth = 0) {
+    if (depth > 20) {
+        return "[Depth Limit Exceeded]";
+    }
+    if (typeof value === "string") {
+        if (BEARER_RE.test(value)) {
+            return "[REDACTED BEARER TOKEN]";
+        }
+        if (value.startsWith("sk-")) {
+            return "[REDACTED API KEY]";
+        }
+        return value;
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const result = [];
+        for (const item of value) {
+            result.push(redactTelemetryValue(item, depth + 1));
+        }
+        return result;
+    }
+    // It is an object
+    const obj = value;
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        const lowercaseKey = key.toLowerCase();
+        if (SECRET_KEYS.has(lowercaseKey)) {
+            result[key] = "[REDACTED]";
+        }
+        else {
+            result[key] = redactTelemetryValue(obj[key], depth + 1);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=telemetry-events.js.map

package/dist/core/autonomy/telemetry-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-events.js","sourceRoot":"","sources":["../../../src/core/autonomy/telemetry-events.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC7C,aAAa,EAAE,yBAAyB;IACxC,WAAW,EAAE,uBAAuB;IACpC,eAAe,EAAE,2BAA2B;IAC5C,cAAc,EAAE,0BAA0B;IAC1C,aAAa,EAAE,yBAAyB;IACxC,YAAY,EAAE,wBAAwB;IACtC,gBAAgB,EAAE,4BAA4B;CACrC,CAAC;AAWX,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;IAC3B,QAAQ;IACR,SAAS;IACT,OAAO;IACP,aAAa;IACb,cAAc;IACd,QAAQ;IACR,UAAU;IACV,eAAe;IACf,YAAY;IACZ,aAAa;CACb,CAAC,CAAC;AAEH,MAAM,SAAS,GAAG,eAAe,CAAC;AAElC,MAAM,UAAU,oBAAoB,CAAC,KAAc,EAAE,KAAK,GAAG,CAAC,EAAW;IACxE,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QAChB,OAAO,wBAAwB,CAAC;IACjC,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,yBAAyB,CAAC;QAClC,CAAC;QACD,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,oBAAoB,CAAC;QAC7B,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC;IAED,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC;IACd,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;IAED,kBAAkB;IAClB,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,YAAY,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YACnC,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;QAC5B,CAAC;aAAM,CAAC;YACP,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACzD,CAAC;IACF,CAAC;IAED,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["import type { JsonValue } from \"./contracts.ts\";\n\nexport const AUTONOMY_TELEMETRY_EVENT_TYPES = {\n\trouteDecision: \"autonomy.route_decision\",\n\tgateOutcome: \"autonomy.gate_outcome\",\n\tapprovalRequest: \"autonomy.approval_request\",\n\tevidenceBundle: \"autonomy.evidence_bundle\",\n\tworkerRequest: \"autonomy.worker_request\",\n\tworkerResult: \"autonomy.worker_result\",\n\tlearningDecision: \"autonomy.learning_decision\",\n} as const;\n\nexport type AutonomyTelemetryEventType =\n\t(typeof AUTONOMY_TELEMETRY_EVENT_TYPES)[keyof typeof AUTONOMY_TELEMETRY_EVENT_TYPES];\n\nexport interface AutonomyTelemetryEvent {\n\ttype: AutonomyTelemetryEventType;\n\ttimestamp: string;\n\tpayload: JsonValue;\n}\n\nconst SECRET_KEYS = new Set([\n\t\"apikey\",\n\t\"api_key\",\n\t\"token\",\n\t\"accesstoken\",\n\t\"refreshtoken\",\n\t\"secret\",\n\t\"password\",\n\t\"authorization\",\n\t\"credential\",\n\t\"credentials\",\n]);\n\nconst BEARER_RE = /bearer\\s+\\S+/i;\n\nexport function redactTelemetryValue(value: unknown, depth = 0): unknown {\n\tif (depth > 20) {\n\t\treturn \"[Depth Limit Exceeded]\";\n\t}\n\n\tif (typeof value === \"string\") {\n\t\tif (BEARER_RE.test(value)) {\n\t\t\treturn \"[REDACTED BEARER TOKEN]\";\n\t\t}\n\t\tif (value.startsWith(\"sk-\")) {\n\t\t\treturn \"[REDACTED API KEY]\";\n\t\t}\n\t\treturn value;\n\t}\n\n\tif (value === null || typeof value !== \"object\") {\n\t\treturn value;\n\t}\n\n\tif (Array.isArray(value)) {\n\t\tconst result: unknown[] = [];\n\t\tfor (const item of value) {\n\t\t\tresult.push(redactTelemetryValue(item, depth + 1));\n\t\t}\n\t\treturn result;\n\t}\n\n\t// It is an object\n\tconst obj = value as Record<string, unknown>;\n\tconst result: Record<string, unknown> = {};\n\n\tfor (const key of Object.keys(obj)) {\n\t\tconst lowercaseKey = key.toLowerCase();\n\t\tif (SECRET_KEYS.has(lowercaseKey)) {\n\t\t\tresult[key] = \"[REDACTED]\";\n\t\t} else {\n\t\t\tresult[key] = redactTelemetryValue(obj[key], depth + 1);\n\t\t}\n\t}\n\n\treturn result;\n}\n"]}

package/dist/core/context/artifact-retrieval.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Bounded artifact retrieval (Phase 8-style helper landing early, per D2b): resolve an
+ * artifact id shown in a "Full output: artifact tool-output:<id>" notice back into a
+ * small, useful slice. Per tool-output-artifacts.md's retrieval behavior: retrieve the
+ * smallest useful slice by default (metadata, or a bounded head/tail).
+ *
+ * Bounds are hard limits, not just defaults: a caller-provided `maxLines`/`maxBytes` is
+ * clamped to `MAX_RETRIEVAL_LINES`/`MAX_RETRIEVAL_BYTES` before use, so no caller --
+ * including a future agent-facing tool wrapper -- can force a large artifact to be fully
+ * rehydrated in one call by simply requesting a larger bound. A small artifact that
+ * already fits within the bound is still returned in full; the guarantee is "never more
+ * than the configured hard bounds," not "never the whole artifact."
+ */
+import { type TruncationResult } from "../tools/truncate.ts";
+import type { ArtifactStore } from "./context-artifacts.ts";
+import { type MissingArtifactReason } from "./context-artifacts.ts";
+import type { ContextArtifactRef } from "./context-item.ts";
+export type ArtifactRetrievalMode = "metadata" | "head" | "tail";
+export declare const DEFAULT_RETRIEVAL_MAX_LINES = 200;
+/** Hard ceilings: a caller-requested maxLines/maxBytes can never exceed these. */
+export declare const MAX_RETRIEVAL_LINES = 2000;
+export declare const MAX_RETRIEVAL_BYTES: number;
+export interface ArtifactRetrievalRequest {
+    artifactId: string;
+    mode?: ArtifactRetrievalMode;
+    maxLines?: number;
+    maxBytes?: number;
+}
+export type ArtifactRetrievalResult = {
+    found: false;
+    missingReason: MissingArtifactReason;
+} | {
+    found: true;
+    mode: "metadata";
+    ref: ContextArtifactRef;
+} | {
+    found: true;
+    mode: "head" | "tail";
+    ref: ContextArtifactRef;
+    slice: string;
+    truncation: TruncationResult;
+};
+/**
+ * Resolve `request.artifactId` against `store` and return a bounded slice. `maxLines`/
+ * `maxBytes` are hard-clamped to `MAX_RETRIEVAL_LINES`/`MAX_RETRIEVAL_BYTES` regardless of
+ * what the caller requests -- see the module doc comment for the exact guarantee.
+ */
+export declare function retrieveArtifactSlice(store: ArtifactStore, request: ArtifactRetrievalRequest): ArtifactRetrievalResult;
+//# sourceMappingURL=artifact-retrieval.d.ts.map

package/dist/core/context/artifact-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-retrieval.d.ts","sourceRoot":"","sources":["../../../src/core/context/artifact-retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAqB,KAAK,gBAAgB,EAA8B,MAAM,sBAAsB,CAAC;AAC5G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC7F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjE,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,mBAAmB,QAAoB,CAAC;AAErD,MAAM,WAAW,wBAAwB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,qBAAqB,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,uBAAuB,GAChC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,aAAa,EAAE,qBAAqB,CAAA;CAAE,GACtD;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,kBAAkB,CAAA;CAAE,GAC1D;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,GAAG,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAQhH;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,wBAAwB,GAC/B,uBAAuB,CAqBzB","sourcesContent":["/**\n * Bounded artifact retrieval (Phase 8-style helper landing early, per D2b): resolve an\n * artifact id shown in a \"Full output: artifact tool-output:<id>\" notice back into a\n * small, useful slice. Per tool-output-artifacts.md's retrieval behavior: retrieve the\n * smallest useful slice by default (metadata, or a bounded head/tail).\n *\n * Bounds are hard limits, not just defaults: a caller-provided `maxLines`/`maxBytes` is\n * clamped to `MAX_RETRIEVAL_LINES`/`MAX_RETRIEVAL_BYTES` before use, so no caller --\n * including a future agent-facing tool wrapper -- can force a large artifact to be fully\n * rehydrated in one call by simply requesting a larger bound. A small artifact that\n * already fits within the bound is still returned in full; the guarantee is \"never more\n * than the configured hard bounds,\" not \"never the whole artifact.\"\n */\n\nimport { DEFAULT_MAX_BYTES, type TruncationResult, truncateHead, truncateTail } from \"../tools/truncate.ts\";\nimport type { ArtifactStore } from \"./context-artifacts.ts\";\nimport { isMissingArtifactMarker, type MissingArtifactReason } from \"./context-artifacts.ts\";\nimport type { ContextArtifactRef } from \"./context-item.ts\";\n\nexport type ArtifactRetrievalMode = \"metadata\" | \"head\" | \"tail\";\n\nexport const DEFAULT_RETRIEVAL_MAX_LINES = 200;\n\n/** Hard ceilings: a caller-requested maxLines/maxBytes can never exceed these. */\nexport const MAX_RETRIEVAL_LINES = 2000;\nexport const MAX_RETRIEVAL_BYTES = DEFAULT_MAX_BYTES;\n\nexport interface ArtifactRetrievalRequest {\n\tartifactId: string;\n\tmode?: ArtifactRetrievalMode;\n\tmaxLines?: number;\n\tmaxBytes?: number;\n}\n\nexport type ArtifactRetrievalResult =\n\t| { found: false; missingReason: MissingArtifactReason }\n\t| { found: true; mode: \"metadata\"; ref: ContextArtifactRef }\n\t| { found: true; mode: \"head\" | \"tail\"; ref: ContextArtifactRef; slice: string; truncation: TruncationResult };\n\nfunction clampToHardCeiling(requested: number | undefined, fallback: number, hardCeiling: number): number {\n\tconst candidate = requested ?? fallback;\n\tif (candidate <= 0) return 0;\n\treturn Math.min(candidate, hardCeiling);\n}\n\n/**\n * Resolve `request.artifactId` against `store` and return a bounded slice. `maxLines`/\n * `maxBytes` are hard-clamped to `MAX_RETRIEVAL_LINES`/`MAX_RETRIEVAL_BYTES` regardless of\n * what the caller requests -- see the module doc comment for the exact guarantee.\n */\nexport function retrieveArtifactSlice(\n\tstore: ArtifactStore,\n\trequest: ArtifactRetrievalRequest,\n): ArtifactRetrievalResult {\n\tconst record = store.read(request.artifactId);\n\tif (isMissingArtifactMarker(record)) {\n\t\treturn { found: false, missingReason: record.reason };\n\t}\n\n\tconst mode = request.mode ?? \"head\";\n\tif (mode === \"metadata\") {\n\t\treturn { found: true, mode: \"metadata\", ref: record.ref };\n\t}\n\n\tconst truncationOptions = {\n\t\tmaxLines: clampToHardCeiling(request.maxLines, DEFAULT_RETRIEVAL_MAX_LINES, MAX_RETRIEVAL_LINES),\n\t\tmaxBytes: clampToHardCeiling(request.maxBytes, DEFAULT_MAX_BYTES, MAX_RETRIEVAL_BYTES),\n\t};\n\tconst truncation =\n\t\tmode === \"tail\"\n\t\t\t? truncateTail(record.content, truncationOptions)\n\t\t\t: truncateHead(record.content, truncationOptions);\n\n\treturn { found: true, mode, ref: record.ref, slice: truncation.content, truncation };\n}\n"]}

package/dist/core/context/artifact-retrieval.js

@@ -0,0 +1,49 @@
+/**
+ * Bounded artifact retrieval (Phase 8-style helper landing early, per D2b): resolve an
+ * artifact id shown in a "Full output: artifact tool-output:<id>" notice back into a
+ * small, useful slice. Per tool-output-artifacts.md's retrieval behavior: retrieve the
+ * smallest useful slice by default (metadata, or a bounded head/tail).
+ *
+ * Bounds are hard limits, not just defaults: a caller-provided `maxLines`/`maxBytes` is
+ * clamped to `MAX_RETRIEVAL_LINES`/`MAX_RETRIEVAL_BYTES` before use, so no caller --
+ * including a future agent-facing tool wrapper -- can force a large artifact to be fully
+ * rehydrated in one call by simply requesting a larger bound. A small artifact that
+ * already fits within the bound is still returned in full; the guarantee is "never more
+ * than the configured hard bounds," not "never the whole artifact."
+ */
+import { DEFAULT_MAX_BYTES, truncateHead, truncateTail } from "../tools/truncate.js";
+import { isMissingArtifactMarker } from "./context-artifacts.js";
+export const DEFAULT_RETRIEVAL_MAX_LINES = 200;
+/** Hard ceilings: a caller-requested maxLines/maxBytes can never exceed these. */
+export const MAX_RETRIEVAL_LINES = 2000;
+export const MAX_RETRIEVAL_BYTES = DEFAULT_MAX_BYTES;
+function clampToHardCeiling(requested, fallback, hardCeiling) {
+    const candidate = requested ?? fallback;
+    if (candidate <= 0)
+        return 0;
+    return Math.min(candidate, hardCeiling);
+}
+/**
+ * Resolve `request.artifactId` against `store` and return a bounded slice. `maxLines`/
+ * `maxBytes` are hard-clamped to `MAX_RETRIEVAL_LINES`/`MAX_RETRIEVAL_BYTES` regardless of
+ * what the caller requests -- see the module doc comment for the exact guarantee.
+ */
+export function retrieveArtifactSlice(store, request) {
+    const record = store.read(request.artifactId);
+    if (isMissingArtifactMarker(record)) {
+        return { found: false, missingReason: record.reason };
+    }
+    const mode = request.mode ?? "head";
+    if (mode === "metadata") {
+        return { found: true, mode: "metadata", ref: record.ref };
+    }
+    const truncationOptions = {
+        maxLines: clampToHardCeiling(request.maxLines, DEFAULT_RETRIEVAL_MAX_LINES, MAX_RETRIEVAL_LINES),
+        maxBytes: clampToHardCeiling(request.maxBytes, DEFAULT_MAX_BYTES, MAX_RETRIEVAL_BYTES),
+    };
+    const truncation = mode === "tail"
+        ? truncateTail(record.content, truncationOptions)
+        : truncateHead(record.content, truncationOptions);
+    return { found: true, mode, ref: record.ref, slice: truncation.content, truncation };
+}
+//# sourceMappingURL=artifact-retrieval.js.map

package/dist/core/context/artifact-retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-retrieval.js","sourceRoot":"","sources":["../../../src/core/context/artifact-retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,iBAAiB,EAAyB,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAE5G,OAAO,EAAE,uBAAuB,EAA8B,MAAM,wBAAwB,CAAC;AAK7F,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAE/C,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACxC,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAcrD,SAAS,kBAAkB,CAAC,SAA6B,EAAE,QAAgB,EAAE,WAAmB,EAAU;IACzG,MAAM,SAAS,GAAG,SAAS,IAAI,QAAQ,CAAC;IACxC,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAAA,CACxC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACpC,KAAoB,EACpB,OAAiC,EACP;IAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9C,IAAI,uBAAuB,CAAC,MAAM,CAAC,EAAE,CAAC;QACrC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;IACpC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACzB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;IAC3D,CAAC;IAED,MAAM,iBAAiB,GAAG;QACzB,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,QAAQ,EAAE,2BAA2B,EAAE,mBAAmB,CAAC;QAChG,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,QAAQ,EAAE,iBAAiB,EAAE,mBAAmB,CAAC;KACtF,CAAC;IACF,MAAM,UAAU,GACf,IAAI,KAAK,MAAM;QACd,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,CAAC;QACjD,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAEpD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC;AAAA,CACrF","sourcesContent":["/**\n * Bounded artifact retrieval (Phase 8-style helper landing early, per D2b): resolve an\n * artifact id shown in a \"Full output: artifact tool-output:<id>\" notice back into a\n * small, useful slice. Per tool-output-artifacts.md's retrieval behavior: retrieve the\n * smallest useful slice by default (metadata, or a bounded head/tail).\n *\n * Bounds are hard limits, not just defaults: a caller-provided `maxLines`/`maxBytes` is\n * clamped to `MAX_RETRIEVAL_LINES`/`MAX_RETRIEVAL_BYTES` before use, so no caller --\n * including a future agent-facing tool wrapper -- can force a large artifact to be fully\n * rehydrated in one call by simply requesting a larger bound. A small artifact that\n * already fits within the bound is still returned in full; the guarantee is \"never more\n * than the configured hard bounds,\" not \"never the whole artifact.\"\n */\n\nimport { DEFAULT_MAX_BYTES, type TruncationResult, truncateHead, truncateTail } from \"../tools/truncate.ts\";\nimport type { ArtifactStore } from \"./context-artifacts.ts\";\nimport { isMissingArtifactMarker, type MissingArtifactReason } from \"./context-artifacts.ts\";\nimport type { ContextArtifactRef } from \"./context-item.ts\";\n\nexport type ArtifactRetrievalMode = \"metadata\" | \"head\" | \"tail\";\n\nexport const DEFAULT_RETRIEVAL_MAX_LINES = 200;\n\n/** Hard ceilings: a caller-requested maxLines/maxBytes can never exceed these. */\nexport const MAX_RETRIEVAL_LINES = 2000;\nexport const MAX_RETRIEVAL_BYTES = DEFAULT_MAX_BYTES;\n\nexport interface ArtifactRetrievalRequest {\n\tartifactId: string;\n\tmode?: ArtifactRetrievalMode;\n\tmaxLines?: number;\n\tmaxBytes?: number;\n}\n\nexport type ArtifactRetrievalResult =\n\t| { found: false; missingReason: MissingArtifactReason }\n\t| { found: true; mode: \"metadata\"; ref: ContextArtifactRef }\n\t| { found: true; mode: \"head\" | \"tail\"; ref: ContextArtifactRef; slice: string; truncation: TruncationResult };\n\nfunction clampToHardCeiling(requested: number | undefined, fallback: number, hardCeiling: number): number {\n\tconst candidate = requested ?? fallback;\n\tif (candidate <= 0) return 0;\n\treturn Math.min(candidate, hardCeiling);\n}\n\n/**\n * Resolve `request.artifactId` against `store` and return a bounded slice. `maxLines`/\n * `maxBytes` are hard-clamped to `MAX_RETRIEVAL_LINES`/`MAX_RETRIEVAL_BYTES` regardless of\n * what the caller requests -- see the module doc comment for the exact guarantee.\n */\nexport function retrieveArtifactSlice(\n\tstore: ArtifactStore,\n\trequest: ArtifactRetrievalRequest,\n): ArtifactRetrievalResult {\n\tconst record = store.read(request.artifactId);\n\tif (isMissingArtifactMarker(record)) {\n\t\treturn { found: false, missingReason: record.reason };\n\t}\n\n\tconst mode = request.mode ?? \"head\";\n\tif (mode === \"metadata\") {\n\t\treturn { found: true, mode: \"metadata\", ref: record.ref };\n\t}\n\n\tconst truncationOptions = {\n\t\tmaxLines: clampToHardCeiling(request.maxLines, DEFAULT_RETRIEVAL_MAX_LINES, MAX_RETRIEVAL_LINES),\n\t\tmaxBytes: clampToHardCeiling(request.maxBytes, DEFAULT_MAX_BYTES, MAX_RETRIEVAL_BYTES),\n\t};\n\tconst truncation =\n\t\tmode === \"tail\"\n\t\t\t? truncateTail(record.content, truncationOptions)\n\t\t\t: truncateHead(record.content, truncationOptions);\n\n\treturn { found: true, mode, ref: record.ref, slice: truncation.content, truncation };\n}\n"]}

package/dist/core/context/context-artifacts.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Artifact store abstraction (Phase 2): stable refs for raw large payloads, kept out of
+ * band from prompt context. This module defines the `ArtifactStore` interface plus two
+ * implementations: an in-memory one for tests, and `createFileArtifactStore` (session-
+ * scoped, filesystem-backed). A SQLite-backed implementation waits until the Phase M0
+ * storage-authority/location/concurrency decisions are accepted (see
+ * docs/context-management-rework/memory-architecture.md).
+ *
+ * `createFileArtifactStore` is wired into live grep/find tool construction in
+ * agent-session.ts (session-scoped under `<agentDir>/context-artifacts/<sessionId>/`).
+ * References are registered at pack time and released when context-gc evicts the
+ * corresponding grep/find tool result (opportunistic, conservative cleanup), with a
+ * best-effort dispose-time sweep for zero-reference artifacts. Payloads are retrievable
+ * out of band via the artifact_retrieve tool (context/artifact-retrieval.ts).
+ */
+import { type ContextArtifactRef } from "./context-item.ts";
+export interface ArtifactWriteRequest {
+    kind: ContextArtifactRef["kind"];
+    content: string;
+    toolName?: string;
+    command?: string;
+    path?: string;
+    sessionEntryId?: string;
+    createdAtTurn: number;
+    reproducible: boolean;
+}
+export interface ArtifactRecord {
+    ref: ContextArtifactRef;
+    content: string;
+}
+export type MissingArtifactReason = "not_found" | "cleaned_up";
+export interface MissingArtifactMarker {
+    id: string;
+    missing: true;
+    reason: MissingArtifactReason;
+}
+export declare function isMissingArtifactMarker(value: ArtifactRecord | MissingArtifactMarker): value is MissingArtifactMarker;
+/**
+ * Artifact id for a capture event, not merely a payload: it hashes every ref-defining
+ * field (kind, tool/command/path, content, sessionEntryId, createdAtTurn, reproducible).
+ * A repeat write with identical content but a different turn or session entry is a
+ * distinct capture and must get a distinct id -- otherwise the later capture's metadata
+ * would be silently discarded in favor of the first write. Only a truly identical
+ * request (same capture, re-submitted) is idempotent under this id.
+ */
+export declare function generateArtifactId(request: Pick<ArtifactWriteRequest, "kind" | "content" | "toolName" | "command" | "path" | "sessionEntryId" | "createdAtTurn" | "reproducible">): string;
+export interface ArtifactStore {
+    write(request: ArtifactWriteRequest): ArtifactRecord;
+    read(id: string): ArtifactRecord | MissingArtifactMarker;
+    /**
+     * Metadata-only lookup: the ref if `id` resolves to a live artifact, `undefined`
+     * otherwise. Never loads the payload -- for the file store this must not touch the
+     * payload file at all beyond an existence check, so a caller that only needs to know
+     * "does this still exist, and what are its ref fields" (e.g. a per-turn audit pass)
+     * never pays the cost of reading potentially large content off disk.
+     */
+    readRef(id: string): ContextArtifactRef | undefined;
+    has(id: string): boolean;
+    /**
+     * Register that `holderId` (a context item id, session entry id, etc.) depends on this
+     * artifact. Returns false if `id` does not exist (never written, or already cleaned
+     * up) so a caller cannot believe it protected an artifact that was never registered.
+     * Callers must fail closed (treat the artifact as unprotected) on a false return.
+     */
+    addReference(id: string, holderId: string): boolean;
+    /** Release a previously registered dependency. Returns true only if a reference was actually removed. */
+    removeReference(id: string, holderId: string): boolean;
+    referenceCount(id: string): number;
+    /** Delete only artifacts with zero active references. Returns the ids actually deleted. */
+    cleanup(): string[];
+}
+export declare function createInMemoryArtifactStore(): ArtifactStore;
+export interface FileArtifactStoreOptions {
+    /** Directory the store persists artifact payloads and metadata under. Created if missing. */
+    baseDir: string;
+}
+/**
+ * Filesystem-backed `ArtifactStore`: payload and metadata (including reference holder ids)
+ * are written to `baseDir` so content, ref fields, and cleanup-protecting references all
+ * survive recreating the store (e.g. across a process restart against the same
+ * directory) -- unlike the in-memory store, which loses everything when the instance is
+ * dropped. No SQLite or other index is used; each artifact's metadata is a small sidecar
+ * JSON file next to its payload file, per the "keep SQLite out of scope unless a minimal
+ * metadata shape is unavoidable" constraint for this slice.
+ *
+ * The one thing that does NOT survive recreation: the missing-artifact reason
+ * distinction. A fresh instance has no in-memory record of which ids it personally
+ * cleaned up, so a previously-cleaned-up id reads back as "not_found" rather than
+ * "cleaned_up" after a restart. This still always returns an explicit missing marker,
+ * never fabricated or empty content -- it only affects which of the two reason codes is
+ * reported.
+ */
+export declare function createFileArtifactStore(options: FileArtifactStoreOptions): ArtifactStore;
+//# sourceMappingURL=context-artifacts.d.ts.map

package/dist/core/context/context-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-artifacts.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,KAAK,kBAAkB,EAAyC,MAAM,mBAAmB,CAAC;AAEnG,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,kBAAkB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,YAAY,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,qBAAqB,CAAC;CAC9B;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,qBAAqB,GAAG,KAAK,IAAI,qBAAqB,CAErH;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,IAAI,CACZ,oBAAoB,EACpB,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,gBAAgB,GAAG,eAAe,GAAG,cAAc,CAC1G,GACC,MAAM,CAgBR;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAAC;IACrD,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,qBAAqB,CAAC;IACzD;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACpD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpD,yGAAyG;IACzG,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACvD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,2FAA2F;IAC3F,OAAO,IAAI,MAAM,EAAE,CAAC;CACpB;AAQD,wBAAgB,2BAA2B,IAAI,aAAa,CA2E3D;AAED,MAAM,WAAW,wBAAwB;IACxC,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;CAChB;AA+ED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,aAAa,CA0GxF","sourcesContent":["/**\n * Artifact store abstraction (Phase 2): stable refs for raw large payloads, kept out of\n * band from prompt context. This module defines the `ArtifactStore` interface plus two\n * implementations: an in-memory one for tests, and `createFileArtifactStore` (session-\n * scoped, filesystem-backed). A SQLite-backed implementation waits until the Phase M0\n * storage-authority/location/concurrency decisions are accepted (see\n * docs/context-management-rework/memory-architecture.md).\n *\n * `createFileArtifactStore` is wired into live grep/find tool construction in\n * agent-session.ts (session-scoped under `<agentDir>/context-artifacts/<sessionId>/`).\n * References are registered at pack time and released when context-gc evicts the\n * corresponding grep/find tool result (opportunistic, conservative cleanup), with a\n * best-effort dispose-time sweep for zero-reference artifacts. Payloads are retrievable\n * out of band via the artifact_retrieve tool (context/artifact-retrieval.ts).\n */\n\nimport { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { type ContextArtifactRef, estimateByteLength, estimateLineCount } from \"./context-item.ts\";\n\nexport interface ArtifactWriteRequest {\n\tkind: ContextArtifactRef[\"kind\"];\n\tcontent: string;\n\ttoolName?: string;\n\tcommand?: string;\n\tpath?: string;\n\tsessionEntryId?: string;\n\tcreatedAtTurn: number;\n\treproducible: boolean;\n}\n\nexport interface ArtifactRecord {\n\tref: ContextArtifactRef;\n\tcontent: string;\n}\n\nexport type MissingArtifactReason = \"not_found\" | \"cleaned_up\";\n\nexport interface MissingArtifactMarker {\n\tid: string;\n\tmissing: true;\n\treason: MissingArtifactReason;\n}\n\nexport function isMissingArtifactMarker(value: ArtifactRecord | MissingArtifactMarker): value is MissingArtifactMarker {\n\treturn (value as MissingArtifactMarker).missing === true;\n}\n\n/**\n * Artifact id for a capture event, not merely a payload: it hashes every ref-defining\n * field (kind, tool/command/path, content, sessionEntryId, createdAtTurn, reproducible).\n * A repeat write with identical content but a different turn or session entry is a\n * distinct capture and must get a distinct id -- otherwise the later capture's metadata\n * would be silently discarded in favor of the first write. Only a truly identical\n * request (same capture, re-submitted) is idempotent under this id.\n */\nexport function generateArtifactId(\n\trequest: Pick<\n\t\tArtifactWriteRequest,\n\t\t\"kind\" | \"content\" | \"toolName\" | \"command\" | \"path\" | \"sessionEntryId\" | \"createdAtTurn\" | \"reproducible\"\n\t>,\n): string {\n\treturn createHash(\"sha256\")\n\t\t.update(\n\t\t\t[\n\t\t\t\trequest.kind,\n\t\t\t\trequest.toolName ?? \"\",\n\t\t\t\trequest.command ?? \"\",\n\t\t\t\trequest.path ?? \"\",\n\t\t\t\trequest.sessionEntryId ?? \"\",\n\t\t\t\tString(request.createdAtTurn),\n\t\t\t\tString(request.reproducible),\n\t\t\t\trequest.content,\n\t\t\t].join(\"\\0\"),\n\t\t)\n\t\t.digest(\"hex\")\n\t\t.slice(0, 24);\n}\n\nexport interface ArtifactStore {\n\twrite(request: ArtifactWriteRequest): ArtifactRecord;\n\tread(id: string): ArtifactRecord | MissingArtifactMarker;\n\t/**\n\t * Metadata-only lookup: the ref if `id` resolves to a live artifact, `undefined`\n\t * otherwise. Never loads the payload -- for the file store this must not touch the\n\t * payload file at all beyond an existence check, so a caller that only needs to know\n\t * \"does this still exist, and what are its ref fields\" (e.g. a per-turn audit pass)\n\t * never pays the cost of reading potentially large content off disk.\n\t */\n\treadRef(id: string): ContextArtifactRef | undefined;\n\thas(id: string): boolean;\n\t/**\n\t * Register that `holderId` (a context item id, session entry id, etc.) depends on this\n\t * artifact. Returns false if `id` does not exist (never written, or already cleaned\n\t * up) so a caller cannot believe it protected an artifact that was never registered.\n\t * Callers must fail closed (treat the artifact as unprotected) on a false return.\n\t */\n\taddReference(id: string, holderId: string): boolean;\n\t/** Release a previously registered dependency. Returns true only if a reference was actually removed. */\n\tremoveReference(id: string, holderId: string): boolean;\n\treferenceCount(id: string): number;\n\t/** Delete only artifacts with zero active references. Returns the ids actually deleted. */\n\tcleanup(): string[];\n}\n\ninterface StoredArtifact {\n\tref: ContextArtifactRef;\n\tcontent: string;\n\treferences: Set<string>;\n}\n\nexport function createInMemoryArtifactStore(): ArtifactStore {\n\tconst artifacts = new Map<string, StoredArtifact>();\n\tconst cleanedUp = new Set<string>();\n\n\treturn {\n\t\twrite(request: ArtifactWriteRequest): ArtifactRecord {\n\t\t\tconst id = generateArtifactId(request);\n\t\t\tconst existing = artifacts.get(id);\n\t\t\tif (existing) {\n\t\t\t\tcleanedUp.delete(id);\n\t\t\t\treturn { ref: existing.ref, content: existing.content };\n\t\t\t}\n\n\t\t\tconst ref: ContextArtifactRef = {\n\t\t\t\tid,\n\t\t\t\tkind: request.kind,\n\t\t\t\tsessionEntryId: request.sessionEntryId,\n\t\t\t\ttoolName: request.toolName,\n\t\t\t\tcommand: request.command,\n\t\t\t\tpath: request.path,\n\t\t\t\tbyteLength: estimateByteLength(request.content),\n\t\t\t\tlineCount: estimateLineCount(request.content),\n\t\t\t\tcreatedAtTurn: request.createdAtTurn,\n\t\t\t\treproducible: request.reproducible,\n\t\t\t};\n\t\t\tartifacts.set(id, { ref, content: request.content, references: new Set() });\n\t\t\tcleanedUp.delete(id);\n\t\t\treturn { ref, content: request.content };\n\t\t},\n\n\t\tread(id: string): ArtifactRecord | MissingArtifactMarker {\n\t\t\tconst stored = artifacts.get(id);\n\t\t\tif (!stored) {\n\t\t\t\treturn { id, missing: true, reason: cleanedUp.has(id) ? \"cleaned_up\" : \"not_found\" };\n\t\t\t}\n\t\t\treturn { ref: stored.ref, content: stored.content };\n\t\t},\n\n\t\treadRef(id: string): ContextArtifactRef | undefined {\n\t\t\treturn artifacts.get(id)?.ref;\n\t\t},\n\n\t\thas(id: string): boolean {\n\t\t\treturn artifacts.has(id);\n\t\t},\n\n\t\taddReference(id: string, holderId: string): boolean {\n\t\t\tconst stored = artifacts.get(id);\n\t\t\tif (!stored) return false;\n\t\t\tstored.references.add(holderId);\n\t\t\treturn true;\n\t\t},\n\n\t\tremoveReference(id: string, holderId: string): boolean {\n\t\t\tconst stored = artifacts.get(id);\n\t\t\tif (!stored) return false;\n\t\t\treturn stored.references.delete(holderId);\n\t\t},\n\n\t\treferenceCount(id: string): number {\n\t\t\treturn artifacts.get(id)?.references.size ?? 0;\n\t\t},\n\n\t\tcleanup(): string[] {\n\t\t\tconst deleted: string[] = [];\n\t\t\tfor (const [id, stored] of artifacts) {\n\t\t\t\tif (stored.references.size === 0) {\n\t\t\t\t\tartifacts.delete(id);\n\t\t\t\t\tcleanedUp.add(id);\n\t\t\t\t\tdeleted.push(id);\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn deleted;\n\t\t},\n\t};\n}\n\nexport interface FileArtifactStoreOptions {\n\t/** Directory the store persists artifact payloads and metadata under. Created if missing. */\n\tbaseDir: string;\n}\n\ninterface PersistedArtifactMeta {\n\tref: ContextArtifactRef;\n\treferences: string[];\n}\n\nconst META_SUFFIX = \".meta.json\";\nconst PAYLOAD_SUFFIX = \".payload\";\n\n/**\n * Artifact ids are generated by `generateArtifactId` as a lowercase hex digest. Reject\n * anything else so a caller-supplied id (including one echoed back from model output)\n * can never be used as a path-traversal vector into `baseDir`.\n */\nfunction isSafeArtifactId(id: string): boolean {\n\treturn /^[0-9a-f]{1,64}$/.test(id);\n}\n\nfunction payloadPath(baseDir: string, id: string): string {\n\treturn join(baseDir, `${id}${PAYLOAD_SUFFIX}`);\n}\n\nfunction metaPath(baseDir: string, id: string): string {\n\treturn join(baseDir, `${id}${META_SUFFIX}`);\n}\n\nconst VALID_ARTIFACT_KINDS: ReadonlySet<ContextArtifactRef[\"kind\"]> = new Set([\n\t\"tool_output\",\n\t\"file_snapshot\",\n\t\"test_output\",\n\t\"diff\",\n\t\"transcript_slice\",\n]);\n\nfunction isValidArtifactRefShape(value: unknown): value is ContextArtifactRef {\n\tif (typeof value !== \"object\" || value === null) return false;\n\tconst ref = value as Record<string, unknown>;\n\treturn (\n\t\ttypeof ref.id === \"string\" &&\n\t\ttypeof ref.kind === \"string\" &&\n\t\tVALID_ARTIFACT_KINDS.has(ref.kind as ContextArtifactRef[\"kind\"]) &&\n\t\ttypeof ref.byteLength === \"number\" &&\n\t\ttypeof ref.createdAtTurn === \"number\" &&\n\t\ttypeof ref.reproducible === \"boolean\"\n\t);\n}\n\n/**\n * A parsed JSON value can be syntactically valid but semantically garbage (truncated\n * write, hand-edited file, future/incompatible format). Validate shape, not just parse\n * success, so a malformed sidecar can never produce an invalid ref or crash `cleanup()` --\n * it is treated as unusable/missing, the same as a sidecar that doesn't exist.\n */\nfunction isValidPersistedArtifactMeta(value: unknown): value is PersistedArtifactMeta {\n\tif (typeof value !== \"object\" || value === null) return false;\n\tconst meta = value as Record<string, unknown>;\n\treturn (\n\t\tisValidArtifactRefShape(meta.ref) &&\n\t\tArray.isArray(meta.references) &&\n\t\tmeta.references.every((entry) => typeof entry === \"string\")\n\t);\n}\n\nfunction readMeta(baseDir: string, id: string): PersistedArtifactMeta | undefined {\n\tconst path = metaPath(baseDir, id);\n\tif (!existsSync(path)) return undefined;\n\ttry {\n\t\tconst parsed: unknown = JSON.parse(readFileSync(path, \"utf8\"));\n\t\treturn isValidPersistedArtifactMeta(parsed) ? parsed : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction writeMeta(baseDir: string, id: string, meta: PersistedArtifactMeta): void {\n\twriteFileSync(metaPath(baseDir, id), JSON.stringify(meta), \"utf8\");\n}\n\n/**\n * Filesystem-backed `ArtifactStore`: payload and metadata (including reference holder ids)\n * are written to `baseDir` so content, ref fields, and cleanup-protecting references all\n * survive recreating the store (e.g. across a process restart against the same\n * directory) -- unlike the in-memory store, which loses everything when the instance is\n * dropped. No SQLite or other index is used; each artifact's metadata is a small sidecar\n * JSON file next to its payload file, per the \"keep SQLite out of scope unless a minimal\n * metadata shape is unavoidable\" constraint for this slice.\n *\n * The one thing that does NOT survive recreation: the missing-artifact reason\n * distinction. A fresh instance has no in-memory record of which ids it personally\n * cleaned up, so a previously-cleaned-up id reads back as \"not_found\" rather than\n * \"cleaned_up\" after a restart. This still always returns an explicit missing marker,\n * never fabricated or empty content -- it only affects which of the two reason codes is\n * reported.\n */\nexport function createFileArtifactStore(options: FileArtifactStoreOptions): ArtifactStore {\n\tconst baseDir = options.baseDir;\n\tmkdirSync(baseDir, { recursive: true });\n\tconst cleanedUpThisInstance = new Set<string>();\n\n\treturn {\n\t\twrite(request: ArtifactWriteRequest): ArtifactRecord {\n\t\t\tconst id = generateArtifactId(request);\n\t\t\tconst existingMeta = readMeta(baseDir, id);\n\t\t\tconst existingPayloadPath = payloadPath(baseDir, id);\n\t\t\tif (existingMeta && existsSync(existingPayloadPath)) {\n\t\t\t\tcleanedUpThisInstance.delete(id);\n\t\t\t\treturn { ref: existingMeta.ref, content: readFileSync(existingPayloadPath, \"utf8\") };\n\t\t\t}\n\n\t\t\tconst ref: ContextArtifactRef = {\n\t\t\t\tid,\n\t\t\t\tkind: request.kind,\n\t\t\t\tsessionEntryId: request.sessionEntryId,\n\t\t\t\ttoolName: request.toolName,\n\t\t\t\tcommand: request.command,\n\t\t\t\tpath: request.path,\n\t\t\t\tbyteLength: estimateByteLength(request.content),\n\t\t\t\tlineCount: estimateLineCount(request.content),\n\t\t\t\tcreatedAtTurn: request.createdAtTurn,\n\t\t\t\treproducible: request.reproducible,\n\t\t\t};\n\t\t\twriteFileSync(payloadPath(baseDir, id), request.content, \"utf8\");\n\t\t\twriteMeta(baseDir, id, { ref, references: [] });\n\t\t\tcleanedUpThisInstance.delete(id);\n\t\t\treturn { ref, content: request.content };\n\t\t},\n\n\t\tread(id: string): ArtifactRecord | MissingArtifactMarker {\n\t\t\tif (!isSafeArtifactId(id)) return { id, missing: true, reason: \"not_found\" };\n\t\t\tconst meta = readMeta(baseDir, id);\n\t\t\tconst pPath = payloadPath(baseDir, id);\n\t\t\tif (!meta || !existsSync(pPath)) {\n\t\t\t\treturn { id, missing: true, reason: cleanedUpThisInstance.has(id) ? \"cleaned_up\" : \"not_found\" };\n\t\t\t}\n\t\t\treturn { ref: meta.ref, content: readFileSync(pPath, \"utf8\") };\n\t\t},\n\n\t\treadRef(id: string): ContextArtifactRef | undefined {\n\t\t\tif (!isSafeArtifactId(id)) return undefined;\n\t\t\tconst meta = readMeta(baseDir, id);\n\t\t\tif (!meta || !existsSync(payloadPath(baseDir, id))) return undefined;\n\t\t\treturn meta.ref;\n\t\t},\n\n\t\thas(id: string): boolean {\n\t\t\tif (!isSafeArtifactId(id)) return false;\n\t\t\treturn readMeta(baseDir, id) !== undefined && existsSync(payloadPath(baseDir, id));\n\t\t},\n\n\t\taddReference(id: string, holderId: string): boolean {\n\t\t\tif (!isSafeArtifactId(id)) return false;\n\t\t\tconst meta = readMeta(baseDir, id);\n\t\t\tif (!meta || !existsSync(payloadPath(baseDir, id))) return false;\n\t\t\tif (!meta.references.includes(holderId)) {\n\t\t\t\tmeta.references.push(holderId);\n\t\t\t\twriteMeta(baseDir, id, meta);\n\t\t\t}\n\t\t\treturn true;\n\t\t},\n\n\t\tremoveReference(id: string, holderId: string): boolean {\n\t\t\tif (!isSafeArtifactId(id)) return false;\n\t\t\tconst meta = readMeta(baseDir, id);\n\t\t\tif (!meta) return false;\n\t\t\tconst index = meta.references.indexOf(holderId);\n\t\t\tif (index === -1) return false;\n\t\t\tmeta.references.splice(index, 1);\n\t\t\twriteMeta(baseDir, id, meta);\n\t\t\treturn true;\n\t\t},\n\n\t\treferenceCount(id: string): number {\n\t\t\tif (!isSafeArtifactId(id)) return 0;\n\t\t\treturn readMeta(baseDir, id)?.references.length ?? 0;\n\t\t},\n\n\t\tcleanup(): string[] {\n\t\t\tconst deleted: string[] = [];\n\t\t\tfor (const entry of readdirSync(baseDir)) {\n\t\t\t\tif (!entry.endsWith(META_SUFFIX)) continue;\n\t\t\t\tconst id = entry.slice(0, -META_SUFFIX.length);\n\t\t\t\tif (!isSafeArtifactId(id)) continue;\n\t\t\t\tconst meta = readMeta(baseDir, id);\n\t\t\t\tif (!meta || meta.references.length > 0) continue;\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(metaPath(baseDir, id));\n\t\t\t\t} catch {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(payloadPath(baseDir, id));\n\t\t\t\t} catch {\n\t\t\t\t\t// Payload already gone; metadata removal above is what matters for reachability.\n\t\t\t\t}\n\t\t\t\tcleanedUpThisInstance.add(id);\n\t\t\t\tdeleted.push(id);\n\t\t\t}\n\t\t\treturn deleted;\n\t\t},\n\t};\n}\n"]}