@agen-ai/agent-runtime 0.2.2 → 0.2.3

package/dist/sessions.d.ts

@@ -1,6 +1,7 @@
-import type { AgentAuthenticationFlow, AgentError, AgentRequestResolution, AgentSessionBinding, AgentSessionBranchSource, AgentSessionConfiguration, AgentSessionId, AgentTurnId, AgentTurnInputContent, AgentTurnInteractionMode, AgentTurnInputPart, AgentTurnInterruptionReason } from "@agen-ai/agent-protocol";
+import type { AgentAuthenticationFlow, AgentCollaborationControlInput, AgentCollaborationNode, AgentCollaborationSpawnInput, AgentConfigurationCatalog, AgentConfigurationSelectionInput, AgentError, AgentGeneratedResourceDescriptor, AgentGeneratedResourceId, AgentIntegrationCatalog, AgentManagedContentCatalog, AgentOperationCatalog, AgentOperationInvocation, AgentOperationResult, 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";
+import type { AgentArtifactCandidate } from "./artifacts.js";
 export interface AgentProviderSessionContext {
     readonly sessionId: AgentSessionId;
     readonly workingDirectory: string;
@@ -38,9 +39,36 @@ export interface AgentProviderInterruptTurnInput {
     readonly requestedAt?: string;
     readonly signal?: AbortSignal;
 }
-export interface AgentProviderApplyConfigurationInput {
-    readonly configuration: AgentSessionConfiguration;
+export interface AgentProviderListInput {
+    readonly signal?: AbortSignal;
+}
+export interface AgentProviderApplyConfigurationSelectionInput {
+    readonly selection: AgentConfigurationSelectionInput;
+    readonly signal?: AbortSignal;
+    readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
+}
+export interface AgentProviderInvokeOperationInput {
+    readonly invocation: AgentOperationInvocation;
+    readonly signal?: AbortSignal;
+    readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
+}
+export interface AgentProviderSpawnCollaborationInput {
+    readonly spawn: AgentCollaborationSpawnInput;
     readonly signal?: AbortSignal;
+    readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
+}
+export interface AgentProviderControlCollaborationInput {
+    readonly control: AgentCollaborationControlInput;
+    readonly signal?: AbortSignal;
+    readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
+}
+export interface AgentProviderGetGeneratedResourceInput {
+    readonly resourceId: AgentGeneratedResourceId;
+    readonly signal?: AbortSignal;
+}
+export interface AgentGeneratedResourceInspection {
+    readonly descriptor: AgentGeneratedResourceDescriptor;
+    readonly candidate?: AgentArtifactCandidate;
 }
 export interface AgentProviderSteerTurnInput extends AgentTurnInputContent {
     readonly turnId: AgentTurnId;
@@ -82,7 +110,40 @@ export type AgentSessionConfigurationControl = Readonly<{
     kind: "managed";
 }> | Readonly<{
     kind: "selectable";
-    applyConfiguration: (input: AgentProviderApplyConfigurationInput) => MaybePromise<AgentProviderOperationResult>;
+    listConfiguration: (input?: AgentProviderListInput) => MaybePromise<AgentConfigurationCatalog>;
+    applyConfigurationSelection: (input: AgentProviderApplyConfigurationSelectionInput) => MaybePromise<AgentProviderOperationResult>;
+}>;
+export type AgentOperationControl = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    listOperations: (input?: AgentProviderListInput) => MaybePromise<AgentOperationCatalog>;
+    invokeOperation: (input: AgentProviderInvokeOperationInput) => MaybePromise<AgentOperationResult>;
+}>;
+export type AgentManagedContentInventory = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    listManagedContent: (input?: AgentProviderListInput) => MaybePromise<AgentManagedContentCatalog>;
+}>;
+export type AgentIntegrationObservation = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    observeIntegrations: (input?: AgentProviderListInput) => MaybePromise<AgentIntegrationCatalog>;
+}>;
+export type AgentCollaborationControl = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    spawnCollaboration: (input: AgentProviderSpawnCollaborationInput) => MaybePromise<AgentCollaborationNode>;
+    controlCollaboration: (input: AgentProviderControlCollaborationInput) => MaybePromise<AgentCollaborationNode>;
+}>;
+export type AgentGeneratedResourceAccess = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "supported";
+    getGeneratedResource: (input: AgentProviderGetGeneratedResourceInput) => MaybePromise<AgentGeneratedResourceInspection>;
 }>;
 export interface AgentProviderSession {
     readonly binding: AgentSessionBinding;
@@ -91,6 +152,11 @@ export interface AgentProviderSession {
     readonly interruption: AgentTurnInterruption;
     readonly steering: AgentTurnSteering;
     readonly configuration: AgentSessionConfigurationControl;
+    readonly operations: AgentOperationControl;
+    readonly managedContent: AgentManagedContentInventory;
+    readonly integrations: AgentIntegrationObservation;
+    readonly collaboration: AgentCollaborationControl;
+    readonly generatedResources: AgentGeneratedResourceAccess;
     readonly close: (input: AgentProviderCloseSessionInput) => MaybePromise<void>;
 }
 export type AgentSessionResumption = Readonly<{

package/dist/testing/conformance.d.ts

@@ -1,4 +1,4 @@
-import { type AgentRequest, type AgentRequestResolution, type AgentSessionBinding, type AgentSessionBranchSource, type AgentSessionConfiguration, type AgentSessionId, type AgentTurnId, type AgentTurnInputContent } from "@agen-ai/agent-protocol";
+import { type AgentCollaborationSpawnInput, type AgentConfigurationSelectionInput, type AgentGeneratedResourceId, type AgentOperationInvocation, 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 {
@@ -6,7 +6,10 @@ export interface AgentProviderConformanceScenario {
     readonly definition: AgentProviderInstanceDefinition;
     readonly workingDirectory: string;
     readonly configuration: AgentSessionConfiguration;
-    readonly updatedConfiguration?: AgentSessionConfiguration;
+    readonly configurationSelection?: AgentConfigurationSelectionInput;
+    readonly operationInvocation?: AgentOperationInvocation;
+    readonly collaborationSpawn?: AgentCollaborationSpawnInput;
+    readonly generatedResourceId?: AgentGeneratedResourceId;
     readonly createSessionId: AgentSessionId;
     readonly resumeSessionId: AgentSessionId;
     readonly branchSessionId?: AgentSessionId;

package/dist/testing/conformance.js

@@ -275,12 +275,24 @@ async function runAgentProviderConformance(scenario) {
     checks.push("interruption");
     if (instance.capabilities.configuration.kind === "selectable") {
       requireCheck(
-        created.configuration.kind === "selectable" && scenario.updatedConfiguration !== void 0,
+        created.configuration.kind === "selectable" && scenario.configurationSelection !== void 0,
         "configuration",
-        "Selectable configuration requires a handler and updated fixture."
+        "Selectable configuration requires a handler and selection fixture."
       );
-      const result = await created.configuration.applyConfiguration({
-        configuration: scenario.updatedConfiguration
+      const catalog = await created.configuration.listConfiguration();
+      requireCheck(
+        catalog.fields.some(
+          (field) => field.key === scenario.configurationSelection?.key
+        ),
+        "configuration",
+        "Configuration catalog did not offer the selected field."
+      );
+      let executionStarted = 0;
+      const result = await created.configuration.applyConfigurationSelection({
+        selection: scenario.configurationSelection,
+        onProviderExecutionStarted: () => {
+          executionStarted += 1;
+        }
       });
       requireOperationStatus(
         result,
@@ -288,6 +300,11 @@ async function runAgentProviderConformance(scenario) {
         "configuration",
         "Selectable configuration did not complete atomically."
       );
+      requireCheck(
+        executionStarted === 1,
+        "configuration",
+        "Configuration selection did not report exactly one execution start."
+      );
     } else {
       requireCheck(
         created.configuration.kind === "managed",
@@ -296,6 +313,146 @@ async function runAgentProviderConformance(scenario) {
       );
     }
     checks.push("configuration");
+    if (instance.capabilities.operations.kind === "supported") {
+      requireCheck(
+        created.operations.kind === "supported" && scenario.operationInvocation !== void 0,
+        "operations",
+        "Supported operations require matching ports and an invocation fixture."
+      );
+      const catalog = await created.operations.listOperations();
+      requireCheck(
+        catalog.operations.some(
+          (operation) => operation.operationId === scenario.operationInvocation?.operationId
+        ),
+        "operations",
+        "Operation catalog did not offer the invocation fixture."
+      );
+      let executionStarted = 0;
+      const result = await created.operations.invokeOperation({
+        invocation: scenario.operationInvocation,
+        onProviderExecutionStarted: () => {
+          executionStarted += 1;
+        }
+      });
+      requireCheck(
+        result.status === "completed" && executionStarted === 1,
+        "operations",
+        "Operation invocation did not complete with one execution-start receipt."
+      );
+    } else {
+      requireCheck(
+        created.operations.kind === "unsupported",
+        "operations",
+        "Unsupported operations exposed callable ports."
+      );
+    }
+    checks.push("operations");
+    if (instance.capabilities.managedContent.kind === "supported") {
+      requireCheck(
+        created.managedContent.kind === "supported",
+        "managed_content",
+        "Supported managed content has no inventory port."
+      );
+      await created.managedContent.listManagedContent();
+    } else {
+      requireCheck(
+        created.managedContent.kind === "unsupported",
+        "managed_content",
+        "Unsupported managed content exposed an inventory port."
+      );
+    }
+    checks.push("managed_content");
+    if (instance.capabilities.integrations.kind === "supported") {
+      requireCheck(
+        created.integrations.kind === "supported",
+        "integrations",
+        "Supported integrations have no observation port."
+      );
+      await created.integrations.observeIntegrations();
+    } else {
+      requireCheck(
+        created.integrations.kind === "unsupported",
+        "integrations",
+        "Unsupported integrations exposed an observation port."
+      );
+    }
+    checks.push("integrations");
+    if (instance.capabilities.collaboration.kind === "supported") {
+      requireCheck(
+        created.collaboration.kind === "supported" && scenario.collaborationSpawn !== void 0,
+        "collaboration",
+        "Supported collaboration requires matching ports and a spawn fixture."
+      );
+      let executionStarted = 0;
+      const spawned = await created.collaboration.spawnCollaboration({
+        spawn: scenario.collaborationSpawn,
+        onProviderExecutionStarted: () => {
+          executionStarted += 1;
+        }
+      });
+      const stopped = await created.collaboration.controlCollaboration({
+        control: {
+          action: "stop",
+          collaborationId: spawned.collaborationId,
+          reason: "user_requested"
+        },
+        onProviderExecutionStarted: () => {
+          executionStarted += 1;
+        }
+      });
+      const closed = await created.collaboration.controlCollaboration({
+        control: {
+          action: "close",
+          collaborationId: stopped.collaborationId
+        },
+        onProviderExecutionStarted: () => {
+          executionStarted += 1;
+        }
+      });
+      const replayedClose = await created.collaboration.controlCollaboration({
+        control: {
+          action: "close",
+          collaborationId: stopped.collaborationId
+        },
+        onProviderExecutionStarted: () => {
+          executionStarted += 1;
+        }
+      });
+      requireCheck(
+        closed.status === "canceled" && closed.outcome?.kind === "canceled" && closed.closedAt !== void 0 && replayedClose === closed && executionStarted === 3,
+        "collaboration",
+        "Collaboration lifecycle did not preserve control and execution receipts."
+      );
+    } else {
+      requireCheck(
+        created.collaboration.kind === "unsupported",
+        "collaboration",
+        "Unsupported collaboration exposed callable ports."
+      );
+    }
+    checks.push("collaboration");
+    if (instance.capabilities.generatedResources.kind === "supported") {
+      requireCheck(
+        created.generatedResources.kind === "supported" && scenario.generatedResourceId !== void 0,
+        "generated_resources",
+        "Supported generated resources require an access port and fixture."
+      );
+      const resource = await created.generatedResources.getGeneratedResource({
+        resourceId: scenario.generatedResourceId
+      });
+      requireCheck(
+        resource.descriptor.resourceId === scenario.generatedResourceId,
+        "generated_resources",
+        "Generated resource access returned another resource."
+      );
+    } else {
+      requireCheck(
+        created.generatedResources.kind === "unsupported",
+        "generated_resources",
+        "Unsupported generated resources exposed an access port."
+      );
+    }
+    checks.push("generated_resources");
     await created.close({ reason: "idle" });
     await created.close({ reason: "idle" });
     checks.push("idempotent_session_close");

package/dist/testing/fakeProvider.js

@@ -3,6 +3,7 @@ import {
   parseAgentInstanceId,
   parseAgentIsoDateTime,
   parseAgentItemId,
+  parseAgentOperationId,
   parseAgentApprovalOptionId,
   parseAgentProviderConversationId,
   parseAgentProviderHistoryAnchor,
@@ -35,7 +36,7 @@ function defaultCapabilities(providerKey) {
     }
   };
   return parseAgentCapabilities({
-    protocolVersion: 7,
+    protocolVersion: 8,
     providerKey,
     sessions: { create: true, resume: true, branch: { kind: "through_turn" } },
     turns: {
@@ -48,7 +49,18 @@ function defaultCapabilities(providerKey) {
         kind: "supported",
         modes: [{ persistence: "once", scopeKinds: ["exact_action"] }]
       },
-      elicitation: { kind: "structured" }
+      elicitation: {
+        kind: "supported",
+        fieldKinds: [
+          "text",
+          "single_select",
+          "multi_select",
+          "boolean",
+          "confirmation"
+        ],
+        maxFields: 16,
+        sensitiveFields: true
+      }
     },
     context: {
       usage: { kind: "unsupported" },
@@ -63,19 +75,61 @@ function defaultCapabilities(providerKey) {
     },
     configuration: {
       kind: "selectable",
-      fields: [
-        { key: "mode", optionIds: ["agent"] },
-        {
-          key: "model",
-          optionIds: ["fake-model", "fake-model-2"]
-        }
-      ]
+      fieldKinds: [
+        "boolean",
+        "single_select",
+        "bounded_integer",
+        "bounded_text"
+      ],
+      maxFields: 100
+    },
+    operations: {
+      kind: "supported",
+      operationKinds: [
+        "session_control",
+        "managed_content_invoke",
+        "configuration_select",
+        "integration_control",
+        "collaboration_control",
+        "resource_generate"
+      ],
+      fieldKinds: [
+        "text",
+        "boolean",
+        "single_select",
+        "multi_select",
+        "integer"
+      ],
+      executionModes: ["immediate", "request_continuation", "durable_job"],
+      maxOperations: 100,
+      maxFieldsPerOperation: 16
     },
-    interactionExtensions: {
-      slashCommands: false,
-      mcp: false,
-      subagents: false,
-      imageGeneration: false
+    managedContent: {
+      kind: "supported",
+      contentKinds: ["skill", "rule", "prompt", "agent_definition"],
+      maxEntries: 100
+    },
+    integrations: {
+      kind: "supported",
+      integrationKinds: ["mcp"],
+      maxIntegrations: 32,
+      maxServersPerIntegration: 32,
+      maxToolsPerServer: 100,
+      maxResourcesPerServer: 100
+    },
+    collaboration: {
+      kind: "supported",
+      roles: ["delegate", "reviewer", "researcher", "specialist"],
+      controlActions: ["spawn", "steer", "stop", "close", "inspect"],
+      maxDepth: 8,
+      maxChildrenPerNode: 16,
+      maxActiveNodes: 64
+    },
+    generatedResources: {
+      kind: "supported",
+      resourceKinds: ["image", "document", "archive"],
+      maxResourcesPerTurn: 16,
+      maxBytesPerResource: 25 * 1024 * 1024
     },
     authentication: { kind: "unsupported" },
     versionReporting: true
@@ -93,7 +147,7 @@ function sessionBinding(state, sessionId) {
   };
 }
 function eventBase(sessionId, turnId, occurredAt) {
-  return { protocolVersion: 7, sessionId, turnId, occurredAt };
+  return { protocolVersion: 8, sessionId, turnId, occurredAt };
 }
 function requestForTurn(turnId) {
   return {
@@ -131,6 +185,13 @@ function completedResult(outputs = []) {
 }
 function fakeSession(input) {
   const pendingRequests = /* @__PURE__ */ new Map();
+  const collaborationNodes = /* @__PURE__ */ new Map();
+  const nextCollaborationObservedAt = (previous) => {
+    const observed = input.now();
+    return Date.parse(observed) > Date.parse(previous) ? observed : parseAgentIsoDateTime(
+      new Date(Date.parse(previous) + 1).toISOString()
+    );
+  };
   let closed = false;
   const runTurn = async function* (turnInput) {
     throwIfAgentOperationAborted(turnInput.signal);
@@ -256,14 +317,156 @@ function fakeSession(input) {
     } : { kind: "unsupported" },
     configuration: input.capabilities.configuration.kind === "selectable" ? {
       kind: "selectable",
-      applyConfiguration: async (configurationInput) => {
+      listConfiguration: async (listInput = {}) => {
+        throwIfAgentOperationAborted(listInput.signal);
+        return {
+          revision: 1,
+          fields: [{
+            key: "model",
+            revision: 1,
+            label: "Model",
+            scope: "session",
+            applicationTiming: "next_session",
+            mutable: true,
+            fieldKind: "single_select",
+            currentValue: "fake-model",
+            options: [
+              { optionId: "fake-model", label: "Fake model" },
+              { optionId: "fake-model-2", label: "Fake model 2" }
+            ]
+          }]
+        };
+      },
+      applyConfigurationSelection: async (configurationInput) => {
         throwIfAgentOperationAborted(configurationInput.signal);
+        configurationInput.onProviderExecutionStarted?.();
         input.state.configurationRevisions.push(
-          configurationInput.configuration.revision
+          `${configurationInput.selection.expectedCatalogRevision}:${configurationInput.selection.key}`
         );
         return completedResult();
       }
     } : { kind: "managed" },
+    operations: input.capabilities.operations.kind === "supported" ? {
+      kind: "supported",
+      listOperations: async (listInput = {}) => {
+        throwIfAgentOperationAborted(listInput.signal);
+        return {
+          revision: 1,
+          operations: [{
+            operationId: parseAgentOperationId("fake.session.reset"),
+            revision: 1,
+            kind: "session_control",
+            title: "Reset fake session",
+            context: "session",
+            timing: "idle_session",
+            executionMode: "immediate",
+            fields: [],
+            confirmation: "required",
+            idempotency: "required",
+            resultKind: "none"
+          }]
+        };
+      },
+      invokeOperation: async (operationInput) => {
+        throwIfAgentOperationAborted(operationInput.signal);
+        operationInput.onProviderExecutionStarted?.();
+        return {
+          invocationId: operationInput.invocation.invocationId,
+          status: "completed"
+        };
+      }
+    } : { kind: "unsupported" },
+    managedContent: input.capabilities.managedContent.kind === "supported" ? {
+      kind: "supported",
+      listManagedContent: async (listInput = {}) => {
+        throwIfAgentOperationAborted(listInput.signal);
+        return { revision: 1, entries: [] };
+      }
+    } : { kind: "unsupported" },
+    integrations: input.capabilities.integrations.kind === "supported" ? {
+      kind: "supported",
+      observeIntegrations: async (listInput = {}) => {
+        throwIfAgentOperationAborted(listInput.signal);
+        return {
+          revision: 1,
+          observedAt: input.now(),
+          integrations: []
+        };
+      }
+    } : { kind: "unsupported" },
+    collaboration: input.capabilities.collaboration.kind === "supported" ? {
+      kind: "supported",
+      spawnCollaboration: async (collaborationInput) => {
+        throwIfAgentOperationAborted(collaborationInput.signal);
+        collaborationInput.onProviderExecutionStarted?.();
+        const parent = collaborationInput.spawn.parentCollaborationId === void 0 ? void 0 : collaborationNodes.get(
+          collaborationInput.spawn.parentCollaborationId
+        );
+        const now = nextCollaborationObservedAt(
+          collaborationInput.spawn.createdAt
+        );
+        const node = {
+          collaborationId: collaborationInput.spawn.collaborationId,
+          rootCollaborationId: parent?.rootCollaborationId ?? collaborationInput.spawn.collaborationId,
+          ...collaborationInput.spawn.parentCollaborationId === void 0 ? {} : {
+            parentCollaborationId: collaborationInput.spawn.parentCollaborationId
+          },
+          role: collaborationInput.spawn.role,
+          title: collaborationInput.spawn.title,
+          status: "running",
+          objective: collaborationInput.spawn.objective,
+          usage: { kind: "unavailable" },
+          createdAt: collaborationInput.spawn.createdAt,
+          updatedAt: now
+        };
+        collaborationNodes.set(node.collaborationId, node);
+        return node;
+      },
+      controlCollaboration: async (collaborationInput) => {
+        throwIfAgentOperationAborted(collaborationInput.signal);
+        collaborationInput.onProviderExecutionStarted?.();
+        const previous = collaborationNodes.get(
+          collaborationInput.control.collaborationId
+        );
+        if (previous === void 0) {
+          throw new TypeError("Fake collaboration does not exist.");
+        }
+        const now = nextCollaborationObservedAt(previous.updatedAt);
+        const node = {
+          ...previous,
+          updatedAt: now,
+          ...collaborationInput.control.action === "stop" ? {
+            status: "canceled",
+            terminalAt: previous.terminalAt ?? now,
+            outcome: {
+              kind: "canceled",
+              reason: collaborationInput.control.reason
+            }
+          } : collaborationInput.control.action === "close" ? { closedAt: previous.closedAt ?? now } : {}
+        };
+        collaborationNodes.set(node.collaborationId, node);
+        return node;
+      }
+    } : { kind: "unsupported" },
+    generatedResources: input.capabilities.generatedResources.kind === "supported" ? {
+      kind: "supported",
+      getGeneratedResource: async (resourceInput) => {
+        throwIfAgentOperationAborted(resourceInput.signal);
+        return {
+          descriptor: {
+            resourceId: resourceInput.resourceId,
+            kind: "image",
+            status: "pending",
+            displayName: "Fake generated resource",
+            producer: {
+              kind: "session",
+              sessionId: input.context.sessionId
+            },
+            createdAt: input.now()
+          }
+        };
+      }
+    } : { kind: "unsupported" },
     close
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agen-ai/agent-runtime",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "private": false,
   "description": "Provider-neutral driver, instance, adapter, session, output, and conformance contracts for coding-agent runtimes.",
   "type": "module",
@@ -27,7 +27,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@agen-ai/agent-protocol": "^0.2.2"
+    "@agen-ai/agent-protocol": "^0.2.3"
   },
   "devDependencies": {
     "tsup": "^8.5.0"