@agen-ai/agent-runtime 0.2.4 → 0.3.0

package/README.md

@@ -3,20 +3,22 @@
 `@agen-ai/agent-runtime` is the process-local service-provider interface for coding-agent
 implementations. It preserves a small ownership chain: a driver parses host configuration and
 materializes an instance; the instance owns one opaque ID, technical capabilities, an adapter,
-readiness, and disposal; the adapter opens provider-native sessions; each returned session owns
-its binding and conversation-local operations.
+account-quota and environment discovery ports, readiness, and disposal; the adapter opens provider-native
+sessions; each returned session owns its binding and conversation-local operations.
 
 The runtime depends only on `@agen-ai/agent-protocol`. It has no concept of tenants, SaaS
 workspaces, assigned users, database rows, persistence sequence, visibility, billing, host boots,
 leases, or storage policy. A host must authorize and select an instance before calling this SPI.
-This source package implements Agent Protocol V8. Agent Protocol V8, private host V16/catalog V10, and Workspaces event V10.
-This is intentionally one coordinated tuple rather than a deployable mixed-version graph.
+This source package implements Agent Protocol V9 as part of the coordinated SDK `0.3.0` contract.
+The SDK contract version is independent of private transport and product persistence versions. This
+is intentionally one coordinated tuple rather than a deployable mixed-version graph.
 
 ## Entrypoints
 
 - `@agen-ai/agent-runtime` exports the public driver, instance, adapter, session, output,
-  readiness, bounded-evidence, artifact-candidate, capability-bound interaction validation,
-  and registry APIs.
+  readiness, account-quota port validation, bounded-evidence, artifact-candidate,
+  capability-bound interaction validation, and registry APIs.
+- `@agen-ai/agent-runtime/environment` exports the instance discovery and session observation ports.
 - `@agen-ai/agent-runtime/testing` exports the deterministic fake provider and reusable
   conformance runner.
 
@@ -41,13 +43,24 @@ exactly once before returning the matching session. Capability-dependent operati
 `supported`/`unsupported` discriminants, and the runtime rejects handlers that disagree with the
 instance capability declaration.
 
-V8 replaces interaction-extension booleans with cohesive capability-matched session ports:
+Sessions expose cohesive capability-matched ports:
 configuration inventory and selection, typed operation inventory and invocation, managed-content
-inventory, integration observation, collaboration spawn/control, and generated-resource access.
+inventory, environment observation, collaboration spawn/control, and generated-resource access.
 An unsupported declaration exposes exactly `{ kind: "unsupported" }`; a supported declaration must
 expose exactly its typed handlers. Catalogs and results are parsed again at the runtime boundary,
 bounded by the declaration, and correlated to the offered revision and caller-owned identity.
 
+Account-quota observation is an instance port beside the session adapter. Its four exact variants
+are `unsupported`, `query`, `observe`, and `query_and_observe`; supported variants must expose all
+methods named by their kind. Every operation receives an `AbortSignal`. The registry combines that
+caller signal with the materialized-instance lifetime, parses every returned snapshot, closes an
+observation iterator on cancellation or disposal, and preserves provider errors. Quota reads are
+replaceable account state and never become model prompts, conversation events, turn output, or
+execution authorization. A malformed or unavailable quota result cannot invalidate an otherwise
+usable session.
+
+Explicit iterator return and normal end join native cleanup for at most 1,000 ms; cleanup failure or timeout is observable. Cancellation or an existing provider failure keeps its original error while cleanup is still attempted. Iterator closure aborts its producer and removes listeners, and late native rejections remain observed.
+
 Approval continuations are refusal-first. Before delegating to the candidate adapter, the
 validated session proves that the request is still pending and unexpired and that a selected
 `optionId` was offered by that exact request. Provider-emitted approval requests must correlate to
@@ -132,7 +145,7 @@ export const driver = defineAgentProviderDriver({
     return input;
   },
   createInstance({ instanceId }): MaterializedAgentProviderInstance {
-    // Construct capabilities, adapter, readiness, and disposal here.
+    // Construct capabilities, adapter, accountQuota, readiness, and disposal here.
     throw new Error(`Implement ${parseAgentInstanceId(instanceId)}.`);
   },
 });
@@ -159,6 +172,26 @@ The runtime distinguishes programmer/contract failures from provider failures:
 Provider-native exceptions should be normalized or safely wrapped at the provider boundary. Do
 not attach credentials, raw prompts, product identities, or unbounded output to public errors.
 
+## Scoped environment observation
+
+`MaterializedAgentProviderInstance.environment` discovers a caller-selected workspace and
+configuration. `AgentProviderSession.environment` observes the already bound session. Both ports
+use exact `unsupported`, `read`, or `read_and_watch` variants and declare their observed domains.
+Unsupported domains cannot expose methods or be returned as available observations.
+
+Every read and watch receives an `AbortSignal` and a caller-supplied `environmentId`; snapshots and
+invalidations must echo that identity. Discovery also requires a canonical absolute working directory
+and validated session configuration. The runtime preserves method receivers and provider exceptions,
+combines caller cancellation with instance/session lifetime, rejects operations after disposal, and
+closes watch iterators with bounded cleanup. It does not accept late yields or concurrent pulls.
+The optional read execution observer runs after prechecks immediately before native delegation.
+An environment metadata error alone does not invalidate an otherwise healthy turn session.
+
+Inventory observation never authorizes invocation. The host owns account/workspace scope, freshness,
+visibility, immutable content admission, and durable mutation authority. Providers should obtain
+registered facts from their native harness and report gaps explicitly; a successful empty inventory
+must not stand in for a failed read. No provider is required to start a model turn for discovery.
+
 ## Conformance and release
 
 Every external driver should run `runAgentProviderConformance` from
@@ -168,13 +201,12 @@ turn/request ordering, request resolution, steering, interruption, configuration
 close, and idempotent disposal. Unsupported operations must remain explicit discriminants and
 must not expose handlers.
 
-The package is at `0.2.4` while the public SPI is being proven with external adapters. Pre-1.0
-releases may include breaking changes during this beta period, and those changes are called out in
-the release notes.
-
-The public runtime implements Agent Protocol V8. Its package version remains independent of private
-host, catalog, persistence, and member-projection versions. V8 directly replaces V7; there is no
-runtime shim or dual-protocol session surface.
+The coordinated SDK version for this source is `0.3.0`, and the source implements Agent Protocol
+V9. The earlier public `0.2.5` release is historical. Upgrade all three SDK packages together. Every materialized instance requires `environment` and
+`accountQuota`; every session requires `environment`. The former standalone `integrations`
+observation port is removed. The public runtime implements Agent Protocol V9 with one current
+adapter/session surface. Package versions remain independent of private transport and product
+persistence versions.
 
 Run the clean packed-consumer proof before any release:
 

package/dist/accountQuota/index.d.ts

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

package/dist/accountQuota/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./validation.js";

package/dist/accountQuota/types.d.ts

@@ -0,0 +1,26 @@
+import type { AgentAccountQuotaSnapshot, AgentProviderKey } from "@agen-ai/agent-protocol";
+import type { MaybePromise } from "../foundation.js";
+export interface AgentAccountQuotaQueryInput {
+    readonly signal: AbortSignal;
+}
+export type AgentAccountQuotaQuery = (input: AgentAccountQuotaQueryInput) => MaybePromise<AgentAccountQuotaSnapshot>;
+export type AgentAccountQuotaObserve = (input: AgentAccountQuotaQueryInput) => AsyncIterable<AgentAccountQuotaSnapshot>;
+export type AgentAccountQuotaPort = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "query";
+    query: AgentAccountQuotaQuery;
+}> | Readonly<{
+    kind: "observe";
+    observe: AgentAccountQuotaObserve;
+}> | Readonly<{
+    kind: "query_and_observe";
+    query: AgentAccountQuotaQuery;
+    observe: AgentAccountQuotaObserve;
+}>;
+export interface ValidateAgentAccountQuotaPortInput {
+    readonly providerKey: AgentProviderKey;
+    readonly port: unknown;
+    readonly signal: AbortSignal;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/accountQuota/validation.d.ts

@@ -0,0 +1,5 @@
+import type { AgentAccountQuotaPort, ValidateAgentAccountQuotaPortInput } from "./types.js";
+/** Maximum time the runtime waits for a provider's native iterator cleanup. */
+export declare const AGENT_ACCOUNT_QUOTA_ITERATOR_CLEANUP_TIMEOUT_MS = 1000;
+export declare function validateAgentAccountQuotaPort(input: ValidateAgentAccountQuotaPortInput): AgentAccountQuotaPort;
+//# sourceMappingURL=validation.d.ts.map

package/dist/accountQuota/validation.js

@@ -0,0 +1,278 @@
+import {
+  parseAgentAccountQuotaSnapshot
+} from "@agen-ai/agent-protocol";
+import { throwAgentProviderContractError } from "../contractErrors.js";
+import { throwIfAgentOperationAborted } from "../foundation.js";
+const AGENT_ACCOUNT_QUOTA_ITERATOR_CLEANUP_TIMEOUT_MS = 1e3;
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function assertSignal(value, field) {
+  if (!(value instanceof AbortSignal)) {
+    throw new TypeError(`Account quota ${field} must be an AbortSignal.`);
+  }
+}
+function exactKeys(value, expected) {
+  const actual = Reflect.ownKeys(value);
+  return actual.length === expected.length && actual.every((key) => typeof key === "string" && expected.includes(key)) && expected.every((key) => Object.prototype.hasOwnProperty.call(value, key));
+}
+function contractError(providerKey, detail) {
+  return throwAgentProviderContractError(
+    providerKey,
+    "capability_port_mismatch",
+    `Provider ${providerKey} returned an invalid account quota ${detail}.`
+  );
+}
+function abortReason(signal) {
+  return signal.reason instanceof Error ? signal.reason : new DOMException("The agent operation was aborted.", "AbortError");
+}
+function awaitCancellable(candidate, signal) {
+  const providerResult = Promise.resolve(candidate);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const remove = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      remove();
+      reject(abortReason(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    providerResult.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        remove();
+        resolve(value);
+      },
+      (error) => {
+        if (settled) return;
+        settled = true;
+        remove();
+        reject(error);
+      }
+    );
+    if (signal.aborted) onAbort();
+  });
+}
+function operationSignal(input) {
+  if (!isObject(input)) {
+    throw new TypeError("Account quota operation input must be an object.");
+  }
+  assertSignal(input.signal, "operation signal");
+  return input.signal;
+}
+function providerIterator(providerKey, iterable) {
+  if (!isObject(iterable)) return contractError(providerKey, "observation");
+  const factory = iterable[Symbol.asyncIterator];
+  if (typeof factory !== "function") return contractError(providerKey, "observation");
+  const iterator = factory.call(iterable);
+  if (!isObject(iterator)) return contractError(providerKey, "observation iterator");
+  const next = iterator.next;
+  if (typeof next !== "function") return contractError(providerKey, "observation iterator");
+  const returnMethod = iterator.return;
+  if (returnMethod !== void 0 && typeof returnMethod !== "function") {
+    return contractError(providerKey, "observation iterator");
+  }
+  return {
+    iterator,
+    next,
+    returnMethod
+  };
+}
+function iteratorResult(value) {
+  if (!isObject(value)) return false;
+  const done = value.done;
+  return done === void 0 || typeof done === "boolean";
+}
+function boundedCleanup(result, providerKey) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(
+      `Provider ${providerKey} account quota iterator cleanup exceeded ${AGENT_ACCOUNT_QUOTA_ITERATOR_CLEANUP_TIMEOUT_MS}ms.`
+    )), AGENT_ACCOUNT_QUOTA_ITERATOR_CLEANUP_TIMEOUT_MS);
+  });
+  return Promise.race([Promise.resolve(result), timeout]).then(() => void 0).finally(() => {
+    if (timer !== void 0) clearTimeout(timer);
+  });
+}
+function beginCleanup(state) {
+  if (state.cleanupPromise !== void 0) return state.cleanupPromise;
+  const source = state.source;
+  if (source === void 0) return Promise.resolve();
+  if (source.returnMethod === void 0) {
+    state.cleanupPromise = Promise.resolve();
+  } else {
+    try {
+      state.cleanupPromise = boundedCleanup(
+        source.returnMethod.call(source.iterator),
+        state.providerKey
+      );
+    } catch (error) {
+      state.cleanupPromise = Promise.reject(error);
+    }
+  }
+  state.cleanupPromise.catch(() => void 0);
+  return state.cleanupPromise;
+}
+function closeState(state) {
+  if (state.closed) {
+    void beginCleanup(state);
+    return;
+  }
+  state.closed = true;
+  state.signal.removeEventListener("abort", state.onAbort);
+  if (!state.controller.signal.aborted) state.controller.abort();
+  void beginCleanup(state);
+}
+function createIterator(providerKey, declaredObserve, receiver, lifetimeSignal, operationSignalValue) {
+  const controller = new AbortController();
+  const signal = AbortSignal.any([
+    lifetimeSignal,
+    operationSignalValue,
+    controller.signal
+  ]);
+  const state = {
+    providerKey,
+    controller,
+    signal,
+    onAbort: () => closeState(state),
+    closed: false,
+    closedNormally: false,
+    pendingNext: false
+  };
+  if (signal.aborted) closeState(state);
+  else signal.addEventListener("abort", state.onAbort, { once: true });
+  const source = () => {
+    if (state.source !== void 0) return state.source;
+    throwIfAgentOperationAborted(signal);
+    const iterable = declaredObserve.call(receiver, { signal });
+    state.source = providerIterator(providerKey, iterable);
+    if (signal.aborted) closeState(state);
+    return state.source;
+  };
+  const next = async () => {
+    if (state.pendingNext) {
+      throw new TypeError("Concurrent account quota observation next calls are not supported.");
+    }
+    if (state.closed) {
+      if (state.closedNormally || !signal.aborted) return { done: true, value: void 0 };
+      throwIfAgentOperationAborted(signal);
+    }
+    throwIfAgentOperationAborted(signal);
+    state.pendingNext = true;
+    try {
+      const iterator = source();
+      throwIfAgentOperationAborted(signal);
+      const result = await awaitCancellable(iterator.next.call(iterator.iterator), signal);
+      throwIfAgentOperationAborted(signal);
+      if (!iteratorResult(result)) return contractError(providerKey, "observation");
+      if (result.done === true) {
+        state.closedNormally = true;
+        closeState(state);
+        await beginCleanup(state);
+        return { done: true, value: void 0 };
+      }
+      return { done: false, value: parseAgentAccountQuotaSnapshot(result.value) };
+    } catch (error) {
+      closeState(state);
+      throw error;
+    } finally {
+      state.pendingNext = false;
+    }
+  };
+  const returnIterator = async (value) => {
+    state.closedNormally = true;
+    state.controller.abort();
+    closeState(state);
+    await beginCleanup(state);
+    return { done: true, value };
+  };
+  return { next, return: returnIterator };
+}
+function wrapQuery(declaredQuery, receiver, lifetimeSignal) {
+  return async (input) => {
+    const signal = AbortSignal.any([lifetimeSignal, operationSignal(input)]);
+    throwIfAgentOperationAborted(signal);
+    const candidate = declaredQuery.call(receiver, { signal });
+    const snapshot = await awaitCancellable(candidate, signal);
+    throwIfAgentOperationAborted(signal);
+    return parseAgentAccountQuotaSnapshot(snapshot);
+  };
+}
+function wrapObserve(providerKey, declaredObserve, receiver, lifetimeSignal) {
+  return (input) => {
+    const operationSignalValue = operationSignal(input);
+    return {
+      [Symbol.asyncIterator]() {
+        return createIterator(
+          providerKey,
+          declaredObserve,
+          receiver,
+          lifetimeSignal,
+          operationSignalValue
+        );
+      }
+    };
+  };
+}
+function validateShape(providerKey, candidate) {
+  if (!isObject(candidate)) return contractError(providerKey, "port");
+  const kind = candidate.kind;
+  const query = candidate.query;
+  const observe = candidate.observe;
+  if (kind === "unsupported") {
+    if (!exactKeys(candidate, ["kind"]) || "query" in candidate || "observe" in candidate) {
+      return contractError(providerKey, "port");
+    }
+    return Object.freeze({ kind: "unsupported" });
+  }
+  if (kind === "query") {
+    if (!exactKeys(candidate, ["kind", "query"]) || typeof query !== "function" || "observe" in candidate) {
+      return contractError(providerKey, "port");
+    }
+    return candidate;
+  }
+  if (kind === "observe") {
+    if (!exactKeys(candidate, ["kind", "observe"]) || typeof observe !== "function" || "query" in candidate) {
+      return contractError(providerKey, "port");
+    }
+    return candidate;
+  }
+  if (kind === "query_and_observe") {
+    if (!exactKeys(candidate, ["kind", "query", "observe"]) || typeof query !== "function" || typeof observe !== "function") {
+      return contractError(providerKey, "port");
+    }
+    return candidate;
+  }
+  return contractError(providerKey, "port");
+}
+function validateAgentAccountQuotaPort(input) {
+  if (!isObject(input)) {
+    throw new TypeError("Account quota port validation input must be an object.");
+  }
+  assertSignal(input.signal, "instance signal");
+  const declared = validateShape(input.providerKey, input.port);
+  if (declared.kind === "unsupported") return declared;
+  if (declared.kind === "query") {
+    return Object.freeze({
+      kind: "query",
+      query: wrapQuery(declared.query, declared, input.signal)
+    });
+  }
+  if (declared.kind === "observe") {
+    return Object.freeze({
+      kind: "observe",
+      observe: wrapObserve(input.providerKey, declared.observe, declared, input.signal)
+    });
+  }
+  return Object.freeze({
+    kind: "query_and_observe",
+    query: wrapQuery(declared.query, declared, input.signal),
+    observe: wrapObserve(input.providerKey, declared.observe, declared, input.signal)
+  });
+}
+export {
+  AGENT_ACCOUNT_QUOTA_ITERATOR_CLEANUP_TIMEOUT_MS,
+  validateAgentAccountQuotaPort
+};

package/dist/environment/index.d.ts

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

package/dist/environment/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./validation.js";

package/dist/environment/types.d.ts

@@ -0,0 +1,59 @@
+import type { AgentEnvironmentDomain, AgentEnvironmentId, AgentEnvironmentInvalidation, AgentEnvironmentSnapshot, AgentSessionConfiguration } from "@agen-ai/agent-protocol";
+import type { AgentProviderExecutionStartedObserver } from "../sessions.js";
+/** Input supplied when a materialized instance discovers its host-scoped environment. */
+export interface AgentEnvironmentDiscoveryInput {
+    readonly signal: AbortSignal;
+    readonly environmentId: AgentEnvironmentId;
+    readonly workingDirectory: string;
+    readonly configuration: AgentSessionConfiguration;
+    /** Runtime receipt invoked immediately before the provider read candidate. */
+    readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
+}
+/** Input supplied to a discovery watch. Watches have no provider-start receipt. */
+export interface AgentEnvironmentDiscoveryWatchInput {
+    readonly signal: AbortSignal;
+    readonly environmentId: AgentEnvironmentId;
+    readonly workingDirectory: string;
+    readonly configuration: AgentSessionConfiguration;
+}
+/** Input supplied when an opened provider session observes its bound environment. */
+export interface AgentEnvironmentObservationInput {
+    readonly signal: AbortSignal;
+    readonly environmentId: AgentEnvironmentId;
+    /** Runtime receipt invoked immediately before the provider read candidate. */
+    readonly onProviderExecutionStarted?: AgentProviderExecutionStartedObserver;
+}
+/** Input supplied to an observation watch. Watches have no provider-start receipt. */
+export interface AgentEnvironmentObservationWatchInput {
+    readonly signal: AbortSignal;
+    readonly environmentId: AgentEnvironmentId;
+}
+export type AgentEnvironmentDiscovery = (input: AgentEnvironmentDiscoveryInput) => Promise<AgentEnvironmentSnapshot>;
+export type AgentEnvironmentObservation = (input: AgentEnvironmentObservationInput) => Promise<AgentEnvironmentSnapshot>;
+export type AgentEnvironmentDiscoveryWatch = (input: AgentEnvironmentDiscoveryWatchInput) => AsyncIterable<AgentEnvironmentInvalidation>;
+export type AgentEnvironmentObservationWatch = (input: AgentEnvironmentObservationWatchInput) => AsyncIterable<AgentEnvironmentInvalidation>;
+export type AgentEnvironmentDiscoveryPort = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "read";
+    domains: readonly AgentEnvironmentDomain[];
+    readEnvironment: AgentEnvironmentDiscovery;
+}> | Readonly<{
+    kind: "read_and_watch";
+    domains: readonly AgentEnvironmentDomain[];
+    readEnvironment: AgentEnvironmentDiscovery;
+    watchEnvironment: AgentEnvironmentDiscoveryWatch;
+}>;
+export type AgentEnvironmentObservationPort = Readonly<{
+    kind: "unsupported";
+}> | Readonly<{
+    kind: "read";
+    domains: readonly AgentEnvironmentDomain[];
+    readEnvironment: AgentEnvironmentObservation;
+}> | Readonly<{
+    kind: "read_and_watch";
+    domains: readonly AgentEnvironmentDomain[];
+    readEnvironment: AgentEnvironmentObservation;
+    watchEnvironment: AgentEnvironmentObservationWatch;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/environment/validation.d.ts

@@ -0,0 +1,17 @@
+import { type AgentCapabilities, type AgentProviderKey } from "@agen-ai/agent-protocol";
+import type { AgentEnvironmentDiscoveryPort, AgentEnvironmentObservationPort } from "./types.js";
+/** Maximum time allowed for a native watch iterator's return method to settle. */
+export declare const AGENT_ENVIRONMENT_ITERATOR_CLEANUP_TIMEOUT_MS = 1000;
+export declare function validateAgentEnvironmentDiscoveryPort(input: Readonly<{
+    readonly providerKey: AgentProviderKey;
+    readonly capability: AgentCapabilities["environment"]["instance"];
+    readonly port: unknown;
+    readonly signal: AbortSignal;
+}>): AgentEnvironmentDiscoveryPort;
+export declare function validateAgentEnvironmentObservationPort(input: Readonly<{
+    readonly providerKey: AgentProviderKey;
+    readonly capability: AgentCapabilities["environment"]["session"];
+    readonly port: unknown;
+    readonly signal: AbortSignal;
+}>): AgentEnvironmentObservationPort;
+//# sourceMappingURL=validation.d.ts.map