@agen-ai/agent-protocol 0.2.2 → 0.2.3

package/README.md

@@ -2,8 +2,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, portable artifact descriptors, and provider-observed events. The package does not
-define a transport or execution runtime.
+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.
 
 ## Ownership boundary
 
@@ -22,8 +23,9 @@ that product concern belongs to the caller's control plane.
 ## Entrypoints
 
 - `@agen-ai/agent-protocol` exports the complete plain API.
-- `/sessions`, `/turns`, `/requests`, `/events`, `/capabilities`, and `/artifacts` are focused plain
-  entrypoints.
+- `/sessions`, `/turns`, `/requests`, `/events`, `/capabilities`, `/artifacts`, `/operations`,
+  `/configuration`, `/managed-content`, `/integrations`, `/collaboration`, and `/resources` are
+  focused plain entrypoints.
 - `/zod` is the only entrypoint that exposes Zod schemas.
 - `/json-schema` exposes deterministic draft 2020-12 schema artifacts.
 
@@ -41,7 +43,7 @@ import {
 } from '@agen-ai/agent-protocol';
 
 const event: AgentEvent = parseAgentEvent({
-  protocolVersion: 7,
+  protocolVersion: 8,
   type: 'content.delta',
   sessionId: parseAgentSessionId('external-session:42'),
   turnId: parseAgentTurnId('external-turn:9'),
@@ -56,7 +58,7 @@ const event: AgentEvent = parseAgentEvent({
 const roundTripped = parseAgentEvent(JSON.parse(JSON.stringify(event)));
 ```
 
-Serialized values carry `protocolVersion: 7`; TypeScript API names remain unsuffixed. Unknown
+Serialized values carry `protocolVersion: 8`; 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
@@ -69,13 +71,21 @@ 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.
 
-V7 approval requests correlate to one live item or exact proposed-plan artifact and provide a
+V8 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.
 
+Capabilities state technical possibility only. Dynamic operations, configuration fields, managed
+content, and integrations are separate bounded, revisioned catalogs; capability declarations do
+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
+extension or metadata bag.
+
 ## Errors and trust
 
 Throwing parsers raise `AgentProtocolValidationError`, a `TypeError` with stable, JSON-safe
@@ -94,11 +104,11 @@ validated protocol output remains canonical across transports and consumers.
 
 ## Versioning and release
 
-The package is at `0.2.2` 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 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 package is at `0.2.3` 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.
 
 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,11 +1,15 @@
 import type { AgentArtifactKind } from '../artifacts/index.js';
+import type { AgentCollaborationControlAction, AgentCollaborationRole } from '../collaboration/index.js';
+import type { AgentConfigurationFieldKind } from '../configuration/index.js';
 import type { AgentProviderKey } from '../foundation/index.js';
+import type { AgentIntegrationKind } from '../integrations/index.js';
+import type { AgentManagedContentKind } from '../managedContent/index.js';
+import type { AgentOperationExecutionMode, AgentOperationFieldKind, AgentOperationKind } from '../operations/index.js';
+import type { AgentGeneratedResourceKind } from '../resources/index.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"];
+import type { AgentApprovalPersistence, AgentApprovalScopeKind, AgentElicitationFieldKind } from '../requests/types.js';
 export declare const AGENT_FILE_CHANGE_MODES: readonly ["none", "final_diff", "structured"];
 export declare const AGENT_AUTHENTICATION_FLOWS: readonly ["device_code", "browser", "terminal"];
-export type AgentElicitationMode = (typeof AGENT_ELICITATION_MODES)[number];
 export type AgentFileChangeMode = (typeof AGENT_FILE_CHANGE_MODES)[number];
 export type AgentAuthenticationFlow = (typeof AGENT_AUTHENTICATION_FLOWS)[number];
 export type AgentBranchCapability = Readonly<{
@@ -16,19 +20,62 @@ export type AgentBranchCapability = Readonly<{
 export type AgentElicitationCapability = Readonly<{
     kind: 'unsupported';
 }> | Readonly<{
-    kind: 'text';
-}> | Readonly<{
-    kind: 'structured';
+    kind: 'supported';
+    fieldKinds: readonly AgentElicitationFieldKind[];
+    maxFields: number;
+    sensitiveFields: boolean;
 }>;
-export interface AgentConfigurationFieldCapability {
-    readonly key: string;
-    readonly optionIds: readonly string[];
-}
 export type AgentConfigurationCapability = Readonly<{
     kind: 'managed';
 }> | Readonly<{
     kind: 'selectable';
-    fields: readonly AgentConfigurationFieldCapability[];
+    fieldKinds: readonly AgentConfigurationFieldKind[];
+    maxFields: number;
+}>;
+export type AgentOperationsCapability = Readonly<{
+    kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    operationKinds: readonly AgentOperationKind[];
+    fieldKinds: readonly AgentOperationFieldKind[];
+    executionModes: readonly AgentOperationExecutionMode[];
+    maxOperations: number;
+    maxFieldsPerOperation: number;
+}>;
+export type AgentManagedContentCapability = Readonly<{
+    kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    contentKinds: readonly AgentManagedContentKind[];
+    maxEntries: number;
+}>;
+export type AgentIntegrationsCapability = Readonly<{
+    kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    integrationKinds: readonly AgentIntegrationKind[];
+    maxIntegrations: number;
+    maxServersPerIntegration: number;
+    maxToolsPerServer: number;
+    maxResourcesPerServer: number;
+}>;
+export type AgentCollaborationCapability = Readonly<{
+    kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    roles: readonly AgentCollaborationRole[];
+    controlActions: readonly AgentCollaborationControlAction[];
+    maxDepth: number;
+    maxChildrenPerNode: number;
+    maxActiveNodes: number;
+}>;
+export type AgentGeneratedResourcesCapability = Readonly<{
+    kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    resourceKinds: readonly AgentGeneratedResourceKind[];
+    maxResourcesPerTurn: number;
+    maxBytesPerResource: number;
 }>;
 export type AgentAuthenticationCapability = Readonly<{
     kind: 'unsupported';
@@ -85,7 +132,7 @@ export type AgentTurnSteeringCapability = Readonly<{
     input: AgentOperationInputCapability;
 }>;
 export interface AgentCapabilities {
-    readonly protocolVersion: 7;
+    readonly protocolVersion: 8;
     readonly providerKey: AgentProviderKey;
     readonly sessions: Readonly<{
         create: true;
@@ -113,12 +160,11 @@ export interface AgentCapabilities {
         artifactKinds: readonly AgentArtifactKind[];
     }>;
     readonly configuration: AgentConfigurationCapability;
-    readonly interactionExtensions: Readonly<{
-        slashCommands: boolean;
-        mcp: boolean;
-        subagents: boolean;
-        imageGeneration: boolean;
-    }>;
+    readonly operations: AgentOperationsCapability;
+    readonly managedContent: AgentManagedContentCapability;
+    readonly integrations: AgentIntegrationsCapability;
+    readonly collaboration: AgentCollaborationCapability;
+    readonly generatedResources: AgentGeneratedResourcesCapability;
     readonly authentication: AgentAuthenticationCapability;
     readonly versionReporting: boolean;
 }

package/dist/capabilities/types.js

@@ -1,8 +1,3 @@
-const AGENT_ELICITATION_MODES = [
-  "unsupported",
-  "text",
-  "structured"
-];
 const AGENT_FILE_CHANGE_MODES = [
   "none",
   "final_diff",
@@ -15,6 +10,5 @@ const AGENT_AUTHENTICATION_FLOWS = [
 ];
 export {
   AGENT_AUTHENTICATION_FLOWS,
-  AGENT_ELICITATION_MODES,
   AGENT_FILE_CHANGE_MODES
 };

package/dist/collaboration/index.d.ts

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

package/dist/collaboration/index.js

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

package/dist/collaboration/parsers.d.ts

@@ -0,0 +1,9 @@
+import type { AgentProtocolParseResult } from '../foundation/index.js';
+import type { AgentCollaborationControlInput, AgentCollaborationNode, AgentCollaborationSpawnInput } from './types.js';
+export declare function parseAgentCollaborationNode(input: unknown): AgentCollaborationNode;
+export declare function safeParseAgentCollaborationNode(input: unknown): AgentProtocolParseResult<AgentCollaborationNode>;
+export declare function parseAgentCollaborationSpawnInput(input: unknown): AgentCollaborationSpawnInput;
+export declare function safeParseAgentCollaborationSpawnInput(input: unknown): AgentProtocolParseResult<AgentCollaborationSpawnInput>;
+export declare function parseAgentCollaborationControlInput(input: unknown): AgentCollaborationControlInput;
+export declare function safeParseAgentCollaborationControlInput(input: unknown): AgentProtocolParseResult<AgentCollaborationControlInput>;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/collaboration/parsers.js

@@ -0,0 +1,32 @@
+import { parseWithSchema, safeParseWithSchema } from "../internal/parsers.js";
+import {
+  AgentCollaborationControlInputSchema,
+  AgentCollaborationNodeSchema,
+  AgentCollaborationSpawnInputSchema
+} from "../zod/collaboration.js";
+function parseAgentCollaborationNode(input) {
+  return parseWithSchema(AgentCollaborationNodeSchema, input);
+}
+function safeParseAgentCollaborationNode(input) {
+  return safeParseWithSchema(AgentCollaborationNodeSchema, input);
+}
+function parseAgentCollaborationSpawnInput(input) {
+  return parseWithSchema(AgentCollaborationSpawnInputSchema, input);
+}
+function safeParseAgentCollaborationSpawnInput(input) {
+  return safeParseWithSchema(AgentCollaborationSpawnInputSchema, input);
+}
+function parseAgentCollaborationControlInput(input) {
+  return parseWithSchema(AgentCollaborationControlInputSchema, input);
+}
+function safeParseAgentCollaborationControlInput(input) {
+  return safeParseWithSchema(AgentCollaborationControlInputSchema, input);
+}
+export {
+  parseAgentCollaborationControlInput,
+  parseAgentCollaborationNode,
+  parseAgentCollaborationSpawnInput,
+  safeParseAgentCollaborationControlInput,
+  safeParseAgentCollaborationNode,
+  safeParseAgentCollaborationSpawnInput
+};

package/dist/collaboration/types.d.ts

@@ -0,0 +1,88 @@
+import type { AgentArtifactId, AgentCollaborationId, AgentError, AgentGeneratedResourceId, AgentIsoDateTime } from '../foundation/index.js';
+import type { AgentTurnInputContent } from '../turns/index.js';
+export declare const AGENT_COLLABORATION_ROLES: readonly ["delegate", "reviewer", "researcher", "specialist"];
+export declare const AGENT_COLLABORATION_STATUSES: readonly ["queued", "starting", "running", "waiting", "completed", "failed", "canceled"];
+export declare const AGENT_COLLABORATION_CONTROL_ACTIONS: readonly ["spawn", "steer", "stop", "close", "inspect"];
+export declare const AGENT_COLLABORATION_OUTCOMES: readonly ["completed", "failed", "canceled"];
+export declare const AGENT_COLLABORATION_STOP_REASONS: readonly ["user_requested", "timeout", "shutdown", "superseded", "other"];
+export declare const AGENT_COLLABORATION_USAGE_FIELDS: readonly ["inputTokens", "outputTokens", "reasoningTokens", "totalTokens", "modelCalls"];
+export declare const AGENT_COLLABORATION_TITLE_MAX_LENGTH = 200;
+export declare const AGENT_COLLABORATION_OBJECTIVE_MAX_LENGTH = 4000;
+export declare const AGENT_COLLABORATION_PROGRESS_MAX_LENGTH = 2000;
+export declare const AGENT_COLLABORATION_RESULT_REFERENCES_MAX_LENGTH = 100;
+export declare const AGENT_COLLABORATION_GRAPH_LIMITS: Readonly<{
+    maxNodes: 100;
+    maxDepth: 16;
+    maxChildrenPerNode: 100;
+    maxActiveNodes: 100;
+}>;
+export type AgentCollaborationRole = (typeof AGENT_COLLABORATION_ROLES)[number];
+export type AgentCollaborationStatus = (typeof AGENT_COLLABORATION_STATUSES)[number];
+export type AgentCollaborationControlAction = (typeof AGENT_COLLABORATION_CONTROL_ACTIONS)[number];
+export type AgentCollaborationOutcomeKind = (typeof AGENT_COLLABORATION_OUTCOMES)[number];
+export type AgentCollaborationStopReason = (typeof AGENT_COLLABORATION_STOP_REASONS)[number];
+export type AgentCollaborationUsageField = (typeof AGENT_COLLABORATION_USAGE_FIELDS)[number];
+export type AgentCollaborationOutcome = Readonly<{
+    kind: 'completed';
+}> | Readonly<{
+    kind: 'failed';
+    error: AgentError;
+}> | Readonly<{
+    kind: 'canceled';
+    reason: AgentCollaborationStopReason;
+}>;
+export type AgentCollaborationUsage = Readonly<{
+    kind: 'unavailable';
+}> | Readonly<{
+    kind: 'reported';
+    inputTokens?: number;
+    outputTokens?: number;
+    reasoningTokens?: number;
+    totalTokens?: number;
+    modelCalls?: number;
+}>;
+export interface AgentCollaborationNode {
+    readonly collaborationId: AgentCollaborationId;
+    readonly rootCollaborationId: AgentCollaborationId;
+    readonly parentCollaborationId?: AgentCollaborationId;
+    readonly role: AgentCollaborationRole;
+    readonly title: string;
+    readonly status: AgentCollaborationStatus;
+    readonly objective: string;
+    readonly progress?: string;
+    readonly usage: AgentCollaborationUsage;
+    readonly outcome?: AgentCollaborationOutcome;
+    readonly createdAt: AgentIsoDateTime;
+    readonly updatedAt: AgentIsoDateTime;
+    readonly terminalAt?: AgentIsoDateTime;
+    readonly closedAt?: AgentIsoDateTime;
+    readonly artifactIds?: readonly AgentArtifactId[];
+    readonly resourceIds?: readonly AgentGeneratedResourceId[];
+}
+export interface AgentCollaborationSpawnInput {
+    readonly collaborationId: AgentCollaborationId;
+    readonly parentCollaborationId?: AgentCollaborationId;
+    readonly role: AgentCollaborationRole;
+    readonly title: string;
+    readonly objective: string;
+    readonly createdAt: AgentIsoDateTime;
+}
+export interface AgentCollaborationSteerInput extends AgentTurnInputContent {
+    readonly action: 'steer';
+    readonly collaborationId: AgentCollaborationId;
+}
+export interface AgentCollaborationStopInput {
+    readonly action: 'stop';
+    readonly collaborationId: AgentCollaborationId;
+    readonly reason: AgentCollaborationStopReason;
+}
+export interface AgentCollaborationCloseInput {
+    readonly action: 'close';
+    readonly collaborationId: AgentCollaborationId;
+}
+export interface AgentCollaborationInspectInput {
+    readonly action: 'inspect';
+    readonly collaborationId: AgentCollaborationId;
+}
+export type AgentCollaborationControlInput = AgentCollaborationSteerInput | AgentCollaborationStopInput | AgentCollaborationCloseInput | AgentCollaborationInspectInput;
+//# sourceMappingURL=types.d.ts.map

package/dist/collaboration/types.js

@@ -0,0 +1,64 @@
+const AGENT_COLLABORATION_ROLES = [
+  "delegate",
+  "reviewer",
+  "researcher",
+  "specialist"
+];
+const AGENT_COLLABORATION_STATUSES = [
+  "queued",
+  "starting",
+  "running",
+  "waiting",
+  "completed",
+  "failed",
+  "canceled"
+];
+const AGENT_COLLABORATION_CONTROL_ACTIONS = [
+  "spawn",
+  "steer",
+  "stop",
+  "close",
+  "inspect"
+];
+const AGENT_COLLABORATION_OUTCOMES = [
+  "completed",
+  "failed",
+  "canceled"
+];
+const AGENT_COLLABORATION_STOP_REASONS = [
+  "user_requested",
+  "timeout",
+  "shutdown",
+  "superseded",
+  "other"
+];
+const AGENT_COLLABORATION_USAGE_FIELDS = [
+  "inputTokens",
+  "outputTokens",
+  "reasoningTokens",
+  "totalTokens",
+  "modelCalls"
+];
+const AGENT_COLLABORATION_TITLE_MAX_LENGTH = 200;
+const AGENT_COLLABORATION_OBJECTIVE_MAX_LENGTH = 4e3;
+const AGENT_COLLABORATION_PROGRESS_MAX_LENGTH = 2e3;
+const AGENT_COLLABORATION_RESULT_REFERENCES_MAX_LENGTH = 100;
+const AGENT_COLLABORATION_GRAPH_LIMITS = Object.freeze({
+  maxNodes: 100,
+  maxDepth: 16,
+  maxChildrenPerNode: 100,
+  maxActiveNodes: 100
+});
+export {
+  AGENT_COLLABORATION_CONTROL_ACTIONS,
+  AGENT_COLLABORATION_GRAPH_LIMITS,
+  AGENT_COLLABORATION_OBJECTIVE_MAX_LENGTH,
+  AGENT_COLLABORATION_OUTCOMES,
+  AGENT_COLLABORATION_PROGRESS_MAX_LENGTH,
+  AGENT_COLLABORATION_RESULT_REFERENCES_MAX_LENGTH,
+  AGENT_COLLABORATION_ROLES,
+  AGENT_COLLABORATION_STATUSES,
+  AGENT_COLLABORATION_STOP_REASONS,
+  AGENT_COLLABORATION_TITLE_MAX_LENGTH,
+  AGENT_COLLABORATION_USAGE_FIELDS
+};

package/dist/configuration/index.d.ts

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

package/dist/configuration/index.js

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

package/dist/configuration/parsers.d.ts

@@ -0,0 +1,9 @@
+import { type AgentProtocolParseResult } from '../foundation/index.js';
+import type { AgentConfigurationCatalog, AgentConfigurationSelectionInput } from './types.js';
+export declare function parseAgentConfigurationCatalog(input: unknown): AgentConfigurationCatalog;
+export declare function safeParseAgentConfigurationCatalog(input: unknown): AgentProtocolParseResult<AgentConfigurationCatalog>;
+export declare function parseAgentConfigurationSelectionInput(input: unknown): AgentConfigurationSelectionInput;
+export declare function safeParseAgentConfigurationSelectionInput(input: unknown): AgentProtocolParseResult<AgentConfigurationSelectionInput>;
+export declare function safeParseAgentConfigurationSelectionFor(catalogInput: unknown, selectionInput: unknown): AgentProtocolParseResult<AgentConfigurationSelectionInput>;
+export declare function parseAgentConfigurationSelectionFor(catalogInput: unknown, selectionInput: unknown): AgentConfigurationSelectionInput;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/configuration/parsers.js

@@ -0,0 +1,98 @@
+import {
+  AgentProtocolValidationError
+} from "../foundation/index.js";
+import { parseWithSchema, safeParseWithSchema } from "../internal/parsers.js";
+import {
+  AgentConfigurationCatalogSchema,
+  AgentConfigurationSelectionInputSchema
+} from "../zod/configuration.js";
+function parseAgentConfigurationCatalog(input) {
+  return parseWithSchema(AgentConfigurationCatalogSchema, input);
+}
+function safeParseAgentConfigurationCatalog(input) {
+  return safeParseWithSchema(AgentConfigurationCatalogSchema, input);
+}
+function parseAgentConfigurationSelectionInput(input) {
+  return parseWithSchema(AgentConfigurationSelectionInputSchema, input);
+}
+function safeParseAgentConfigurationSelectionInput(input) {
+  return safeParseWithSchema(AgentConfigurationSelectionInputSchema, input);
+}
+function issue(path, message) {
+  return { code: "custom", path, message };
+}
+function safeParseAgentConfigurationSelectionFor(catalogInput, selectionInput) {
+  const catalog = safeParseAgentConfigurationCatalog(catalogInput);
+  if (!catalog.success) return catalog;
+  const selection = safeParseAgentConfigurationSelectionInput(selectionInput);
+  if (!selection.success) return selection;
+  const issues = [];
+  if (selection.data.expectedCatalogRevision !== catalog.data.revision) {
+    issues.push(issue(
+      ["expectedCatalogRevision"],
+      "Configuration selection must target the current catalog revision."
+    ));
+  }
+  const field = catalog.data.fields.find(
+    (candidate) => candidate.key === selection.data.key
+  );
+  if (field === void 0) {
+    issues.push(issue(
+      ["key"],
+      "Configuration selection must target an offered field."
+    ));
+    return { success: false, issues };
+  }
+  if (selection.data.expectedFieldRevision !== field.revision) {
+    issues.push(issue(
+      ["expectedFieldRevision"],
+      "Configuration selection must target the current field revision."
+    ));
+  }
+  if (!field.mutable) {
+    issues.push(issue(["key"], "Configuration field is not mutable."));
+  }
+  if (selection.data.value.fieldKind !== field.fieldKind) {
+    issues.push(issue(
+      ["value", "fieldKind"],
+      "Configuration value kind must match the selected field."
+    ));
+    return { success: false, issues };
+  }
+  const value = selection.data.value;
+  if (field.fieldKind === "single_select" && value.fieldKind === "single_select" && !field.options.some((option) => option.optionId === value.optionId)) {
+    issues.push(issue(
+      ["value", "optionId"],
+      "Configuration selection must reference an offered option."
+    ));
+  }
+  if (field.fieldKind === "bounded_integer" && value.fieldKind === "bounded_integer" && (value.value < field.minimum || value.value > field.maximum)) {
+    issues.push(issue(
+      ["value", "value"],
+      "Configuration integer is outside the field bounds."
+    ));
+  }
+  if (field.fieldKind === "bounded_text" && value.fieldKind === "bounded_text" && value.value.length > field.maxLength) {
+    issues.push(issue(
+      ["value", "value"],
+      "Configuration text exceeds the field maximum length."
+    ));
+  }
+  return issues.length === 0 ? selection : { success: false, issues };
+}
+function parseAgentConfigurationSelectionFor(catalogInput, selectionInput) {
+  const parsed = safeParseAgentConfigurationSelectionFor(
+    catalogInput,
+    selectionInput
+  );
+  if (parsed.success) return parsed.data;
+  throw new AgentProtocolValidationError(parsed.issues);
+}
+export {
+  parseAgentConfigurationCatalog,
+  parseAgentConfigurationSelectionFor,
+  parseAgentConfigurationSelectionInput,
+  safeParseAgentConfigurationCatalog,
+  safeParseAgentConfigurationSelectionFor,
+  safeParseAgentConfigurationSelectionInput
+};

package/dist/configuration/types.d.ts

@@ -0,0 +1,72 @@
+export declare const AGENT_CONFIGURATION_FIELD_KINDS: readonly ["boolean", "single_select", "bounded_integer", "bounded_text"];
+export declare const AGENT_CONFIGURATION_SCOPES: readonly ["session", "provider_instance"];
+export declare const AGENT_CONFIGURATION_APPLICATION_TIMINGS: readonly ["immediate", "next_session", "provider_restart"];
+export declare const AGENT_CONFIGURATION_FIELDS_MAX_LENGTH = 100;
+export declare const AGENT_CONFIGURATION_OPTIONS_MAX_LENGTH = 100;
+export declare const AGENT_CONFIGURATION_LABEL_MAX_LENGTH = 200;
+export declare const AGENT_CONFIGURATION_DESCRIPTION_MAX_LENGTH = 2000;
+export declare const AGENT_CONFIGURATION_TEXT_VALUE_MAX_LENGTH = 4000;
+export type AgentConfigurationFieldKind = (typeof AGENT_CONFIGURATION_FIELD_KINDS)[number];
+export type AgentConfigurationScope = (typeof AGENT_CONFIGURATION_SCOPES)[number];
+export type AgentConfigurationApplicationTiming = (typeof AGENT_CONFIGURATION_APPLICATION_TIMINGS)[number];
+export interface AgentConfigurationSelectOption {
+    readonly optionId: string;
+    readonly label: string;
+    readonly description?: string;
+}
+interface AgentConfigurationFieldBase {
+    readonly key: string;
+    readonly revision: number;
+    readonly label: string;
+    readonly description?: string;
+    readonly scope: AgentConfigurationScope;
+    readonly applicationTiming: AgentConfigurationApplicationTiming;
+    readonly mutable: boolean;
+}
+export interface AgentBooleanConfigurationField extends AgentConfigurationFieldBase {
+    readonly fieldKind: 'boolean';
+    readonly currentValue: boolean;
+}
+export interface AgentSingleSelectConfigurationField extends AgentConfigurationFieldBase {
+    readonly fieldKind: 'single_select';
+    readonly currentValue: string;
+    readonly options: readonly AgentConfigurationSelectOption[];
+}
+export interface AgentBoundedIntegerConfigurationField extends AgentConfigurationFieldBase {
+    readonly fieldKind: 'bounded_integer';
+    readonly currentValue: number;
+    readonly minimum: number;
+    readonly maximum: number;
+}
+export interface AgentBoundedTextConfigurationField extends AgentConfigurationFieldBase {
+    readonly fieldKind: 'bounded_text';
+    readonly currentValue: string;
+    readonly maxLength: number;
+    readonly multiline: boolean;
+}
+export type AgentConfigurationField = AgentBooleanConfigurationField | AgentSingleSelectConfigurationField | AgentBoundedIntegerConfigurationField | AgentBoundedTextConfigurationField;
+export interface AgentConfigurationCatalog {
+    readonly revision: number;
+    readonly fields: readonly AgentConfigurationField[];
+}
+export type AgentConfigurationValue = Readonly<{
+    fieldKind: 'boolean';
+    value: boolean;
+}> | Readonly<{
+    fieldKind: 'single_select';
+    optionId: string;
+}> | Readonly<{
+    fieldKind: 'bounded_integer';
+    value: number;
+}> | Readonly<{
+    fieldKind: 'bounded_text';
+    value: string;
+}>;
+export interface AgentConfigurationSelectionInput {
+    readonly key: string;
+    readonly expectedCatalogRevision: number;
+    readonly expectedFieldRevision: number;
+    readonly value: AgentConfigurationValue;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/configuration/types.js

@@ -0,0 +1,27 @@
+const AGENT_CONFIGURATION_FIELD_KINDS = [
+  "boolean",
+  "single_select",
+  "bounded_integer",
+  "bounded_text"
+];
+const AGENT_CONFIGURATION_SCOPES = ["session", "provider_instance"];
+const AGENT_CONFIGURATION_APPLICATION_TIMINGS = [
+  "immediate",
+  "next_session",
+  "provider_restart"
+];
+const AGENT_CONFIGURATION_FIELDS_MAX_LENGTH = 100;
+const AGENT_CONFIGURATION_OPTIONS_MAX_LENGTH = 100;
+const AGENT_CONFIGURATION_LABEL_MAX_LENGTH = 200;
+const AGENT_CONFIGURATION_DESCRIPTION_MAX_LENGTH = 2e3;
+const AGENT_CONFIGURATION_TEXT_VALUE_MAX_LENGTH = 4e3;
+export {
+  AGENT_CONFIGURATION_APPLICATION_TIMINGS,
+  AGENT_CONFIGURATION_DESCRIPTION_MAX_LENGTH,
+  AGENT_CONFIGURATION_FIELDS_MAX_LENGTH,
+  AGENT_CONFIGURATION_FIELD_KINDS,
+  AGENT_CONFIGURATION_LABEL_MAX_LENGTH,
+  AGENT_CONFIGURATION_OPTIONS_MAX_LENGTH,
+  AGENT_CONFIGURATION_SCOPES,
+  AGENT_CONFIGURATION_TEXT_VALUE_MAX_LENGTH
+};