@graphorin/agent 0.5.0

package/dist/filters/index.js

@@ -0,0 +1,273 @@
+import "@graphorin/core";
+
+//#region src/filters/index.ts
+const SENSITIVITY_RANK = {
+	public: 0,
+	internal: 1,
+	secret: 2
+};
+/**
+* Return `true` iff the message's effective sensitivity is at most
+* `maxTier` (a strictly weaker check than core's
+* `acceptsSensitivity` because the filter library does not have
+* the provider's `acceptsSensitivity[]` array — only a ceiling).
+*/
+function withinTier(record, maxTier) {
+	return SENSITIVITY_RANK[record] <= SENSITIVITY_RANK[maxTier];
+}
+function makeFilter(fn, descriptor) {
+	const wrapped = ((history) => fn(history));
+	Object.defineProperty(wrapped, "descriptor", {
+		value: descriptor,
+		enumerable: true
+	});
+	return wrapped;
+}
+function isReasoningPart(part) {
+	if (typeof part !== "object" || part === null) return false;
+	return part.type === "reasoning";
+}
+function stripReasoningFromMessage(msg) {
+	if (msg.role === "system" || msg.role === "tool") return msg;
+	const content = msg.content;
+	if (typeof content === "string") return msg;
+	const filtered = content.filter((part) => !isReasoningPart(part));
+	if (filtered.length === content.length) return msg;
+	if (msg.role === "assistant") return {
+		...msg,
+		content: filtered
+	};
+	return {
+		...msg,
+		content: filtered
+	};
+}
+/**
+* Keep the parent's system prompt and the last `n` non-system
+* messages. Default `n = 10` per DEC-146 / RB-40 security-first
+* compose.
+*
+* @stable
+*/
+function lastN(n = 10) {
+	if (!Number.isFinite(n) || n <= 0) throw new RangeError(`filters.lastN: n must be a positive integer (got ${String(n)})`);
+	return makeFilter((history) => {
+		const out = [];
+		for (const msg of history) if (msg.role === "system") out.push(msg);
+		const nonSystem = history.filter((m) => m.role !== "system");
+		const tail = nonSystem.slice(Math.max(0, nonSystem.length - n));
+		return [...out, ...tail];
+	}, {
+		kind: "last-n",
+		meta: { n }
+	});
+}
+/**
+* Keep only the parent's system prompt and the most recent user
+* message. Useful for simple sub-agents that only need the question.
+*
+* @stable
+*/
+function lastUser() {
+	return makeFilter((history) => {
+		const out = [];
+		let lastUserIdx = -1;
+		for (let i = history.length - 1; i >= 0; i--) {
+			const msg = history[i];
+			if (msg && msg.role === "user") {
+				lastUserIdx = i;
+				break;
+			}
+		}
+		for (const msg of history) if (msg.role === "system") out.push(msg);
+		if (lastUserIdx >= 0) {
+			const m = history[lastUserIdx];
+			if (m) out.push(m);
+		}
+		return out;
+	}, { kind: "last-user" });
+}
+/**
+* The full unfiltered history. Discouraged — security-conscious
+* callers should pick {@link lastN} or {@link bySensitivity} instead
+* (a sub-agent rarely needs the parent's entire conversation).
+*
+* @stable
+*/
+function full() {
+	return makeFilter((history) => history.slice(), { kind: "full" });
+}
+/**
+* Replace the parent's history with a single system message carrying
+* the supplied summary. Used by callers that wire in an LLM-based
+* summarizer outside the framework.
+*
+* @stable
+*/
+function summary(text) {
+	return makeFilter(() => [{
+		role: "system",
+		content: `[Summary of parent conversation]\n${text}`
+	}], {
+		kind: "summary",
+		meta: { summaryLength: text.length }
+	});
+}
+/**
+* Drop messages whose effective sensitivity ceiling exceeds
+* `maxTier`. Messages without sensitivity metadata default to
+* `'public'` and are always kept.
+*
+* The framework currently records sensitivity at the
+* `MessageContent` part level via the `inboundTrust` / `secret`
+* annotations. v0.1 ships a coarse-grained heuristic: a message is
+* kept iff every text part's content does not contain the literal
+* `[REDACTED:secret]` token AND every part's annotated sensitivity
+* is acceptable to `maxTier`. Operators that need a stricter
+* filter compose the function with `stripSensitiveOutputs()` or a
+* custom predicate.
+*
+* @stable
+*/
+function bySensitivity(args = {}) {
+	const maxTier = args.maxTier ?? "public";
+	return makeFilter((history) => {
+		const out = [];
+		for (const msg of history) {
+			const content = msg.role === "system" ? msg.content : msg.content;
+			if ((typeof content === "string" ? content : JSON.stringify(content)).includes("[REDACTED:secret]") && !withinTier("secret", maxTier)) continue;
+			out.push(msg);
+		}
+		return out;
+	}, {
+		kind: "sensitivity-filter",
+		meta: { maxTier }
+	});
+}
+/**
+* Strip every `ReasoningContent` part from each message. Always
+* applied at the handoff boundary (the `compose(...)` helper appends
+* this filter automatically).
+*
+* @stable
+*/
+function stripReasoning() {
+	return makeFilter((history) => history.map(stripReasoningFromMessage), { kind: "strip-reasoning" });
+}
+/**
+* Strip tool messages whose `content` carries the literal token
+* `[REDACTED:secret]` or whose `secret` annotation marks the body as
+* sensitive. Conservative-by-design: the agent runtime tags
+* sensitive tool outputs at session-write time so this filter has
+* stable bytes to scan against.
+*
+* @stable
+*/
+function stripSensitiveOutputs() {
+	return makeFilter((history) => {
+		const out = [];
+		let stripped = 0;
+		for (const msg of history) {
+			if (msg.role === "tool") {
+				if ((typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content)).includes("[REDACTED:")) {
+					stripped += 1;
+					continue;
+				}
+			}
+			out.push(msg);
+		}
+		return out;
+	}, { kind: "strip-sensitive-outputs" });
+}
+/**
+* Drop every assistant `toolCalls` array AND every `tool` message.
+* Useful when a sub-agent should only see the textual conversation.
+*
+* @stable
+*/
+function stripToolCalls() {
+	return makeFilter((history) => {
+		const out = [];
+		for (const msg of history) {
+			if (msg.role === "tool") continue;
+			if (msg.role === "assistant" && msg.toolCalls && msg.toolCalls.length > 0) {
+				const { toolCalls: _toolCalls, ...rest } = msg;
+				out.push(rest);
+				continue;
+			}
+			out.push(msg);
+		}
+		return out;
+	}, { kind: "strip-tool-calls" });
+}
+/**
+* Compose multiple filters left-to-right. The composer **always**
+* appends `stripReasoning()` at the end so reasoning content never
+* crosses a handoff boundary regardless of caller intent.
+*
+* @stable
+*/
+function compose(...filters$1) {
+	const stripper = stripReasoning();
+	const ordered = [...filters$1, stripper];
+	const descriptors = filters$1.map((f) => {
+		return f.descriptor ?? { kind: "custom" };
+	});
+	descriptors.push(stripper.descriptor);
+	return makeFilter((history) => {
+		let current = history;
+		for (const filter of ordered) current = filter(current);
+		return current;
+	}, {
+		kind: "compose",
+		meta: { steps: descriptors }
+	});
+}
+/**
+* Wrap a caller-supplied function as a {@link DescribedFilter} with
+* the canonical `'custom'` descriptor.
+*
+* @stable
+*/
+function custom(fn, meta) {
+	return makeFilter(fn, meta !== void 0 ? {
+		kind: "custom",
+		meta
+	} : { kind: "custom" });
+}
+/**
+* The canonical default applied by the agent runtime to every
+* `Agent.toTool(...)` and `handoff(...)` invocation when the caller
+* does not supply an explicit filter.
+*
+* @stable
+*/
+function defaultHandoffFilter() {
+	return compose(lastN(10), stripSensitiveOutputs());
+}
+/**
+* Pure `HandoffInputFilterDescriptor` for callers that just need the
+* descriptor without instantiating the runtime function (e.g. the
+* sessions package's lenient-forward-parse path).
+*
+* @stable
+*/
+const FILTER_KIND_CUSTOM = { kind: "custom" };
+/** Aggregate module export. */
+const filters = {
+	lastN,
+	lastUser,
+	full,
+	summary,
+	bySensitivity,
+	stripReasoning,
+	stripSensitiveOutputs,
+	stripToolCalls,
+	compose,
+	custom,
+	defaultHandoffFilter
+};
+
+//#endregion
+export { FILTER_KIND_CUSTOM, bySensitivity, compose, custom, defaultHandoffFilter, filters, full, lastN, lastUser, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary };
+//# sourceMappingURL=index.js.map

package/dist/filters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["SENSITIVITY_RANK: Record<Sensitivity, number>","out: Message[]","nonSystem: Message[]","maxTier: Sensitivity","filters","ordered: ReadonlyArray<HandoffFilter>","descriptors: HandoffInputFilterDescriptor[]","current: readonly Message[]","FILTER_KIND_CUSTOM: HandoffInputFilterDescriptor"],"sources":["../../src/filters/index.ts"],"sourcesContent":["/**\n * Handoff filter library — a small set of pure, composable functions\n * that take the parent agent's message history and return a filtered\n * subset suitable for forwarding to a child agent.\n *\n * Every filter pairs a `HandoffFilter` runtime function with a\n * serializable {@link HandoffInputFilterDescriptor} so the JSONL\n * session export (`@graphorin/sessions`) can replay the filter stack\n * even after the runtime implementations evolve.\n *\n * Reasoning content is **always** stripped at the handoff boundary —\n * `filters.compose(...)` guarantees `stripReasoning()` runs last so a\n * caller-supplied filter cannot accidentally forward reasoning to a\n * child agent. This is the confidentiality + token-economy default\n * documented in the agent-loop reference.\n *\n * @packageDocumentation\n */\n\nimport type {\n  HandoffFilter,\n  HandoffInputFilterDescriptor,\n  Message,\n  Sensitivity,\n} from '@graphorin/core';\nimport { SENSITIVITY_ORDER } from '@graphorin/core';\n\nconst SENSITIVITY_RANK: Record<Sensitivity, number> = {\n  public: 0,\n  internal: 1,\n  secret: 2,\n};\n\n/**\n * Return `true` iff the message's effective sensitivity is at most\n * `maxTier` (a strictly weaker check than core's\n * `acceptsSensitivity` because the filter library does not have\n * the provider's `acceptsSensitivity[]` array — only a ceiling).\n */\nfunction withinTier(record: Sensitivity, maxTier: Sensitivity): boolean {\n  return SENSITIVITY_RANK[record] <= SENSITIVITY_RANK[maxTier];\n}\n\nvoid SENSITIVITY_ORDER;\n\n/**\n * A `HandoffFilter` paired with the serializable descriptor that\n * round-trips through the JSONL session export. Authors of custom\n * filters return one of these via `filters.custom({...})`.\n *\n * @stable\n */\nexport interface DescribedFilter extends HandoffFilter {\n  readonly descriptor: HandoffInputFilterDescriptor;\n}\n\nfunction makeFilter(fn: HandoffFilter, descriptor: HandoffInputFilterDescriptor): DescribedFilter {\n  const wrapped = ((history: readonly Message[]): readonly Message[] =>\n    fn(history)) as DescribedFilter;\n  Object.defineProperty(wrapped, 'descriptor', { value: descriptor, enumerable: true });\n  return wrapped;\n}\n\nfunction isReasoningPart(part: unknown): boolean {\n  if (typeof part !== 'object' || part === null) return false;\n  const t = (part as { readonly type?: unknown }).type;\n  return t === 'reasoning';\n}\n\nfunction stripReasoningFromMessage(msg: Message): Message {\n  if (msg.role === 'system' || msg.role === 'tool') return msg;\n  const content = msg.content;\n  if (typeof content === 'string') return msg;\n  const filtered = content.filter((part) => !isReasoningPart(part));\n  if (filtered.length === content.length) return msg;\n  if (msg.role === 'assistant') {\n    return { ...msg, content: filtered };\n  }\n  return { ...msg, content: filtered };\n}\n\n/**\n * Keep the parent's system prompt and the last `n` non-system\n * messages. Default `n = 10` per DEC-146 / RB-40 security-first\n * compose.\n *\n * @stable\n */\nexport function lastN(n = 10): DescribedFilter {\n  if (!Number.isFinite(n) || n <= 0) {\n    throw new RangeError(`filters.lastN: n must be a positive integer (got ${String(n)})`);\n  }\n  return makeFilter(\n    (history) => {\n      const out: Message[] = [];\n      for (const msg of history) {\n        if (msg.role === 'system') {\n          out.push(msg);\n        }\n      }\n      const nonSystem: Message[] = history.filter((m) => m.role !== 'system');\n      const tail = nonSystem.slice(Math.max(0, nonSystem.length - n));\n      return [...out, ...tail];\n    },\n    { kind: 'last-n', meta: { n } },\n  );\n}\n\n/**\n * Keep only the parent's system prompt and the most recent user\n * message. Useful for simple sub-agents that only need the question.\n *\n * @stable\n */\nexport function lastUser(): DescribedFilter {\n  return makeFilter(\n    (history) => {\n      const out: Message[] = [];\n      let lastUserIdx = -1;\n      for (let i = history.length - 1; i >= 0; i--) {\n        const msg = history[i];\n        if (msg && msg.role === 'user') {\n          lastUserIdx = i;\n          break;\n        }\n      }\n      for (const msg of history) {\n        if (msg.role === 'system') out.push(msg);\n      }\n      if (lastUserIdx >= 0) {\n        const m = history[lastUserIdx];\n        if (m) out.push(m);\n      }\n      return out;\n    },\n    { kind: 'last-user' },\n  );\n}\n\n/**\n * The full unfiltered history. Discouraged — security-conscious\n * callers should pick {@link lastN} or {@link bySensitivity} instead\n * (a sub-agent rarely needs the parent's entire conversation).\n *\n * @stable\n */\nexport function full(): DescribedFilter {\n  return makeFilter((history) => history.slice(), { kind: 'full' });\n}\n\n/**\n * Replace the parent's history with a single system message carrying\n * the supplied summary. Used by callers that wire in an LLM-based\n * summarizer outside the framework.\n *\n * @stable\n */\nexport function summary(text: string): DescribedFilter {\n  return makeFilter(\n    () => [\n      {\n        role: 'system',\n        content: `[Summary of parent conversation]\\n${text}`,\n      },\n    ],\n    { kind: 'summary', meta: { summaryLength: text.length } },\n  );\n}\n\n/**\n * Drop messages whose effective sensitivity ceiling exceeds\n * `maxTier`. Messages without sensitivity metadata default to\n * `'public'` and are always kept.\n *\n * The framework currently records sensitivity at the\n * `MessageContent` part level via the `inboundTrust` / `secret`\n * annotations. v0.1 ships a coarse-grained heuristic: a message is\n * kept iff every text part's content does not contain the literal\n * `[REDACTED:secret]` token AND every part's annotated sensitivity\n * is acceptable to `maxTier`. Operators that need a stricter\n * filter compose the function with `stripSensitiveOutputs()` or a\n * custom predicate.\n *\n * @stable\n */\nexport function bySensitivity(args: { readonly maxTier?: Sensitivity } = {}): DescribedFilter {\n  const maxTier: Sensitivity = args.maxTier ?? 'public';\n  return makeFilter(\n    (history) => {\n      const out: Message[] = [];\n      for (const msg of history) {\n        const content = msg.role === 'system' ? msg.content : msg.content;\n        const text = typeof content === 'string' ? content : JSON.stringify(content);\n        if (text.includes('[REDACTED:secret]') && !withinTier('secret', maxTier)) {\n          continue;\n        }\n        out.push(msg);\n      }\n      return out;\n    },\n    { kind: 'sensitivity-filter', meta: { maxTier } },\n  );\n}\n\n/**\n * Strip every `ReasoningContent` part from each message. Always\n * applied at the handoff boundary (the `compose(...)` helper appends\n * this filter automatically).\n *\n * @stable\n */\nexport function stripReasoning(): DescribedFilter {\n  return makeFilter((history) => history.map(stripReasoningFromMessage), {\n    kind: 'strip-reasoning',\n  });\n}\n\n/**\n * Strip tool messages whose `content` carries the literal token\n * `[REDACTED:secret]` or whose `secret` annotation marks the body as\n * sensitive. Conservative-by-design: the agent runtime tags\n * sensitive tool outputs at session-write time so this filter has\n * stable bytes to scan against.\n *\n * @stable\n */\nexport function stripSensitiveOutputs(): DescribedFilter {\n  return makeFilter(\n    (history) => {\n      const out: Message[] = [];\n      let stripped = 0;\n      for (const msg of history) {\n        if (msg.role === 'tool') {\n          const text = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);\n          if (text.includes('[REDACTED:')) {\n            stripped += 1;\n            continue;\n          }\n        }\n        out.push(msg);\n      }\n      void stripped;\n      return out;\n    },\n    { kind: 'strip-sensitive-outputs' },\n  );\n}\n\n/**\n * Drop every assistant `toolCalls` array AND every `tool` message.\n * Useful when a sub-agent should only see the textual conversation.\n *\n * @stable\n */\nexport function stripToolCalls(): DescribedFilter {\n  return makeFilter(\n    (history) => {\n      const out: Message[] = [];\n      for (const msg of history) {\n        if (msg.role === 'tool') continue;\n        if (msg.role === 'assistant' && msg.toolCalls && msg.toolCalls.length > 0) {\n          const { toolCalls: _toolCalls, ...rest } = msg;\n          out.push(rest);\n          continue;\n        }\n        out.push(msg);\n      }\n      return out;\n    },\n    { kind: 'strip-tool-calls' },\n  );\n}\n\n/**\n * Compose multiple filters left-to-right. The composer **always**\n * appends `stripReasoning()` at the end so reasoning content never\n * crosses a handoff boundary regardless of caller intent.\n *\n * @stable\n */\nexport function compose(...filters: ReadonlyArray<HandoffFilter>): DescribedFilter {\n  const stripper = stripReasoning();\n  const ordered: ReadonlyArray<HandoffFilter> = [...filters, stripper];\n  const descriptors: HandoffInputFilterDescriptor[] = filters.map((f) => {\n    const desc = (f as DescribedFilter).descriptor;\n    return desc ?? { kind: 'custom' };\n  });\n  descriptors.push(stripper.descriptor);\n  return makeFilter(\n    (history) => {\n      let current: readonly Message[] = history;\n      for (const filter of ordered) {\n        current = filter(current);\n      }\n      return current;\n    },\n    { kind: 'compose', meta: { steps: descriptors } },\n  );\n}\n\n/**\n * Wrap a caller-supplied function as a {@link DescribedFilter} with\n * the canonical `'custom'` descriptor.\n *\n * @stable\n */\nexport function custom(\n  fn: HandoffFilter,\n  meta?: Readonly<Record<string, unknown>>,\n): DescribedFilter {\n  return makeFilter(fn, meta !== undefined ? { kind: 'custom', meta } : { kind: 'custom' });\n}\n\n/**\n * The canonical default applied by the agent runtime to every\n * `Agent.toTool(...)` and `handoff(...)` invocation when the caller\n * does not supply an explicit filter.\n *\n * @stable\n */\nexport function defaultHandoffFilter(): DescribedFilter {\n  return compose(lastN(10), stripSensitiveOutputs());\n}\n\n/**\n * Pure `HandoffInputFilterDescriptor` for callers that just need the\n * descriptor without instantiating the runtime function (e.g. the\n * sessions package's lenient-forward-parse path).\n *\n * @stable\n */\nexport const FILTER_KIND_CUSTOM: HandoffInputFilterDescriptor = { kind: 'custom' };\n\n/** Aggregate module export. */\nexport const filters = {\n  lastN,\n  lastUser,\n  full,\n  summary,\n  bySensitivity,\n  stripReasoning,\n  stripSensitiveOutputs,\n  stripToolCalls,\n  compose,\n  custom,\n  defaultHandoffFilter,\n};\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { AgentResolutionError, AgentRuntimeError, AgentRuntimeErrorCode, EvaluatorOptimizerConfigError, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RunStateMalformedError, RunStateVersionUnsupportedError, ToolNotFoundError } from "./errors/index.js";
+import { EvaluatorCallable, EvaluatorOptimizerOptions, EvaluatorOptimizerOutcome, EvaluatorOutcome, GeneratorCallable, Rubric, evaluatorOptimizer } from "./evaluator-optimizer/index.js";
+import { AgentFallbackEligibility, AgentFallbackPolicy, AgentFallbackReason, isAgentFallbackEligible } from "./fallback/index.js";
+import { ChildTrustInput, ContentOriginKind, MergeBiasDecision, MergeGuardConfig, TrustClass, computeSourceTrust, evaluateMerge } from "./lateral-leak/merge-guard.js";
+import { ChildResult, FanOutOptions, FanOutResult, MergeStrategy, PerChildBudget, runFanOut } from "./fanout/index.js";
+import { CausalityMonitor, CausalityMonitorCheck, CausalityMonitorConfig, CausalityMonitorStrictness, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH } from "./lateral-leak/causality-monitor.js";
+import { ProgressIO, ProgressIOConfig, ProgressReadOptions, ProgressWriteOptions, createProgressIO } from "./progress/index.js";
+import { AbortOptions, Agent, AgentCallOptions, AgentConfig, AgentInput, AgentToToolOptions, CompactOptions, CompactionApiResult, OutputSpec, PostCompactionHook, PrepareStepHook, PrepareStepOverrides, ResumeDirective, SkillsRegistryLike } from "./types.js";
+import { createAgent } from "./factory.js";
+import { DescribedFilter, FILTER_KIND_CUSTOM, bySensitivity, compose, custom, defaultHandoffFilter, filters, full, lastN, lastUser, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary } from "./filters/index.js";
+import { GuardOutcome, ProtocolBoundary, ProtocolEscapePolicy, ProtocolGuardConfig, guardOutboundContent, resolvePolicy } from "./lateral-leak/protocol-guard.js";
+import "./lateral-leak/index.js";
+import { PreferredModelResolution, ResolvePreferredModelInput, pickTopTierAcrossTools, resolvePreferredModel } from "./preferred-model/index.js";
+import { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, SerializeRunStateOptions, SerializedRunState, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState } from "./run-state/index.js";
+import { GuardrailContext, GuardrailDefinition, GuardrailResult, InputGuardrail, OutputGuardrail } from "@graphorin/security/guardrails";
+
+//#region src/index.d.ts
+
+/**
+ * `@graphorin/agent` — agent runtime for the Graphorin framework.
+ *
+ * The package owns:
+ *
+ * - The `createAgent({...})` factory that wires the typed
+ *   `model -> tool calls -> model` loop, the streaming event
+ *   surface, the steering / followUp queues, durable HITL
+ *   approvals, multi-agent handoffs (`Agent.toTool`, the filter
+ *   library, secrets isolation), the agent-level model fallback
+ *   chain, the per-step compaction lifecycle, the per-tool
+ *   preferred-model resolution, the structured progress-artifact
+ *   APIs, and the lateral-leak defense layer.
+ * - `runStateToJSON / runStateFromJSON` helpers for caller-managed
+ *   durable HITL.
+ * - The handoff filter library.
+ * - The agent-step-level fan-out helpers (`runFanOut`,
+ *   `evaluatorOptimizer`, the progress IO surface).
+ * - Pure decision functions consulted by the loop
+ *   (`isAgentFallbackEligible`, `resolvePreferredModel`).
+ * - Lateral-leak primitives (`CausalityMonitor`,
+ *   `MergeAgentSidewaysInjectionGuard` decision helpers,
+ *   protocol-injection guard).
+ *
+ * The full documentation lives in the package `README.md`.
+ *
+ * @packageDocumentation
+ */
+/** Canonical version constant. Mirrors the `package.json` version. */
+declare const VERSION = "0.5.0";
+//#endregion
+export { type AbortOptions, type Agent, type AgentCallOptions, type AgentConfig, type AgentFallbackEligibility, type AgentFallbackPolicy, type AgentFallbackReason, type AgentInput, AgentResolutionError, AgentRuntimeError, type AgentRuntimeErrorCode, type AgentToToolOptions, CausalityMonitor, type CausalityMonitorCheck, type CausalityMonitorConfig, type CausalityMonitorStrictness, type ChildResult, type ChildTrustInput, type CompactOptions, type CompactionApiResult, type ContentOriginKind, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH, type DescribedFilter, type EvaluatorCallable, EvaluatorOptimizerConfigError, type EvaluatorOptimizerOptions, type EvaluatorOptimizerOutcome, type EvaluatorOutcome, FILTER_KIND_CUSTOM, type FanOutOptions, type FanOutResult, type GeneratorCallable, type GuardOutcome, type GuardrailContext, type GuardrailDefinition, type GuardrailResult, type InputGuardrail, InvalidAgentConfigError, InvalidPreferredModelError, type MergeBiasDecision, MergeBlockedError, type MergeGuardConfig, type MergeStrategy, MultipleHandoffsInStepError, type OutputGuardrail, type OutputSpec, type PerChildBudget, type PostCompactionHook, type PreferredModelResolution, type PrepareStepHook, type PrepareStepOverrides, type ProgressIO, type ProgressIOConfig, type ProgressReadOptions, ProgressWriteError, type ProgressWriteOptions, type ProtocolBoundary, type ProtocolEscapePolicy, type ProtocolGuardConfig, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, type ResolvePreferredModelInput, type ResumeDirective, type Rubric, RunStateMalformedError, RunStateVersionUnsupportedError, type SerializeRunStateOptions, type SerializedRunState, type SkillsRegistryLike, ToolNotFoundError, type TrustClass, VERSION, addModelUsage, aggregateUsageFromByModel, bySensitivity, completedToolCallsFromState, compose, computeSourceTrust, createAgent, createInitialRunState, createProgressIO, custom, defaultHandoffFilter, deserializeRunState, evaluateMerge, evaluatorOptimizer, filters, full, guardOutboundContent, isAgentFallbackEligible, lastN, lastUser, pickTopTierAcrossTools, resolvePolicy, resolvePreferredModel, runFanOut, runStateFromJSON, runStateToJSON, serializeRunState, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA;;;;;;;;;;;;cAAa,OAAA"}

package/dist/index.js

@@ -0,0 +1,49 @@
+import { AgentResolutionError, AgentRuntimeError, EvaluatorOptimizerConfigError, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RunStateMalformedError, RunStateVersionUnsupportedError, ToolNotFoundError } from "./errors/index.js";
+import { evaluatorOptimizer } from "./evaluator-optimizer/index.js";
+import { isAgentFallbackEligible } from "./fallback/index.js";
+import { computeSourceTrust, evaluateMerge } from "./lateral-leak/merge-guard.js";
+import { runFanOut } from "./fanout/index.js";
+import { FILTER_KIND_CUSTOM, bySensitivity, compose, custom, defaultHandoffFilter, filters, full, lastN, lastUser, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary } from "./filters/index.js";
+import { CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH } from "./lateral-leak/causality-monitor.js";
+import { pickTopTierAcrossTools, resolvePreferredModel } from "./preferred-model/index.js";
+import { createProgressIO } from "./progress/index.js";
+import { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState } from "./run-state/index.js";
+import { createAgent } from "./factory.js";
+import { guardOutboundContent, resolvePolicy } from "./lateral-leak/protocol-guard.js";
+import "./lateral-leak/index.js";
+
+//#region src/index.ts
+/**
+* `@graphorin/agent` — agent runtime for the Graphorin framework.
+*
+* The package owns:
+*
+* - The `createAgent({...})` factory that wires the typed
+*   `model -> tool calls -> model` loop, the streaming event
+*   surface, the steering / followUp queues, durable HITL
+*   approvals, multi-agent handoffs (`Agent.toTool`, the filter
+*   library, secrets isolation), the agent-level model fallback
+*   chain, the per-step compaction lifecycle, the per-tool
+*   preferred-model resolution, the structured progress-artifact
+*   APIs, and the lateral-leak defense layer.
+* - `runStateToJSON / runStateFromJSON` helpers for caller-managed
+*   durable HITL.
+* - The handoff filter library.
+* - The agent-step-level fan-out helpers (`runFanOut`,
+*   `evaluatorOptimizer`, the progress IO surface).
+* - Pure decision functions consulted by the loop
+*   (`isAgentFallbackEligible`, `resolvePreferredModel`).
+* - Lateral-leak primitives (`CausalityMonitor`,
+*   `MergeAgentSidewaysInjectionGuard` decision helpers,
+*   protocol-injection guard).
+*
+* The full documentation lives in the package `README.md`.
+*
+* @packageDocumentation
+*/
+/** Canonical version constant. Mirrors the `package.json` version. */
+const VERSION = "0.5.0";
+
+//#endregion
+export { AgentResolutionError, AgentRuntimeError, CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH, EvaluatorOptimizerConfigError, FILTER_KIND_CUSTOM, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, RunStateMalformedError, RunStateVersionUnsupportedError, ToolNotFoundError, VERSION, addModelUsage, aggregateUsageFromByModel, bySensitivity, completedToolCallsFromState, compose, computeSourceTrust, createAgent, createInitialRunState, createProgressIO, custom, defaultHandoffFilter, deserializeRunState, evaluateMerge, evaluatorOptimizer, filters, full, guardOutboundContent, isAgentFallbackEligible, lastN, lastUser, pickTopTierAcrossTools, resolvePolicy, resolvePreferredModel, runFanOut, runStateFromJSON, runStateToJSON, serializeRunState, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@graphorin/agent` — agent runtime for the Graphorin framework.\n *\n * The package owns:\n *\n * - The `createAgent({...})` factory that wires the typed\n *   `model -> tool calls -> model` loop, the streaming event\n *   surface, the steering / followUp queues, durable HITL\n *   approvals, multi-agent handoffs (`Agent.toTool`, the filter\n *   library, secrets isolation), the agent-level model fallback\n *   chain, the per-step compaction lifecycle, the per-tool\n *   preferred-model resolution, the structured progress-artifact\n *   APIs, and the lateral-leak defense layer.\n * - `runStateToJSON / runStateFromJSON` helpers for caller-managed\n *   durable HITL.\n * - The handoff filter library.\n * - The agent-step-level fan-out helpers (`runFanOut`,\n *   `evaluatorOptimizer`, the progress IO surface).\n * - Pure decision functions consulted by the loop\n *   (`isAgentFallbackEligible`, `resolvePreferredModel`).\n * - Lateral-leak primitives (`CausalityMonitor`,\n *   `MergeAgentSidewaysInjectionGuard` decision helpers,\n *   protocol-injection guard).\n *\n * The full documentation lives in the package `README.md`.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.5.0';\n\n// AG-2 / SDF-4: the canonical guardrail contract lives in\n// `@graphorin/security`; re-exported here for config ergonomics.\nexport type {\n  GuardrailContext,\n  GuardrailDefinition,\n  GuardrailResult,\n  InputGuardrail,\n  OutputGuardrail,\n} from '@graphorin/security/guardrails';\nexport {\n  AgentResolutionError,\n  AgentRuntimeError,\n  type AgentRuntimeErrorCode,\n  EvaluatorOptimizerConfigError,\n  InvalidAgentConfigError,\n  InvalidPreferredModelError,\n  MergeBlockedError,\n  MultipleHandoffsInStepError,\n  ProgressWriteError,\n  ProtocolInjectionRejectError,\n  ProviderMiddlewareOrderError,\n  RunStateMalformedError,\n  RunStateVersionUnsupportedError,\n  ToolNotFoundError,\n} from './errors/index.js';\nexport {\n  type EvaluatorCallable,\n  type EvaluatorOptimizerOptions,\n  type EvaluatorOptimizerOutcome,\n  type EvaluatorOutcome,\n  evaluatorOptimizer,\n  type GeneratorCallable,\n  type Rubric,\n} from './evaluator-optimizer/index.js';\nexport { createAgent } from './factory.js';\nexport {\n  type AgentFallbackEligibility,\n  type AgentFallbackPolicy,\n  type AgentFallbackReason,\n  isAgentFallbackEligible,\n} from './fallback/index.js';\nexport {\n  type ChildResult,\n  type FanOutOptions,\n  type FanOutResult,\n  type MergeStrategy,\n  type PerChildBudget,\n  runFanOut,\n} from './fanout/index.js';\nexport {\n  bySensitivity,\n  compose,\n  custom,\n  type DescribedFilter,\n  defaultHandoffFilter,\n  FILTER_KIND_CUSTOM,\n  filters,\n  full,\n  lastN,\n  lastUser,\n  stripReasoning,\n  stripSensitiveOutputs,\n  stripToolCalls,\n  summary,\n} from './filters/index.js';\nexport {\n  CausalityMonitor,\n  type CausalityMonitorCheck,\n  type CausalityMonitorConfig,\n  type CausalityMonitorStrictness,\n  type ChildTrustInput,\n  type ContentOriginKind,\n  computeSourceTrust,\n  DEFAULT_DENIAL_PATTERNS,\n  DEFAULT_MAX_CHAIN_DEPTH,\n  evaluateMerge,\n  type GuardOutcome,\n  guardOutboundContent,\n  type MergeBiasDecision,\n  type MergeGuardConfig,\n  type ProtocolBoundary,\n  type ProtocolEscapePolicy,\n  type ProtocolGuardConfig,\n  resolvePolicy,\n  type TrustClass,\n} from './lateral-leak/index.js';\nexport {\n  type PreferredModelResolution,\n  pickTopTierAcrossTools,\n  type ResolvePreferredModelInput,\n  resolvePreferredModel,\n} from './preferred-model/index.js';\nexport {\n  createProgressIO,\n  type ProgressIO,\n  type ProgressIOConfig,\n  type ProgressReadOptions,\n  type ProgressWriteOptions,\n} from './progress/index.js';\nexport {\n  addModelUsage,\n  aggregateUsageFromByModel,\n  completedToolCallsFromState,\n  createInitialRunState,\n  deserializeRunState,\n  RUN_STATE_SCHEMA_MAJOR_SUPPORTED,\n  RUN_STATE_SCHEMA_VERSION,\n  runStateFromJSON,\n  runStateToJSON,\n  type SerializedRunState,\n  type SerializeRunStateOptions,\n  serializeRunState,\n} from './run-state/index.js';\nexport type {\n  AbortOptions,\n  Agent,\n  AgentCallOptions,\n  AgentConfig,\n  AgentInput,\n  AgentToToolOptions,\n  CompactionApiResult,\n  CompactOptions,\n  OutputSpec,\n  PostCompactionHook,\n  PrepareStepHook,\n  PrepareStepOverrides,\n  ResumeDirective,\n  SkillsRegistryLike,\n} from './types.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,MAAa,UAAU"}

package/dist/internal/ids.js

@@ -0,0 +1,46 @@
+import { randomBytes } from "node:crypto";
+
+//#region src/internal/ids.ts
+/**
+* Tiny id helpers used by the agent runtime. URL-safe Base32 alphabet,
+* monotonic timestamp prefix to keep ids loosely sortable.
+*
+* @packageDocumentation
+*/
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function pad(value, width) {
+	return value.padStart(width, "0");
+}
+/**
+* 7-character Base32 tail backed by 35 bits of CSPRNG entropy. We read
+* 5 random bytes (40 bits) and consume 5 bits per emitted character
+* MSB-first; the leftover bits are discarded. Sourcing from
+* `randomBytes` (uniform over `[0, 256)`) guarantees a uniform
+* distribution over `ALPHABET` — no modulo bias.
+*/
+function randomTail() {
+	const buf = randomBytes(5);
+	let bitBuffer = 0;
+	let bitCount = 0;
+	let cursor = 0;
+	let out = "";
+	for (let i = 0; i < 7; i++) {
+		while (bitCount < 5) {
+			bitBuffer = bitBuffer << 8 | (buf[cursor++] ?? 0);
+			bitCount += 8;
+		}
+		bitCount -= 5;
+		const idx = bitBuffer >>> bitCount & 31;
+		out += ALPHABET[idx];
+	}
+	return out;
+}
+/** Generate a fresh, sortable, URL-safe identifier. */
+function newId(prefix) {
+	const id = `${pad(Date.now().toString(32).toUpperCase(), 9)}${randomTail()}`;
+	return prefix ? `${prefix}_${id}` : id;
+}
+
+//#endregion
+export { newId };
+//# sourceMappingURL=ids.js.map

package/dist/internal/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","names":[],"sources":["../../src/internal/ids.ts"],"sourcesContent":["/**\n * Tiny id helpers used by the agent runtime. URL-safe Base32 alphabet,\n * monotonic timestamp prefix to keep ids loosely sortable.\n *\n * @packageDocumentation\n */\n\nimport { randomBytes } from 'node:crypto';\n\nconst ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';\n\nfunction pad(value: string, width: number): string {\n  return value.padStart(width, '0');\n}\n\n/**\n * 7-character Base32 tail backed by 35 bits of CSPRNG entropy. We read\n * 5 random bytes (40 bits) and consume 5 bits per emitted character\n * MSB-first; the leftover bits are discarded. Sourcing from\n * `randomBytes` (uniform over `[0, 256)`) guarantees a uniform\n * distribution over `ALPHABET` — no modulo bias.\n */\nfunction randomTail(): string {\n  const buf = randomBytes(5);\n  let bitBuffer = 0;\n  let bitCount = 0;\n  let cursor = 0;\n  let out = '';\n  for (let i = 0; i < 7; i++) {\n    while (bitCount < 5) {\n      bitBuffer = (bitBuffer << 8) | (buf[cursor++] ?? 0);\n      bitCount += 8;\n    }\n    bitCount -= 5;\n    const idx = (bitBuffer >>> bitCount) & 0x1f;\n    out += ALPHABET[idx];\n  }\n  return out;\n}\n\n/** Generate a fresh, sortable, URL-safe identifier. */\nexport function newId(prefix?: string): string {\n  const ts = pad(Date.now().toString(32).toUpperCase(), 9);\n  const id = `${ts}${randomTail()}`;\n  return prefix ? `${prefix}_${id}` : id;\n}\n"],"mappings":";;;;;;;;;AASA,MAAM,WAAW;AAEjB,SAAS,IAAI,OAAe,OAAuB;AACjD,QAAO,MAAM,SAAS,OAAO,IAAI;;;;;;;;;AAUnC,SAAS,aAAqB;CAC5B,MAAM,MAAM,YAAY,EAAE;CAC1B,IAAI,YAAY;CAChB,IAAI,WAAW;CACf,IAAI,SAAS;CACb,IAAI,MAAM;AACV,MAAK,IAAI,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,SAAO,WAAW,GAAG;AACnB,eAAa,aAAa,KAAM,IAAI,aAAa;AACjD,eAAY;;AAEd,cAAY;EACZ,MAAM,MAAO,cAAc,WAAY;AACvC,SAAO,SAAS;;AAElB,QAAO;;;AAIT,SAAgB,MAAM,QAAyB;CAE7C,MAAM,KAAK,GADA,IAAI,KAAK,KAAK,CAAC,SAAS,GAAG,CAAC,aAAa,EAAE,EAAE,GACrC,YAAY;AAC/B,QAAO,SAAS,GAAG,OAAO,GAAG,OAAO"}

package/dist/internal/usage-accumulator.js

@@ -0,0 +1,62 @@
+//#region src/internal/usage-accumulator.ts
+var InMemoryUsageAccumulator = class {
+	#aggregate = {
+		promptTokens: 0,
+		completionTokens: 0,
+		totalTokens: 0
+	};
+	#byModel = /* @__PURE__ */ new Map();
+	get total() {
+		return this.#aggregate;
+	}
+	get byModel() {
+		return this.#byModel;
+	}
+	add(modelId, usage) {
+		const prev = this.#byModel.get(modelId);
+		if (prev === void 0) this.#byModel.set(modelId, {
+			modelId,
+			promptTokens: usage.promptTokens,
+			completionTokens: usage.completionTokens,
+			totalTokens: usage.totalTokens,
+			callCount: 1,
+			...usage.reasoningTokens !== void 0 ? { reasoningTokens: usage.reasoningTokens } : {},
+			...usage.cost !== void 0 ? { cost: usage.cost } : {}
+		});
+		else {
+			const merged = {
+				modelId,
+				promptTokens: prev.promptTokens + usage.promptTokens,
+				completionTokens: prev.completionTokens + usage.completionTokens,
+				totalTokens: prev.totalTokens + usage.totalTokens,
+				callCount: prev.callCount + 1,
+				...usage.reasoningTokens !== void 0 || prev.reasoningTokens !== void 0 ? { reasoningTokens: (prev.reasoningTokens ?? 0) + (usage.reasoningTokens ?? 0) } : {}
+			};
+			this.#byModel.set(modelId, merged);
+		}
+		this.#aggregate = {
+			promptTokens: this.#aggregate.promptTokens + usage.promptTokens,
+			completionTokens: this.#aggregate.completionTokens + usage.completionTokens,
+			totalTokens: this.#aggregate.totalTokens + usage.totalTokens,
+			...usage.reasoningTokens !== void 0 || this.#aggregate.reasoningTokens !== void 0 ? { reasoningTokens: (this.#aggregate.reasoningTokens ?? 0) + (usage.reasoningTokens ?? 0) } : {}
+		};
+	}
+	reset() {
+		this.#aggregate = {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0
+		};
+		this.#byModel.clear();
+	}
+	snapshot() {
+		return {
+			total: { ...this.#aggregate },
+			byModel: Array.from(this.#byModel.values()).map((m) => ({ ...m }))
+		};
+	}
+};
+
+//#endregion
+export { InMemoryUsageAccumulator };
+//# sourceMappingURL=usage-accumulator.js.map

package/dist/internal/usage-accumulator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-accumulator.js","names":["#byModel","#aggregate","merged: ModelUsage"],"sources":["../../src/internal/usage-accumulator.ts"],"sourcesContent":["/**\n * Minimal {@link UsageAccumulator} implementation used by the agent\n * runtime when the consumer does not pass a custom one through\n * `RunContext.usage`. Tracks per-model breakdown and a running\n * aggregate.\n *\n * @packageDocumentation\n */\n\nimport type { ModelUsage, Usage, UsageAccumulator, UsageSnapshot } from '@graphorin/core';\n\nexport class InMemoryUsageAccumulator implements UsageAccumulator {\n  #aggregate: Usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };\n  readonly #byModel = new Map<string, ModelUsage>();\n\n  get total(): Usage {\n    return this.#aggregate;\n  }\n\n  get byModel(): ReadonlyMap<string, ModelUsage> {\n    return this.#byModel;\n  }\n\n  add(modelId: string, usage: Usage): void {\n    const prev = this.#byModel.get(modelId);\n    if (prev === undefined) {\n      this.#byModel.set(modelId, {\n        modelId,\n        promptTokens: usage.promptTokens,\n        completionTokens: usage.completionTokens,\n        totalTokens: usage.totalTokens,\n        callCount: 1,\n        ...(usage.reasoningTokens !== undefined ? { reasoningTokens: usage.reasoningTokens } : {}),\n        ...(usage.cost !== undefined ? { cost: usage.cost } : {}),\n      });\n    } else {\n      const merged: ModelUsage = {\n        modelId,\n        promptTokens: prev.promptTokens + usage.promptTokens,\n        completionTokens: prev.completionTokens + usage.completionTokens,\n        totalTokens: prev.totalTokens + usage.totalTokens,\n        callCount: prev.callCount + 1,\n        ...(usage.reasoningTokens !== undefined || prev.reasoningTokens !== undefined\n          ? {\n              reasoningTokens: (prev.reasoningTokens ?? 0) + (usage.reasoningTokens ?? 0),\n            }\n          : {}),\n      };\n      this.#byModel.set(modelId, merged);\n    }\n    this.#aggregate = {\n      promptTokens: this.#aggregate.promptTokens + usage.promptTokens,\n      completionTokens: this.#aggregate.completionTokens + usage.completionTokens,\n      totalTokens: this.#aggregate.totalTokens + usage.totalTokens,\n      ...(usage.reasoningTokens !== undefined || this.#aggregate.reasoningTokens !== undefined\n        ? {\n            reasoningTokens: (this.#aggregate.reasoningTokens ?? 0) + (usage.reasoningTokens ?? 0),\n          }\n        : {}),\n    };\n  }\n\n  reset(): void {\n    this.#aggregate = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };\n    this.#byModel.clear();\n  }\n\n  snapshot(): UsageSnapshot {\n    return {\n      total: { ...this.#aggregate },\n      byModel: Array.from(this.#byModel.values()).map((m) => ({ ...m })),\n    };\n  }\n}\n"],"mappings":";AAWA,IAAa,2BAAb,MAAkE;CAChE,aAAoB;EAAE,cAAc;EAAG,kBAAkB;EAAG,aAAa;EAAG;CAC5E,CAASA,0BAAW,IAAI,KAAyB;CAEjD,IAAI,QAAe;AACjB,SAAO,MAAKC;;CAGd,IAAI,UAA2C;AAC7C,SAAO,MAAKD;;CAGd,IAAI,SAAiB,OAAoB;EACvC,MAAM,OAAO,MAAKA,QAAS,IAAI,QAAQ;AACvC,MAAI,SAAS,OACX,OAAKA,QAAS,IAAI,SAAS;GACzB;GACA,cAAc,MAAM;GACpB,kBAAkB,MAAM;GACxB,aAAa,MAAM;GACnB,WAAW;GACX,GAAI,MAAM,oBAAoB,SAAY,EAAE,iBAAiB,MAAM,iBAAiB,GAAG,EAAE;GACzF,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD,CAAC;OACG;GACL,MAAME,SAAqB;IACzB;IACA,cAAc,KAAK,eAAe,MAAM;IACxC,kBAAkB,KAAK,mBAAmB,MAAM;IAChD,aAAa,KAAK,cAAc,MAAM;IACtC,WAAW,KAAK,YAAY;IAC5B,GAAI,MAAM,oBAAoB,UAAa,KAAK,oBAAoB,SAChE,EACE,kBAAkB,KAAK,mBAAmB,MAAM,MAAM,mBAAmB,IAC1E,GACD,EAAE;IACP;AACD,SAAKF,QAAS,IAAI,SAAS,OAAO;;AAEpC,QAAKC,YAAa;GAChB,cAAc,MAAKA,UAAW,eAAe,MAAM;GACnD,kBAAkB,MAAKA,UAAW,mBAAmB,MAAM;GAC3D,aAAa,MAAKA,UAAW,cAAc,MAAM;GACjD,GAAI,MAAM,oBAAoB,UAAa,MAAKA,UAAW,oBAAoB,SAC3E,EACE,kBAAkB,MAAKA,UAAW,mBAAmB,MAAM,MAAM,mBAAmB,IACrF,GACD,EAAE;GACP;;CAGH,QAAc;AACZ,QAAKA,YAAa;GAAE,cAAc;GAAG,kBAAkB;GAAG,aAAa;GAAG;AAC1E,QAAKD,QAAS,OAAO;;CAGvB,WAA0B;AACxB,SAAO;GACL,OAAO,EAAE,GAAG,MAAKC,WAAY;GAC7B,SAAS,MAAM,KAAK,MAAKD,QAAS,QAAQ,CAAC,CAAC,KAAK,OAAO,EAAE,GAAG,GAAG,EAAE;GACnE"}

package/dist/lateral-leak/causality-monitor.d.ts

@@ -0,0 +1,97 @@
+import { LateralLeakVector } from "@graphorin/core";
+
+//#region src/lateral-leak/causality-monitor.d.ts
+
+/**
+ * Operator-tunable strictness level. Default `'detect-and-flag'`
+ * for cloud-tier providers; `'detect'` for loopback providers;
+ * `'off'` for v0.1-alpha backward compatibility.
+ *
+ * @stable
+ */
+type CausalityMonitorStrictness = 'off' | 'detect' | 'detect-and-flag' | 'detect-and-block';
+/**
+ * Per-agent configuration accepted by `createAgent({ causalityMonitor })`.
+ *
+ * @stable
+ */
+interface CausalityMonitorConfig {
+  readonly strictness: CausalityMonitorStrictness;
+  /** Maximum depth of the chain. Default `32`. */
+  readonly maxChainDepth?: number;
+  /** Operator-extensible denial patterns. */
+  readonly denialPatterns?: ReadonlyArray<RegExp>;
+  /**
+   * When `true`, emit the chain on every `checkMessage(...)` call
+   * (high-cardinality; opt-in for compliance audits). Default
+   * `false` — only emit on detected leaks.
+   */
+  readonly auditAllChains?: boolean;
+}
+/**
+ * Default denial-pattern catalogue. The agent runtime extends this
+ * list when the operator supplies their own patterns.
+ *
+ * @stable
+ */
+declare const DEFAULT_DENIAL_PATTERNS: ReadonlyArray<RegExp>;
+/** Default chain depth when not specified. */
+declare const DEFAULT_MAX_CHAIN_DEPTH = 32;
+/**
+ * Result returned by {@link CausalityMonitor.checkMessage}.
+ *
+ * @stable
+ */
+interface CausalityMonitorCheck {
+  readonly leakDetected: boolean;
+  readonly severity: 'info' | 'warn' | 'block';
+  readonly causalityChain: ReadonlyArray<string>;
+  readonly matchedPattern?: string;
+  readonly decision: 'detect' | 'flag' | 'strip' | 'block';
+  readonly vector: LateralLeakVector;
+}
+/**
+ * In-memory primitive instantiated per `RunContext`. Bounded-depth
+ * append discipline keeps the memory footprint trivial even on long
+ * runs.
+ *
+ * @stable
+ */
+declare class CausalityMonitor {
+  #private;
+  readonly strictness: CausalityMonitorStrictness;
+  readonly maxChainDepth: number;
+  readonly denialPatterns: ReadonlyArray<RegExp>;
+  readonly auditAllChains: boolean;
+  constructor(cfg: CausalityMonitorConfig);
+  /** Snapshot the current causality chain. */
+  get chain(): ReadonlyArray<string>;
+  /**
+   * 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: string): void;
+  /** Reset the chain — e.g. on `agent.run` boundary. */
+  reset(): void;
+  /**
+   * 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: string): CausalityMonitorCheck;
+  /**
+   * 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: 'agent.run.complete' | 'agent.abort'): {
+    readonly chain: ReadonlyArray<string>;
+    readonly reason: 'agent.run.complete' | 'agent.abort';
+  };
+}
+//#endregion
+export { CausalityMonitor, CausalityMonitorCheck, CausalityMonitorConfig, CausalityMonitorStrictness, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH };
+//# sourceMappingURL=causality-monitor.d.ts.map

package/dist/lateral-leak/causality-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causality-monitor.d.ts","names":[],"sources":["../../src/lateral-leak/causality-monitor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;KAuBY,0BAAA;;;;;;UAOK,sBAAA;uBACM;;;;4BAIK,cAAc;;;;;;;;;;;;;;cAe7B,yBAAyB,cAAc;;cAQvC,uBAAA;;;;;;UAOI,qBAAA;;;2BAGU;;;mBAGR;;;;;;;;;cAUN,gBAAA;;uBACU;;2BAEI,cAAc;;mBAItB;;eAUJ;;;;;;;;;;;;;;;;iCA8BkB;;;;;;;oBAuFb"}