@agen-ai/agent-runtime 0.2.4 → 0.2.5

package/README.md

@@ -3,20 +3,20 @@
 `@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.
+an account-quota observation port, 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 source package implements Agent Protocol V8. Agent Protocol V8, private host V18/catalog V11, and Workspaces event V11/member response V12.
 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/testing` exports the deterministic fake provider and reusable
   conformance runner.
 
@@ -48,6 +48,17 @@ An unsupported declaration exposes exactly `{ kind: "unsupported" }`; a supporte
 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 +143,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)}.`);
   },
 });
@@ -168,9 +179,11 @@ 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
+The package is at `0.2.5` 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 release notes. Requiring `accountQuota` on every materialized instance is a source-level
+implementer change in the coordinated `0.2.5` release. Upgrade all three SDK packages together;
+there is no compatibility shim or optional-field fallback.
 
 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

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/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./adapterValidation.js";
+export * from "./accountQuota/index.js";
 export * from "./artifacts.js";
 export * from "./contractErrors.js";
 export * from "./evidence.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./adapterValidation.js";
+export * from "./accountQuota/index.js";
 export * from "./artifacts.js";
 export * from "./contractErrors.js";
 export * from "./evidence.js";

package/dist/providerDriver.d.ts

@@ -1,5 +1,6 @@
 import { type AgentCapabilities, type AgentInstanceId, type AgentProviderKey } from "@agen-ai/agent-protocol";
 import type { MaybePromise } from "./foundation.js";
+import type { AgentAccountQuotaPort } from "./accountQuota/types.js";
 import type { AgentProviderReadiness } from "./readiness.js";
 import type { AgentProviderAdapter } from "./sessions.js";
 export interface AgentProviderInstanceDefinition {
@@ -14,6 +15,7 @@ export interface MaterializedAgentProviderInstance {
     readonly instanceId: AgentInstanceId;
     readonly capabilities: AgentCapabilities;
     readonly adapter: AgentProviderAdapter;
+    readonly accountQuota: AgentAccountQuotaPort;
     readonly checkReadiness: (input?: AgentProviderReadinessCheckInput) => MaybePromise<AgentProviderReadiness>;
     readonly dispose: () => MaybePromise<void>;
 }

package/dist/providerInstanceRegistry.js

@@ -4,6 +4,7 @@ import {
   parseAgentProviderKey
 } from "@agen-ai/agent-protocol";
 import { validateAgentProviderAdapter } from "./adapterValidation.js";
+import { validateAgentAccountQuotaPort } from "./accountQuota/validation.js";
 import {
   createAgentProviderCatalogEntries,
   createAgentProviderInstanceCatalogEntries
@@ -138,10 +139,16 @@ function managedInstance(rawInstance, providerKey) {
     status: "active",
     disposePromise: null
   };
+  const quotaLifetime = new AbortController();
   const instance = Object.freeze({
     instanceId: parseAgentInstanceId(rawInstance.instanceId),
     capabilities,
     adapter: validateAgentProviderAdapter(capabilities, rawInstance.adapter),
+    accountQuota: validateAgentAccountQuotaPort({
+      providerKey,
+      port: rawInstance.accountQuota,
+      signal: quotaLifetime.signal
+    }),
     checkReadiness: async (input) => {
       const readiness = await checkReadiness(input);
       return validateAgentProviderReadiness(readiness);
@@ -150,6 +157,7 @@ function managedInstance(rawInstance, providerKey) {
       if (lifecycle.status === "disposed") return Promise.resolve();
       if (lifecycle.disposePromise) return lifecycle.disposePromise;
       lifecycle.status = "disposing";
+      quotaLifetime.abort(new DOMException("The provider instance was disposed.", "AbortError"));
       lifecycle.disposePromise = Promise.resolve().then(() => dispose()).then(() => {
         lifecycle.status = "disposed";
       }).catch((error) => {

package/dist/testing/conformance.js

@@ -122,6 +122,26 @@ async function runAgentProviderConformance(scenario) {
       "Version-reporting capability did not return a runtime version."
     );
     checks.push("readiness", "version_reporting_capability");
+    const quota = instance.accountQuota;
+    const quotaAbort = new AbortController();
+    quotaAbort.abort();
+    const quotaOperations = [];
+    if (quota.kind === "query" || quota.kind === "query_and_observe") {
+      quotaOperations.push(async () => quota.query({ signal: quotaAbort.signal }));
+    }
+    if (quota.kind === "observe" || quota.kind === "query_and_observe") {
+      quotaOperations.push(async () => quota.observe({ signal: quotaAbort.signal })[Symbol.asyncIterator]().next());
+    }
+    for (const operation of quotaOperations) {
+      let aborted2 = false;
+      try {
+        await operation();
+      } catch (error) {
+        aborted2 = isAgentOperationAbortError(error);
+      }
+      requireCheck(aborted2, "account_quota", "Pre-aborted quota work must fail with AbortError.");
+    }
+    checks.push("account_quota");
     let createdBindingCount = 0;
     const created = await instance.adapter.createSession({
       sessionId: scenario.createSessionId,

package/dist/testing/fakeProvider.d.ts

@@ -1,4 +1,5 @@
 import { type AgentCapabilities, type AgentInstanceId, type AgentRequestResolution, type AgentSessionId, type AgentTurnId } from "@agen-ai/agent-protocol";
+import type { AgentAccountQuotaPort } from "../accountQuota/types.js";
 import { type AgentProviderDriver, type AgentProviderInstanceDefinition } from "../providerDriver.js";
 import type { AgentProviderSteerTurnInput, AgentTurnSteeringResult } from "../sessions.js";
 export interface FakeAgentProviderOptions {
@@ -7,6 +8,7 @@ export interface FakeAgentProviderOptions {
     readonly capabilities?: AgentCapabilities;
     readonly now?: () => string;
     readonly steeringResult?: AgentTurnSteeringResult;
+    readonly accountQuota?: AgentAccountQuotaPort;
 }
 export type FakeAgentSteeringInput = Readonly<Omit<AgentProviderSteerTurnInput, "signal">>;
 export interface FakeAgentProviderSnapshot {

package/dist/testing/fakeProvider.js

@@ -555,6 +555,7 @@ function createFakeAgentProvider(options = {}) {
         instanceId: createdInstanceId,
         capabilities,
         adapter: fakeAdapter({ state, capabilities, now, steeringResult }),
+        accountQuota: options.accountQuota ?? { kind: "unsupported" },
         checkReadiness: () => createAgentProviderReadiness({
           status: "ready",
           checkedAt: now(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agen-ai/agent-runtime",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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.4"
+    "@agen-ai/agent-protocol": "^0.2.5"
   },
   "devDependencies": {
     "tsup": "^8.5.0"