@agen-ai/agent-protocol 0.3.0 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 `@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, effective harness content and package catalogs, environment observations, account-quota observations, collaboration lifecycles, generated resources, portable
+observations, effective harness content and package catalogs, environment observations, account-quota observations, operational failures and recovery hints, collaboration lifecycles, generated resources, portable
 artifact descriptors, and provider-observed events. The package does not define a transport or
 execution runtime.
 
@@ -50,7 +50,7 @@ import {
 } from '@agen-ai/agent-protocol';
 
 const event: AgentEvent = parseAgentEvent({
-  protocolVersion: 9,
+  protocolVersion: 10,
   type: 'content.delta',
   sessionId: parseAgentSessionId('external-session:42'),
   turnId: parseAgentTurnId('external-turn:9'),
@@ -65,7 +65,7 @@ const event: AgentEvent = parseAgentEvent({
 const roundTripped = parseAgentEvent(JSON.parse(JSON.stringify(event)));
 ```
 
-Serialized values carry `protocolVersion: 9`; TypeScript API names remain unsuffixed. Unknown
+Serialized values carry `protocolVersion: 10`; TypeScript API names remain unsuffixed. Unknown
 fields and unsupported protocol versions are rejected.
 
 Item snapshots are a closed union keyed by `itemKind`. Common identity and lifecycle fields are
@@ -78,7 +78,7 @@ attribute bag; source evidence belongs outside the portable event. File-change p
 `compareStringsByUnicodeCodePoint` to emit the canonical path ordering required by the protocol
 across both BMP and supplementary Unicode characters.
 
-V9 approval requests correlate to one live item or exact proposed-plan artifact and provide a
+Approval requests correlate to one live item or exact proposed-plan artifact and provide a
 bounded list of typed options. Every option declares its decision, persistence, and neutral scope;
 resolutions select one offered `optionId` or explicitly cancel. Approval capabilities advertise
 the exact persistence/scope combinations an adapter can emit. `context.usage.updated` reports
@@ -98,6 +98,49 @@ extension or metadata bag.
 
 ## Errors and trust
 
+`AgentError` contains required `category`, stable `code`, safe `message`, tagged `recovery`, and
+optional bounded `context`. The categories distinguish rate limiting, exhausted account quota,
+turn budget, execution/context limits, authentication, permission, invalid input, provider overload,
+transport, provider, protocol, internal, and unknown failures. Adapters classify from native evidence;
+an HTTP 429 alone establishes rate limiting and does not establish exhausted account quota.
+
+Recovery is one of `unknown`, `none`, `retry`, `wait_for_quota`, or `user_action`. `retry` may carry
+an exactly reported `notBefore` timestamp. `user_action` names `authenticate`, `review_access`,
+`change_configuration`, or `review_allowance`. `none` offers no applicable recovery for this operation.
+These hints describe possible next steps; the application must assess execution certainty and effect
+replay independently before starting more work. The protocol does not retry, schedule continuation,
+switch accounts, or switch providers.
+
+An operational failure is separate from terminal authority. `turn.completed` with outcome `failed`
+requires an error; other terminal outcomes cannot carry one. A `runtime.error` observation does not
+itself complete a turn, and a failed tool item does not by itself fail the turn. Contract violations,
+uncertain dispatch and cleanup ownership retain their runtime semantics regardless of failure category.
+
+`wait_for_quota` may carry an immutable `AgentFailureQuotaReference` identifying an existing source,
+pool, window, and observation timestamp. Its optional `reset` uses the same `AgentAccountQuotaReset`
+shape and preserves reported versus estimated precision. Reset evidence cannot be newer than the
+referenced observation. Only `rate_limited` and `quota_exhausted` failures may carry a quota reference;
+turn budget and execution limits do not acquire account-quota identity. Omitted quota or reset evidence
+remains absent. The host must establish reference visibility and applicability to the selected binding;
+historical references grant no eligibility after account or credential changes.
+
+`runtime.retrying` reports provider-owned retry activity within an active turn. It requires
+`owner: 'provider'`, the turn identity, and an `AgentError`. Its optional `attempt` is a positive,
+one-based retry ordinal; `maxAttempts` is the positive maximum number of retries. Both exclude the
+original attempt. When both are reported, `attempt` cannot exceed `maxAttempts`. Optional `delayMs`
+is a nonnegative safe integer. Counters may repeat or restart across the provider's request/stream
+retry domains within one turn, and missing native facts remain absent. A retry observation neither
+completes a turn nor resolves a pending request; a later authoritative success completes the same turn.
+
+V10 removes `AgentError.retryable` and `runtime.warning.payload.retryable`. Warnings retain only
+bounded code, message, and optional context. Existing `AgentError`, `parseAgentError`, and
+`safeParseAgentError` root imports remain available. Failure messages are bounded at 4,000 characters,
+codes at 120 characters, context fields at 160 characters, and serialized failures at 32 KiB.
+Context contains only optional `operation`, `component` and `status`; it cannot carry native payloads,
+credentials or arbitrary attributes.
+The `/json-schema` error artifact publishes structural constraints and names the residual semantic
+invariants enforced by the ordinary parser, including quota applicability and reset observation order.
+
 Throwing parsers raise `AgentProtocolValidationError`, a `TypeError` with stable, JSON-safe
 `issues`. Each corresponding `safeParse...` function returns either parsed data or the same issue
 array without throwing. Callers should branch on that public result or error class, not on Zod
@@ -147,12 +190,14 @@ before delegation; a composer can use the same pure functions to preserve and ex
 
 ## Versioning and release
 
-Agent Protocol V9 defines the coordinated SDK `0.3.0` contract shared by this package,
+Agent Protocol V10 defines the coordinated SDK `0.4.0` contract shared by this package,
 `@agen-ai/validation`, and `@agen-ai/agent-runtime`. Registry publication and dist-tag state are
-release metadata outside this contract. The earlier public `0.2.5` release remains historical. All
-three SDK packages must be released together. Protocol V9 is independent of private transport and
-product persistence versions and directly replaces V8 at live boundaries. There is one current
-parser. The environment and account-quota namespaces each use their own schema version 1.
+release metadata outside this contract. The earlier public `0.3.0` and `0.3.1` releases remain historical.
+The complete seven-package public release inventory must use one coordinated source version. Protocol V10 is
+independent of private transport and product
+persistence versions and directly replaces V9 at live boundaries. There is one current parser. V9
+serialized data requires the historical owner's frozen decoder and is rejected by the live V10 parser. The
+environment and account-quota namespaces each use their own schema version 1.
 
 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/capabilities/types.d.ts

@@ -149,7 +149,7 @@ export type AgentTurnSteeringCapability = Readonly<{
     input: AgentOperationInputCapability;
 }>;
 export interface AgentCapabilities {
-    readonly protocolVersion: 9;
+    readonly protocolVersion: 10;
     readonly providerKey: AgentProviderKey;
     readonly sessions: Readonly<{
         create: true;

package/dist/events/types.d.ts

@@ -5,10 +5,10 @@ import type { AgentRequest } from '../requests/index.js';
 import type { AgentOperationResult } from '../operations/index.js';
 import type { AgentGeneratedResourceDescriptor } from '../resources/index.js';
 import type { AgentContentStreamKind, AgentContextUsage, AgentDiffSummary, AgentItemSnapshot, AgentPlanStep, AgentTurnCompletedPayload, AgentTurnState } from '../turns/index.js';
-export declare const AGENT_EVENT_TYPES: readonly ["turn.started", "turn.state_changed", "turn.completed", "item.started", "item.updated", "item.completed", "content.delta", "turn.plan.updated", "turn.plan.proposed", "turn.diff.updated", "request.opened", "progress.updated", "context.usage.updated", "artifact.referenced", "operation.updated", "collaboration.updated", "resource.updated", "runtime.warning", "runtime.error", "provider.diagnostic"];
+export declare const AGENT_EVENT_TYPES: readonly ["turn.started", "turn.state_changed", "turn.completed", "item.started", "item.updated", "item.completed", "content.delta", "turn.plan.updated", "turn.plan.proposed", "turn.diff.updated", "request.opened", "progress.updated", "context.usage.updated", "artifact.referenced", "operation.updated", "collaboration.updated", "resource.updated", "runtime.retrying", "runtime.warning", "runtime.error", "provider.diagnostic"];
 export type AgentEventType = (typeof AGENT_EVENT_TYPES)[number];
 interface AgentEventBase<Type extends AgentEventType, Payload> {
-    readonly protocolVersion: 9;
+    readonly protocolVersion: 10;
     readonly type: Type;
     readonly sessionId: AgentSessionId;
     readonly providerRefs?: AgentProviderRefs;
@@ -72,10 +72,18 @@ export type AgentCollaborationUpdatedEvent = AgentOptionallyTurnScopedEventBase<
 export type AgentResourceUpdatedEvent = AgentOptionallyTurnScopedEventBase<'resource.updated', Readonly<{
     resource: AgentGeneratedResourceDescriptor;
 }>>;
+export type AgentRuntimeRetryingEvent = AgentTurnEventBase<'runtime.retrying', Readonly<{
+    owner: 'provider';
+    error: AgentError;
+    /** One-based retry ordinal, excluding the original attempt. */
+    attempt?: number;
+    /** Maximum number of retries, excluding the original attempt. */
+    maxAttempts?: number;
+    delayMs?: number;
+}>>;
 export type AgentRuntimeWarningEvent = AgentOptionallyTurnScopedEventBase<'runtime.warning', Readonly<{
     code: string;
     message: string;
-    retryable?: boolean;
     context?: AgentErrorContext;
 }>>;
 export type AgentRuntimeErrorEvent = AgentOptionallyTurnScopedEventBase<'runtime.error', Readonly<{
@@ -86,6 +94,6 @@ export type AgentProviderDiagnosticEvent = AgentOptionallyTurnScopedEventBase<'p
     message: string;
     context?: AgentErrorContext;
 }>>;
-export type AgentEvent = AgentTurnStartedEvent | AgentTurnStateChangedEvent | AgentTurnCompletedEvent | AgentItemStartedEvent | AgentItemUpdatedEvent | AgentItemCompletedEvent | AgentContentDeltaEvent | AgentPlanUpdatedEvent | AgentPlanProposedEvent | AgentDiffUpdatedEvent | AgentRequestOpenedEvent | AgentProgressUpdatedEvent | AgentContextUsageUpdatedEvent | AgentArtifactReferencedEvent | AgentOperationUpdatedEvent | AgentCollaborationUpdatedEvent | AgentResourceUpdatedEvent | AgentRuntimeWarningEvent | AgentRuntimeErrorEvent | AgentProviderDiagnosticEvent;
+export type AgentEvent = AgentTurnStartedEvent | AgentTurnStateChangedEvent | AgentTurnCompletedEvent | AgentItemStartedEvent | AgentItemUpdatedEvent | AgentItemCompletedEvent | AgentContentDeltaEvent | AgentPlanUpdatedEvent | AgentPlanProposedEvent | AgentDiffUpdatedEvent | AgentRequestOpenedEvent | AgentProgressUpdatedEvent | AgentContextUsageUpdatedEvent | AgentArtifactReferencedEvent | AgentOperationUpdatedEvent | AgentCollaborationUpdatedEvent | AgentResourceUpdatedEvent | AgentRuntimeRetryingEvent | AgentRuntimeWarningEvent | AgentRuntimeErrorEvent | AgentProviderDiagnosticEvent;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/events/types.js

@@ -16,6 +16,7 @@ const AGENT_EVENT_TYPES = [
   "operation.updated",
   "collaboration.updated",
   "resource.updated",
+  "runtime.retrying",
   "runtime.warning",
   "runtime.error",
   "provider.diagnostic"

package/dist/failures/index.d.ts

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

package/dist/failures/index.js

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

package/dist/failures/parsers.d.ts

@@ -0,0 +1,5 @@
+import type { AgentProtocolParseResult } from '../foundation/validation.js';
+import type { AgentError } from './types.js';
+export declare function parseAgentError(input: unknown): AgentError;
+export declare function safeParseAgentError(input: unknown): AgentProtocolParseResult<AgentError>;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/failures/parsers.js

@@ -0,0 +1,12 @@
+import { parseWithSchema, safeParseWithSchema } from "../internal/parsers.js";
+import { AgentErrorSchema } from "../zod/failures.js";
+function parseAgentError(input) {
+  return parseWithSchema(AgentErrorSchema, input);
+}
+function safeParseAgentError(input) {
+  return safeParseWithSchema(AgentErrorSchema, input);
+}
+export {
+  parseAgentError,
+  safeParseAgentError
+};

package/dist/failures/types.d.ts

@@ -0,0 +1,41 @@
+import type { AgentAccountQuotaReset } from '../accountQuota/types.js';
+import type { AgentIsoDateTime } from '../foundation/types.js';
+export declare const AGENT_FAILURE_CATEGORIES: readonly ["rate_limited", "quota_exhausted", "budget_exhausted", "execution_limit", "context_limit", "authentication", "permission", "invalid_request", "overloaded", "transport", "provider", "protocol", "internal", "unknown"];
+export type AgentFailureCategory = (typeof AGENT_FAILURE_CATEGORIES)[number];
+export declare const AGENT_ERROR_CONTEXT_MAX_LENGTH = 160;
+export interface AgentErrorContext {
+    readonly operation?: string;
+    readonly component?: string;
+    readonly status?: string;
+}
+/** Immutable quota observation evidence, without account or execution authority. */
+export interface AgentFailureQuotaReference {
+    readonly sourceId: string;
+    readonly poolId: string;
+    readonly windowId: string;
+    readonly observedAt: AgentIsoDateTime;
+    readonly reset?: AgentAccountQuotaReset;
+}
+/** Recovery describes an applicable next step; it never authorizes effect replay. */
+export type AgentRecoveryHint = Readonly<{
+    kind: 'unknown';
+}> | Readonly<{
+    kind: 'none';
+}> | Readonly<{
+    kind: 'retry';
+    notBefore?: AgentIsoDateTime;
+}> | Readonly<{
+    kind: 'wait_for_quota';
+    quota?: AgentFailureQuotaReference;
+}> | Readonly<{
+    kind: 'user_action';
+    action: 'authenticate' | 'review_access' | 'change_configuration' | 'review_allowance';
+}>;
+export interface AgentError {
+    readonly category: AgentFailureCategory;
+    readonly code: string;
+    readonly message: string;
+    readonly recovery: AgentRecoveryHint;
+    readonly context?: AgentErrorContext;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/failures/types.js

@@ -0,0 +1,21 @@
+const AGENT_FAILURE_CATEGORIES = [
+  "rate_limited",
+  "quota_exhausted",
+  "budget_exhausted",
+  "execution_limit",
+  "context_limit",
+  "authentication",
+  "permission",
+  "invalid_request",
+  "overloaded",
+  "transport",
+  "provider",
+  "protocol",
+  "internal",
+  "unknown"
+];
+const AGENT_ERROR_CONTEXT_MAX_LENGTH = 160;
+export {
+  AGENT_ERROR_CONTEXT_MAX_LENGTH,
+  AGENT_FAILURE_CATEGORIES
+};

package/dist/foundation/parsers.d.ts

@@ -1,5 +1,6 @@
-import type { AgentArtifactId, AgentApprovalOptionId, AgentCollaborationId, AgentConfigurationRevisionId, AgentError, AgentGeneratedResourceId, AgentInstanceId, AgentIntegrationId, AgentIntegrationResourceId, AgentIntegrationServerId, AgentIntegrationToolId, AgentIsoDateTime, AgentItemId, AgentJsonValue, AgentManagedContentId, AgentEnvironmentId, AgentEffectiveContentId, AgentCommandId, AgentExtensionId, AgentOperationId, AgentOperationInvocationId, AgentProviderConversationId, AgentProviderHistoryAnchor, AgentProviderItemRef, AgentProviderKey, AgentProviderRefs, AgentProviderRequestRef, AgentProviderTurnRef, AgentRequestFieldId, AgentRequestId, AgentSessionId, AgentTurnId } from './types.js';
+import type { AgentArtifactId, AgentApprovalOptionId, AgentCollaborationId, AgentConfigurationRevisionId, AgentGeneratedResourceId, AgentInstanceId, AgentIntegrationId, AgentIntegrationResourceId, AgentIntegrationServerId, AgentIntegrationToolId, AgentIsoDateTime, AgentItemId, AgentJsonValue, AgentManagedContentId, AgentEnvironmentId, AgentEffectiveContentId, AgentCommandId, AgentExtensionId, AgentOperationId, AgentOperationInvocationId, AgentProviderConversationId, AgentProviderHistoryAnchor, AgentProviderItemRef, AgentProviderKey, AgentProviderRefs, AgentProviderRequestRef, AgentProviderTurnRef, AgentRequestFieldId, AgentRequestId, AgentSessionId, AgentTurnId } from './types.js';
 import type { AgentProtocolParseResult } from './validation.js';
+export { parseAgentError, safeParseAgentError } from '../failures/parsers.js';
 export declare const parseAgentInstanceId: (input: unknown) => AgentInstanceId;
 export declare const safeParseAgentInstanceId: (input: unknown) => AgentProtocolParseResult<AgentInstanceId>;
 export declare const parseAgentSessionId: (input: unknown) => AgentSessionId;
@@ -54,8 +55,6 @@ export declare function parseAgentJsonValue(input: unknown): AgentJsonValue;
 export declare function safeParseAgentJsonValue(input: unknown): AgentProtocolParseResult<AgentJsonValue>;
 export declare function parseAgentProviderRefs(input: unknown): AgentProviderRefs;
 export declare function safeParseAgentProviderRefs(input: unknown): AgentProtocolParseResult<AgentProviderRefs>;
-export declare function parseAgentError(input: unknown): AgentError;
-export declare function safeParseAgentError(input: unknown): AgentProtocolParseResult<AgentError>;
 export declare const parseAgentEnvironmentId: (input: unknown) => AgentEnvironmentId;
 export declare const safeParseAgentEnvironmentId: (input: unknown) => AgentProtocolParseResult<AgentEnvironmentId>;
 export declare const parseAgentEffectiveContentId: (input: unknown) => AgentEffectiveContentId;

package/dist/foundation/parsers.js

@@ -5,7 +5,6 @@ import {
   AgentCollaborationIdSchema,
   AgentConfigurationRevisionIdSchema,
   AgentGeneratedResourceIdSchema,
-  AgentErrorSchema,
   AgentInstanceIdSchema,
   AgentIntegrationIdSchema,
   AgentIntegrationResourceIdSchema,
@@ -33,6 +32,7 @@ import {
   AgentSessionIdSchema,
   AgentTurnIdSchema
 } from "../zod/foundation.js";
+import { parseAgentError, safeParseAgentError } from "../failures/parsers.js";
 function idParser(schema) {
   return {
     parse: (input) => parseWithSchema(schema, input),
@@ -164,12 +164,6 @@ function parseAgentProviderRefs(input) {
 function safeParseAgentProviderRefs(input) {
   return safeParseWithSchema(AgentProviderRefsSchema, input);
 }
-function parseAgentError(input) {
-  return parseWithSchema(AgentErrorSchema, input);
-}
-function safeParseAgentError(input) {
-  return safeParseWithSchema(AgentErrorSchema, input);
-}
 const environmentIdParser = idParser(AgentEnvironmentIdSchema);
 const parseAgentEnvironmentId = environmentIdParser.parse;
 const safeParseAgentEnvironmentId = environmentIdParser.safeParse;

package/dist/foundation/types.d.ts

@@ -1,6 +1,7 @@
 export type { AgentProtocolParseFailure, AgentProtocolParseResult, AgentProtocolParseSuccess, ValidationIssue, ValidationPathSegment, } from './validation.js';
 export { AgentProtocolValidationError } from './validation.js';
-export declare const AGENT_PROTOCOL_VERSION: 9;
+export type { AgentError, AgentErrorContext } from '../failures/types.js';
+export declare const AGENT_PROTOCOL_VERSION: 10;
 export declare const AGENT_PROTOCOL_ID_MAX_LENGTH = 256;
 export declare const AGENT_PROTOCOL_PROVIDER_REFERENCE_MAX_LENGTH = 512;
 export declare const AGENT_PROTOCOL_PROVIDER_KEY_MAX_LENGTH = 100;
@@ -61,16 +62,5 @@ export interface AgentProviderRefs {
     readonly itemId?: AgentProviderItemRef;
     readonly requestId?: AgentProviderRequestRef;
 }
-export interface AgentErrorContext {
-    readonly operation?: string;
-    readonly component?: string;
-    readonly status?: string;
-}
-export interface AgentError {
-    readonly code: string;
-    readonly message: string;
-    readonly retryable: boolean;
-    readonly context?: AgentErrorContext;
-}
 export declare function agentProtocolSerializedJsonBytes(value: unknown): number;
 //# sourceMappingURL=types.d.ts.map

package/dist/foundation/types.js

@@ -1,5 +1,5 @@
 import { AgentProtocolValidationError } from "./validation.js";
-const AGENT_PROTOCOL_VERSION = 9;
+const AGENT_PROTOCOL_VERSION = 10;
 const AGENT_PROTOCOL_ID_MAX_LENGTH = 256;
 const AGENT_PROTOCOL_PROVIDER_REFERENCE_MAX_LENGTH = 512;
 const AGENT_PROTOCOL_PROVIDER_KEY_MAX_LENGTH = 100;