@agen-ai/agent-runtime 0.2.5 → 0.3.1

package/dist/sessionValidation.js

@@ -1,5 +1,7 @@
 import {
   AGENT_COLLABORATION_GRAPH_LIMITS,
+  AGENT_CONTENT_REFERENCES_MAX_LENGTH,
+  findAgentContentReferenceTextIssue,
   matchesAgentSessionBinding,
   parseAgentCollaborationControlInput,
   parseAgentCollaborationSpawnInput,
@@ -18,11 +20,11 @@ import {
 import {
   createAgentArtifactCandidate
 } from "./artifacts.js";
+import { validateAgentEnvironmentObservationPort } from "./environment/validation.js";
 import {
   validateAgentCollaborationNodeForCapabilities,
   validateAgentConfigurationCatalogForCapabilities,
   validateAgentGeneratedResourceForCapabilities,
-  validateAgentIntegrationCatalogForCapabilities,
   validateAgentManagedContentCatalogForCapabilities,
   validateAgentOperationCatalogForCapabilities,
   validateAgentOperationResultForInvocation,
@@ -57,11 +59,11 @@ function validateSessionPorts(capabilities, session) {
     "configuration",
     "operations",
     "managedContent",
-    "integrations",
+    "environment",
     "collaboration",
     "generatedResources",
     "close"
-  ]) || typeof session.runTurn !== "function" || typeof session.resolveRequest !== "function" || typeof session.close !== "function" || session.interruption === null || typeof session.interruption !== "object" || !["supported", "unsupported"].includes(session.interruption.kind) || session.steering === null || typeof session.steering !== "object" || !["supported", "unsupported"].includes(session.steering.kind) || session.configuration === null || typeof session.configuration !== "object" || !["managed", "selectable"].includes(session.configuration.kind) || session.operations === null || typeof session.operations !== "object" || !["supported", "unsupported"].includes(session.operations.kind) || session.managedContent === null || typeof session.managedContent !== "object" || !["supported", "unsupported"].includes(session.managedContent.kind) || session.integrations === null || typeof session.integrations !== "object" || !["supported", "unsupported"].includes(session.integrations.kind) || session.collaboration === null || typeof session.collaboration !== "object" || !["supported", "unsupported"].includes(session.collaboration.kind) || session.generatedResources === null || typeof session.generatedResources !== "object" || !["supported", "unsupported"].includes(session.generatedResources.kind)) {
+  ]) || typeof session.runTurn !== "function" || typeof session.resolveRequest !== "function" || typeof session.close !== "function" || session.interruption === null || typeof session.interruption !== "object" || !["supported", "unsupported"].includes(session.interruption.kind) || session.steering === null || typeof session.steering !== "object" || !["supported", "unsupported"].includes(session.steering.kind) || session.configuration === null || typeof session.configuration !== "object" || !["managed", "selectable"].includes(session.configuration.kind) || session.operations === null || typeof session.operations !== "object" || !["supported", "unsupported"].includes(session.operations.kind) || session.managedContent === null || typeof session.managedContent !== "object" || !["supported", "unsupported"].includes(session.managedContent.kind) || session.environment === null || typeof session.environment !== "object" || !["read", "read_and_watch", "unsupported"].includes(session.environment.kind) || session.collaboration === null || typeof session.collaboration !== "object" || !["supported", "unsupported"].includes(session.collaboration.kind) || session.generatedResources === null || typeof session.generatedResources !== "object" || !["supported", "unsupported"].includes(session.generatedResources.kind)) {
     throwAgentProviderContractError(
       capabilities.providerKey,
       "invalid_session",
@@ -84,15 +86,15 @@ function validateSessionPorts(capabilities, session) {
     session.managedContent,
     session.managedContent.kind === "supported" ? ["kind", "listManagedContent"] : ["kind"]
   ) || !hasExactOwnKeys(
-    session.integrations,
-    session.integrations.kind === "supported" ? ["kind", "observeIntegrations"] : ["kind"]
+    session.environment,
+    session.environment.kind === "unsupported" ? ["kind"] : session.environment.kind === "read" ? ["kind", "domains", "readEnvironment"] : ["kind", "domains", "readEnvironment", "watchEnvironment"]
   ) || !hasExactOwnKeys(
     session.collaboration,
     session.collaboration.kind === "supported" ? ["kind", "spawnCollaboration", "controlCollaboration"] : ["kind"]
   ) || !hasExactOwnKeys(
     session.generatedResources,
     session.generatedResources.kind === "supported" ? ["kind", "getGeneratedResource"] : ["kind"]
-  ) || session.interruption.kind === "supported" !== capabilities.turns.interrupt || session.steering.kind === "supported" !== (capabilities.turns.steer.kind === "supported") || session.configuration.kind !== capabilities.configuration.kind || session.interruption.kind === "supported" && typeof session.interruption.interruptTurn !== "function" || session.steering.kind === "supported" && typeof session.steering.steerTurn !== "function" || session.configuration.kind === "selectable" && (typeof session.configuration.listConfiguration !== "function" || typeof session.configuration.applyConfigurationSelection !== "function") || session.operations.kind === "supported" !== (capabilities.operations.kind === "supported") || session.operations.kind === "supported" && (typeof session.operations.listOperations !== "function" || typeof session.operations.invokeOperation !== "function") || session.managedContent.kind === "supported" !== (capabilities.managedContent.kind === "supported") || session.managedContent.kind === "supported" && typeof session.managedContent.listManagedContent !== "function" || session.integrations.kind === "supported" !== (capabilities.integrations.kind === "supported") || session.integrations.kind === "supported" && typeof session.integrations.observeIntegrations !== "function" || session.collaboration.kind === "supported" !== (capabilities.collaboration.kind === "supported") || session.collaboration.kind === "supported" && (typeof session.collaboration.spawnCollaboration !== "function" || typeof session.collaboration.controlCollaboration !== "function") || session.generatedResources.kind === "supported" !== (capabilities.generatedResources.kind === "supported") || session.generatedResources.kind === "supported" && typeof session.generatedResources.getGeneratedResource !== "function") {
+  ) || session.interruption.kind === "supported" !== capabilities.turns.interrupt || session.steering.kind === "supported" !== (capabilities.turns.steer.kind === "supported") || session.configuration.kind !== capabilities.configuration.kind || session.interruption.kind === "supported" && typeof session.interruption.interruptTurn !== "function" || session.steering.kind === "supported" && typeof session.steering.steerTurn !== "function" || session.configuration.kind === "selectable" && (typeof session.configuration.listConfiguration !== "function" || typeof session.configuration.applyConfigurationSelection !== "function") || session.operations.kind === "supported" !== (capabilities.operations.kind === "supported") || session.operations.kind === "supported" && (typeof session.operations.listOperations !== "function" || typeof session.operations.invokeOperation !== "function") || session.managedContent.kind === "supported" !== (capabilities.managedContent.kind === "supported") || session.managedContent.kind === "supported" && typeof session.managedContent.listManagedContent !== "function" || session.environment.kind !== capabilities.environment.session.kind || session.environment.kind !== "unsupported" && (typeof session.environment.readEnvironment !== "function" || session.environment.kind === "read_and_watch" && typeof session.environment.watchEnvironment !== "function") || session.collaboration.kind === "supported" !== (capabilities.collaboration.kind === "supported") || session.collaboration.kind === "supported" && (typeof session.collaboration.spawnCollaboration !== "function" || typeof session.collaboration.controlCollaboration !== "function") || session.generatedResources.kind === "supported" !== (capabilities.generatedResources.kind === "supported") || session.generatedResources.kind === "supported" && typeof session.generatedResources.getGeneratedResource !== "function") {
     throwAgentProviderContractError(
       capabilities.providerKey,
       "capability_port_mismatch",
@@ -612,46 +614,75 @@ function clearPendingRequestsForTurn(pendingRequests, turnId) {
 }
 function assertAgentTurnInputCapability(input) {
   const imageParts = input.parts.filter((part) => part.type === "image");
-  if (imageParts.length === 0) return;
-  const imageCapability = input.capability.images;
-  if (imageCapability.kind === "unsupported") {
-    throwAgentProviderContractError(
+  if (imageParts.length > 0) {
+    const imageCapability = input.capability.images;
+    if (imageCapability.kind === "unsupported") {
+      throwAgentProviderContractError(
+        input.providerKey,
+        "input_capability_mismatch",
+        `Provider ${input.providerKey} does not accept image input.`
+      );
+    }
+    const reject = (reason) => throwAgentProviderContractError(
       input.providerKey,
       "input_capability_mismatch",
-      `Provider ${input.providerKey} does not accept image input.`
+      `Provider ${input.providerKey} cannot accept this image input: ${reason}.`
     );
+    if (imageParts.length > imageCapability.maxImages) {
+      reject("image count exceeds the declared limit");
+    }
+    if (!imageCapability.supportsImageOnly && !input.parts.some((part) => part.type === "text" && part.text.trim().length > 0)) {
+      reject("image-only input is unsupported");
+    }
+    let totalBytes = 0;
+    for (const part of imageParts) {
+      const { source } = part;
+      if (!imageCapability.sourceKinds.includes(source.type)) {
+        reject(`source kind ${source.type} is unsupported`);
+      }
+      if (!imageCapability.mediaTypes.includes(source.mediaType)) {
+        reject(`media type ${source.mediaType} is unsupported`);
+      }
+      if (source.byteSize > imageCapability.maxBytesPerImage) {
+        reject("an image exceeds the declared byte limit");
+      }
+      if (source.widthPixels > imageCapability.maxWidthPixels || source.heightPixels > imageCapability.maxHeightPixels || source.widthPixels * source.heightPixels > imageCapability.maxPixelsPerImage) {
+        reject("an image exceeds the declared dimension or pixel limit");
+      }
+      totalBytes += source.byteSize;
+    }
+    if (totalBytes > imageCapability.maxTotalBytes) {
+      reject("aggregate image bytes exceed the declared limit");
+    }
   }
-  const reject = (reason) => throwAgentProviderContractError(
+  const contentReferenceParts = input.parts.filter(
+    (part) => part.type === "content_reference"
+  );
+  if (contentReferenceParts.length === 0) return;
+  const contentReferenceCapability = input.capability.contentReferences;
+  const rejectReference = (reason) => throwAgentProviderContractError(
     input.providerKey,
     "input_capability_mismatch",
-    `Provider ${input.providerKey} cannot accept this image input: ${reason}.`
+    `Provider ${input.providerKey} cannot accept this content reference input: ${reason}.`
   );
-  if (imageParts.length > imageCapability.maxImages) {
-    reject("image count exceeds the declared limit");
+  if (contentReferenceParts.length > AGENT_CONTENT_REFERENCES_MAX_LENGTH) {
+    rejectReference("content reference count exceeds the protocol limit");
   }
-  if (!imageCapability.supportsImageOnly && !input.parts.some((part) => part.type === "text" && part.text.trim().length > 0)) {
-    reject("image-only input is unsupported");
+  if (contentReferenceCapability.kind === "unsupported") {
+    return rejectReference("content references are unsupported");
   }
-  let totalBytes = 0;
-  for (const part of imageParts) {
-    const { source } = part;
-    if (!imageCapability.sourceKinds.includes(source.type)) {
-      reject(`source kind ${source.type} is unsupported`);
-    }
-    if (!imageCapability.mediaTypes.includes(source.mediaType)) {
-      reject(`media type ${source.mediaType} is unsupported`);
-    }
-    if (source.byteSize > imageCapability.maxBytesPerImage) {
-      reject("an image exceeds the declared byte limit");
-    }
-    if (source.widthPixels > imageCapability.maxWidthPixels || source.heightPixels > imageCapability.maxHeightPixels || source.widthPixels * source.heightPixels > imageCapability.maxPixelsPerImage) {
-      reject("an image exceeds the declared dimension or pixel limit");
-    }
-    totalBytes += source.byteSize;
+  if (contentReferenceParts.length > contentReferenceCapability.maxReferences) {
+    rejectReference("content reference count exceeds the declared limit");
   }
-  if (totalBytes > imageCapability.maxTotalBytes) {
-    reject("aggregate image bytes exceed the declared limit");
+  if (!contentReferenceCapability.arguments && contentReferenceParts.some((part) => part.arguments !== void 0)) {
+    rejectReference("reference arguments are unsupported");
   }
+  const textIssue = findAgentContentReferenceTextIssue({
+    prompt: input.parts.filter((part) => part.type === "text").map((part) => part.text).join("\n"),
+    arguments: contentReferenceParts.map((part) => part.arguments ?? ""),
+    textFormats: contentReferenceCapability.textFormats
+  });
+  if (textIssue) rejectReference(`${textIssue.target} must use ${textIssue.format} text`);
 }
 function validateAgentProviderSession(input) {
   const { capabilities, sessionId } = input;
@@ -688,6 +719,13 @@ function validateAgentProviderSession(input) {
     );
   }
   validateSessionPorts(capabilities, input.candidate);
+  const sessionLifetime = new AbortController();
+  const environment = validateAgentEnvironmentObservationPort({
+    providerKey,
+    capability: capabilities.environment.session,
+    port: input.candidate.environment,
+    signal: sessionLifetime.signal
+  });
   const pendingRequests = /* @__PURE__ */ new Map();
   const waitingTurnStates = /* @__PURE__ */ new Map();
   const openedRequestIds = /* @__PURE__ */ new Set();
@@ -1331,20 +1369,6 @@ function validateAgentProviderSession(input) {
       );
     }
   });
-  const declaredIntegrations = input.candidate.integrations;
-  const integrations = declaredIntegrations.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
-    kind: "supported",
-    observeIntegrations: async (listInput = {}) => {
-      requireUsable();
-      throwIfAgentOperationAborted(listInput.signal);
-      return validateAgentIntegrationCatalogForCapabilities(
-        capabilities,
-        await declaredIntegrations.observeIntegrations(
-          listInput.signal === void 0 ? {} : { signal: listInput.signal }
-        )
-      );
-    }
-  });
   const declaredCollaboration = input.candidate.collaboration;
   const collaboration = declaredCollaboration.kind === "unsupported" ? Object.freeze({ kind: "unsupported" }) : Object.freeze({
     kind: "supported",
@@ -1592,6 +1616,7 @@ function validateAgentProviderSession(input) {
       throw new TypeError("Provider session close reason is unsupported.");
     }
     unusable = true;
+    sessionLifetime.abort(new DOMException("The provider session was closed.", "AbortError"));
     closePromise = Promise.resolve().then(() => input.candidate.close(closeInput)).then(() => {
       closed = true;
     }).finally(() => {
@@ -1608,7 +1633,7 @@ function validateAgentProviderSession(input) {
     configuration,
     operations,
     managedContent,
-    integrations,
+    environment,
     collaboration,
     generatedResources,
     close

package/dist/sessions.d.ts

@@ -1,7 +1,8 @@
-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 { AgentAuthenticationFlow, AgentCollaborationControlInput, AgentCollaborationNode, AgentCollaborationSpawnInput, AgentConfigurationCatalog, AgentConfigurationSelectionInput, AgentError, AgentGeneratedResourceDescriptor, AgentGeneratedResourceId, 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";
+import type { AgentEnvironmentObservationPort } from "./environment/types.js";
 export interface AgentProviderSessionContext {
     readonly sessionId: AgentSessionId;
     readonly workingDirectory: string;
@@ -129,12 +130,6 @@ export type AgentManagedContentInventory = 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<{
@@ -157,7 +152,7 @@ export interface AgentProviderSession {
     readonly configuration: AgentSessionConfigurationControl;
     readonly operations: AgentOperationControl;
     readonly managedContent: AgentManagedContentInventory;
-    readonly integrations: AgentIntegrationObservation;
+    readonly environment: AgentEnvironmentObservationPort;
     readonly collaboration: AgentCollaborationControl;
     readonly generatedResources: AgentGeneratedResourceAccess;
     readonly close: (input: AgentProviderCloseSessionInput) => MaybePromise<void>;

package/dist/testing/conformance.d.ts

@@ -1,4 +1,4 @@
-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 AgentCollaborationSpawnInput, type AgentConfigurationSelectionInput, type AgentEnvironmentId, 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 {
@@ -10,6 +10,7 @@ export interface AgentProviderConformanceScenario {
     readonly operationInvocation?: AgentOperationInvocation;
     readonly collaborationSpawn?: AgentCollaborationSpawnInput;
     readonly generatedResourceId?: AgentGeneratedResourceId;
+    readonly environmentId?: AgentEnvironmentId;
     readonly createSessionId: AgentSessionId;
     readonly resumeSessionId: AgentSessionId;
     readonly branchSessionId?: AgentSessionId;

package/dist/testing/conformance.js

@@ -1,5 +1,6 @@
 import {
   matchesAgentSessionBinding,
+  parseAgentEnvironmentId,
   parseAgentRequestResolutionFor,
   parseAgentTurnId
 } from "@agen-ai/agent-protocol";
@@ -19,6 +20,23 @@ class AgentProviderConformanceError extends Error {
 function requireCheck(condition, check, message) {
   if (!condition) throw new AgentProviderConformanceError(check, message);
 }
+async function checkEnvironmentWatch(input) {
+  const pending = input.iterator.next();
+  await Promise.resolve();
+  input.controller.abort(new DOMException("Conformance watch complete.", "AbortError"));
+  try {
+    const next = await pending;
+    requireCheck(
+      next.done || next.value.environmentId === input.environmentId,
+      input.check,
+      "Environment watch returned a different identity."
+    );
+  } catch (error) {
+    if (!isAgentOperationAbortError(error)) throw error;
+  } finally {
+    await input.iterator.return?.();
+  }
+}
 async function advanceToStartedTurn(session, input) {
   const iterator = session.runTurn(input)[Symbol.asyncIterator]();
   const outputs = [];
@@ -142,6 +160,46 @@ async function runAgentProviderConformance(scenario) {
       requireCheck(aborted2, "account_quota", "Pre-aborted quota work must fail with AbortError.");
     }
     checks.push("account_quota");
+    const environmentId = scenario.environmentId ?? parseAgentEnvironmentId("conformance-environment:instance");
+    if (instance.capabilities.environment.instance.kind === "unsupported") {
+      requireCheck(
+        instance.environment.kind === "unsupported",
+        "environment_instance",
+        "Unsupported instance environment exposed a discovery port."
+      );
+    } else {
+      requireCheck(
+        instance.environment.kind === instance.capabilities.environment.instance.kind,
+        "environment_instance",
+        "Instance environment capability has no matching discovery port."
+      );
+      const readSignal = new AbortController();
+      let executionStarted = 0;
+      const snapshot = await instance.environment.readEnvironment({
+        signal: readSignal.signal,
+        environmentId,
+        workingDirectory: scenario.workingDirectory,
+        configuration: scenario.configuration,
+        onProviderExecutionStarted: () => {
+          executionStarted += 1;
+        }
+      });
+      requireCheck(
+        snapshot.environmentId === environmentId && executionStarted === 1,
+        "environment_instance",
+        "Instance environment discovery did not echo its identity and start receipt."
+      );
+      if (instance.environment.kind === "read_and_watch") {
+        const iterator = instance.environment.watchEnvironment({
+          signal: readSignal.signal,
+          environmentId,
+          workingDirectory: scenario.workingDirectory,
+          configuration: scenario.configuration
+        })[Symbol.asyncIterator]();
+        await checkEnvironmentWatch({ iterator, controller: readSignal, environmentId, check: "environment_instance" });
+      }
+    }
+    checks.push("environment_instance");
     let createdBindingCount = 0;
     const created = await instance.adapter.createSession({
       sessionId: scenario.createSessionId,
@@ -158,6 +216,41 @@ async function runAgentProviderConformance(scenario) {
       "Create session did not report exactly one binding."
     );
     checks.push("create_session", "binding_callback");
+    if (instance.capabilities.environment.session.kind === "unsupported") {
+      requireCheck(
+        created.environment.kind === "unsupported",
+        "environment_session",
+        "Unsupported session environment exposed an observation port."
+      );
+    } else {
+      requireCheck(
+        created.environment.kind === instance.capabilities.environment.session.kind,
+        "environment_session",
+        "Session environment capability has no matching observation port."
+      );
+      const readSignal = new AbortController();
+      let executionStarted = 0;
+      const snapshot = await created.environment.readEnvironment({
+        signal: readSignal.signal,
+        environmentId,
+        onProviderExecutionStarted: () => {
+          executionStarted += 1;
+        }
+      });
+      requireCheck(
+        snapshot.environmentId === environmentId && executionStarted === 1,
+        "environment_session",
+        "Session environment observation did not echo its identity and start receipt."
+      );
+      if (created.environment.kind === "read_and_watch") {
+        const iterator = created.environment.watchEnvironment({
+          signal: readSignal.signal,
+          environmentId
+        })[Symbol.asyncIterator]();
+        await checkEnvironmentWatch({ iterator, controller: readSignal, environmentId, check: "environment_session" });
+      }
+    }
+    checks.push("environment_session");
     const aborted = new AbortController();
     aborted.abort(new DOMException("Conformance abort.", "AbortError"));
     try {
@@ -386,21 +479,6 @@ async function runAgentProviderConformance(scenario) {
       );
     }
     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,

package/dist/testing/fakeProvider.d.ts

@@ -22,6 +22,8 @@ export interface FakeAgentProviderSnapshot {
     readonly interruptedTurnIds: readonly AgentTurnId[];
     readonly steeringInputs: readonly FakeAgentSteeringInput[];
     readonly configurationRevisions: readonly string[];
+    readonly environmentReadIds: readonly string[];
+    readonly environmentInvalidationIds: readonly string[];
     readonly closeCounts: Readonly<Record<string, number>>;
 }
 export interface FakeAgentProvider {

package/dist/testing/fakeProvider.js

@@ -1,4 +1,6 @@
 import {
+  AGENT_ENVIRONMENT_DOMAINS,
+  parseAgentEnvironmentSnapshot,
   parseAgentCapabilities,
   parseAgentInstanceId,
   parseAgentIsoDateTime,
@@ -33,10 +35,16 @@ function defaultCapabilities(providerKey) {
       maxHeightPixels: 6e3,
       maxPixelsPerImage: 36e6,
       supportsImageOnly: true
+    },
+    contentReferences: {
+      kind: "supported",
+      maxReferences: 16,
+      arguments: true,
+      textFormats: { prompt: "unrestricted", arguments: "unrestricted" }
     }
   };
   return parseAgentCapabilities({
-    protocolVersion: 8,
+    protocolVersion: 9,
     providerKey,
     sessions: { create: true, resume: true, branch: { kind: "through_turn" } },
     turns: {
@@ -117,6 +125,16 @@ function defaultCapabilities(providerKey) {
       maxToolsPerServer: 100,
       maxResourcesPerServer: 100
     },
+    environment: {
+      instance: {
+        kind: "read_and_watch",
+        domains: [...AGENT_ENVIRONMENT_DOMAINS]
+      },
+      session: {
+        kind: "read_and_watch",
+        domains: [...AGENT_ENVIRONMENT_DOMAINS]
+      }
+    },
     collaboration: {
       kind: "supported",
       roles: ["delegate", "reviewer", "researcher", "specialist"],
@@ -147,7 +165,76 @@ function sessionBinding(state, sessionId) {
   };
 }
 function eventBase(sessionId, turnId, occurredAt) {
-  return { protocolVersion: 8, sessionId, turnId, occurredAt };
+  return { protocolVersion: 9, sessionId, turnId, occurredAt };
+}
+function fakeEnvironmentSnapshot(environmentId) {
+  return parseAgentEnvironmentSnapshot({
+    schemaVersion: 1,
+    environmentId,
+    revision: 1,
+    content: { kind: "unavailable", reasons: ["transient_failure"] },
+    commands: { kind: "unavailable", reasons: ["transient_failure"] },
+    extensions: { kind: "unavailable", reasons: ["transient_failure"] },
+    integrations: { kind: "unavailable", reasons: ["transient_failure"] }
+  });
+}
+function fakeDiscoveryEnvironment(state, capability) {
+  if (capability.kind === "unsupported") return { kind: "unsupported" };
+  const domains = Object.freeze([
+    ...capability.domains
+  ]);
+  const readEnvironment = async ({ signal, environmentId }) => {
+    throwIfAgentOperationAborted(signal);
+    state.environmentReadIds.push(environmentId);
+    return fakeEnvironmentSnapshot(environmentId);
+  };
+  const watchEnvironment = async function* ({ signal, environmentId }) {
+    throwIfAgentOperationAborted(signal);
+    state.environmentInvalidationIds.push(environmentId);
+    yield { environmentId, domains: ["content"] };
+  };
+  if (capability.kind === "read") {
+    return {
+      kind: "read",
+      domains,
+      readEnvironment
+    };
+  }
+  return {
+    kind: "read_and_watch",
+    domains,
+    readEnvironment,
+    watchEnvironment
+  };
+}
+function fakeObservationEnvironment(state, capability) {
+  if (capability.kind === "unsupported") return { kind: "unsupported" };
+  const domains = Object.freeze([
+    ...capability.domains
+  ]);
+  const readEnvironment = async ({ signal, environmentId }) => {
+    throwIfAgentOperationAborted(signal);
+    state.environmentReadIds.push(environmentId);
+    return fakeEnvironmentSnapshot(environmentId);
+  };
+  const watchEnvironment = async function* ({ signal, environmentId }) {
+    throwIfAgentOperationAborted(signal);
+    state.environmentInvalidationIds.push(environmentId);
+    yield { environmentId, domains: ["content"] };
+  };
+  if (capability.kind === "read") {
+    return {
+      kind: "read",
+      domains,
+      readEnvironment
+    };
+  }
+  return {
+    kind: "read_and_watch",
+    domains,
+    readEnvironment,
+    watchEnvironment
+  };
 }
 function requestForTurn(turnId) {
   return {
@@ -383,17 +470,10 @@ function fakeSession(input) {
         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" },
+    environment: fakeObservationEnvironment(
+      input.state,
+      input.capabilities.environment.session
+    ),
     collaboration: input.capabilities.collaboration.kind === "supported" ? {
       kind: "supported",
       spawnCollaboration: async (collaborationInput) => {
@@ -537,6 +617,8 @@ function createFakeAgentProvider(options = {}) {
     interruptedTurnIds: [],
     steeringInputs: [],
     configurationRevisions: [],
+    environmentReadIds: [],
+    environmentInvalidationIds: [],
     closeCounts: /* @__PURE__ */ new Map()
   };
   const driver = defineAgentProviderDriver({
@@ -555,6 +637,10 @@ function createFakeAgentProvider(options = {}) {
         instanceId: createdInstanceId,
         capabilities,
         adapter: fakeAdapter({ state, capabilities, now, steeringResult }),
+        environment: fakeDiscoveryEnvironment(
+          state,
+          capabilities.environment.instance
+        ),
         accountQuota: options.accountQuota ?? { kind: "unsupported" },
         checkReadiness: () => createAgentProviderReadiness({
           status: "ready",
@@ -591,6 +677,10 @@ function createFakeAgentProvider(options = {}) {
       configurationRevisions: Object.freeze([
         ...state.configurationRevisions
       ]),
+      environmentReadIds: Object.freeze([...state.environmentReadIds]),
+      environmentInvalidationIds: Object.freeze([
+        ...state.environmentInvalidationIds
+      ]),
       closeCounts: Object.freeze(Object.fromEntries(state.closeCounts))
     })
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agen-ai/agent-runtime",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "private": false,
   "description": "Provider-neutral driver, instance, adapter, session, output, and conformance contracts for coding-agent runtimes.",
   "type": "module",
@@ -24,10 +24,14 @@
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./environment": {
+      "types": "./dist/environment/index.d.ts",
+      "import": "./dist/environment/index.js"
+    }
   },
   "dependencies": {
-    "@agen-ai/agent-protocol": "^0.2.5"
+    "@agen-ai/agent-protocol": "^0.3.1"
   },
   "devDependencies": {
     "tsup": "^8.5.0"