@agen-ai/agent-protocol 0.1.0 → 0.2.0

package/README.md

@@ -41,7 +41,7 @@ import {
 } from '@agen-ai/agent-protocol';
 
 const event: AgentEvent = parseAgentEvent({
-  protocolVersion: 6,
+  protocolVersion: 7,
   type: 'content.delta',
   sessionId: parseAgentSessionId('external-session:42'),
   turnId: parseAgentTurnId('external-turn:9'),
@@ -56,17 +56,25 @@ const event: AgentEvent = parseAgentEvent({
 const roundTripped = parseAgentEvent(JSON.parse(JSON.stringify(event)));
 ```
 
-Serialized values carry `protocolVersion: 6`; TypeScript API names remain unsuffixed. Unknown
+Serialized values carry `protocolVersion: 7`; 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
 shared, while commands, file changes, managed tools, web/computer activity, image views, and
-reviews expose only their bounded semantic `details`. Message, reasoning, plan, compaction, and
-unknown items have no details. Review details are required and distinguish an entered target from
-an exited report. There is no metadata or provider-native attribute bag; source evidence belongs
-outside the portable event. File-change producers can use `compareStringsByUnicodeCodePoint` to
-emit the canonical path ordering required by the protocol across both BMP and supplementary
-Unicode characters.
+reviews expose only their bounded semantic `details`. Context-compaction items require neutral
+details describing the trigger, optional before/after occupancy, duration, and bounded summary
+preview. Message, reasoning, plan, and unknown items have no details. Review details are required
+and distinguish an entered target from an exited report. There is no metadata or provider-native
+attribute bag; source evidence belongs outside the portable event. File-change producers can use
+`compareStringsByUnicodeCodePoint` to emit the canonical path ordering required by the protocol
+across both BMP and supplementary Unicode characters.
+
+V7 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 occupancy and optional monotonic cumulative counters for an advertised session or
+materialization measurement scope.
 
 ## Errors and trust
 
@@ -86,10 +94,11 @@ validated protocol output remains canonical across transports and consumers.
 
 ## Versioning and release
 
-The package is at `0.1.0` while the public API is still being proven with external adapters. Minor
+The package is at `0.2.0` while the public API is still being proven with external adapters. Minor
 releases may include breaking changes during this beta period. Every such change will be called out
-in the release notes. Protocol V6 is independent of any host transport or product persistence
-version.
+in the release notes. Protocol V7 is independent of any host transport or product persistence
+version. Version `0.2.0` is a direct break from V6/`0.1.0`; there is no compatibility parser. See
+the repository `MIGRATING-TO-0.2.md` guide for the complete API change matrix.
 
 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

@@ -1,6 +1,7 @@
 import type { AgentArtifactKind } from '../artifacts/index.js';
 import type { AgentProviderKey } from '../foundation/index.js';
-import type { AgentImageInputMediaType, AgentImageInputSourceKind, AgentTurnInteractionMode } from '../turns/types.js';
+import type { AgentContextCompactionTrigger, AgentContextCumulativeUsageField, AgentContextMeasurementScope, AgentImageInputMediaType, AgentImageInputSourceKind, AgentTurnInteractionMode } from '../turns/types.js';
+import type { AgentApprovalPersistence, AgentApprovalScopeKind } from '../requests/types.js';
 export declare const AGENT_ELICITATION_MODES: readonly ["unsupported", "text", "structured"];
 export declare const AGENT_FILE_CHANGE_MODES: readonly ["none", "final_diff", "structured"];
 export declare const AGENT_AUTHENTICATION_FLOWS: readonly ["device_code", "browser", "terminal"];
@@ -35,6 +36,30 @@ export type AgentAuthenticationCapability = Readonly<{
     kind: 'supported';
     flows: readonly AgentAuthenticationFlow[];
 }>;
+export interface AgentApprovalCapabilityMode {
+    readonly persistence: AgentApprovalPersistence;
+    readonly scopeKinds: readonly AgentApprovalScopeKind[];
+}
+export type AgentApprovalCapability = Readonly<{
+    kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    modes: readonly AgentApprovalCapabilityMode[];
+}>;
+export type AgentContextUsageCapability = Readonly<{
+    kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    measurementScopes: readonly AgentContextMeasurementScope[];
+    cumulativeFields: readonly AgentContextCumulativeUsageField[];
+}>;
+export type AgentContextCompactionCapability = Readonly<{
+    kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    triggers: readonly AgentContextCompactionTrigger[];
+    sameSessionContinuation: boolean;
+}>;
 export type AgentImageInputCapability = Readonly<{
     kind: 'unsupported';
 }> | Readonly<{
@@ -60,7 +85,7 @@ export type AgentTurnSteeringCapability = Readonly<{
     input: AgentOperationInputCapability;
 }>;
 export interface AgentCapabilities {
-    readonly protocolVersion: 6;
+    readonly protocolVersion: 7;
     readonly providerKey: AgentProviderKey;
     readonly sessions: Readonly<{
         create: true;
@@ -73,9 +98,13 @@ export interface AgentCapabilities {
         steer: AgentTurnSteeringCapability;
     }>;
     readonly requests: Readonly<{
-        approval: boolean;
+        approval: AgentApprovalCapability;
         elicitation: AgentElicitationCapability;
     }>;
+    readonly context: Readonly<{
+        usage: AgentContextUsageCapability;
+        compaction: AgentContextCompactionCapability;
+    }>;
     readonly input: AgentOperationInputCapability;
     readonly output: Readonly<{
         streaming: boolean;

package/dist/events/types.d.ts

@@ -1,11 +1,11 @@
 import type { AgentArtifactDescriptor } from '../artifacts/index.js';
 import type { AgentArtifactId, AgentError, AgentErrorContext, AgentIsoDateTime, AgentItemId, AgentProviderRefs, AgentRequestId, AgentSessionId, AgentTurnId } from '../foundation/index.js';
 import type { AgentRequest } from '../requests/index.js';
-import type { AgentContentStreamKind, 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", "artifact.referenced", "runtime.warning", "runtime.error", "provider.diagnostic"];
+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", "runtime.warning", "runtime.error", "provider.diagnostic"];
 export type AgentEventType = (typeof AGENT_EVENT_TYPES)[number];
 interface AgentEventBase<Type extends AgentEventType, Payload> {
-    readonly protocolVersion: 6;
+    readonly protocolVersion: 7;
     readonly type: Type;
     readonly sessionId: AgentSessionId;
     readonly providerRefs?: AgentProviderRefs;
@@ -56,6 +56,7 @@ export type AgentProgressUpdatedEvent = AgentTurnEventBase<'progress.updated', R
     current?: number;
     total?: number;
 }>>;
+export type AgentContextUsageUpdatedEvent = AgentTurnEventBase<'context.usage.updated', AgentContextUsage>;
 export type AgentArtifactReferencedEvent = AgentOptionallyTurnScopedEventBase<'artifact.referenced', Readonly<{
     artifact: AgentArtifactDescriptor;
 }>>;
@@ -73,6 +74,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 | AgentArtifactReferencedEvent | AgentRuntimeWarningEvent | AgentRuntimeErrorEvent | AgentProviderDiagnosticEvent;
+export type AgentEvent = AgentTurnStartedEvent | AgentTurnStateChangedEvent | AgentTurnCompletedEvent | AgentItemStartedEvent | AgentItemUpdatedEvent | AgentItemCompletedEvent | AgentContentDeltaEvent | AgentPlanUpdatedEvent | AgentPlanProposedEvent | AgentDiffUpdatedEvent | AgentRequestOpenedEvent | AgentProgressUpdatedEvent | AgentContextUsageUpdatedEvent | AgentArtifactReferencedEvent | AgentRuntimeWarningEvent | AgentRuntimeErrorEvent | AgentProviderDiagnosticEvent;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/events/types.js

@@ -11,6 +11,7 @@ const AGENT_EVENT_TYPES = [
   "turn.diff.updated",
   "request.opened",
   "progress.updated",
+  "context.usage.updated",
   "artifact.referenced",
   "runtime.warning",
   "runtime.error",

package/dist/foundation/parsers.d.ts

@@ -1,4 +1,4 @@
-import type { AgentArtifactId, AgentConfigurationRevisionId, AgentError, AgentInstanceId, AgentIsoDateTime, AgentItemId, AgentJsonValue, AgentProviderConversationId, AgentProviderHistoryAnchor, AgentProviderItemRef, AgentProviderKey, AgentProviderRefs, AgentProviderRequestRef, AgentProviderTurnRef, AgentRequestFieldId, AgentRequestId, AgentSessionId, AgentTurnId } from './types.js';
+import type { AgentArtifactId, AgentApprovalOptionId, AgentConfigurationRevisionId, AgentError, AgentInstanceId, AgentIsoDateTime, AgentItemId, AgentJsonValue, AgentProviderConversationId, AgentProviderHistoryAnchor, AgentProviderItemRef, AgentProviderKey, AgentProviderRefs, AgentProviderRequestRef, AgentProviderTurnRef, AgentRequestFieldId, AgentRequestId, AgentSessionId, AgentTurnId } from './types.js';
 import type { AgentProtocolParseResult } from './validation.js';
 export declare const parseAgentInstanceId: (input: unknown) => AgentInstanceId;
 export declare const safeParseAgentInstanceId: (input: unknown) => AgentProtocolParseResult<AgentInstanceId>;
@@ -10,6 +10,8 @@ export declare const parseAgentItemId: (input: unknown) => AgentItemId;
 export declare const safeParseAgentItemId: (input: unknown) => AgentProtocolParseResult<AgentItemId>;
 export declare const parseAgentRequestId: (input: unknown) => AgentRequestId;
 export declare const safeParseAgentRequestId: (input: unknown) => AgentProtocolParseResult<AgentRequestId>;
+export declare const parseAgentApprovalOptionId: (input: unknown) => AgentApprovalOptionId;
+export declare const safeParseAgentApprovalOptionId: (input: unknown) => AgentProtocolParseResult<AgentApprovalOptionId>;
 export declare const parseAgentRequestFieldId: (input: unknown) => AgentRequestFieldId;
 export declare const safeParseAgentRequestFieldId: (input: unknown) => AgentProtocolParseResult<AgentRequestFieldId>;
 export declare const parseAgentArtifactId: (input: unknown) => AgentArtifactId;

package/dist/foundation/parsers.js

@@ -1,6 +1,7 @@
 import { parseWithSchema, safeParseWithSchema } from "../internal/parsers.js";
 import {
   AgentArtifactIdSchema,
+  AgentApprovalOptionIdSchema,
   AgentConfigurationRevisionIdSchema,
   AgentErrorSchema,
   AgentInstanceIdSchema,
@@ -30,6 +31,9 @@ const sessionIdParser = idParser(AgentSessionIdSchema);
 const turnIdParser = idParser(AgentTurnIdSchema);
 const itemIdParser = idParser(AgentItemIdSchema);
 const requestIdParser = idParser(AgentRequestIdSchema);
+const approvalOptionIdParser = idParser(
+  AgentApprovalOptionIdSchema
+);
 const requestFieldIdParser = idParser(
   AgentRequestFieldIdSchema
 );
@@ -62,6 +66,8 @@ const parseAgentItemId = itemIdParser.parse;
 const safeParseAgentItemId = itemIdParser.safeParse;
 const parseAgentRequestId = requestIdParser.parse;
 const safeParseAgentRequestId = requestIdParser.safeParse;
+const parseAgentApprovalOptionId = approvalOptionIdParser.parse;
+const safeParseAgentApprovalOptionId = approvalOptionIdParser.safeParse;
 const parseAgentRequestFieldId = requestFieldIdParser.parse;
 const safeParseAgentRequestFieldId = requestFieldIdParser.safeParse;
 const parseAgentArtifactId = artifactIdParser.parse;
@@ -109,6 +115,7 @@ function safeParseAgentError(input) {
   return safeParseWithSchema(AgentErrorSchema, input);
 }
 export {
+  parseAgentApprovalOptionId,
   parseAgentArtifactId,
   parseAgentConfigurationRevisionId,
   parseAgentError,
@@ -127,6 +134,7 @@ export {
   parseAgentRequestId,
   parseAgentSessionId,
   parseAgentTurnId,
+  safeParseAgentApprovalOptionId,
   safeParseAgentArtifactId,
   safeParseAgentConfigurationRevisionId,
   safeParseAgentError,

package/dist/foundation/types.d.ts

@@ -1,6 +1,6 @@
 export type { AgentProtocolParseFailure, AgentProtocolParseResult, AgentProtocolParseSuccess, ValidationIssue, ValidationPathSegment, } from './validation.js';
 export { AgentProtocolValidationError } from './validation.js';
-export declare const AGENT_PROTOCOL_VERSION: 6;
+export declare const AGENT_PROTOCOL_VERSION: 7;
 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;
@@ -22,6 +22,7 @@ export type AgentSessionId = AgentProtocolId<'AgentSessionId'>;
 export type AgentTurnId = AgentProtocolId<'AgentTurnId'>;
 export type AgentItemId = AgentProtocolId<'AgentItemId'>;
 export type AgentRequestId = AgentProtocolId<'AgentRequestId'>;
+export type AgentApprovalOptionId = AgentProtocolId<'AgentApprovalOptionId'>;
 export type AgentRequestFieldId = AgentProtocolId<'AgentRequestFieldId'>;
 export type AgentArtifactId = AgentProtocolId<'AgentArtifactId'>;
 export type AgentConfigurationRevisionId = AgentProtocolId<'AgentConfigurationRevisionId'>;

package/dist/foundation/types.js

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