@graphorin/agent 0.5.0

package/dist/lateral-leak/causality-monitor.js

@@ -0,0 +1,139 @@
+//#region src/lateral-leak/causality-monitor.ts
+/**
+* Default denial-pattern catalogue. The agent runtime extends this
+* list when the operator supplies their own patterns.
+*
+* @stable
+*/
+const DEFAULT_DENIAL_PATTERNS = [
+	/SecretAccessDenied/i,
+	/ToolApprovalDenied/i,
+	/HandoffPermissionDenied/i,
+	/SandboxViolation/i
+];
+/** Default chain depth when not specified. */
+const DEFAULT_MAX_CHAIN_DEPTH = 32;
+/**
+* In-memory primitive instantiated per `RunContext`. Bounded-depth
+* append discipline keeps the memory footprint trivial even on long
+* runs.
+*
+* @stable
+*/
+var CausalityMonitor = class {
+	strictness;
+	maxChainDepth;
+	denialPatterns;
+	auditAllChains;
+	#chain = [];
+	constructor(cfg) {
+		this.strictness = cfg.strictness;
+		this.maxChainDepth = cfg.maxChainDepth ?? DEFAULT_MAX_CHAIN_DEPTH;
+		this.denialPatterns = cfg.denialPatterns ? [...DEFAULT_DENIAL_PATTERNS, ...cfg.denialPatterns] : DEFAULT_DENIAL_PATTERNS;
+		this.auditAllChains = cfg.auditAllChains ?? false;
+	}
+	/** Snapshot the current causality chain. */
+	get chain() {
+		return this.#chain.slice();
+	}
+	/**
+	* Append an entry to the causality chain, dropping the oldest
+	* when the chain exceeds `maxChainDepth`. Bounded-length, no PII,
+	* no secret values — entries are short opaque strings like
+	* `tool:slack-notify`, `tool.error:SecretAccessDenied`,
+	* `subagent:research-east`, `compaction:auto-trigger`.
+	*/
+	recordCall(entry) {
+		if (this.strictness === "off") return;
+		if (entry.length === 0) return;
+		this.#chain.push(entry);
+		if (this.#chain.length > this.maxChainDepth) this.#chain.shift();
+	}
+	/** Reset the chain — e.g. on `agent.run` boundary. */
+	reset() {
+		this.#chain = [];
+	}
+	/**
+	* Inspect a candidate assistant-visible string and return whether
+	* the lateral-leak defense should fire. Pure decision based on
+	* the current chain + the operator-extensible denial patterns.
+	*/
+	checkMessage(content) {
+		if (this.strictness === "off") return {
+			leakDetected: false,
+			severity: "info",
+			causalityChain: [],
+			decision: "detect",
+			vector: "causality-laundering"
+		};
+		if (!this.#chain.some((entry) => this.denialPatterns.some((pat) => pat.test(entry)))) return {
+			leakDetected: false,
+			severity: "info",
+			causalityChain: this.chain,
+			decision: "detect",
+			vector: "causality-laundering"
+		};
+		let matchedPattern;
+		for (const pat of this.denialPatterns) if (pat.test(content)) {
+			matchedPattern = pat.source;
+			break;
+		}
+		if (!(matchedPattern !== void 0)) return {
+			leakDetected: false,
+			severity: "info",
+			causalityChain: this.chain,
+			decision: "detect",
+			vector: "causality-laundering"
+		};
+		switch (this.strictness) {
+			case "detect": return {
+				leakDetected: true,
+				severity: "info",
+				causalityChain: this.chain,
+				...matchedPattern !== void 0 ? { matchedPattern } : {},
+				decision: "detect",
+				vector: "causality-laundering"
+			};
+			case "detect-and-flag": return {
+				leakDetected: true,
+				severity: "warn",
+				causalityChain: this.chain,
+				...matchedPattern !== void 0 ? { matchedPattern } : {},
+				decision: "flag",
+				vector: "causality-laundering"
+			};
+			case "detect-and-block": return {
+				leakDetected: true,
+				severity: "block",
+				causalityChain: this.chain,
+				...matchedPattern !== void 0 ? { matchedPattern } : {},
+				decision: "block",
+				vector: "causality-laundering"
+			};
+			default:
+				this.strictness;
+				return {
+					leakDetected: false,
+					severity: "info",
+					causalityChain: this.chain,
+					decision: "detect",
+					vector: "causality-laundering"
+				};
+		}
+	}
+	/**
+	* Drain the chain to the audit log on `agent.run` completion or
+	* `agent.abort`. The runtime supplies the audit emitter — the
+	* primitive itself is storage-agnostic.
+	*/
+	flush(reason) {
+		return {
+			chain: this.chain,
+			reason
+		};
+	}
+};
+
+//#endregion
+export { CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH };
+//# sourceMappingURL=causality-monitor.js.map

package/dist/lateral-leak/causality-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"causality-monitor.js","names":["DEFAULT_DENIAL_PATTERNS: ReadonlyArray<RegExp>","#chain","matchedPattern: string | undefined"],"sources":["../../src/lateral-leak/causality-monitor.ts"],"sourcesContent":["/**\n * `CausalityMonitor` — lateral-leak defense primitive that maintains\n * a per-`RunContext` `causalityChain` of bounded depth and refuses\n * to let an assistant message reference information about a denied\n * earlier action.\n *\n * The monitor is opt-in: agents declare `causalityMonitor:\n * { strictness, denialPatterns?, ... }` on `createAgent({...})`.\n * When the field is absent, the runtime instantiates a no-op monitor\n * that records nothing and never flags.\n *\n * @packageDocumentation\n */\n\nimport type { LateralLeakVector } from '@graphorin/core';\n\n/**\n * Operator-tunable strictness level. Default `'detect-and-flag'`\n * for cloud-tier providers; `'detect'` for loopback providers;\n * `'off'` for v0.1-alpha backward compatibility.\n *\n * @stable\n */\nexport type CausalityMonitorStrictness = 'off' | 'detect' | 'detect-and-flag' | 'detect-and-block';\n\n/**\n * Per-agent configuration accepted by `createAgent({ causalityMonitor })`.\n *\n * @stable\n */\nexport interface CausalityMonitorConfig {\n  readonly strictness: CausalityMonitorStrictness;\n  /** Maximum depth of the chain. Default `32`. */\n  readonly maxChainDepth?: number;\n  /** Operator-extensible denial patterns. */\n  readonly denialPatterns?: ReadonlyArray<RegExp>;\n  /**\n   * When `true`, emit the chain on every `checkMessage(...)` call\n   * (high-cardinality; opt-in for compliance audits). Default\n   * `false` — only emit on detected leaks.\n   */\n  readonly auditAllChains?: boolean;\n}\n\n/**\n * Default denial-pattern catalogue. The agent runtime extends this\n * list when the operator supplies their own patterns.\n *\n * @stable\n */\nexport const DEFAULT_DENIAL_PATTERNS: ReadonlyArray<RegExp> = [\n  /SecretAccessDenied/i,\n  /ToolApprovalDenied/i,\n  /HandoffPermissionDenied/i,\n  /SandboxViolation/i,\n];\n\n/** Default chain depth when not specified. */\nexport const DEFAULT_MAX_CHAIN_DEPTH = 32;\n\n/**\n * Result returned by {@link CausalityMonitor.checkMessage}.\n *\n * @stable\n */\nexport interface CausalityMonitorCheck {\n  readonly leakDetected: boolean;\n  readonly severity: 'info' | 'warn' | 'block';\n  readonly causalityChain: ReadonlyArray<string>;\n  readonly matchedPattern?: string;\n  readonly decision: 'detect' | 'flag' | 'strip' | 'block';\n  readonly vector: LateralLeakVector;\n}\n\n/**\n * In-memory primitive instantiated per `RunContext`. Bounded-depth\n * append discipline keeps the memory footprint trivial even on long\n * runs.\n *\n * @stable\n */\nexport class CausalityMonitor {\n  readonly strictness: CausalityMonitorStrictness;\n  readonly maxChainDepth: number;\n  readonly denialPatterns: ReadonlyArray<RegExp>;\n  readonly auditAllChains: boolean;\n  #chain: string[] = [];\n\n  constructor(cfg: CausalityMonitorConfig) {\n    this.strictness = cfg.strictness;\n    this.maxChainDepth = cfg.maxChainDepth ?? DEFAULT_MAX_CHAIN_DEPTH;\n    this.denialPatterns = cfg.denialPatterns\n      ? [...DEFAULT_DENIAL_PATTERNS, ...cfg.denialPatterns]\n      : DEFAULT_DENIAL_PATTERNS;\n    this.auditAllChains = cfg.auditAllChains ?? false;\n  }\n\n  /** Snapshot the current causality chain. */\n  get chain(): ReadonlyArray<string> {\n    return this.#chain.slice();\n  }\n\n  /**\n   * Append an entry to the causality chain, dropping the oldest\n   * when the chain exceeds `maxChainDepth`. Bounded-length, no PII,\n   * no secret values — entries are short opaque strings like\n   * `tool:slack-notify`, `tool.error:SecretAccessDenied`,\n   * `subagent:research-east`, `compaction:auto-trigger`.\n   */\n  recordCall(entry: string): void {\n    if (this.strictness === 'off') return;\n    if (entry.length === 0) return;\n    this.#chain.push(entry);\n    if (this.#chain.length > this.maxChainDepth) {\n      this.#chain.shift();\n    }\n  }\n\n  /** Reset the chain — e.g. on `agent.run` boundary. */\n  reset(): void {\n    this.#chain = [];\n  }\n\n  /**\n   * Inspect a candidate assistant-visible string and return whether\n   * the lateral-leak defense should fire. Pure decision based on\n   * the current chain + the operator-extensible denial patterns.\n   */\n  checkMessage(content: string): CausalityMonitorCheck {\n    if (this.strictness === 'off') {\n      return {\n        leakDetected: false,\n        severity: 'info',\n        causalityChain: [],\n        decision: 'detect',\n        vector: 'causality-laundering',\n      };\n    }\n    const chainHasDenial = this.#chain.some((entry) =>\n      this.denialPatterns.some((pat) => pat.test(entry)),\n    );\n    if (!chainHasDenial) {\n      return {\n        leakDetected: false,\n        severity: 'info',\n        causalityChain: this.chain,\n        decision: 'detect',\n        vector: 'causality-laundering',\n      };\n    }\n    let matchedPattern: string | undefined;\n    for (const pat of this.denialPatterns) {\n      if (pat.test(content)) {\n        matchedPattern = pat.source;\n        break;\n      }\n    }\n    const leakDetected = matchedPattern !== undefined;\n    if (!leakDetected) {\n      return {\n        leakDetected: false,\n        severity: 'info',\n        causalityChain: this.chain,\n        decision: 'detect',\n        vector: 'causality-laundering',\n      };\n    }\n    switch (this.strictness) {\n      case 'detect':\n        return {\n          leakDetected: true,\n          severity: 'info',\n          causalityChain: this.chain,\n          ...(matchedPattern !== undefined ? { matchedPattern } : {}),\n          decision: 'detect',\n          vector: 'causality-laundering',\n        };\n      case 'detect-and-flag':\n        return {\n          leakDetected: true,\n          severity: 'warn',\n          causalityChain: this.chain,\n          ...(matchedPattern !== undefined ? { matchedPattern } : {}),\n          decision: 'flag',\n          vector: 'causality-laundering',\n        };\n      case 'detect-and-block':\n        return {\n          leakDetected: true,\n          severity: 'block',\n          causalityChain: this.chain,\n          ...(matchedPattern !== undefined ? { matchedPattern } : {}),\n          decision: 'block',\n          vector: 'causality-laundering',\n        };\n      default: {\n        const _exhaustive: never = this.strictness;\n        void _exhaustive;\n        return {\n          leakDetected: false,\n          severity: 'info',\n          causalityChain: this.chain,\n          decision: 'detect',\n          vector: 'causality-laundering',\n        };\n      }\n    }\n  }\n\n  /**\n   * Drain the chain to the audit log on `agent.run` completion or\n   * `agent.abort`. The runtime supplies the audit emitter — the\n   * primitive itself is storage-agnostic.\n   */\n  flush(reason: 'agent.run.complete' | 'agent.abort'): {\n    readonly chain: ReadonlyArray<string>;\n    readonly reason: 'agent.run.complete' | 'agent.abort';\n  } {\n    return { chain: this.chain, reason };\n  }\n}\n"],"mappings":";;;;;;;AAkDA,MAAaA,0BAAiD;CAC5D;CACA;CACA;CACA;CACD;;AAGD,MAAa,0BAA0B;;;;;;;;AAuBvC,IAAa,mBAAb,MAA8B;CAC5B,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CACT,SAAmB,EAAE;CAErB,YAAY,KAA6B;AACvC,OAAK,aAAa,IAAI;AACtB,OAAK,gBAAgB,IAAI,iBAAiB;AAC1C,OAAK,iBAAiB,IAAI,iBACtB,CAAC,GAAG,yBAAyB,GAAG,IAAI,eAAe,GACnD;AACJ,OAAK,iBAAiB,IAAI,kBAAkB;;;CAI9C,IAAI,QAA+B;AACjC,SAAO,MAAKC,MAAO,OAAO;;;;;;;;;CAU5B,WAAW,OAAqB;AAC9B,MAAI,KAAK,eAAe,MAAO;AAC/B,MAAI,MAAM,WAAW,EAAG;AACxB,QAAKA,MAAO,KAAK,MAAM;AACvB,MAAI,MAAKA,MAAO,SAAS,KAAK,cAC5B,OAAKA,MAAO,OAAO;;;CAKvB,QAAc;AACZ,QAAKA,QAAS,EAAE;;;;;;;CAQlB,aAAa,SAAwC;AACnD,MAAI,KAAK,eAAe,MACtB,QAAO;GACL,cAAc;GACd,UAAU;GACV,gBAAgB,EAAE;GAClB,UAAU;GACV,QAAQ;GACT;AAKH,MAAI,CAHmB,MAAKA,MAAO,MAAM,UACvC,KAAK,eAAe,MAAM,QAAQ,IAAI,KAAK,MAAM,CAAC,CACnD,CAEC,QAAO;GACL,cAAc;GACd,UAAU;GACV,gBAAgB,KAAK;GACrB,UAAU;GACV,QAAQ;GACT;EAEH,IAAIC;AACJ,OAAK,MAAM,OAAO,KAAK,eACrB,KAAI,IAAI,KAAK,QAAQ,EAAE;AACrB,oBAAiB,IAAI;AACrB;;AAIJ,MAAI,EADiB,mBAAmB,QAEtC,QAAO;GACL,cAAc;GACd,UAAU;GACV,gBAAgB,KAAK;GACrB,UAAU;GACV,QAAQ;GACT;AAEH,UAAQ,KAAK,YAAb;GACE,KAAK,SACH,QAAO;IACL,cAAc;IACd,UAAU;IACV,gBAAgB,KAAK;IACrB,GAAI,mBAAmB,SAAY,EAAE,gBAAgB,GAAG,EAAE;IAC1D,UAAU;IACV,QAAQ;IACT;GACH,KAAK,kBACH,QAAO;IACL,cAAc;IACd,UAAU;IACV,gBAAgB,KAAK;IACrB,GAAI,mBAAmB,SAAY,EAAE,gBAAgB,GAAG,EAAE;IAC1D,UAAU;IACV,QAAQ;IACT;GACH,KAAK,mBACH,QAAO;IACL,cAAc;IACd,UAAU;IACV,gBAAgB,KAAK;IACrB,GAAI,mBAAmB,SAAY,EAAE,gBAAgB,GAAG,EAAE;IAC1D,UAAU;IACV,QAAQ;IACT;GACH;AAC6B,SAAK;AAEhC,WAAO;KACL,cAAc;KACd,UAAU;KACV,gBAAgB,KAAK;KACrB,UAAU;KACV,QAAQ;KACT;;;;;;;;CAUP,MAAM,QAGJ;AACA,SAAO;GAAE,OAAO,KAAK;GAAO;GAAQ"}

package/dist/lateral-leak/index.d.ts

@@ -0,0 +1,4 @@
+import { ChildTrustInput, ContentOriginKind, MergeBiasDecision, MergeGuardConfig, TrustClass, computeSourceTrust, evaluateMerge } from "./merge-guard.js";
+import { CausalityMonitor, CausalityMonitorCheck, CausalityMonitorConfig, CausalityMonitorStrictness, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH } from "./causality-monitor.js";
+import { GuardOutcome, ProtocolBoundary, ProtocolEscapePolicy, ProtocolGuardConfig, guardOutboundContent, resolvePolicy } from "./protocol-guard.js";
+export { CausalityMonitor, type CausalityMonitorCheck, type CausalityMonitorConfig, type CausalityMonitorStrictness, type ChildTrustInput, type ContentOriginKind, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH, type GuardOutcome, type MergeBiasDecision, type MergeGuardConfig, type ProtocolBoundary, type ProtocolEscapePolicy, type ProtocolGuardConfig, type TrustClass, computeSourceTrust, evaluateMerge, guardOutboundContent, resolvePolicy };

package/dist/lateral-leak/index.js

@@ -0,0 +1,5 @@
+import { computeSourceTrust, evaluateMerge } from "./merge-guard.js";
+import { CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH } from "./causality-monitor.js";
+import { guardOutboundContent, resolvePolicy } from "./protocol-guard.js";
+
+export { CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH, computeSourceTrust, evaluateMerge, guardOutboundContent, resolvePolicy };

package/dist/lateral-leak/merge-guard.d.ts

@@ -0,0 +1,89 @@
+//#region src/lateral-leak/merge-guard.d.ts
+/**
+ * `MergeAgentSidewaysInjectionGuard` — layered on top of the
+ * `Agent.fanOut(...)` `'judge-merge'` strategy. Computes a
+ * per-child `sourceTrust` score in `[0.0, 1.0]` and flags merges
+ * where a low-trust child's contribution-weight exceeds the
+ * configured `maxLowTrustWeight` threshold.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Trust-class baseline used by the guard's `sourceTrust`
+ * computation. Mirrors the DEC-149 trust-class taxonomy from
+ * `@graphorin/provider`.
+ *
+ * @stable
+ */
+type TrustClass = 'loopback' | 'public-tls' | 'public-mtls' | 'untrusted-skill';
+/**
+ * Tool-source provenance multiplier. Mirrors the `ContentOrigin`
+ * annotation from `@graphorin/memory.context-engine`.
+ *
+ * @stable
+ */
+type ContentOriginKind = 'built-in' | 'user-defined' | 'trusted-skill' | 'untrusted-skill' | 'mcp' | 'web-search';
+/**
+ * Per-agent guard configuration accepted by
+ * `createAgent({ mergeGuard })`.
+ *
+ * @stable
+ */
+interface MergeGuardConfig {
+  readonly strictness: 'off' | 'detect' | 'detect-and-flag' | 'detect-and-block';
+  /** Default `0.3`. */
+  readonly maxLowTrustWeight?: number;
+  /** Default `0.5`. */
+  readonly lowTrustThreshold?: number;
+  /** Operator overrides for known agent ids. */
+  readonly sourceTrustOverrides?: Readonly<Record<string, number>>;
+}
+/**
+ * Per-child input descriptor for {@link computeSourceTrust}.
+ *
+ * @stable
+ */
+interface ChildTrustInput {
+  readonly agentId: string;
+  readonly trustClass: TrustClass;
+  readonly origin: ContentOriginKind;
+  /** Rolling trust score in `[0.0, 1.0]`. Defaults to `1.0`. */
+  readonly historyAdjustment?: number;
+}
+/**
+ * Compose `baseline * provenance * historyAdjustment` and clamp.
+ *
+ * @stable
+ */
+declare function computeSourceTrust(input: ChildTrustInput, overrides?: Readonly<Record<string, number>>): number;
+/**
+ * Pure decision returned by {@link evaluateMerge}.
+ *
+ * @stable
+ */
+interface MergeBiasDecision {
+  readonly biased: boolean;
+  readonly offendingChild?: string;
+  readonly contributionWeight?: number;
+  readonly sourceTrust?: number;
+  readonly decision: 'pass-through' | 'flag' | 'block';
+}
+/**
+ * Evaluate whether the merge is biased — a child with
+ * `sourceTrust < lowTrustThreshold` contributing more than
+ * `maxLowTrustWeight` of the merged output.
+ *
+ * Inputs are pre-computed per-child trust scores together with the
+ * estimated contribution weights (token-count overlap between each
+ * child's output and the merged output, normalized to sum to ~1.0).
+ *
+ * @stable
+ */
+declare function evaluateMerge(perChild: ReadonlyArray<{
+  readonly agentId: string;
+  readonly sourceTrust: number;
+  readonly contributionWeight: number;
+}>, cfg: MergeGuardConfig): MergeBiasDecision;
+//#endregion
+export { ChildTrustInput, ContentOriginKind, MergeBiasDecision, MergeGuardConfig, TrustClass, computeSourceTrust, evaluateMerge };
+//# sourceMappingURL=merge-guard.d.ts.map

package/dist/lateral-leak/merge-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-guard.d.ts","names":[],"sources":["../../src/lateral-leak/merge-guard.ts"],"sourcesContent":[],"mappings":";;AAiBA;AAeA;AAuBA;AAeA;AAaA;;;;;AAiBA;AAmBA;;;;;KAtGY,UAAA;;;;;;;KAeA,iBAAA;;;;;;;UAuBK,gBAAA;;;;;;;kCAOiB,SAAS;;;;;;;UAQ1B,eAAA;;uBAEM;mBACJ;;;;;;;;;iBAUH,kBAAA,QACP,6BACI,SAAS;;;;;;UAeL,iBAAA;;;;;;;;;;;;;;;;;;iBAmBD,aAAA,WACJ;;;;SAKL,mBACJ"}

package/dist/lateral-leak/merge-guard.js

@@ -0,0 +1,65 @@
+//#region src/lateral-leak/merge-guard.ts
+const TRUST_CLASS_BASELINE = {
+	loopback: .9,
+	"public-tls": .7,
+	"public-mtls": .8,
+	"untrusted-skill": .3
+};
+const ORIGIN_MULTIPLIER = {
+	"built-in": 1,
+	"user-defined": .9,
+	"trusted-skill": .85,
+	"untrusted-skill": .4,
+	mcp: .7,
+	"web-search": .5
+};
+/**
+* Compose `baseline * provenance * historyAdjustment` and clamp.
+*
+* @stable
+*/
+function computeSourceTrust(input, overrides = {}) {
+	const override = overrides[input.agentId];
+	if (override !== void 0) return Math.max(0, Math.min(1, override));
+	const baseline = TRUST_CLASS_BASELINE[input.trustClass];
+	const provenance = ORIGIN_MULTIPLIER[input.origin];
+	const history = input.historyAdjustment ?? 1;
+	return Math.max(0, Math.min(1, baseline * provenance * history));
+}
+/**
+* Evaluate whether the merge is biased — a child with
+* `sourceTrust < lowTrustThreshold` contributing more than
+* `maxLowTrustWeight` of the merged output.
+*
+* Inputs are pre-computed per-child trust scores together with the
+* estimated contribution weights (token-count overlap between each
+* child's output and the merged output, normalized to sum to ~1.0).
+*
+* @stable
+*/
+function evaluateMerge(perChild, cfg) {
+	if (cfg.strictness === "off") return {
+		biased: false,
+		decision: "pass-through"
+	};
+	const lowTrustThreshold = cfg.lowTrustThreshold ?? .5;
+	const maxLowTrustWeight = cfg.maxLowTrustWeight ?? .3;
+	for (const child of perChild) if (child.sourceTrust < lowTrustThreshold && child.contributionWeight > maxLowTrustWeight) {
+		const decision = cfg.strictness === "detect-and-block" ? "block" : cfg.strictness === "detect-and-flag" ? "flag" : "pass-through";
+		return {
+			biased: true,
+			offendingChild: child.agentId,
+			contributionWeight: child.contributionWeight,
+			sourceTrust: child.sourceTrust,
+			decision
+		};
+	}
+	return {
+		biased: false,
+		decision: "pass-through"
+	};
+}
+
+//#endregion
+export { computeSourceTrust, evaluateMerge };
+//# sourceMappingURL=merge-guard.js.map

package/dist/lateral-leak/merge-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-guard.js","names":["TRUST_CLASS_BASELINE: Record<TrustClass, number>","ORIGIN_MULTIPLIER: Record<ContentOriginKind, number>","decision: MergeBiasDecision['decision']"],"sources":["../../src/lateral-leak/merge-guard.ts"],"sourcesContent":["/**\n * `MergeAgentSidewaysInjectionGuard` — layered on top of the\n * `Agent.fanOut(...)` `'judge-merge'` strategy. Computes a\n * per-child `sourceTrust` score in `[0.0, 1.0]` and flags merges\n * where a low-trust child's contribution-weight exceeds the\n * configured `maxLowTrustWeight` threshold.\n *\n * @packageDocumentation\n */\n\n/**\n * Trust-class baseline used by the guard's `sourceTrust`\n * computation. Mirrors the DEC-149 trust-class taxonomy from\n * `@graphorin/provider`.\n *\n * @stable\n */\nexport type TrustClass = 'loopback' | 'public-tls' | 'public-mtls' | 'untrusted-skill';\n\nconst TRUST_CLASS_BASELINE: Record<TrustClass, number> = {\n  loopback: 0.9,\n  'public-tls': 0.7,\n  'public-mtls': 0.8,\n  'untrusted-skill': 0.3,\n};\n\n/**\n * Tool-source provenance multiplier. Mirrors the `ContentOrigin`\n * annotation from `@graphorin/memory.context-engine`.\n *\n * @stable\n */\nexport type ContentOriginKind =\n  | 'built-in'\n  | 'user-defined'\n  | 'trusted-skill'\n  | 'untrusted-skill'\n  | 'mcp'\n  | 'web-search';\n\nconst ORIGIN_MULTIPLIER: Record<ContentOriginKind, number> = {\n  'built-in': 1.0,\n  'user-defined': 0.9,\n  'trusted-skill': 0.85,\n  'untrusted-skill': 0.4,\n  mcp: 0.7,\n  'web-search': 0.5,\n};\n\n/**\n * Per-agent guard configuration accepted by\n * `createAgent({ mergeGuard })`.\n *\n * @stable\n */\nexport interface MergeGuardConfig {\n  readonly strictness: 'off' | 'detect' | 'detect-and-flag' | 'detect-and-block';\n  /** Default `0.3`. */\n  readonly maxLowTrustWeight?: number;\n  /** Default `0.5`. */\n  readonly lowTrustThreshold?: number;\n  /** Operator overrides for known agent ids. */\n  readonly sourceTrustOverrides?: Readonly<Record<string, number>>;\n}\n\n/**\n * Per-child input descriptor for {@link computeSourceTrust}.\n *\n * @stable\n */\nexport interface ChildTrustInput {\n  readonly agentId: string;\n  readonly trustClass: TrustClass;\n  readonly origin: ContentOriginKind;\n  /** Rolling trust score in `[0.0, 1.0]`. Defaults to `1.0`. */\n  readonly historyAdjustment?: number;\n}\n\n/**\n * Compose `baseline * provenance * historyAdjustment` and clamp.\n *\n * @stable\n */\nexport function computeSourceTrust(\n  input: ChildTrustInput,\n  overrides: Readonly<Record<string, number>> = {},\n): number {\n  const override = overrides[input.agentId];\n  if (override !== undefined) return Math.max(0, Math.min(1, override));\n  const baseline = TRUST_CLASS_BASELINE[input.trustClass];\n  const provenance = ORIGIN_MULTIPLIER[input.origin];\n  const history = input.historyAdjustment ?? 1.0;\n  return Math.max(0, Math.min(1, baseline * provenance * history));\n}\n\n/**\n * Pure decision returned by {@link evaluateMerge}.\n *\n * @stable\n */\nexport interface MergeBiasDecision {\n  readonly biased: boolean;\n  readonly offendingChild?: string;\n  readonly contributionWeight?: number;\n  readonly sourceTrust?: number;\n  readonly decision: 'pass-through' | 'flag' | 'block';\n}\n\n/**\n * Evaluate whether the merge is biased — a child with\n * `sourceTrust < lowTrustThreshold` contributing more than\n * `maxLowTrustWeight` of the merged output.\n *\n * Inputs are pre-computed per-child trust scores together with the\n * estimated contribution weights (token-count overlap between each\n * child's output and the merged output, normalized to sum to ~1.0).\n *\n * @stable\n */\nexport function evaluateMerge(\n  perChild: ReadonlyArray<{\n    readonly agentId: string;\n    readonly sourceTrust: number;\n    readonly contributionWeight: number;\n  }>,\n  cfg: MergeGuardConfig,\n): MergeBiasDecision {\n  if (cfg.strictness === 'off') {\n    return { biased: false, decision: 'pass-through' };\n  }\n  const lowTrustThreshold = cfg.lowTrustThreshold ?? 0.5;\n  const maxLowTrustWeight = cfg.maxLowTrustWeight ?? 0.3;\n  for (const child of perChild) {\n    if (child.sourceTrust < lowTrustThreshold && child.contributionWeight > maxLowTrustWeight) {\n      const decision: MergeBiasDecision['decision'] =\n        cfg.strictness === 'detect-and-block'\n          ? 'block'\n          : cfg.strictness === 'detect-and-flag'\n            ? 'flag'\n            : 'pass-through';\n      return {\n        biased: true,\n        offendingChild: child.agentId,\n        contributionWeight: child.contributionWeight,\n        sourceTrust: child.sourceTrust,\n        decision,\n      };\n    }\n  }\n  return { biased: false, decision: 'pass-through' };\n}\n"],"mappings":";AAmBA,MAAMA,uBAAmD;CACvD,UAAU;CACV,cAAc;CACd,eAAe;CACf,mBAAmB;CACpB;AAgBD,MAAMC,oBAAuD;CAC3D,YAAY;CACZ,gBAAgB;CAChB,iBAAiB;CACjB,mBAAmB;CACnB,KAAK;CACL,cAAc;CACf;;;;;;AAoCD,SAAgB,mBACd,OACA,YAA8C,EAAE,EACxC;CACR,MAAM,WAAW,UAAU,MAAM;AACjC,KAAI,aAAa,OAAW,QAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,SAAS,CAAC;CACrE,MAAM,WAAW,qBAAqB,MAAM;CAC5C,MAAM,aAAa,kBAAkB,MAAM;CAC3C,MAAM,UAAU,MAAM,qBAAqB;AAC3C,QAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,WAAW,aAAa,QAAQ,CAAC;;;;;;;;;;;;;AA2BlE,SAAgB,cACd,UAKA,KACmB;AACnB,KAAI,IAAI,eAAe,MACrB,QAAO;EAAE,QAAQ;EAAO,UAAU;EAAgB;CAEpD,MAAM,oBAAoB,IAAI,qBAAqB;CACnD,MAAM,oBAAoB,IAAI,qBAAqB;AACnD,MAAK,MAAM,SAAS,SAClB,KAAI,MAAM,cAAc,qBAAqB,MAAM,qBAAqB,mBAAmB;EACzF,MAAMC,WACJ,IAAI,eAAe,qBACf,UACA,IAAI,eAAe,oBACjB,SACA;AACR,SAAO;GACL,QAAQ;GACR,gBAAgB,MAAM;GACtB,oBAAoB,MAAM;GAC1B,aAAa,MAAM;GACnB;GACD;;AAGL,QAAO;EAAE,QAAQ;EAAO,UAAU;EAAgB"}

package/dist/lateral-leak/protocol-guard.d.ts

@@ -0,0 +1,76 @@
+//#region src/lateral-leak/protocol-guard.d.ts
+/**
+ * Protocol/header injection guard — escapes control characters in
+ * tool result bodies before they cross internal-service delivery
+ * boundaries (SSE, WebSocket, REST body, HTTP header, audit row).
+ *
+ * The default policy mirrors the deployment-posture matrix from the
+ * lateral-leak design (DEC-171 / suggested ADR-059):
+ *
+ * - `'sse' | 'http-header'`  → `'strict'`  (escape control chars to
+ *   `\xNN` hex literals; the safest default for cleartext frame
+ *   protocols).
+ * - `'ws' | 'rest-body'`     → `'replace'` (replace with the Unicode
+ *   replacement character `\uFFFD`).
+ * - `'audit'`                → `'strict'`  (regulated deployments).
+ * - `'reject'` is operator opt-in — the guard throws
+ *   {@link ProtocolInjectionRejectError} when control characters are
+ *   detected.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Per-boundary identifier used by the runtime when calling the
+ * guard.
+ *
+ * @stable
+ */
+type ProtocolBoundary = 'sse' | 'http-header' | 'ws' | 'rest-body' | 'audit';
+/**
+ * Per-boundary escape policy.
+ *
+ * @stable
+ */
+type ProtocolEscapePolicy = 'strict' | 'replace' | 'reject';
+/**
+ * Configurable per-boundary policy table. Operators may override
+ * specific boundaries via `Agent.protocolGuard?: { ... }`.
+ *
+ * @stable
+ */
+interface ProtocolGuardConfig {
+  readonly sse?: ProtocolEscapePolicy;
+  readonly httpHeader?: ProtocolEscapePolicy;
+  readonly ws?: ProtocolEscapePolicy;
+  readonly restBody?: ProtocolEscapePolicy;
+  readonly audit?: ProtocolEscapePolicy;
+}
+/**
+ * Resolved policy lookup. Pure function — no side effects.
+ *
+ * @stable
+ */
+declare function resolvePolicy(boundary: ProtocolBoundary, cfg?: ProtocolGuardConfig): ProtocolEscapePolicy;
+/**
+ * Outcome of {@link guardOutboundContent}.
+ *
+ * @stable
+ */
+interface GuardOutcome {
+  readonly content: string;
+  readonly escapedCharCount: number;
+  readonly matchedPattern?: string;
+  readonly decision: 'pass-through' | 'escaped' | 'replaced' | 'rejected';
+  readonly boundary: ProtocolBoundary;
+  readonly policy: ProtocolEscapePolicy;
+}
+/**
+ * Apply the configured escape policy to a single string body. Pure
+ * — never mutates inputs.
+ *
+ * @stable
+ */
+declare function guardOutboundContent(input: string, boundary: ProtocolBoundary, cfg?: ProtocolGuardConfig): GuardOutcome;
+//#endregion
+export { GuardOutcome, ProtocolBoundary, ProtocolEscapePolicy, ProtocolGuardConfig, guardOutboundContent, resolvePolicy };
+//# sourceMappingURL=protocol-guard.d.ts.map

package/dist/lateral-leak/protocol-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-guard.d.ts","names":[],"sources":["../../src/lateral-leak/protocol-guard.ts"],"sourcesContent":[],"mappings":";;AA6BA;AAOA;AAQA;;;;;;;AAaA;;;;;AA+CA;AAgEA;;;;;;;;;;KA3IY,gBAAA;;;;;;KAOA,oBAAA;;;;;;;UAQK,mBAAA;iBACA;wBACO;gBACR;sBACM;mBACH;;;;;;;iBAQH,aAAA,WACJ,wBACL,sBACJ;;;;;;UA4Cc,YAAA;;;;;qBAKI;mBACF;;;;;;;;iBA0DH,oBAAA,0BAEJ,wBACL,sBACJ"}

package/dist/lateral-leak/protocol-guard.js

@@ -0,0 +1,147 @@
+import { ProtocolInjectionRejectError } from "../errors/index.js";
+
+//#region src/lateral-leak/protocol-guard.ts
+/**
+* Protocol/header injection guard — escapes control characters in
+* tool result bodies before they cross internal-service delivery
+* boundaries (SSE, WebSocket, REST body, HTTP header, audit row).
+*
+* The default policy mirrors the deployment-posture matrix from the
+* lateral-leak design (DEC-171 / suggested ADR-059):
+*
+* - `'sse' | 'http-header'`  → `'strict'`  (escape control chars to
+*   `\xNN` hex literals; the safest default for cleartext frame
+*   protocols).
+* - `'ws' | 'rest-body'`     → `'replace'` (replace with the Unicode
+*   replacement character `\uFFFD`).
+* - `'audit'`                → `'strict'`  (regulated deployments).
+* - `'reject'` is operator opt-in — the guard throws
+*   {@link ProtocolInjectionRejectError} when control characters are
+*   detected.
+*
+* @packageDocumentation
+*/
+/**
+* Resolved policy lookup. Pure function — no side effects.
+*
+* @stable
+*/
+function resolvePolicy(boundary, cfg = {}) {
+	switch (boundary) {
+		case "sse": return cfg.sse ?? "strict";
+		case "http-header": return cfg.httpHeader ?? "strict";
+		case "ws": return cfg.ws ?? "replace";
+		case "rest-body": return cfg.restBody ?? "replace";
+		case "audit": return cfg.audit ?? "strict";
+		default: return "strict";
+	}
+}
+function buildControlCharsRegex() {
+	const codePoints = [];
+	for (let n = 0; n < 32; n++) {
+		if (n === 9 || n === 10 || n === 13) continue;
+		codePoints.push(n);
+	}
+	codePoints.push(127);
+	const cls = codePoints.map((c) => `\\x${c.toString(16).padStart(2, "0")}`).join("");
+	return new RegExp(`[${cls}]`, "g");
+}
+const CONTROL_CHARS_RE = buildControlCharsRegex();
+const SSE_FRAME_RE = /\r?\n\r?\n/g;
+const HEADER_CRLF_RE = /\r\n/g;
+function escapeStrict(input, boundary) {
+	let count = 0;
+	let out = input.replace(CONTROL_CHARS_RE, (ch) => {
+		count += 1;
+		return `\\x${ch.charCodeAt(0).toString(16).padStart(2, "0")}`;
+	});
+	if (boundary === "sse") out = out.replace(SSE_FRAME_RE, (m) => {
+		count += 1;
+		return m.replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+	});
+	if (boundary === "http-header" || boundary === "audit") out = out.replace(HEADER_CRLF_RE, () => {
+		count += 1;
+		return "\\r\\n";
+	});
+	return {
+		content: out,
+		count
+	};
+}
+function replaceUFFFD(input) {
+	let count = 0;
+	return {
+		content: input.replace(CONTROL_CHARS_RE, () => {
+			count += 1;
+			return "�";
+		}),
+		count
+	};
+}
+function findMatchedPattern(input) {
+	if (CONTROL_CHARS_RE.test(input)) {
+		CONTROL_CHARS_RE.lastIndex = 0;
+		return "control-char";
+	}
+	if (SSE_FRAME_RE.test(input)) {
+		SSE_FRAME_RE.lastIndex = 0;
+		return "sse-frame";
+	}
+	if (HEADER_CRLF_RE.test(input)) {
+		HEADER_CRLF_RE.lastIndex = 0;
+		return "header-crlf";
+	}
+}
+/**
+* Apply the configured escape policy to a single string body. Pure
+* — never mutates inputs.
+*
+* @stable
+*/
+function guardOutboundContent(input, boundary, cfg = {}) {
+	const policy = resolvePolicy(boundary, cfg);
+	const matchedPattern = findMatchedPattern(input);
+	if (matchedPattern === void 0) return {
+		content: input,
+		escapedCharCount: 0,
+		decision: "pass-through",
+		boundary,
+		policy
+	};
+	switch (policy) {
+		case "strict": {
+			const r = escapeStrict(input, boundary);
+			return {
+				content: r.content,
+				escapedCharCount: r.count,
+				matchedPattern,
+				decision: "escaped",
+				boundary,
+				policy
+			};
+		}
+		case "replace": {
+			const r = replaceUFFFD(input);
+			return {
+				content: r.content,
+				escapedCharCount: r.count,
+				matchedPattern,
+				decision: "replaced",
+				boundary,
+				policy
+			};
+		}
+		case "reject": throw new ProtocolInjectionRejectError(boundary, matchedPattern);
+		default: return {
+			content: input,
+			escapedCharCount: 0,
+			decision: "pass-through",
+			boundary,
+			policy
+		};
+	}
+}
+
+//#endregion
+export { guardOutboundContent, resolvePolicy };
+//# sourceMappingURL=protocol-guard.js.map

package/dist/lateral-leak/protocol-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-guard.js","names":["codePoints: number[]"],"sources":["../../src/lateral-leak/protocol-guard.ts"],"sourcesContent":["/**\n * Protocol/header injection guard — escapes control characters in\n * tool result bodies before they cross internal-service delivery\n * boundaries (SSE, WebSocket, REST body, HTTP header, audit row).\n *\n * The default policy mirrors the deployment-posture matrix from the\n * lateral-leak design (DEC-171 / suggested ADR-059):\n *\n * - `'sse' | 'http-header'`  → `'strict'`  (escape control chars to\n *   `\\xNN` hex literals; the safest default for cleartext frame\n *   protocols).\n * - `'ws' | 'rest-body'`     → `'replace'` (replace with the Unicode\n *   replacement character `\\uFFFD`).\n * - `'audit'`                → `'strict'`  (regulated deployments).\n * - `'reject'` is operator opt-in — the guard throws\n *   {@link ProtocolInjectionRejectError} when control characters are\n *   detected.\n *\n * @packageDocumentation\n */\n\nimport { ProtocolInjectionRejectError } from '../errors/index.js';\n\n/**\n * Per-boundary identifier used by the runtime when calling the\n * guard.\n *\n * @stable\n */\nexport type ProtocolBoundary = 'sse' | 'http-header' | 'ws' | 'rest-body' | 'audit';\n\n/**\n * Per-boundary escape policy.\n *\n * @stable\n */\nexport type ProtocolEscapePolicy = 'strict' | 'replace' | 'reject';\n\n/**\n * Configurable per-boundary policy table. Operators may override\n * specific boundaries via `Agent.protocolGuard?: { ... }`.\n *\n * @stable\n */\nexport interface ProtocolGuardConfig {\n  readonly sse?: ProtocolEscapePolicy;\n  readonly httpHeader?: ProtocolEscapePolicy;\n  readonly ws?: ProtocolEscapePolicy;\n  readonly restBody?: ProtocolEscapePolicy;\n  readonly audit?: ProtocolEscapePolicy;\n}\n\n/**\n * Resolved policy lookup. Pure function — no side effects.\n *\n * @stable\n */\nexport function resolvePolicy(\n  boundary: ProtocolBoundary,\n  cfg: ProtocolGuardConfig = {},\n): ProtocolEscapePolicy {\n  switch (boundary) {\n    case 'sse':\n      return cfg.sse ?? 'strict';\n    case 'http-header':\n      return cfg.httpHeader ?? 'strict';\n    case 'ws':\n      return cfg.ws ?? 'replace';\n    case 'rest-body':\n      return cfg.restBody ?? 'replace';\n    case 'audit':\n      return cfg.audit ?? 'strict';\n    default: {\n      const _exhaustive: never = boundary;\n      void _exhaustive;\n      return 'strict';\n    }\n  }\n}\n\n// Control-character catalogue used to detect injection attempts at\n// the framework's outbound delivery boundaries. Building the regex\n// programmatically avoids embedding control bytes in the source —\n// the bytes are exactly the ones a malicious tool result might\n// inject to escape framing on cleartext protocols.\nfunction buildControlCharsRegex(): RegExp {\n  const codePoints: number[] = [];\n  for (let n = 0; n < 0x20; n++) {\n    if (n === 0x09 || n === 0x0a || n === 0x0d) continue;\n    codePoints.push(n);\n  }\n  codePoints.push(0x7f);\n  const cls = codePoints.map((c) => `\\\\x${c.toString(16).padStart(2, '0')}`).join('');\n  return new RegExp(`[${cls}]`, 'g');\n}\nconst CONTROL_CHARS_RE = buildControlCharsRegex();\nconst SSE_FRAME_RE = /\\r?\\n\\r?\\n/g;\nconst HEADER_CRLF_RE = /\\r\\n/g;\n\n/**\n * Outcome of {@link guardOutboundContent}.\n *\n * @stable\n */\nexport interface GuardOutcome {\n  readonly content: string;\n  readonly escapedCharCount: number;\n  readonly matchedPattern?: string;\n  readonly decision: 'pass-through' | 'escaped' | 'replaced' | 'rejected';\n  readonly boundary: ProtocolBoundary;\n  readonly policy: ProtocolEscapePolicy;\n}\n\nfunction escapeStrict(\n  input: string,\n  boundary: ProtocolBoundary,\n): { content: string; count: number } {\n  let count = 0;\n  let out = input.replace(CONTROL_CHARS_RE, (ch) => {\n    count += 1;\n    return `\\\\x${ch.charCodeAt(0).toString(16).padStart(2, '0')}`;\n  });\n  if (boundary === 'sse') {\n    out = out.replace(SSE_FRAME_RE, (m) => {\n      count += 1;\n      return m.replace(/\\n/g, '\\\\n').replace(/\\r/g, '\\\\r');\n    });\n  }\n  if (boundary === 'http-header' || boundary === 'audit') {\n    out = out.replace(HEADER_CRLF_RE, () => {\n      count += 1;\n      return '\\\\r\\\\n';\n    });\n  }\n  return { content: out, count };\n}\n\nfunction replaceUFFFD(input: string): { content: string; count: number } {\n  let count = 0;\n  const out = input.replace(CONTROL_CHARS_RE, () => {\n    count += 1;\n    return '\\uFFFD';\n  });\n  return { content: out, count };\n}\n\nfunction findMatchedPattern(input: string): string | undefined {\n  if (CONTROL_CHARS_RE.test(input)) {\n    CONTROL_CHARS_RE.lastIndex = 0;\n    return 'control-char';\n  }\n  if (SSE_FRAME_RE.test(input)) {\n    SSE_FRAME_RE.lastIndex = 0;\n    return 'sse-frame';\n  }\n  if (HEADER_CRLF_RE.test(input)) {\n    HEADER_CRLF_RE.lastIndex = 0;\n    return 'header-crlf';\n  }\n  return undefined;\n}\n\n/**\n * Apply the configured escape policy to a single string body. Pure\n * — never mutates inputs.\n *\n * @stable\n */\nexport function guardOutboundContent(\n  input: string,\n  boundary: ProtocolBoundary,\n  cfg: ProtocolGuardConfig = {},\n): GuardOutcome {\n  const policy = resolvePolicy(boundary, cfg);\n  const matchedPattern = findMatchedPattern(input);\n  if (matchedPattern === undefined) {\n    return {\n      content: input,\n      escapedCharCount: 0,\n      decision: 'pass-through',\n      boundary,\n      policy,\n    };\n  }\n  switch (policy) {\n    case 'strict': {\n      const r = escapeStrict(input, boundary);\n      return {\n        content: r.content,\n        escapedCharCount: r.count,\n        matchedPattern,\n        decision: 'escaped',\n        boundary,\n        policy,\n      };\n    }\n    case 'replace': {\n      const r = replaceUFFFD(input);\n      return {\n        content: r.content,\n        escapedCharCount: r.count,\n        matchedPattern,\n        decision: 'replaced',\n        boundary,\n        policy,\n      };\n    }\n    case 'reject':\n      throw new ProtocolInjectionRejectError(boundary, matchedPattern);\n    default: {\n      const _exhaustive: never = policy;\n      void _exhaustive;\n      return {\n        content: input,\n        escapedCharCount: 0,\n        decision: 'pass-through',\n        boundary,\n        policy,\n      };\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,cACd,UACA,MAA2B,EAAE,EACP;AACtB,SAAQ,UAAR;EACE,KAAK,MACH,QAAO,IAAI,OAAO;EACpB,KAAK,cACH,QAAO,IAAI,cAAc;EAC3B,KAAK,KACH,QAAO,IAAI,MAAM;EACnB,KAAK,YACH,QAAO,IAAI,YAAY;EACzB,KAAK,QACH,QAAO,IAAI,SAAS;EACtB,QAGE,QAAO;;;AAUb,SAAS,yBAAiC;CACxC,MAAMA,aAAuB,EAAE;AAC/B,MAAK,IAAI,IAAI,GAAG,IAAI,IAAM,KAAK;AAC7B,MAAI,MAAM,KAAQ,MAAM,MAAQ,MAAM,GAAM;AAC5C,aAAW,KAAK,EAAE;;AAEpB,YAAW,KAAK,IAAK;CACrB,MAAM,MAAM,WAAW,KAAK,MAAM,MAAM,EAAE,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,GAAG,CAAC,KAAK,GAAG;AACnF,QAAO,IAAI,OAAO,IAAI,IAAI,IAAI,IAAI;;AAEpC,MAAM,mBAAmB,wBAAwB;AACjD,MAAM,eAAe;AACrB,MAAM,iBAAiB;AAgBvB,SAAS,aACP,OACA,UACoC;CACpC,IAAI,QAAQ;CACZ,IAAI,MAAM,MAAM,QAAQ,mBAAmB,OAAO;AAChD,WAAS;AACT,SAAO,MAAM,GAAG,WAAW,EAAE,CAAC,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI;GAC3D;AACF,KAAI,aAAa,MACf,OAAM,IAAI,QAAQ,eAAe,MAAM;AACrC,WAAS;AACT,SAAO,EAAE,QAAQ,OAAO,MAAM,CAAC,QAAQ,OAAO,MAAM;GACpD;AAEJ,KAAI,aAAa,iBAAiB,aAAa,QAC7C,OAAM,IAAI,QAAQ,sBAAsB;AACtC,WAAS;AACT,SAAO;GACP;AAEJ,QAAO;EAAE,SAAS;EAAK;EAAO;;AAGhC,SAAS,aAAa,OAAmD;CACvE,IAAI,QAAQ;AAKZ,QAAO;EAAE,SAJG,MAAM,QAAQ,wBAAwB;AAChD,YAAS;AACT,UAAO;IACP;EACqB;EAAO;;AAGhC,SAAS,mBAAmB,OAAmC;AAC7D,KAAI,iBAAiB,KAAK,MAAM,EAAE;AAChC,mBAAiB,YAAY;AAC7B,SAAO;;AAET,KAAI,aAAa,KAAK,MAAM,EAAE;AAC5B,eAAa,YAAY;AACzB,SAAO;;AAET,KAAI,eAAe,KAAK,MAAM,EAAE;AAC9B,iBAAe,YAAY;AAC3B,SAAO;;;;;;;;;AAWX,SAAgB,qBACd,OACA,UACA,MAA2B,EAAE,EACf;CACd,MAAM,SAAS,cAAc,UAAU,IAAI;CAC3C,MAAM,iBAAiB,mBAAmB,MAAM;AAChD,KAAI,mBAAmB,OACrB,QAAO;EACL,SAAS;EACT,kBAAkB;EAClB,UAAU;EACV;EACA;EACD;AAEH,SAAQ,QAAR;EACE,KAAK,UAAU;GACb,MAAM,IAAI,aAAa,OAAO,SAAS;AACvC,UAAO;IACL,SAAS,EAAE;IACX,kBAAkB,EAAE;IACpB;IACA,UAAU;IACV;IACA;IACD;;EAEH,KAAK,WAAW;GACd,MAAM,IAAI,aAAa,MAAM;AAC7B,UAAO;IACL,SAAS,EAAE;IACX,kBAAkB,EAAE;IACpB;IACA,UAAU;IACV;IACA;IACD;;EAEH,KAAK,SACH,OAAM,IAAI,6BAA6B,UAAU,eAAe;EAClE,QAGE,QAAO;GACL,SAAS;GACT,kBAAkB;GAClB,UAAU;GACV;GACA;GACD"}

package/dist/preferred-model/index.d.ts

@@ -0,0 +1,53 @@
+import { ModelHint, ModelSpec, Provider } from "@graphorin/core";
+
+//#region src/preferred-model/index.d.ts
+
+/**
+ * Result returned by {@link resolvePreferredModel}.
+ *
+ * @stable
+ */
+interface PreferredModelResolution {
+  readonly resolvedProvider: Provider;
+  readonly resolvedModelId: string;
+  readonly source: 'prepare-step' | 'tier-map' | 'spec' | 'agent-preferred' | 'fallthrough-default';
+  readonly hintApplied?: ModelHint;
+  readonly fallthroughReason?: 'tier-not-mapped' | 'provider-unavailable' | 'override-takes-precedence';
+}
+/**
+ * Pure inputs to {@link resolvePreferredModel}.
+ *
+ * @stable
+ */
+interface ResolvePreferredModelInput {
+  readonly prepareStepProvider?: Provider;
+  readonly toolPreferredModels: ReadonlyArray<ModelHint | ModelSpec | undefined>;
+  readonly agentPreferredModel?: ModelHint | ModelSpec;
+  readonly agentDefaultProvider: Provider;
+  readonly modelTierMap?: Partial<Record<ModelHint, ModelSpec>>;
+}
+/**
+ * Pick the highest-cost tier across the supplied per-tool hints.
+ * Explicit `ModelSpec` entries are treated as the highest tier
+ * (`'smart'`) for tie-breaking — the conservative-correctness rule
+ * documented in DEC-169 / suggested ADR-057.
+ *
+ * Returns the picked hint together with the original `ModelSpec`
+ * (when an explicit spec won the tie-break).
+ *
+ * @stable
+ */
+declare function pickTopTierAcrossTools(hints: ReadonlyArray<ModelHint | ModelSpec | undefined>): {
+  readonly hint: ModelHint;
+  readonly spec?: ModelSpec;
+} | undefined;
+/**
+ * Walk the precedence ladder and return the resolved provider for a
+ * single agent step. Pure function — no side effects.
+ *
+ * @stable
+ */
+declare function resolvePreferredModel(input: ResolvePreferredModelInput): PreferredModelResolution;
+//#endregion
+export { PreferredModelResolution, ResolvePreferredModelInput, pickTopTierAcrossTools, resolvePreferredModel };
+//# sourceMappingURL=index.d.ts.map

package/dist/preferred-model/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/preferred-model/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAkCiB,wBAAA;6BACY;;;yBAGJ;;;;;;;;UAYR,0BAAA;iCACgB;gCACD,cAAc,YAAY;iCACzB,YAAY;iCACZ;0BACP,QAAQ,OAAO,WAAW;;;;;;;;;;;;;iBA4BpC,sBAAA,QACP,cAAc,YAAY;iBACf;kBAA2B;;;;;;;;iBAkC/B,qBAAA,QAA6B,6BAA6B"}