@caupulican/pi-adaptative 0.80.86 → 0.80.88

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-audit.js","sourceRoot":"","sources":["../../../src/core/context/context-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,EAGN,kBAAkB,EAClB,sBAAsB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,4BAA4B,EAA6B,MAAM,wBAAwB,CAAC;AACjG,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAkC7D,SAAS,2BAA2B,CAAC,OAA0B,EAAsB;IACpF,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACtE,MAAM,UAAU,GAAI,OAAoC,CAAC,UAAU,CAAC;IACpE,OAAO,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CAC/D;AAED,SAAS,cAAc,CAAC,OAA0B,EAAU;IAC3D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CACxB;AAQD,SAAS,mBAAmB,CAC3B,OAA0B,EAC1B,YAAoB,EACpB,OAA4B,EACN;IACtB,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,UAAU,GAAG,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,cAAc,GAAG,OAAO,CAAC,2BAA2B,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAEjF,IAAI,UAA0C,CAAC;IAC/C,IAAI,mBAAmB,GAAG,KAAK,CAAC;IAChC,uFAAuF;IACvF,0EAA0E;IAC1E,IAAI,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC;IACtC,IAAI,UAAU,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QACzC,oFAAoF;QACpF,iFAAiF;QACjF,qEAAqE;QACrE,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACtD,IAAI,GAAG,EAAE,CAAC;YACT,UAAU,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;YACvC,mBAAmB,GAAG,IAAI,CAAC;YAC3B,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC;QACnC,CAAC;IACF,CAAC;IAED,MAAM,YAAY,GAAyB,EAAE,CAAC;IAC9C,IAAI,cAAc,EAAE,CAAC;QACpB,MAAM,aAAa,GAAuB;YACzC,IAAI,EAAE,YAAY;YAClB,GAAG,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE;SACrC,CAAC;QACF,IAAI,CAAC,UAAU;YAAE,UAAU,GAAG,aAAa,CAAC;;YACvC,YAAY,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,IAAI,GAAgB;QACzB,EAAE,EAAE,eAAe,OAAO,CAAC,UAAU,EAAE;QACvC,IAAI,EAAE,aAAa;QACnB,cAAc,EAAE,WAAW;QAC3B,MAAM,EAAE,MAAM;QACd,qFAAqF;QACrF,8EAA8E;QAC9E,oFAAoF;QACpF,mFAAmF;QACnF,6DAA6D;QAC7D,aAAa;QACb,OAAO,EAAE,GAAG,OAAO,CAAC,QAAQ,cAAc;QAC1C,UAAU;QACV,YAAY,EAAE,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;QAChE,aAAa,EAAE,sBAAsB,CAAC,IAAI,CAAC;QAC3C,YAAY,EAAE,kBAAkB,CAAC,IAAI,CAAC;KACtC,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;AAAA,CACrC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,IAAiB,EAAE,KAA0B,EAAE,SAAiB,EAAkB;IAC9G,OAAO;QACN,SAAS;QACT,sBAAsB,EAAE,CAAC;QACzB,WAAW,EAAE,CAAC;QACd,YAAY,EAAE,CAAC;QACf,eAAe,EAAE,CAAC;QAClB,gBAAgB,EAAE,CAAC;QACnB,aAAa,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAChE,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,uBAAuB,EAAE,IAAI,CAAC,aAAa;QAC3C,aAAa,EAAE,eAAe;QAC9B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,cAAc,EAAE,IAAI;QACpB,iBAAiB,EAAE,KAAK;QACxB,QAAQ,EAAE,KAAK;QACf,iBAAiB,EAAE,KAAK;QACxB,eAAe,EAAE,KAAK;QACtB,aAAa,EAAE,KAAK;QACpB,sBAAsB,EAAE,CAAC;QACzB,yBAAyB,EAAE,CAAC;QAC5B,mBAAmB,EAAE,CAAC;QACtB,cAAc,EAAE,CAAC;QACjB,eAAe,EAAE,CAAC;QAClB,iBAAiB,EAAE,CAAC;QACpB,oBAAoB,EAAE,CAAC;KACvB,CAAC;AAAA,CACF;AAED,SAAS,wBAAwB,CAAC,KAA0B,EAAE,sBAA+B,EAAuB;IACnH,OAAO;QACN,kBAAkB,EAAE,KAAK;QACzB,kBAAkB,EAAE,KAAK;QACzB,eAAe,EAAE,KAAK;QACtB,yBAAyB,EAAE,KAAK;QAChC,iBAAiB,EAAE,KAAK;QACxB,8EAA8E;QAC9E,qDAAqD;QACrD,yBAAyB,EAAE,KAAK,CAAC,mBAAmB;QACpD,sBAAsB;QACtB,wBAAwB,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC;QAC3G,4BAA4B,EAAE,IAAI;QAClC,4BAA4B,EAAE,KAAK;QACnC,4CAA4C,EAAE,KAAK;QACnD,gCAAgC,EAAE,KAAK;KACvC,CAAC;AAAA,CACF;AAED,sFAAsF;AACtF,MAAM,UAAU,0BAA0B,CACzC,OAA0B,EAC1B,YAAoB,EACpB,OAA4B,EACd;IACd,OAAO,mBAAmB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;AAAA,CAChE;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,QAAwB,EAAE,OAA4B,EAAsB;IAC3G,MAAM,KAAK,GAA6B,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC;QAC3C,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY;YAAE,OAAO;QAC1C,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;QAClE,MAAM,QAAQ,GAAG,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAC3E,MAAM,KAAK,GAAG,wBAAwB,CAAC,KAAK,EAAE,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC;QACnF,KAAK,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,YAAY;YACZ,SAAS,EAAE,4BAA4B,CAAC,KAAK,CAAC,IAAI,CAAC;YACnD,sBAAsB,EAAE,uBAAuB,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,CAAC;YAC5E,6BAA6B,EAAE,uBAAuB,CAAC,kBAAkB,EAAE,QAAQ,EAAE,KAAK,CAAC;YAC3F,6BAA6B,EAAE,uBAAuB,CAAC,kBAAkB,EAAE,QAAQ,EAAE,KAAK,CAAC;YAC3F,wBAAwB,EAAE,uBAAuB,CAAC,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC;SAC/E,CAAC,CAAC;IAAA,CACH,CAAC,CAAC;IACH,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC;AAAA,CAC/C","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-item.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Pure, provider-free context contracts.
+ *
+ * These types describe the curated working state the prompt builder will eventually
+ * consume, distinct from the immutable session transcript. Adding this module makes no
+ * behavior change: nothing here is wired into prompt construction yet.
+ */
+export type ContextItemKind = "user_instruction" | "approval" | "denial" | "safety_constraint" | "goal_state" | "requirement" | "plan" | "blocker" | "evidence" | "invalidated_assumption" | "tool_output" | "tool_output_digest" | "file_snapshot" | "diff_summary" | "test_result" | "conversation_tail" | "retrieved_artifact" | "memory_item" | "memory_digest";
+export type ContextRetentionClass = "pinned" | "active" | "decision_bearing" | "useful" | "ephemeral" | "expired";
+export type ContextSource = "user" | "assistant" | "tool" | "runtime" | "session" | "memory" | "external_provider";
+export interface ContextArtifactRef {
+    id: string;
+    kind: "tool_output" | "file_snapshot" | "test_output" | "diff" | "transcript_slice";
+    storagePath?: string;
+    sessionEntryId?: string;
+    toolName?: string;
+    command?: string;
+    path?: string;
+    byteLength: number;
+    lineCount?: number;
+    createdAtTurn: number;
+    reproducible: boolean;
+}
+export type MemoryScope = "session" | "project" | "user" | "global";
+export interface ContextMemoryRef {
+    providerId: string;
+    itemId: string;
+    scope: MemoryScope;
+    kind: string;
+    uri?: string;
+}
+export interface ContextTranscriptRef {
+    sessionEntryId: string;
+    branchId?: string;
+    messageIndex?: number;
+}
+export type ContextEvidenceRef = {
+    type: "artifact";
+    ref: ContextArtifactRef;
+} | {
+    type: "memory";
+    ref: ContextMemoryRef;
+} | {
+    type: "transcript";
+    ref: ContextTranscriptRef;
+} | {
+    type: "runtime";
+    id: string;
+    description: string;
+};
+export interface ContextItem {
+    id: string;
+    kind: ContextItemKind;
+    retentionClass: ContextRetentionClass;
+    source: ContextSource;
+    createdAtTurn: number;
+    lastUsedAtTurn?: number;
+    summary?: string;
+    content?: string;
+    primaryRef?: ContextEvidenceRef;
+    evidenceRefs?: ContextEvidenceRef[];
+    tokenEstimate: number;
+    byteEstimate: number;
+    supersededBy?: string;
+    invalidates?: string[];
+    pinReason?: string;
+    expiresAfterGoalId?: string;
+}
+export interface InvalidatedAssumptionItem {
+    id: string;
+    kind: "invalidated_assumption";
+    retentionClass: "decision_bearing" | "useful";
+    summary: string;
+    reason: string;
+    evidenceRefs: ContextEvidenceRef[];
+    expiresAfterGoalId?: string;
+}
+export type ModelRetentionAction = {
+    action: "keep";
+    itemId: string;
+    reason: string;
+} | {
+    action: "summarize";
+    itemId: string;
+    summary: string;
+    reason: string;
+    evidenceRefs?: ContextEvidenceRef[];
+} | {
+    action: "drop_from_prompt";
+    itemId: string;
+    reason: string;
+} | {
+    action: "invalidate";
+    itemId: string;
+    summary: string;
+    reason: string;
+    evidenceRefs: ContextEvidenceRef[];
+} | {
+    action: "pin_request";
+    itemId: string;
+    reason: string;
+};
+/**
+ * Kinds that are hard-retained regardless of retentionClass: their semantics must remain
+ * present in prompt context per the contracts-and-retention.md hard retention rules.
+ */
+export declare const HARD_RETAINED_CONTEXT_KINDS: ReadonlySet<ContextItemKind>;
+/** UTF-8 byte length, matching how the runtime measures raw payload size elsewhere. */
+export declare function estimateByteLength(text: string): number;
+export declare function estimateLineCount(text: string): number;
+/**
+ * No-tokenizer sizing rule from policy-engine-spec.md: estimatedTokens = ceil(chars / 4).
+ * Calibrate against provider-reported usage post-call; never treat this as semantic criticality.
+ */
+export declare function estimateTokensFromChars(charCount: number): number;
+export declare function estimateTokensFromText(text: string): number;
+//# sourceMappingURL=context-item.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-item.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-item.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure, provider-free context contracts.\n *\n * These types describe the curated working state the prompt builder will eventually\n * consume, distinct from the immutable session transcript. Adding this module makes no\n * behavior change: nothing here is wired into prompt construction yet.\n */\n\nexport type ContextItemKind =\n\t| \"user_instruction\"\n\t| \"approval\"\n\t| \"denial\"\n\t| \"safety_constraint\"\n\t| \"goal_state\"\n\t| \"requirement\"\n\t| \"plan\"\n\t| \"blocker\"\n\t| \"evidence\"\n\t| \"invalidated_assumption\"\n\t| \"tool_output\"\n\t| \"tool_output_digest\"\n\t| \"file_snapshot\"\n\t| \"diff_summary\"\n\t| \"test_result\"\n\t| \"conversation_tail\"\n\t| \"retrieved_artifact\"\n\t| \"memory_item\"\n\t| \"memory_digest\";\n\nexport type ContextRetentionClass = \"pinned\" | \"active\" | \"decision_bearing\" | \"useful\" | \"ephemeral\" | \"expired\";\n\nexport type ContextSource = \"user\" | \"assistant\" | \"tool\" | \"runtime\" | \"session\" | \"memory\" | \"external_provider\";\n\nexport interface ContextArtifactRef {\n\tid: string;\n\tkind: \"tool_output\" | \"file_snapshot\" | \"test_output\" | \"diff\" | \"transcript_slice\";\n\tstoragePath?: string;\n\tsessionEntryId?: string;\n\ttoolName?: string;\n\tcommand?: string;\n\tpath?: string;\n\tbyteLength: number;\n\tlineCount?: number;\n\tcreatedAtTurn: number;\n\treproducible: boolean;\n}\n\nexport type MemoryScope = \"session\" | \"project\" | \"user\" | \"global\";\n\nexport interface ContextMemoryRef {\n\tproviderId: string;\n\titemId: string;\n\tscope: MemoryScope;\n\tkind: string;\n\turi?: string;\n}\n\nexport interface ContextTranscriptRef {\n\tsessionEntryId: string;\n\tbranchId?: string;\n\tmessageIndex?: number;\n}\n\nexport type ContextEvidenceRef =\n\t| { type: \"artifact\"; ref: ContextArtifactRef }\n\t| { type: \"memory\"; ref: ContextMemoryRef }\n\t| { type: \"transcript\"; ref: ContextTranscriptRef }\n\t| { type: \"runtime\"; id: string; description: string };\n\nexport interface ContextItem {\n\tid: string;\n\tkind: ContextItemKind;\n\tretentionClass: ContextRetentionClass;\n\tsource: ContextSource;\n\tcreatedAtTurn: number;\n\tlastUsedAtTurn?: number;\n\tsummary?: string;\n\tcontent?: string;\n\tprimaryRef?: ContextEvidenceRef;\n\tevidenceRefs?: ContextEvidenceRef[];\n\ttokenEstimate: number;\n\tbyteEstimate: number;\n\tsupersededBy?: string;\n\tinvalidates?: string[];\n\tpinReason?: string;\n\texpiresAfterGoalId?: string;\n}\n\nexport interface InvalidatedAssumptionItem {\n\tid: string;\n\tkind: \"invalidated_assumption\";\n\tretentionClass: \"decision_bearing\" | \"useful\";\n\tsummary: string;\n\treason: string;\n\tevidenceRefs: ContextEvidenceRef[];\n\texpiresAfterGoalId?: string;\n}\n\nexport type ModelRetentionAction =\n\t| { action: \"keep\"; itemId: string; reason: string }\n\t| { action: \"summarize\"; itemId: string; summary: string; reason: string; evidenceRefs?: ContextEvidenceRef[] }\n\t| { action: \"drop_from_prompt\"; itemId: string; reason: string }\n\t| { action: \"invalidate\"; itemId: string; summary: string; reason: string; evidenceRefs: ContextEvidenceRef[] }\n\t| { action: \"pin_request\"; itemId: string; reason: string };\n\n/**\n * Kinds that are hard-retained regardless of retentionClass: their semantics must remain\n * present in prompt context per the contracts-and-retention.md hard retention rules.\n */\nexport const HARD_RETAINED_CONTEXT_KINDS: ReadonlySet<ContextItemKind> = new Set([\n\t\"user_instruction\",\n\t\"approval\",\n\t\"denial\",\n\t\"safety_constraint\",\n]);\n\nconst NO_TOKENIZER_CHARS_PER_TOKEN = 4;\n\n/** UTF-8 byte length, matching how the runtime measures raw payload size elsewhere. */\nexport function estimateByteLength(text: string): number {\n\treturn Buffer.byteLength(text, \"utf8\");\n}\n\nexport function estimateLineCount(text: string): number {\n\treturn text.length === 0 ? 0 : text.split(\"\\n\").length;\n}\n\n/**\n * No-tokenizer sizing rule from policy-engine-spec.md: estimatedTokens = ceil(chars / 4).\n * Calibrate against provider-reported usage post-call; never treat this as semantic criticality.\n */\nexport function estimateTokensFromChars(charCount: number): number {\n\treturn Math.ceil(Math.max(0, charCount) / NO_TOKENIZER_CHARS_PER_TOKEN);\n}\n\nexport function estimateTokensFromText(text: string): number {\n\treturn estimateTokensFromChars(text.length);\n}\n"]}

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

@@ -0,0 +1,36 @@
+/**
+ * Pure, provider-free context contracts.
+ *
+ * These types describe the curated working state the prompt builder will eventually
+ * consume, distinct from the immutable session transcript. Adding this module makes no
+ * behavior change: nothing here is wired into prompt construction yet.
+ */
+/**
+ * Kinds that are hard-retained regardless of retentionClass: their semantics must remain
+ * present in prompt context per the contracts-and-retention.md hard retention rules.
+ */
+export const HARD_RETAINED_CONTEXT_KINDS = new Set([
+    "user_instruction",
+    "approval",
+    "denial",
+    "safety_constraint",
+]);
+const NO_TOKENIZER_CHARS_PER_TOKEN = 4;
+/** UTF-8 byte length, matching how the runtime measures raw payload size elsewhere. */
+export function estimateByteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+export function estimateLineCount(text) {
+    return text.length === 0 ? 0 : text.split("\n").length;
+}
+/**
+ * No-tokenizer sizing rule from policy-engine-spec.md: estimatedTokens = ceil(chars / 4).
+ * Calibrate against provider-reported usage post-call; never treat this as semantic criticality.
+ */
+export function estimateTokensFromChars(charCount) {
+    return Math.ceil(Math.max(0, charCount) / NO_TOKENIZER_CHARS_PER_TOKEN);
+}
+export function estimateTokensFromText(text) {
+    return estimateTokensFromChars(text.length);
+}
+//# sourceMappingURL=context-item.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-item.js","sourceRoot":"","sources":["../../../src/core/context/context-item.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmGH;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAiC,IAAI,GAAG,CAAC;IAChF,kBAAkB;IAClB,UAAU;IACV,QAAQ;IACR,mBAAmB;CACnB,CAAC,CAAC;AAEH,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAEvC,uFAAuF;AACvF,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAU;IACxD,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAAA,CACvC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAU;IACvD,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AAAA,CACvD;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAiB,EAAU;IAClE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,4BAA4B,CAAC,CAAC;AAAA,CACxE;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAY,EAAU;IAC5D,OAAO,uBAAuB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAAA,CAC5C","sourcesContent":["/**\n * Pure, provider-free context contracts.\n *\n * These types describe the curated working state the prompt builder will eventually\n * consume, distinct from the immutable session transcript. Adding this module makes no\n * behavior change: nothing here is wired into prompt construction yet.\n */\n\nexport type ContextItemKind =\n\t| \"user_instruction\"\n\t| \"approval\"\n\t| \"denial\"\n\t| \"safety_constraint\"\n\t| \"goal_state\"\n\t| \"requirement\"\n\t| \"plan\"\n\t| \"blocker\"\n\t| \"evidence\"\n\t| \"invalidated_assumption\"\n\t| \"tool_output\"\n\t| \"tool_output_digest\"\n\t| \"file_snapshot\"\n\t| \"diff_summary\"\n\t| \"test_result\"\n\t| \"conversation_tail\"\n\t| \"retrieved_artifact\"\n\t| \"memory_item\"\n\t| \"memory_digest\";\n\nexport type ContextRetentionClass = \"pinned\" | \"active\" | \"decision_bearing\" | \"useful\" | \"ephemeral\" | \"expired\";\n\nexport type ContextSource = \"user\" | \"assistant\" | \"tool\" | \"runtime\" | \"session\" | \"memory\" | \"external_provider\";\n\nexport interface ContextArtifactRef {\n\tid: string;\n\tkind: \"tool_output\" | \"file_snapshot\" | \"test_output\" | \"diff\" | \"transcript_slice\";\n\tstoragePath?: string;\n\tsessionEntryId?: string;\n\ttoolName?: string;\n\tcommand?: string;\n\tpath?: string;\n\tbyteLength: number;\n\tlineCount?: number;\n\tcreatedAtTurn: number;\n\treproducible: boolean;\n}\n\nexport type MemoryScope = \"session\" | \"project\" | \"user\" | \"global\";\n\nexport interface ContextMemoryRef {\n\tproviderId: string;\n\titemId: string;\n\tscope: MemoryScope;\n\tkind: string;\n\turi?: string;\n}\n\nexport interface ContextTranscriptRef {\n\tsessionEntryId: string;\n\tbranchId?: string;\n\tmessageIndex?: number;\n}\n\nexport type ContextEvidenceRef =\n\t| { type: \"artifact\"; ref: ContextArtifactRef }\n\t| { type: \"memory\"; ref: ContextMemoryRef }\n\t| { type: \"transcript\"; ref: ContextTranscriptRef }\n\t| { type: \"runtime\"; id: string; description: string };\n\nexport interface ContextItem {\n\tid: string;\n\tkind: ContextItemKind;\n\tretentionClass: ContextRetentionClass;\n\tsource: ContextSource;\n\tcreatedAtTurn: number;\n\tlastUsedAtTurn?: number;\n\tsummary?: string;\n\tcontent?: string;\n\tprimaryRef?: ContextEvidenceRef;\n\tevidenceRefs?: ContextEvidenceRef[];\n\ttokenEstimate: number;\n\tbyteEstimate: number;\n\tsupersededBy?: string;\n\tinvalidates?: string[];\n\tpinReason?: string;\n\texpiresAfterGoalId?: string;\n}\n\nexport interface InvalidatedAssumptionItem {\n\tid: string;\n\tkind: \"invalidated_assumption\";\n\tretentionClass: \"decision_bearing\" | \"useful\";\n\tsummary: string;\n\treason: string;\n\tevidenceRefs: ContextEvidenceRef[];\n\texpiresAfterGoalId?: string;\n}\n\nexport type ModelRetentionAction =\n\t| { action: \"keep\"; itemId: string; reason: string }\n\t| { action: \"summarize\"; itemId: string; summary: string; reason: string; evidenceRefs?: ContextEvidenceRef[] }\n\t| { action: \"drop_from_prompt\"; itemId: string; reason: string }\n\t| { action: \"invalidate\"; itemId: string; summary: string; reason: string; evidenceRefs: ContextEvidenceRef[] }\n\t| { action: \"pin_request\"; itemId: string; reason: string };\n\n/**\n * Kinds that are hard-retained regardless of retentionClass: their semantics must remain\n * present in prompt context per the contracts-and-retention.md hard retention rules.\n */\nexport const HARD_RETAINED_CONTEXT_KINDS: ReadonlySet<ContextItemKind> = new Set([\n\t\"user_instruction\",\n\t\"approval\",\n\t\"denial\",\n\t\"safety_constraint\",\n]);\n\nconst NO_TOKENIZER_CHARS_PER_TOKEN = 4;\n\n/** UTF-8 byte length, matching how the runtime measures raw payload size elsewhere. */\nexport function estimateByteLength(text: string): number {\n\treturn Buffer.byteLength(text, \"utf8\");\n}\n\nexport function estimateLineCount(text: string): number {\n\treturn text.length === 0 ? 0 : text.split(\"\\n\").length;\n}\n\n/**\n * No-tokenizer sizing rule from policy-engine-spec.md: estimatedTokens = ceil(chars / 4).\n * Calibrate against provider-reported usage post-call; never treat this as semantic criticality.\n */\nexport function estimateTokensFromChars(charCount: number): number {\n\treturn Math.ceil(Math.max(0, charCount) / NO_TOKENIZER_CHARS_PER_TOKEN);\n}\n\nexport function estimateTokensFromText(text: string): number {\n\treturn estimateTokensFromChars(text.length);\n}\n"]}

package/dist/core/context/context-prompt-enforcement.d.ts

@@ -0,0 +1,73 @@
+/**
+ * First enforcement pilot for the context-policy layer (opt-in, default disabled). Unlike
+ * context-audit.ts/context-prompt-policy.ts (both strictly observe-only), this module CAN
+ * change the provider-visible message array -- but only ever via stub-in-place on
+ * artifact-backed tool_output results, never by removing a message or breaking
+ * assistant/toolResult pairing. It never touches the transcript, never releases/reclaims
+ * artifact references, and never writes a new artifact -- it only replaces the visible
+ * text of an already artifact-backed message with a bounded pointer to the existing
+ * artifact, retrievable via the `artifact_retrieve` tool.
+ *
+ * Eligibility for stubbing is deliberately conservative (see `enforcePromptPolicy`): the
+ * setting must be enabled, the item must be outside the recent-message safety window, not
+ * an errored tool result, not already stubbed by this module or already packed by legacy
+ * context-gc this turn, must have a resolvable artifact id, the `artifact_retrieve` tool
+ * must actually be active this turn, and must clear `hardConstraints.dropFromPrompt` (see
+ * below for why that specific action, not `pack_to_artifact`).
+ *
+ * Why `dropFromPrompt`, not `packToArtifact`: this operation does not create a new
+ * artifact -- it reuses the ref an earlier `pack_to_artifact` capture already produced (see
+ * tool-output-artifacts.md's "measure -> digest/preview/artifact -> prompt item" pipeline).
+ * `drop_from_prompt` requires an existing retrieval path and is exactly the operation being
+ * performed (evicting raw content from the live prompt in favor of that existing path);
+ * `pack_to_artifact` is the distinct first-capture operation, which we never invoke here.
+ *
+ * Why `retrievalToolAvailable` is checked separately from `hasAvailableRetrievalPath`: the
+ * latter only proves the artifact still exists in the store; it says nothing about whether
+ * the model can currently act on the stub's instruction to call `artifact_retrieve`.
+ * `artifact_retrieve` is a companion affordance (auto-activated alongside grep/find, not a
+ * default/global tool -- see agent-session.ts's companion-activation enforcement), so active
+ * tools can differ turn to turn. Stubbing content with an unactionable pointer would be
+ * strictly worse than leaving the raw content in place.
+ */
+import type { AgentMessage } from "@caupulican/pi-agent-core";
+import type { PromptPolicyShadowReport } from "./context-prompt-policy.ts";
+export interface ContextPromptEnforcementSettings {
+    enabled: boolean;
+    preserveRecentMessages: number;
+    minChars: number;
+    /**
+     * Whether the `artifact_retrieve` tool is actually active this turn -- a runtime fact,
+     * not a persisted setting. Callers must derive this from the live active-tool set (e.g.
+     * `AgentSession.getActiveToolNames().includes("artifact_retrieve")`), never assume it.
+     */
+    retrievalToolAvailable: boolean;
+}
+export type PromptEnforcementSkipReason = "message_mismatch" | "within_recent_window" | "errored_tool_result" | "already_stubbed_or_packed" | "not_artifact_backed" | "retrieval_tool_unavailable" | "hard_constraint_rejected" | "missing_artifact_id" | "below_min_chars";
+export interface PromptEnforcementItemReport {
+    itemId: string;
+    toolCallId: string;
+    messageIndex: number;
+    enforced: boolean;
+    action?: "artifact_stub";
+    artifactId?: string;
+    originalChars?: number;
+    skipReason?: PromptEnforcementSkipReason;
+}
+export interface PromptEnforcementReport {
+    turnIndex: number;
+    items: PromptEnforcementItemReport[];
+}
+export interface EnforcePromptPolicyResult {
+    messages: AgentMessage[];
+    report: PromptEnforcementReport;
+}
+/**
+ * Apply the first enforcement pilot to `messages` (expected to be the provider-visible
+ * array after existing context-gc has already run). Returns a new array only when at least
+ * one item was actually stubbed; otherwise returns the same `messages` reference unchanged
+ * (in particular, always true when `settings.enabled` is false). Never mutates `messages`
+ * or any message object within it -- every stubbed entry is a fresh object.
+ */
+export declare function enforcePromptPolicy(messages: AgentMessage[], shadowReport: PromptPolicyShadowReport, settings: ContextPromptEnforcementSettings): EnforcePromptPolicyResult;
+//# sourceMappingURL=context-prompt-enforcement.d.ts.map

package/dist/core/context/context-prompt-enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-prompt-enforcement.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-prompt-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAE3E,MAAM,WAAW,gCAAgC;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,sBAAsB,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,2BAA2B,GACpC,kBAAkB,GAClB,sBAAsB,GACtB,qBAAqB,GACrB,2BAA2B,GAC3B,qBAAqB,GACrB,4BAA4B,GAC5B,0BAA0B,GAC1B,qBAAqB,GACrB,iBAAiB,CAAC;AAErB,MAAM,WAAW,2BAA2B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,2BAA2B,CAAC;CACzC;AAED,MAAM,WAAW,uBAAuB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,2BAA2B,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACzC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,MAAM,EAAE,uBAAuB,CAAC;CAChC;AA0CD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,YAAY,EAAE,EACxB,YAAY,EAAE,wBAAwB,EACtC,QAAQ,EAAE,gCAAgC,GACxC,yBAAyB,CAkF3B","sourcesContent":["/**\n * First enforcement pilot for the context-policy layer (opt-in, default disabled). Unlike\n * context-audit.ts/context-prompt-policy.ts (both strictly observe-only), this module CAN\n * change the provider-visible message array -- but only ever via stub-in-place on\n * artifact-backed tool_output results, never by removing a message or breaking\n * assistant/toolResult pairing. It never touches the transcript, never releases/reclaims\n * artifact references, and never writes a new artifact -- it only replaces the visible\n * text of an already artifact-backed message with a bounded pointer to the existing\n * artifact, retrievable via the `artifact_retrieve` tool.\n *\n * Eligibility for stubbing is deliberately conservative (see `enforcePromptPolicy`): the\n * setting must be enabled, the item must be outside the recent-message safety window, not\n * an errored tool result, not already stubbed by this module or already packed by legacy\n * context-gc this turn, must have a resolvable artifact id, the `artifact_retrieve` tool\n * must actually be active this turn, and must clear `hardConstraints.dropFromPrompt` (see\n * below for why that specific action, not `pack_to_artifact`).\n *\n * Why `dropFromPrompt`, not `packToArtifact`: this operation does not create a new\n * artifact -- it reuses the ref an earlier `pack_to_artifact` capture already produced (see\n * tool-output-artifacts.md's \"measure -> digest/preview/artifact -> prompt item\" pipeline).\n * `drop_from_prompt` requires an existing retrieval path and is exactly the operation being\n * performed (evicting raw content from the live prompt in favor of that existing path);\n * `pack_to_artifact` is the distinct first-capture operation, which we never invoke here.\n *\n * Why `retrievalToolAvailable` is checked separately from `hasAvailableRetrievalPath`: the\n * latter only proves the artifact still exists in the store; it says nothing about whether\n * the model can currently act on the stub's instruction to call `artifact_retrieve`.\n * `artifact_retrieve` is a companion affordance (auto-activated alongside grep/find, not a\n * default/global tool -- see agent-session.ts's companion-activation enforcement), so active\n * tools can differ turn to turn. Stubbing content with an unactionable pointer would be\n * strictly worse than leaving the raw content in place.\n */\n\nimport type { AgentMessage } from \"@caupulican/pi-agent-core\";\nimport type { ToolResultMessage } from \"@caupulican/pi-ai\";\nimport type { PromptPolicyShadowReport } from \"./context-prompt-policy.ts\";\n\nexport interface ContextPromptEnforcementSettings {\n\tenabled: boolean;\n\tpreserveRecentMessages: number;\n\tminChars: number;\n\t/**\n\t * Whether the `artifact_retrieve` tool is actually active this turn -- a runtime fact,\n\t * not a persisted setting. Callers must derive this from the live active-tool set (e.g.\n\t * `AgentSession.getActiveToolNames().includes(\"artifact_retrieve\")`), never assume it.\n\t */\n\tretrievalToolAvailable: boolean;\n}\n\nexport type PromptEnforcementSkipReason =\n\t| \"message_mismatch\"\n\t| \"within_recent_window\"\n\t| \"errored_tool_result\"\n\t| \"already_stubbed_or_packed\"\n\t| \"not_artifact_backed\"\n\t| \"retrieval_tool_unavailable\"\n\t| \"hard_constraint_rejected\"\n\t| \"missing_artifact_id\"\n\t| \"below_min_chars\";\n\nexport interface PromptEnforcementItemReport {\n\titemId: string;\n\ttoolCallId: string;\n\tmessageIndex: number;\n\tenforced: boolean;\n\taction?: \"artifact_stub\";\n\tartifactId?: string;\n\toriginalChars?: number;\n\tskipReason?: PromptEnforcementSkipReason;\n}\n\nexport interface PromptEnforcementReport {\n\tturnIndex: number;\n\titems: PromptEnforcementItemReport[];\n}\n\nexport interface EnforcePromptPolicyResult {\n\tmessages: AgentMessage[];\n\treport: PromptEnforcementReport;\n}\n\nfunction extractDetailsArtifactId(details: unknown): string | undefined {\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\n/** True if legacy context-gc already packed this message this turn, or this module already stubbed it. */\nfunction isAlreadyStubbedOrPacked(details: unknown): boolean {\n\tif (typeof details !== \"object\" || details === null) return false;\n\tconst record = details as { promptPolicy?: { enforced?: unknown }; contextGc?: { packed?: unknown } };\n\treturn record.promptPolicy?.enforced === true || record.contextGc?.packed === true;\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\nfunction buildStubText(toolName: string, originalChars: number, artifactId: string): string {\n\treturn `[content replaced by prompt-policy: originally ${originalChars} chars from a stale ${toolName} tool result. Retrieve the full output with artifact_retrieve using artifactId \"${artifactId}\".]`;\n}\n\nfunction skip(\n\titem: { itemId: string; toolCallId: string; messageIndex: number },\n\tskipReason: PromptEnforcementSkipReason,\n\textra?: { artifactId?: string; originalChars?: number },\n): PromptEnforcementItemReport {\n\treturn {\n\t\titemId: item.itemId,\n\t\ttoolCallId: item.toolCallId,\n\t\tmessageIndex: item.messageIndex,\n\t\tenforced: false,\n\t\tskipReason,\n\t\t...extra,\n\t};\n}\n\n/**\n * Apply the first enforcement pilot to `messages` (expected to be the provider-visible\n * array after existing context-gc has already run). Returns a new array only when at least\n * one item was actually stubbed; otherwise returns the same `messages` reference unchanged\n * (in particular, always true when `settings.enabled` is false). Never mutates `messages`\n * or any message object within it -- every stubbed entry is a fresh object.\n */\nexport function enforcePromptPolicy(\n\tmessages: AgentMessage[],\n\tshadowReport: PromptPolicyShadowReport,\n\tsettings: ContextPromptEnforcementSettings,\n): EnforcePromptPolicyResult {\n\tif (!settings.enabled) {\n\t\treturn { messages, report: { turnIndex: shadowReport.turnIndex, items: [] } };\n\t}\n\n\tconst recentCutoffIndex = Math.max(0, messages.length - settings.preserveRecentMessages);\n\tconst nextMessages = messages.slice();\n\tlet changed = false;\n\tconst items: PromptEnforcementItemReport[] = [];\n\n\tfor (const planItem of shadowReport.items) {\n\t\tconst message = messages[planItem.messageIndex];\n\t\tif (!message || message.role !== \"toolResult\" || message.toolCallId !== planItem.toolCallId) {\n\t\t\titems.push(skip(planItem, \"message_mismatch\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (planItem.messageIndex >= recentCutoffIndex) {\n\t\t\titems.push(skip(planItem, \"within_recent_window\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (message.isError) {\n\t\t\titems.push(skip(planItem, \"errored_tool_result\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (isAlreadyStubbedOrPacked(message.details)) {\n\t\t\titems.push(skip(planItem, \"already_stubbed_or_packed\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (!planItem.hasAvailableRetrievalPath) {\n\t\t\titems.push(skip(planItem, \"not_artifact_backed\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (!settings.retrievalToolAvailable) {\n\t\t\titems.push(skip(planItem, \"retrieval_tool_unavailable\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (planItem.hardConstraints.dropFromPrompt.length > 0) {\n\t\t\titems.push(skip(planItem, \"hard_constraint_rejected\"));\n\t\t\tcontinue;\n\t\t}\n\t\tconst artifactId = extractDetailsArtifactId(message.details);\n\t\tif (!artifactId) {\n\t\t\titems.push(skip(planItem, \"missing_artifact_id\"));\n\t\t\tcontinue;\n\t\t}\n\t\tconst originalChars = toolResultText(message).length;\n\t\tif (originalChars < settings.minChars) {\n\t\t\titems.push(skip(planItem, \"below_min_chars\", { artifactId, originalChars }));\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst existingDetails = typeof message.details === \"object\" && message.details !== null ? message.details : {};\n\t\tnextMessages[planItem.messageIndex] = {\n\t\t\t...message,\n\t\t\tcontent: [{ type: \"text\", text: buildStubText(message.toolName, originalChars, artifactId) }],\n\t\t\tdetails: {\n\t\t\t\t...existingDetails,\n\t\t\t\tpromptPolicy: {\n\t\t\t\t\tenforced: true,\n\t\t\t\t\taction: \"artifact_stub\",\n\t\t\t\t\tartifactId,\n\t\t\t\t\toriginalChars,\n\t\t\t\t\treason: \"stale_artifact_backed_tool_output\",\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t\tchanged = true;\n\t\titems.push({\n\t\t\titemId: planItem.itemId,\n\t\t\ttoolCallId: planItem.toolCallId,\n\t\t\tmessageIndex: planItem.messageIndex,\n\t\t\tenforced: true,\n\t\t\taction: \"artifact_stub\",\n\t\t\tartifactId,\n\t\t\toriginalChars,\n\t\t});\n\t}\n\n\treturn {\n\t\tmessages: changed ? nextMessages : messages,\n\t\treport: { turnIndex: shadowReport.turnIndex, items },\n\t};\n}\n"]}

package/dist/core/context/context-prompt-enforcement.js

@@ -0,0 +1,153 @@
+/**
+ * First enforcement pilot for the context-policy layer (opt-in, default disabled). Unlike
+ * context-audit.ts/context-prompt-policy.ts (both strictly observe-only), this module CAN
+ * change the provider-visible message array -- but only ever via stub-in-place on
+ * artifact-backed tool_output results, never by removing a message or breaking
+ * assistant/toolResult pairing. It never touches the transcript, never releases/reclaims
+ * artifact references, and never writes a new artifact -- it only replaces the visible
+ * text of an already artifact-backed message with a bounded pointer to the existing
+ * artifact, retrievable via the `artifact_retrieve` tool.
+ *
+ * Eligibility for stubbing is deliberately conservative (see `enforcePromptPolicy`): the
+ * setting must be enabled, the item must be outside the recent-message safety window, not
+ * an errored tool result, not already stubbed by this module or already packed by legacy
+ * context-gc this turn, must have a resolvable artifact id, the `artifact_retrieve` tool
+ * must actually be active this turn, and must clear `hardConstraints.dropFromPrompt` (see
+ * below for why that specific action, not `pack_to_artifact`).
+ *
+ * Why `dropFromPrompt`, not `packToArtifact`: this operation does not create a new
+ * artifact -- it reuses the ref an earlier `pack_to_artifact` capture already produced (see
+ * tool-output-artifacts.md's "measure -> digest/preview/artifact -> prompt item" pipeline).
+ * `drop_from_prompt` requires an existing retrieval path and is exactly the operation being
+ * performed (evicting raw content from the live prompt in favor of that existing path);
+ * `pack_to_artifact` is the distinct first-capture operation, which we never invoke here.
+ *
+ * Why `retrievalToolAvailable` is checked separately from `hasAvailableRetrievalPath`: the
+ * latter only proves the artifact still exists in the store; it says nothing about whether
+ * the model can currently act on the stub's instruction to call `artifact_retrieve`.
+ * `artifact_retrieve` is a companion affordance (auto-activated alongside grep/find, not a
+ * default/global tool -- see agent-session.ts's companion-activation enforcement), so active
+ * tools can differ turn to turn. Stubbing content with an unactionable pointer would be
+ * strictly worse than leaving the raw content in place.
+ */
+function extractDetailsArtifactId(details) {
+    if (typeof details !== "object" || details === null)
+        return undefined;
+    const artifactId = details.artifactId;
+    return typeof artifactId === "string" ? artifactId : undefined;
+}
+/** True if legacy context-gc already packed this message this turn, or this module already stubbed it. */
+function isAlreadyStubbedOrPacked(details) {
+    if (typeof details !== "object" || details === null)
+        return false;
+    const record = details;
+    return record.promptPolicy?.enforced === true || record.contextGc?.packed === true;
+}
+function toolResultText(message) {
+    const parts = [];
+    for (const part of message.content) {
+        if (part.type === "text")
+            parts.push(part.text);
+    }
+    return parts.join("\n");
+}
+function buildStubText(toolName, originalChars, artifactId) {
+    return `[content replaced by prompt-policy: originally ${originalChars} chars from a stale ${toolName} tool result. Retrieve the full output with artifact_retrieve using artifactId "${artifactId}".]`;
+}
+function skip(item, skipReason, extra) {
+    return {
+        itemId: item.itemId,
+        toolCallId: item.toolCallId,
+        messageIndex: item.messageIndex,
+        enforced: false,
+        skipReason,
+        ...extra,
+    };
+}
+/**
+ * Apply the first enforcement pilot to `messages` (expected to be the provider-visible
+ * array after existing context-gc has already run). Returns a new array only when at least
+ * one item was actually stubbed; otherwise returns the same `messages` reference unchanged
+ * (in particular, always true when `settings.enabled` is false). Never mutates `messages`
+ * or any message object within it -- every stubbed entry is a fresh object.
+ */
+export function enforcePromptPolicy(messages, shadowReport, settings) {
+    if (!settings.enabled) {
+        return { messages, report: { turnIndex: shadowReport.turnIndex, items: [] } };
+    }
+    const recentCutoffIndex = Math.max(0, messages.length - settings.preserveRecentMessages);
+    const nextMessages = messages.slice();
+    let changed = false;
+    const items = [];
+    for (const planItem of shadowReport.items) {
+        const message = messages[planItem.messageIndex];
+        if (!message || message.role !== "toolResult" || message.toolCallId !== planItem.toolCallId) {
+            items.push(skip(planItem, "message_mismatch"));
+            continue;
+        }
+        if (planItem.messageIndex >= recentCutoffIndex) {
+            items.push(skip(planItem, "within_recent_window"));
+            continue;
+        }
+        if (message.isError) {
+            items.push(skip(planItem, "errored_tool_result"));
+            continue;
+        }
+        if (isAlreadyStubbedOrPacked(message.details)) {
+            items.push(skip(planItem, "already_stubbed_or_packed"));
+            continue;
+        }
+        if (!planItem.hasAvailableRetrievalPath) {
+            items.push(skip(planItem, "not_artifact_backed"));
+            continue;
+        }
+        if (!settings.retrievalToolAvailable) {
+            items.push(skip(planItem, "retrieval_tool_unavailable"));
+            continue;
+        }
+        if (planItem.hardConstraints.dropFromPrompt.length > 0) {
+            items.push(skip(planItem, "hard_constraint_rejected"));
+            continue;
+        }
+        const artifactId = extractDetailsArtifactId(message.details);
+        if (!artifactId) {
+            items.push(skip(planItem, "missing_artifact_id"));
+            continue;
+        }
+        const originalChars = toolResultText(message).length;
+        if (originalChars < settings.minChars) {
+            items.push(skip(planItem, "below_min_chars", { artifactId, originalChars }));
+            continue;
+        }
+        const existingDetails = typeof message.details === "object" && message.details !== null ? message.details : {};
+        nextMessages[planItem.messageIndex] = {
+            ...message,
+            content: [{ type: "text", text: buildStubText(message.toolName, originalChars, artifactId) }],
+            details: {
+                ...existingDetails,
+                promptPolicy: {
+                    enforced: true,
+                    action: "artifact_stub",
+                    artifactId,
+                    originalChars,
+                    reason: "stale_artifact_backed_tool_output",
+                },
+            },
+        };
+        changed = true;
+        items.push({
+            itemId: planItem.itemId,
+            toolCallId: planItem.toolCallId,
+            messageIndex: planItem.messageIndex,
+            enforced: true,
+            action: "artifact_stub",
+            artifactId,
+            originalChars,
+        });
+    }
+    return {
+        messages: changed ? nextMessages : messages,
+        report: { turnIndex: shadowReport.turnIndex, items },
+    };
+}
+//# sourceMappingURL=context-prompt-enforcement.js.map

package/dist/core/context/context-prompt-enforcement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-prompt-enforcement.js","sourceRoot":"","sources":["../../../src/core/context/context-prompt-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAkDH,SAAS,wBAAwB,CAAC,OAAgB,EAAsB;IACvE,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACtE,MAAM,UAAU,GAAI,OAAoC,CAAC,UAAU,CAAC;IACpE,OAAO,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CAC/D;AAED,0GAA0G;AAC1G,SAAS,wBAAwB,CAAC,OAAgB,EAAW;IAC5D,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClE,MAAM,MAAM,GAAG,OAAsF,CAAC;IACtG,OAAO,MAAM,CAAC,YAAY,EAAE,QAAQ,KAAK,IAAI,IAAI,MAAM,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;AAAA,CACnF;AAED,SAAS,cAAc,CAAC,OAA0B,EAAU;IAC3D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CACxB;AAED,SAAS,aAAa,CAAC,QAAgB,EAAE,aAAqB,EAAE,UAAkB,EAAU;IAC3F,OAAO,kDAAkD,aAAa,uBAAuB,QAAQ,mFAAmF,UAAU,KAAK,CAAC;AAAA,CACxM;AAED,SAAS,IAAI,CACZ,IAAkE,EAClE,UAAuC,EACvC,KAAuD,EACzB;IAC9B,OAAO;QACN,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,QAAQ,EAAE,KAAK;QACf,UAAU;QACV,GAAG,KAAK;KACR,CAAC;AAAA,CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAClC,QAAwB,EACxB,YAAsC,EACtC,QAA0C,EACd;IAC5B,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC;IAC/E,CAAC;IAED,MAAM,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IACzF,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;IACtC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,KAAK,GAAkC,EAAE,CAAC;IAEhD,KAAK,MAAM,QAAQ,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QAChD,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY,IAAI,OAAO,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;YAC7F,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC;YAC/C,SAAS;QACV,CAAC;QACD,IAAI,QAAQ,CAAC,YAAY,IAAI,iBAAiB,EAAE,CAAC;YAChD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC;YACnD,SAAS;QACV,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC;YAClD,SAAS;QACV,CAAC;QACD,IAAI,wBAAwB,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,2BAA2B,CAAC,CAAC,CAAC;YACxD,SAAS;QACV,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,yBAAyB,EAAE,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC;YAClD,SAAS;QACV,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,sBAAsB,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,4BAA4B,CAAC,CAAC,CAAC;YACzD,SAAS;QACV,CAAC;QACD,IAAI,QAAQ,CAAC,eAAe,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,0BAA0B,CAAC,CAAC,CAAC;YACvD,SAAS;QACV,CAAC;QACD,MAAM,UAAU,GAAG,wBAAwB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC7D,IAAI,CAAC,UAAU,EAAE,CAAC;YACjB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC;YAClD,SAAS;QACV,CAAC;QACD,MAAM,aAAa,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QACrD,IAAI,aAAa,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,iBAAiB,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;YAC7E,SAAS;QACV,CAAC;QAED,MAAM,eAAe,GAAG,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/G,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC,GAAG;YACrC,GAAG,OAAO;YACV,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,CAAC;YAC7F,OAAO,EAAE;gBACR,GAAG,eAAe;gBAClB,YAAY,EAAE;oBACb,QAAQ,EAAE,IAAI;oBACd,MAAM,EAAE,eAAe;oBACvB,UAAU;oBACV,aAAa;oBACb,MAAM,EAAE,mCAAmC;iBAC3C;aACD;SACD,CAAC;QACF,OAAO,GAAG,IAAI,CAAC;QACf,KAAK,CAAC,IAAI,CAAC;YACV,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,eAAe;YACvB,UAAU;YACV,aAAa;SACb,CAAC,CAAC;IACJ,CAAC;IAED,OAAO;QACN,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ;QAC3C,MAAM,EAAE,EAAE,SAAS,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE;KACpD,CAAC;AAAA,CACF","sourcesContent":["/**\n * First enforcement pilot for the context-policy layer (opt-in, default disabled). Unlike\n * context-audit.ts/context-prompt-policy.ts (both strictly observe-only), this module CAN\n * change the provider-visible message array -- but only ever via stub-in-place on\n * artifact-backed tool_output results, never by removing a message or breaking\n * assistant/toolResult pairing. It never touches the transcript, never releases/reclaims\n * artifact references, and never writes a new artifact -- it only replaces the visible\n * text of an already artifact-backed message with a bounded pointer to the existing\n * artifact, retrievable via the `artifact_retrieve` tool.\n *\n * Eligibility for stubbing is deliberately conservative (see `enforcePromptPolicy`): the\n * setting must be enabled, the item must be outside the recent-message safety window, not\n * an errored tool result, not already stubbed by this module or already packed by legacy\n * context-gc this turn, must have a resolvable artifact id, the `artifact_retrieve` tool\n * must actually be active this turn, and must clear `hardConstraints.dropFromPrompt` (see\n * below for why that specific action, not `pack_to_artifact`).\n *\n * Why `dropFromPrompt`, not `packToArtifact`: this operation does not create a new\n * artifact -- it reuses the ref an earlier `pack_to_artifact` capture already produced (see\n * tool-output-artifacts.md's \"measure -> digest/preview/artifact -> prompt item\" pipeline).\n * `drop_from_prompt` requires an existing retrieval path and is exactly the operation being\n * performed (evicting raw content from the live prompt in favor of that existing path);\n * `pack_to_artifact` is the distinct first-capture operation, which we never invoke here.\n *\n * Why `retrievalToolAvailable` is checked separately from `hasAvailableRetrievalPath`: the\n * latter only proves the artifact still exists in the store; it says nothing about whether\n * the model can currently act on the stub's instruction to call `artifact_retrieve`.\n * `artifact_retrieve` is a companion affordance (auto-activated alongside grep/find, not a\n * default/global tool -- see agent-session.ts's companion-activation enforcement), so active\n * tools can differ turn to turn. Stubbing content with an unactionable pointer would be\n * strictly worse than leaving the raw content in place.\n */\n\nimport type { AgentMessage } from \"@caupulican/pi-agent-core\";\nimport type { ToolResultMessage } from \"@caupulican/pi-ai\";\nimport type { PromptPolicyShadowReport } from \"./context-prompt-policy.ts\";\n\nexport interface ContextPromptEnforcementSettings {\n\tenabled: boolean;\n\tpreserveRecentMessages: number;\n\tminChars: number;\n\t/**\n\t * Whether the `artifact_retrieve` tool is actually active this turn -- a runtime fact,\n\t * not a persisted setting. Callers must derive this from the live active-tool set (e.g.\n\t * `AgentSession.getActiveToolNames().includes(\"artifact_retrieve\")`), never assume it.\n\t */\n\tretrievalToolAvailable: boolean;\n}\n\nexport type PromptEnforcementSkipReason =\n\t| \"message_mismatch\"\n\t| \"within_recent_window\"\n\t| \"errored_tool_result\"\n\t| \"already_stubbed_or_packed\"\n\t| \"not_artifact_backed\"\n\t| \"retrieval_tool_unavailable\"\n\t| \"hard_constraint_rejected\"\n\t| \"missing_artifact_id\"\n\t| \"below_min_chars\";\n\nexport interface PromptEnforcementItemReport {\n\titemId: string;\n\ttoolCallId: string;\n\tmessageIndex: number;\n\tenforced: boolean;\n\taction?: \"artifact_stub\";\n\tartifactId?: string;\n\toriginalChars?: number;\n\tskipReason?: PromptEnforcementSkipReason;\n}\n\nexport interface PromptEnforcementReport {\n\tturnIndex: number;\n\titems: PromptEnforcementItemReport[];\n}\n\nexport interface EnforcePromptPolicyResult {\n\tmessages: AgentMessage[];\n\treport: PromptEnforcementReport;\n}\n\nfunction extractDetailsArtifactId(details: unknown): string | undefined {\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\n/** True if legacy context-gc already packed this message this turn, or this module already stubbed it. */\nfunction isAlreadyStubbedOrPacked(details: unknown): boolean {\n\tif (typeof details !== \"object\" || details === null) return false;\n\tconst record = details as { promptPolicy?: { enforced?: unknown }; contextGc?: { packed?: unknown } };\n\treturn record.promptPolicy?.enforced === true || record.contextGc?.packed === true;\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\nfunction buildStubText(toolName: string, originalChars: number, artifactId: string): string {\n\treturn `[content replaced by prompt-policy: originally ${originalChars} chars from a stale ${toolName} tool result. Retrieve the full output with artifact_retrieve using artifactId \"${artifactId}\".]`;\n}\n\nfunction skip(\n\titem: { itemId: string; toolCallId: string; messageIndex: number },\n\tskipReason: PromptEnforcementSkipReason,\n\textra?: { artifactId?: string; originalChars?: number },\n): PromptEnforcementItemReport {\n\treturn {\n\t\titemId: item.itemId,\n\t\ttoolCallId: item.toolCallId,\n\t\tmessageIndex: item.messageIndex,\n\t\tenforced: false,\n\t\tskipReason,\n\t\t...extra,\n\t};\n}\n\n/**\n * Apply the first enforcement pilot to `messages` (expected to be the provider-visible\n * array after existing context-gc has already run). Returns a new array only when at least\n * one item was actually stubbed; otherwise returns the same `messages` reference unchanged\n * (in particular, always true when `settings.enabled` is false). Never mutates `messages`\n * or any message object within it -- every stubbed entry is a fresh object.\n */\nexport function enforcePromptPolicy(\n\tmessages: AgentMessage[],\n\tshadowReport: PromptPolicyShadowReport,\n\tsettings: ContextPromptEnforcementSettings,\n): EnforcePromptPolicyResult {\n\tif (!settings.enabled) {\n\t\treturn { messages, report: { turnIndex: shadowReport.turnIndex, items: [] } };\n\t}\n\n\tconst recentCutoffIndex = Math.max(0, messages.length - settings.preserveRecentMessages);\n\tconst nextMessages = messages.slice();\n\tlet changed = false;\n\tconst items: PromptEnforcementItemReport[] = [];\n\n\tfor (const planItem of shadowReport.items) {\n\t\tconst message = messages[planItem.messageIndex];\n\t\tif (!message || message.role !== \"toolResult\" || message.toolCallId !== planItem.toolCallId) {\n\t\t\titems.push(skip(planItem, \"message_mismatch\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (planItem.messageIndex >= recentCutoffIndex) {\n\t\t\titems.push(skip(planItem, \"within_recent_window\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (message.isError) {\n\t\t\titems.push(skip(planItem, \"errored_tool_result\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (isAlreadyStubbedOrPacked(message.details)) {\n\t\t\titems.push(skip(planItem, \"already_stubbed_or_packed\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (!planItem.hasAvailableRetrievalPath) {\n\t\t\titems.push(skip(planItem, \"not_artifact_backed\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (!settings.retrievalToolAvailable) {\n\t\t\titems.push(skip(planItem, \"retrieval_tool_unavailable\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (planItem.hardConstraints.dropFromPrompt.length > 0) {\n\t\t\titems.push(skip(planItem, \"hard_constraint_rejected\"));\n\t\t\tcontinue;\n\t\t}\n\t\tconst artifactId = extractDetailsArtifactId(message.details);\n\t\tif (!artifactId) {\n\t\t\titems.push(skip(planItem, \"missing_artifact_id\"));\n\t\t\tcontinue;\n\t\t}\n\t\tconst originalChars = toolResultText(message).length;\n\t\tif (originalChars < settings.minChars) {\n\t\t\titems.push(skip(planItem, \"below_min_chars\", { artifactId, originalChars }));\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst existingDetails = typeof message.details === \"object\" && message.details !== null ? message.details : {};\n\t\tnextMessages[planItem.messageIndex] = {\n\t\t\t...message,\n\t\t\tcontent: [{ type: \"text\", text: buildStubText(message.toolName, originalChars, artifactId) }],\n\t\t\tdetails: {\n\t\t\t\t...existingDetails,\n\t\t\t\tpromptPolicy: {\n\t\t\t\t\tenforced: true,\n\t\t\t\t\taction: \"artifact_stub\",\n\t\t\t\t\tartifactId,\n\t\t\t\t\toriginalChars,\n\t\t\t\t\treason: \"stale_artifact_backed_tool_output\",\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t\tchanged = true;\n\t\titems.push({\n\t\t\titemId: planItem.itemId,\n\t\t\ttoolCallId: planItem.toolCallId,\n\t\t\tmessageIndex: planItem.messageIndex,\n\t\t\tenforced: true,\n\t\t\taction: \"artifact_stub\",\n\t\t\tartifactId,\n\t\t\toriginalChars,\n\t\t});\n\t}\n\n\treturn {\n\t\tmessages: changed ? nextMessages : messages,\n\t\treport: { turnIndex: shadowReport.turnIndex, items },\n\t};\n}\n"]}

package/dist/core/context/context-prompt-policy.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Observe-first shadow/planning layer, one step closer to prompt construction than
+ * context-audit.ts (Phase 1). This module re-shapes an already-computed `ContextAuditReport`
+ * into a deterministic per-item policy plan, and can correlate that plan against the
+ * legacy context-gc's actual packed records. It never enforces anything: `appliedAction` is
+ * a literal `"keep_raw"` on every item -- the type itself makes it impossible for this
+ * module to report having changed prompt behavior. Nothing here mutates messages, the
+ * transcript, or artifact references; it only reads an already-computed report.
+ *
+ * Single source of truth for feature/flag construction remains context-audit.ts
+ * (`buildPolicyFeatures`/`buildHardConstraintFlags`): this module reuses the hard-constraint
+ * codes already computed there rather than reconstructing them, so there is exactly one
+ * place that decides how a tool_output item's PolicyFeatures/HardConstraintFlags are built.
+ */
+import type { ContextGcPackedRecord, ContextGcReport } from "../context-gc.ts";
+import type { ContextAuditReport } from "./context-audit.ts";
+import type { ContextEvidenceRef, ContextItemKind, ContextRetentionClass, ContextSource } from "./context-item.ts";
+import type { RetentionAction } from "./context-retention.ts";
+import type { PolicyHardConstraintCode } from "./policy-types.ts";
+export interface PromptPolicyHardConstraints {
+    keepRaw: PolicyHardConstraintCode[];
+    packToArtifact: PolicyHardConstraintCode[];
+    dropFromPrompt: PolicyHardConstraintCode[];
+    summarize: PolicyHardConstraintCode[];
+}
+export interface PromptPolicyItemReport {
+    itemId: string;
+    kind: ContextItemKind;
+    retentionClass: ContextRetentionClass;
+    source: ContextSource;
+    toolCallId: string;
+    messageIndex: number;
+    primaryRefType: ContextEvidenceRef["type"] | undefined;
+    /**
+     * True only for a resolved artifact ref, never for a transcript ref -- the same
+     * fail-closed resolved-artifact-only rule context-audit.ts uses (a transcript ref is
+     * provenance, not a live retrieval mechanism; see that module's doc comment).
+     */
+    hasAvailableRetrievalPath: boolean;
+    /** Coarse, store-free eligibility from context-retention.ts (treats any ref as retrievable). */
+    allowedRetentionActions: RetentionAction[];
+    hardConstraints: PromptPolicyHardConstraints;
+    /**
+     * This shadow/planning pass never changes behavior: the applied action is always
+     * "keep_raw", regardless of what the hard-constraint/retention analysis above would
+     * otherwise allow. Typed as a literal so nothing here can ever report applying anything
+     * else.
+     */
+    appliedAction: "keep_raw";
+}
+export interface PromptPolicyShadowReport {
+    turnIndex: number;
+    items: PromptPolicyItemReport[];
+}
+/**
+ * Deterministic re-shaping of an audit report into the shadow policy plan shape. Pure: no
+ * I/O, no mutation, given the same audit report this always returns an equal result.
+ */
+export declare function planPromptPolicy(auditReport: ContextAuditReport): PromptPolicyShadowReport;
+export interface PromptPolicyGcCorrelationEntry {
+    itemId: string;
+    toolCallId: string;
+    /** True if the legacy context-gc pass actually packed this item's tool result this turn. */
+    actuallyPackedByLegacyGc: boolean;
+    gcPackReason?: ContextGcPackedRecord["reason"];
+    /** True if the shadow plan's pack_to_artifact hard constraints did not reject packing. */
+    policyWouldAllowPack: boolean;
+    /** True if the shadow plan's drop_from_prompt hard constraints did not reject dropping. */
+    policyWouldAllowDrop: boolean;
+}
+export interface PromptPolicyGcCorrelationReport {
+    turnIndex: number;
+    entries: PromptPolicyGcCorrelationEntry[];
+}
+/**
+ * Report-only correlation between the shadow plan and what the legacy context-gc pass
+ * actually did this turn. Does not influence context-gc in any way -- it runs after gc has
+ * already produced its report, purely to observe what each side did/would do.
+ *
+ * Deliberately does not derive an "agrees with legacy gc" boolean: legacy context-gc
+ * "packing" summarizes/stubs a tool result in place (provider-visible content shrinks in
+ * place), while the policy action `pack_to_artifact` means artifact-backed capture and
+ * out-of-band retrieval -- a different operation with different semantics, not a
+ * calibrated equivalent. Collapsing them into one "agreement" boolean would overclaim
+ * semantic agreement between the two and risk a later enforcement slice mistaking this
+ * observe-only diagnostic for a calibrated authority. The raw booleans below are reported
+ * as-is; comparing them is left to the reader.
+ */
+export declare function correlateWithContextGc(shadowReport: PromptPolicyShadowReport, gcReport: ContextGcReport): PromptPolicyGcCorrelationReport;
+//# sourceMappingURL=context-prompt-policy.d.ts.map

package/dist/core/context/context-prompt-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-prompt-policy.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-prompt-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACnH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElE,MAAM,WAAW,2BAA2B;IAC3C,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,cAAc,EAAE,wBAAwB,EAAE,CAAC;IAC3C,cAAc,EAAE,wBAAwB,EAAE,CAAC;IAC3C,SAAS,EAAE,wBAAwB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,eAAe,CAAC;IACtB,cAAc,EAAE,qBAAqB,CAAC;IACtC,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACvD;;;;OAIG;IACH,yBAAyB,EAAE,OAAO,CAAC;IACnC,gGAAgG;IAChG,uBAAuB,EAAE,eAAe,EAAE,CAAC;IAC3C,eAAe,EAAE,2BAA2B,CAAC;IAC7C;;;;;OAKG;IACH,aAAa,EAAE,UAAU,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,sBAAsB,EAAE,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,kBAAkB,GAAG,wBAAwB,CAsB1F;AAED,MAAM,WAAW,8BAA8B;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,wBAAwB,EAAE,OAAO,CAAC;IAClC,YAAY,CAAC,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAC/C,0FAA0F;IAC1F,oBAAoB,EAAE,OAAO,CAAC;IAC9B,2FAA2F;IAC3F,oBAAoB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,+BAA+B;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,8BAA8B,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACrC,YAAY,EAAE,wBAAwB,EACtC,QAAQ,EAAE,eAAe,GACvB,+BAA+B,CAiBjC","sourcesContent":["/**\n * Observe-first shadow/planning layer, one step closer to prompt construction than\n * context-audit.ts (Phase 1). This module re-shapes an already-computed `ContextAuditReport`\n * into a deterministic per-item policy plan, and can correlate that plan against the\n * legacy context-gc's actual packed records. It never enforces anything: `appliedAction` is\n * a literal `\"keep_raw\"` on every item -- the type itself makes it impossible for this\n * module to report having changed prompt behavior. Nothing here mutates messages, the\n * transcript, or artifact references; it only reads an already-computed report.\n *\n * Single source of truth for feature/flag construction remains context-audit.ts\n * (`buildPolicyFeatures`/`buildHardConstraintFlags`): this module reuses the hard-constraint\n * codes already computed there rather than reconstructing them, so there is exactly one\n * place that decides how a tool_output item's PolicyFeatures/HardConstraintFlags are built.\n */\n\nimport type { ContextGcPackedRecord, ContextGcReport } from \"../context-gc.ts\";\nimport type { ContextAuditReport } from \"./context-audit.ts\";\nimport type { ContextEvidenceRef, ContextItemKind, ContextRetentionClass, ContextSource } from \"./context-item.ts\";\nimport type { RetentionAction } from \"./context-retention.ts\";\nimport type { PolicyHardConstraintCode } from \"./policy-types.ts\";\n\nexport interface PromptPolicyHardConstraints {\n\tkeepRaw: PolicyHardConstraintCode[];\n\tpackToArtifact: PolicyHardConstraintCode[];\n\tdropFromPrompt: PolicyHardConstraintCode[];\n\tsummarize: PolicyHardConstraintCode[];\n}\n\nexport interface PromptPolicyItemReport {\n\titemId: string;\n\tkind: ContextItemKind;\n\tretentionClass: ContextRetentionClass;\n\tsource: ContextSource;\n\ttoolCallId: string;\n\tmessageIndex: number;\n\tprimaryRefType: ContextEvidenceRef[\"type\"] | undefined;\n\t/**\n\t * True only for a resolved artifact ref, never for a transcript ref -- the same\n\t * fail-closed resolved-artifact-only rule context-audit.ts uses (a transcript ref is\n\t * provenance, not a live retrieval mechanism; see that module's doc comment).\n\t */\n\thasAvailableRetrievalPath: boolean;\n\t/** Coarse, store-free eligibility from context-retention.ts (treats any ref as retrievable). */\n\tallowedRetentionActions: RetentionAction[];\n\thardConstraints: PromptPolicyHardConstraints;\n\t/**\n\t * This shadow/planning pass never changes behavior: the applied action is always\n\t * \"keep_raw\", regardless of what the hard-constraint/retention analysis above would\n\t * otherwise allow. Typed as a literal so nothing here can ever report applying anything\n\t * else.\n\t */\n\tappliedAction: \"keep_raw\";\n}\n\nexport interface PromptPolicyShadowReport {\n\tturnIndex: number;\n\titems: PromptPolicyItemReport[];\n}\n\n/**\n * Deterministic re-shaping of an audit report into the shadow policy plan shape. Pure: no\n * I/O, no mutation, given the same audit report this always returns an equal result.\n */\nexport function planPromptPolicy(auditReport: ContextAuditReport): PromptPolicyShadowReport {\n\treturn {\n\t\tturnIndex: auditReport.turnIndex,\n\t\titems: auditReport.items.map((entry) => ({\n\t\t\titemId: entry.item.id,\n\t\t\tkind: entry.item.kind,\n\t\t\tretentionClass: entry.item.retentionClass,\n\t\t\tsource: entry.item.source,\n\t\t\ttoolCallId: entry.toolCallId,\n\t\t\tmessageIndex: entry.messageIndex,\n\t\t\tprimaryRefType: entry.item.primaryRef?.type,\n\t\t\thasAvailableRetrievalPath: entry.item.primaryRef?.type === \"artifact\",\n\t\t\tallowedRetentionActions: entry.retention.allowedActions,\n\t\t\thardConstraints: {\n\t\t\t\tkeepRaw: entry.keepRawHardConstraints,\n\t\t\t\tpackToArtifact: entry.packToArtifactHardConstraints,\n\t\t\t\tdropFromPrompt: entry.dropFromPromptHardConstraints,\n\t\t\t\tsummarize: entry.summarizeHardConstraints,\n\t\t\t},\n\t\t\tappliedAction: \"keep_raw\",\n\t\t})),\n\t};\n}\n\nexport interface PromptPolicyGcCorrelationEntry {\n\titemId: string;\n\ttoolCallId: string;\n\t/** True if the legacy context-gc pass actually packed this item's tool result this turn. */\n\tactuallyPackedByLegacyGc: boolean;\n\tgcPackReason?: ContextGcPackedRecord[\"reason\"];\n\t/** True if the shadow plan's pack_to_artifact hard constraints did not reject packing. */\n\tpolicyWouldAllowPack: boolean;\n\t/** True if the shadow plan's drop_from_prompt hard constraints did not reject dropping. */\n\tpolicyWouldAllowDrop: boolean;\n}\n\nexport interface PromptPolicyGcCorrelationReport {\n\tturnIndex: number;\n\tentries: PromptPolicyGcCorrelationEntry[];\n}\n\n/**\n * Report-only correlation between the shadow plan and what the legacy context-gc pass\n * actually did this turn. Does not influence context-gc in any way -- it runs after gc has\n * already produced its report, purely to observe what each side did/would do.\n *\n * Deliberately does not derive an \"agrees with legacy gc\" boolean: legacy context-gc\n * \"packing\" summarizes/stubs a tool result in place (provider-visible content shrinks in\n * place), while the policy action `pack_to_artifact` means artifact-backed capture and\n * out-of-band retrieval -- a different operation with different semantics, not a\n * calibrated equivalent. Collapsing them into one \"agreement\" boolean would overclaim\n * semantic agreement between the two and risk a later enforcement slice mistaking this\n * observe-only diagnostic for a calibrated authority. The raw booleans below are reported\n * as-is; comparing them is left to the reader.\n */\nexport function correlateWithContextGc(\n\tshadowReport: PromptPolicyShadowReport,\n\tgcReport: ContextGcReport,\n): PromptPolicyGcCorrelationReport {\n\tconst packedByToolCallId = new Map<string, ContextGcPackedRecord>();\n\tfor (const record of gcReport.records) packedByToolCallId.set(record.toolCallId, record);\n\n\tconst entries: PromptPolicyGcCorrelationEntry[] = shadowReport.items.map((item) => {\n\t\tconst gcRecord = packedByToolCallId.get(item.toolCallId);\n\t\treturn {\n\t\t\titemId: item.itemId,\n\t\t\ttoolCallId: item.toolCallId,\n\t\t\tactuallyPackedByLegacyGc: gcRecord !== undefined,\n\t\t\tgcPackReason: gcRecord?.reason,\n\t\t\tpolicyWouldAllowPack: item.hardConstraints.packToArtifact.length === 0,\n\t\t\tpolicyWouldAllowDrop: item.hardConstraints.dropFromPrompt.length === 0,\n\t\t};\n\t});\n\n\treturn { turnIndex: shadowReport.turnIndex, entries };\n}\n"]}