@graphorin/memory 0.5.0

package/dist/context-engine/annotations.d.ts

@@ -0,0 +1,118 @@
+//#region src/context-engine/annotations.d.ts
+/**
+ * Cooperation contract between the {@link ContextEngine} and the
+ * outbound prompt-redaction middleware (D3, see ADR-045 / DEC-157)
+ * + the inbound tool-result sanitization middleware (D4, see
+ * RB-43 / DEC-159).
+ *
+ * Every {@link MessageContent} part assembled by the ContextEngine
+ * carries two **independent** annotations:
+ *
+ * - `graphorin.content.origin` — where the content came from. Used
+ *   by D3 (`withRedaction`) under `scanScope: 'untrusted'` to
+ *   decide whether to re-scan a part that already passed the D2
+ *   sensitivity-tier filter.
+ * - `graphorin.content.inbound.trust` — what trust class the source
+ *   carries. Used by D4 (`withInboundSanitization`) and by Phase 12
+ *   (agent runtime) to gate the per-step preamble injection.
+ *
+ * Both annotations live as **span attributes only** (observability)
+ * — they are never serialized to the wire payload. The wire-stable
+ * `ProviderRequest` shape is unchanged by Phase 10d.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Span-attribute key for the origin axis.
+ *
+ * @stable
+ */
+declare const CONTENT_ORIGIN_ATTR: "graphorin.content.origin";
+/**
+ * Span-attribute key for the inbound-trust axis.
+ *
+ * @stable
+ */
+declare const INBOUND_TRUST_ATTR: "graphorin.content.inbound.trust";
+/**
+ * Origin discriminator for an assembled message-content part. The
+ * non-ContextEngine origins (`'user:input'`, `'tool:result'`,
+ * `'mcp:response'`, `'tool-call:args'`) are tagged by Phase 12
+ * (agent runtime) when the corresponding payload enters
+ * `session_messages`; the ContextEngine then propagates the tag
+ * through the assembled message list.
+ *
+ * @stable
+ */
+type ContentOrigin = 'memory:tier-filtered' | 'system:framework' | 'agent:instructions' | 'skill:content' | 'user:input' | 'tool:result' | 'mcp:response' | 'tool-call:args';
+/**
+ * Trust-class discriminator for an assembled message-content part.
+ * Sibling axis to {@link ContentOrigin}; the two are independent.
+ *
+ * - `'trusted'` — built-in framework tools + trusted-skill-bundled
+ *   tools; D4 preamble does NOT fire on steps containing only
+ *   these parts.
+ * - `'user-defined'` — tools registered via `tool({...})` from user
+ *   application code; D4 preamble fires.
+ * - `'untrusted-skill'` — tools bundled by an untrusted skill; D4
+ *   preamble fires; default policy is strip-and-wrap.
+ * - `'mcp'` — every `Tool` produced by `MCPClient.toTools(...)`; D4
+ *   preamble fires; default policy is strip-and-wrap.
+ * - `'web-search'` — built-in `web_search` adapter; D4 preamble
+ *   fires; default policy is strip-and-wrap.
+ * - `'n/a'` — non-tool-result parts for which the inbound-trust
+ *   axis is meaningless (`'user:input'`, `'memory:tier-filtered'`,
+ *   `'system:framework'`, `'agent:instructions'`,
+ *   `'tool-call:args'`).
+ *
+ * @stable
+ */
+type InboundTrust = 'trusted' | 'user-defined' | 'untrusted-skill' | 'mcp' | 'web-search' | 'n/a';
+/**
+ * Origins for which the inbound-trust axis is meaningless and is
+ * always set to `'n/a'`. Surfaced as a frozen constant so consumers
+ * can introspect the contract without re-implementing the rule.
+ *
+ * @stable
+ */
+declare const NON_INBOUND_ORIGINS: ReadonlySet<ContentOrigin>;
+/**
+ * Single typed annotation for an assembled message-content part.
+ *
+ * @stable
+ */
+interface ContentAnnotation {
+  readonly origin: ContentOrigin;
+  readonly inboundTrust: InboundTrust;
+}
+/**
+ * Build an annotation, enforcing the rule that
+ * non-tool-result origins always carry `inboundTrust: 'n/a'`. A
+ * caller that requests a non-`'n/a'` value for a non-inbound origin
+ * is silently corrected (defense-in-depth: the rule is enforced
+ * here so callers cannot accidentally violate it).
+ *
+ * @stable
+ */
+declare function annotate(origin: ContentOrigin, inboundTrust: InboundTrust): ContentAnnotation;
+/**
+ * Convert a {@link ContentAnnotation} to a span-attributes record
+ * suitable for `AISpan.setAttributes(...)`.
+ *
+ * @stable
+ */
+declare function toSpanAttributes(annotation: ContentAnnotation): Readonly<Record<string, string>>;
+/**
+ * Decide whether the per-step inbound-sanitization preamble (D4)
+ * should fire for an assembled message list. The preamble fires
+ * iff at least one part carries an inbound-trust value other than
+ * `'trusted'` and `'n/a'`. Trusted-only steps skip the preamble for
+ * cache-friendliness; preamble is emitted exactly once per step
+ * regardless of how many untrusted parts the step carries.
+ *
+ * @stable
+ */
+declare function shouldFireInboundPreamble(annotations: ReadonlyArray<ContentAnnotation>): boolean;
+//#endregion
+export { CONTENT_ORIGIN_ATTR, ContentAnnotation, ContentOrigin, INBOUND_TRUST_ATTR, InboundTrust, NON_INBOUND_ORIGINS, annotate, shouldFireInboundPreamble, toSpanAttributes };
+//# sourceMappingURL=annotations.d.ts.map

package/dist/context-engine/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","names":[],"sources":["../../src/context-engine/annotations.ts"],"sourcesContent":[],"mappings":";;AA6BA;AAOA;AAYA;AAgCA;AAeA;AAeA;AAcA;;;;;AAaA;;;;;AAiBA;;;;;;;;;;;cA7Ha;;;;;;cAOA;;;;;;;;;;;KAYD,aAAA;;;;;;;;;;;;;;;;;;;;;;;KAgCA,YAAA;;;;;;;;cAeC,qBAAqB,YAAY;;;;;;UAe7B,iBAAA;mBACE;yBACM;;;;;;;;;;;iBAYT,QAAA,SAAiB,6BAA6B,eAAe;;;;;;;iBAa7D,gBAAA,aAA6B,oBAAoB,SAAS;;;;;;;;;;;iBAiB1D,yBAAA,cAAuC,cAAc"}

package/dist/context-engine/annotations.js

@@ -0,0 +1,102 @@
+//#region src/context-engine/annotations.ts
+/**
+* Cooperation contract between the {@link ContextEngine} and the
+* outbound prompt-redaction middleware (D3, see ADR-045 / DEC-157)
+* + the inbound tool-result sanitization middleware (D4, see
+* RB-43 / DEC-159).
+*
+* Every {@link MessageContent} part assembled by the ContextEngine
+* carries two **independent** annotations:
+*
+* - `graphorin.content.origin` — where the content came from. Used
+*   by D3 (`withRedaction`) under `scanScope: 'untrusted'` to
+*   decide whether to re-scan a part that already passed the D2
+*   sensitivity-tier filter.
+* - `graphorin.content.inbound.trust` — what trust class the source
+*   carries. Used by D4 (`withInboundSanitization`) and by Phase 12
+*   (agent runtime) to gate the per-step preamble injection.
+*
+* Both annotations live as **span attributes only** (observability)
+* — they are never serialized to the wire payload. The wire-stable
+* `ProviderRequest` shape is unchanged by Phase 10d.
+*
+* @packageDocumentation
+*/
+/**
+* Span-attribute key for the origin axis.
+*
+* @stable
+*/
+const CONTENT_ORIGIN_ATTR = "graphorin.content.origin";
+/**
+* Span-attribute key for the inbound-trust axis.
+*
+* @stable
+*/
+const INBOUND_TRUST_ATTR = "graphorin.content.inbound.trust";
+/**
+* Origins for which the inbound-trust axis is meaningless and is
+* always set to `'n/a'`. Surfaced as a frozen constant so consumers
+* can introspect the contract without re-implementing the rule.
+*
+* @stable
+*/
+const NON_INBOUND_ORIGINS = Object.freeze(new Set([
+	"memory:tier-filtered",
+	"system:framework",
+	"agent:instructions",
+	"user:input",
+	"tool-call:args"
+]));
+/**
+* Build an annotation, enforcing the rule that
+* non-tool-result origins always carry `inboundTrust: 'n/a'`. A
+* caller that requests a non-`'n/a'` value for a non-inbound origin
+* is silently corrected (defense-in-depth: the rule is enforced
+* here so callers cannot accidentally violate it).
+*
+* @stable
+*/
+function annotate(origin, inboundTrust) {
+	if (NON_INBOUND_ORIGINS.has(origin)) return Object.freeze({
+		origin,
+		inboundTrust: "n/a"
+	});
+	return Object.freeze({
+		origin,
+		inboundTrust
+	});
+}
+/**
+* Convert a {@link ContentAnnotation} to a span-attributes record
+* suitable for `AISpan.setAttributes(...)`.
+*
+* @stable
+*/
+function toSpanAttributes(annotation) {
+	return Object.freeze({
+		[CONTENT_ORIGIN_ATTR]: annotation.origin,
+		[INBOUND_TRUST_ATTR]: annotation.inboundTrust
+	});
+}
+/**
+* Decide whether the per-step inbound-sanitization preamble (D4)
+* should fire for an assembled message list. The preamble fires
+* iff at least one part carries an inbound-trust value other than
+* `'trusted'` and `'n/a'`. Trusted-only steps skip the preamble for
+* cache-friendliness; preamble is emitted exactly once per step
+* regardless of how many untrusted parts the step carries.
+*
+* @stable
+*/
+function shouldFireInboundPreamble(annotations) {
+	for (const annotation of annotations) {
+		const trust = annotation.inboundTrust;
+		if (trust !== "trusted" && trust !== "n/a") return true;
+	}
+	return false;
+}
+
+//#endregion
+export { CONTENT_ORIGIN_ATTR, INBOUND_TRUST_ATTR, NON_INBOUND_ORIGINS, annotate, shouldFireInboundPreamble, toSpanAttributes };
+//# sourceMappingURL=annotations.js.map

package/dist/context-engine/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","names":["NON_INBOUND_ORIGINS: ReadonlySet<ContentOrigin>"],"sources":["../../src/context-engine/annotations.ts"],"sourcesContent":["/**\n * Cooperation contract between the {@link ContextEngine} and the\n * outbound prompt-redaction middleware (D3, see ADR-045 / DEC-157)\n * + the inbound tool-result sanitization middleware (D4, see\n * RB-43 / DEC-159).\n *\n * Every {@link MessageContent} part assembled by the ContextEngine\n * carries two **independent** annotations:\n *\n * - `graphorin.content.origin` — where the content came from. Used\n *   by D3 (`withRedaction`) under `scanScope: 'untrusted'` to\n *   decide whether to re-scan a part that already passed the D2\n *   sensitivity-tier filter.\n * - `graphorin.content.inbound.trust` — what trust class the source\n *   carries. Used by D4 (`withInboundSanitization`) and by Phase 12\n *   (agent runtime) to gate the per-step preamble injection.\n *\n * Both annotations live as **span attributes only** (observability)\n * — they are never serialized to the wire payload. The wire-stable\n * `ProviderRequest` shape is unchanged by Phase 10d.\n *\n * @packageDocumentation\n */\n\n/**\n * Span-attribute key for the origin axis.\n *\n * @stable\n */\nexport const CONTENT_ORIGIN_ATTR = 'graphorin.content.origin' as const;\n\n/**\n * Span-attribute key for the inbound-trust axis.\n *\n * @stable\n */\nexport const INBOUND_TRUST_ATTR = 'graphorin.content.inbound.trust' as const;\n\n/**\n * Origin discriminator for an assembled message-content part. The\n * non-ContextEngine origins (`'user:input'`, `'tool:result'`,\n * `'mcp:response'`, `'tool-call:args'`) are tagged by Phase 12\n * (agent runtime) when the corresponding payload enters\n * `session_messages`; the ContextEngine then propagates the tag\n * through the assembled message list.\n *\n * @stable\n */\nexport type ContentOrigin =\n  | 'memory:tier-filtered'\n  | 'system:framework'\n  | 'agent:instructions'\n  | 'skill:content'\n  | 'user:input'\n  | 'tool:result'\n  | 'mcp:response'\n  | 'tool-call:args';\n\n/**\n * Trust-class discriminator for an assembled message-content part.\n * Sibling axis to {@link ContentOrigin}; the two are independent.\n *\n * - `'trusted'` — built-in framework tools + trusted-skill-bundled\n *   tools; D4 preamble does NOT fire on steps containing only\n *   these parts.\n * - `'user-defined'` — tools registered via `tool({...})` from user\n *   application code; D4 preamble fires.\n * - `'untrusted-skill'` — tools bundled by an untrusted skill; D4\n *   preamble fires; default policy is strip-and-wrap.\n * - `'mcp'` — every `Tool` produced by `MCPClient.toTools(...)`; D4\n *   preamble fires; default policy is strip-and-wrap.\n * - `'web-search'` — built-in `web_search` adapter; D4 preamble\n *   fires; default policy is strip-and-wrap.\n * - `'n/a'` — non-tool-result parts for which the inbound-trust\n *   axis is meaningless (`'user:input'`, `'memory:tier-filtered'`,\n *   `'system:framework'`, `'agent:instructions'`,\n *   `'tool-call:args'`).\n *\n * @stable\n */\nexport type InboundTrust =\n  | 'trusted'\n  | 'user-defined'\n  | 'untrusted-skill'\n  | 'mcp'\n  | 'web-search'\n  | 'n/a';\n\n/**\n * Origins for which the inbound-trust axis is meaningless and is\n * always set to `'n/a'`. Surfaced as a frozen constant so consumers\n * can introspect the contract without re-implementing the rule.\n *\n * @stable\n */\nexport const NON_INBOUND_ORIGINS: ReadonlySet<ContentOrigin> = Object.freeze(\n  new Set<ContentOrigin>([\n    'memory:tier-filtered',\n    'system:framework',\n    'agent:instructions',\n    'user:input',\n    'tool-call:args',\n  ]),\n);\n\n/**\n * Single typed annotation for an assembled message-content part.\n *\n * @stable\n */\nexport interface ContentAnnotation {\n  readonly origin: ContentOrigin;\n  readonly inboundTrust: InboundTrust;\n}\n\n/**\n * Build an annotation, enforcing the rule that\n * non-tool-result origins always carry `inboundTrust: 'n/a'`. A\n * caller that requests a non-`'n/a'` value for a non-inbound origin\n * is silently corrected (defense-in-depth: the rule is enforced\n * here so callers cannot accidentally violate it).\n *\n * @stable\n */\nexport function annotate(origin: ContentOrigin, inboundTrust: InboundTrust): ContentAnnotation {\n  if (NON_INBOUND_ORIGINS.has(origin)) {\n    return Object.freeze({ origin, inboundTrust: 'n/a' });\n  }\n  return Object.freeze({ origin, inboundTrust });\n}\n\n/**\n * Convert a {@link ContentAnnotation} to a span-attributes record\n * suitable for `AISpan.setAttributes(...)`.\n *\n * @stable\n */\nexport function toSpanAttributes(annotation: ContentAnnotation): Readonly<Record<string, string>> {\n  return Object.freeze({\n    [CONTENT_ORIGIN_ATTR]: annotation.origin,\n    [INBOUND_TRUST_ATTR]: annotation.inboundTrust,\n  });\n}\n\n/**\n * Decide whether the per-step inbound-sanitization preamble (D4)\n * should fire for an assembled message list. The preamble fires\n * iff at least one part carries an inbound-trust value other than\n * `'trusted'` and `'n/a'`. Trusted-only steps skip the preamble for\n * cache-friendliness; preamble is emitted exactly once per step\n * regardless of how many untrusted parts the step carries.\n *\n * @stable\n */\nexport function shouldFireInboundPreamble(annotations: ReadonlyArray<ContentAnnotation>): boolean {\n  for (const annotation of annotations) {\n    const trust = annotation.inboundTrust;\n    if (trust !== 'trusted' && trust !== 'n/a') return true;\n  }\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,sBAAsB;;;;;;AAOnC,MAAa,qBAAqB;;;;;;;;AA2DlC,MAAaA,sBAAkD,OAAO,OACpE,IAAI,IAAmB;CACrB;CACA;CACA;CACA;CACA;CACD,CAAC,CACH;;;;;;;;;;AAqBD,SAAgB,SAAS,QAAuB,cAA+C;AAC7F,KAAI,oBAAoB,IAAI,OAAO,CACjC,QAAO,OAAO,OAAO;EAAE;EAAQ,cAAc;EAAO,CAAC;AAEvD,QAAO,OAAO,OAAO;EAAE;EAAQ;EAAc,CAAC;;;;;;;;AAShD,SAAgB,iBAAiB,YAAiE;AAChG,QAAO,OAAO,OAAO;GAClB,sBAAsB,WAAW;GACjC,qBAAqB,WAAW;EAClC,CAAC;;;;;;;;;;;;AAaJ,SAAgB,0BAA0B,aAAwD;AAChG,MAAK,MAAM,cAAc,aAAa;EACpC,MAAM,QAAQ,WAAW;AACzB,MAAI,UAAU,aAAa,UAAU,MAAO,QAAO;;AAErD,QAAO"}

package/dist/context-engine/auto-recall.d.ts

@@ -0,0 +1,52 @@
+import { ContextLocalePack } from "./locale-packs/types.js";
+
+//#region src/context-engine/auto-recall.d.ts
+
+/**
+ * Per-call scope passed to a custom strategy.
+ *
+ * @stable
+ */
+interface AutoRecallStrategyContext {
+  readonly locale: string;
+  readonly lastUserMessage: string;
+}
+/**
+ * Outcome of a strategy invocation.
+ *
+ * @stable
+ */
+interface AutoRecallTriggerResult {
+  readonly factsTriggered: boolean;
+  /** Optional reason surfaced in spans / metadata. */
+  readonly reason?: string;
+}
+/**
+ * Pluggable strategy signature.
+ *
+ * @stable
+ */
+type AutoRecallStrategy = (ctx: AutoRecallStrategyContext) => AutoRecallTriggerResult;
+/**
+ * Build a locale-driven heuristic strategy. The default for every
+ * configured locale.
+ *
+ * @stable
+ */
+declare function defaultLocaleHeuristicStrategy(pack: ContextLocalePack): AutoRecallStrategy;
+/**
+ * Builder for application-supplied custom strategies. Accepts a
+ * raw function and returns a tagged version so the engine can
+ * surface the strategy name on spans.
+ *
+ * @stable
+ */
+declare function defineAutoRecallStrategy(opts: {
+  readonly id: string;
+  readonly evaluate: AutoRecallStrategy;
+}): AutoRecallStrategy & {
+  readonly id: string;
+};
+//#endregion
+export { AutoRecallStrategy, AutoRecallStrategyContext, AutoRecallTriggerResult, defaultLocaleHeuristicStrategy, defineAutoRecallStrategy };
+//# sourceMappingURL=auto-recall.d.ts.map

package/dist/context-engine/auto-recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-recall.d.ts","names":[],"sources":["../../src/context-engine/auto-recall.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAqBiB,yBAAA;;;;;;;;;UAUA,uBAAA;;;;;;;;;;KAWL,kBAAA,SAA2B,8BAA8B;;;;;;;iBAQrD,8BAAA,OAAqC,oBAAoB;;;;;;;;iBAsBzD,wBAAA;;qBAEK;IACjB"}

package/dist/context-engine/auto-recall.js

@@ -0,0 +1,41 @@
+//#region src/context-engine/auto-recall.ts
+/**
+* Build a locale-driven heuristic strategy. The default for every
+* configured locale.
+*
+* @stable
+*/
+function defaultLocaleHeuristicStrategy(pack) {
+	const factTriggers = pack.autoRecallTriggers.factTriggers;
+	return (ctx) => {
+		const text = ctx.lastUserMessage ?? "";
+		if (text.length === 0) return { factsTriggered: false };
+		const factsTriggered = factTriggers.some((re) => re.test(text));
+		if (factsTriggered) return {
+			factsTriggered,
+			reason: "locale-heuristic-trigger-matched"
+		};
+		return { factsTriggered: false };
+	};
+}
+/**
+* Builder for application-supplied custom strategies. Accepts a
+* raw function and returns a tagged version so the engine can
+* surface the strategy name on spans.
+*
+* @stable
+*/
+function defineAutoRecallStrategy(opts) {
+	if (typeof opts.id !== "string" || opts.id.length === 0) throw new TypeError("[graphorin/memory] defineAutoRecallStrategy: `id` must be a non-empty string.");
+	if (typeof opts.evaluate !== "function") throw new TypeError("[graphorin/memory] defineAutoRecallStrategy: `evaluate` must be a function.");
+	const wrapped = ((ctx) => opts.evaluate(ctx));
+	Object.defineProperty(wrapped, "id", {
+		value: opts.id,
+		enumerable: true
+	});
+	return wrapped;
+}
+
+//#endregion
+export { defaultLocaleHeuristicStrategy, defineAutoRecallStrategy };
+//# sourceMappingURL=auto-recall.js.map

package/dist/context-engine/auto-recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-recall.js","names":[],"sources":["../../src/context-engine/auto-recall.ts"],"sourcesContent":["/**\n * Auto-recall heuristic — opt-in regex-based pre-call that injects\n * the top-K facts into Layer 6 when the last user message matches one\n * of the configured trigger phrases. (Episode auto-recall is not\n * implemented; episodes are reachable via the `recall_episodes` tool.)\n *\n * The framework ships English defaults; per-locale trigger\n * phrases extend the default via {@link defineContextLocalePack}.\n * Application code can also register a fully-custom strategy via\n * {@link defineAutoRecallStrategy}.\n *\n * @packageDocumentation\n */\n\nimport type { ContextLocalePack } from './locale-packs/index.js';\n\n/**\n * Per-call scope passed to a custom strategy.\n *\n * @stable\n */\nexport interface AutoRecallStrategyContext {\n  readonly locale: string;\n  readonly lastUserMessage: string;\n}\n\n/**\n * Outcome of a strategy invocation.\n *\n * @stable\n */\nexport interface AutoRecallTriggerResult {\n  readonly factsTriggered: boolean;\n  /** Optional reason surfaced in spans / metadata. */\n  readonly reason?: string;\n}\n\n/**\n * Pluggable strategy signature.\n *\n * @stable\n */\nexport type AutoRecallStrategy = (ctx: AutoRecallStrategyContext) => AutoRecallTriggerResult;\n\n/**\n * Build a locale-driven heuristic strategy. The default for every\n * configured locale.\n *\n * @stable\n */\nexport function defaultLocaleHeuristicStrategy(pack: ContextLocalePack): AutoRecallStrategy {\n  const factTriggers = pack.autoRecallTriggers.factTriggers;\n  return (ctx) => {\n    const text = ctx.lastUserMessage ?? '';\n    if (text.length === 0) {\n      return { factsTriggered: false };\n    }\n    const factsTriggered = factTriggers.some((re) => re.test(text));\n    if (factsTriggered) {\n      return { factsTriggered, reason: 'locale-heuristic-trigger-matched' };\n    }\n    return { factsTriggered: false };\n  };\n}\n\n/**\n * Builder for application-supplied custom strategies. Accepts a\n * raw function and returns a tagged version so the engine can\n * surface the strategy name on spans.\n *\n * @stable\n */\nexport function defineAutoRecallStrategy(opts: {\n  readonly id: string;\n  readonly evaluate: AutoRecallStrategy;\n}): AutoRecallStrategy & { readonly id: string } {\n  if (typeof opts.id !== 'string' || opts.id.length === 0) {\n    throw new TypeError(\n      '[graphorin/memory] defineAutoRecallStrategy: `id` must be a non-empty string.',\n    );\n  }\n  if (typeof opts.evaluate !== 'function') {\n    throw new TypeError(\n      '[graphorin/memory] defineAutoRecallStrategy: `evaluate` must be a function.',\n    );\n  }\n  const wrapped = ((ctx: AutoRecallStrategyContext) => opts.evaluate(ctx)) as AutoRecallStrategy & {\n    readonly id: string;\n  };\n  Object.defineProperty(wrapped, 'id', { value: opts.id, enumerable: true });\n  return wrapped;\n}\n"],"mappings":";;;;;;;AAkDA,SAAgB,+BAA+B,MAA6C;CAC1F,MAAM,eAAe,KAAK,mBAAmB;AAC7C,SAAQ,QAAQ;EACd,MAAM,OAAO,IAAI,mBAAmB;AACpC,MAAI,KAAK,WAAW,EAClB,QAAO,EAAE,gBAAgB,OAAO;EAElC,MAAM,iBAAiB,aAAa,MAAM,OAAO,GAAG,KAAK,KAAK,CAAC;AAC/D,MAAI,eACF,QAAO;GAAE;GAAgB,QAAQ;GAAoC;AAEvE,SAAO,EAAE,gBAAgB,OAAO;;;;;;;;;;AAWpC,SAAgB,yBAAyB,MAGQ;AAC/C,KAAI,OAAO,KAAK,OAAO,YAAY,KAAK,GAAG,WAAW,EACpD,OAAM,IAAI,UACR,gFACD;AAEH,KAAI,OAAO,KAAK,aAAa,WAC3B,OAAM,IAAI,UACR,8EACD;CAEH,MAAM,YAAY,QAAmC,KAAK,SAAS,IAAI;AAGvE,QAAO,eAAe,SAAS,MAAM;EAAE,OAAO,KAAK;EAAI,YAAY;EAAM,CAAC;AAC1E,QAAO"}

package/dist/context-engine/compaction/clear-tool-results.d.ts

@@ -0,0 +1,55 @@
+import { ContextTokenCounter } from "../token-counter.js";
+import { Message } from "@graphorin/core";
+
+//#region src/context-engine/compaction/clear-tool-results.d.ts
+
+/** Placeholder prefix on a cleared tool result — makes clearing idempotent. */
+declare const CLEARED_TOOL_RESULT_MARKER = "[cleared tool result";
+/** Knobs for {@link clearOldToolResults} (mirrors the strategy variant). */
+interface ClearToolResultsOptions {
+  /** Most-recent tool results kept verbatim (default {@link DEFAULT_KEEP_TOOL_USES}). */
+  readonly keepToolUses?: number;
+  /** Only clear if at least this many tokens are reclaimable; else leave untouched (default 0). */
+  readonly clearAtLeast?: number;
+  /** Tool names whose results are never cleared. */
+  readonly excludeTools?: ReadonlyArray<string>;
+  /** Placeholder builder; defaults to a one-line `[cleared tool result …]` marker. */
+  readonly placeholder?: (info: {
+    readonly toolCallId: string;
+    readonly toolName?: string;
+    readonly clearedTokens: number;
+  }) => string;
+  /**
+   * A6 / SOTA-2 — recoverable clearing. When provided, the original tool-result
+   * text of each cleared message is handed to this callback (wire it to a spill
+   * store / the `read_result` handle registry) and the placeholder references the
+   * returned handle id + preview, so the model can re-fetch the full result via
+   * `read_result` rather than losing it. Invoked only for clears that actually
+   * commit (after the `clearAtLeast` floor), so a rejected clearing never spills.
+   * Omitted ⇒ the bare `placeholder` (irrecoverable, byte-identical default).
+   */
+  readonly externalize?: (content: string, info: {
+    readonly toolCallId: string;
+    readonly toolName?: string;
+    readonly clearedTokens: number;
+  }) => Promise<{
+    readonly handleId: string;
+    readonly preview?: string;
+  }>;
+}
+/** Result of a clearing pass. `clearedIndices` empty ⇒ nothing changed. */
+interface ClearToolResultsOutcome {
+  readonly messages: ReadonlyArray<Message>;
+  readonly clearedIndices: ReadonlyArray<number>;
+  readonly reclaimedTokens: number;
+}
+/**
+ * Replace the oldest clearable tool results with placeholders. Returns the new
+ * buffer (same length — content is replaced in place, never removed) plus the
+ * cleared indices and reclaimed token count. Idempotent: already-cleared
+ * placeholders are skipped on a second pass.
+ */
+declare function clearOldToolResults(messages: ReadonlyArray<Message>, options: ClearToolResultsOptions, counter: ContextTokenCounter): Promise<ClearToolResultsOutcome>;
+//#endregion
+export { CLEARED_TOOL_RESULT_MARKER, ClearToolResultsOptions, ClearToolResultsOutcome, clearOldToolResults };
+//# sourceMappingURL=clear-tool-results.d.ts.map

package/dist/context-engine/compaction/clear-tool-results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear-tool-results.d.ts","names":[],"sources":["../../../src/context-engine/compaction/clear-tool-results.ts"],"sourcesContent":[],"mappings":";;;;;;AA8FW,cAzEE,0BAAA,GAyEF,sBAAA;;UAnEM,uBAAA;;;;;;0BAMS;;;;;;;;;;;;;;;;;;;;QAuBnB;;;;;;UAIU,uBAAA;qBACI,cAAc;2BACR;;;;;;;;;iBA6BL,mBAAA,WACV,cAAc,mBACf,kCACA,sBACR,QAAQ"}

package/dist/context-engine/compaction/clear-tool-results.js

@@ -0,0 +1,97 @@
+import { countMessageTokens, renderMessageText } from "../token-counter.js";
+
+//#region src/context-engine/compaction/clear-tool-results.ts
+/** Placeholder prefix on a cleared tool result — makes clearing idempotent. */
+const CLEARED_TOOL_RESULT_MARKER = "[cleared tool result";
+/** Default count of most-recent tool results kept verbatim. */
+const DEFAULT_KEEP_TOOL_USES = 3;
+function defaultPlaceholder(info) {
+	return `${CLEARED_TOOL_RESULT_MARKER} · ${info.toolName ?? "tool"} · ${info.clearedTokens} tokens elided · re-run the tool if needed]`;
+}
+/** A6: a placeholder that points at the externalized handle (recoverable via read_result). */
+function handlePlaceholder(info) {
+	const preview = info.preview !== void 0 && info.preview.length > 0 ? ` · ${info.preview}` : "";
+	return `${CLEARED_TOOL_RESULT_MARKER} · ${info.toolName ?? "tool"} · ${info.clearedTokens} tokens · full result via read_result handle: ${info.handleId}${preview}]`;
+}
+function isAlreadyCleared(content) {
+	return typeof content === "string" && content.startsWith(CLEARED_TOOL_RESULT_MARKER);
+}
+/**
+* Replace the oldest clearable tool results with placeholders. Returns the new
+* buffer (same length — content is replaced in place, never removed) plus the
+* cleared indices and reclaimed token count. Idempotent: already-cleared
+* placeholders are skipped on a second pass.
+*/
+async function clearOldToolResults(messages, options, counter) {
+	const keep = options.keepToolUses ?? DEFAULT_KEEP_TOOL_USES;
+	const exclude = new Set(options.excludeTools ?? []);
+	const placeholder = options.placeholder ?? defaultPlaceholder;
+	const toolNameById = /* @__PURE__ */ new Map();
+	for (const m of messages) if (m.role === "assistant" && m.toolCalls) for (const tc of m.toolCalls) toolNameById.set(tc.toolCallId, tc.toolName);
+	const toolIdx = [];
+	for (let i = 0; i < messages.length; i++) {
+		const m = messages[i];
+		if (m?.role === "tool" && !isAlreadyCleared(m.content)) toolIdx.push(i);
+	}
+	const keptCutoff = toolIdx.length - Math.max(0, keep);
+	const replacements = /* @__PURE__ */ new Map();
+	const clearedTokensByIdx = /* @__PURE__ */ new Map();
+	let reclaimable = 0;
+	for (let j = 0; j < toolIdx.length && j < keptCutoff; j++) {
+		const idx = toolIdx[j];
+		if (idx === void 0) continue;
+		const tm = messages[idx];
+		const name = toolNameById.get(tm.toolCallId);
+		if (name !== void 0 && exclude.has(name)) continue;
+		const originalTokens = await countMessageTokens([tm], counter);
+		const replaced = {
+			role: "tool",
+			toolCallId: tm.toolCallId,
+			content: placeholder({
+				toolCallId: tm.toolCallId,
+				...name !== void 0 ? { toolName: name } : {},
+				clearedTokens: originalTokens
+			})
+		};
+		const placeholderTokens = await countMessageTokens([replaced], counter);
+		reclaimable += Math.max(0, originalTokens - placeholderTokens);
+		replacements.set(idx, replaced);
+		clearedTokensByIdx.set(idx, originalTokens);
+	}
+	const clearAtLeast = options.clearAtLeast ?? 0;
+	if (replacements.size === 0 || reclaimable < clearAtLeast) return {
+		messages,
+		clearedIndices: [],
+		reclaimedTokens: 0
+	};
+	const externalize = options.externalize;
+	if (externalize !== void 0) for (const idx of replacements.keys()) {
+		const tm = messages[idx];
+		const name = toolNameById.get(tm.toolCallId);
+		const clearedTokens = clearedTokensByIdx.get(idx) ?? 0;
+		const handle = await externalize(typeof tm.content === "string" ? tm.content : renderMessageText(tm), {
+			toolCallId: tm.toolCallId,
+			...name !== void 0 ? { toolName: name } : {},
+			clearedTokens
+		});
+		replacements.set(idx, {
+			role: "tool",
+			toolCallId: tm.toolCallId,
+			content: handlePlaceholder({
+				...name !== void 0 ? { toolName: name } : {},
+				clearedTokens,
+				handleId: handle.handleId,
+				...handle.preview !== void 0 ? { preview: handle.preview } : {}
+			})
+		});
+	}
+	return {
+		messages: messages.map((m, i) => replacements.get(i) ?? m),
+		clearedIndices: [...replacements.keys()],
+		reclaimedTokens: reclaimable
+	};
+}
+
+//#endregion
+export { CLEARED_TOOL_RESULT_MARKER, DEFAULT_KEEP_TOOL_USES, clearOldToolResults };
+//# sourceMappingURL=clear-tool-results.js.map

package/dist/context-engine/compaction/clear-tool-results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear-tool-results.js","names":["toolIdx: number[]","replaced: ToolMessage"],"sources":["../../../src/context-engine/compaction/clear-tool-results.ts"],"sourcesContent":["/**\n * SOTA-1: zero-LLM tool-result clearing — the cheapest pre-compaction tier.\n *\n * Mirrors Anthropic context editing (`clear_tool_uses_20250919`): when the\n * buffer crosses the compaction threshold, replace the oldest tool results with\n * a compact placeholder BEFORE paying for a summarizer LLM call. The most recent\n * `keepToolUses` results stay verbatim, `excludeTools` are never touched, and\n * clearing is skipped entirely when it would reclaim fewer than `clearAtLeast`\n * tokens (not worth the context churn). Pure + deterministic — no provider call.\n *\n * @packageDocumentation\n */\n\nimport type { Message, ToolMessage } from '@graphorin/core';\nimport {\n  type ContextTokenCounter,\n  countMessageTokens,\n  renderMessageText,\n} from '../token-counter.js';\n\n/** Placeholder prefix on a cleared tool result — makes clearing idempotent. */\nexport const CLEARED_TOOL_RESULT_MARKER = '[cleared tool result';\n\n/** Default count of most-recent tool results kept verbatim. */\nexport const DEFAULT_KEEP_TOOL_USES = 3;\n\n/** Knobs for {@link clearOldToolResults} (mirrors the strategy variant). */\nexport interface ClearToolResultsOptions {\n  /** Most-recent tool results kept verbatim (default {@link DEFAULT_KEEP_TOOL_USES}). */\n  readonly keepToolUses?: number;\n  /** Only clear if at least this many tokens are reclaimable; else leave untouched (default 0). */\n  readonly clearAtLeast?: number;\n  /** Tool names whose results are never cleared. */\n  readonly excludeTools?: ReadonlyArray<string>;\n  /** Placeholder builder; defaults to a one-line `[cleared tool result …]` marker. */\n  readonly placeholder?: (info: {\n    readonly toolCallId: string;\n    readonly toolName?: string;\n    readonly clearedTokens: number;\n  }) => string;\n  /**\n   * A6 / SOTA-2 — recoverable clearing. When provided, the original tool-result\n   * text of each cleared message is handed to this callback (wire it to a spill\n   * store / the `read_result` handle registry) and the placeholder references the\n   * returned handle id + preview, so the model can re-fetch the full result via\n   * `read_result` rather than losing it. Invoked only for clears that actually\n   * commit (after the `clearAtLeast` floor), so a rejected clearing never spills.\n   * Omitted ⇒ the bare `placeholder` (irrecoverable, byte-identical default).\n   */\n  readonly externalize?: (\n    content: string,\n    info: {\n      readonly toolCallId: string;\n      readonly toolName?: string;\n      readonly clearedTokens: number;\n    },\n  ) => Promise<{ readonly handleId: string; readonly preview?: string }>;\n}\n\n/** Result of a clearing pass. `clearedIndices` empty ⇒ nothing changed. */\nexport interface ClearToolResultsOutcome {\n  readonly messages: ReadonlyArray<Message>;\n  readonly clearedIndices: ReadonlyArray<number>;\n  readonly reclaimedTokens: number;\n}\n\nfunction defaultPlaceholder(info: { toolName?: string; clearedTokens: number }): string {\n  return `${CLEARED_TOOL_RESULT_MARKER} · ${info.toolName ?? 'tool'} · ${info.clearedTokens} tokens elided · re-run the tool if needed]`;\n}\n\n/** A6: a placeholder that points at the externalized handle (recoverable via read_result). */\nfunction handlePlaceholder(info: {\n  toolName?: string;\n  clearedTokens: number;\n  handleId: string;\n  preview?: string;\n}): string {\n  const preview = info.preview !== undefined && info.preview.length > 0 ? ` · ${info.preview}` : '';\n  return `${CLEARED_TOOL_RESULT_MARKER} · ${info.toolName ?? 'tool'} · ${info.clearedTokens} tokens · full result via read_result handle: ${info.handleId}${preview}]`;\n}\n\nfunction isAlreadyCleared(content: Message['content']): boolean {\n  return typeof content === 'string' && content.startsWith(CLEARED_TOOL_RESULT_MARKER);\n}\n\n/**\n * Replace the oldest clearable tool results with placeholders. Returns the new\n * buffer (same length — content is replaced in place, never removed) plus the\n * cleared indices and reclaimed token count. Idempotent: already-cleared\n * placeholders are skipped on a second pass.\n */\nexport async function clearOldToolResults(\n  messages: ReadonlyArray<Message>,\n  options: ClearToolResultsOptions,\n  counter: ContextTokenCounter,\n): Promise<ClearToolResultsOutcome> {\n  const keep = options.keepToolUses ?? DEFAULT_KEEP_TOOL_USES;\n  const exclude = new Set(options.excludeTools ?? []);\n  const placeholder = options.placeholder ?? defaultPlaceholder;\n\n  // toolCallId → toolName from every assistant tool-call in the buffer.\n  const toolNameById = new Map<string, string>();\n  for (const m of messages) {\n    if (m.role === 'assistant' && m.toolCalls) {\n      for (const tc of m.toolCalls) toolNameById.set(tc.toolCallId, tc.toolName);\n    }\n  }\n\n  // Indices of all not-yet-cleared tool-result messages, oldest first.\n  const toolIdx: number[] = [];\n  for (let i = 0; i < messages.length; i++) {\n    const m = messages[i];\n    if (m?.role === 'tool' && !isAlreadyCleared(m.content)) toolIdx.push(i);\n  }\n\n  // Keep the most-recent `keep`; older ones are candidates unless excluded.\n  const keptCutoff = toolIdx.length - Math.max(0, keep);\n  const replacements = new Map<number, ToolMessage>();\n  const clearedTokensByIdx = new Map<number, number>();\n  let reclaimable = 0;\n  for (let j = 0; j < toolIdx.length && j < keptCutoff; j++) {\n    const idx = toolIdx[j];\n    if (idx === undefined) continue;\n    const tm = messages[idx] as ToolMessage;\n    const name = toolNameById.get(tm.toolCallId);\n    if (name !== undefined && exclude.has(name)) continue;\n    const originalTokens = await countMessageTokens([tm], counter);\n    const replaced: ToolMessage = {\n      role: 'tool',\n      toolCallId: tm.toolCallId,\n      content: placeholder({\n        toolCallId: tm.toolCallId,\n        ...(name !== undefined ? { toolName: name } : {}),\n        clearedTokens: originalTokens,\n      }),\n    };\n    const placeholderTokens = await countMessageTokens([replaced], counter);\n    reclaimable += Math.max(0, originalTokens - placeholderTokens);\n    replacements.set(idx, replaced);\n    clearedTokensByIdx.set(idx, originalTokens);\n  }\n\n  const clearAtLeast = options.clearAtLeast ?? 0;\n  if (replacements.size === 0 || reclaimable < clearAtLeast) {\n    return { messages, clearedIndices: [], reclaimedTokens: 0 };\n  }\n\n  // A6: only now that the clearing commits, externalize each cleared result to a\n  // recoverable handle and rewrite its placeholder to reference it. Skipped\n  // clears (above) never reach here, so the spill never fires for nothing.\n  const externalize = options.externalize;\n  if (externalize !== undefined) {\n    for (const idx of replacements.keys()) {\n      const tm = messages[idx] as ToolMessage;\n      const name = toolNameById.get(tm.toolCallId);\n      const clearedTokens = clearedTokensByIdx.get(idx) ?? 0;\n      const content = typeof tm.content === 'string' ? tm.content : renderMessageText(tm);\n      const handle = await externalize(content, {\n        toolCallId: tm.toolCallId,\n        ...(name !== undefined ? { toolName: name } : {}),\n        clearedTokens,\n      });\n      replacements.set(idx, {\n        role: 'tool',\n        toolCallId: tm.toolCallId,\n        content: handlePlaceholder({\n          ...(name !== undefined ? { toolName: name } : {}),\n          clearedTokens,\n          handleId: handle.handleId,\n          ...(handle.preview !== undefined ? { preview: handle.preview } : {}),\n        }),\n      });\n    }\n  }\n\n  const out = messages.map((m, i) => replacements.get(i) ?? m);\n  return {\n    messages: out,\n    clearedIndices: [...replacements.keys()],\n    reclaimedTokens: reclaimable,\n  };\n}\n"],"mappings":"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"}

package/dist/context-engine/compaction/compactor.d.ts

@@ -0,0 +1,52 @@
+import { ContextLocalePack } from "../locale-packs/types.js";
+import { ContextTokenCounter } from "../token-counter.js";
+import { CompactionResult, CompactionSource, CompactionStrategy, CompactionSummarizer } from "./types.js";
+import * as _graphorin_core2 from "@graphorin/core";
+import { Message } from "@graphorin/core";
+
+//#region src/context-engine/compaction/compactor.d.ts
+
+/**
+ * Default count of recent turns preserved verbatim by the
+ * `summarize-old-preserve-recent` strategy.
+ *
+ * @stable
+ */
+declare const DEFAULT_PRESERVE_RECENT_TURNS = 6;
+/**
+ * Trim the in-flight buffer using the
+ * `summarize-old-preserve-recent` strategy. Returns the trimmed
+ * messages + summary metadata; the caller is responsible for
+ * appending the summary to the message buffer (Phase 12 owns the
+ * lifecycle; this module exposes the primitive).
+ *
+ * @stable
+ */
+interface ExecuteCompactionInput {
+  readonly messages: ReadonlyArray<Message>;
+  readonly source: CompactionSource;
+  readonly strategy: CompactionStrategy;
+  readonly localePack: ContextLocalePack;
+  readonly summarizer: CompactionSummarizer;
+  readonly tokenCounter?: ContextTokenCounter;
+  readonly thresholdTokens: number;
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly scope: _graphorin_core2.SessionScope;
+  readonly providerTrust?: _graphorin_core2.LocalProviderTrust;
+  readonly now?: () => number;
+  readonly signal?: AbortSignal;
+}
+/**
+ * Perform a compaction call. Returns the result envelope containing
+ * the produced summary, the dropped/preserved message slices, and
+ * the per-event metadata. Phase 12 / `agent.compact()` is the
+ * lifecycle owner; this function is the trim primitive.
+ *
+ * @stable
+ */
+declare function executeCompaction(input: ExecuteCompactionInput): Promise<CompactionResult>;
+//#endregion
+export { DEFAULT_PRESERVE_RECENT_TURNS, ExecuteCompactionInput, executeCompaction };
+//# sourceMappingURL=compactor.d.ts.map

package/dist/context-engine/compaction/compactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactor.d.ts","names":[],"sources":["../../../src/context-engine/compaction/compactor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;cAiDa,6BAAA;;;;;;;;;;UA0CI,sBAAA;qBACI,cAAc;mBAChB;qBACE;uBACE;uBACA;0BACG;;;;;kBAAmB,gBAAA,CAKD;2BAAY,gBAAA,CACH;;oBAEjC;;;;;;;;;;iBAWE,iBAAA,QAAyB,yBAAyB,QAAQ"}