@agen-ai/agent-runtime 0.1.0

package/dist/sessions.d.ts

@@ -0,0 +1,133 @@
+import type { AgentAuthenticationFlow, AgentError, AgentRequestResolution, AgentSessionBinding, AgentSessionBranchSource, AgentSessionConfiguration, AgentSessionId, AgentTurnId, AgentTurnInputContent, AgentTurnInteractionMode, AgentTurnInputPart, AgentTurnInterruptionReason } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "./foundation.js";
+import type { AgentProviderOutput } from "./outputs.js";
+export interface AgentProviderSessionContext {
+    readonly sessionId: AgentSessionId;
+    readonly workingDirectory: string;
+    readonly configuration: AgentSessionConfiguration;
+    readonly signal?: AbortSignal;
+}
+export type AgentSessionBindingCreatedObserver = (binding: AgentSessionBinding) => void;
+export interface AgentProviderCreateSessionInput extends AgentProviderSessionContext {
+    readonly onBindingCreated: AgentSessionBindingCreatedObserver;
+}
+export interface AgentProviderResumeSessionInput extends AgentProviderSessionContext {
+    readonly binding: AgentSessionBinding;
+}
+export interface AgentProviderBranchSessionInput extends AgentProviderSessionContext {
+    readonly source: AgentSessionBranchSource;
+    readonly onBindingCreated: AgentSessionBindingCreatedObserver;
+}
+export type AgentProviderExecutionStartedObserver = () => void;
+export interface AgentProviderRunTurnInput {
+    readonly turnId: AgentTurnId;
+    readonly interactionMode: AgentTurnInteractionMode;
+    readonly parts: readonly AgentTurnInputPart[];
+    readonly summary?: string;
+    readonly deadlineAt?: string;
+    readonly signal?: AbortSignal;
+    readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
+}
+export interface AgentProviderResolveRequestInput {
+    readonly resolution: AgentRequestResolution;
+    readonly signal?: AbortSignal;
+}
+export interface AgentProviderInterruptTurnInput {
+    readonly turnId: AgentTurnId;
+    readonly reason: AgentTurnInterruptionReason;
+    readonly requestedAt?: string;
+    readonly signal?: AbortSignal;
+}
+export interface AgentProviderApplyConfigurationInput {
+    readonly configuration: AgentSessionConfiguration;
+    readonly signal?: AbortSignal;
+}
+export interface AgentProviderSteerTurnInput extends AgentTurnInputContent {
+    readonly turnId: AgentTurnId;
+    readonly signal?: AbortSignal;
+}
+export type AgentProviderSessionCloseReason = "idle" | "shutdown" | "replaced" | "contract_rejected" | "error" | "other";
+export interface AgentProviderCloseSessionInput {
+    readonly reason?: AgentProviderSessionCloseReason;
+    readonly signal?: AbortSignal;
+}
+export type AgentProviderOperationStatus = "accepted" | "completed" | "failed" | "canceled" | "waiting_for_request";
+export interface AgentProviderOperationResult {
+    readonly status: AgentProviderOperationStatus;
+    readonly outputs?: readonly AgentProviderOutput[];
+    readonly error?: AgentError;
+}
+export type AgentTurnSteeringResult = Readonly<{
+    status: "delivered";
+}> | Readonly<{
+    status: "rejected";
+    error: AgentError;
+}> | Readonly<{
+    status: "delivery_uncertain";
+    error: AgentError;
+}>;
+export type AgentTurnInterruption = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    interruptTurn: (input: AgentProviderInterruptTurnInput) => MaybePromise<AgentProviderOperationResult>;
+}>;
+export type AgentTurnSteering = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    steerTurn: (input: AgentProviderSteerTurnInput) => MaybePromise<AgentTurnSteeringResult>;
+}>;
+export type AgentSessionConfigurationControl = Readonly<{
+    kind: "managed";
+}> | Readonly<{
+    kind: "selectable";
+    applyConfiguration: (input: AgentProviderApplyConfigurationInput) => MaybePromise<AgentProviderOperationResult>;
+}>;
+export interface AgentProviderSession {
+    readonly binding: AgentSessionBinding;
+    readonly runTurn: (input: AgentProviderRunTurnInput) => AsyncIterable<AgentProviderOutput>;
+    readonly resolveRequest: (input: AgentProviderResolveRequestInput) => AsyncIterable<AgentProviderOutput>;
+    readonly interruption: AgentTurnInterruption;
+    readonly steering: AgentTurnSteering;
+    readonly configuration: AgentSessionConfigurationControl;
+    readonly close: (input: AgentProviderCloseSessionInput) => MaybePromise<void>;
+}
+export type AgentSessionResumption = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    resumeSession: (input: AgentProviderResumeSessionInput) => MaybePromise<AgentProviderSession>;
+}>;
+export type AgentSessionBranching = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "through_turn";
+    branchSession: (input: AgentProviderBranchSessionInput) => MaybePromise<AgentProviderSession>;
+}>;
+export interface AgentProviderAuthenticationStartInput {
+    readonly attemptId: string;
+    readonly flow: AgentAuthenticationFlow;
+    readonly deadlineAt?: string;
+    readonly signal?: AbortSignal;
+}
+export interface AgentProviderAuthenticationCancelInput {
+    readonly attemptId: string;
+    readonly providerLoginId?: string;
+    readonly reason?: "user_requested" | "timeout" | "shutdown" | "other";
+    readonly signal?: AbortSignal;
+}
+export type AgentProviderAuthentication = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    start: (input: AgentProviderAuthenticationStartInput) => AsyncIterable<AgentProviderOutput>;
+    cancel: (input: AgentProviderAuthenticationCancelInput) => MaybePromise<AgentProviderOperationResult>;
+}>;
+export interface AgentProviderAdapter {
+    readonly createSession: (input: AgentProviderCreateSessionInput) => MaybePromise<AgentProviderSession>;
+    readonly resumption: AgentSessionResumption;
+    readonly branching: AgentSessionBranching;
+    readonly authentication: AgentProviderAuthentication;
+}
+//# sourceMappingURL=sessions.d.ts.map

package/dist/steeringValidation.d.ts

@@ -0,0 +1,4 @@
+import { type AgentProviderKey } from "@agen-ai/agent-protocol";
+import type { AgentTurnSteeringResult } from "./sessions.js";
+export declare function validateAgentTurnSteeringResult(candidate: AgentTurnSteeringResult, providerKey: AgentProviderKey): AgentTurnSteeringResult;
+//# sourceMappingURL=steeringValidation.d.ts.map

package/dist/steeringValidation.js

@@ -0,0 +1,36 @@
+import {
+  parseAgentError
+} from "@agen-ai/agent-protocol";
+import { throwAgentProviderContractError } from "./contractErrors.js";
+function validateAgentTurnSteeringResult(candidate, providerKey) {
+  if (candidate === null || typeof candidate !== "object") {
+    return invalidSteeringResult(providerKey);
+  }
+  if (candidate.status === "delivered") {
+    if (Reflect.ownKeys(candidate).length !== 1) {
+      return invalidSteeringResult(providerKey);
+    }
+    return Object.freeze({ status: "delivered" });
+  }
+  if (!["rejected", "delivery_uncertain"].includes(candidate.status) || Reflect.ownKeys(candidate).length !== 2 || !("error" in candidate)) {
+    return invalidSteeringResult(providerKey);
+  }
+  try {
+    return Object.freeze({
+      status: candidate.status,
+      error: parseAgentError(candidate.error)
+    });
+  } catch {
+    return invalidSteeringResult(providerKey);
+  }
+}
+function invalidSteeringResult(providerKey) {
+  return throwAgentProviderContractError(
+    providerKey,
+    "invalid_operation_result",
+    `Provider ${providerKey} returned an invalid steering result.`
+  );
+}
+export {
+  validateAgentTurnSteeringResult
+};

package/dist/testing/conformance.d.ts

@@ -0,0 +1,30 @@
+import { type AgentRequest, type AgentRequestResolution, type AgentSessionBinding, type AgentSessionBranchSource, type AgentSessionConfiguration, type AgentSessionId, type AgentTurnId, type AgentTurnInputContent } from "@agen-ai/agent-protocol";
+import type { AgentProviderDriver, AgentProviderInstanceDefinition } from "../providerDriver.js";
+import type { AgentProviderRunTurnInput } from "../sessions.js";
+export interface AgentProviderConformanceScenario {
+    readonly driver: AgentProviderDriver;
+    readonly definition: AgentProviderInstanceDefinition;
+    readonly workingDirectory: string;
+    readonly configuration: AgentSessionConfiguration;
+    readonly updatedConfiguration?: AgentSessionConfiguration;
+    readonly createSessionId: AgentSessionId;
+    readonly resumeSessionId: AgentSessionId;
+    readonly branchSessionId?: AgentSessionId;
+    readonly abortedSessionId: AgentSessionId;
+    readonly interruptionSessionId: AgentSessionId;
+    readonly turn: AgentProviderRunTurnInput;
+    readonly interruptionTurn: AgentProviderRunTurnInput;
+    readonly resolutionFor: (request: AgentRequest) => AgentRequestResolution;
+    readonly branchSource?: (binding: AgentSessionBinding, turnId: AgentTurnId) => AgentSessionBranchSource;
+    readonly steeringInput?: AgentTurnInputContent;
+}
+export interface AgentProviderConformanceReport {
+    readonly providerKey: string;
+    readonly checks: readonly string[];
+}
+export declare class AgentProviderConformanceError extends Error {
+    readonly check: string;
+    constructor(check: string, message: string);
+}
+export declare function runAgentProviderConformance(scenario: AgentProviderConformanceScenario): Promise<AgentProviderConformanceReport>;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/testing/conformance.js

@@ -0,0 +1,379 @@
+import {
+  matchesAgentSessionBinding,
+  parseAgentRequestResolutionFor
+} from "@agen-ai/agent-protocol";
+import { isAgentOperationAbortError } from "../foundation.js";
+import {
+  createAgentProviderRegistry,
+  AgentProviderRegistryError
+} from "../providerInstanceRegistry.js";
+class AgentProviderConformanceError extends Error {
+  constructor(check, message) {
+    super(message);
+    this.check = check;
+    this.name = "AgentProviderConformanceError";
+  }
+  check;
+}
+function requireCheck(condition, check, message) {
+  if (!condition) throw new AgentProviderConformanceError(check, message);
+}
+async function advanceToStartedTurn(session, input) {
+  const iterator = session.runTurn(input)[Symbol.asyncIterator]();
+  const outputs = [];
+  try {
+    for (; ; ) {
+      const next = await iterator.next();
+      requireCheck(
+        !next.done,
+        "turn_order",
+        "Turn ended before emitting turn.started."
+      );
+      outputs.push(next.value);
+      if (next.value.kind === "event" && next.value.event.type === "turn.started") {
+        return { iterator, outputs };
+      }
+    }
+  } catch (error) {
+    await iterator.return?.();
+    throw error;
+  }
+}
+async function collectRemainingOutputs(started) {
+  for (; ; ) {
+    const next = await started.iterator.next();
+    if (next.done) return started.outputs;
+    started.outputs.push(next.value);
+  }
+}
+async function collectOutputs(outputs) {
+  const collected = [];
+  for await (const output of outputs) collected.push(output);
+  return collected;
+}
+function requireOperationStatus(result, statuses, check, message) {
+  requireCheck(statuses.includes(result.status), check, message);
+}
+function semanticEvents(outputs) {
+  return outputs.flatMap(
+    (output) => output.kind === "event" ? [output.event] : []
+  );
+}
+async function runAgentProviderConformance(scenario) {
+  const checks = [];
+  try {
+    await createAgentProviderRegistry({
+      drivers: [scenario.driver],
+      definitions: [scenario.definition, scenario.definition]
+    });
+    requireCheck(
+      false,
+      "duplicate_instance",
+      "Duplicate instance definitions were accepted."
+    );
+  } catch (error) {
+    requireCheck(
+      error instanceof AgentProviderRegistryError && error.code === "duplicate_instance",
+      "duplicate_instance",
+      "Duplicate instance definitions did not fail with the registry contract error."
+    );
+    checks.push("duplicate_instance");
+  }
+  const registry = await createAgentProviderRegistry({
+    drivers: [scenario.driver],
+    definitions: [scenario.definition]
+  });
+  let disposed = false;
+  let createdSession = null;
+  try {
+    const instance = registry.requireInstance(scenario.definition.instanceId);
+    requireCheck(
+      instance.instanceId === scenario.definition.instanceId,
+      "instance_identity",
+      "Materialized instance identity changed."
+    );
+    requireCheck(
+      instance.capabilities.providerKey === scenario.definition.providerKey,
+      "capabilities",
+      "Capabilities identify another provider."
+    );
+    requireCheck(
+      instance.capabilities.authentication.kind === instance.adapter.authentication.kind,
+      "authentication_capability",
+      "Authentication capability does not match the adapter port."
+    );
+    checks.push(
+      "instance_identity",
+      "capabilities",
+      "authentication_capability"
+    );
+    const readiness = await registry.checkReadiness(
+      scenario.definition.instanceId
+    );
+    requireCheck(
+      readiness.status === "ready",
+      "readiness",
+      "Provider is not ready."
+    );
+    requireCheck(
+      !instance.capabilities.versionReporting || readiness.version !== void 0,
+      "version_reporting_capability",
+      "Version-reporting capability did not return a runtime version."
+    );
+    checks.push("readiness", "version_reporting_capability");
+    let createdBindingCount = 0;
+    const created = await instance.adapter.createSession({
+      sessionId: scenario.createSessionId,
+      workingDirectory: scenario.workingDirectory,
+      configuration: scenario.configuration,
+      onBindingCreated: () => {
+        createdBindingCount += 1;
+      }
+    });
+    createdSession = created;
+    requireCheck(
+      createdBindingCount === 1,
+      "binding_callback",
+      "Create session did not report exactly one binding."
+    );
+    checks.push("create_session", "binding_callback");
+    const aborted = new AbortController();
+    aborted.abort(new DOMException("Conformance abort.", "AbortError"));
+    try {
+      await instance.adapter.createSession({
+        sessionId: scenario.abortedSessionId,
+        workingDirectory: scenario.workingDirectory,
+        configuration: scenario.configuration,
+        signal: aborted.signal,
+        onBindingCreated: () => void 0
+      });
+      requireCheck(false, "abort", "Pre-aborted createSession was accepted.");
+    } catch (error) {
+      requireCheck(
+        isAgentOperationAbortError(error),
+        "abort",
+        "Pre-aborted createSession did not fail with AbortError."
+      );
+      checks.push("abort");
+    }
+    const startedTurn = await advanceToStartedTurn(created, scenario.turn);
+    let turnOutputs;
+    try {
+      if (instance.capabilities.turns.steer.kind === "supported") {
+        requireCheck(
+          created.steering.kind === "supported",
+          "steering",
+          "Steering capability has no handler."
+        );
+        const result = await created.steering.steerTurn({
+          turnId: scenario.turn.turnId,
+          ...scenario.steeringInput ?? {
+            parts: [
+              { type: "text", text: "Additional conformance input." }
+            ]
+          }
+        });
+        requireCheck(
+          result.status === "delivered",
+          "steering",
+          "Steering did not deliver to the live turn."
+        );
+      } else {
+        requireCheck(
+          created.steering.kind === "unsupported",
+          "steering",
+          "Unsupported steering exposed a handler."
+        );
+      }
+      turnOutputs = await collectRemainingOutputs(startedTurn);
+    } catch (error) {
+      await startedTurn.iterator.return?.();
+      await created.close({ reason: "contract_rejected" });
+      throw error;
+    }
+    const events = semanticEvents(turnOutputs);
+    requireCheck(
+      events[0]?.type === "turn.started",
+      "turn_order",
+      "Turn did not start first."
+    );
+    const lastEvent = events.at(-1);
+    requireCheck(
+      lastEvent?.type === "turn.completed" || lastEvent?.type === "turn.state_changed" && lastEvent.payload.state === "waiting_for_request",
+      "turn_order",
+      "Turn did not terminate or enter a waiting state."
+    );
+    checks.push("turn_order");
+    const openedRequest = events.find(
+      (event) => event.type === "request.opened"
+    );
+    if (openedRequest?.type === "request.opened") {
+      const resolution = parseAgentRequestResolutionFor(
+        openedRequest.payload.request,
+        scenario.resolutionFor(openedRequest.payload.request)
+      );
+      const resolutionOutputs = await collectOutputs(
+        created.resolveRequest({ resolution })
+      );
+      const resolutionBoundary = semanticEvents(resolutionOutputs).at(-1);
+      requireCheck(
+        resolutionBoundary?.type === "turn.completed" || resolutionBoundary?.type === "turn.state_changed" && resolutionBoundary.payload.state === "waiting_for_request",
+        "request_resolution",
+        "Matching request resolution did not reach a stable turn boundary."
+      );
+      checks.push("request_resolution");
+    }
+    checks.push("steering");
+    if (instance.capabilities.turns.interrupt) {
+      let interruptedBindingCount = 0;
+      const interrupted = await instance.adapter.createSession({
+        sessionId: scenario.interruptionSessionId,
+        workingDirectory: scenario.workingDirectory,
+        configuration: scenario.configuration,
+        onBindingCreated: () => {
+          interruptedBindingCount += 1;
+        }
+      });
+      requireCheck(
+        interruptedBindingCount === 1 && interrupted.interruption.kind === "supported",
+        "interruption",
+        "Interruption capability did not open a conforming session handler."
+      );
+      let liveTurn = null;
+      try {
+        liveTurn = await advanceToStartedTurn(
+          interrupted,
+          scenario.interruptionTurn
+        );
+        if (interrupted.interruption.kind !== "supported") {
+          throw new AgentProviderConformanceError(
+            "interruption",
+            "Interruption capability has no handler."
+          );
+        }
+        const result = await interrupted.interruption.interruptTurn({
+          turnId: scenario.interruptionTurn.turnId,
+          reason: "user_requested"
+        });
+        requireOperationStatus(
+          result,
+          ["accepted", "completed", "canceled"],
+          "interruption",
+          "Live turn interruption did not succeed."
+        );
+      } finally {
+        await liveTurn?.iterator.return?.();
+        await interrupted.close({ reason: "other" });
+      }
+    } else {
+      requireCheck(
+        created.interruption.kind === "unsupported",
+        "interruption",
+        "Unsupported interruption exposed a handler."
+      );
+    }
+    checks.push("interruption");
+    if (instance.capabilities.configuration.kind === "selectable") {
+      requireCheck(
+        created.configuration.kind === "selectable" && scenario.updatedConfiguration !== void 0,
+        "configuration",
+        "Selectable configuration requires a handler and updated fixture."
+      );
+      const result = await created.configuration.applyConfiguration({
+        configuration: scenario.updatedConfiguration
+      });
+      requireOperationStatus(
+        result,
+        ["completed"],
+        "configuration",
+        "Selectable configuration did not complete atomically."
+      );
+    } else {
+      requireCheck(
+        created.configuration.kind === "managed",
+        "configuration",
+        "Managed configuration exposed a selection handler."
+      );
+    }
+    checks.push("configuration");
+    await created.close({ reason: "idle" });
+    await created.close({ reason: "idle" });
+    checks.push("idempotent_session_close");
+    if (instance.capabilities.sessions.resume) {
+      requireCheck(
+        instance.adapter.resumption.kind === "supported",
+        "resume_session",
+        "Resume capability has no adapter port."
+      );
+      const resumed = await instance.adapter.resumption.resumeSession({
+        sessionId: scenario.resumeSessionId,
+        workingDirectory: scenario.workingDirectory,
+        configuration: scenario.configuration,
+        binding: created.binding
+      });
+      requireCheck(
+        matchesAgentSessionBinding(resumed.binding, created.binding),
+        "resume_session",
+        "Resume changed the provider binding."
+      );
+      await resumed.close({ reason: "idle" });
+    } else {
+      requireCheck(
+        instance.adapter.resumption.kind === "unsupported",
+        "resume_session",
+        "Unsupported resume exposed an adapter port."
+      );
+    }
+    checks.push("resume_session");
+    if (instance.capabilities.sessions.branch.kind === "through_turn") {
+      requireCheck(
+        instance.adapter.branching.kind === "through_turn" && scenario.branchSessionId !== void 0 && scenario.branchSource !== void 0,
+        "branch_session",
+        "Branch capability requires a handler and branch fixtures."
+      );
+      let branchBindingCount = 0;
+      const branched = await instance.adapter.branching.branchSession({
+        sessionId: scenario.branchSessionId,
+        workingDirectory: scenario.workingDirectory,
+        configuration: scenario.configuration,
+        source: scenario.branchSource(created.binding, scenario.turn.turnId),
+        onBindingCreated: () => {
+          branchBindingCount += 1;
+        }
+      });
+      requireCheck(
+        branchBindingCount === 1 && !matchesAgentSessionBinding(branched.binding, created.binding),
+        "branch_session",
+        "Branch did not report exactly one new provider binding."
+      );
+      await branched.close({ reason: "idle" });
+    } else {
+      requireCheck(
+        instance.adapter.branching.kind === "unsupported",
+        "branch_session",
+        "Unsupported branch exposed an adapter port."
+      );
+    }
+    checks.push("branch_session");
+    await registry.dispose();
+    await registry.dispose();
+    disposed = true;
+    requireCheck(
+      registry.listInstances().length === 0,
+      "disposal",
+      "Disposed registry retained instances."
+    );
+    checks.push("idempotent_disposal");
+    return Object.freeze({
+      providerKey: scenario.definition.providerKey,
+      checks: Object.freeze(checks)
+    });
+  } finally {
+    await createdSession?.close({ reason: "contract_rejected" });
+    if (!disposed) await registry.dispose();
+  }
+}
+export {
+  AgentProviderConformanceError,
+  runAgentProviderConformance
+};

package/dist/testing/fakeProvider.d.ts

@@ -0,0 +1,35 @@
+import { type AgentCapabilities, type AgentInstanceId, type AgentRequestResolution, type AgentSessionId, type AgentTurnId } from "@agen-ai/agent-protocol";
+import { type AgentProviderDriver, type AgentProviderInstanceDefinition } from "../providerDriver.js";
+import type { AgentProviderSteerTurnInput, AgentTurnSteeringResult } from "../sessions.js";
+export interface FakeAgentProviderOptions {
+    readonly providerKey?: string;
+    readonly instanceId?: string;
+    readonly capabilities?: AgentCapabilities;
+    readonly now?: () => string;
+    readonly steeringResult?: AgentTurnSteeringResult;
+}
+export type FakeAgentSteeringInput = Readonly<Omit<AgentProviderSteerTurnInput, "signal">>;
+export interface FakeAgentProviderSnapshot {
+    readonly materializationCount: number;
+    readonly instanceDisposeCount: number;
+    readonly createdSessionIds: readonly AgentSessionId[];
+    readonly resumedSessionIds: readonly AgentSessionId[];
+    readonly branchedSessionIds: readonly AgentSessionId[];
+    readonly turnIds: readonly AgentTurnId[];
+    readonly resolutions: readonly AgentRequestResolution[];
+    readonly interruptedTurnIds: readonly AgentTurnId[];
+    readonly steeringInputs: readonly FakeAgentSteeringInput[];
+    readonly configurationRevisions: readonly string[];
+    readonly closeCounts: Readonly<Record<string, number>>;
+}
+export interface FakeAgentProvider {
+    readonly driver: AgentProviderDriver;
+    readonly definition: AgentProviderInstanceDefinition;
+    readonly capabilities: AgentCapabilities;
+    readonly snapshot: () => FakeAgentProviderSnapshot;
+}
+export declare function createFakeAgentProvider(options?: FakeAgentProviderOptions): FakeAgentProvider;
+export declare function createFakeAgentSessionId(value: string): AgentSessionId;
+export declare function createFakeAgentTurnId(value: string): AgentTurnId;
+export declare function createFakeAgentInstanceId(value: string): AgentInstanceId;
+//# sourceMappingURL=fakeProvider.d.ts.map