@agen-ai/agent-protocol 0.2.4 → 0.2.5

package/README.md

@@ -3,8 +3,9 @@
 `@agen-ai/agent-protocol` is the provider-neutral data contract for coding-agent runtimes. It
 defines opaque identifiers, sessions, turns, approval and elicitation requests, technical
 capabilities, typed operations, safe configuration and managed-content inventories, integration
-observations, collaboration lifecycles, generated resources, portable artifact descriptors, and
-provider-observed events. The package does not define a transport or execution runtime.
+observations, account-quota observations, collaboration lifecycles, generated resources, portable
+artifact descriptors, and provider-observed events. The package does not define a transport or
+execution runtime.
 
 ## Ownership boundary
 
@@ -20,12 +21,18 @@ identities to protocol IDs.
 the currently running turn. It does not describe, authorize, or implement future-turn queueing;
 that product concern belongs to the caller's control plane.
 
+Account-quota observations describe the allowance state reported by the account that funds a
+provider connection. They do not identify that account, authorize a caller, decide whether a turn
+may run, or represent AgenAI billing. `sourceId`, `poolId`, and `windowId` are opaque correlation
+values. A quota observation with a known zero or an unknown reset remains valid; unavailable states
+carry no fabricated windows or hints.
+
 ## Entrypoints
 
 - `@agen-ai/agent-protocol` exports the complete plain API.
 - `/sessions`, `/turns`, `/requests`, `/events`, `/capabilities`, `/artifacts`, `/operations`,
-  `/configuration`, `/managed-content`, `/integrations`, `/collaboration`, and `/resources` are
-  focused plain entrypoints.
+  `/configuration`, `/managed-content`, `/integrations`, `/collaboration`, `/resources`, and
+  `/account-quota` are focused plain entrypoints.
 - `/zod` is the only entrypoint that exposes Zod schemas.
 - `/json-schema` exposes deterministic draft 2020-12 schema artifacts.
 
@@ -83,7 +90,10 @@ content, and integrations are separate bounded, revisioned catalogs; capability
 not carry inventory or authority. Operation and configuration input is correlated to the exact
 offered revision and typed field definition. Collaboration exposes canonical graph identity and
 lifecycle state without provider handles. Generated resources expose portable publication state
-and an artifact reference only when the resource is available. None of these domains has a generic
+and an artifact reference only when the resource is available. Account-quota windows keep period,
+measurement, applicability, allowance, and observation timestamps separate so a provider cannot
+collapse unrelated pools into one percentage. Quantity units remain distinct from exact money,
+which uses integer minor units with an explicit scale. None of these domains has a generic
 extension or metadata bag.
 
 ## Errors and trust
@@ -104,11 +114,14 @@ validated protocol output remains canonical across transports and consumers.
 
 ## Versioning and release
 
-The package is at `0.2.4` while the public API is still being proven with external adapters.
+The package is at `0.2.5` while the public API is still being proven with external adapters.
 Pre-1.0 releases may include breaking changes during this beta period, and every such change is
 called out in the release notes. Protocol V8 is independent of any host transport or product
 persistence version. It directly replaces V7 in source; there is no compatibility parser, alias,
-or extension reader.
+or extension reader. The account-quota namespace starts at schema version 1 and is additive to
+Protocol V8. The required `MaterializedAgentProviderInstance.accountQuota` runtime field is a
+source-level implementer change in the coordinated `0.2.5` release; all three SDK packages must
+be upgraded together. See the public repository migration guide for the explicit unsupported port.
 
 The repository release proof builds and packs `@agen-ai/validation`, this package, and
 `@agen-ai/agent-runtime`; rejects workspace-only or private references; then typechecks and runs a

package/dist/accountQuota/index.d.ts

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

package/dist/accountQuota/index.js

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

package/dist/accountQuota/parsers.d.ts

@@ -0,0 +1,7 @@
+import type { AgentProtocolParseResult } from '../foundation/types.js';
+import type { AgentAccountQuotaSnapshot, AgentAccountQuotaWindow } from './types.js';
+export declare function parseAgentAccountQuotaSnapshot(input: unknown): AgentAccountQuotaSnapshot;
+export declare function safeParseAgentAccountQuotaSnapshot(input: unknown): AgentProtocolParseResult<AgentAccountQuotaSnapshot>;
+export declare function parseAgentAccountQuotaWindow(input: unknown): AgentAccountQuotaWindow;
+export declare function safeParseAgentAccountQuotaWindow(input: unknown): AgentProtocolParseResult<AgentAccountQuotaWindow>;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/accountQuota/parsers.js

@@ -0,0 +1,20 @@
+import { parseWithSchema, safeParseWithSchema } from "../internal/parsers.js";
+import { AgentAccountQuotaSnapshotSchema, AgentAccountQuotaWindowSchema } from "../zod/accountQuota.js";
+function parseAgentAccountQuotaSnapshot(input) {
+  return parseWithSchema(AgentAccountQuotaSnapshotSchema, input);
+}
+function safeParseAgentAccountQuotaSnapshot(input) {
+  return safeParseWithSchema(AgentAccountQuotaSnapshotSchema, input);
+}
+function parseAgentAccountQuotaWindow(input) {
+  return parseWithSchema(AgentAccountQuotaWindowSchema, input);
+}
+function safeParseAgentAccountQuotaWindow(input) {
+  return safeParseWithSchema(AgentAccountQuotaWindowSchema, input);
+}
+export {
+  parseAgentAccountQuotaSnapshot,
+  parseAgentAccountQuotaWindow,
+  safeParseAgentAccountQuotaSnapshot,
+  safeParseAgentAccountQuotaWindow
+};

package/dist/accountQuota/types.d.ts

@@ -0,0 +1,89 @@
+import type { AgentIsoDateTime } from '../foundation/types.js';
+export declare const AGENT_ACCOUNT_QUOTA_SCHEMA_VERSION: 1;
+export declare const AGENT_ACCOUNT_QUOTA_MAX_WINDOWS = 64;
+export declare const AGENT_ACCOUNT_QUOTA_MAX_BYTES = 65536;
+export declare const AGENT_ACCOUNT_QUOTA_MAX_LABEL_LENGTH = 160;
+export declare const AGENT_ACCOUNT_QUOTA_MAX_SCOPE_IDS = 32;
+export type AgentAccountQuotaApplicability = Readonly<{
+    kind: 'account';
+}> | Readonly<{
+    kind: 'product';
+    productId: string;
+}> | Readonly<{
+    kind: 'models';
+    modelIds: readonly string[];
+}> | Readonly<{
+    kind: 'unknown';
+}>;
+export type AgentAccountQuotaPeriod = Readonly<{
+    kind: 'rolling' | 'fixed' | 'unknown';
+    durationSeconds?: number;
+}> | Readonly<{
+    kind: 'calendar';
+    unit: 'day' | 'week' | 'month' | 'year';
+    timeZone: string;
+}> | Readonly<{
+    kind: 'billing_cycle';
+    unit: 'month' | 'year' | 'unknown';
+}>;
+export type AgentAccountQuotaMeasurement = Readonly<{
+    kind: 'unknown';
+}> | Readonly<{
+    kind: 'percentage';
+    usedPercent: number;
+}> | Readonly<{
+    kind: 'quantity';
+    unit: string;
+    used?: number;
+    limit?: number;
+    remaining?: number;
+    usedPercent?: number;
+}> | Readonly<{
+    kind: 'money';
+    currency: string;
+    scale: number;
+    usedMinorUnits?: number;
+    limitMinorUnits?: number;
+    remainingMinorUnits?: number;
+    usedPercent?: number;
+}>;
+export interface AgentAccountQuotaReset {
+    readonly at: AgentIsoDateTime;
+    readonly precision: 'reported' | 'estimated';
+    readonly observedAt: AgentIsoDateTime;
+}
+export interface AgentAccountQuotaWindow {
+    readonly poolId: string;
+    readonly windowId: string;
+    readonly label: string;
+    readonly allowanceKind: 'included' | 'extra' | 'reserve' | 'unknown';
+    readonly applicability: AgentAccountQuotaApplicability;
+    readonly period: AgentAccountQuotaPeriod;
+    readonly measurement: AgentAccountQuotaMeasurement;
+    readonly observedAt: AgentIsoDateTime;
+    readonly startsAt?: AgentIsoDateTime;
+    readonly reset?: AgentAccountQuotaReset;
+}
+export interface AgentAccountQuotaAllowance {
+    readonly included: 'allowed' | 'exhausted' | 'unknown';
+    readonly extra: 'allowed' | 'unavailable' | 'unknown';
+    readonly reserve: 'allowed' | 'unavailable' | 'unknown';
+}
+interface AgentAccountQuotaSnapshotBase {
+    readonly schemaVersion: typeof AGENT_ACCOUNT_QUOTA_SCHEMA_VERSION;
+    readonly sourceId: string;
+    readonly observedAt: AgentIsoDateTime;
+}
+export interface AgentAvailableAccountQuotaSnapshot extends AgentAccountQuotaSnapshotBase {
+    readonly state: 'available';
+    readonly completeness: 'complete' | 'partial';
+    readonly accountLabel?: string;
+    readonly planLabel?: string;
+    readonly windows: readonly AgentAccountQuotaWindow[];
+    readonly allowance: AgentAccountQuotaAllowance;
+}
+export type AgentAccountQuotaSnapshot = AgentAvailableAccountQuotaSnapshot | Readonly<AgentAccountQuotaSnapshotBase & {
+    state: 'authentication_required' | 'inapplicable' | 'temporarily_unavailable';
+}>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/accountQuota/types.js

@@ -0,0 +1,12 @@
+const AGENT_ACCOUNT_QUOTA_SCHEMA_VERSION = 1;
+const AGENT_ACCOUNT_QUOTA_MAX_WINDOWS = 64;
+const AGENT_ACCOUNT_QUOTA_MAX_BYTES = 65536;
+const AGENT_ACCOUNT_QUOTA_MAX_LABEL_LENGTH = 160;
+const AGENT_ACCOUNT_QUOTA_MAX_SCOPE_IDS = 32;
+export {
+  AGENT_ACCOUNT_QUOTA_MAX_BYTES,
+  AGENT_ACCOUNT_QUOTA_MAX_LABEL_LENGTH,
+  AGENT_ACCOUNT_QUOTA_MAX_SCOPE_IDS,
+  AGENT_ACCOUNT_QUOTA_MAX_WINDOWS,
+  AGENT_ACCOUNT_QUOTA_SCHEMA_VERSION
+};