@agen-ai/agent-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trevor Nichols
+
+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,139 @@
+# `@agen-ai/agent-runtime`
+
+`@agen-ai/agent-runtime` is the process-local service-provider interface for coding-agent
+implementations. It preserves a small ownership chain: a driver parses host configuration and
+materializes an instance; the instance owns one opaque ID, technical capabilities, an adapter,
+readiness, and disposal; the adapter opens provider-native sessions; each returned session owns
+its binding and conversation-local operations.
+
+The runtime depends only on `@agen-ai/agent-protocol`. It has no concept of tenants, SaaS
+workspaces, assigned users, database rows, persistence sequence, visibility, billing, host boots,
+leases, or storage policy. A host must authorize and select an instance before calling this SPI.
+
+## Entrypoints
+
+- `@agen-ai/agent-runtime` exports the public driver, instance, adapter, session, output,
+  readiness, bounded-evidence, artifact-candidate, and registry APIs.
+- `@agen-ai/agent-runtime/testing` exports the deterministic fake provider and reusable
+  conformance runner.
+
+## Lifecycle and ownership
+
+1. Define an `AgentProviderDriver` with `defineAgentProviderDriver`.
+2. Give caller-owned instance definitions to `createAgentProviderRegistry`.
+3. Select a materialized instance by opaque `instanceId`.
+4. Create, resume, or branch a provider session through its adapter.
+5. Consume each `runTurn` or `resolveRequest` output stream incrementally. Neutral `AgentEvent`
+   output carries bounded provider source evidence atomically. A `request.opened` output may also
+   carry separately bounded, non-truncated provider request context for continuation; lifecycle,
+   authentication, artifact, and standalone diagnostic evidence remain separate output variants.
+   Evidence reports an exact truncation reason. `originalDataBytes` is `null` when a structural
+   collection, depth, object-key, cycle, accessor, unsupported-value, or inspectability constraint
+   prevents honest measurement of the original provider payload.
+6. Close sessions idempotently, then dispose the instance or registry.
+
+Instance IDs never repeat in session calls. `workingDirectory` is resolved by the host and is not
+an authorization credential. Create and branch implementations must invoke `onBindingCreated`
+exactly once before returning the matching session. Capability-dependent operations use explicit
+`supported`/`unsupported` discriminants, and the runtime rejects handlers that disagree with the
+instance capability declaration.
+
+The host should serialize mutating operations for a given session. Separate session objects may
+run concurrently, so provider implementations must isolate their conversation-local state.
+`runTurn` and `resolveRequest` both preserve consumer backpressure: the provider does not resume
+until the consumer requests the next output. Each stream must end at a completed turn or exactly
+one newly pending request. If a consumer abandons a stream, a provider throws, or either stream
+ends before that stable boundary, the validated session becomes unusable and must be closed rather
+than retried. The validated `runTurn` input may observe `onProviderExecutionStarted`; validation
+invokes it exactly at candidate-port delegation, after runtime prechecks pass, and never forwards it
+to the candidate adapter. A delegated mutating operation that throws or returns an invalid result
+has the same effect. Pre-aborted operations fail with `AbortError`; close and disposal must be safe
+to call repeatedly. An accepted interruption of an already-waiting turn does not prove that the
+turn terminalized; unless the result also carries a terminal event, the validated session becomes
+unusable and must be closed and rematerialized. A close failure makes the session unusable while
+leaving close itself retryable.
+
+When `capabilities.turns.steer` is true, the session exposes `steering.steerTurn`. Steering accepts
+the existing turn ID plus the same canonical `parts` and optional `summary` used to start a turn.
+It does not create or own an output stream: model output continues on the original `runTurn`
+iterator. The receipt is exactly `delivered`, `rejected` with a bounded neutral error, or
+`delivery_uncertain` with a bounded neutral error. A provider must use uncertainty when delivery
+may have started but its authoritative acknowledgement was lost; callers cannot safely replay that
+result. The validated runtime preserves pre-delegation validation and abort errors unchanged, while
+provider-delegated steering failures throw `AgentProviderDelegatedOperationError` with the original
+cause and explicit started-execution evidence so a host can retire the unusable session. Platform
+scheduling and provider-native queue modes are intentionally outside this SPI.
+
+## Minimal driver
+
+```ts
+import {
+  defineAgentProviderDriver,
+  type MaterializedAgentProviderInstance,
+} from "@agen-ai/agent-runtime";
+import {
+  parseAgentInstanceId,
+  parseAgentProviderKey,
+} from "@agen-ai/agent-protocol";
+
+const providerKey = parseAgentProviderKey("third-party-provider");
+
+export const driver = defineAgentProviderDriver({
+  providerKey,
+  supportsMultipleInstances: true,
+  parseConfiguration(input) {
+    if (input === null || typeof input !== "object")
+      throw new TypeError("Invalid config.");
+    return input;
+  },
+  createInstance({ instanceId }): MaterializedAgentProviderInstance {
+    // Construct capabilities, adapter, readiness, and disposal here.
+    throw new Error(`Implement ${parseAgentInstanceId(instanceId)}.`);
+  },
+});
+```
+
+Use the `/testing` conformance runner for lifecycle, binding, turn-ordering, live steering and
+interruption, interaction results, capability ports, cancellation, close, and disposal checks.
+Registry publication and provider package discovery are intentionally outside this package.
+
+## Errors and cancellation
+
+The runtime distinguishes programmer/contract failures from provider failures:
+
+- `AgentProviderContractError` reports a stable `code` when an adapter contradicts its declared
+  capabilities, emits invalid output, violates turn/request ordering, or returns a mismatched
+  binding.
+- `AgentProviderRegistryError` reports stable registry/materialization/disposal codes and retains
+  provider/instance correlation when available.
+- `AgentProviderConfigurationError` wraps driver configuration rejection without exposing product
+  configuration policy.
+- malformed primitive input may raise `TypeError` or `RangeError`; an aborted operation preserves
+  an `AbortError`-named reason.
+
+Provider-native exceptions should be normalized or safely wrapped at the provider boundary. Do
+not attach credentials, raw prompts, product identities, or unbounded output to public errors.
+
+## Conformance and release
+
+Every external driver should run `runAgentProviderConformance` from
+`@agen-ai/agent-runtime/testing`. The deterministic suite exercises duplicate-instance rejection,
+instance identity, capabilities, readiness, create/resume/branch, binding callbacks, abort,
+turn/request ordering, request resolution, steering, interruption, configuration, idempotent
+close, and idempotent disposal. Unsupported operations must remain explicit discriminants and
+must not expose handlers.
+
+The package is at `0.1.0` while the public SPI is being proven with external adapters. Minor
+releases may include breaking changes during this beta period, and those changes will be called out
+in the release notes.
+
+The current version tuple is Agent Protocol V6, private host V14/catalog V8, and Workspaces event V8.
+The runtime package version remains independent of Agent Protocol V6.
+
+Run the clean packed-consumer proof before any release:
+
+From the public repository root, run `pnpm check`.
+
+It installs tarballs into a temporary project outside the workspace, typechecks every documented
+entrypoint, runs the fake provider and parser flow, and removes the temporary directory. It never
+publishes or accesses release credentials.

package/dist/adapterValidation.d.ts

@@ -0,0 +1,4 @@
+import { type AgentCapabilities } from "@agen-ai/agent-protocol";
+import type { AgentProviderAdapter } from "./sessions.js";
+export declare function validateAgentProviderAdapter(capabilityInput: AgentCapabilities, adapter: AgentProviderAdapter): AgentProviderAdapter;
+//# sourceMappingURL=adapterValidation.d.ts.map

package/dist/adapterValidation.js

@@ -0,0 +1,242 @@
+import path from "node:path";
+import {
+  parseAgentCapabilities,
+  parseAgentIsoDateTime,
+  parseAgentSessionOpenInput
+} from "@agen-ai/agent-protocol";
+import {
+  assertAgentSessionConfigurationSupported
+} from "./configurationValidation.js";
+import { throwAgentProviderContractError } from "./contractErrors.js";
+import {
+  parseAgentProviderTechnicalId,
+  throwIfAgentOperationAborted
+} from "./foundation.js";
+import { containsAgentControlCharacter } from "./internal/controlCharacters.js";
+import {
+  validateAgentProviderOperationResult,
+  validateAgentProviderOutputForContext
+} from "./outputValidation.js";
+import {
+  closeRejectedAgentProviderSession,
+  openIdentityCreatingAgentProviderSession,
+  validateAgentProviderSession
+} from "./sessionValidation.js";
+function parseWorkingDirectory(value) {
+  if (value.length < 1 || value.length > 4096 || !path.isAbsolute(value) || path.normalize(value) !== value || containsAgentControlCharacter(value)) {
+    throw new TypeError(
+      "Provider workingDirectory must be a canonical absolute path."
+    );
+  }
+  return value;
+}
+function assertAuthenticationOutputKind(providerKey, output) {
+  if (["authentication", "lifecycle", "evidence"].includes(output.kind)) {
+    return;
+  }
+  throwAgentProviderContractError(
+    providerKey,
+    "output_capability_mismatch",
+    "Authentication may emit only authentication, lifecycle, or evidence output."
+  );
+}
+function validateAgentProviderAdapter(capabilityInput, adapter) {
+  const capabilities = parseAgentCapabilities(capabilityInput);
+  if (adapter === null || typeof adapter !== "object" || typeof adapter.createSession !== "function" || adapter.resumption === null || typeof adapter.resumption !== "object" || !["supported", "unsupported"].includes(adapter.resumption.kind) || adapter.resumption.kind === "supported" && typeof adapter.resumption.resumeSession !== "function" || adapter.branching === null || typeof adapter.branching !== "object" || !["through_turn", "unsupported"].includes(adapter.branching.kind) || adapter.branching.kind === "through_turn" && typeof adapter.branching.branchSession !== "function" || adapter.authentication === null || typeof adapter.authentication !== "object" || !["supported", "unsupported"].includes(adapter.authentication.kind) || adapter.authentication.kind === "supported" && (typeof adapter.authentication.start !== "function" || typeof adapter.authentication.cancel !== "function")) {
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "invalid_adapter",
+      `Provider ${capabilities.providerKey} returned an incomplete adapter.`
+    );
+  }
+  if (adapter.resumption.kind === "supported" !== capabilities.sessions.resume || adapter.branching.kind !== capabilities.sessions.branch.kind || adapter.authentication.kind !== capabilities.authentication.kind) {
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "capability_port_mismatch",
+      `Provider ${capabilities.providerKey} adapter ports do not match its capabilities.`
+    );
+  }
+  const declaredResumption = adapter.resumption;
+  const resumption = declaredResumption.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    resumeSession: async (resumeInput) => {
+      throwIfAgentOperationAborted(resumeInput.signal);
+      const parsed = parseAgentSessionOpenInput({
+        operation: "resume",
+        sessionId: resumeInput.sessionId,
+        binding: resumeInput.binding,
+        configuration: resumeInput.configuration
+      });
+      if (parsed.operation !== "resume") {
+        throw new TypeError("Expected a resume session input.");
+      }
+      assertAgentSessionConfigurationSupported(
+        capabilities,
+        parsed.configuration
+      );
+      const workingDirectory = parseWorkingDirectory(
+        resumeInput.workingDirectory
+      );
+      const binding = parsed.binding;
+      const candidate = await declaredResumption.resumeSession({
+        sessionId: parsed.sessionId,
+        workingDirectory,
+        binding,
+        configuration: parsed.configuration,
+        ...resumeInput.signal === void 0 ? {} : { signal: resumeInput.signal }
+      });
+      try {
+        return validateAgentProviderSession({
+          capabilities,
+          sessionId: parsed.sessionId,
+          candidate,
+          expectedBinding: binding
+        });
+      } catch (error) {
+        return closeRejectedAgentProviderSession(candidate, error);
+      }
+    }
+  });
+  const declaredBranching = adapter.branching;
+  const branching = declaredBranching.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "through_turn",
+    branchSession: async (branchInput) => {
+      throwIfAgentOperationAborted(branchInput.signal);
+      const parsed = parseAgentSessionOpenInput({
+        operation: "branch",
+        sessionId: branchInput.sessionId,
+        source: branchInput.source,
+        configuration: branchInput.configuration
+      });
+      if (parsed.operation !== "branch") {
+        throw new TypeError("Expected a branch session input.");
+      }
+      assertAgentSessionConfigurationSupported(
+        capabilities,
+        parsed.configuration
+      );
+      const workingDirectory = parseWorkingDirectory(
+        branchInput.workingDirectory
+      );
+      const sourceBinding = parsed.source.binding;
+      return openIdentityCreatingAgentProviderSession({
+        capabilities,
+        sessionId: parsed.sessionId,
+        observer: branchInput.onBindingCreated,
+        sourceBinding,
+        open: (observer) => declaredBranching.branchSession({
+          sessionId: parsed.sessionId,
+          workingDirectory,
+          source: parsed.source,
+          configuration: parsed.configuration,
+          onBindingCreated: observer,
+          ...branchInput.signal === void 0 ? {} : { signal: branchInput.signal }
+        })
+      });
+    }
+  });
+  const declaredAuthentication = adapter.authentication;
+  const authenticationFlows = capabilities.authentication.kind === "supported" ? capabilities.authentication.flows : [];
+  const authentication = declaredAuthentication.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
+    kind: "supported",
+    start: async function* (authInput) {
+      throwIfAgentOperationAborted(authInput.signal);
+      const attemptId = parseAgentProviderTechnicalId(
+        authInput.attemptId,
+        "authentication attemptId"
+      );
+      if (!authenticationFlows.includes(authInput.flow)) {
+        throwAgentProviderContractError(
+          capabilities.providerKey,
+          "input_capability_mismatch",
+          "Agent authentication flow is not declared by provider capabilities."
+        );
+      }
+      const deadlineAt = authInput.deadlineAt === void 0 ? void 0 : parseAgentIsoDateTime(authInput.deadlineAt);
+      for await (const candidate of declaredAuthentication.start({
+        attemptId,
+        flow: authInput.flow,
+        ...deadlineAt === void 0 ? {} : { deadlineAt },
+        ...authInput.signal === void 0 ? {} : { signal: authInput.signal }
+      })) {
+        const output = validateAgentProviderOutputForContext(candidate, {
+          capabilities,
+          providerKey: capabilities.providerKey,
+          authenticationAttemptId: attemptId
+        });
+        assertAuthenticationOutputKind(capabilities.providerKey, output);
+        yield output;
+      }
+    },
+    cancel: async (authInput) => {
+      throwIfAgentOperationAborted(authInput.signal);
+      const attemptId = parseAgentProviderTechnicalId(
+        authInput.attemptId,
+        "authentication attemptId"
+      );
+      const providerLoginId = authInput.providerLoginId === void 0 ? void 0 : parseAgentProviderTechnicalId(
+        authInput.providerLoginId,
+        "providerLoginId"
+      );
+      if (authInput.reason !== void 0 && !["user_requested", "timeout", "shutdown", "other"].includes(
+        authInput.reason
+      )) {
+        throw new TypeError(
+          "Agent authentication cancel reason is unsupported."
+        );
+      }
+      const result = validateAgentProviderOperationResult(
+        await declaredAuthentication.cancel({
+          attemptId,
+          ...providerLoginId === void 0 ? {} : { providerLoginId },
+          ...authInput.reason === void 0 ? {} : { reason: authInput.reason },
+          ...authInput.signal === void 0 ? {} : { signal: authInput.signal }
+        }),
+        {
+          capabilities,
+          providerKey: capabilities.providerKey,
+          authenticationAttemptId: attemptId
+        }
+      );
+      for (const output of result.outputs ?? []) {
+        assertAuthenticationOutputKind(capabilities.providerKey, output);
+      }
+      return result;
+    }
+  });
+  return Object.freeze({
+    createSession: async (createInput) => {
+      throwIfAgentOperationAborted(createInput.signal);
+      const parsed = parseAgentSessionOpenInput({
+        operation: "create",
+        sessionId: createInput.sessionId,
+        configuration: createInput.configuration
+      });
+      assertAgentSessionConfigurationSupported(
+        capabilities,
+        parsed.configuration
+      );
+      const workingDirectory = parseWorkingDirectory(
+        createInput.workingDirectory
+      );
+      return openIdentityCreatingAgentProviderSession({
+        capabilities,
+        sessionId: parsed.sessionId,
+        observer: createInput.onBindingCreated,
+        open: (observer) => adapter.createSession({
+          sessionId: parsed.sessionId,
+          workingDirectory,
+          configuration: parsed.configuration,
+          onBindingCreated: observer,
+          ...createInput.signal === void 0 ? {} : { signal: createInput.signal }
+        })
+      });
+    },
+    resumption,
+    branching,
+    authentication
+  });
+}
+export {
+  validateAgentProviderAdapter
+};

package/dist/artifacts.d.ts

@@ -0,0 +1,28 @@
+import { type AgentArtifactDescriptor } from "@agen-ai/agent-protocol";
+export declare const AGENT_ARTIFACT_CANDIDATE_MAX_BYTES: number;
+export type AgentArtifactDeliveryRequirement = "best_effort" | "required_before_reference";
+export type AgentArtifactCandidateSource = Readonly<{
+    kind: "bytes";
+    bytes: Uint8Array;
+}> | Readonly<{
+    kind: "file";
+    filePath: string;
+}>;
+export interface AgentArtifactCandidate {
+    readonly descriptor: AgentArtifactDescriptor;
+    readonly source: AgentArtifactCandidateSource;
+    readonly delivery: AgentArtifactDeliveryRequirement;
+}
+export interface CreateAgentArtifactCandidateInput {
+    readonly descriptor: AgentArtifactDescriptor;
+    readonly source: AgentArtifactCandidateSource;
+    readonly delivery: AgentArtifactDeliveryRequirement;
+}
+export declare const AGENT_ARTIFACT_CANDIDATE_ERROR_CODES: readonly ["invalid_descriptor", "invalid_source", "source_too_large", "byte_size_mismatch", "digest_mismatch", "invalid_delivery"];
+export type AgentArtifactCandidateErrorCode = (typeof AGENT_ARTIFACT_CANDIDATE_ERROR_CODES)[number];
+export declare class AgentArtifactCandidateError extends TypeError {
+    readonly code: AgentArtifactCandidateErrorCode;
+    constructor(code: AgentArtifactCandidateErrorCode);
+}
+export declare function createAgentArtifactCandidate(input: CreateAgentArtifactCandidateInput): AgentArtifactCandidate;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import {
+  parseAgentArtifactDescriptor
+} from "@agen-ai/agent-protocol";
+import { containsAgentControlCharacter } from "./internal/controlCharacters.js";
+const AGENT_ARTIFACT_CANDIDATE_MAX_BYTES = 10 * 1024 * 1024;
+const AGENT_ARTIFACT_CANDIDATE_ERROR_CODES = [
+  "invalid_descriptor",
+  "invalid_source",
+  "source_too_large",
+  "byte_size_mismatch",
+  "digest_mismatch",
+  "invalid_delivery"
+];
+class AgentArtifactCandidateError extends TypeError {
+  constructor(code) {
+    super(`Agent artifact candidate is invalid: ${code}.`);
+    this.code = code;
+    this.name = "AgentArtifactCandidateError";
+  }
+  code;
+}
+function candidateError(code) {
+  throw new AgentArtifactCandidateError(code);
+}
+function bytesCandidateDescriptor(descriptor, bytes) {
+  if (bytes.byteLength > AGENT_ARTIFACT_CANDIDATE_MAX_BYTES) {
+    candidateError("source_too_large");
+  }
+  if (descriptor.byteSize !== void 0 && descriptor.byteSize !== bytes.byteLength) {
+    candidateError("byte_size_mismatch");
+  }
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (descriptor.digest !== void 0 && descriptor.digest.value !== digest) {
+    candidateError("digest_mismatch");
+  }
+  return parseAgentArtifactDescriptor({
+    ...descriptor,
+    byteSize: bytes.byteLength,
+    digest: { algorithm: "sha256", value: digest }
+  });
+}
+function fileCandidateSource(filePath) {
+  if (filePath.length < 1 || filePath.length > 4096 || filePath !== filePath.trim() || containsAgentControlCharacter(filePath)) {
+    candidateError("invalid_source");
+  }
+  return Object.freeze({ kind: "file", filePath });
+}
+function createAgentArtifactCandidate(input) {
+  let descriptor;
+  try {
+    descriptor = parseAgentArtifactDescriptor(input.descriptor);
+  } catch {
+    candidateError("invalid_descriptor");
+  }
+  if (!["best_effort", "required_before_reference"].includes(input.delivery)) {
+    candidateError("invalid_delivery");
+  }
+  if (descriptor.kind === "plan" && input.delivery !== "required_before_reference") {
+    candidateError("invalid_delivery");
+  }
+  if (input.source === null || typeof input.source !== "object") {
+    candidateError("invalid_source");
+  }
+  let source;
+  if (input.source.kind === "bytes") {
+    if (!(input.source.bytes instanceof Uint8Array))
+      candidateError("invalid_source");
+    source = Object.freeze({
+      kind: "bytes",
+      bytes: new Uint8Array(input.source.bytes)
+    });
+  } else if (input.source.kind === "file") {
+    source = fileCandidateSource(input.source.filePath);
+  } else {
+    candidateError("invalid_source");
+  }
+  if (source.kind === "bytes")
+    descriptor = bytesCandidateDescriptor(descriptor, source.bytes);
+  return Object.freeze({ descriptor, source, delivery: input.delivery });
+}
+export {
+  AGENT_ARTIFACT_CANDIDATE_ERROR_CODES,
+  AGENT_ARTIFACT_CANDIDATE_MAX_BYTES,
+  AgentArtifactCandidateError,
+  createAgentArtifactCandidate
+};

package/dist/configurationValidation.d.ts

@@ -0,0 +1,3 @@
+import type { AgentCapabilities, AgentSessionConfiguration } from "@agen-ai/agent-protocol";
+export declare function assertAgentSessionConfigurationSupported(capabilities: AgentCapabilities, configuration: AgentSessionConfiguration): void;
+//# sourceMappingURL=configurationValidation.d.ts.map

package/dist/configurationValidation.js

@@ -0,0 +1,35 @@
+import { throwAgentProviderContractError } from "./contractErrors.js";
+function assertAgentSessionConfigurationSupported(capabilities, configuration) {
+  const entries = Object.entries(configuration.values);
+  if (capabilities.configuration.kind === "managed") {
+    if (entries.length === 0) return;
+    throwAgentProviderContractError(
+      capabilities.providerKey,
+      "configuration_key_unsupported",
+      "Managed provider configuration values must be empty."
+    );
+  }
+  const fields = new Map(
+    capabilities.configuration.fields.map((field) => [field.key, field])
+  );
+  for (const [key, value] of entries) {
+    const field = fields.get(key);
+    if (!field) {
+      throwAgentProviderContractError(
+        capabilities.providerKey,
+        "configuration_key_unsupported",
+        "Provider configuration contains a key not declared by its capabilities."
+      );
+    }
+    if (typeof value !== "string" || !field.optionIds.includes(value)) {
+      throwAgentProviderContractError(
+        capabilities.providerKey,
+        "configuration_value_unsupported",
+        "Provider configuration contains an option not declared by its capabilities."
+      );
+    }
+  }
+}
+export {
+  assertAgentSessionConfigurationSupported
+};

package/dist/contractErrors.d.ts

@@ -0,0 +1,17 @@
+import type { AgentProviderKey } from "@agen-ai/agent-protocol";
+export declare const AGENT_PROVIDER_CONTRACT_ERROR_CODES: readonly ["capability_port_mismatch", "invalid_adapter", "invalid_session", "invalid_binding", "binding_callback_missing", "binding_callback_repeated", "binding_callback_mismatch", "resume_binding_mismatch", "branch_binding_reused", "session_closed", "session_unusable", "concurrent_turn", "active_turn_mismatch", "invalid_operation_result", "output_session_mismatch", "output_turn_mismatch", "output_authentication_attempt_mismatch", "output_capability_mismatch", "input_capability_mismatch", "invalid_turn_sequence", "request_resolution_mismatch", "configuration_key_unsupported", "configuration_value_unsupported", "request_pending"];
+export type AgentProviderContractErrorCode = (typeof AGENT_PROVIDER_CONTRACT_ERROR_CODES)[number];
+export type AgentProviderDelegatedOperation = "steer_turn";
+export declare class AgentProviderContractError extends Error {
+    readonly providerKey: AgentProviderKey;
+    readonly code: AgentProviderContractErrorCode;
+    constructor(providerKey: AgentProviderKey, code: AgentProviderContractErrorCode, message: string);
+}
+export declare class AgentProviderDelegatedOperationError extends Error {
+    readonly providerKey: AgentProviderKey;
+    readonly operation: AgentProviderDelegatedOperation;
+    readonly providerExecution: "started";
+    constructor(providerKey: AgentProviderKey, operation: AgentProviderDelegatedOperation, cause: unknown);
+}
+export declare function throwAgentProviderContractError(providerKey: AgentProviderKey, code: AgentProviderContractErrorCode, message: string): never;
+//# sourceMappingURL=contractErrors.d.ts.map

package/dist/contractErrors.js

@@ -0,0 +1,59 @@
+const AGENT_PROVIDER_CONTRACT_ERROR_CODES = [
+  "capability_port_mismatch",
+  "invalid_adapter",
+  "invalid_session",
+  "invalid_binding",
+  "binding_callback_missing",
+  "binding_callback_repeated",
+  "binding_callback_mismatch",
+  "resume_binding_mismatch",
+  "branch_binding_reused",
+  "session_closed",
+  "session_unusable",
+  "concurrent_turn",
+  "active_turn_mismatch",
+  "invalid_operation_result",
+  "output_session_mismatch",
+  "output_turn_mismatch",
+  "output_authentication_attempt_mismatch",
+  "output_capability_mismatch",
+  "input_capability_mismatch",
+  "invalid_turn_sequence",
+  "request_resolution_mismatch",
+  "configuration_key_unsupported",
+  "configuration_value_unsupported",
+  "request_pending"
+];
+class AgentProviderContractError extends Error {
+  constructor(providerKey, code, message) {
+    super(message);
+    this.providerKey = providerKey;
+    this.code = code;
+    this.name = "AgentProviderContractError";
+  }
+  providerKey;
+  code;
+}
+class AgentProviderDelegatedOperationError extends Error {
+  constructor(providerKey, operation, cause) {
+    super(
+      cause instanceof Error ? cause.message : `Provider ${providerKey} failed after ${operation} delegation.`,
+      { cause }
+    );
+    this.providerKey = providerKey;
+    this.operation = operation;
+    this.name = "AgentProviderDelegatedOperationError";
+  }
+  providerKey;
+  operation;
+  providerExecution = "started";
+}
+function throwAgentProviderContractError(providerKey, code, message) {
+  throw new AgentProviderContractError(providerKey, code, message);
+}
+export {
+  AGENT_PROVIDER_CONTRACT_ERROR_CODES,
+  AgentProviderContractError,
+  AgentProviderDelegatedOperationError,
+  throwAgentProviderContractError
+};