@graphorin/agent 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @graphorin/agent
+
+## 0.1.0
+
+Initial release. See the workspace root `CHANGELOG.md` for the full
+release notes; the per-package changelog is generated by Changesets
+and tracks subsequent updates.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# @graphorin/agent
+
+> Agent runtime for the Graphorin framework.
+
+`@graphorin/agent` is the agent layer of the Graphorin framework. It
+owns the typed `model -> tool calls -> model` loop, the streaming
+event surface, durable HITL approvals, multi-agent handoffs, and
+the cross-cutting safety mechanisms (intra-loop reasoning
+preservation, agent-level model fallback, post-compaction hooks,
+per-tool model-tier hints, lateral-leak defenses).
+
+The package is **library-mode-first**: every primitive that can be
+useful from a script (`createAgent`, `RunState.toJSON / fromJSON`,
+the filter library, `evaluatorOptimizer`, `Agent.fanOut`,
+`agent.progress.write / read`) ships from the npm package without
+the optional standalone server.
+
+## Dependencies
+
+- `@graphorin/core` — typed contracts (`AgentEvent`, `RunState`,
+  `RunContext`, `Provider`, `Tool`, `StopCondition`, `HandoffFilter`,
+  `Sensitivity`, …).
+- `@graphorin/provider` — middleware composer assertion + token
+  counter dispatcher + per-provider model-tier auto-classifier.
+- `@graphorin/tools` — `ToolRegistry` + `ToolExecutor` (parallel /
+  sequential dispatch, approval flow, sandbox enforcement, inbound
+  sanitization).
+- `@graphorin/skills` — skill metadata cards, lazy body loading.
+- `@graphorin/memory` — `Memory` facade + `ContextEngine` for
+  per-step prompt assembly + auto-compaction trigger.
+- `@graphorin/sessions` — multi-agent attribution, handoff records,
+  `AgentRegistry`, audit trail.
+- `@graphorin/observability` — `Tracer`, span attributes, counter
+  receivers.
+- `@graphorin/security` — `SecretsAccessScope` for sub-agent
+  inheritance, audit chain, lateral-leak guard primitives.
+
+## Quick start
+
+```ts
+import { createAgent } from '@graphorin/agent';
+import { createProvider } from '@graphorin/provider';
+
+const agent = createAgent({
+  name: 'helpful-assistant',
+  instructions: 'You are a helpful, concise assistant.',
+  provider: createProvider({ /* ... */ }),
+});
+
+for await (const event of agent.stream('Plan a trip to Mars')) {
+  if (event.type === 'text.delta') process.stdout.write(event.delta);
+}
+```
+
+## Highlights
+
+- **Streaming-first.** Every operation returns
+  `AsyncIterable<AgentEvent<TOutput>>`. `agent.run(...)` is a thin
+  collect helper.
+- **Typed events.** The `AgentEvent<TOutput>` discriminated union
+  covers every event the runtime emits (text deltas, tool calls,
+  approvals, handoffs, compaction, fan-out, evaluator iterations,
+  progress artifacts, lateral-leak detections, model fallback
+  transitions, …). `assertNever(...)` exhaustiveness is verified at
+  compile time.
+- **Durable HITL.** `RunState.toJSON()` /
+  `RunState.fromJSON(serialized, agent)` round-trip the full run
+  state through any storage the caller picks (file, SQLite, KV, S3).
+- **Multi-agent.** `Agent.toTool({ exposeTurns, inputFilter })`
+  wraps an agent as a tool the parent agent can call. The parent's
+  abort signal, deps, and sessionId propagate into the sub-run;
+  without an `inputFilter` the sub-agent sees only the input string
+  (no parent conversation crosses the boundary), and there is no
+  secret-inheritance mechanism at this boundary at all — least
+  authority by construction.
+- **Filter library.** `filters.lastN(n)`, `filters.lastUser`,
+  `filters.summary({...})`, `filters.bySensitivity({...})`,
+  `filters.stripReasoning()`, `filters.stripSensitiveOutputs()`,
+  `filters.stripToolCalls()`, `filters.compose(...)`. Every filter
+  returns a serializable `HandoffInputFilterDescriptor` so the
+  JSONL session export can replay it byte-equal.
+- **Cancellation.** `agent.abort({ drain, onPendingApprovals })` —
+  the default hard-kills the in-flight provider stream mid-event;
+  `drain: true` lets the current step's stream finish (reach its step
+  boundary) before stopping. A mid-stream abort ends the run as
+  `'aborted'` (a cancellation), never a failed run. Pending approvals
+  can be auto-denied (`'deny'` default), held (`'hold'`), or raised as
+  an error (`'fail'`).
+- **Reasoning preservation.** Anthropic Claude tool-use loops
+  round-trip `reasoning` content parts (with opaque `meta` such as
+  `signature` / `data`) into the next provider call when the
+  effective `reasoningRetention` is not `'strip'`. The handoff
+  boundary is independent: `filters.stripReasoning()` is always
+  applied to messages forwarded to a sub-agent regardless of the
+  intra-loop policy.
+- **Agent-level model fallback.** `Agent.fallbackModels: ModelSpec[]`
+  retries the whole step against the next model on rate-limit /
+  capacity / context-length errors; `agent.model.fellback` event
+  fires per transition; per-model usage attribution lives in
+  `RunState.usage.byModel`.
+- **Post-compaction hook lifecycle.** When
+  `@graphorin/memory.contextEngine` auto-compacts the buffer, the
+  runtime fires every registered `postCompactionHooks[i]` between
+  the trim and the next `provider.stream(...)` call. Failed hooks
+  are isolated; the harness continues with the survivors.
+- **Agent-step-level fan-out.** `Agent.fanOut({ subagents,
+  mergeStrategy, perBudget, ... })` spawns N sub-agents under a
+  bounded-fanout cap (default `maxConcurrentChildren: 4`) with
+  per-child token / tool-call / duration budgets and four built-in
+  merge strategies (`'concat'`, `'first-success'`, `'judge-merge'`,
+  `'custom'`).
+- **`evaluatorOptimizer({...})`.** Generator → Evaluator iteration
+  loop with three rubric kinds (`'free-form'`, `'zod'`,
+  `'llm-judge'`) + REQUIRED iteration cap.
+- **Progress artifacts.** `agent.progress.write(content, { role,
+  seq, sensitivity, tags })` and `agent.progress.read({ runId,
+  role, sinceSeq, maxArtifacts })` persist UTF-8 text artifacts to
+  the artifact root via atomic-write `.tmp + rename` discipline for
+  cross-session continuity.
+- **Per-tool model-tier hints.** `tool({ ..., preferredModel:
+  'fast' | 'balanced' | 'smart' | ModelSpec })` declares a hint;
+  `Agent.modelTierMap` resolves the cost-tier vocabulary to
+  concrete `Provider` instances at agent warm-up; the per-step
+  planner walks the precedence ladder
+  `'prepare-step' > 'tier-map' | 'spec' > 'agent-preferred' >
+  'fallthrough-default'` once per step.
+- **Lateral-leak defense layer.** `Agent.causalityMonitor`
+  (Agentic Reference Monitor pattern), `Agent.mergeGuard` (per-child
+  trust scoring + bias detection on `'judge-merge'`; `detect-and-block`
+  refuses the merge with `MergeBlockedError`), the protocol
+  injection guard (`guardOutboundContent` — an exported helper for
+  the server boundary, not an `AgentConfig` knob), and
+  commentary-phase trace sanitization at the session-output
+  boundary compose orthogonally with the other security layers
+  (handoff input filter, outbound redaction, inbound sanitization).
+- **Inbound sanitization preamble.** Part of the context-engine
+  assemble path: with `autoAssembleContext: true` **and** memory
+  wired, when the assembled message list contains any non-trusted
+  `MessageContent` part the engine appends the locale-resolved
+  preamble fragment to the system prompt **after** the cache
+  breakpoint so the trusted-only cache prefix is not invalidated.
+  Without that opt-in the preamble (like the rest of `assemble()`)
+  does not run; the context engine is configured on the memory
+  facade (`createMemory({ contextEngine })`), not on `AgentConfig`.
+
+## Documentation
+
+The full architecture lives in the framework docs (the agent loop
+reference). The package's `CHANGELOG.md` records every change.
+
+## License
+
+MIT © Oleksiy Stepurenko. See [LICENSE](./LICENSE) for the full
+text.
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy
+Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/errors/index.d.ts

@@ -0,0 +1,170 @@
+//#region src/errors/index.d.ts
+/**
+ * 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
+ */
+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' | '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
+ */
+declare class AgentRuntimeError extends Error {
+  readonly code: AgentRuntimeErrorCode;
+  constructor(code: AgentRuntimeErrorCode, message: string, name?: string);
+}
+/**
+ * Thrown by `createAgent({...})` when the supplied options fail
+ * structural validation (missing `provider`, empty `name`, an
+ * `outputType` of kind `'text'` carrying a `schema`, ...).
+ *
+ * @stable
+ */
+declare class InvalidAgentConfigError extends AgentRuntimeError {
+  constructor(reason: string);
+}
+/**
+ * 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
+ */
+declare class InvalidPreferredModelError extends AgentRuntimeError {
+  readonly value: unknown;
+  constructor(value: unknown);
+}
+/**
+ * Thrown by `evaluatorOptimizer({...})` when `maxIterations < 1` at
+ * construction time. The helper purposely surfaces the misuse early
+ * rather than failing on the first run.
+ *
+ * @stable
+ */
+declare class EvaluatorOptimizerConfigError extends AgentRuntimeError {
+  constructor(reason: string);
+}
+/**
+ * Thrown by `runStateFromJSON(...)` when the agent name in the
+ * serialized state cannot be resolved against the supplied agent
+ * graph (renamed agent / removed handoff).
+ *
+ * @stable
+ */
+declare class AgentResolutionError extends AgentRuntimeError {
+  readonly agentId: string;
+  constructor(agentId: string);
+}
+/**
+ * Thrown by the agent loop when the model emits a tool call referring
+ * to an unregistered tool (the model hallucinated a name).
+ *
+ * @stable
+ */
+declare class ToolNotFoundError extends AgentRuntimeError {
+  readonly toolName: string;
+  constructor(toolName: string);
+}
+/**
+ * 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
+ */
+declare class ConcurrentRunError extends AgentRuntimeError {
+  constructor();
+}
+declare class MultipleHandoffsInStepError extends AgentRuntimeError {
+  readonly handoffNames: ReadonlyArray<string>;
+  constructor(handoffNames: ReadonlyArray<string>);
+}
+/**
+ * Thrown by `runStateFromJSON(...)` when the version field in the
+ * serialized state is from a future major version of the framework.
+ *
+ * @stable
+ */
+declare class RunStateVersionUnsupportedError extends AgentRuntimeError {
+  readonly version: string;
+  readonly readerVersion: string;
+  constructor(version: string, readerVersion: string);
+}
+/**
+ * Thrown by `runStateFromJSON(...)` when the supplied JSON does not
+ * shape-match the documented {@link SerializedRunState}.
+ *
+ * @stable
+ */
+declare class RunStateMalformedError extends AgentRuntimeError {
+  constructor(reason: string);
+}
+/**
+ * Thrown by `Agent.fanOut(...)` when the configured
+ * {@link MergeAgentSidewaysInjectionGuard} fires with strictness
+ * `'detect-and-block'`.
+ *
+ * @stable
+ */
+declare class MergeBlockedError extends AgentRuntimeError {
+  readonly fanOutId: string;
+  readonly reason: string;
+  constructor(fanOutId: string, reason: string);
+}
+/**
+ * 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
+ */
+declare class ProtocolInjectionRejectError extends AgentRuntimeError {
+  readonly boundary: string;
+  readonly matchedPattern: string;
+  constructor(boundary: string, matchedPattern: string);
+}
+/**
+ * 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
+ */
+declare class ProgressWriteError extends AgentRuntimeError {
+  readonly path: string;
+  constructor(path: string, cause: unknown);
+}
+/**
+ * Thrown by `createAgent({...})` when the supplied
+ * `composeProviderMiddleware` chain violates the canonical inside-out
+ * ordering (DEC-145 / ADR-039).
+ *
+ * @stable
+ */
+declare class ProviderMiddlewareOrderError extends AgentRuntimeError {
+  constructor(reason: string);
+}
+//#endregion
+export { AgentResolutionError, AgentRuntimeError, AgentRuntimeErrorCode, ConcurrentRunError, EvaluatorOptimizerConfigError, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RunStateMalformedError, RunStateVersionUnsupportedError, ToolNotFoundError };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":[],"mappings":";;AAeA;AAuBA;;;;;AAgBA;AAiBA;AAoBA;AAiBA;AAkBA;AA6BA;AAUA;AACyB,KAvJb,qBAAA,GAuJa,gBAAA,GAAA,yBAAA,GAAA,yBAAA,GAAA,oCAAA,GAAA,yBAAA,GAAA,gBAAA,GAAA,0BAAA,GAAA,2BAAA,GAAA,aAAA,GAAA,4BAAA,GAAA,uBAAA,GAAA,eAAA,GAAA,6BAAA,GAAA,+BAAA,GAAA,qBAAA,GAAA,gBAAA;;;;AAiBzB;AAqBA;AAaa,cAnLA,iBAAA,SAA0B,KAAA,CAmLA;EAsB1B,SAAA,IAAA,EAxMI,qBAwMyB;EAqB7B,WAAA,CAAA,IAAA,EA5NO,qBA4NoB,EAAA,OAAA,EAAA,MAAiB,EAAA,IAAA,CAAA,EAAA,MAAA;AA6BzD;;;;;;;;cA3Oa,uBAAA,SAAgC,iBAAA;;;;;;;;;;cAiBhC,0BAAA,SAAmC,iBAAA;;;;;;;;;;;cAoBnC,6BAAA,SAAsC,iBAAA;;;;;;;;;;cAiBtC,oBAAA,SAA6B,iBAAA;;;;;;;;;;cAkB7B,iBAAA,SAA0B,iBAAA;;;;;;;;;;;;;;;;;;;;;cA6B1B,kBAAA,SAA2B,iBAAA;;;cAU3B,2BAAA,SAAoC,iBAAA;yBACxB;4BACG;;;;;;;;cAgBf,+BAAA,SAAwC,iBAAA;;;;;;;;;;;cAqBxC,sBAAA,SAA+B,iBAAA;;;;;;;;;;cAa/B,iBAAA,SAA0B,iBAAA;;;;;;;;;;;;;cAsB1B,4BAAA,SAAqC,iBAAA;;;;;;;;;;;;cAqBrC,kBAAA,SAA2B,iBAAA;;;;;;;;;;;cA6B3B,4BAAA,SAAqC,iBAAA"}

package/dist/errors/index.js

@@ -0,0 +1,204 @@
+//#region src/errors/index.ts
+/**
+* Base class for every error thrown from `@graphorin/agent`.
+*
+* @stable
+*/
+var AgentRuntimeError = class extends Error {
+	code;
+	constructor(code, message, 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
+*/
+var InvalidAgentConfigError = class extends AgentRuntimeError {
+	constructor(reason) {
+		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
+*/
+var InvalidPreferredModelError = class extends AgentRuntimeError {
+	value;
+	constructor(value) {
+		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
+*/
+var EvaluatorOptimizerConfigError = class extends AgentRuntimeError {
+	constructor(reason) {
+		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
+*/
+var AgentResolutionError = class extends AgentRuntimeError {
+	agentId;
+	constructor(agentId) {
+		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
+*/
+var ToolNotFoundError = class extends AgentRuntimeError {
+	toolName;
+	constructor(toolName) {
+		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
+*/
+var ConcurrentRunError = class 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");
+	}
+};
+var MultipleHandoffsInStepError = class extends AgentRuntimeError {
+	handoffNames;
+	constructor(handoffNames) {
+		super("multiple-handoffs-in-step", `The model invoked multiple handoff tools in one step: ${handoffNames.join(", ")}.`, "MultipleHandoffsInStepError");
+		this.handoffNames = handoffNames;
+	}
+};
+/**
+* Thrown by `runStateFromJSON(...)` when the version field in the
+* serialized state is from a future major version of the framework.
+*
+* @stable
+*/
+var RunStateVersionUnsupportedError = class extends AgentRuntimeError {
+	version;
+	readerVersion;
+	constructor(version, readerVersion) {
+		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 {@link SerializedRunState}.
+*
+* @stable
+*/
+var RunStateMalformedError = class extends AgentRuntimeError {
+	constructor(reason) {
+		super("run-state-malformed", `Malformed RunState JSON: ${reason}.`, "RunStateMalformedError");
+	}
+};
+/**
+* Thrown by `Agent.fanOut(...)` when the configured
+* {@link MergeAgentSidewaysInjectionGuard} fires with strictness
+* `'detect-and-block'`.
+*
+* @stable
+*/
+var MergeBlockedError = class extends AgentRuntimeError {
+	fanOutId;
+	reason;
+	constructor(fanOutId, reason) {
+		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
+*/
+var ProtocolInjectionRejectError = class extends AgentRuntimeError {
+	boundary;
+	matchedPattern;
+	constructor(boundary, matchedPattern) {
+		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
+*/
+var ProgressWriteError = class extends AgentRuntimeError {
+	path;
+	constructor(path, cause) {
+		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 !== void 0) 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
+*/
+var ProviderMiddlewareOrderError = class extends AgentRuntimeError {
+	constructor(reason) {
+		super("middleware-order-violation", `Provider middleware composition violated the inside-out ordering: ${reason}.`, "ProviderMiddlewareOrderError");
+	}
+};
+
+//#endregion
+export { AgentResolutionError, AgentRuntimeError, ConcurrentRunError, EvaluatorOptimizerConfigError, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RunStateMalformedError, RunStateVersionUnsupportedError, ToolNotFoundError };
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":["/**\n * Typed error surface for `@graphorin/agent`.\n *\n * Every error class extends the base {@link AgentRuntimeError} which is\n * a thin wrapper around `Error` with a stable `code` discriminator so\n * callers can `switch` on it without parsing messages.\n *\n * @packageDocumentation\n */\n\n/**\n * Stable code discriminator surfaced on every {@link AgentRuntimeError}.\n *\n * @stable\n */\nexport type AgentRuntimeErrorCode =\n  | 'invalid-config'\n  | 'invalid-preferred-model'\n  | 'invalid-fallback-policy'\n  | 'invalid-evaluator-optimizer-config'\n  | 'agent-resolution-failed'\n  | 'tool-not-found'\n  | 'handoff-target-not-found'\n  | 'multiple-handoffs-in-step'\n  | 'run-aborted'\n  | 'middleware-order-violation'\n  | 'progress-write-failed'\n  | 'merge-blocked'\n  | 'protocol-injection-rejected'\n  | 'run-state-version-unsupported'\n  | 'run-state-malformed'\n  | 'concurrent-run';\n\n/**\n * Base class for every error thrown from `@graphorin/agent`.\n *\n * @stable\n */\nexport class AgentRuntimeError extends Error {\n  readonly code: AgentRuntimeErrorCode;\n  constructor(code: AgentRuntimeErrorCode, message: string, name = 'AgentRuntimeError') {\n    super(message);\n    this.name = name;\n    this.code = code;\n  }\n}\n\n/**\n * Thrown by `createAgent({...})` when the supplied options fail\n * structural validation (missing `provider`, empty `name`, an\n * `outputType` of kind `'text'` carrying a `schema`, ...).\n *\n * @stable\n */\nexport class InvalidAgentConfigError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super(\n      'invalid-config',\n      `Invalid createAgent({...}) options: ${reason}.`,\n      'InvalidAgentConfigError',\n    );\n  }\n}\n\n/**\n * Thrown by `createAgent({...})` when `preferredModel` carries an\n * unknown literal (any value outside the `'fast' | 'balanced' |\n * 'smart'` cost-tier vocabulary AND not a valid `ModelSpec`).\n *\n * @stable\n */\nexport class InvalidPreferredModelError extends AgentRuntimeError {\n  readonly value: unknown;\n  constructor(value: unknown) {\n    super(\n      'invalid-preferred-model',\n      `Invalid Agent.preferredModel: ${JSON.stringify(value)}. ` +\n        \"Expected 'fast' | 'balanced' | 'smart' | ModelSpec.\",\n      'InvalidPreferredModelError',\n    );\n    this.value = value;\n  }\n}\n\n/**\n * Thrown by `evaluatorOptimizer({...})` when `maxIterations < 1` at\n * construction time. The helper purposely surfaces the misuse early\n * rather than failing on the first run.\n *\n * @stable\n */\nexport class EvaluatorOptimizerConfigError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super(\n      'invalid-evaluator-optimizer-config',\n      `Invalid evaluatorOptimizer({...}) options: ${reason}.`,\n      'EvaluatorOptimizerConfigError',\n    );\n  }\n}\n\n/**\n * Thrown by `runStateFromJSON(...)` when the agent name in the\n * serialized state cannot be resolved against the supplied agent\n * graph (renamed agent / removed handoff).\n *\n * @stable\n */\nexport class AgentResolutionError extends AgentRuntimeError {\n  readonly agentId: string;\n  constructor(agentId: string) {\n    super(\n      'agent-resolution-failed',\n      `runStateFromJSON: agent '${agentId}' is not registered in the supplied graph.`,\n      'AgentResolutionError',\n    );\n    this.agentId = agentId;\n  }\n}\n\n/**\n * Thrown by the agent loop when the model emits a tool call referring\n * to an unregistered tool (the model hallucinated a name).\n *\n * @stable\n */\nexport class ToolNotFoundError extends AgentRuntimeError {\n  readonly toolName: string;\n  constructor(toolName: string) {\n    super(\n      'tool-not-found',\n      `Tool '${toolName}' is not registered on this agent.`,\n      'ToolNotFoundError',\n    );\n    this.toolName = toolName;\n  }\n}\n\n/**\n * Thrown when the model invokes more than one handoff (`transfer_to_*`)\n * tool in a single response. Per the agent-loop documentation this is\n * an error rather than a silent drop.\n *\n * @stable\n */\n/**\n * Thrown when a second `run()` / `stream()` starts while another run is\n * in flight on the same `Agent` instance (AG-11). The public surface\n * (`steer` / `followUp` / `abort` / `compact`) addresses \"the run\"\n * without a run handle, so overlapping runs would share the abort\n * controller, steer queue, and executor bridge — start the second run\n * on its own `createAgent(...)` instance instead.\n *\n * @stable\n */\nexport class ConcurrentRunError extends AgentRuntimeError {\n  constructor() {\n    super(\n      'concurrent-run',\n      '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.',\n      'ConcurrentRunError',\n    );\n  }\n}\n\nexport class MultipleHandoffsInStepError extends AgentRuntimeError {\n  readonly handoffNames: ReadonlyArray<string>;\n  constructor(handoffNames: ReadonlyArray<string>) {\n    super(\n      'multiple-handoffs-in-step',\n      `The model invoked multiple handoff tools in one step: ${handoffNames.join(', ')}.`,\n      'MultipleHandoffsInStepError',\n    );\n    this.handoffNames = handoffNames;\n  }\n}\n\n/**\n * Thrown by `runStateFromJSON(...)` when the version field in the\n * serialized state is from a future major version of the framework.\n *\n * @stable\n */\nexport class RunStateVersionUnsupportedError extends AgentRuntimeError {\n  readonly version: string;\n  readonly readerVersion: string;\n  constructor(version: string, readerVersion: string) {\n    super(\n      'run-state-version-unsupported',\n      `RunState version '${version}' is newer than reader '${readerVersion}'. ` +\n        'Upgrade @graphorin/agent to load this state.',\n      'RunStateVersionUnsupportedError',\n    );\n    this.version = version;\n    this.readerVersion = readerVersion;\n  }\n}\n\n/**\n * Thrown by `runStateFromJSON(...)` when the supplied JSON does not\n * shape-match the documented {@link SerializedRunState}.\n *\n * @stable\n */\nexport class RunStateMalformedError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super('run-state-malformed', `Malformed RunState JSON: ${reason}.`, 'RunStateMalformedError');\n  }\n}\n\n/**\n * Thrown by `Agent.fanOut(...)` when the configured\n * {@link MergeAgentSidewaysInjectionGuard} fires with strictness\n * `'detect-and-block'`.\n *\n * @stable\n */\nexport class MergeBlockedError extends AgentRuntimeError {\n  readonly fanOutId: string;\n  readonly reason: string;\n  constructor(fanOutId: string, reason: string) {\n    super(\n      'merge-blocked',\n      `Agent.fanOut('${fanOutId}') merge blocked by MergeAgentSidewaysInjectionGuard: ${reason}.`,\n      'MergeBlockedError',\n    );\n    this.fanOutId = fanOutId;\n    this.reason = reason;\n  }\n}\n\n/**\n * Thrown by the protocol-injection guard when the operator selected\n * the strictest deployment posture (`escapePolicy: 'reject'`) and a\n * tool result body carries control characters at the corresponding\n * outbound boundary.\n *\n * @stable\n */\nexport class ProtocolInjectionRejectError extends AgentRuntimeError {\n  readonly boundary: string;\n  readonly matchedPattern: string;\n  constructor(boundary: string, matchedPattern: string) {\n    super(\n      'protocol-injection-rejected',\n      `Protocol injection guard rejected output at the '${boundary}' boundary (matched ${matchedPattern}).`,\n      'ProtocolInjectionRejectError',\n    );\n    this.boundary = boundary;\n    this.matchedPattern = matchedPattern;\n  }\n}\n\n/**\n * Thrown by `agent.progress.write(...)` when the atomic write fails\n * (disk full, permission denied, ...). The partial `.tmp` file is\n * unlinked before the error propagates.\n *\n * @stable\n */\nexport class ProgressWriteError extends AgentRuntimeError {\n  readonly path: string;\n  constructor(path: string, cause: unknown) {\n    const message = cause instanceof Error ? cause.message : String(cause);\n    super(\n      'progress-write-failed',\n      `agent.progress.write('${path}') failed: ${message}.`,\n      'ProgressWriteError',\n    );\n    this.path = path;\n    if (cause !== undefined) {\n      // Preserve the underlying cause for diagnostics.\n      Object.defineProperty(this, 'cause', {\n        value: cause,\n        enumerable: false,\n        configurable: true,\n        writable: true,\n      });\n    }\n  }\n}\n\n/**\n * Thrown by `createAgent({...})` when the supplied\n * `composeProviderMiddleware` chain violates the canonical inside-out\n * ordering (DEC-145 / ADR-039).\n *\n * @stable\n */\nexport class ProviderMiddlewareOrderError extends AgentRuntimeError {\n  constructor(reason: string) {\n    super(\n      'middleware-order-violation',\n      `Provider middleware composition violated the inside-out ordering: ${reason}.`,\n      'ProviderMiddlewareOrderError',\n    );\n  }\n}\n"],"mappings":";;;;;;AAsCA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,AAAS;CACT,YAAY,MAA6B,SAAiB,OAAO,qBAAqB;AACpF,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,OAAO;;;;;;;;;;AAWhB,IAAa,0BAAb,cAA6C,kBAAkB;CAC7D,YAAY,QAAgB;AAC1B,QACE,kBACA,uCAAuC,OAAO,IAC9C,0BACD;;;;;;;;;;AAWL,IAAa,6BAAb,cAAgD,kBAAkB;CAChE,AAAS;CACT,YAAY,OAAgB;AAC1B,QACE,2BACA,iCAAiC,KAAK,UAAU,MAAM,CAAC,wDAEvD,6BACD;AACD,OAAK,QAAQ;;;;;;;;;;AAWjB,IAAa,gCAAb,cAAmD,kBAAkB;CACnE,YAAY,QAAgB;AAC1B,QACE,sCACA,8CAA8C,OAAO,IACrD,gCACD;;;;;;;;;;AAWL,IAAa,uBAAb,cAA0C,kBAAkB;CAC1D,AAAS;CACT,YAAY,SAAiB;AAC3B,QACE,2BACA,4BAA4B,QAAQ,6CACpC,uBACD;AACD,OAAK,UAAU;;;;;;;;;AAUnB,IAAa,oBAAb,cAAuC,kBAAkB;CACvD,AAAS;CACT,YAAY,UAAkB;AAC5B,QACE,kBACA,SAAS,SAAS,qCAClB,oBACD;AACD,OAAK,WAAW;;;;;;;;;;;;;;;;;;;;AAqBpB,IAAa,qBAAb,cAAwC,kBAAkB;CACxD,cAAc;AACZ,QACE,kBACA,qKACA,qBACD;;;AAIL,IAAa,8BAAb,cAAiD,kBAAkB;CACjE,AAAS;CACT,YAAY,cAAqC;AAC/C,QACE,6BACA,yDAAyD,aAAa,KAAK,KAAK,CAAC,IACjF,8BACD;AACD,OAAK,eAAe;;;;;;;;;AAUxB,IAAa,kCAAb,cAAqD,kBAAkB;CACrE,AAAS;CACT,AAAS;CACT,YAAY,SAAiB,eAAuB;AAClD,QACE,iCACA,qBAAqB,QAAQ,0BAA0B,cAAc,kDAErE,kCACD;AACD,OAAK,UAAU;AACf,OAAK,gBAAgB;;;;;;;;;AAUzB,IAAa,yBAAb,cAA4C,kBAAkB;CAC5D,YAAY,QAAgB;AAC1B,QAAM,uBAAuB,4BAA4B,OAAO,IAAI,yBAAyB;;;;;;;;;;AAWjG,IAAa,oBAAb,cAAuC,kBAAkB;CACvD,AAAS;CACT,AAAS;CACT,YAAY,UAAkB,QAAgB;AAC5C,QACE,iBACA,iBAAiB,SAAS,wDAAwD,OAAO,IACzF,oBACD;AACD,OAAK,WAAW;AAChB,OAAK,SAAS;;;;;;;;;;;AAYlB,IAAa,+BAAb,cAAkD,kBAAkB;CAClE,AAAS;CACT,AAAS;CACT,YAAY,UAAkB,gBAAwB;AACpD,QACE,+BACA,oDAAoD,SAAS,sBAAsB,eAAe,KAClG,+BACD;AACD,OAAK,WAAW;AAChB,OAAK,iBAAiB;;;;;;;;;;AAW1B,IAAa,qBAAb,cAAwC,kBAAkB;CACxD,AAAS;CACT,YAAY,MAAc,OAAgB;EACxC,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AACtE,QACE,yBACA,yBAAyB,KAAK,aAAa,QAAQ,IACnD,qBACD;AACD,OAAK,OAAO;AACZ,MAAI,UAAU,OAEZ,QAAO,eAAe,MAAM,SAAS;GACnC,OAAO;GACP,YAAY;GACZ,cAAc;GACd,UAAU;GACX,CAAC;;;;;;;;;;AAYR,IAAa,+BAAb,cAAkD,kBAAkB;CAClE,YAAY,QAAgB;AAC1B,QACE,8BACA,qEAAqE,OAAO,IAC5E,+BACD"}