@agen-ai/agent-runtime 0.1.0

package/dist/testing/fakeProvider.js

@@ -0,0 +1,367 @@
+import {
+  parseAgentCapabilities,
+  parseAgentInstanceId,
+  parseAgentIsoDateTime,
+  parseAgentProviderConversationId,
+  parseAgentProviderHistoryAnchor,
+  parseAgentProviderKey,
+  parseAgentRequestId,
+  parseAgentRequestResolutionFor,
+  parseAgentSessionId,
+  parseAgentTurnId
+} from "@agen-ai/agent-protocol";
+import { createAgentEventOutput } from "../outputs.js";
+import {
+  defineAgentProviderDriver
+} from "../providerDriver.js";
+import { createAgentProviderReadiness } from "../readiness.js";
+import { throwIfAgentOperationAborted } from "../foundation.js";
+function defaultCapabilities(providerKey) {
+  const input = {
+    text: true,
+    images: {
+      kind: "supported",
+      sourceKinds: ["url", "base64", "local_file"],
+      mediaTypes: ["image/png", "image/jpeg", "image/webp"],
+      maxImages: 6,
+      maxBytesPerImage: 10 * 1024 * 1024,
+      maxTotalBytes: 25 * 1024 * 1024,
+      maxWidthPixels: 6e3,
+      maxHeightPixels: 6e3,
+      maxPixelsPerImage: 36e6,
+      supportsImageOnly: true
+    }
+  };
+  return parseAgentCapabilities({
+    protocolVersion: 6,
+    providerKey,
+    sessions: { create: true, resume: true, branch: { kind: "through_turn" } },
+    turns: {
+      interactionModes: ["default"],
+      interrupt: true,
+      steer: { kind: "supported", input }
+    },
+    requests: { approval: true, elicitation: { kind: "structured" } },
+    input,
+    output: {
+      streaming: true,
+      plans: true,
+      fileChanges: "structured",
+      artifactKinds: ["plan", "diff"]
+    },
+    configuration: {
+      kind: "selectable",
+      fields: [
+        { key: "mode", optionIds: ["agent"] },
+        {
+          key: "model",
+          optionIds: ["fake-model", "fake-model-2"]
+        }
+      ]
+    },
+    interactionExtensions: {
+      slashCommands: false,
+      mcp: false,
+      subagents: false,
+      imageGeneration: false
+    },
+    authentication: { kind: "unsupported" },
+    versionReporting: true
+  });
+}
+function sessionBinding(state, sessionId) {
+  state.bindingSequence += 1;
+  return {
+    conversationId: parseAgentProviderConversationId(
+      `fake-conversation:${sessionId}:${state.bindingSequence}`
+    ),
+    historyAnchor: parseAgentProviderHistoryAnchor(
+      `fake-history:${sessionId}:${state.bindingSequence}`
+    )
+  };
+}
+function eventBase(sessionId, turnId, occurredAt) {
+  return { protocolVersion: 6, sessionId, turnId, occurredAt };
+}
+function requestForTurn(turnId) {
+  return {
+    requestKind: "approval",
+    requestId: parseAgentRequestId(`fake-request:${turnId}`),
+    prompt: "Approve the deterministic fake operation?",
+    subject: { kind: "other", title: "Fake provider operation" }
+  };
+}
+function completedResult(outputs = []) {
+  return Object.freeze({
+    status: "completed",
+    outputs: Object.freeze(outputs)
+  });
+}
+function fakeSession(input) {
+  const pendingRequests = /* @__PURE__ */ new Map();
+  let closed = false;
+  const runTurn = async function* (turnInput) {
+    throwIfAgentOperationAborted(turnInput.signal);
+    input.state.turnIds.push(turnInput.turnId);
+    const occurredAt = input.now();
+    yield createAgentEventOutput({
+      ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
+      type: "turn.started",
+      payload: { message: "Fake provider turn started." }
+    });
+    if (input.capabilities.output.streaming) {
+      yield createAgentEventOutput({
+        ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
+        type: "content.delta",
+        payload: {
+          itemId: `fake-item:${turnInput.turnId}`,
+          streamKind: "assistant_text",
+          delta: "Deterministic fake output."
+        }
+      });
+    }
+    if (input.capabilities.requests.approval) {
+      const request = requestForTurn(turnInput.turnId);
+      pendingRequests.set(request.requestId, {
+        request,
+        turnId: turnInput.turnId
+      });
+      yield createAgentEventOutput({
+        ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
+        type: "request.opened",
+        payload: { request }
+      });
+      yield createAgentEventOutput({
+        ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
+        type: "turn.state_changed",
+        payload: { state: "waiting_for_request", requestId: request.requestId }
+      });
+      return;
+    }
+    yield createAgentEventOutput({
+      ...eventBase(input.context.sessionId, turnInput.turnId, occurredAt),
+      type: "turn.completed",
+      payload: { outcome: "completed", reason: "Fake provider completed." }
+    });
+  };
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    input.state.closeCounts.set(
+      input.context.sessionId,
+      (input.state.closeCounts.get(input.context.sessionId) ?? 0) + 1
+    );
+  };
+  return {
+    binding: input.binding,
+    runTurn,
+    resolveRequest: async function* (requestInput) {
+      throwIfAgentOperationAborted(requestInput.signal);
+      const pending = pendingRequests.get(requestInput.resolution.requestId);
+      if (!pending)
+        throw new TypeError("Fake provider has no matching pending request.");
+      const resolution = parseAgentRequestResolutionFor(
+        pending.request,
+        requestInput.resolution
+      );
+      input.state.resolutions.push(resolution);
+      pendingRequests.delete(resolution.requestId);
+      const occurredAt = input.now();
+      yield createAgentEventOutput({
+        ...eventBase(input.context.sessionId, pending.turnId, occurredAt),
+        type: "turn.state_changed",
+        payload: { state: "running" }
+      });
+      yield createAgentEventOutput({
+        ...eventBase(input.context.sessionId, pending.turnId, occurredAt),
+        type: "turn.completed",
+        payload: { outcome: "completed", reason: "Fake request resolved." }
+      });
+    },
+    interruption: input.capabilities.turns.interrupt ? {
+      kind: "supported",
+      interruptTurn: async (interruptionInput) => {
+        throwIfAgentOperationAborted(interruptionInput.signal);
+        input.state.interruptedTurnIds.push(interruptionInput.turnId);
+        return completedResult([
+          createAgentEventOutput({
+            ...eventBase(
+              input.context.sessionId,
+              interruptionInput.turnId,
+              input.now()
+            ),
+            type: "turn.completed",
+            payload: {
+              outcome: "canceled",
+              reason: interruptionInput.reason
+            }
+          })
+        ]);
+      }
+    } : { kind: "unsupported" },
+    steering: input.capabilities.turns.steer.kind === "supported" ? {
+      kind: "supported",
+      steerTurn: async (steeringInput) => {
+        throwIfAgentOperationAborted(steeringInput.signal);
+        input.state.steeringInputs.push(
+          Object.freeze({
+            turnId: steeringInput.turnId,
+            parts: Object.freeze([...steeringInput.parts]),
+            ...steeringInput.summary === void 0 ? {} : { summary: steeringInput.summary }
+          })
+        );
+        return input.steeringResult;
+      }
+    } : { kind: "unsupported" },
+    configuration: input.capabilities.configuration.kind === "selectable" ? {
+      kind: "selectable",
+      applyConfiguration: async (configurationInput) => {
+        throwIfAgentOperationAborted(configurationInput.signal);
+        input.state.configurationRevisions.push(
+          configurationInput.configuration.revision
+        );
+        return completedResult();
+      }
+    } : { kind: "managed" },
+    close
+  };
+}
+function fakeAdapter(input) {
+  const open = (context, binding) => fakeSession({ ...input, context, binding });
+  return {
+    createSession(createInput) {
+      throwIfAgentOperationAborted(createInput.signal);
+      input.state.createdSessionIds.push(createInput.sessionId);
+      const binding = sessionBinding(input.state, createInput.sessionId);
+      createInput.onBindingCreated(binding);
+      return open(createInput, binding);
+    },
+    resumption: input.capabilities.sessions.resume ? {
+      kind: "supported",
+      resumeSession(resumeInput) {
+        throwIfAgentOperationAborted(resumeInput.signal);
+        input.state.resumedSessionIds.push(resumeInput.sessionId);
+        return open(resumeInput, resumeInput.binding);
+      }
+    } : { kind: "unsupported" },
+    branching: input.capabilities.sessions.branch.kind === "through_turn" ? {
+      kind: "through_turn",
+      branchSession(branchInput) {
+        throwIfAgentOperationAborted(branchInput.signal);
+        input.state.branchedSessionIds.push(branchInput.sessionId);
+        const binding = sessionBinding(
+          input.state,
+          branchInput.sessionId
+        );
+        branchInput.onBindingCreated(binding);
+        return open(branchInput, binding);
+      }
+    } : { kind: "unsupported" },
+    authentication: input.capabilities.authentication.kind === "supported" ? {
+      kind: "supported",
+      start: async function* () {
+        return;
+      },
+      cancel: async () => completedResult()
+    } : { kind: "unsupported" }
+  };
+}
+function createFakeAgentProvider(options = {}) {
+  const providerKey = parseAgentProviderKey(
+    options.providerKey ?? "fake-provider"
+  );
+  const instanceId = parseAgentInstanceId(
+    options.instanceId ?? "fake-instance:primary"
+  );
+  const capabilities = parseAgentCapabilities(
+    options.capabilities ?? defaultCapabilities(providerKey)
+  );
+  if (capabilities.providerKey !== providerKey) {
+    throw new TypeError("Fake provider capabilities must match providerKey.");
+  }
+  const now = () => parseAgentIsoDateTime(options.now?.() ?? "2026-08-04T00:00:00.000Z");
+  const steeringResult = options.steeringResult ?? Object.freeze({ status: "delivered" });
+  const state = {
+    materializationCount: 0,
+    instanceDisposeCount: 0,
+    bindingSequence: 0,
+    createdSessionIds: [],
+    resumedSessionIds: [],
+    branchedSessionIds: [],
+    turnIds: [],
+    resolutions: [],
+    interruptedTurnIds: [],
+    steeringInputs: [],
+    configurationRevisions: [],
+    closeCounts: /* @__PURE__ */ new Map()
+  };
+  const driver = defineAgentProviderDriver({
+    providerKey,
+    supportsMultipleInstances: true,
+    parseConfiguration(input) {
+      if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new TypeError("Fake driver configuration must be an object.");
+      }
+      return Object.freeze({ ...input });
+    },
+    createInstance({ instanceId: createdInstanceId }) {
+      state.materializationCount += 1;
+      let disposed = false;
+      return {
+        instanceId: createdInstanceId,
+        capabilities,
+        adapter: fakeAdapter({ state, capabilities, now, steeringResult }),
+        checkReadiness: () => createAgentProviderReadiness({
+          status: "ready",
+          checkedAt: now(),
+          version: "1.0.0-fake",
+          diagnostics: { deterministic: true }
+        }),
+        dispose: async () => {
+          if (disposed) return;
+          disposed = true;
+          state.instanceDisposeCount += 1;
+        }
+      };
+    }
+  });
+  return Object.freeze({
+    driver,
+    definition: Object.freeze({
+      providerKey,
+      instanceId,
+      driverConfiguration: Object.freeze({})
+    }),
+    capabilities,
+    snapshot: () => Object.freeze({
+      materializationCount: state.materializationCount,
+      instanceDisposeCount: state.instanceDisposeCount,
+      createdSessionIds: Object.freeze([...state.createdSessionIds]),
+      resumedSessionIds: Object.freeze([...state.resumedSessionIds]),
+      branchedSessionIds: Object.freeze([...state.branchedSessionIds]),
+      turnIds: Object.freeze([...state.turnIds]),
+      resolutions: Object.freeze([...state.resolutions]),
+      interruptedTurnIds: Object.freeze([...state.interruptedTurnIds]),
+      steeringInputs: Object.freeze([...state.steeringInputs]),
+      configurationRevisions: Object.freeze([
+        ...state.configurationRevisions
+      ]),
+      closeCounts: Object.freeze(Object.fromEntries(state.closeCounts))
+    })
+  });
+}
+function createFakeAgentSessionId(value) {
+  return parseAgentSessionId(value);
+}
+function createFakeAgentTurnId(value) {
+  return parseAgentTurnId(value);
+}
+function createFakeAgentInstanceId(value) {
+  return parseAgentInstanceId(value);
+}
+export {
+  createFakeAgentInstanceId,
+  createFakeAgentProvider,
+  createFakeAgentSessionId,
+  createFakeAgentTurnId
+};

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./conformance.js";
+export * from "./fakeProvider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.js

@@ -0,0 +1,2 @@
+export * from "./conformance.js";
+export * from "./fakeProvider.js";

package/dist/text.d.ts

@@ -0,0 +1,2 @@
+export declare function chunkAgentCanonicalText(value: string): readonly string[];
+//# sourceMappingURL=text.d.ts.map

package/dist/text.js

@@ -0,0 +1,16 @@
+import { AGENT_PROTOCOL_TEXT_MAX_LENGTH } from "@agen-ai/agent-protocol";
+function chunkAgentCanonicalText(value) {
+  const chunks = [];
+  let offset = 0;
+  while (offset < value.length) {
+    let end = Math.min(offset + AGENT_PROTOCOL_TEXT_MAX_LENGTH, value.length);
+    const splitsSurrogatePair = end < value.length && /[\uD800-\uDBFF]/u.test(value[end - 1] ?? "") && /[\uDC00-\uDFFF]/u.test(value[end] ?? "");
+    if (splitsSurrogatePair) end -= 1;
+    chunks.push(value.slice(offset, end));
+    offset = end;
+  }
+  return Object.freeze(chunks);
+}
+export {
+  chunkAgentCanonicalText
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@agen-ai/agent-runtime",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Provider-neutral driver, instance, adapter, session, output, and conformance contracts for coding-agent runtimes.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@agen-ai/agent-protocol": "^0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trevor-nichols/agenai-agent-sdk.git",
+    "directory": "packages/agent-runtime"
+  },
+  "homepage": "https://github.com/trevor-nichols/agenai-agent-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/trevor-nichols/agenai-agent-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "pnpm run clean && pnpm run build:runtime && pnpm run build:types",
+    "build:runtime": "tsup",
+    "build:types": "tsc --project tsconfig.json --emitDeclarationOnly --outDir dist",
+    "dev": "pnpm run build:runtime -- --watch",
+    "dev:types": "tsc --project tsconfig.json --emitDeclarationOnly --outDir dist --watch",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit && tsc --project tsconfig.test.json --noEmit && tsc --project tsconfig.type-tests.json --noEmit && tsc --project tsconfig.external.json --noEmit",
+    "typecheck:external": "tsc --project tsconfig.external.json --noEmit",
+    "clean": "rimraf dist *.tsbuildinfo"
+  }
+}