@graphorin/agent 0.5.0

package/dist/fanout/index.d.ts

@@ -0,0 +1,142 @@
+import { ContentOriginKind, MergeGuardConfig, TrustClass } from "../lateral-leak/merge-guard.js";
+import { AgentEvent } from "@graphorin/core";
+
+//#region src/fanout/index.d.ts
+
+/**
+ * Per-child budget. Defaults derived from the canonical 2026
+ * scaling-rule table for agent fan-out workloads.
+ *
+ * @stable
+ */
+interface PerChildBudget {
+  /**
+   * Max `usage.totalTokens` per child. Enforced **post-hoc** and only
+   * for usage-reporting children (an `invoke` that resolves to a full
+   * `AgentResult` — e.g. `() => child.run(input)`); a child returning a
+   * plain value reports `tokensUsed: 0` and this cap cannot fire.
+   */
+  readonly tokens?: number;
+  /**
+   * Max tool calls per child. Same usage-reporting contract as
+   * {@link PerChildBudget.tokens} (counted from `state.steps`).
+   */
+  readonly toolCalls?: number;
+  /** Wall-clock cap, enforced for every child via a race timer. */
+  readonly durationMs?: number;
+}
+/**
+ * Built-in merge-strategy taxonomy.
+ *
+ * @stable
+ */
+type MergeStrategy<TOutput = unknown> = {
+  readonly kind: 'concat';
+  readonly separator?: string;
+} | {
+  readonly kind: 'first-success';
+} | {
+  readonly kind: 'judge-merge';
+  readonly judge: (children: ReadonlyArray<ChildResult<TOutput>>) => Promise<TOutput>;
+} | {
+  readonly kind: 'custom';
+  readonly merge: (children: ReadonlyArray<ChildResult<TOutput>>) => Promise<TOutput>;
+};
+/**
+ * Per-child outcome surfaced on
+ * {@link FanOutResult.children}. Failed-child isolation: a child
+ * that throws produces a `ChildResult` with `status: 'failed'` —
+ * never an exception thrown from the fan-out call itself.
+ *
+ * @stable
+ */
+interface ChildResult<TOutput = unknown> {
+  readonly agentId: string;
+  readonly status: 'completed' | 'failed' | 'budget-exceeded' | 'cancelled';
+  readonly output?: TOutput;
+  readonly error?: {
+    readonly message: string;
+    readonly code: string;
+  };
+  readonly tokensUsed: number;
+  readonly toolCallCount: number;
+  readonly durationMs: number;
+}
+/**
+ * Aggregate result returned by `Agent.fanOut(...)`.
+ *
+ * @stable
+ */
+interface FanOutResult<TOutput = unknown> {
+  readonly fanOutId: string;
+  readonly output: TOutput;
+  readonly children: ReadonlyArray<ChildResult<TOutput>>;
+  readonly mergeDurationMs: number;
+}
+/**
+ * Per-call options accepted by `Agent.fanOut(...)`.
+ *
+ * @stable
+ */
+interface FanOutOptions<TOutput = unknown> {
+  /**
+   * The sub-agents to invoke. Each entry is invoked as a function
+   * returning a `Promise<TOutput>` — the fan-out helper does not
+   * impose an `Agent` shape on the children so the runtime can
+   * adapt any callable surface.
+   */
+  readonly children: ReadonlyArray<{
+    readonly agentId: string;
+    /**
+     * Child callable. Resolve to a plain `TOutput`, or to a full
+     * `AgentResult` (e.g. `() => childAgent.run(input)`) — the fan-out
+     * detects the result envelope structurally (`output` + numeric
+     * `usage.totalTokens` + `state`), unwraps `output`, and harvests
+     * `tokensUsed` / `toolCallCount` so per-child budgets can enforce.
+     */
+    readonly invoke: () => Promise<TOutput>;
+    /** Trust-class for the merge guard (default `'loopback'`). */
+    readonly trustClass?: TrustClass;
+    /** Content-origin for the merge guard (default `'built-in'`). */
+    readonly origin?: ContentOriginKind;
+    /** Rolling trust adjustment in `[0,1]` (default `1`). */
+    readonly historyAdjustment?: number;
+  }>;
+  /** Default `4` per the canonical 2026 production lesson. */
+  readonly maxConcurrentChildren?: number;
+  /** Per-child budget; default unset. */
+  readonly perBudget?: PerChildBudget;
+  /** Default `{ kind: 'concat' }`. */
+  readonly mergeStrategy?: MergeStrategy<TOutput>;
+  readonly signal?: AbortSignal;
+  /** Optional callback for per-child completion observability. */
+  readonly onChildResult?: (result: ChildResult<TOutput>) => void;
+  /** Optional event emitter for `agent.fanout.spawned / merged`. */
+  readonly emit?: (event: AgentEvent) => void;
+  /**
+   * Sideways-injection merge guard (AG-7): on `'judge-merge'` the
+   * fan-out scores each child's source trust and contribution weight
+   * against the judge's merged output; a biased merge emits
+   * `agent.lateral-leak.detected` (vector `sideways-injection`) and —
+   * under `strictness: 'detect-and-block'` — throws
+   * {@link MergeBlockedError}.
+   */
+  readonly mergeGuard?: MergeGuardConfig;
+  /** Identifiers required to populate the events. */
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly agentId: string;
+  /** Default — generated from `runId + Date.now()`. */
+  readonly fanOutId?: string;
+}
+/**
+ * Run a fan-out and produce the aggregate {@link FanOutResult}.
+ * Pure with respect to side effects — the runtime emits events /
+ * audit rows / counter increments via the supplied `emit` callback.
+ *
+ * @stable
+ */
+declare function runFanOut<TOutput>(opts: FanOutOptions<TOutput>): Promise<FanOutResult<TOutput>>;
+//#endregion
+export { ChildResult, FanOutOptions, FanOutResult, MergeStrategy, PerChildBudget, runFanOut };
+//# sourceMappingURL=index.d.ts.map

package/dist/fanout/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/fanout/index.ts"],"sourcesContent":[],"mappings":";;;;;;AA0EA;AAeA;;;;AAGqB,UA5DJ,cAAA,CA4DI;EAAa;AASlC;;;;;EAOqB,SAAA,MAAA,CAAA,EAAA,MAAA;EAoBE;;;;EAKyB,SAAA,SAAA,CAAA,EAAA,MAAA;EAAZ;EAEV,SAAA,UAAA,CAAA,EAAA,MAAA;;;AAkM1B;;;;AAEW,KArRC,aAqRD,CAAA,UAAA,OAAA,CAAA,GAAA;EAAR,SAAA,IAAA,EAAA,QAAA;EAAO,SAAA,SAAA,CAAA,EAAA,MAAA;;;;;6BAhRuB,cAAc,YAAY,cAAc,QAAQ;;;6BAIhD,cAAc,YAAY,cAAc,QAAQ;;;;;;;;;;UAWhE;;;oBAGG;;;;;;;;;;;;;;UAYH;;mBAEE;qBACE,cAAc,YAAY;;;;;;;;UAS9B;;;;;;;qBAOI;;;;;;;;;2BASM,QAAQ;;0BAET;;sBAEJ;;;;;;;uBAOC;;2BAEI,cAAc;oBACrB;;oCAEgB,YAAY;;0BAEtB;;;;;;;;;wBASF;;;;;;;;;;;;;;;iBAyLF,yBACd,cAAc,WACnB,QAAQ,aAAa"}

package/dist/fanout/index.js

@@ -0,0 +1,252 @@
+import { MergeBlockedError } from "../errors/index.js";
+import { computeSourceTrust, evaluateMerge } from "../lateral-leak/merge-guard.js";
+import { createHash } from "node:crypto";
+
+//#region src/fanout/index.ts
+/**
+* Agent-step-level fan-out — `Agent.fanOut(...)` convenience that
+* spawns N sub-agents in parallel under a bounded-fanout cap with
+* per-child budgets and four built-in merge strategies.
+*
+* Boundary discipline against the workflow `Dispatch(...)`
+* primitive: fan-out is **agent-step-level inline result** (children
+* share parent `RunContext` lineage; result consumed by parent's
+* continuing loop within one or few `agent.run(...)` calls).
+* `Dispatch(...)` is workflow-step-level checkpointed durable graph.
+* The two compose orthogonally.
+*
+* @packageDocumentation
+*/
+const DEFAULT_MAX_CONCURRENT_CHILDREN = 4;
+/**
+* Structurally detect a full `AgentResult` returned by a child
+* `invoke` (AG-16): an object carrying `output`, a numeric
+* `usage.totalTokens`, and a `state` with string `id`/`status`. The
+* three-field match makes accidental collision with a user `TOutput`
+* negligible; children whose genuine output looks like this should
+* resolve a plain value instead.
+*/
+function harvestAgentResult(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const v = value;
+	if (!("output" in v)) return void 0;
+	if (typeof v.usage?.totalTokens !== "number") return void 0;
+	if (typeof v.state?.id !== "string" || typeof v.state.status !== "string") return void 0;
+	let toolCallCount = 0;
+	if (Array.isArray(v.state.steps)) for (const step of v.state.steps) {
+		const calls = step.toolCalls;
+		if (Array.isArray(calls)) toolCallCount += calls.length;
+	}
+	return {
+		output: v.output,
+		tokensUsed: v.usage.totalTokens,
+		toolCallCount
+	};
+}
+/**
+* Whitespace-token overlap of a child's output against the merged
+* output, in `[0,1]` — the contribution-weight estimate the merge
+* guard's docstring contracts (each child scored independently; a
+* judge parroting one child verbatim yields ~1.0 for that child).
+*/
+function contributionWeight(childText, mergedText) {
+	if (childText.length === 0 || mergedText.length === 0) return 0;
+	const mergedTokens = mergedText.split(/\s+/).filter((t) => t.length > 0);
+	if (mergedTokens.length === 0) return 0;
+	const childTokens = new Set(childText.split(/\s+/).filter((t) => t.length > 0));
+	let hits = 0;
+	for (const token of mergedTokens) if (childTokens.has(token)) hits += 1;
+	return hits / mergedTokens.length;
+}
+async function runWithSemaphore(children, cap, signal, perBudget, onChildResult) {
+	const results = new Array(children.length);
+	let cursor = 0;
+	const running = /* @__PURE__ */ new Set();
+	const limit = Math.max(1, Math.min(cap, children.length));
+	const launchOne = (index) => {
+		const child = children[index];
+		if (child === void 0) return Promise.resolve();
+		const start = Date.now();
+		const exec = async () => {
+			if (signal?.aborted) return {
+				agentId: child.agentId,
+				status: "cancelled",
+				tokensUsed: 0,
+				toolCallCount: 0,
+				durationMs: 0
+			};
+			let timer;
+			try {
+				const timedPromise = perBudget?.durationMs !== void 0 ? new Promise((_, reject) => {
+					timer = setTimeout(() => reject(/* @__PURE__ */ new Error("budget-exceeded:durationMs")), perBudget.durationMs);
+				}) : void 0;
+				const raw = await (timedPromise ? Promise.race([child.invoke(), timedPromise]) : child.invoke());
+				const report = harvestAgentResult(raw);
+				const output = report === void 0 ? raw : report.output;
+				const tokensUsed = report?.tokensUsed ?? 0;
+				const toolCallCount = report?.toolCallCount ?? 0;
+				const exceeded = (perBudget?.tokens !== void 0 && tokensUsed > perBudget.tokens ? `tokens ${tokensUsed} > ${perBudget.tokens}` : void 0) ?? (perBudget?.toolCalls !== void 0 && toolCallCount > perBudget.toolCalls ? `toolCalls ${toolCallCount} > ${perBudget.toolCalls}` : void 0);
+				if (exceeded !== void 0) return {
+					agentId: child.agentId,
+					status: "budget-exceeded",
+					error: {
+						message: `budget-exceeded: ${exceeded}`,
+						code: "budget-exceeded"
+					},
+					tokensUsed,
+					toolCallCount,
+					durationMs: Date.now() - start
+				};
+				return {
+					agentId: child.agentId,
+					status: "completed",
+					output,
+					tokensUsed,
+					toolCallCount,
+					durationMs: Date.now() - start
+				};
+			} catch (cause) {
+				const message = cause instanceof Error ? cause.message : String(cause);
+				const aborted = signal?.aborted;
+				const status = message.startsWith("budget-exceeded") ? "budget-exceeded" : aborted ? "cancelled" : "failed";
+				return {
+					agentId: child.agentId,
+					status,
+					error: {
+						message,
+						code: status
+					},
+					tokensUsed: 0,
+					toolCallCount: 0,
+					durationMs: Date.now() - start
+				};
+			} finally {
+				if (timer !== void 0) clearTimeout(timer);
+			}
+		};
+		const promise = exec().then((r) => {
+			results[index] = r;
+			onChildResult?.(r);
+		});
+		running.add(promise);
+		promise.finally(() => running.delete(promise));
+		return promise;
+	};
+	while (cursor < children.length || running.size > 0) {
+		while (running.size < limit && cursor < children.length) {
+			launchOne(cursor);
+			cursor += 1;
+		}
+		if (running.size > 0) await Promise.race(running);
+	}
+	return results;
+}
+/**
+* Run a fan-out and produce the aggregate {@link FanOutResult}.
+* Pure with respect to side effects — the runtime emits events /
+* audit rows / counter increments via the supplied `emit` callback.
+*
+* @stable
+*/
+async function runFanOut(opts) {
+	const fanOutId = opts.fanOutId ?? `fanout-${opts.runId.slice(-8)}-${Date.now().toString(36)}`;
+	const merge = opts.mergeStrategy ?? { kind: "concat" };
+	const cap = opts.maxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN;
+	opts.emit?.({
+		type: "agent.fanout.spawned",
+		runId: opts.runId,
+		sessionId: opts.sessionId,
+		agentId: opts.agentId,
+		fanOutId,
+		childCount: opts.children.length,
+		mergeStrategyKind: merge.kind,
+		spawnedAtIso: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	const results = await runWithSemaphore(opts.children, cap, opts.signal, opts.perBudget, opts.onChildResult);
+	const mergeStart = Date.now();
+	let merged;
+	switch (merge.kind) {
+		case "concat": {
+			const sep = merge.separator ?? "\n\n---\n\n";
+			const parts = [];
+			for (const r of results) if (r.status === "completed" && r.output !== void 0) parts.push(typeof r.output === "string" ? r.output : JSON.stringify(r.output));
+			else if (r.status === "failed" || r.status === "budget-exceeded" || r.status === "cancelled") parts.push(`[${r.status}: ${r.agentId}]`);
+			merged = parts.join(sep);
+			break;
+		}
+		case "first-success":
+			merged = results.find((r) => r.status === "completed")?.output ?? "";
+			break;
+		case "judge-merge":
+			merged = await merge.judge(results);
+			if (opts.mergeGuard !== void 0 && opts.mergeGuard.strictness !== "off") {
+				const mergedText = typeof merged === "string" ? merged : JSON.stringify(merged);
+				const overrides = opts.mergeGuard.sourceTrustOverrides ?? {};
+				const verdict = evaluateMerge(results.map((r, i) => {
+					const c = opts.children[i];
+					const childText = r.output === void 0 ? "" : typeof r.output === "string" ? r.output : JSON.stringify(r.output);
+					return {
+						agentId: r.agentId,
+						sourceTrust: computeSourceTrust({
+							agentId: r.agentId,
+							trustClass: c?.trustClass ?? "loopback",
+							origin: c?.origin ?? "built-in",
+							...c?.historyAdjustment !== void 0 ? { historyAdjustment: c.historyAdjustment } : {}
+						}, overrides),
+						contributionWeight: contributionWeight(childText, mergedText)
+					};
+				}), opts.mergeGuard);
+				if (verdict.biased) {
+					opts.emit?.({
+						type: "agent.lateral-leak.detected",
+						runId: opts.runId,
+						sessionId: opts.sessionId,
+						agentId: opts.agentId,
+						vector: "sideways-injection",
+						severity: verdict.decision === "block" ? "block" : "warn",
+						causalityChain: verdict.offendingChild === void 0 ? [] : [verdict.offendingChild],
+						messageContentSha256: createHash("sha256").update(mergedText, "utf8").digest("hex"),
+						decision: verdict.decision === "block" ? "block" : verdict.decision === "flag" ? "flag" : "detect",
+						detectedAtIso: (/* @__PURE__ */ new Date()).toISOString()
+					});
+					if (verdict.decision === "block") throw new MergeBlockedError(fanOutId, `low-trust child '${verdict.offendingChild}' (sourceTrust ${verdict.sourceTrust?.toFixed(2)}) contributes ${((verdict.contributionWeight ?? 0) * 100).toFixed(0)}% of the merged output`);
+				}
+			}
+			break;
+		case "custom":
+			merged = await merge.merge(results);
+			break;
+		default: merged = "";
+	}
+	const mergeDurationMs = Date.now() - mergeStart;
+	const childMetadata = results.map((r) => ({
+		agentId: r.agentId,
+		status: r.status,
+		tokensUsed: r.tokensUsed,
+		toolCallCount: r.toolCallCount,
+		durationMs: r.durationMs
+	}));
+	const successfulChildCount = results.filter((r) => r.status === "completed").length;
+	opts.emit?.({
+		type: "agent.fanout.merged",
+		runId: opts.runId,
+		sessionId: opts.sessionId,
+		agentId: opts.agentId,
+		fanOutId,
+		childCount: opts.children.length,
+		successfulChildCount,
+		mergeStrategyKind: merge.kind,
+		mergeDurationMs,
+		childMetadata
+	});
+	return {
+		fanOutId,
+		output: merged,
+		children: results,
+		mergeDurationMs
+	};
+}
+
+//#endregion
+export { runFanOut };
+//# sourceMappingURL=index.js.map

package/dist/fanout/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["results: ChildResult<TOutput>[]","running: Set<Promise<void>>","timer: ReturnType<typeof setTimeout> | undefined","status: ChildResult<TOutput>['status']","merge: MergeStrategy<TOutput>","merged: TOutput","parts: string[]","childMetadata: FanOutChildMetadata[]"],"sources":["../../src/fanout/index.ts"],"sourcesContent":["/**\n * Agent-step-level fan-out — `Agent.fanOut(...)` convenience that\n * spawns N sub-agents in parallel under a bounded-fanout cap with\n * per-child budgets and four built-in merge strategies.\n *\n * Boundary discipline against the workflow `Dispatch(...)`\n * primitive: fan-out is **agent-step-level inline result** (children\n * share parent `RunContext` lineage; result consumed by parent's\n * continuing loop within one or few `agent.run(...)` calls).\n * `Dispatch(...)` is workflow-step-level checkpointed durable graph.\n * The two compose orthogonally.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'node:crypto';\nimport type { AgentEvent, FanOutChildMetadata } from '@graphorin/core';\nimport { MergeBlockedError } from '../errors/index.js';\nimport {\n  type ContentOriginKind,\n  computeSourceTrust,\n  evaluateMerge,\n  type MergeGuardConfig,\n  type TrustClass,\n} from '../lateral-leak/merge-guard.js';\n\n/**\n * Per-child budget. Defaults derived from the canonical 2026\n * scaling-rule table for agent fan-out workloads.\n *\n * @stable\n */\nexport interface PerChildBudget {\n  /**\n   * Max `usage.totalTokens` per child. Enforced **post-hoc** and only\n   * for usage-reporting children (an `invoke` that resolves to a full\n   * `AgentResult` — e.g. `() => child.run(input)`); a child returning a\n   * plain value reports `tokensUsed: 0` and this cap cannot fire.\n   */\n  readonly tokens?: number;\n  /**\n   * Max tool calls per child. Same usage-reporting contract as\n   * {@link PerChildBudget.tokens} (counted from `state.steps`).\n   */\n  readonly toolCalls?: number;\n  /** Wall-clock cap, enforced for every child via a race timer. */\n  readonly durationMs?: number;\n}\n\n/**\n * Built-in merge-strategy taxonomy.\n *\n * @stable\n */\nexport type MergeStrategy<TOutput = unknown> =\n  | { readonly kind: 'concat'; readonly separator?: string }\n  | { readonly kind: 'first-success' }\n  | {\n      readonly kind: 'judge-merge';\n      readonly judge: (children: ReadonlyArray<ChildResult<TOutput>>) => Promise<TOutput>;\n    }\n  | {\n      readonly kind: 'custom';\n      readonly merge: (children: ReadonlyArray<ChildResult<TOutput>>) => Promise<TOutput>;\n    };\n\n/**\n * Per-child outcome surfaced on\n * {@link FanOutResult.children}. Failed-child isolation: a child\n * that throws produces a `ChildResult` with `status: 'failed'` —\n * never an exception thrown from the fan-out call itself.\n *\n * @stable\n */\nexport interface ChildResult<TOutput = unknown> {\n  readonly agentId: string;\n  readonly status: 'completed' | 'failed' | 'budget-exceeded' | 'cancelled';\n  readonly output?: TOutput;\n  readonly error?: { readonly message: string; readonly code: string };\n  readonly tokensUsed: number;\n  readonly toolCallCount: number;\n  readonly durationMs: number;\n}\n\n/**\n * Aggregate result returned by `Agent.fanOut(...)`.\n *\n * @stable\n */\nexport interface FanOutResult<TOutput = unknown> {\n  readonly fanOutId: string;\n  readonly output: TOutput;\n  readonly children: ReadonlyArray<ChildResult<TOutput>>;\n  readonly mergeDurationMs: number;\n}\n\n/**\n * Per-call options accepted by `Agent.fanOut(...)`.\n *\n * @stable\n */\nexport interface FanOutOptions<TOutput = unknown> {\n  /**\n   * The sub-agents to invoke. Each entry is invoked as a function\n   * returning a `Promise<TOutput>` — the fan-out helper does not\n   * impose an `Agent` shape on the children so the runtime can\n   * adapt any callable surface.\n   */\n  readonly children: ReadonlyArray<{\n    readonly agentId: string;\n    /**\n     * Child callable. Resolve to a plain `TOutput`, or to a full\n     * `AgentResult` (e.g. `() => childAgent.run(input)`) — the fan-out\n     * detects the result envelope structurally (`output` + numeric\n     * `usage.totalTokens` + `state`), unwraps `output`, and harvests\n     * `tokensUsed` / `toolCallCount` so per-child budgets can enforce.\n     */\n    readonly invoke: () => Promise<TOutput>;\n    /** Trust-class for the merge guard (default `'loopback'`). */\n    readonly trustClass?: TrustClass;\n    /** Content-origin for the merge guard (default `'built-in'`). */\n    readonly origin?: ContentOriginKind;\n    /** Rolling trust adjustment in `[0,1]` (default `1`). */\n    readonly historyAdjustment?: number;\n  }>;\n  /** Default `4` per the canonical 2026 production lesson. */\n  readonly maxConcurrentChildren?: number;\n  /** Per-child budget; default unset. */\n  readonly perBudget?: PerChildBudget;\n  /** Default `{ kind: 'concat' }`. */\n  readonly mergeStrategy?: MergeStrategy<TOutput>;\n  readonly signal?: AbortSignal;\n  /** Optional callback for per-child completion observability. */\n  readonly onChildResult?: (result: ChildResult<TOutput>) => void;\n  /** Optional event emitter for `agent.fanout.spawned / merged`. */\n  readonly emit?: (event: AgentEvent) => void;\n  /**\n   * Sideways-injection merge guard (AG-7): on `'judge-merge'` the\n   * fan-out scores each child's source trust and contribution weight\n   * against the judge's merged output; a biased merge emits\n   * `agent.lateral-leak.detected` (vector `sideways-injection`) and —\n   * under `strictness: 'detect-and-block'` — throws\n   * {@link MergeBlockedError}.\n   */\n  readonly mergeGuard?: MergeGuardConfig;\n  /** Identifiers required to populate the events. */\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly agentId: string;\n  /** Default — generated from `runId + Date.now()`. */\n  readonly fanOutId?: string;\n}\n\nconst DEFAULT_MAX_CONCURRENT_CHILDREN = 4;\n\n/**\n * Structurally detect a full `AgentResult` returned by a child\n * `invoke` (AG-16): an object carrying `output`, a numeric\n * `usage.totalTokens`, and a `state` with string `id`/`status`. The\n * three-field match makes accidental collision with a user `TOutput`\n * negligible; children whose genuine output looks like this should\n * resolve a plain value instead.\n */\nfunction harvestAgentResult(\n  value: unknown,\n):\n  | { readonly output: unknown; readonly tokensUsed: number; readonly toolCallCount: number }\n  | undefined {\n  if (typeof value !== 'object' || value === null) return undefined;\n  const v = value as {\n    readonly output?: unknown;\n    readonly usage?: { readonly totalTokens?: unknown };\n    readonly state?: { readonly id?: unknown; readonly status?: unknown; readonly steps?: unknown };\n  };\n  if (!('output' in v)) return undefined;\n  if (typeof v.usage?.totalTokens !== 'number') return undefined;\n  if (typeof v.state?.id !== 'string' || typeof v.state.status !== 'string') return undefined;\n  let toolCallCount = 0;\n  if (Array.isArray(v.state.steps)) {\n    for (const step of v.state.steps) {\n      const calls = (step as { readonly toolCalls?: unknown }).toolCalls;\n      if (Array.isArray(calls)) toolCallCount += calls.length;\n    }\n  }\n  return { output: v.output, tokensUsed: v.usage.totalTokens, toolCallCount };\n}\n\n/**\n * Whitespace-token overlap of a child's output against the merged\n * output, in `[0,1]` — the contribution-weight estimate the merge\n * guard's docstring contracts (each child scored independently; a\n * judge parroting one child verbatim yields ~1.0 for that child).\n */\nfunction contributionWeight(childText: string, mergedText: string): number {\n  if (childText.length === 0 || mergedText.length === 0) return 0;\n  const mergedTokens = mergedText.split(/\\s+/).filter((t) => t.length > 0);\n  if (mergedTokens.length === 0) return 0;\n  const childTokens = new Set(childText.split(/\\s+/).filter((t) => t.length > 0));\n  let hits = 0;\n  for (const token of mergedTokens) {\n    if (childTokens.has(token)) hits += 1;\n  }\n  return hits / mergedTokens.length;\n}\n\nasync function runWithSemaphore<TOutput>(\n  children: ReadonlyArray<FanOutOptions<TOutput>['children'][number]>,\n  cap: number,\n  signal: AbortSignal | undefined,\n  perBudget: PerChildBudget | undefined,\n  onChildResult?: (r: ChildResult<TOutput>) => void,\n): Promise<ReadonlyArray<ChildResult<TOutput>>> {\n  const results: ChildResult<TOutput>[] = new Array(children.length);\n  let cursor = 0;\n  const running: Set<Promise<void>> = new Set();\n  const limit = Math.max(1, Math.min(cap, children.length));\n\n  const launchOne = (index: number): Promise<void> => {\n    const child = children[index];\n    if (child === undefined) return Promise.resolve();\n    const start = Date.now();\n    const exec = async (): Promise<ChildResult<TOutput>> => {\n      if (signal?.aborted) {\n        return {\n          agentId: child.agentId,\n          status: 'cancelled',\n          tokensUsed: 0,\n          toolCallCount: 0,\n          durationMs: 0,\n        };\n      }\n      let timer: ReturnType<typeof setTimeout> | undefined;\n      try {\n        const timedPromise =\n          perBudget?.durationMs !== undefined\n            ? new Promise<TOutput>((_, reject) => {\n                timer = setTimeout(\n                  () => reject(new Error('budget-exceeded:durationMs')),\n                  perBudget.durationMs,\n                );\n              })\n            : undefined;\n        const racePromise = timedPromise\n          ? Promise.race([child.invoke(), timedPromise])\n          : child.invoke();\n        const raw = await racePromise;\n        // AG-16: a child resolving to a full AgentResult reports its\n        // real usage — unwrap the output and harvest the counters.\n        const report = harvestAgentResult(raw);\n        const output = (report === undefined ? raw : report.output) as TOutput;\n        const tokensUsed = report?.tokensUsed ?? 0;\n        const toolCallCount = report?.toolCallCount ?? 0;\n        // Post-hoc budget enforcement (only fires for usage-reporting\n        // children): the over-budget output is withheld from the merge.\n        const exceeded =\n          (perBudget?.tokens !== undefined && tokensUsed > perBudget.tokens\n            ? `tokens ${tokensUsed} > ${perBudget.tokens}`\n            : undefined) ??\n          (perBudget?.toolCalls !== undefined && toolCallCount > perBudget.toolCalls\n            ? `toolCalls ${toolCallCount} > ${perBudget.toolCalls}`\n            : undefined);\n        if (exceeded !== undefined) {\n          return {\n            agentId: child.agentId,\n            status: 'budget-exceeded',\n            error: { message: `budget-exceeded: ${exceeded}`, code: 'budget-exceeded' },\n            tokensUsed,\n            toolCallCount,\n            durationMs: Date.now() - start,\n          };\n        }\n        return {\n          agentId: child.agentId,\n          status: 'completed',\n          output,\n          tokensUsed,\n          toolCallCount,\n          durationMs: Date.now() - start,\n        };\n      } catch (cause) {\n        const message = cause instanceof Error ? cause.message : String(cause);\n        const aborted = signal?.aborted;\n        const status: ChildResult<TOutput>['status'] = message.startsWith('budget-exceeded')\n          ? 'budget-exceeded'\n          : aborted\n            ? 'cancelled'\n            : 'failed';\n        return {\n          agentId: child.agentId,\n          status,\n          error: { message, code: status },\n          tokensUsed: 0,\n          toolCallCount: 0,\n          durationMs: Date.now() - start,\n        };\n      } finally {\n        // AG-16: the duration timer must die on EVERY path — leaving it\n        // armed on rejection held the event loop open.\n        if (timer !== undefined) clearTimeout(timer);\n      }\n    };\n    const promise = exec().then((r) => {\n      results[index] = r;\n      onChildResult?.(r);\n    });\n    running.add(promise);\n    promise.finally(() => running.delete(promise));\n    return promise;\n  };\n\n  while (cursor < children.length || running.size > 0) {\n    while (running.size < limit && cursor < children.length) {\n      void launchOne(cursor);\n      cursor += 1;\n    }\n    if (running.size > 0) {\n      await Promise.race(running);\n    }\n  }\n  return results;\n}\n\n/**\n * Run a fan-out and produce the aggregate {@link FanOutResult}.\n * Pure with respect to side effects — the runtime emits events /\n * audit rows / counter increments via the supplied `emit` callback.\n *\n * @stable\n */\nexport async function runFanOut<TOutput>(\n  opts: FanOutOptions<TOutput>,\n): Promise<FanOutResult<TOutput>> {\n  const fanOutId = opts.fanOutId ?? `fanout-${opts.runId.slice(-8)}-${Date.now().toString(36)}`;\n  const merge: MergeStrategy<TOutput> = opts.mergeStrategy ?? {\n    kind: 'concat',\n  };\n  const cap = opts.maxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN;\n\n  opts.emit?.({\n    type: 'agent.fanout.spawned',\n    runId: opts.runId,\n    sessionId: opts.sessionId,\n    agentId: opts.agentId,\n    fanOutId,\n    childCount: opts.children.length,\n    mergeStrategyKind: merge.kind,\n    spawnedAtIso: new Date().toISOString(),\n  });\n\n  const results = await runWithSemaphore<TOutput>(\n    opts.children,\n    cap,\n    opts.signal,\n    opts.perBudget,\n    opts.onChildResult,\n  );\n\n  const mergeStart = Date.now();\n  let merged: TOutput;\n  switch (merge.kind) {\n    case 'concat': {\n      const sep = merge.separator ?? '\\n\\n---\\n\\n';\n      const parts: string[] = [];\n      for (const r of results) {\n        if (r.status === 'completed' && r.output !== undefined) {\n          parts.push(typeof r.output === 'string' ? r.output : JSON.stringify(r.output));\n        } else if (\n          r.status === 'failed' ||\n          r.status === 'budget-exceeded' ||\n          r.status === 'cancelled'\n        ) {\n          parts.push(`[${r.status}: ${r.agentId}]`);\n        }\n      }\n      merged = parts.join(sep) as unknown as TOutput;\n      break;\n    }\n    case 'first-success': {\n      const first = results.find((r) => r.status === 'completed');\n      merged = first?.output ?? ('' as unknown as TOutput);\n      break;\n    }\n    case 'judge-merge': {\n      merged = await merge.judge(results);\n      // AG-7: the sideways-injection merge guard scores each child's\n      // source trust × contribution weight against the judge's merged\n      // output. A biased merge emits `agent.lateral-leak.detected`;\n      // 'detect-and-block' refuses the merge entirely.\n      if (opts.mergeGuard !== undefined && opts.mergeGuard.strictness !== 'off') {\n        const mergedText = typeof merged === 'string' ? merged : JSON.stringify(merged);\n        const overrides = opts.mergeGuard.sourceTrustOverrides ?? {};\n        const perChild = results.map((r, i) => {\n          const c = opts.children[i];\n          const childText =\n            r.output === undefined\n              ? ''\n              : typeof r.output === 'string'\n                ? r.output\n                : JSON.stringify(r.output);\n          return {\n            agentId: r.agentId,\n            sourceTrust: computeSourceTrust(\n              {\n                agentId: r.agentId,\n                trustClass: c?.trustClass ?? 'loopback',\n                origin: c?.origin ?? 'built-in',\n                ...(c?.historyAdjustment !== undefined\n                  ? { historyAdjustment: c.historyAdjustment }\n                  : {}),\n              },\n              overrides,\n            ),\n            contributionWeight: contributionWeight(childText, mergedText),\n          };\n        });\n        const verdict = evaluateMerge(perChild, opts.mergeGuard);\n        if (verdict.biased) {\n          opts.emit?.({\n            type: 'agent.lateral-leak.detected',\n            runId: opts.runId,\n            sessionId: opts.sessionId,\n            agentId: opts.agentId,\n            vector: 'sideways-injection',\n            severity: verdict.decision === 'block' ? 'block' : 'warn',\n            causalityChain: verdict.offendingChild === undefined ? [] : [verdict.offendingChild],\n            messageContentSha256: createHash('sha256').update(mergedText, 'utf8').digest('hex'),\n            decision:\n              verdict.decision === 'block'\n                ? 'block'\n                : verdict.decision === 'flag'\n                  ? 'flag'\n                  : 'detect',\n            detectedAtIso: new Date().toISOString(),\n          });\n          if (verdict.decision === 'block') {\n            throw new MergeBlockedError(\n              fanOutId,\n              `low-trust child '${verdict.offendingChild}' (sourceTrust ${verdict.sourceTrust?.toFixed(2)}) contributes ${(\n                (verdict.contributionWeight ?? 0) * 100\n              ).toFixed(0)}% of the merged output`,\n            );\n          }\n        }\n      }\n      break;\n    }\n    case 'custom':\n      merged = await merge.merge(results);\n      break;\n    default: {\n      const _exhaustive: never = merge;\n      void _exhaustive;\n      merged = '' as unknown as TOutput;\n    }\n  }\n  const mergeDurationMs = Date.now() - mergeStart;\n\n  const childMetadata: FanOutChildMetadata[] = results.map((r) => ({\n    agentId: r.agentId,\n    status: r.status,\n    tokensUsed: r.tokensUsed,\n    toolCallCount: r.toolCallCount,\n    durationMs: r.durationMs,\n  }));\n  const successfulChildCount = results.filter((r) => r.status === 'completed').length;\n\n  opts.emit?.({\n    type: 'agent.fanout.merged',\n    runId: opts.runId,\n    sessionId: opts.sessionId,\n    agentId: opts.agentId,\n    fanOutId,\n    childCount: opts.children.length,\n    successfulChildCount,\n    mergeStrategyKind: merge.kind,\n    mergeDurationMs,\n    childMetadata,\n  });\n\n  return {\n    fanOutId,\n    output: merged,\n    children: results,\n    mergeDurationMs,\n  };\n}\n"],"mappings":"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"}

package/dist/filters/index.d.ts

@@ -0,0 +1,137 @@
+import { HandoffFilter, HandoffInputFilterDescriptor, Sensitivity } from "@graphorin/core";
+
+//#region src/filters/index.d.ts
+
+/**
+ * A `HandoffFilter` paired with the serializable descriptor that
+ * round-trips through the JSONL session export. Authors of custom
+ * filters return one of these via `filters.custom({...})`.
+ *
+ * @stable
+ */
+interface DescribedFilter extends HandoffFilter {
+  readonly descriptor: HandoffInputFilterDescriptor;
+}
+/**
+ * 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
+ */
+declare function lastN(n?: number): DescribedFilter;
+/**
+ * Keep only the parent's system prompt and the most recent user
+ * message. Useful for simple sub-agents that only need the question.
+ *
+ * @stable
+ */
+declare function lastUser(): DescribedFilter;
+/**
+ * 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
+ */
+declare function full(): DescribedFilter;
+/**
+ * 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
+ */
+declare function summary(text: string): DescribedFilter;
+/**
+ * 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
+ */
+declare function bySensitivity(args?: {
+  readonly maxTier?: Sensitivity;
+}): DescribedFilter;
+/**
+ * Strip every `ReasoningContent` part from each message. Always
+ * applied at the handoff boundary (the `compose(...)` helper appends
+ * this filter automatically).
+ *
+ * @stable
+ */
+declare function stripReasoning(): DescribedFilter;
+/**
+ * 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
+ */
+declare function stripSensitiveOutputs(): DescribedFilter;
+/**
+ * Drop every assistant `toolCalls` array AND every `tool` message.
+ * Useful when a sub-agent should only see the textual conversation.
+ *
+ * @stable
+ */
+declare function stripToolCalls(): DescribedFilter;
+/**
+ * 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
+ */
+declare function compose(...filters: ReadonlyArray<HandoffFilter>): DescribedFilter;
+/**
+ * Wrap a caller-supplied function as a {@link DescribedFilter} with
+ * the canonical `'custom'` descriptor.
+ *
+ * @stable
+ */
+declare function custom(fn: HandoffFilter, meta?: Readonly<Record<string, unknown>>): DescribedFilter;
+/**
+ * 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
+ */
+declare function defaultHandoffFilter(): DescribedFilter;
+/**
+ * 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
+ */
+declare const FILTER_KIND_CUSTOM: HandoffInputFilterDescriptor;
+/** Aggregate module export. */
+declare const filters: {
+  lastN: typeof lastN;
+  lastUser: typeof lastUser;
+  full: typeof full;
+  summary: typeof summary;
+  bySensitivity: typeof bySensitivity;
+  stripReasoning: typeof stripReasoning;
+  stripSensitiveOutputs: typeof stripSensitiveOutputs;
+  stripToolCalls: typeof stripToolCalls;
+  compose: typeof compose;
+  custom: typeof custom;
+  defaultHandoffFilter: typeof defaultHandoffFilter;
+};
+//#endregion
+export { DescribedFilter, FILTER_KIND_CUSTOM, bySensitivity, compose, custom, defaultHandoffFilter, filters, full, lastN, lastUser, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary };
+//# sourceMappingURL=index.d.ts.map

package/dist/filters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/filters/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAgUA;AAWA;AAGA;UA1RiB,eAAA,SAAwB;uBAClB;;;;;;;;;iBAmCP,KAAA,cAAe;;;;;;;iBA0Bf,QAAA,CAAA,GAAY;;;;;;;;iBAgCZ,IAAA,CAAA,GAAQ;;;;;;;;iBAWR,OAAA,gBAAuB;;;;;;;;;;;;;;;;;iBA4BvB,aAAA;qBAAyC;IAAqB;;;;;;;;iBA0B9D,cAAA,CAAA,GAAkB;;;;;;;;;;iBAelB,qBAAA,CAAA,GAAyB;;;;;;;iBA4BzB,cAAA,CAAA,GAAkB;;;;;;;;iBA0BlB,OAAA,aAAoB,cAAc,iBAAiB;;;;;;;iBA0BnD,MAAA,KACV,sBACG,SAAS,2BACf;;;;;;;;iBAWa,oBAAA,CAAA,GAAwB;;;;;;;;cAW3B,oBAAoB;;cAGpB"}