@agen-ai/agent-protocol 0.2.5 → 0.3.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, account-quota observations, collaboration lifecycles, generated resources, portable
+observations, effective harness content and package catalogs, environment observations, account-quota observations, collaboration lifecycles, generated resources, portable
 artifact descriptors, and provider-observed events. The package does not define a transport or
 execution runtime.
 
@@ -32,7 +32,7 @@ carry no fabricated windows or hints.
 - `@agen-ai/agent-protocol` exports the complete plain API.
 - `/sessions`, `/turns`, `/requests`, `/events`, `/capabilities`, `/artifacts`, `/operations`,
   `/configuration`, `/managed-content`, `/integrations`, `/collaboration`, `/resources`, and
-  `/account-quota` are focused plain entrypoints.
+  `/account-quota`, `/effective-content`, `/commands`, `/extensions`, and `/environment` are focused plain entrypoints.
 - `/zod` is the only entrypoint that exposes Zod schemas.
 - `/json-schema` exposes deterministic draft 2020-12 schema artifacts.
 
@@ -50,7 +50,7 @@ import {
 } from '@agen-ai/agent-protocol';
 
 const event: AgentEvent = parseAgentEvent({
-  protocolVersion: 8,
+  protocolVersion: 9,
   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: 8`; TypeScript API names remain unsuffixed. Unknown
+Serialized values carry `protocolVersion: 9`; 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.
 
-V8 approval requests correlate to one live item or exact proposed-plan artifact and provide a
+V9 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
@@ -112,16 +112,47 @@ published JSON Schemas enforce the same rule. Plan-step and progress identifiers
 messages, and error context must contain non-whitespace content without surrounding whitespace so
 validated protocol output remains canonical across transports and consumers.
 
+## Effective environment values
+
+`managedContent` describes content a caller manages and distributes. `effectiveContent` describes
+what the selected harness reports for a workspace or session. Effective descriptors keep registration,
+enablement, user invocation, and model callability separate; unknown facts are explicit. Optional
+`agentDefinition` observations preserve primary/subagent mode and hidden state independently of
+those execution facts. They apply only to agent-definition entries and never grant a spawn action. A package
+belongs in `extensions` and references its contributed content, commands, and integrations. MCP
+servers and Apps/connectors share the discriminated `integrations` catalog.
+
+`AgentEnvironmentSnapshot` composes these bounded domains without copying their inventories. Each
+domain distinguishes unsupported, not initialized, unavailable, partial, and complete observations.
+Catalog revisions describe semantic content; observation timestamps never grant mutation authority.
+The caller supplies an opaque environment identity. Hosts must scope that identity to their own
+account, workspace, configuration, session, and authorization state.
+
+A `content_reference` input part carries the environment and content catalog revisions plus the
+selected content identity and revision. It is neither embedded skill text nor a slash command.
+Providers advertise reference and argument support explicitly. The parser allows at most 16
+references, bounds each argument at 4 KiB of UTF-8, rejects duplicate identities, and includes the
+reference bytes in the existing input envelope. Product admission must still validate current
+catalog identity, visibility, and execution authority before provider delegation.
+
+Supported reference capabilities require `textFormats.prompt` and `textFormats.arguments`:
+`unrestricted` adds no text restriction; `single_line` excludes Unicode control (Cc), format (Cf),
+line separator (Zl), and paragraph separator (Zp) characters; `literal_single_line` also excludes
+`$`, `@`, backticks, and a slash after leading whitespace. These constraints apply only when the
+input contains a content reference and do not replace the ordinary input envelope or other
+admission checks. `findAgentContentReferenceTextIssue` reports the affected field and format
+without returning submitted text. `meetAgentContentReferenceTextFormat` retains the stricter
+constraint when composing capabilities. Runtime and product admission must enforce both fields
+before delegation; a composer can use the same pure functions to preserve and explain an invalid draft.
+
 ## Versioning and release
 
-The package is at `0.2.5` 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 account-quota namespace starts at schema version 1 and is additive to
-Protocol V8. The required `MaterializedAgentProviderInstance.accountQuota` runtime field is a
-source-level implementer change in the coordinated `0.2.5` release; all three SDK packages must
-be upgraded together. See the public repository migration guide for the explicit unsupported port.
+Agent Protocol V9 defines the coordinated SDK `0.3.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.
 
 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/contentReferenceText.d.ts

@@ -0,0 +1,13 @@
+import type { AgentContentReferenceTextFormat, AgentContentReferenceTextFormats } from './types.js';
+export interface AgentContentReferenceTextIssue {
+    readonly target: 'prompt' | 'arguments';
+    readonly format: Exclude<AgentContentReferenceTextFormat, 'unrestricted'>;
+}
+export declare function isAgentContentReferenceTextAllowed(text: string, format: AgentContentReferenceTextFormat): boolean;
+export declare function meetAgentContentReferenceTextFormat(left: AgentContentReferenceTextFormat, right: AgentContentReferenceTextFormat): AgentContentReferenceTextFormat;
+export declare function findAgentContentReferenceTextIssue(input: {
+    readonly prompt: string;
+    readonly arguments: readonly string[];
+    readonly textFormats: AgentContentReferenceTextFormats;
+}): AgentContentReferenceTextIssue | null;
+//# sourceMappingURL=contentReferenceText.d.ts.map

package/dist/capabilities/contentReferenceText.js

@@ -0,0 +1,25 @@
+function isAgentContentReferenceTextAllowed(text, format) {
+  if (format === "unrestricted") return true;
+  if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(text)) return false;
+  return format !== "literal_single_line" || !/[$@`]/u.test(text) && !text.trimStart().startsWith("/");
+}
+function meetAgentContentReferenceTextFormat(left, right) {
+  if (left === "literal_single_line" || right === "literal_single_line") return "literal_single_line";
+  if (left === "single_line" || right === "single_line") return "single_line";
+  return "unrestricted";
+}
+function findAgentContentReferenceTextIssue(input) {
+  const { prompt, arguments: argumentFormat } = input.textFormats;
+  if (prompt !== "unrestricted" && !isAgentContentReferenceTextAllowed(input.prompt, prompt)) {
+    return { target: "prompt", format: prompt };
+  }
+  if (argumentFormat !== "unrestricted" && input.arguments.some((value) => !isAgentContentReferenceTextAllowed(value, argumentFormat))) {
+    return { target: "arguments", format: argumentFormat };
+  }
+  return null;
+}
+export {
+  findAgentContentReferenceTextIssue,
+  isAgentContentReferenceTextAllowed,
+  meetAgentContentReferenceTextFormat
+};

package/dist/capabilities/index.d.ts

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

package/dist/capabilities/index.js

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

package/dist/capabilities/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgentEnvironmentCapability } from '../environment/types.js';
 import type { AgentArtifactKind } from '../artifacts/index.js';
 import type { AgentCollaborationControlAction, AgentCollaborationRole } from '../collaboration/index.js';
 import type { AgentConfigurationFieldKind } from '../configuration/index.js';
@@ -121,9 +122,25 @@ export type AgentImageInputCapability = Readonly<{
     maxPixelsPerImage: number;
     supportsImageOnly: boolean;
 }>;
+export declare const AGENT_CONTENT_REFERENCE_TEXT_FORMATS: readonly ["unrestricted", "single_line", "literal_single_line"];
+/** Single lines exclude Unicode Cc, Cf, Zl and Zp; literal lines also exclude $, @, backtick and a leading slash. */
+export type AgentContentReferenceTextFormat = typeof AGENT_CONTENT_REFERENCE_TEXT_FORMATS[number];
+export interface AgentContentReferenceTextFormats {
+    readonly prompt: AgentContentReferenceTextFormat;
+    readonly arguments: AgentContentReferenceTextFormat;
+}
+export type AgentContentReferenceInputCapability = Readonly<{
+    kind: 'unsupported';
+}> | Readonly<{
+    kind: 'supported';
+    maxReferences: number;
+    arguments: boolean;
+    textFormats: AgentContentReferenceTextFormats;
+}>;
 export interface AgentOperationInputCapability {
     readonly text: true;
     readonly images: AgentImageInputCapability;
+    readonly contentReferences: AgentContentReferenceInputCapability;
 }
 export type AgentTurnSteeringCapability = Readonly<{
     kind: 'unsupported';
@@ -132,7 +149,7 @@ export type AgentTurnSteeringCapability = Readonly<{
     input: AgentOperationInputCapability;
 }>;
 export interface AgentCapabilities {
-    readonly protocolVersion: 8;
+    readonly protocolVersion: 9;
     readonly providerKey: AgentProviderKey;
     readonly sessions: Readonly<{
         create: true;
@@ -163,6 +180,7 @@ export interface AgentCapabilities {
     readonly operations: AgentOperationsCapability;
     readonly managedContent: AgentManagedContentCapability;
     readonly integrations: AgentIntegrationsCapability;
+    readonly environment: AgentEnvironmentCapability;
     readonly collaboration: AgentCollaborationCapability;
     readonly generatedResources: AgentGeneratedResourcesCapability;
     readonly authentication: AgentAuthenticationCapability;

package/dist/capabilities/types.js

@@ -8,7 +8,13 @@ const AGENT_AUTHENTICATION_FLOWS = [
   "browser",
   "terminal"
 ];
+const AGENT_CONTENT_REFERENCE_TEXT_FORMATS = [
+  "unrestricted",
+  "single_line",
+  "literal_single_line"
+];
 export {
   AGENT_AUTHENTICATION_FLOWS,
+  AGENT_CONTENT_REFERENCE_TEXT_FORMATS,
   AGENT_FILE_CHANGE_MODES
 };

package/dist/commands/index.d.ts

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

package/dist/commands/index.js

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

package/dist/commands/parsers.d.ts

@@ -0,0 +1,7 @@
+import type { AgentProtocolParseResult } from '../foundation/index.js';
+import type { AgentCommandCatalog, AgentCommandDescriptor } from './types.js';
+export declare function parseAgentCommandDescriptor(input: unknown): AgentCommandDescriptor;
+export declare function safeParseAgentCommandDescriptor(input: unknown): AgentProtocolParseResult<AgentCommandDescriptor>;
+export declare function parseAgentCommandCatalog(input: unknown): AgentCommandCatalog;
+export declare function safeParseAgentCommandCatalog(input: unknown): AgentProtocolParseResult<AgentCommandCatalog>;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/commands/parsers.js

@@ -0,0 +1,23 @@
+import { parseWithSchema, safeParseWithSchema } from "../internal/parsers.js";
+import {
+  AgentCommandCatalogSchema,
+  AgentCommandDescriptorSchema
+} from "../zod/commands.js";
+function parseAgentCommandDescriptor(input) {
+  return parseWithSchema(AgentCommandDescriptorSchema, input);
+}
+function safeParseAgentCommandDescriptor(input) {
+  return safeParseWithSchema(AgentCommandDescriptorSchema, input);
+}
+function parseAgentCommandCatalog(input) {
+  return parseWithSchema(AgentCommandCatalogSchema, input);
+}
+function safeParseAgentCommandCatalog(input) {
+  return safeParseWithSchema(AgentCommandCatalogSchema, input);
+}
+export {
+  parseAgentCommandCatalog,
+  parseAgentCommandDescriptor,
+  safeParseAgentCommandCatalog,
+  safeParseAgentCommandDescriptor
+};

package/dist/commands/types.d.ts

@@ -0,0 +1,26 @@
+import type { AgentCommandId, AgentIsoDateTime, AgentOperationId } from '../foundation/index.js';
+import type { AgentAvailabilityFact, AgentEnvironmentSource } from '../environment/facts.js';
+export declare const AGENT_COMMAND_NAME_MAX_LENGTH = 200;
+export declare const AGENT_COMMAND_SUMMARY_MAX_LENGTH = 2000;
+export declare const AGENT_COMMAND_CATALOG_MAX_LENGTH = 1024;
+export declare const AGENT_COMMAND_CATALOG_BYTES_LIMIT: number;
+export interface AgentCommandOperationReference {
+    readonly operationId: AgentOperationId;
+    readonly revision: number;
+    readonly catalogRevision: number;
+}
+export interface AgentCommandDescriptor {
+    readonly commandId: AgentCommandId;
+    readonly revision: number;
+    readonly name: string;
+    readonly summary?: string;
+    readonly source: AgentEnvironmentSource;
+    readonly availability: AgentAvailabilityFact;
+    readonly operation?: AgentCommandOperationReference;
+}
+export interface AgentCommandCatalog {
+    readonly revision: number;
+    readonly observedAt: AgentIsoDateTime;
+    readonly commands: readonly AgentCommandDescriptor[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/commands/types.js

@@ -0,0 +1,10 @@
+const AGENT_COMMAND_NAME_MAX_LENGTH = 200;
+const AGENT_COMMAND_SUMMARY_MAX_LENGTH = 2e3;
+const AGENT_COMMAND_CATALOG_MAX_LENGTH = 1024;
+const AGENT_COMMAND_CATALOG_BYTES_LIMIT = 512 * 1024;
+export {
+  AGENT_COMMAND_CATALOG_BYTES_LIMIT,
+  AGENT_COMMAND_CATALOG_MAX_LENGTH,
+  AGENT_COMMAND_NAME_MAX_LENGTH,
+  AGENT_COMMAND_SUMMARY_MAX_LENGTH
+};

package/dist/effectiveContent/index.d.ts

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

package/dist/effectiveContent/index.js

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

package/dist/effectiveContent/parsers.d.ts

@@ -0,0 +1,7 @@
+import type { AgentProtocolParseResult } from '../foundation/index.js';
+import type { AgentEffectiveContentCatalog, AgentEffectiveContentDescriptor } from './types.js';
+export declare function parseAgentEffectiveContentDescriptor(input: unknown): AgentEffectiveContentDescriptor;
+export declare function safeParseAgentEffectiveContentDescriptor(input: unknown): AgentProtocolParseResult<AgentEffectiveContentDescriptor>;
+export declare function parseAgentEffectiveContentCatalog(input: unknown): AgentEffectiveContentCatalog;
+export declare function safeParseAgentEffectiveContentCatalog(input: unknown): AgentProtocolParseResult<AgentEffectiveContentCatalog>;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/effectiveContent/parsers.js

@@ -0,0 +1,23 @@
+import { parseWithSchema, safeParseWithSchema } from "../internal/parsers.js";
+import {
+  AgentEffectiveContentCatalogSchema,
+  AgentEffectiveContentDescriptorSchema
+} from "../zod/effectiveContent.js";
+function parseAgentEffectiveContentDescriptor(input) {
+  return parseWithSchema(AgentEffectiveContentDescriptorSchema, input);
+}
+function safeParseAgentEffectiveContentDescriptor(input) {
+  return safeParseWithSchema(AgentEffectiveContentDescriptorSchema, input);
+}
+function parseAgentEffectiveContentCatalog(input) {
+  return parseWithSchema(AgentEffectiveContentCatalogSchema, input);
+}
+function safeParseAgentEffectiveContentCatalog(input) {
+  return safeParseWithSchema(AgentEffectiveContentCatalogSchema, input);
+}
+export {
+  parseAgentEffectiveContentCatalog,
+  parseAgentEffectiveContentDescriptor,
+  safeParseAgentEffectiveContentCatalog,
+  safeParseAgentEffectiveContentDescriptor
+};

package/dist/effectiveContent/types.d.ts

@@ -0,0 +1,35 @@
+import type { AgentEffectiveContentId, AgentIsoDateTime } from '../foundation/index.js';
+import type { AgentAvailabilityFact, AgentEnvironmentSource, AgentInvocationPosture, AgentQualifiedExtensionReference } from '../environment/facts.js';
+export declare const AGENT_EFFECTIVE_CONTENT_KINDS: readonly ["skill", "rule", "prompt", "agent_definition"];
+export declare const AGENT_EFFECTIVE_CONTENT_NAME_MAX_LENGTH = 200;
+export declare const AGENT_EFFECTIVE_CONTENT_SUMMARY_MAX_LENGTH = 2000;
+export declare const AGENT_EFFECTIVE_CONTENT_CATALOG_MAX_LENGTH = 1024;
+export declare const AGENT_EFFECTIVE_CONTENT_CATALOG_BYTES_LIMIT: number;
+export type AgentEffectiveContentKind = (typeof AGENT_EFFECTIVE_CONTENT_KINDS)[number];
+export declare const AGENT_DEFINITION_MODES: readonly ["primary", "subagent", "all", "unknown"];
+export type AgentDefinitionMode = (typeof AGENT_DEFINITION_MODES)[number];
+/** Definition metadata does not grant selection or running-agent authority. */
+export interface AgentDefinitionObservation {
+    readonly mode: AgentDefinitionMode;
+    readonly hidden: AgentAvailabilityFact;
+}
+export interface AgentEffectiveContentDescriptor {
+    readonly contentId: AgentEffectiveContentId;
+    readonly revision: number;
+    readonly kind: AgentEffectiveContentKind;
+    readonly name: string;
+    readonly summary?: string;
+    readonly source: AgentEnvironmentSource;
+    readonly registration: AgentAvailabilityFact;
+    readonly enablement: AgentAvailabilityFact;
+    readonly invocation: AgentInvocationPosture;
+    readonly modelCallability: AgentAvailabilityFact;
+    readonly extension?: AgentQualifiedExtensionReference;
+    readonly agentDefinition?: AgentDefinitionObservation;
+}
+export interface AgentEffectiveContentCatalog {
+    readonly revision: number;
+    readonly observedAt: AgentIsoDateTime;
+    readonly content: readonly AgentEffectiveContentDescriptor[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/effectiveContent/types.js

@@ -0,0 +1,19 @@
+const AGENT_EFFECTIVE_CONTENT_KINDS = [
+  "skill",
+  "rule",
+  "prompt",
+  "agent_definition"
+];
+const AGENT_EFFECTIVE_CONTENT_NAME_MAX_LENGTH = 200;
+const AGENT_EFFECTIVE_CONTENT_SUMMARY_MAX_LENGTH = 2e3;
+const AGENT_EFFECTIVE_CONTENT_CATALOG_MAX_LENGTH = 1024;
+const AGENT_EFFECTIVE_CONTENT_CATALOG_BYTES_LIMIT = 512 * 1024;
+const AGENT_DEFINITION_MODES = ["primary", "subagent", "all", "unknown"];
+export {
+  AGENT_DEFINITION_MODES,
+  AGENT_EFFECTIVE_CONTENT_CATALOG_BYTES_LIMIT,
+  AGENT_EFFECTIVE_CONTENT_CATALOG_MAX_LENGTH,
+  AGENT_EFFECTIVE_CONTENT_KINDS,
+  AGENT_EFFECTIVE_CONTENT_NAME_MAX_LENGTH,
+  AGENT_EFFECTIVE_CONTENT_SUMMARY_MAX_LENGTH
+};

package/dist/environment/facts.d.ts

@@ -0,0 +1,28 @@
+import type { AgentExtensionId } from '../foundation/index.js';
+export declare const AGENT_ENVIRONMENT_SCOPES: readonly ["workspace", "project", "user", "system", "remote", "unknown"];
+export declare const AGENT_ENVIRONMENT_ORIGINS: readonly ["managed", "workspace", "user", "bundled", "plugin", "remote", "unknown"];
+export declare const AGENT_INVOCATION_POSTURES: readonly ["user_and_model", "user_only", "model_only", "unavailable", "unknown"];
+export declare const AGENT_ENVIRONMENT_REASONS: readonly ["missing_metadata", "native_ambiguity", "permission_denied", "authentication_required", "source_changed", "capacity_exceeded", "transient_failure"];
+export type AgentEnvironmentScope = (typeof AGENT_ENVIRONMENT_SCOPES)[number];
+export type AgentEnvironmentOrigin = (typeof AGENT_ENVIRONMENT_ORIGINS)[number];
+export type AgentInvocationPosture = (typeof AGENT_INVOCATION_POSTURES)[number];
+export type AgentEnvironmentReason = (typeof AGENT_ENVIRONMENT_REASONS)[number];
+/** A source's location scope and provenance are separate observations. */
+export interface AgentEnvironmentSource {
+    readonly scope: AgentEnvironmentScope;
+    readonly origin: AgentEnvironmentOrigin;
+}
+/** A native fact is explicit when the provider cannot establish a boolean value. */
+export type AgentAvailabilityFact = Readonly<{
+    readonly kind: 'known';
+    readonly value: boolean;
+}> | Readonly<{
+    readonly kind: 'unknown';
+}>;
+/** A relationship to an observed extension is valid only at an exact package generation. */
+export interface AgentQualifiedExtensionReference {
+    readonly extensionId: AgentExtensionId;
+    readonly revision: number;
+    readonly catalogRevision: number;
+}
+//# sourceMappingURL=facts.d.ts.map

package/dist/environment/facts.js

@@ -0,0 +1,39 @@
+const AGENT_ENVIRONMENT_SCOPES = [
+  "workspace",
+  "project",
+  "user",
+  "system",
+  "remote",
+  "unknown"
+];
+const AGENT_ENVIRONMENT_ORIGINS = [
+  "managed",
+  "workspace",
+  "user",
+  "bundled",
+  "plugin",
+  "remote",
+  "unknown"
+];
+const AGENT_INVOCATION_POSTURES = [
+  "user_and_model",
+  "user_only",
+  "model_only",
+  "unavailable",
+  "unknown"
+];
+const AGENT_ENVIRONMENT_REASONS = [
+  "missing_metadata",
+  "native_ambiguity",
+  "permission_denied",
+  "authentication_required",
+  "source_changed",
+  "capacity_exceeded",
+  "transient_failure"
+];
+export {
+  AGENT_ENVIRONMENT_ORIGINS,
+  AGENT_ENVIRONMENT_REASONS,
+  AGENT_ENVIRONMENT_SCOPES,
+  AGENT_INVOCATION_POSTURES
+};

package/dist/environment/index.d.ts

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

package/dist/environment/index.js

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

package/dist/environment/parsers.d.ts

@@ -0,0 +1,17 @@
+import type { AgentProtocolParseResult } from '../foundation/index.js';
+import type { AgentEnvironmentCapability, AgentEnvironmentContentResult, AgentEnvironmentCommandsResult, AgentEnvironmentExtensionsResult, AgentEnvironmentIntegrationsResult, AgentEnvironmentInvalidation, AgentEnvironmentSnapshot } from './types.js';
+export declare function parseAgentEnvironmentCapability(input: unknown): AgentEnvironmentCapability;
+export declare function safeParseAgentEnvironmentCapability(input: unknown): AgentProtocolParseResult<AgentEnvironmentCapability>;
+export declare function parseAgentEnvironmentContentResult(input: unknown): AgentEnvironmentContentResult;
+export declare function safeParseAgentEnvironmentContentResult(input: unknown): AgentProtocolParseResult<AgentEnvironmentContentResult>;
+export declare function parseAgentEnvironmentCommandsResult(input: unknown): AgentEnvironmentCommandsResult;
+export declare function safeParseAgentEnvironmentCommandsResult(input: unknown): AgentProtocolParseResult<AgentEnvironmentCommandsResult>;
+export declare function parseAgentEnvironmentExtensionsResult(input: unknown): AgentEnvironmentExtensionsResult;
+export declare function safeParseAgentEnvironmentExtensionsResult(input: unknown): AgentProtocolParseResult<AgentEnvironmentExtensionsResult>;
+export declare function parseAgentEnvironmentIntegrationsResult(input: unknown): AgentEnvironmentIntegrationsResult;
+export declare function safeParseAgentEnvironmentIntegrationsResult(input: unknown): AgentProtocolParseResult<AgentEnvironmentIntegrationsResult>;
+export declare function parseAgentEnvironmentInvalidation(input: unknown): AgentEnvironmentInvalidation;
+export declare function safeParseAgentEnvironmentInvalidation(input: unknown): AgentProtocolParseResult<AgentEnvironmentInvalidation>;
+export declare function parseAgentEnvironmentSnapshot(input: unknown): AgentEnvironmentSnapshot;
+export declare function safeParseAgentEnvironmentSnapshot(input: unknown): AgentProtocolParseResult<AgentEnvironmentSnapshot>;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/environment/parsers.js

@@ -0,0 +1,68 @@
+import { parseWithSchema, safeParseWithSchema } from "../internal/parsers.js";
+import {
+  AgentEnvironmentCapabilitySchema,
+  AgentEnvironmentContentResultSchema,
+  AgentEnvironmentCommandsResultSchema,
+  AgentEnvironmentExtensionsResultSchema,
+  AgentEnvironmentIntegrationsResultSchema,
+  AgentEnvironmentInvalidationSchema,
+  AgentEnvironmentSnapshotSchema
+} from "../zod/environment.js";
+function parseAgentEnvironmentCapability(input) {
+  return parseWithSchema(AgentEnvironmentCapabilitySchema, input);
+}
+function safeParseAgentEnvironmentCapability(input) {
+  return safeParseWithSchema(AgentEnvironmentCapabilitySchema, input);
+}
+function parseAgentEnvironmentContentResult(input) {
+  return parseWithSchema(AgentEnvironmentContentResultSchema, input);
+}
+function safeParseAgentEnvironmentContentResult(input) {
+  return safeParseWithSchema(AgentEnvironmentContentResultSchema, input);
+}
+function parseAgentEnvironmentCommandsResult(input) {
+  return parseWithSchema(AgentEnvironmentCommandsResultSchema, input);
+}
+function safeParseAgentEnvironmentCommandsResult(input) {
+  return safeParseWithSchema(AgentEnvironmentCommandsResultSchema, input);
+}
+function parseAgentEnvironmentExtensionsResult(input) {
+  return parseWithSchema(AgentEnvironmentExtensionsResultSchema, input);
+}
+function safeParseAgentEnvironmentExtensionsResult(input) {
+  return safeParseWithSchema(AgentEnvironmentExtensionsResultSchema, input);
+}
+function parseAgentEnvironmentIntegrationsResult(input) {
+  return parseWithSchema(AgentEnvironmentIntegrationsResultSchema, input);
+}
+function safeParseAgentEnvironmentIntegrationsResult(input) {
+  return safeParseWithSchema(AgentEnvironmentIntegrationsResultSchema, input);
+}
+function parseAgentEnvironmentInvalidation(input) {
+  return parseWithSchema(AgentEnvironmentInvalidationSchema, input);
+}
+function safeParseAgentEnvironmentInvalidation(input) {
+  return safeParseWithSchema(AgentEnvironmentInvalidationSchema, input);
+}
+function parseAgentEnvironmentSnapshot(input) {
+  return parseWithSchema(AgentEnvironmentSnapshotSchema, input);
+}
+function safeParseAgentEnvironmentSnapshot(input) {
+  return safeParseWithSchema(AgentEnvironmentSnapshotSchema, input);
+}
+export {
+  parseAgentEnvironmentCapability,
+  parseAgentEnvironmentCommandsResult,
+  parseAgentEnvironmentContentResult,
+  parseAgentEnvironmentExtensionsResult,
+  parseAgentEnvironmentIntegrationsResult,
+  parseAgentEnvironmentInvalidation,
+  parseAgentEnvironmentSnapshot,
+  safeParseAgentEnvironmentCapability,
+  safeParseAgentEnvironmentCommandsResult,
+  safeParseAgentEnvironmentContentResult,
+  safeParseAgentEnvironmentExtensionsResult,
+  safeParseAgentEnvironmentIntegrationsResult,
+  safeParseAgentEnvironmentInvalidation,
+  safeParseAgentEnvironmentSnapshot
+};

package/dist/environment/types.d.ts

@@ -0,0 +1,61 @@
+import type { AgentCommandCatalog } from '../commands/index.js';
+import type { AgentEffectiveContentCatalog } from '../effectiveContent/index.js';
+import type { AgentExtensionCatalog } from '../extensions/index.js';
+import type { AgentIntegrationCatalog } from '../integrations/index.js';
+import type { AgentEnvironmentId } from '../foundation/index.js';
+import type { AgentEnvironmentReason } from './facts.js';
+export declare const AGENT_ENVIRONMENT_SCHEMA_VERSION: 1;
+export declare const AGENT_ENVIRONMENT_DOMAINS: readonly ["content", "commands", "extensions", "integrations"];
+export declare const AGENT_ENVIRONMENT_EVIDENCE_EXTENTS: readonly ["workspace_discovery", "session"];
+export declare const AGENT_ENVIRONMENT_COMPLETENESSES: readonly ["complete", "partial"];
+export declare const AGENT_ENVIRONMENT_DOMAIN_CATALOG_BYTES_LIMIT: number;
+export declare const AGENT_ENVIRONMENT_SNAPSHOT_BYTES_LIMIT: number;
+export declare const AGENT_ENVIRONMENT_EFFECTIVE_ENTRIES_MAX_LENGTH = 1024;
+export declare const AGENT_ENVIRONMENT_INTEGRATION_CONTRIBUTIONS_MAX_LENGTH = 4096;
+export type AgentEnvironmentDomain = (typeof AGENT_ENVIRONMENT_DOMAINS)[number];
+export type AgentEnvironmentEvidenceExtent = (typeof AGENT_ENVIRONMENT_EVIDENCE_EXTENTS)[number];
+export type AgentEnvironmentCompleteness = (typeof AGENT_ENVIRONMENT_COMPLETENESSES)[number];
+export type AgentEnvironmentAvailableDomainResult<Catalog> = Readonly<{
+    readonly kind: 'available';
+    readonly catalog: Catalog;
+    readonly extent: AgentEnvironmentEvidenceExtent;
+    readonly completeness: AgentEnvironmentCompleteness;
+    readonly reasons: readonly AgentEnvironmentReason[];
+}>;
+export type AgentEnvironmentUnavailableDomainResult = Readonly<{
+    readonly kind: 'unsupported' | 'not_initialized' | 'unavailable';
+    readonly reasons: readonly AgentEnvironmentReason[];
+}>;
+export type AgentEnvironmentDomainResult<Catalog> = AgentEnvironmentAvailableDomainResult<Catalog> | AgentEnvironmentUnavailableDomainResult;
+export type AgentEnvironmentContentResult = AgentEnvironmentDomainResult<AgentEffectiveContentCatalog>;
+export type AgentEnvironmentCommandsResult = AgentEnvironmentDomainResult<AgentCommandCatalog>;
+export type AgentEnvironmentExtensionsResult = AgentEnvironmentDomainResult<AgentExtensionCatalog>;
+export type AgentEnvironmentIntegrationsResult = AgentEnvironmentDomainResult<AgentIntegrationCatalog>;
+export interface AgentEnvironmentSnapshot {
+    readonly schemaVersion: typeof AGENT_ENVIRONMENT_SCHEMA_VERSION;
+    readonly environmentId: AgentEnvironmentId;
+    readonly revision: number;
+    readonly content: AgentEnvironmentContentResult;
+    readonly commands: AgentEnvironmentCommandsResult;
+    readonly extensions: AgentEnvironmentExtensionsResult;
+    readonly integrations: AgentEnvironmentIntegrationsResult;
+}
+export interface AgentEnvironmentInvalidation {
+    readonly environmentId: AgentEnvironmentId;
+    readonly domains: readonly AgentEnvironmentDomain[];
+}
+/** The serializable capability advertised by a provider instance or session. */
+export type AgentEnvironmentReadCapability = Readonly<{
+    readonly kind: 'unsupported';
+}> | Readonly<{
+    readonly kind: 'read';
+    readonly domains: readonly AgentEnvironmentDomain[];
+}> | Readonly<{
+    readonly kind: 'read_and_watch';
+    readonly domains: readonly AgentEnvironmentDomain[];
+}>;
+export interface AgentEnvironmentCapability {
+    readonly instance: AgentEnvironmentReadCapability;
+    readonly session: AgentEnvironmentReadCapability;
+}
+//# sourceMappingURL=types.d.ts.map