@caupulican/pi-adaptative 0.80.86 → 0.80.88

package/dist/core/context/context-artifacts.js

@@ -0,0 +1,307 @@
+/**
+ * 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 { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { estimateByteLength, estimateLineCount } from "./context-item.js";
+export function isMissingArtifactMarker(value) {
+    return value.missing === true;
+}
+/**
+ * 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 function generateArtifactId(request) {
+    return createHash("sha256")
+        .update([
+        request.kind,
+        request.toolName ?? "",
+        request.command ?? "",
+        request.path ?? "",
+        request.sessionEntryId ?? "",
+        String(request.createdAtTurn),
+        String(request.reproducible),
+        request.content,
+    ].join("\0"))
+        .digest("hex")
+        .slice(0, 24);
+}
+export function createInMemoryArtifactStore() {
+    const artifacts = new Map();
+    const cleanedUp = new Set();
+    return {
+        write(request) {
+            const id = generateArtifactId(request);
+            const existing = artifacts.get(id);
+            if (existing) {
+                cleanedUp.delete(id);
+                return { ref: existing.ref, content: existing.content };
+            }
+            const ref = {
+                id,
+                kind: request.kind,
+                sessionEntryId: request.sessionEntryId,
+                toolName: request.toolName,
+                command: request.command,
+                path: request.path,
+                byteLength: estimateByteLength(request.content),
+                lineCount: estimateLineCount(request.content),
+                createdAtTurn: request.createdAtTurn,
+                reproducible: request.reproducible,
+            };
+            artifacts.set(id, { ref, content: request.content, references: new Set() });
+            cleanedUp.delete(id);
+            return { ref, content: request.content };
+        },
+        read(id) {
+            const stored = artifacts.get(id);
+            if (!stored) {
+                return { id, missing: true, reason: cleanedUp.has(id) ? "cleaned_up" : "not_found" };
+            }
+            return { ref: stored.ref, content: stored.content };
+        },
+        readRef(id) {
+            return artifacts.get(id)?.ref;
+        },
+        has(id) {
+            return artifacts.has(id);
+        },
+        addReference(id, holderId) {
+            const stored = artifacts.get(id);
+            if (!stored)
+                return false;
+            stored.references.add(holderId);
+            return true;
+        },
+        removeReference(id, holderId) {
+            const stored = artifacts.get(id);
+            if (!stored)
+                return false;
+            return stored.references.delete(holderId);
+        },
+        referenceCount(id) {
+            return artifacts.get(id)?.references.size ?? 0;
+        },
+        cleanup() {
+            const deleted = [];
+            for (const [id, stored] of artifacts) {
+                if (stored.references.size === 0) {
+                    artifacts.delete(id);
+                    cleanedUp.add(id);
+                    deleted.push(id);
+                }
+            }
+            return deleted;
+        },
+    };
+}
+const META_SUFFIX = ".meta.json";
+const PAYLOAD_SUFFIX = ".payload";
+/**
+ * Artifact ids are generated by `generateArtifactId` as a lowercase hex digest. Reject
+ * anything else so a caller-supplied id (including one echoed back from model output)
+ * can never be used as a path-traversal vector into `baseDir`.
+ */
+function isSafeArtifactId(id) {
+    return /^[0-9a-f]{1,64}$/.test(id);
+}
+function payloadPath(baseDir, id) {
+    return join(baseDir, `${id}${PAYLOAD_SUFFIX}`);
+}
+function metaPath(baseDir, id) {
+    return join(baseDir, `${id}${META_SUFFIX}`);
+}
+const VALID_ARTIFACT_KINDS = new Set([
+    "tool_output",
+    "file_snapshot",
+    "test_output",
+    "diff",
+    "transcript_slice",
+]);
+function isValidArtifactRefShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const ref = value;
+    return (typeof ref.id === "string" &&
+        typeof ref.kind === "string" &&
+        VALID_ARTIFACT_KINDS.has(ref.kind) &&
+        typeof ref.byteLength === "number" &&
+        typeof ref.createdAtTurn === "number" &&
+        typeof ref.reproducible === "boolean");
+}
+/**
+ * A parsed JSON value can be syntactically valid but semantically garbage (truncated
+ * write, hand-edited file, future/incompatible format). Validate shape, not just parse
+ * success, so a malformed sidecar can never produce an invalid ref or crash `cleanup()` --
+ * it is treated as unusable/missing, the same as a sidecar that doesn't exist.
+ */
+function isValidPersistedArtifactMeta(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const meta = value;
+    return (isValidArtifactRefShape(meta.ref) &&
+        Array.isArray(meta.references) &&
+        meta.references.every((entry) => typeof entry === "string"));
+}
+function readMeta(baseDir, id) {
+    const path = metaPath(baseDir, id);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return isValidPersistedArtifactMeta(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeMeta(baseDir, id, meta) {
+    writeFileSync(metaPath(baseDir, id), JSON.stringify(meta), "utf8");
+}
+/**
+ * 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 function createFileArtifactStore(options) {
+    const baseDir = options.baseDir;
+    mkdirSync(baseDir, { recursive: true });
+    const cleanedUpThisInstance = new Set();
+    return {
+        write(request) {
+            const id = generateArtifactId(request);
+            const existingMeta = readMeta(baseDir, id);
+            const existingPayloadPath = payloadPath(baseDir, id);
+            if (existingMeta && existsSync(existingPayloadPath)) {
+                cleanedUpThisInstance.delete(id);
+                return { ref: existingMeta.ref, content: readFileSync(existingPayloadPath, "utf8") };
+            }
+            const ref = {
+                id,
+                kind: request.kind,
+                sessionEntryId: request.sessionEntryId,
+                toolName: request.toolName,
+                command: request.command,
+                path: request.path,
+                byteLength: estimateByteLength(request.content),
+                lineCount: estimateLineCount(request.content),
+                createdAtTurn: request.createdAtTurn,
+                reproducible: request.reproducible,
+            };
+            writeFileSync(payloadPath(baseDir, id), request.content, "utf8");
+            writeMeta(baseDir, id, { ref, references: [] });
+            cleanedUpThisInstance.delete(id);
+            return { ref, content: request.content };
+        },
+        read(id) {
+            if (!isSafeArtifactId(id))
+                return { id, missing: true, reason: "not_found" };
+            const meta = readMeta(baseDir, id);
+            const pPath = payloadPath(baseDir, id);
+            if (!meta || !existsSync(pPath)) {
+                return { id, missing: true, reason: cleanedUpThisInstance.has(id) ? "cleaned_up" : "not_found" };
+            }
+            return { ref: meta.ref, content: readFileSync(pPath, "utf8") };
+        },
+        readRef(id) {
+            if (!isSafeArtifactId(id))
+                return undefined;
+            const meta = readMeta(baseDir, id);
+            if (!meta || !existsSync(payloadPath(baseDir, id)))
+                return undefined;
+            return meta.ref;
+        },
+        has(id) {
+            if (!isSafeArtifactId(id))
+                return false;
+            return readMeta(baseDir, id) !== undefined && existsSync(payloadPath(baseDir, id));
+        },
+        addReference(id, holderId) {
+            if (!isSafeArtifactId(id))
+                return false;
+            const meta = readMeta(baseDir, id);
+            if (!meta || !existsSync(payloadPath(baseDir, id)))
+                return false;
+            if (!meta.references.includes(holderId)) {
+                meta.references.push(holderId);
+                writeMeta(baseDir, id, meta);
+            }
+            return true;
+        },
+        removeReference(id, holderId) {
+            if (!isSafeArtifactId(id))
+                return false;
+            const meta = readMeta(baseDir, id);
+            if (!meta)
+                return false;
+            const index = meta.references.indexOf(holderId);
+            if (index === -1)
+                return false;
+            meta.references.splice(index, 1);
+            writeMeta(baseDir, id, meta);
+            return true;
+        },
+        referenceCount(id) {
+            if (!isSafeArtifactId(id))
+                return 0;
+            return readMeta(baseDir, id)?.references.length ?? 0;
+        },
+        cleanup() {
+            const deleted = [];
+            for (const entry of readdirSync(baseDir)) {
+                if (!entry.endsWith(META_SUFFIX))
+                    continue;
+                const id = entry.slice(0, -META_SUFFIX.length);
+                if (!isSafeArtifactId(id))
+                    continue;
+                const meta = readMeta(baseDir, id);
+                if (!meta || meta.references.length > 0)
+                    continue;
+                try {
+                    unlinkSync(metaPath(baseDir, id));
+                }
+                catch {
+                    continue;
+                }
+                try {
+                    unlinkSync(payloadPath(baseDir, id));
+                }
+                catch {
+                    // Payload already gone; metadata removal above is what matters for reachability.
+                }
+                cleanedUpThisInstance.add(id);
+                deleted.push(id);
+            }
+            return deleted;
+        },
+    };
+}
+//# sourceMappingURL=context-artifacts.js.map

package/dist/core/context/context-artifacts.js.map

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

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

@@ -0,0 +1,66 @@
+/**
+ * Live observe-only bridge from AgentMessage[] to the ContextItem/policy-engine layer
+ * (Phase 1 audit pass). This module only ever reads messages and the artifact store; it
+ * never mutates messages, the transcript, or artifact references. It is the first thing to
+ * consume the context-item.ts/context-retention.ts/policy-engine.ts contracts against live
+ * session state, but it does not yet change what the model sees -- see
+ * docs/context-management-rework/implementation-phases.md for where this sits.
+ *
+ * Scope for this pass: only `toolResult` messages become `ContextItem`s (kind
+ * "tool_output"). Other roles (user/assistant) are skipped; representing them is later
+ * work once their ContextItemKind mapping (user_instruction/approval/etc.) is designed.
+ *
+ * Retrieval-path semantics (deliberately narrower than context-retention.ts's item-level
+ * `hasReferencedEvidence`): a transcript ref is attached to every item as provenance
+ * evidence (which live message this item came from), but it never counts toward
+ * `HardConstraintFlags.hasAvailableRetrievalPath` on its own -- there is no live mechanism
+ * today for the model to fetch an older message back into context by session-entry id, so
+ * claiming that would overclaim retrievability (the same fail-closed principle
+ * `artifact_retrieve` follows). Only a resolved artifact ref (the store still has the
+ * payload) counts as an available retrieval path.
+ */
+import type { AgentMessage } from "@caupulican/pi-agent-core";
+import type { ToolResultMessage } from "@caupulican/pi-ai";
+import type { ArtifactStore } from "./context-artifacts.ts";
+import { type ContextItem } from "./context-item.ts";
+import { type RetentionEligibility } from "./context-retention.ts";
+import type { PolicyHardConstraintCode } from "./policy-types.ts";
+export interface ContextAuditOptions {
+    /** Current turn index (AgentSession's own per-run counter); used as `createdAtTurn`. */
+    turnIndex: number;
+    /** Session-scoped artifact store, if one has been constructed. Read-only here. */
+    artifactStore?: ArtifactStore;
+    /** Resolve the persisted session-entry id for a toolResult message's toolCallId, if known. */
+    sessionEntryIdForToolCallId?: (toolCallId: string) => string | undefined;
+}
+export interface ContextAuditItemReport {
+    item: ContextItem;
+    /** The source toolResult message's own id and position, always available (unlike refs). */
+    toolCallId: string;
+    messageIndex: number;
+    /** Coarse, store-free eligibility from context-retention.ts (treats any ref as retrievable). */
+    retention: RetentionEligibility;
+    /** Store-aware hard-constraint codes for keep_raw; always empty (no evaluated action restricts it), included for reportability. */
+    keepRawHardConstraints: PolicyHardConstraintCode[];
+    /** Store-aware hard-constraint codes for pack_to_artifact; empty means no hard rejection. */
+    packToArtifactHardConstraints: PolicyHardConstraintCode[];
+    /** Store-aware hard-constraint codes for drop_from_prompt; empty means no hard rejection. */
+    dropFromPromptHardConstraints: PolicyHardConstraintCode[];
+    /** Store-aware hard-constraint codes for summarize; empty means no hard rejection. */
+    summarizeHardConstraints: PolicyHardConstraintCode[];
+}
+export interface ContextAuditReport {
+    turnIndex: number;
+    items: ContextAuditItemReport[];
+}
+/** Build the ContextItem for a single toolResult message, for direct unit testing. */
+export declare function buildToolResultContextItem(message: ToolResultMessage, messageIndex: number, options: ContextAuditOptions): ContextItem;
+/**
+ * Read-only audit pass: converts live toolResult messages into ContextItems and runs the
+ * existing pure retention/hard-constraint evaluators over them. Never mutates `messages`,
+ * the transcript, or artifact references -- deterministic given the same messages,
+ * `turnIndex`, and artifact-store state (not a cross-turn stability guarantee: turnIndex
+ * and artifact-backed createdAtTurn values are expected to change turn over turn).
+ */
+export declare function runContextAudit(messages: AgentMessage[], options: ContextAuditOptions): ContextAuditReport;
+//# sourceMappingURL=context-audit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-audit.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAEN,KAAK,WAAW,EAGhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAgC,KAAK,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEjG,OAAO,KAAK,EAAuC,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAEvG,MAAM,WAAW,mBAAmB;IACnC,wFAAwF;IACxF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,8FAA8F;IAC9F,2BAA2B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACzE;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,WAAW,CAAC;IAClB,2FAA2F;IAC3F,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,gGAAgG;IAChG,SAAS,EAAE,oBAAoB,CAAC;IAChC,mIAAmI;IACnI,sBAAsB,EAAE,wBAAwB,EAAE,CAAC;IACnD,6FAA6F;IAC7F,6BAA6B,EAAE,wBAAwB,EAAE,CAAC;IAC1D,6FAA6F;IAC7F,6BAA6B,EAAE,wBAAwB,EAAE,CAAC;IAC1D,sFAAsF;IACtF,wBAAwB,EAAE,wBAAwB,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,sBAAsB,EAAE,CAAC;CAChC;AAqID,sFAAsF;AACtF,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,iBAAiB,EAC1B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,mBAAmB,GAC1B,WAAW,CAEb;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAmB1G","sourcesContent":["/**\n * Live observe-only bridge from AgentMessage[] to the ContextItem/policy-engine layer\n * (Phase 1 audit pass). This module only ever reads messages and the artifact store; it\n * never mutates messages, the transcript, or artifact references. It is the first thing to\n * consume the context-item.ts/context-retention.ts/policy-engine.ts contracts against live\n * session state, but it does not yet change what the model sees -- see\n * docs/context-management-rework/implementation-phases.md for where this sits.\n *\n * Scope for this pass: only `toolResult` messages become `ContextItem`s (kind\n * \"tool_output\"). Other roles (user/assistant) are skipped; representing them is later\n * work once their ContextItemKind mapping (user_instruction/approval/etc.) is designed.\n *\n * Retrieval-path semantics (deliberately narrower than context-retention.ts's item-level\n * `hasReferencedEvidence`): a transcript ref is attached to every item as provenance\n * evidence (which live message this item came from), but it never counts toward\n * `HardConstraintFlags.hasAvailableRetrievalPath` on its own -- there is no live mechanism\n * today for the model to fetch an older message back into context by session-entry id, so\n * claiming that would overclaim retrievability (the same fail-closed principle\n * `artifact_retrieve` follows). Only a resolved artifact ref (the store still has the\n * payload) counts as an available retrieval path.\n */\n\nimport type { AgentMessage } from \"@caupulican/pi-agent-core\";\nimport type { ToolResultMessage } from \"@caupulican/pi-ai\";\nimport type { ArtifactStore } from \"./context-artifacts.ts\";\nimport {\n\ttype ContextEvidenceRef,\n\ttype ContextItem,\n\testimateByteLength,\n\testimateTokensFromText,\n} from \"./context-item.ts\";\nimport { evaluateRetentionEligibility, type RetentionEligibility } from \"./context-retention.ts\";\nimport { evaluateHardConstraints } from \"./policy-engine.ts\";\nimport type { HardConstraintFlags, PolicyFeatures, PolicyHardConstraintCode } from \"./policy-types.ts\";\n\nexport interface ContextAuditOptions {\n\t/** Current turn index (AgentSession's own per-run counter); used as `createdAtTurn`. */\n\tturnIndex: number;\n\t/** Session-scoped artifact store, if one has been constructed. Read-only here. */\n\tartifactStore?: ArtifactStore;\n\t/** Resolve the persisted session-entry id for a toolResult message's toolCallId, if known. */\n\tsessionEntryIdForToolCallId?: (toolCallId: string) => string | undefined;\n}\n\nexport interface ContextAuditItemReport {\n\titem: ContextItem;\n\t/** The source toolResult message's own id and position, always available (unlike refs). */\n\ttoolCallId: string;\n\tmessageIndex: number;\n\t/** Coarse, store-free eligibility from context-retention.ts (treats any ref as retrievable). */\n\tretention: RetentionEligibility;\n\t/** Store-aware hard-constraint codes for keep_raw; always empty (no evaluated action restricts it), included for reportability. */\n\tkeepRawHardConstraints: PolicyHardConstraintCode[];\n\t/** Store-aware hard-constraint codes for pack_to_artifact; empty means no hard rejection. */\n\tpackToArtifactHardConstraints: PolicyHardConstraintCode[];\n\t/** Store-aware hard-constraint codes for drop_from_prompt; empty means no hard rejection. */\n\tdropFromPromptHardConstraints: PolicyHardConstraintCode[];\n\t/** Store-aware hard-constraint codes for summarize; empty means no hard rejection. */\n\tsummarizeHardConstraints: PolicyHardConstraintCode[];\n}\n\nexport interface ContextAuditReport {\n\tturnIndex: number;\n\titems: ContextAuditItemReport[];\n}\n\nfunction extractToolResultArtifactId(message: ToolResultMessage): string | undefined {\n\tconst details = message.details;\n\tif (typeof details !== \"object\" || details === null) return undefined;\n\tconst artifactId = (details as { artifactId?: unknown }).artifactId;\n\treturn typeof artifactId === \"string\" ? artifactId : undefined;\n}\n\nfunction toolResultText(message: ToolResultMessage): string {\n\tconst parts: string[] = [];\n\tfor (const part of message.content) {\n\t\tif (part.type === \"text\") parts.push(part.text);\n\t}\n\treturn parts.join(\"\\n\");\n}\n\ninterface BuiltToolOutputItem {\n\titem: ContextItem;\n\t/** True only if an artifact ref was found AND resolved against a live store. */\n\thasResolvedArtifact: boolean;\n}\n\nfunction buildToolOutputItem(\n\tmessage: ToolResultMessage,\n\tmessageIndex: number,\n\toptions: ContextAuditOptions,\n): BuiltToolOutputItem {\n\tconst text = toolResultText(message);\n\tconst artifactId = extractToolResultArtifactId(message);\n\tconst sessionEntryId = options.sessionEntryIdForToolCallId?.(message.toolCallId);\n\n\tlet primaryRef: ContextEvidenceRef | undefined;\n\tlet hasResolvedArtifact = false;\n\t// createdAtTurn defaults to the current audit turn (an approximation -- see below) and\n\t// is overridden with the real capture turn when an artifact ref resolves.\n\tlet createdAtTurn = options.turnIndex;\n\tif (artifactId && options.artifactStore) {\n\t\t// Metadata-only: never loads the artifact's payload just to check resolvability and\n\t\t// grab ref fields (a per-turn audit pass over every artifact-backed result would\n\t\t// otherwise re-read every payload off disk each turn for no reason).\n\t\tconst ref = options.artifactStore.readRef(artifactId);\n\t\tif (ref) {\n\t\t\tprimaryRef = { type: \"artifact\", ref };\n\t\t\thasResolvedArtifact = true;\n\t\t\tcreatedAtTurn = ref.createdAtTurn;\n\t\t}\n\t}\n\n\tconst evidenceRefs: ContextEvidenceRef[] = [];\n\tif (sessionEntryId) {\n\t\tconst transcriptRef: ContextEvidenceRef = {\n\t\t\ttype: \"transcript\",\n\t\t\tref: { sessionEntryId, messageIndex },\n\t\t};\n\t\tif (!primaryRef) primaryRef = transcriptRef;\n\t\telse evidenceRefs.push(transcriptRef);\n\t}\n\n\tconst item: ContextItem = {\n\t\tid: `tool-output:${message.toolCallId}`,\n\t\tkind: \"tool_output\",\n\t\tretentionClass: \"ephemeral\",\n\t\tsource: \"tool\",\n\t\t// Transcript-only items (no artifact ref) have no real creation-turn source threaded\n\t\t// in yet, so this falls back to the current audit turn as an approximation --\n\t\t// deliberately not left silently wrong: no evaluator reads createdAtTurn today, but\n\t\t// any future staleness/break-even math must use the real per-item value above, not\n\t\t// this fallback, once one exists for non-artifact items too.\n\t\tcreatedAtTurn,\n\t\tsummary: `${message.toolName} tool result`,\n\t\tprimaryRef,\n\t\tevidenceRefs: evidenceRefs.length > 0 ? evidenceRefs : undefined,\n\t\ttokenEstimate: estimateTokensFromText(text),\n\t\tbyteEstimate: estimateByteLength(text),\n\t};\n\n\treturn { item, hasResolvedArtifact };\n}\n\n/**\n * Economic/probability fields are zeroed: `evaluateHardConstraints` does not read them for\n * pack_to_artifact/drop_from_prompt (only the break-even scoring math this audit\n * deliberately does not invoke would need real numbers here).\n */\nfunction buildPolicyFeatures(item: ContextItem, built: BuiltToolOutputItem, turnIndex: number): PolicyFeatures {\n\treturn {\n\t\tturnIndex,\n\t\texpectedRemainingTurns: 0,\n\t\tinputTokens: 0,\n\t\toutputTokens: 0,\n\t\tcacheReadTokens: 0,\n\t\tcacheWriteTokens: 0,\n\t\tartifactBytes: built.hasResolvedArtifact ? item.byteEstimate : 0,\n\t\tcharEstimate: item.byteEstimate,\n\t\tcalibratedTokenEstimate: item.tokenEstimate,\n\t\tpromptSection: \"volatile_tail\",\n\t\tretentionClass: item.retentionClass,\n\t\tisReproducible: true,\n\t\tisDecisionBearing: false,\n\t\tisPinned: false,\n\t\tisOpenRequirement: false,\n\t\tisLatestFailure: false,\n\t\tisCurrentDiff: false,\n\t\tprobabilityNeededAgain: 0,\n\t\tprobabilityErrorIfDropped: 0,\n\t\tretrievalCostTokens: 0,\n\t\tpackCostTokens: 0,\n\t\tretryCostTokens: 0,\n\t\tfailureCostTokens: 0,\n\t\tvalidationCostTokens: 0,\n\t};\n}\n\nfunction buildHardConstraintFlags(built: BuiltToolOutputItem, artifactStoreAvailable: boolean): HardConstraintFlags {\n\treturn {\n\t\tisApprovalOrDenial: false,\n\t\tisSafetyConstraint: false,\n\t\tisActiveBlocker: false,\n\t\tisCurrentValidationResult: false,\n\t\tisPathOrToolScope: false,\n\t\t// Only a resolved artifact counts; a transcript ref is provenance, not a live\n\t\t// retrieval mechanism -- see the module doc comment.\n\t\thasAvailableRetrievalPath: built.hasResolvedArtifact,\n\t\tartifactStoreAvailable,\n\t\thasEvidenceRefForSummary: built.item.primaryRef !== undefined || (built.item.evidenceRefs?.length ?? 0) > 0,\n\t\tpathOrToolBoundariesEnforced: true,\n\t\tvalidationAvailableAndStrong: false,\n\t\tpriorAttemptFailedForReasoningOrArchitecture: false,\n\t\tisHighImpactOrBroadMultiFileEdit: false,\n\t};\n}\n\n/** Build the ContextItem for a single toolResult message, for direct unit testing. */\nexport function buildToolResultContextItem(\n\tmessage: ToolResultMessage,\n\tmessageIndex: number,\n\toptions: ContextAuditOptions,\n): ContextItem {\n\treturn buildToolOutputItem(message, messageIndex, options).item;\n}\n\n/**\n * Read-only audit pass: converts live toolResult messages into ContextItems and runs the\n * existing pure retention/hard-constraint evaluators over them. Never mutates `messages`,\n * the transcript, or artifact references -- deterministic given the same messages,\n * `turnIndex`, and artifact-store state (not a cross-turn stability guarantee: turnIndex\n * and artifact-backed createdAtTurn values are expected to change turn over turn).\n */\nexport function runContextAudit(messages: AgentMessage[], options: ContextAuditOptions): ContextAuditReport {\n\tconst items: ContextAuditItemReport[] = [];\n\tmessages.forEach((message, messageIndex) => {\n\t\tif (message.role !== \"toolResult\") return;\n\t\tconst built = buildToolOutputItem(message, messageIndex, options);\n\t\tconst features = buildPolicyFeatures(built.item, built, options.turnIndex);\n\t\tconst flags = buildHardConstraintFlags(built, options.artifactStore !== undefined);\n\t\titems.push({\n\t\t\titem: built.item,\n\t\t\ttoolCallId: message.toolCallId,\n\t\t\tmessageIndex,\n\t\t\tretention: evaluateRetentionEligibility(built.item),\n\t\t\tkeepRawHardConstraints: evaluateHardConstraints(\"keep_raw\", features, flags),\n\t\t\tpackToArtifactHardConstraints: evaluateHardConstraints(\"pack_to_artifact\", features, flags),\n\t\t\tdropFromPromptHardConstraints: evaluateHardConstraints(\"drop_from_prompt\", features, flags),\n\t\t\tsummarizeHardConstraints: evaluateHardConstraints(\"summarize\", features, flags),\n\t\t});\n\t});\n\treturn { turnIndex: options.turnIndex, items };\n}\n"]}

package/dist/core/context/context-audit.js

@@ -0,0 +1,173 @@
+/**
+ * Live observe-only bridge from AgentMessage[] to the ContextItem/policy-engine layer
+ * (Phase 1 audit pass). This module only ever reads messages and the artifact store; it
+ * never mutates messages, the transcript, or artifact references. It is the first thing to
+ * consume the context-item.ts/context-retention.ts/policy-engine.ts contracts against live
+ * session state, but it does not yet change what the model sees -- see
+ * docs/context-management-rework/implementation-phases.md for where this sits.
+ *
+ * Scope for this pass: only `toolResult` messages become `ContextItem`s (kind
+ * "tool_output"). Other roles (user/assistant) are skipped; representing them is later
+ * work once their ContextItemKind mapping (user_instruction/approval/etc.) is designed.
+ *
+ * Retrieval-path semantics (deliberately narrower than context-retention.ts's item-level
+ * `hasReferencedEvidence`): a transcript ref is attached to every item as provenance
+ * evidence (which live message this item came from), but it never counts toward
+ * `HardConstraintFlags.hasAvailableRetrievalPath` on its own -- there is no live mechanism
+ * today for the model to fetch an older message back into context by session-entry id, so
+ * claiming that would overclaim retrievability (the same fail-closed principle
+ * `artifact_retrieve` follows). Only a resolved artifact ref (the store still has the
+ * payload) counts as an available retrieval path.
+ */
+import { estimateByteLength, estimateTokensFromText, } from "./context-item.js";
+import { evaluateRetentionEligibility } from "./context-retention.js";
+import { evaluateHardConstraints } from "./policy-engine.js";
+function extractToolResultArtifactId(message) {
+    const details = message.details;
+    if (typeof details !== "object" || details === null)
+        return undefined;
+    const artifactId = details.artifactId;
+    return typeof artifactId === "string" ? artifactId : undefined;
+}
+function toolResultText(message) {
+    const parts = [];
+    for (const part of message.content) {
+        if (part.type === "text")
+            parts.push(part.text);
+    }
+    return parts.join("\n");
+}
+function buildToolOutputItem(message, messageIndex, options) {
+    const text = toolResultText(message);
+    const artifactId = extractToolResultArtifactId(message);
+    const sessionEntryId = options.sessionEntryIdForToolCallId?.(message.toolCallId);
+    let primaryRef;
+    let hasResolvedArtifact = false;
+    // createdAtTurn defaults to the current audit turn (an approximation -- see below) and
+    // is overridden with the real capture turn when an artifact ref resolves.
+    let createdAtTurn = options.turnIndex;
+    if (artifactId && options.artifactStore) {
+        // Metadata-only: never loads the artifact's payload just to check resolvability and
+        // grab ref fields (a per-turn audit pass over every artifact-backed result would
+        // otherwise re-read every payload off disk each turn for no reason).
+        const ref = options.artifactStore.readRef(artifactId);
+        if (ref) {
+            primaryRef = { type: "artifact", ref };
+            hasResolvedArtifact = true;
+            createdAtTurn = ref.createdAtTurn;
+        }
+    }
+    const evidenceRefs = [];
+    if (sessionEntryId) {
+        const transcriptRef = {
+            type: "transcript",
+            ref: { sessionEntryId, messageIndex },
+        };
+        if (!primaryRef)
+            primaryRef = transcriptRef;
+        else
+            evidenceRefs.push(transcriptRef);
+    }
+    const item = {
+        id: `tool-output:${message.toolCallId}`,
+        kind: "tool_output",
+        retentionClass: "ephemeral",
+        source: "tool",
+        // Transcript-only items (no artifact ref) have no real creation-turn source threaded
+        // in yet, so this falls back to the current audit turn as an approximation --
+        // deliberately not left silently wrong: no evaluator reads createdAtTurn today, but
+        // any future staleness/break-even math must use the real per-item value above, not
+        // this fallback, once one exists for non-artifact items too.
+        createdAtTurn,
+        summary: `${message.toolName} tool result`,
+        primaryRef,
+        evidenceRefs: evidenceRefs.length > 0 ? evidenceRefs : undefined,
+        tokenEstimate: estimateTokensFromText(text),
+        byteEstimate: estimateByteLength(text),
+    };
+    return { item, hasResolvedArtifact };
+}
+/**
+ * Economic/probability fields are zeroed: `evaluateHardConstraints` does not read them for
+ * pack_to_artifact/drop_from_prompt (only the break-even scoring math this audit
+ * deliberately does not invoke would need real numbers here).
+ */
+function buildPolicyFeatures(item, built, turnIndex) {
+    return {
+        turnIndex,
+        expectedRemainingTurns: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        artifactBytes: built.hasResolvedArtifact ? item.byteEstimate : 0,
+        charEstimate: item.byteEstimate,
+        calibratedTokenEstimate: item.tokenEstimate,
+        promptSection: "volatile_tail",
+        retentionClass: item.retentionClass,
+        isReproducible: true,
+        isDecisionBearing: false,
+        isPinned: false,
+        isOpenRequirement: false,
+        isLatestFailure: false,
+        isCurrentDiff: false,
+        probabilityNeededAgain: 0,
+        probabilityErrorIfDropped: 0,
+        retrievalCostTokens: 0,
+        packCostTokens: 0,
+        retryCostTokens: 0,
+        failureCostTokens: 0,
+        validationCostTokens: 0,
+    };
+}
+function buildHardConstraintFlags(built, artifactStoreAvailable) {
+    return {
+        isApprovalOrDenial: false,
+        isSafetyConstraint: false,
+        isActiveBlocker: false,
+        isCurrentValidationResult: false,
+        isPathOrToolScope: false,
+        // Only a resolved artifact counts; a transcript ref is provenance, not a live
+        // retrieval mechanism -- see the module doc comment.
+        hasAvailableRetrievalPath: built.hasResolvedArtifact,
+        artifactStoreAvailable,
+        hasEvidenceRefForSummary: built.item.primaryRef !== undefined || (built.item.evidenceRefs?.length ?? 0) > 0,
+        pathOrToolBoundariesEnforced: true,
+        validationAvailableAndStrong: false,
+        priorAttemptFailedForReasoningOrArchitecture: false,
+        isHighImpactOrBroadMultiFileEdit: false,
+    };
+}
+/** Build the ContextItem for a single toolResult message, for direct unit testing. */
+export function buildToolResultContextItem(message, messageIndex, options) {
+    return buildToolOutputItem(message, messageIndex, options).item;
+}
+/**
+ * Read-only audit pass: converts live toolResult messages into ContextItems and runs the
+ * existing pure retention/hard-constraint evaluators over them. Never mutates `messages`,
+ * the transcript, or artifact references -- deterministic given the same messages,
+ * `turnIndex`, and artifact-store state (not a cross-turn stability guarantee: turnIndex
+ * and artifact-backed createdAtTurn values are expected to change turn over turn).
+ */
+export function runContextAudit(messages, options) {
+    const items = [];
+    messages.forEach((message, messageIndex) => {
+        if (message.role !== "toolResult")
+            return;
+        const built = buildToolOutputItem(message, messageIndex, options);
+        const features = buildPolicyFeatures(built.item, built, options.turnIndex);
+        const flags = buildHardConstraintFlags(built, options.artifactStore !== undefined);
+        items.push({
+            item: built.item,
+            toolCallId: message.toolCallId,
+            messageIndex,
+            retention: evaluateRetentionEligibility(built.item),
+            keepRawHardConstraints: evaluateHardConstraints("keep_raw", features, flags),
+            packToArtifactHardConstraints: evaluateHardConstraints("pack_to_artifact", features, flags),
+            dropFromPromptHardConstraints: evaluateHardConstraints("drop_from_prompt", features, flags),
+            summarizeHardConstraints: evaluateHardConstraints("summarize", features, flags),
+        });
+    });
+    return { turnIndex: options.turnIndex, items };
+}
+//# sourceMappingURL=context-audit.js.map