@agen-ai/agent-protocol 0.2.4 → 0.3.0

package/README.md

@@ -3,8 +3,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, 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.
+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.
 
 ## Ownership boundary
 
@@ -20,12 +21,18 @@ identities to protocol IDs.
 the currently running turn. It does not describe, authorize, or implement future-turn queueing;
 that product concern belongs to the caller's control plane.
 
+Account-quota observations describe the allowance state reported by the account that funds a
+provider connection. They do not identify that account, authorize a caller, decide whether a turn
+may run, or represent AgenAI billing. `sourceId`, `poolId`, and `windowId` are opaque correlation
+values. A quota observation with a known zero or an unknown reset remains valid; unavailable states
+carry no fabricated windows or hints.
+
 ## Entrypoints
 
 - `@agen-ai/agent-protocol` exports the complete plain API.
 - `/sessions`, `/turns`, `/requests`, `/events`, `/capabilities`, `/artifacts`, `/operations`,
-  `/configuration`, `/managed-content`, `/integrations`, `/collaboration`, and `/resources` are
-  focused plain entrypoints.
+  `/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.
 - `/json-schema` exposes deterministic draft 2020-12 schema artifacts.
 
@@ -43,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'),
@@ -58,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
@@ -71,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
@@ -83,7 +90,10 @@ content, and integrations are separate bounded, revisioned catalogs; capability
 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
+and an artifact reference only when the resource is available. Account-quota windows keep period,
+measurement, applicability, allowance, and observation timestamps separate so a provider cannot
+collapse unrelated pools into one percentage. Quantity units remain distinct from exact money,
+which uses integer minor units with an explicit scale. None of these domains has a generic
 extension or metadata bag.
 
 ## Errors and trust
@@ -102,13 +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.4` 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.
+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/accountQuota/index.d.ts

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

package/dist/accountQuota/index.js

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

package/dist/accountQuota/parsers.d.ts

@@ -0,0 +1,7 @@
+import type { AgentProtocolParseResult } from '../foundation/types.js';
+import type { AgentAccountQuotaSnapshot, AgentAccountQuotaWindow } from './types.js';
+export declare function parseAgentAccountQuotaSnapshot(input: unknown): AgentAccountQuotaSnapshot;
+export declare function safeParseAgentAccountQuotaSnapshot(input: unknown): AgentProtocolParseResult<AgentAccountQuotaSnapshot>;
+export declare function parseAgentAccountQuotaWindow(input: unknown): AgentAccountQuotaWindow;
+export declare function safeParseAgentAccountQuotaWindow(input: unknown): AgentProtocolParseResult<AgentAccountQuotaWindow>;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/accountQuota/parsers.js

@@ -0,0 +1,20 @@
+import { parseWithSchema, safeParseWithSchema } from "../internal/parsers.js";
+import { AgentAccountQuotaSnapshotSchema, AgentAccountQuotaWindowSchema } from "../zod/accountQuota.js";
+function parseAgentAccountQuotaSnapshot(input) {
+  return parseWithSchema(AgentAccountQuotaSnapshotSchema, input);
+}
+function safeParseAgentAccountQuotaSnapshot(input) {
+  return safeParseWithSchema(AgentAccountQuotaSnapshotSchema, input);
+}
+function parseAgentAccountQuotaWindow(input) {
+  return parseWithSchema(AgentAccountQuotaWindowSchema, input);
+}
+function safeParseAgentAccountQuotaWindow(input) {
+  return safeParseWithSchema(AgentAccountQuotaWindowSchema, input);
+}
+export {
+  parseAgentAccountQuotaSnapshot,
+  parseAgentAccountQuotaWindow,
+  safeParseAgentAccountQuotaSnapshot,
+  safeParseAgentAccountQuotaWindow
+};

package/dist/accountQuota/types.d.ts

@@ -0,0 +1,89 @@
+import type { AgentIsoDateTime } from '../foundation/types.js';
+export declare const AGENT_ACCOUNT_QUOTA_SCHEMA_VERSION: 1;
+export declare const AGENT_ACCOUNT_QUOTA_MAX_WINDOWS = 64;
+export declare const AGENT_ACCOUNT_QUOTA_MAX_BYTES = 65536;
+export declare const AGENT_ACCOUNT_QUOTA_MAX_LABEL_LENGTH = 160;
+export declare const AGENT_ACCOUNT_QUOTA_MAX_SCOPE_IDS = 32;
+export type AgentAccountQuotaApplicability = Readonly<{
+    kind: 'account';
+}> | Readonly<{
+    kind: 'product';
+    productId: string;
+}> | Readonly<{
+    kind: 'models';
+    modelIds: readonly string[];
+}> | Readonly<{
+    kind: 'unknown';
+}>;
+export type AgentAccountQuotaPeriod = Readonly<{
+    kind: 'rolling' | 'fixed' | 'unknown';
+    durationSeconds?: number;
+}> | Readonly<{
+    kind: 'calendar';
+    unit: 'day' | 'week' | 'month' | 'year';
+    timeZone: string;
+}> | Readonly<{
+    kind: 'billing_cycle';
+    unit: 'month' | 'year' | 'unknown';
+}>;
+export type AgentAccountQuotaMeasurement = Readonly<{
+    kind: 'unknown';
+}> | Readonly<{
+    kind: 'percentage';
+    usedPercent: number;
+}> | Readonly<{
+    kind: 'quantity';
+    unit: string;
+    used?: number;
+    limit?: number;
+    remaining?: number;
+    usedPercent?: number;
+}> | Readonly<{
+    kind: 'money';
+    currency: string;
+    scale: number;
+    usedMinorUnits?: number;
+    limitMinorUnits?: number;
+    remainingMinorUnits?: number;
+    usedPercent?: number;
+}>;
+export interface AgentAccountQuotaReset {
+    readonly at: AgentIsoDateTime;
+    readonly precision: 'reported' | 'estimated';
+    readonly observedAt: AgentIsoDateTime;
+}
+export interface AgentAccountQuotaWindow {
+    readonly poolId: string;
+    readonly windowId: string;
+    readonly label: string;
+    readonly allowanceKind: 'included' | 'extra' | 'reserve' | 'unknown';
+    readonly applicability: AgentAccountQuotaApplicability;
+    readonly period: AgentAccountQuotaPeriod;
+    readonly measurement: AgentAccountQuotaMeasurement;
+    readonly observedAt: AgentIsoDateTime;
+    readonly startsAt?: AgentIsoDateTime;
+    readonly reset?: AgentAccountQuotaReset;
+}
+export interface AgentAccountQuotaAllowance {
+    readonly included: 'allowed' | 'exhausted' | 'unknown';
+    readonly extra: 'allowed' | 'unavailable' | 'unknown';
+    readonly reserve: 'allowed' | 'unavailable' | 'unknown';
+}
+interface AgentAccountQuotaSnapshotBase {
+    readonly schemaVersion: typeof AGENT_ACCOUNT_QUOTA_SCHEMA_VERSION;
+    readonly sourceId: string;
+    readonly observedAt: AgentIsoDateTime;
+}
+export interface AgentAvailableAccountQuotaSnapshot extends AgentAccountQuotaSnapshotBase {
+    readonly state: 'available';
+    readonly completeness: 'complete' | 'partial';
+    readonly accountLabel?: string;
+    readonly planLabel?: string;
+    readonly windows: readonly AgentAccountQuotaWindow[];
+    readonly allowance: AgentAccountQuotaAllowance;
+}
+export type AgentAccountQuotaSnapshot = AgentAvailableAccountQuotaSnapshot | Readonly<AgentAccountQuotaSnapshotBase & {
+    state: 'authentication_required' | 'inapplicable' | 'temporarily_unavailable';
+}>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/accountQuota/types.js

@@ -0,0 +1,12 @@
+const AGENT_ACCOUNT_QUOTA_SCHEMA_VERSION = 1;
+const AGENT_ACCOUNT_QUOTA_MAX_WINDOWS = 64;
+const AGENT_ACCOUNT_QUOTA_MAX_BYTES = 65536;
+const AGENT_ACCOUNT_QUOTA_MAX_LABEL_LENGTH = 160;
+const AGENT_ACCOUNT_QUOTA_MAX_SCOPE_IDS = 32;
+export {
+  AGENT_ACCOUNT_QUOTA_MAX_BYTES,
+  AGENT_ACCOUNT_QUOTA_MAX_LABEL_LENGTH,
+  AGENT_ACCOUNT_QUOTA_MAX_SCOPE_IDS,
+  AGENT_ACCOUNT_QUOTA_MAX_WINDOWS,
+  AGENT_ACCOUNT_QUOTA_SCHEMA_VERSION
+};

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";