@graphorin/agent 0.6.0 → 0.7.0

package/dist/tooling/policy.js

@@ -1,3 +1,4 @@
+import { isUntrustedTrustClass } from "@graphorin/security/dataflow";
 import { buildRuleOfTwoPolicy, evaluateToolArgumentPolicy } from "@graphorin/security/policy";
 
 //#region src/tooling/policy.ts
@@ -32,6 +33,7 @@ function buildToolArgumentPolicy(toolPolicy, ruleOfTwo) {
 		toolName: input.toolName,
 		sideEffectClass: input.sideEffectClass,
 		sensitive: input.sensitive,
+		untrustedSource: isUntrustedTrustClass(input.trustClass),
 		args: input.args
 	}) };
 	return compiled?.capability !== void 0 ? {

package/dist/tooling/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","names":["merged: ToolArgumentPolicy","guard: ToolArgumentPolicyGuard"],"sources":["../../src/tooling/policy.ts"],"sourcesContent":["/**\n * Agent-side adapter for the D4 tool-argument policy (Progent) and the\n * Rule-of-Two capability preset. Compiles `AgentConfig.toolPolicy` /\n * `AgentConfig.ruleOfTwo` into the structural\n * {@link ToolArgumentPolicyGuard} the tool executor consumes plus a\n * capability floor the run loop folds into its single-writer gate.\n *\n * The pure decision engine lives in `@graphorin/security/policy`; this\n * module is the thin binding, mirroring `tooling/dataflow.ts`.\n *\n * @packageDocumentation\n */\n\nimport {\n  buildRuleOfTwoPolicy,\n  evaluateToolArgumentPolicy,\n  type PolicySideEffectClass,\n  type RuleOfTwoProfile,\n  type ToolArgumentPolicy,\n} from '@graphorin/security/policy';\nimport type { ToolArgumentPolicyGuard } from '@graphorin/tools/executor';\n\nexport type { RuleOfTwoProfile, ToolArgumentPolicy } from '@graphorin/security/policy';\n\n/**\n * Compile the agent's opt-in tool-argument policy + Rule-of-Two profile\n * into a single guard. `ruleOfTwo` is compiled first (yielding a base\n * policy + optional read-only floor); an explicit `toolPolicy` is\n * appended so its rules compose - a forbid in either always wins\n * (forbid-before-allow). Returns `{ guard: undefined }` when neither is\n * configured (zero overhead on the default path).\n */\nexport function buildToolArgumentPolicy(\n  toolPolicy: ToolArgumentPolicy | undefined,\n  ruleOfTwo: RuleOfTwoProfile | undefined,\n): { readonly guard: ToolArgumentPolicyGuard | undefined; readonly capabilityFloor?: 'read-only' } {\n  if (toolPolicy === undefined && ruleOfTwo === undefined) {\n    return { guard: undefined };\n  }\n\n  const compiled = ruleOfTwo !== undefined ? buildRuleOfTwoPolicy(ruleOfTwo) : undefined;\n  const merged: ToolArgumentPolicy = {\n    rules: [...(compiled?.policy.rules ?? []), ...(toolPolicy?.rules ?? [])],\n    defaultDenySensitive:\n      (compiled?.policy.defaultDenySensitive ?? false) ||\n      (toolPolicy?.defaultDenySensitive ?? false),\n  };\n\n  const guard: ToolArgumentPolicyGuard = {\n    evaluate: (input) =>\n      evaluateToolArgumentPolicy(merged, {\n        toolName: input.toolName,\n        sideEffectClass: input.sideEffectClass as PolicySideEffectClass,\n        sensitive: input.sensitive,\n        args: input.args,\n      }),\n  };\n\n  return compiled?.capability !== undefined\n    ? { guard, capabilityFloor: compiled.capability }\n    : { guard };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,wBACd,YACA,WACiG;AACjG,KAAI,eAAe,UAAa,cAAc,OAC5C,QAAO,EAAE,OAAO,QAAW;CAG7B,MAAM,WAAW,cAAc,SAAY,qBAAqB,UAAU,GAAG;CAC7E,MAAMA,SAA6B;EACjC,OAAO,CAAC,GAAI,UAAU,OAAO,SAAS,EAAE,EAAG,GAAI,YAAY,SAAS,EAAE,CAAE;EACxE,uBACG,UAAU,OAAO,wBAAwB,WACzC,YAAY,wBAAwB;EACxC;CAED,MAAMC,QAAiC,EACrC,WAAW,UACT,2BAA2B,QAAQ;EACjC,UAAU,MAAM;EAChB,iBAAiB,MAAM;EACvB,WAAW,MAAM;EACjB,MAAM,MAAM;EACb,CAAC,EACL;AAED,QAAO,UAAU,eAAe,SAC5B;EAAE;EAAO,iBAAiB,SAAS;EAAY,GAC/C,EAAE,OAAO"}
+{"version":3,"file":"policy.js","names":["merged: ToolArgumentPolicy","guard: ToolArgumentPolicyGuard"],"sources":["../../src/tooling/policy.ts"],"sourcesContent":["/**\n * Agent-side adapter for the D4 tool-argument policy (Progent) and the\n * Rule-of-Two capability preset. Compiles `AgentConfig.toolPolicy` /\n * `AgentConfig.ruleOfTwo` into the structural\n * {@link ToolArgumentPolicyGuard} the tool executor consumes plus a\n * capability floor the run loop folds into its single-writer gate.\n *\n * The pure decision engine lives in `@graphorin/security/policy`; this\n * module is the thin binding, mirroring `tooling/dataflow.ts`.\n *\n * @packageDocumentation\n */\n\nimport { isUntrustedTrustClass } from '@graphorin/security/dataflow';\nimport {\n  buildRuleOfTwoPolicy,\n  evaluateToolArgumentPolicy,\n  type PolicySideEffectClass,\n  type RuleOfTwoProfile,\n  type ToolArgumentPolicy,\n} from '@graphorin/security/policy';\nimport type { ToolArgumentPolicyGuard } from '@graphorin/tools/executor';\n\nexport type { RuleOfTwoProfile, ToolArgumentPolicy } from '@graphorin/security/policy';\n\n/**\n * Compile the agent's opt-in tool-argument policy + Rule-of-Two profile\n * into a single guard. `ruleOfTwo` is compiled first (yielding a base\n * policy + optional read-only floor); an explicit `toolPolicy` is\n * appended so its rules compose - a forbid in either always wins\n * (forbid-before-allow). Returns `{ guard: undefined }` when neither is\n * configured (zero overhead on the default path).\n */\nexport function buildToolArgumentPolicy(\n  toolPolicy: ToolArgumentPolicy | undefined,\n  ruleOfTwo: RuleOfTwoProfile | undefined,\n): { readonly guard: ToolArgumentPolicyGuard | undefined; readonly capabilityFloor?: 'read-only' } {\n  if (toolPolicy === undefined && ruleOfTwo === undefined) {\n    return { guard: undefined };\n  }\n\n  const compiled = ruleOfTwo !== undefined ? buildRuleOfTwoPolicy(ruleOfTwo) : undefined;\n  const merged: ToolArgumentPolicy = {\n    rules: [...(compiled?.policy.rules ?? []), ...(toolPolicy?.rules ?? [])],\n    defaultDenySensitive:\n      (compiled?.policy.defaultDenySensitive ?? false) ||\n      (toolPolicy?.defaultDenySensitive ?? false),\n  };\n\n  const guard: ToolArgumentPolicyGuard = {\n    evaluate: (input) =>\n      evaluateToolArgumentPolicy(merged, {\n        toolName: input.toolName,\n        sideEffectClass: input.sideEffectClass as PolicySideEffectClass,\n        sensitive: input.sensitive,\n        // W-101: derived with the same taxonomy the taint engine uses,\n        // so the Rule-of-Two untrustedInput leg and dataflow policy can\n        // never disagree about what \"untrusted source\" means.\n        untrustedSource: isUntrustedTrustClass(input.trustClass),\n        args: input.args,\n      }),\n  };\n\n  return compiled?.capability !== undefined\n    ? { guard, capabilityFloor: compiled.capability }\n    : { guard };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,wBACd,YACA,WACiG;AACjG,KAAI,eAAe,UAAa,cAAc,OAC5C,QAAO,EAAE,OAAO,QAAW;CAG7B,MAAM,WAAW,cAAc,SAAY,qBAAqB,UAAU,GAAG;CAC7E,MAAMA,SAA6B;EACjC,OAAO,CAAC,GAAI,UAAU,OAAO,SAAS,EAAE,EAAG,GAAI,YAAY,SAAS,EAAE,CAAE;EACxE,uBACG,UAAU,OAAO,wBAAwB,WACzC,YAAY,wBAAwB;EACxC;CAED,MAAMC,QAAiC,EACrC,WAAW,UACT,2BAA2B,QAAQ;EACjC,UAAU,MAAM;EAChB,iBAAiB,MAAM;EACvB,WAAW,MAAM;EAIjB,iBAAiB,sBAAsB,MAAM,WAAW;EACxD,MAAM,MAAM;EACb,CAAC,EACL;AAED,QAAO,UAAU,eAAe,SAC5B;EAAE;EAAO,iBAAiB,SAAS;EAAY,GAC/C,EAAE,OAAO"}

package/dist/types.d.ts

@@ -4,13 +4,13 @@ import { ChildResult, FanOutOptions, FanOutResult, MergeStrategy, PerChildBudget
 import { CausalityMonitorConfig } from "./lateral-leak/causality-monitor.js";
 import { ProgressIO, ProgressReadOptions, ProgressWriteOptions } from "./progress/index.js";
 import * as _graphorin_core0 from "@graphorin/core";
-import { AgentEvent, AgentResult, CheckpointStore, HandoffFilter, Message, ModelHint, ModelSpec, ProgressArtifactRef, Provider, ProviderCachePolicy, ReasoningRetention, RunContext, RunState, Sensitivity, StopCondition, Tool, ToolChoice, Tracer } from "@graphorin/core";
-import { InputGuardrail, OutputGuardrail } from "@graphorin/security/guardrails";
+import { AISpan, AgentEvent, AgentResult, AnyTool, CheckpointStore, HandoffFilter, Message, ModelHint, ModelSpec, ProgressArtifactRef, Provider, ProviderCachePolicy, ReasoningRetention, RunContext, RunState, Sensitivity, StopCondition, Tool, ToolChoice, Tracer } from "@graphorin/core";
+import { Memory, PostCompactionHook } from "@graphorin/memory";
 import { ResultReader } from "@graphorin/tools/result";
 import { DataFlowPolicyConfig } from "@graphorin/security/dataflow";
+import { InputGuardrail, OutputGuardrail } from "@graphorin/security/guardrails";
 import { RuleOfTwoProfile, ToolArgumentPolicy } from "@graphorin/security/policy";
 import { ToolRegistry } from "@graphorin/tools/registry";
-import { Memory, PostCompactionHook } from "@graphorin/memory";
 
 //#region src/types.d.ts
 
@@ -59,7 +59,7 @@ type PrepareStepHook<TDeps = unknown> = (ctx: RunContext<TDeps>) => Promise<Prep
 /** @stable */
 interface PrepareStepOverrides<TDeps = unknown> {
   readonly provider?: Provider;
-  readonly tools?: ReadonlyArray<Tool<unknown, unknown, TDeps>>;
+  readonly tools?: ReadonlyArray<AnyTool<TDeps>>;
   readonly toolChoice?: ToolChoice;
   readonly temperature?: number;
   readonly maxTokens?: number;
@@ -92,7 +92,18 @@ interface SkillsRegistryLike {
 type HandoffEntry<TDeps = unknown> = Agent<TDeps, any> | {
   readonly target: Agent<TDeps, any>;
   readonly inputFilter?: HandoffFilter;
+  /** W-036: which child events forward into the parent stream. */
+  readonly forwardEvents?: SubagentForwardPolicy;
 };
+/**
+ * W-036: sub-agent event-forwarding policy. `'lifecycle'` (default)
+ * forwards tool execution/approval, guardrail, lateral-leak,
+ * compaction and error events - never the high-frequency text deltas;
+ * `'all'` forwards everything; `'none'` keeps the child a black box.
+ *
+ * @stable
+ */
+type SubagentForwardPolicy = 'none' | 'lifecycle' | 'all';
 /**
  * The full options object accepted by {@link createAgent}.
  *
@@ -109,12 +120,12 @@ interface AgentConfig<TDeps = unknown, TOutput = string> {
    */
   readonly instructions: string | ((ctx: RunContext<TDeps>) => string | Promise<string>);
   readonly provider: Provider;
-  readonly tools?: ReadonlyArray<Tool<unknown, unknown, TDeps>>;
+  readonly tools?: ReadonlyArray<AnyTool<TDeps>>;
   readonly skills?: SkillsRegistryLike;
   readonly memory?: Memory;
   /**
    * Opt in to building the per-run system prompt from the memory
-   * {@link ContextEngine} (CE-1). When `true` **and** `memory` is wired, the
+   * `ContextEngine` (CE-1). When `true` **and** `memory` is wired, the
    * runtime calls `memory.contextEngine.assemble(...)` once at run start: the
    * agent's `instructions` become Layer 2 and the engine prepends the memory
    * base and appends working blocks, procedural rules, skill cards, the
@@ -282,6 +293,17 @@ interface AgentConfig<TDeps = unknown, TOutput = string> {
   readonly recordProviderResponses?: boolean;
   readonly tracer?: Tracer;
   readonly checkpointStore?: CheckpointStore;
+  /**
+   * What happens to the run's checkpoint thread when the run reaches a
+   * terminal status (W-005). `'keep'` (default) preserves the current
+   * behaviour: checkpoints survive for post-hoc debugging and
+   * process-restart resume. `'delete-on-terminal'` best-effort deletes
+   * the thread after `completed` / `failed` runs; `awaiting_approval`
+   * and `aborted` runs always keep theirs (the thread IS the resume
+   * state). Requires {@link AgentConfig.checkpointStore}.
+   * @default 'keep'
+   */
+  readonly checkpointPolicy?: 'keep' | 'delete-on-terminal';
   readonly sensitivity?: Sensitivity;
   /**
    * Agent-default capability restriction (D2). `'read-only'` builds a
@@ -336,8 +358,9 @@ type VerifierResult = {
  * to the model (as a user message prefixed `[verifier:<id>]`) and the
  * loop continues for up to `AgentConfig.maxVerifierRounds` extra rounds.
  *
- * A verifier that THROWS is treated as passed (and logged): a buggy
- * verifier must never take down a run.
+ * A verifier that THROWS is treated as passed (the `verifier.result`
+ * event still fires with `ok: true`): a buggy verifier must never
+ * take down a run.
  *
  * @stable
  */
@@ -362,6 +385,16 @@ interface ApprovalDecision {
   readonly toolCallId: string;
   readonly granted: boolean;
   readonly reason?: string;
+  /**
+   * W-001: echo of `ToolApproval.subRunToolCallId` for approvals that
+   * belong to a parked sub-agent run. Operators read the pair
+   * (`toolCallId`, `subRunToolCallId`) from `RunState.pendingApprovals`
+   * and return BOTH fields; decisions match on the composite key, so
+   * child-local toolCallId collisions across two parked children never
+   * cross-apply. A decision without this field applies only to the
+   * parent's own (unparked) approvals.
+   */
+  readonly subRunToolCallId?: string;
 }
 /**
  * Resume directive accepted by `agent.run(input | RunState, { directive })`.
@@ -400,6 +433,15 @@ interface AgentCallOptions<TDeps> {
    * resuming a suspended run.
    */
   readonly capability?: AgentCapability;
+  /**
+   * W-036: parent span for this run's `agent.run` root span - a
+   * multi-agent invocation forms ONE trace tree (the child's run span
+   * parents under the caller's step/tool span). The runtime supplies it
+   * automatically for handoffs and `toTool` sub-agents. Like
+   * `capability`, it is NOT persisted in `RunState`: re-supply on
+   * resume when stitching matters.
+   */
+  readonly parentSpan?: AISpan;
 }
 /**
  * Run-level capability restriction (D2 - the single-writer constraint
@@ -433,6 +475,8 @@ interface AgentToToolOptions {
    * boundary at all).
    */
   readonly inputFilter?: HandoffFilter;
+  /** W-036: which child events forward into the parent stream. */
+  readonly forwardEvents?: SubagentForwardPolicy;
   /**
    * Run the sub-agent under a restricted capability (D2): a
    * `'read-only'` worker cannot execute or advertise writer tools. The
@@ -475,11 +519,17 @@ interface AbortOptions {
   readonly drain?: boolean;
   /**
    * What to do with approvals that were already requested but not
-   * resolved at abort time.
+   * resolved at abort time (W-038).
    *
-   * - `'deny'` (default) - auto-deny pending approvals.
-   * - `'hold'`            - keep the approvals on `RunState.pendingApprovals`.
-   * - `'fail'`            - reject the run with `RunError(code: 'run-aborted')`.
+   * - `'deny'` (default) - auto-deny pending approvals; each drained
+   *   toolCallId gets a matching tool message so the transcript keeps
+   *   no dangling `tool_use`, and the run ends `'aborted'`.
+   * - `'hold'` - keep the approvals on `RunState.pendingApprovals` of
+   *   the `'aborted'` state; such a state re-enters the loop only via
+   *   an explicit resume directive.
+   * - `'fail'` - reject the run with `RunError(code: 'run-aborted')`
+   *   ONLY when approvals are actually pending; an abort with an empty
+   *   queue ends `'aborted'`, never `'failed'`.
    */
   readonly onPendingApprovals?: 'deny' | 'hold' | 'fail';
 }
@@ -580,5 +630,5 @@ interface Agent<TDeps = unknown, TOutput = string> {
   readonly registry?: ToolRegistry;
 }
 //#endregion
-export { AbortOptions, Agent, AgentCallOptions, AgentCapability, AgentConfig, AgentInput, AgentToToolOptions, CompactOptions, CompactionApiResult, OutputSpec, PostCompactionHook$1 as PostCompactionHook, PrepareStepHook, PrepareStepOverrides, ResponseVerifier, ResumeDirective, SkillsRegistryLike, VerifierResult };
+export { AbortOptions, Agent, AgentCallOptions, AgentCapability, AgentConfig, AgentInput, AgentToToolOptions, CompactOptions, CompactionApiResult, HandoffEntry, OutputSpec, PostCompactionHook$1 as PostCompactionHook, PrepareStepHook, PrepareStepOverrides, ResponseVerifier, ResumeDirective, SkillsRegistryLike, VerifierResult };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/agent",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Agent runtime for the Graphorin framework: createAgent({...}) factory, the typed model -> tool calls -> model loop, the AgentEvent<TOutput> discriminated event stream, steering / followUp queues, durable HITL approvals via runStateToJSON / runStateFromJSON, multi-agent handoffs (Agent.toTool, filter library, secrets isolation), agent-level model fallback chain, intra-loop reasoning preservation, post-compaction hook lifecycle, agent-step-level fan-out (Agent.fanOut + evaluatorOptimizer + progress artifacts), per-tool model-tier hint resolution, lateral-leak defense layer (CausalityMonitor + MergeAgentSidewaysInjectionGuard + protocol-guard), inbound-content sanitization preamble injection, and AbortSignal-aware hard-kill / drain cancellation. Created and maintained by Oleksiy Stepurenko.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -33,8 +33,9 @@
     "causality-monitor"
   ],
   "type": "module",
+  "sideEffects": false,
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -42,64 +43,63 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./factory": {
       "types": "./dist/factory.d.ts",
-      "import": "./dist/factory.js"
+      "default": "./dist/factory.js"
     },
     "./run-state": {
       "types": "./dist/run-state/index.d.ts",
-      "import": "./dist/run-state/index.js"
+      "default": "./dist/run-state/index.js"
     },
     "./filters": {
       "types": "./dist/filters/index.d.ts",
-      "import": "./dist/filters/index.js"
+      "default": "./dist/filters/index.js"
     },
     "./fallback": {
       "types": "./dist/fallback/index.d.ts",
-      "import": "./dist/fallback/index.js"
+      "default": "./dist/fallback/index.js"
     },
     "./preferred-model": {
       "types": "./dist/preferred-model/index.d.ts",
-      "import": "./dist/preferred-model/index.js"
+      "default": "./dist/preferred-model/index.js"
     },
     "./fanout": {
       "types": "./dist/fanout/index.d.ts",
-      "import": "./dist/fanout/index.js"
+      "default": "./dist/fanout/index.js"
     },
     "./evaluator-optimizer": {
       "types": "./dist/evaluator-optimizer/index.d.ts",
-      "import": "./dist/evaluator-optimizer/index.js"
+      "default": "./dist/evaluator-optimizer/index.js"
     },
     "./progress": {
       "types": "./dist/progress/index.d.ts",
-      "import": "./dist/progress/index.js"
+      "default": "./dist/progress/index.js"
     },
     "./lateral-leak": {
       "types": "./dist/lateral-leak/index.d.ts",
-      "import": "./dist/lateral-leak/index.js"
+      "default": "./dist/lateral-leak/index.js"
     },
     "./errors": {
       "types": "./dist/errors/index.d.ts",
-      "import": "./dist/errors/index.js"
+      "default": "./dist/errors/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@graphorin/core": "0.6.0",
-    "@graphorin/memory": "0.6.0",
-    "@graphorin/observability": "0.6.0",
-    "@graphorin/provider": "0.6.0",
-    "@graphorin/security": "0.6.0",
-    "@graphorin/skills": "0.6.0",
-    "@graphorin/tools": "0.6.0"
+    "@graphorin/core": "0.7.0",
+    "@graphorin/memory": "0.7.0",
+    "@graphorin/security": "0.7.0",
+    "@graphorin/skills": "0.7.0",
+    "@graphorin/tools": "0.7.0"
   },
   "publishConfig": {
     "access": "public",

package/src/errors/index.ts

@@ -0,0 +1,320 @@
+/**
+ * Typed error surface for `@graphorin/agent`.
+ *
+ * Every error class extends the base {@link AgentRuntimeError} which is
+ * a thin wrapper around `Error` with a stable `code` discriminator so
+ * callers can `switch` on it without parsing messages.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Stable code discriminator surfaced on every {@link AgentRuntimeError}.
+ *
+ * @stable
+ */
+export type AgentRuntimeErrorCode =
+  | 'invalid-config'
+  | 'invalid-preferred-model'
+  | 'invalid-fallback-policy'
+  | 'invalid-evaluator-optimizer-config'
+  | 'agent-resolution-failed'
+  | 'tool-not-found'
+  | 'handoff-target-not-found'
+  | 'multiple-handoffs-in-step'
+  | 'sub-run-resume-target-not-found'
+  | 'run-aborted'
+  | 'middleware-order-violation'
+  | 'progress-write-failed'
+  | 'merge-blocked'
+  | 'protocol-injection-rejected'
+  | 'run-state-version-unsupported'
+  | 'run-state-malformed'
+  | 'concurrent-run';
+
+/**
+ * Base class for every error thrown from `@graphorin/agent`.
+ *
+ * @stable
+ */
+export class AgentRuntimeError extends Error {
+  readonly code: AgentRuntimeErrorCode;
+  constructor(code: AgentRuntimeErrorCode, message: string, name = 'AgentRuntimeError') {
+    super(message);
+    this.name = name;
+    this.code = code;
+  }
+}
+
+/**
+ * Thrown by `createAgent({...})` when the supplied options fail
+ * structural validation (missing `provider`, empty `name`, an
+ * `outputType` of kind `'text'` carrying a `schema`, ...).
+ *
+ * @stable
+ */
+export class InvalidAgentConfigError extends AgentRuntimeError {
+  constructor(reason: string) {
+    super(
+      'invalid-config',
+      `Invalid createAgent({...}) options: ${reason}.`,
+      'InvalidAgentConfigError',
+    );
+  }
+}
+
+/**
+ * Thrown by `createAgent({...})` when `preferredModel` carries an
+ * unknown literal (any value outside the `'fast' | 'balanced' |
+ * 'smart'` cost-tier vocabulary AND not a valid `ModelSpec`).
+ *
+ * @stable
+ */
+export class InvalidPreferredModelError extends AgentRuntimeError {
+  readonly value: unknown;
+  constructor(value: unknown) {
+    super(
+      'invalid-preferred-model',
+      `Invalid Agent.preferredModel: ${JSON.stringify(value)}. ` +
+        "Expected 'fast' | 'balanced' | 'smart' | ModelSpec.",
+      'InvalidPreferredModelError',
+    );
+    this.value = value;
+  }
+}
+
+/**
+ * Thrown by `evaluatorOptimizer({...})` when `maxIterations < 1` at
+ * construction time. The helper purposely surfaces the misuse early
+ * rather than failing on the first run.
+ *
+ * @stable
+ */
+export class EvaluatorOptimizerConfigError extends AgentRuntimeError {
+  constructor(reason: string) {
+    super(
+      'invalid-evaluator-optimizer-config',
+      `Invalid evaluatorOptimizer({...}) options: ${reason}.`,
+      'EvaluatorOptimizerConfigError',
+    );
+  }
+}
+
+/**
+ * Thrown by `runStateFromJSON(...)` when the agent name in the
+ * serialized state cannot be resolved against the supplied agent
+ * graph (renamed agent / removed handoff).
+ *
+ * @stable
+ */
+export class AgentResolutionError extends AgentRuntimeError {
+  readonly agentId: string;
+  constructor(agentId: string) {
+    super(
+      'agent-resolution-failed',
+      `runStateFromJSON: agent '${agentId}' is not registered in the supplied graph.`,
+      'AgentResolutionError',
+    );
+    this.agentId = agentId;
+  }
+}
+
+/**
+ * Thrown by the agent loop when the model emits a tool call referring
+ * to an unregistered tool (the model hallucinated a name).
+ *
+ * @stable
+ */
+export class ToolNotFoundError extends AgentRuntimeError {
+  readonly toolName: string;
+  constructor(toolName: string) {
+    super(
+      'tool-not-found',
+      `Tool '${toolName}' is not registered on this agent.`,
+      'ToolNotFoundError',
+    );
+    this.toolName = toolName;
+  }
+}
+
+/**
+ * Thrown when the model invokes more than one handoff (`transfer_to_*`)
+ * tool in a single response. Per the agent-loop documentation this is
+ * an error rather than a silent drop.
+ *
+ * @stable
+ */
+/**
+ * Thrown when a second `run()` / `stream()` starts while another run is
+ * in flight on the same `Agent` instance (AG-11). The public surface
+ * (`steer` / `followUp` / `abort` / `compact`) addresses "the run"
+ * without a run handle, so overlapping runs would share the abort
+ * controller, steer queue, and executor bridge - start the second run
+ * on its own `createAgent(...)` instance instead.
+ *
+ * @stable
+ */
+export class ConcurrentRunError extends AgentRuntimeError {
+  constructor() {
+    super(
+      'concurrent-run',
+      'This Agent instance already has a run in flight. One run per instance: await the active run (or abort it), or create a separate agent instance for parallel work.',
+      'ConcurrentRunError',
+    );
+  }
+}
+
+export class MultipleHandoffsInStepError extends AgentRuntimeError {
+  readonly handoffNames: ReadonlyArray<string>;
+  constructor(handoffNames: ReadonlyArray<string>) {
+    super(
+      'multiple-handoffs-in-step',
+      `The model invoked multiple handoff tools in one step: ${handoffNames.join(', ')}.`,
+      'MultipleHandoffsInStepError',
+    );
+    this.handoffNames = handoffNames;
+  }
+}
+
+/**
+ * Thrown when a resume directive routes a decision into a parked
+ * sub-agent run (W-001) but the resuming agent instance cannot resolve
+ * the target: the parked toolName matches neither a configured handoff
+ * target nor a `toTool` sub-agent tool. Resume a parked sub-run on the
+ * SAME parent instance (or an identically-configured one).
+ *
+ * @stable
+ */
+export class SubAgentResumeTargetNotFoundError extends AgentRuntimeError {
+  readonly toolName: string;
+  constructor(toolName: string, detail: string) {
+    super(
+      'sub-run-resume-target-not-found',
+      `Cannot resume parked sub-agent run for tool '${toolName}': ${detail}. Parked sub-runs resume only on a parent instance configured with the same handoff target or toTool sub-agent tool.`,
+      'SubAgentResumeTargetNotFoundError',
+    );
+    this.toolName = toolName;
+  }
+}
+
+/**
+ * Thrown by `runStateFromJSON(...)` when the version field in the
+ * serialized state is from a future major version of the framework.
+ *
+ * @stable
+ */
+export class RunStateVersionUnsupportedError extends AgentRuntimeError {
+  readonly version: string;
+  readonly readerVersion: string;
+  constructor(version: string, readerVersion: string) {
+    super(
+      'run-state-version-unsupported',
+      `RunState version '${version}' is newer than reader '${readerVersion}'. ` +
+        'Upgrade @graphorin/agent to load this state.',
+      'RunStateVersionUnsupportedError',
+    );
+    this.version = version;
+    this.readerVersion = readerVersion;
+  }
+}
+
+/**
+ * Thrown by `runStateFromJSON(...)` when the supplied JSON does not
+ * shape-match the documented `SerializedRunState`.
+ *
+ * @stable
+ */
+export class RunStateMalformedError extends AgentRuntimeError {
+  constructor(reason: string) {
+    super('run-state-malformed', `Malformed RunState JSON: ${reason}.`, 'RunStateMalformedError');
+  }
+}
+
+/**
+ * Thrown by `Agent.fanOut(...)` when the configured
+ * `MergeAgentSidewaysInjectionGuard` fires with strictness
+ * `'detect-and-block'`.
+ *
+ * @stable
+ */
+export class MergeBlockedError extends AgentRuntimeError {
+  readonly fanOutId: string;
+  readonly reason: string;
+  constructor(fanOutId: string, reason: string) {
+    super(
+      'merge-blocked',
+      `Agent.fanOut('${fanOutId}') merge blocked by MergeAgentSidewaysInjectionGuard: ${reason}.`,
+      'MergeBlockedError',
+    );
+    this.fanOutId = fanOutId;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Thrown by the protocol-injection guard when the operator selected
+ * the strictest deployment posture (`escapePolicy: 'reject'`) and a
+ * tool result body carries control characters at the corresponding
+ * outbound boundary.
+ *
+ * @stable
+ */
+export class ProtocolInjectionRejectError extends AgentRuntimeError {
+  readonly boundary: string;
+  readonly matchedPattern: string;
+  constructor(boundary: string, matchedPattern: string) {
+    super(
+      'protocol-injection-rejected',
+      `Protocol injection guard rejected output at the '${boundary}' boundary (matched ${matchedPattern}).`,
+      'ProtocolInjectionRejectError',
+    );
+    this.boundary = boundary;
+    this.matchedPattern = matchedPattern;
+  }
+}
+
+/**
+ * Thrown by `agent.progress.write(...)` when the atomic write fails
+ * (disk full, permission denied, ...). The partial `.tmp` file is
+ * unlinked before the error propagates.
+ *
+ * @stable
+ */
+export class ProgressWriteError extends AgentRuntimeError {
+  readonly path: string;
+  constructor(path: string, cause: unknown) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    super(
+      'progress-write-failed',
+      `agent.progress.write('${path}') failed: ${message}.`,
+      'ProgressWriteError',
+    );
+    this.path = path;
+    if (cause !== undefined) {
+      // Preserve the underlying cause for diagnostics.
+      Object.defineProperty(this, 'cause', {
+        value: cause,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+      });
+    }
+  }
+}
+
+/**
+ * Thrown by `createAgent({...})` when the supplied
+ * `composeProviderMiddleware` chain violates the canonical inside-out
+ * ordering (DEC-145 / ADR-039).
+ *
+ * @stable
+ */
+export class ProviderMiddlewareOrderError extends AgentRuntimeError {
+  constructor(reason: string) {
+    super(
+      'middleware-order-violation',
+      `Provider middleware composition violated the inside-out ordering: ${reason}.`,
+      'ProviderMiddlewareOrderError',
+    );
+  }
+}