@graphorin/agent 0.6.0 → 0.7.0

package/src/filters/index.ts

@@ -0,0 +1,347 @@
+/**
+ * Handoff filter library - a small set of pure, composable functions
+ * that take the parent agent's message history and return a filtered
+ * subset suitable for forwarding to a child agent.
+ *
+ * Every filter pairs a `HandoffFilter` runtime function with a
+ * serializable {@link HandoffInputFilterDescriptor} so the JSONL
+ * session export (`@graphorin/sessions`) can replay the filter stack
+ * even after the runtime implementations evolve.
+ *
+ * Reasoning content is **always** stripped at the handoff boundary -
+ * `filters.compose(...)` guarantees `stripReasoning()` runs last so a
+ * caller-supplied filter cannot accidentally forward reasoning to a
+ * child agent. This is the confidentiality + token-economy default
+ * documented in the agent-loop reference.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  HandoffFilter,
+  HandoffInputFilterDescriptor,
+  Message,
+  Sensitivity,
+} from '@graphorin/core';
+import { SENSITIVITY_ORDER } from '@graphorin/core';
+
+const SENSITIVITY_RANK: Record<Sensitivity, number> = {
+  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: Sensitivity, maxTier: Sensitivity): boolean {
+  return SENSITIVITY_RANK[record] <= SENSITIVITY_RANK[maxTier];
+}
+
+void SENSITIVITY_ORDER;
+
+/**
+ * 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
+ */
+export interface DescribedFilter extends HandoffFilter {
+  readonly descriptor: HandoffInputFilterDescriptor;
+}
+
+function makeFilter(fn: HandoffFilter, descriptor: HandoffInputFilterDescriptor): DescribedFilter {
+  const wrapped = ((history: readonly Message[]): readonly Message[] =>
+    fn(history)) as DescribedFilter;
+  Object.defineProperty(wrapped, 'descriptor', { value: descriptor, enumerable: true });
+  return wrapped;
+}
+
+function isReasoningPart(part: unknown): boolean {
+  if (typeof part !== 'object' || part === null) return false;
+  const t = (part as { readonly type?: unknown }).type;
+  return t === 'reasoning';
+}
+
+function stripReasoningFromMessage(msg: Message): Message {
+  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
+ */
+export function lastN(n = 10): DescribedFilter {
+  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: Message[] = [];
+      for (const msg of history) {
+        if (msg.role === 'system') {
+          out.push(msg);
+        }
+      }
+      const nonSystem: Message[] = 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
+ */
+export function lastUser(): DescribedFilter {
+  return makeFilter(
+    (history) => {
+      const out: Message[] = [];
+      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
+ */
+export function full(): DescribedFilter {
+  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
+ */
+export function summary(text: string): DescribedFilter {
+  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
+ */
+export function bySensitivity(args: { readonly maxTier?: Sensitivity } = {}): DescribedFilter {
+  const maxTier: Sensitivity = args.maxTier ?? 'public';
+  return makeFilter(
+    (history) => {
+      const out: Message[] = [];
+      for (const msg of history) {
+        const content = msg.role === 'system' ? msg.content : msg.content;
+        const text = typeof content === 'string' ? content : JSON.stringify(content);
+        if (text.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
+ */
+export function stripReasoning(): DescribedFilter {
+  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
+ */
+export function stripSensitiveOutputs(): DescribedFilter {
+  return makeFilter(
+    (history) => {
+      const out: Message[] = [];
+      let stripped = 0;
+      for (const msg of history) {
+        if (msg.role === 'tool') {
+          const text = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+          if (text.includes('[REDACTED:')) {
+            stripped += 1;
+            continue;
+          }
+        }
+        out.push(msg);
+      }
+      void stripped;
+      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
+ */
+export function stripToolCalls(): DescribedFilter {
+  return makeFilter(
+    (history) => {
+      const out: Message[] = [];
+      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
+ */
+export function compose(...filters: ReadonlyArray<HandoffFilter>): DescribedFilter {
+  const stripper = stripReasoning();
+  const ordered: ReadonlyArray<HandoffFilter> = [...filters, stripper];
+  const descriptors: HandoffInputFilterDescriptor[] = filters.map((f) => {
+    const desc = (f as DescribedFilter).descriptor;
+    return desc ?? { kind: 'custom' };
+  });
+  descriptors.push(stripper.descriptor);
+  return makeFilter(
+    (history) => {
+      let current: readonly Message[] = 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
+ */
+export function custom(
+  fn: HandoffFilter,
+  meta?: Readonly<Record<string, unknown>>,
+): DescribedFilter {
+  return makeFilter(fn, meta !== undefined ? { 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
+ */
+export function defaultHandoffFilter(): DescribedFilter {
+  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
+ */
+export const FILTER_KIND_CUSTOM: HandoffInputFilterDescriptor = { kind: 'custom' };
+
+/** Aggregate module export. */
+export const filters = {
+  lastN,
+  lastUser,
+  full,
+  summary,
+  bySensitivity,
+  stripReasoning,
+  stripSensitiveOutputs,
+  stripToolCalls,
+  compose,
+  custom,
+  defaultHandoffFilter,
+};

package/src/index.ts

@@ -0,0 +1,180 @@
+/**
+ * `@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, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+// AG-2 / SDF-4: the canonical guardrail contract lives in
+// `@graphorin/security`; re-exported here for config ergonomics.
+export type {
+  GuardrailContext,
+  GuardrailDefinition,
+  GuardrailResult,
+  InputGuardrail,
+  OutputGuardrail,
+} from '@graphorin/security/guardrails';
+export {
+  AgentResolutionError,
+  AgentRuntimeError,
+  type AgentRuntimeErrorCode,
+  EvaluatorOptimizerConfigError,
+  InvalidAgentConfigError,
+  InvalidPreferredModelError,
+  MergeBlockedError,
+  MultipleHandoffsInStepError,
+  ProgressWriteError,
+  ProtocolInjectionRejectError,
+  ProviderMiddlewareOrderError,
+  RunStateMalformedError,
+  RunStateVersionUnsupportedError,
+  SubAgentResumeTargetNotFoundError,
+  ToolNotFoundError,
+} from './errors/index.js';
+export {
+  type EvaluatorCallable,
+  type EvaluatorOptimizerOptions,
+  type EvaluatorOptimizerOutcome,
+  type EvaluatorOutcome,
+  evaluatorOptimizer,
+  type GeneratorCallable,
+  type Rubric,
+} from './evaluator-optimizer/index.js';
+export { createAgent } from './factory.js';
+export {
+  type AgentFallbackEligibility,
+  type AgentFallbackPolicy,
+  type AgentFallbackReason,
+  isAgentFallbackEligible,
+} from './fallback/index.js';
+export {
+  type ChildResult,
+  type FanOutOptions,
+  type FanOutResult,
+  type MergeStrategy,
+  type PerChildBudget,
+  runFanOut,
+} from './fanout/index.js';
+export {
+  bySensitivity,
+  compose,
+  custom,
+  type DescribedFilter,
+  defaultHandoffFilter,
+  FILTER_KIND_CUSTOM,
+  filters,
+  full,
+  lastN,
+  lastUser,
+  stripReasoning,
+  stripSensitiveOutputs,
+  stripToolCalls,
+  summary,
+} from './filters/index.js';
+export {
+  CausalityMonitor,
+  type CausalityMonitorCheck,
+  type CausalityMonitorConfig,
+  type CausalityMonitorStrictness,
+  type ChildTrustInput,
+  type ContentOriginKind,
+  computeSourceTrust,
+  DEFAULT_DENIAL_PATTERNS,
+  DEFAULT_MAX_CHAIN_DEPTH,
+  evaluateMerge,
+  type GuardOutcome,
+  guardOutboundContent,
+  type MergeBiasDecision,
+  type MergeGuardConfig,
+  type ProtocolBoundary,
+  type ProtocolEscapePolicy,
+  type ProtocolGuardConfig,
+  resolvePolicy,
+  type TrustClass,
+} from './lateral-leak/index.js';
+export {
+  type PreferredModelResolution,
+  pickTopTierAcrossTools,
+  type ResolvePreferredModelInput,
+  resolvePreferredModel,
+} from './preferred-model/index.js';
+export {
+  createProgressIO,
+  type ProgressIO,
+  type ProgressIOConfig,
+  type ProgressReadOptions,
+  type ProgressWriteOptions,
+} from './progress/index.js';
+export {
+  addModelUsage,
+  aggregateUsageFromByModel,
+  completedToolCallsFromState,
+  createInitialRunState,
+  deserializeRunState,
+  RUN_STATE_SCHEMA_MAJOR_SUPPORTED,
+  RUN_STATE_SCHEMA_VERSION,
+  runStateFromJSON,
+  runStateToJSON,
+  type SerializedPendingSubRun,
+  type SerializedRunState,
+  type SerializeRunStateOptions,
+  serializeRunState,
+} from './run-state/index.js';
+export {
+  getSubAgentToolRefs,
+  SUBAGENT_TOOL,
+  type SubAgentFoldTaint,
+  type SubAgentToolRefs,
+} from './runtime/agent-to-tool.js';
+export { foldChildRunUsage } from './runtime/messages.js';
+export {
+  createReplayProvider,
+  type ReplayProviderOptions,
+} from './testing/replay-provider.js';
+export type {
+  AbortOptions,
+  Agent,
+  AgentCallOptions,
+  AgentCapability,
+  AgentConfig,
+  AgentInput,
+  AgentToToolOptions,
+  CompactionApiResult,
+  CompactOptions,
+  HandoffEntry,
+  OutputSpec,
+  PostCompactionHook,
+  PrepareStepHook,
+  PrepareStepOverrides,
+  ResponseVerifier,
+  ResumeDirective,
+  SkillsRegistryLike,
+  VerifierResult,
+} from './types.js';

package/src/internal/ids.ts

@@ -0,0 +1,46 @@
+/**
+ * Tiny id helpers used by the agent runtime. URL-safe Base32 alphabet,
+ * monotonic timestamp prefix to keep ids loosely sortable.
+ *
+ * @packageDocumentation
+ */
+
+import { randomBytes } from 'node:crypto';
+
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+function pad(value: string, width: number): string {
+  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(): string {
+  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) & 0x1f;
+    out += ALPHABET[idx];
+  }
+  return out;
+}
+
+/** Generate a fresh, sortable, URL-safe identifier. */
+export function newId(prefix?: string): string {
+  const ts = pad(Date.now().toString(32).toUpperCase(), 9);
+  const id = `${ts}${randomTail()}`;
+  return prefix ? `${prefix}_${id}` : id;
+}

package/src/internal/usage-accumulator.ts

@@ -0,0 +1,90 @@
+/**
+ * Minimal {@link UsageAccumulator} implementation used by the agent
+ * runtime when the consumer does not pass a custom one through
+ * `RunContext.usage`. Tracks per-model breakdown and a running
+ * aggregate.
+ *
+ * @packageDocumentation
+ */
+
+import type { ModelUsage, Usage, UsageAccumulator, UsageSnapshot } from '@graphorin/core';
+
+export class InMemoryUsageAccumulator implements UsageAccumulator {
+  #aggregate: Usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+  readonly #byModel = new Map<string, ModelUsage>();
+
+  get total(): Usage {
+    return this.#aggregate;
+  }
+
+  get byModel(): ReadonlyMap<string, ModelUsage> {
+    return this.#byModel;
+  }
+
+  add(modelId: string, usage: Usage): void {
+    const prev = this.#byModel.get(modelId);
+    if (prev === undefined) {
+      this.#byModel.set(modelId, {
+        modelId,
+        promptTokens: usage.promptTokens,
+        completionTokens: usage.completionTokens,
+        totalTokens: usage.totalTokens,
+        callCount: 1,
+        ...(usage.reasoningTokens !== undefined ? { reasoningTokens: usage.reasoningTokens } : {}),
+        ...(usage.cachedReadTokens !== undefined
+          ? { cachedReadTokens: usage.cachedReadTokens }
+          : {}),
+        ...(usage.cacheWriteTokens !== undefined
+          ? { cacheWriteTokens: usage.cacheWriteTokens }
+          : {}),
+        ...(usage.cost !== undefined ? { cost: usage.cost } : {}),
+      });
+    } else {
+      const merged: ModelUsage = {
+        modelId,
+        promptTokens: prev.promptTokens + usage.promptTokens,
+        completionTokens: prev.completionTokens + usage.completionTokens,
+        totalTokens: prev.totalTokens + usage.totalTokens,
+        callCount: prev.callCount + 1,
+        ...sumOptional('reasoningTokens', prev.reasoningTokens, usage.reasoningTokens),
+        ...sumOptional('cachedReadTokens', prev.cachedReadTokens, usage.cachedReadTokens),
+        ...sumOptional('cacheWriteTokens', prev.cacheWriteTokens, usage.cacheWriteTokens),
+      };
+      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,
+      ...sumOptional('reasoningTokens', this.#aggregate.reasoningTokens, usage.reasoningTokens),
+      ...sumOptional('cachedReadTokens', this.#aggregate.cachedReadTokens, usage.cachedReadTokens),
+      ...sumOptional('cacheWriteTokens', this.#aggregate.cacheWriteTokens, usage.cacheWriteTokens),
+    };
+  }
+
+  reset(): void {
+    this.#aggregate = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    this.#byModel.clear();
+  }
+
+  snapshot(): UsageSnapshot {
+    return {
+      total: { ...this.#aggregate },
+      byModel: Array.from(this.#byModel.values()).map((m) => ({ ...m })),
+    };
+  }
+}
+
+/**
+ * Sum an optional token field: present in the output only when at least
+ * one side carries it (so a run that never saw the field keeps the same
+ * serialized shape as before the field existed).
+ */
+function sumOptional<K extends string>(
+  key: K,
+  a: number | undefined,
+  b: number | undefined,
+): Partial<Record<K, number>> {
+  if (a === undefined && b === undefined) return {};
+  return { [key]: (a ?? 0) + (b ?? 0) } as Partial<Record<K, number>>;
+}