@agen-ai/agent-protocol 0.4.0 → 0.4.1

package/README.md

@@ -6,6 +6,8 @@ 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 source version is unpublished `0.4.1` and uses Agent Protocol V11. The published
+release remains `0.4.0` with V10. The source candidate also includes session-decision data.
 
 ## Ownership boundary
 
@@ -30,7 +32,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 +52,7 @@ import {
 } from '@agen-ai/agent-protocol';
 
 const event: AgentEvent = parseAgentEvent({
-  protocolVersion: 10,
+  protocolVersion: 11,
   type: 'content.delta',
   sessionId: parseAgentSessionId('external-session:42'),
   turnId: parseAgentTurnId('external-turn:9'),
@@ -65,7 +67,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: 11`; 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 +81,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 V11. 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 +113,45 @@ 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.
 
+## Session-decision data
+
+`AgentSessionDecisionRequest` describes a bounded decision outside any model turn. It carries
+`requestId`, `sessionId`, a title, optional description, a workspace target, `expiresAt` and
+one to sixteen uniquely identified choices. It has no `turnId`, provider-native request ID,
+open metadata bag or transport correlation field. Use the root entrypoint or the focused
+`@agen-ai/agent-protocol/session-interactions` entrypoint for its plain types and parsers.
+Only `/zod` exposes the corresponding schemas; the deterministic JSON Schema surface retains
+the same portable data boundary.
+
+Every choice describes its consequence. A workspace `grant` is provider-managed, persistent
+and may affect other sessions; it authorizes the workspace rather than only the categories
+detected when the question was created. A `decline` leaves configuration gated and does not
+promise revocation of existing trust, persisted denial or suppression of future questions.
+Hosts must present the target and consequences before applying their decision policy.
+Descriptions and opaque IDs are data, not execution authority.
+
+`parseAgentSessionDecisionResponseFor(request, { choiceId })` validates that the response
+selects a choice offered by that exact request. The response has no free-form answer or
+caller-supplied request/session correlation. Actual response authority belongs to the runtime's
+bound `AgentSessionInteraction.respond` capability. The protocol defines portable data;
+callback lifetime, deadlines, delivery receipts, terminal settlement and cleanup are documented
+by [`@agen-ai/agent-runtime`](../agent-runtime/README.md#session-lifetime-interactions).
+
+| Portable bound | Maximum |
+| --- | --- |
+| Serialized request | 65,536 UTF-8 bytes |
+| Serialized response | 1,024 UTF-8 bytes |
+| Offered choices | 16, with unique IDs |
+| Choice ID | 128 UTF-8 bytes |
+| Request title and choice label | 120 characters |
+| Request description | 4,000 characters |
+| Choice description | 1,000 characters |
+| Workspace target path | 4,096 UTF-8 bytes |
+
+Throwing parsers and `safeParse...` variants use the existing validator-neutral issue contract.
+Unknown fields, duplicate choice IDs and unsupported consequence shapes reject. These values
+remain separate from turn approval/elicitation data and introduce no protocol-version change.
+
 ## Errors and trust
 
 `AgentError` contains required `category`, stable `code`, safe `message`, tagged `recovery`, and
@@ -190,13 +246,14 @@ 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
+Agent Protocol V11 defines the contract shared by this package, `@agen-ai/validation`, and
+`@agen-ai/agent-runtime`. The coordinated source SDK is unpublished `0.4.1`; the published
+release is `0.4.0` with V10. 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
+The complete seven-package public release inventory must use one coordinated source version. Protocol V11 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
+persistence versions and directly replaces V10 at live boundaries. There is one current parser. V10
+and older serialized data require the historical owner's frozen decoder and are rejected by the live V11 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

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: 11;
     readonly providerKey: AgentProviderKey;
     readonly sessions: Readonly<{
         create: true;

package/dist/events/types.d.ts

@@ -8,7 +8,7 @@ import type { AgentContentStreamKind, AgentContextUsage, AgentDiffSummary, Agent
 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: 10;
+    readonly protocolVersion: 11;
     readonly type: Type;
     readonly sessionId: AgentSessionId;
     readonly providerRefs?: AgentProviderRefs;

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: 11;
 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 = 11;
 const AGENT_PROTOCOL_ID_MAX_LENGTH = 256;
 const AGENT_PROTOCOL_PROVIDER_REFERENCE_MAX_LENGTH = 512;
 const AGENT_PROTOCOL_PROVIDER_KEY_MAX_LENGTH = 100;