@agen-ai/agent-protocol 0.4.0 → 0.4.2

package/README.md

@@ -6,6 +6,12 @@ capabilities, typed operations, safe configuration and managed-content inventori
 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.
+The coordinated unpublished source candidate is `0.4.2` and uses Agent Protocol V12, including exact request
+unavailability and session decisions, forms and plan reviews. Published `0.4.1` retains V11;
+`0.4.0` retains V10. Source versioning does not establish registry publication.
+Keep all installed SDK packages at one coordinated version. The [0.4.2 migration
+guide](../../MIGRATING-TO-0.4.2.md) covers V12 envelopes, tagged session responses and
+the separate ownership of request eligibility, entered receipts and continuation output.
 
 ## Ownership boundary
 
@@ -30,7 +36,7 @@ carry no fabricated windows or hints.
 ## Entrypoints
 
 - `@agen-ai/agent-protocol` exports the complete plain API.
-- `/sessions`, `/turns`, `/requests`, `/events`, `/capabilities`, `/artifacts`, `/operations`,
+- `/sessions`, `/session-interactions`, `/turns`, `/requests`, `/events`, `/capabilities`, `/artifacts`, `/operations`,
   `/configuration`, `/managed-content`, `/integrations`, `/collaboration`, `/resources`, and
   `/account-quota`, `/effective-content`, `/commands`, `/extensions`, and `/environment` are focused plain entrypoints.
 - `/zod` is the only entrypoint that exposes Zod schemas.
@@ -50,7 +56,7 @@ import {
 } from '@agen-ai/agent-protocol';
 
 const event: AgentEvent = parseAgentEvent({
-  protocolVersion: 10,
+  protocolVersion: 12,
   type: 'content.delta',
   sessionId: parseAgentSessionId('external-session:42'),
   turnId: parseAgentTurnId('external-turn:9'),
@@ -65,7 +71,7 @@ const event: AgentEvent = parseAgentEvent({
 const roundTripped = parseAgentEvent(JSON.parse(JSON.stringify(event)));
 ```
 
-Serialized values carry `protocolVersion: 10`; TypeScript API names remain unsuffixed. Unknown
+Serialized values carry `protocolVersion: 12`; 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
@@ -79,9 +85,24 @@ attribute bag; source evidence belongs outside the portable event. File-change p
 across both BMP and supplementary Unicode characters.
 
 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
+bounded list of typed options. Every option declares its decision and a closed `consequence`.
+`scoped` contains precise `persistence` and `scope`; `provider_managed_remembrance` contains explicit
+unknown duration and applicability and a required bounded explanation. Flat persistence/scope
+fields are rejected in V12. Neither approval nor a delivered answer proves the provider wrote a rule.
+Resolutions select one exact offered `optionId` or explicitly cancel. Supported approval capability
+requires `providerManagedRemembrance`: false requires a nonempty readonly precise-mode tuple; true
+allows a bounded readonly array, including empty for a remembered-only provider. Scoped options
+must fit an exact declared mode; remembered options require the true capability. The SDK owns no
+permission database, answer cache, pattern editor, provider payload bag, or revoke API.
+
+Consumers should present each offered decision and consequence together. Several options can have
+the same immediate decision and different consequences, so selecting the first `approved` option
+cannot express a person's choice reliably. Return the exact selected `optionId`; keep deny-once,
+deny-and-remember, and explicit cancellation distinct. Show the remembered option's explanation
+and unknown duration/applicability without converting observed provider behavior into a session,
+workspace, path-pattern, or permanent grant.
+
+`context.usage.updated` reports
 bounded occupancy and optional monotonic cumulative counters for an advertised session or
 materialization measurement scope.
 
@@ -96,6 +117,81 @@ collapse unrelated pools into one percentage. Quantity units remain distinct fro
 which uses integer minor units with an explicit scale. None of these domains has a generic
 extension or metadata bag.
 
+## Request lifecycle and session interactions
+
+`request.unavailable` is a turn event with the existing session, turn and timestamp envelope.
+Its strict payload contains the exact `requestId` and a reason: `withdrawn`, `expired` or
+`unknown`. Each reason requires authoritative unavailability of that exact native callback;
+`expired` describes a provider observation. The event ends answer eligibility. It does not
+complete the execution or rewrite an entered response's delivery receipt. Runtime validation
+owns once-only retirement, original execution correlation and same-session request-ID uniqueness.
+
+`AgentSessionRequest` is a closed union of `decision`, `form` and `plan_review` descriptors
+outside a model turn. Each carries `requestId`, `sessionId`, a title, optional description,
+explicit offered choices and optional `expiresAt`. That expiry is only a provider-reported fact;
+the host's effective deadline is a separate runtime observation. Descriptors have no `turnId`,
+provider-native request ID, metadata bag or transport correlation field. The root and focused
+`@agen-ai/agent-protocol/session-interactions` entrypoints expose plain types and parsers.
+Only `/zod` exposes schemas. The `/json-schema` registry contains 35 deterministic contracts,
+including request/response schemas for each session kind and their complete unions.
+
+A workspace decision preserves its exact target and grant/decline consequences. A workspace
+`grant` is provider-managed, persistent and may affect other sessions; it covers the workspace
+rather than only the categories detected when the question was created. A `decline` leaves
+configuration gated without promising revocation, persisted denial or suppression of future
+questions. Present the target and consequences before applying a decision policy. V12 responses
+are tagged: `parseAgentSessionDecisionResponseFor(request, { kind: 'decision', choiceId })`.
+The earlier untagged `{ choiceId }` argument is rejected.
+
+Forms reuse the exact `AgentElicitationField` and `AgentElicitationAnswer` semantics from turn
+elicitation. A form offers exactly one `submit` action and optionally one `cancel` action, with
+unique choice IDs and distinct actions. Submitted responses carry `answers`; canceled responses
+carry no answers. Required fields, kinds, declared select values, custom-choice permission and
+selection limits are checked against the offered descriptor. Cancellation is an explicit offered
+human action and is never synthesized by timeout or cleanup.
+
+Plan reviews contain the complete actual offered text in an immutable `AgentSessionPlanSnapshot`,
+with a neutral `planId`, exact `revision`, title and `plain_text` or `markdown` content. They do
+not dereference paths or URLs. Each offered action is `approve`, `revise` or `abandon`, with unique
+choice IDs and distinct actions; a mapping must offer the action explicitly. Every response
+identifies the exact plan and revision. Only revision responses carry nonblank `feedback`.
+Content changes require a fresh revision and request ID. These identities grant no execution
+or replay authority.
+
+`parseAgentSessionResponseFor(request, response)` and the kind-specific helpers reject a wrong
+kind, unoffered choice, mismatched action, invalid field answer and stale plan identity/revision.
+Throwing parsers and their `safeParse...` counterparts use validator-neutral issues. Parsing
+creates detached readonly snapshots and rejects unknown fields, cyclic material, accessors and
+non-JSON values before invoking a getter. The nominal decision/form/review choice IDs, plan ID
+and plan revision are distinct TypeScript types granted only after canonical string validation.
+
+`AgentSessionAcceptedResponse` is the bounded accepted-response projection: it retains kind,
+choice and action, plus plan identity/revision when applicable. It omits sensitive form answers
+and revision feedback. Actual response authority belongs to the runtime's bound
+`AgentSessionInteraction.respond` capability. Process-local callbacks, human-wait policy,
+delivery receipts, terminal settlement and cleanup are documented by
+[`@agen-ai/agent-runtime`](../agent-runtime/README.md#session-lifetime-interactions).
+
+| Portable bound | Maximum |
+| --- | --- |
+| Every serialized session request | 65,536 UTF-8 bytes |
+| Serialized decision response | 1,024 UTF-8 bytes |
+| Serialized form or plan-review response | 65,536 UTF-8 bytes |
+| Offered choices | 16, with unique IDs and distinct form/review actions |
+| Choice ID, plan ID and plan revision | 128 UTF-8 bytes each |
+| Request/plan title and choice label | 120 characters |
+| Request description | 4,000 characters |
+| Choice description | 1,000 characters |
+| Workspace target path | 4,096 UTF-8 bytes |
+| Form fields / options per select / text value | 16 / 100 / 4,000 characters |
+| Complete plan text | 49,152 UTF-8 bytes within the request bound |
+| Revision feedback | 4,000 characters and 16,384 UTF-8 bytes |
+
+The JSON Schema artifacts name residual parser invariants, including serialized UTF-8 bytes,
+identity/action uniqueness, exact offered-choice membership, form-field correlation and exact
+plan/revision matching. Portable session opening, configuration and turn input do not carry
+runtime human-wait policy or callbacks.
+
 ## Errors and trust
 
 `AgentError` contains required `category`, stable `code`, safe `message`, tagged `recovery`, and
@@ -190,18 +286,19 @@ before delegation; a composer can use the same pure functions to preserve and ex
 
 ## Versioning and release
 
-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.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
-consumer outside the monorepo:
+Agent Protocol V12 defines the contract shared by this package, `@agen-ai/validation`, and
+`@agen-ai/agent-runtime`. The coordinated source release is `0.4.2`; published `0.4.1` retains
+V11 and `0.4.0` retains V10. Registry publication and dist-tag state are release metadata outside
+this contract. Earlier public releases remain historical. The complete seven-package public
+release inventory must use one coordinated source version.
+
+Protocol V12 is independent of private transport and product persistence versions and replaces
+V11 at live boundaries. There is one current parser. V11 and older serialized data require the
+historical owner's frozen decoder and are rejected by the live V12 parser where versioned.
+The environment and account-quota namespaces each retain their own schema version 1.
+
+The repository release proof builds and packs the exact seven-package release set, rejects
+workspace-only or private references, then typechecks and runs a consumer outside the monorepo.
 
 From the public repository root, run `pnpm check` to execute the same packed-consumer proof.
 

package/dist/capabilities/types.d.ts

@@ -90,9 +90,14 @@ export interface AgentApprovalCapabilityMode {
 }
 export type AgentApprovalCapability = Readonly<{
     kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    modes: readonly [AgentApprovalCapabilityMode, ...AgentApprovalCapabilityMode[]];
+    providerManagedRemembrance: false;
 }> | Readonly<{
     kind: 'supported';
     modes: readonly AgentApprovalCapabilityMode[];
+    providerManagedRemembrance: true;
 }>;
 export type AgentContextUsageCapability = Readonly<{
     kind: 'unsupported';
@@ -149,7 +154,7 @@ export type AgentTurnSteeringCapability = Readonly<{
     input: AgentOperationInputCapability;
 }>;
 export interface AgentCapabilities {
-    readonly protocolVersion: 10;
+    readonly protocolVersion: 12;
     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.retrying", "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", "request.unavailable", "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: 10;
+    readonly protocolVersion: 12;
     readonly type: Type;
     readonly sessionId: AgentSessionId;
     readonly providerRefs?: AgentProviderRefs;
@@ -50,6 +50,12 @@ export type AgentDiffUpdatedEvent = AgentTurnEventBase<'turn.diff.updated', Agen
 export type AgentRequestOpenedEvent = AgentTurnEventBase<'request.opened', Readonly<{
     request: AgentRequest;
 }>>;
+export declare const AGENT_REQUEST_UNAVAILABLE_REASONS: readonly ["withdrawn", "expired", "unknown"];
+export type AgentRequestUnavailableReason = (typeof AGENT_REQUEST_UNAVAILABLE_REASONS)[number];
+export type AgentRequestUnavailableEvent = AgentTurnEventBase<'request.unavailable', Readonly<{
+    requestId: AgentRequestId;
+    reason: AgentRequestUnavailableReason;
+}>>;
 export type AgentProgressUpdatedEvent = AgentTurnEventBase<'progress.updated', Readonly<{
     progressId: string;
     kind: 'task' | 'hook' | 'tool' | 'unknown';
@@ -94,6 +100,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 | AgentRuntimeRetryingEvent | AgentRuntimeWarningEvent | AgentRuntimeErrorEvent | AgentProviderDiagnosticEvent;
+export type AgentEvent = AgentTurnStartedEvent | AgentTurnStateChangedEvent | AgentTurnCompletedEvent | AgentItemStartedEvent | AgentItemUpdatedEvent | AgentItemCompletedEvent | AgentContentDeltaEvent | AgentPlanUpdatedEvent | AgentPlanProposedEvent | AgentDiffUpdatedEvent | AgentRequestOpenedEvent | AgentRequestUnavailableEvent | AgentProgressUpdatedEvent | AgentContextUsageUpdatedEvent | AgentArtifactReferencedEvent | AgentOperationUpdatedEvent | AgentCollaborationUpdatedEvent | AgentResourceUpdatedEvent | AgentRuntimeRetryingEvent | AgentRuntimeWarningEvent | AgentRuntimeErrorEvent | AgentProviderDiagnosticEvent;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/events/types.js

@@ -10,6 +10,7 @@ const AGENT_EVENT_TYPES = [
   "turn.plan.proposed",
   "turn.diff.updated",
   "request.opened",
+  "request.unavailable",
   "progress.updated",
   "context.usage.updated",
   "artifact.referenced",
@@ -21,6 +22,8 @@ const AGENT_EVENT_TYPES = [
   "runtime.error",
   "provider.diagnostic"
 ];
+const AGENT_REQUEST_UNAVAILABLE_REASONS = ["withdrawn", "expired", "unknown"];
 export {
-  AGENT_EVENT_TYPES
+  AGENT_EVENT_TYPES,
+  AGENT_REQUEST_UNAVAILABLE_REASONS
 };

package/dist/foundation/types.d.ts

@@ -1,7 +1,7 @@
 export type { AgentProtocolParseFailure, AgentProtocolParseResult, AgentProtocolParseSuccess, ValidationIssue, ValidationPathSegment, } from './validation.js';
 export { AgentProtocolValidationError } from './validation.js';
 export type { AgentError, AgentErrorContext } from '../failures/types.js';
-export declare const AGENT_PROTOCOL_VERSION: 10;
+export declare const AGENT_PROTOCOL_VERSION: 12;
 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;

package/dist/foundation/types.js

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