@clowder-ai/plugin-contract 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/generated/contract.generated.d.ts

@@ -1,7 +1,21 @@
 /**
- * Generated from manifest.schema.json, messaging.schema.json, and behavior-fixture.schema.json.
+ * Generated from plugin-metadata.schema.json, manifest.schema.json, catalog.schema.json, signal.schema.json, messaging.schema.json, physical-limb.schema.json, docx-materialization.schema.json, and behavior-fixture.schema.json.
  * Do not edit by hand. Run `pnpm generate` after changing a schema.
  */
+export type LocalizedDescriptionObject = {
+    readonly default: string;
+    readonly translations: Readonly<Record<string, string>>;
+};
+export type LocalizedDescription = string | LocalizedDescriptionObject;
+export type PackageAssetPath = string;
+export type PackageIcon = {
+    readonly type: 'svg';
+    readonly src: PackageAssetPath & `${string}.svg`;
+} | {
+    readonly type: 'png';
+    readonly src: PackageAssetPath & `${string}.png`;
+};
+export type PluginIcon = 'github' | PackageIcon;
 export type SemVer = string;
 export type DataClass = 'cache' | 'ephemeral' | 'user-authored' | 'derived-user-visible' | 'relationship' | 'interaction-history';
 export type DataStrategy = 'lifecycle' | 'retained' | 'ask-on-uninstall';
@@ -41,17 +55,246 @@ export type ResourceReference = {
     readonly type: string;
     readonly id: string;
 };
+export type ContributionReference = {
+    readonly type: 'identity' | 'schedule' | 'tool' | 'mcp' | 'skill' | 'limb' | 'webhook' | 'message-subscription' | 'service' | 'connector' | 'ui' | 'content-editor-provider' | 'desktop-window';
+    readonly id: string;
+};
+export type PackageRelativePath = string;
+export type ConfigurationOption = {
+    readonly value: string;
+    readonly label: string;
+    readonly hint?: string;
+    readonly docsUrl?: string;
+};
+export type ConfigurationField = {
+    readonly key: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly kind: 'string';
+    readonly required: boolean;
+    readonly default?: string;
+    readonly options?: never;
+} | {
+    readonly key: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly kind: 'secret';
+    readonly required: boolean;
+    readonly default?: never;
+    readonly options?: never;
+} | {
+    readonly key: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly kind: 'select';
+    readonly required: boolean;
+    readonly default?: string;
+    readonly options: readonly ConfigurationOption[];
+} | {
+    readonly key: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly kind: 'boolean';
+    readonly required: boolean;
+    readonly default?: boolean;
+    readonly options?: never;
+} | {
+    readonly key: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly kind: 'number';
+    readonly required: boolean;
+    readonly default?: number;
+    readonly options?: never;
+} | {
+    readonly key: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly kind: 'url';
+    readonly required: boolean;
+    readonly default?: string;
+    readonly options?: never;
+};
+export type EnvironmentBinding = {
+    readonly source: 'config';
+    readonly key: string;
+} | {
+    readonly source: 'secret';
+    readonly key: string;
+};
+export type ContributionRuntime = {
+    readonly transport: 'stdio' | 'ipc';
+    readonly entrypoint: PackageRelativePath;
+    readonly args?: readonly string[];
+};
+export type CallbackAction = {
+    readonly method: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+};
+export type IdentityContribution = {
+    readonly type: 'identity';
+    readonly id: string;
+    readonly displayName: string;
+    readonly icon?: string;
+    readonly color?: string;
+};
+export type ScheduleContribution = {
+    readonly type: 'schedule';
+    readonly id: string;
+    readonly schedule: {
+        readonly kind: 'interval';
+        readonly everyMs: number;
+    } | {
+        readonly kind: 'cron';
+        readonly expression: string;
+    };
+    readonly action: CallbackAction;
+    readonly policy: {
+        readonly overlap: 'skip';
+        readonly timeoutMs: number;
+    };
+};
+export type DirectToolContribution = {
+    readonly type: 'tool';
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    readonly action: CallbackAction;
+};
+export type McpContribution = {
+    readonly type: 'mcp';
+    readonly id: string;
+    readonly runtime: ContributionRuntime;
+    readonly environment?: Readonly<Record<string, EnvironmentBinding>>;
+};
+export type SkillContribution = {
+    readonly type: 'skill';
+    readonly id: string;
+    readonly path: PackageRelativePath;
+};
+export type LimbContribution = {
+    readonly type: 'limb';
+    readonly id: string;
+    readonly manifestPath: PackageRelativePath;
+};
+export type WebhookContribution = {
+    readonly type: 'webhook';
+    readonly id: string;
+    readonly path: string;
+    readonly methods: readonly ('GET' | 'POST' | 'PUT' | 'DELETE')[];
+    readonly action: CallbackAction;
+    readonly verificationSecretRef?: string;
+};
+export type MessageSubscriptionContribution = {
+    readonly type: 'message-subscription';
+    readonly id: string;
+    readonly binding: string;
+    readonly filter?: Readonly<Record<string, unknown>>;
+    readonly action: CallbackAction;
+};
+export type ServiceContribution = {
+    readonly type: 'service';
+    readonly id: string;
+    readonly runtime: ContributionRuntime;
+    readonly healthMethod: string;
+    readonly environment?: Readonly<Record<string, EnvironmentBinding>>;
+};
+export type ConnectorContribution = {
+    readonly type: 'connector';
+    readonly id: string;
+    readonly identityRef: string;
+    readonly inboundMethod: string;
+    readonly outboundMethod: string;
+};
+export type UiWhenClause = {
+    readonly featureEnabled?: boolean;
+    readonly requiresCapabilities?: readonly Capability[];
+};
+export type UiAnchor = {
+    readonly position: 'before' | 'after';
+    readonly target: string;
+};
+export type UiCommandContribution = {
+    readonly type: 'ui';
+    readonly id: string;
+    readonly kind: 'command';
+    readonly label: string;
+    readonly action: CallbackAction;
+    readonly when?: UiWhenClause;
+};
+export type UiSlotItemContribution = {
+    readonly type: 'ui';
+    readonly id: string;
+    readonly kind: 'slot-item';
+    readonly label: string;
+    readonly command: string;
+    readonly group: string;
+    readonly anchor?: UiAnchor;
+    readonly order?: number;
+    readonly when?: UiWhenClause;
+};
+export type UiMessageElementContribution = {
+    readonly type: 'ui';
+    readonly id: string;
+    readonly kind: 'message-element';
+    readonly label: string;
+    readonly elementKind: string;
+    readonly renderer: string;
+    readonly when?: UiWhenClause;
+};
+export type UiContribution = UiCommandContribution | UiSlotItemContribution | UiMessageElementContribution;
+export type SemanticMaterializerDeclaration = {
+    readonly executionClass: 'dedicated-browser-worker';
+    readonly entrypoint: PackageRelativePath & `${string}.js`;
+    readonly integrity: string;
+    readonly protocolVersion: '1.0.0';
+};
+export type DesktopWindowContribution = {
+    readonly type: 'desktop-window';
+    readonly id: string;
+    readonly role: 'companion';
+    readonly surface: {
+        readonly entrypoint: PackageRelativePath & `${string}.html`;
+        readonly integrity: string;
+    };
+    readonly bridgeVersion: '1.0.0' | '1.1.0' | '1.2.0' | '1.3.0';
+    readonly presentation: {
+        readonly width: number;
+        readonly height: number;
+        readonly transparent: true;
+        readonly frame: false;
+        readonly alwaysOnTop: boolean;
+        readonly skipTaskbar: boolean;
+    };
+};
+export type ContentEditorProviderContribution = {
+    readonly type: 'content-editor-provider';
+    readonly id: string;
+    readonly mediaTypes: readonly ['application/vnd.openxmlformats-officedocument.wordprocessingml.document'];
+    readonly surface: {
+        readonly entrypoint: PackageRelativePath;
+        readonly integrity: string;
+        readonly sandbox: 'dedicated-origin-iframe';
+        readonly navigationPolicy: 'navigation-api-deny';
+    };
+    readonly bridgeVersion: '1.0.0';
+    readonly semanticMaterializer?: SemanticMaterializerDeclaration;
+    readonly operations: readonly ['load' | 'settle' | 'comment' | 'tracked-change', 'load' | 'settle' | 'comment' | 'tracked-change', 'load' | 'settle' | 'comment' | 'tracked-change', 'load' | 'settle' | 'comment' | 'tracked-change'];
+};
+export type StaticContribution = IdentityContribution | ScheduleContribution | DirectToolContribution | McpContribution | SkillContribution | LimbContribution | WebhookContribution | MessageSubscriptionContribution | ServiceContribution | ConnectorContribution | UiContribution | ContentEditorProviderContribution | DesktopWindowContribution;
 export type PluginFeature = {
     readonly id: string;
     readonly name: string;
     readonly resources: readonly ResourceReference[];
+    readonly contributions?: readonly ContributionReference[];
     readonly capabilities: readonly Capability[];
 };
 export type RuntimeTransport = 'stdio' | 'ipc' | 'builtin';
 export type ExternalRuntimeTransport = 'stdio' | 'ipc';
 export type ExternalRuntimeDeclaration = {
     readonly transport: ExternalRuntimeTransport;
-    readonly entrypoint: string;
+    readonly entrypoint: PackageRelativePath;
 };
 export type BuiltinRuntimeDeclaration = {
     readonly transport: 'builtin';
@@ -63,10 +306,87 @@ export type PluginManifest = {
     readonly version: SemVer;
     readonly contractVersion: SemVer;
     readonly name: string;
-    readonly description?: string;
+    readonly description?: LocalizedDescription;
+    readonly icon?: PluginIcon;
+    readonly configuration?: readonly ConfigurationField[];
+    readonly contributions?: readonly StaticContribution[];
     readonly features: readonly PluginFeature[];
     readonly data?: readonly DataDeclaration[];
     readonly runtime: RuntimeDeclaration;
+    readonly signals?: SignalContribution;
+};
+export type CatalogSemVer = string;
+export type CatalogPublisher = {
+    readonly id: string;
+    readonly name: string;
+};
+export type ArtifactProvenance = {
+    readonly repository: string;
+    readonly sourceDirectory: string;
+};
+export type NpmArtifact = {
+    readonly kind: 'npm';
+    readonly packageName: string;
+    readonly version: CatalogSemVer;
+    readonly tarballUrl: string;
+    readonly integrity: string;
+    readonly shasum: string;
+    readonly provenance: ArtifactProvenance;
+};
+export type CatalogPluginVersion = {
+    readonly version: CatalogSemVer;
+    readonly contractVersion: CatalogSemVer;
+    readonly manifestPath: 'plugin.yaml';
+    readonly artifact: NpmArtifact;
+};
+export type CatalogPluginEntry = {
+    readonly pluginId: string;
+    readonly name: string;
+    readonly description: LocalizedDescription;
+    readonly icon: PluginIcon;
+    readonly publisher: CatalogPublisher;
+    readonly keywords?: readonly string[];
+    readonly versions: readonly CatalogPluginVersion[];
+};
+export type PluginCatalog = {
+    readonly schemaVersion: '1';
+    readonly plugins: readonly CatalogPluginEntry[];
+};
+export type SignalType = string;
+export type SignalSchemaRef = string;
+export type SignalEpistemicStatus = 'observation' | 'inference';
+export type SignalPrivacyClass = 'behavioral' | 'content-adjacent' | 'content' | 'av-raw' | 'input-raw';
+export type AdmissibleSignalPrivacyClass = 'behavioral' | 'content-adjacent' | 'content';
+export type SignalSourceClass = 'os-metadata' | 'accessibility-api' | 'remote-service' | 'av-capture' | 'input-hardware';
+export type AdmissibleSignalSourceClass = 'os-metadata' | 'accessibility-api' | 'remote-service';
+export type SignalDeclaration = {
+    readonly type: SignalType;
+    readonly schemaRef: SignalSchemaRef;
+    readonly epistemicStatus: SignalEpistemicStatus;
+    readonly privacyClass: AdmissibleSignalPrivacyClass;
+    readonly sourceClass: AdmissibleSignalSourceClass;
+};
+export type SignalContribution = {
+    readonly provides: readonly SignalDeclaration[];
+};
+export type SignalEventId = string;
+export type SignalIdempotencyKey = string;
+export type OpaqueSourceHandle = string;
+export type SignalSourceRef = {
+    readonly handle: OpaqueSourceHandle;
+};
+export type EventsPublishInput = {
+    readonly signalType: SignalType;
+    readonly eventId: SignalEventId;
+    readonly idempotencyKey: SignalIdempotencyKey;
+    readonly occurredAt: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly source: SignalSourceRef;
+};
+export type EventsPublishDisposition = 'accepted' | 'duplicate';
+export type EventsPublishResult = {
+    readonly publicationId: SignalEventId;
+    readonly disposition: EventsPublishDisposition;
 };
 export type ActorKind = 'user' | 'cat' | 'plugin' | 'device' | 'system';
 export type ActorRef = {
@@ -171,6 +491,7 @@ export type MessageDraft = {
     readonly replyTo?: string;
     readonly payload: DraftPayload;
 };
+export type OccurredAt = string | string;
 export type MessageEnvelope = {
     readonly messageId: string;
     readonly revision: number;
@@ -178,7 +499,7 @@ export type MessageEnvelope = {
     readonly replyTo?: string;
     readonly actor: ActorRef;
     readonly audience: CanonicalAudience;
-    readonly occurredAt: string;
+    readonly occurredAt: OccurredAt;
     readonly payload: MessagePayload;
 };
 export type MessagePublishEvent = {
@@ -203,6 +524,7 @@ export type SendReceipt = {
     readonly messageId: string;
     readonly threadId: string;
     readonly revision: number;
+    readonly messageHandle: MessageHandle;
     readonly publishSequence?: number;
 };
 export type AppendReceipt = {
@@ -229,12 +551,12 @@ export type SubscriptionNormalResponse = {
     readonly stale: false;
 };
 export type SubscriptionEmptyResponse = {
-    readonly events: readonly MessageOutputEvent[];
+    readonly events: readonly [];
     readonly ackToken: null;
     readonly stale: false;
 };
 export type SubscriptionStaleResponse = {
-    readonly events: readonly MessageOutputEvent[];
+    readonly events: readonly [];
     readonly ackToken: null;
     readonly stale: true;
 };
@@ -243,6 +565,485 @@ export type SnapshotResponse = {
     readonly envelopes: readonly MessageEnvelope[];
     readonly resumeSequence: number;
 };
+export type M0CSubscribeInput = {
+    readonly handle: string;
+};
+export type M0CSubscribeResult = {
+    readonly subscriptionId: string;
+};
+export type M0CReadInput = {
+    readonly subscriptionId: string;
+    readonly limit: number;
+};
+export type M0CReadNormalResult = {
+    readonly events: readonly MessageOutputEvent[];
+    readonly ackToken: string;
+    readonly stale: false;
+};
+export type M0CReadEmptyResult = {
+    readonly events: readonly [];
+    readonly ackToken: null;
+    readonly stale: false;
+};
+export type M0CReadStaleResult = {
+    readonly events: readonly [];
+    readonly ackToken: null;
+    readonly stale: true;
+};
+export type M0CReadResult = M0CReadNormalResult | M0CReadEmptyResult | M0CReadStaleResult;
+export type M0CAckInput = {
+    readonly subscriptionId: string;
+    readonly ackToken: string;
+};
+export type M0CAckResult = null;
+export type M0CSnapshotInput = {
+    readonly subscriptionId: string;
+    readonly maxItems: number;
+    readonly pageToken?: string;
+};
+export type M0CSnapshotIntermediateResult = {
+    readonly items: readonly MessageEnvelope[];
+    readonly nextPageToken: string;
+    readonly snapshotAckToken: null;
+};
+export type M0CSnapshotFinalResult = {
+    readonly items: readonly MessageEnvelope[];
+    readonly nextPageToken: null;
+    readonly snapshotAckToken: string;
+};
+export type M0CSnapshotResult = M0CSnapshotIntermediateResult | M0CSnapshotFinalResult;
+export type M0CDeliverInput = {
+    readonly deliveryId: string;
+    readonly threadHandle: ThreadHandleAddress;
+    readonly envelope: MessageEnvelope;
+};
+export type M0CDeliverResult = {
+    readonly deliveryId: string;
+};
+export type PhysicalLimbIdentifier = string;
+export type PhysicalLimbGrant = 'limb.action.motion' | 'limb.action.display' | 'limb.action.light' | 'limb.action.speaker' | 'limb.observe.touch' | 'limb.sensor.microphone' | 'limb.sensor.camera';
+export type PhysicalLimbSafePose = {
+    readonly yawDeg: number;
+    readonly pitchDeg: number;
+    readonly timeoutMs: number;
+};
+export type PhysicalLimbContribution = {
+    readonly contributionId: PhysicalLimbIdentifier;
+    readonly nodeType: PhysicalLimbIdentifier;
+    readonly displayName: string;
+    readonly grants: readonly PhysicalLimbGrant[];
+    readonly safePose: PhysicalLimbSafePose;
+};
+export type PhysicalLimbExpressionSource = {
+    readonly kind: 'cat_state' | 'play' | 'degraded';
+    readonly ref: PhysicalLimbIdentifier;
+};
+export type PhysicalLimbTouchPayload = {
+    readonly gesture: 'tap' | 'stroke';
+    readonly durationMs: number;
+    readonly confidence: number;
+};
+export type PhysicalLimbTranscriptPayload = {
+    readonly interactionId: PhysicalLimbIdentifier;
+    readonly text: string;
+    readonly language?: string;
+    readonly captureDurationMs: number;
+};
+export type PhysicalLimbTouchObservation = {
+    readonly v: 1;
+    readonly observationId: PhysicalLimbIdentifier;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly occurredAt: string;
+    readonly sessionId: PhysicalLimbIdentifier;
+    readonly kind: 'touch';
+    readonly payload: PhysicalLimbTouchPayload;
+};
+export type PhysicalLimbTranscriptObservation = {
+    readonly v: 1;
+    readonly observationId: PhysicalLimbIdentifier;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly occurredAt: string;
+    readonly sessionId: PhysicalLimbIdentifier;
+    readonly kind: 'transcript';
+    readonly payload: PhysicalLimbTranscriptPayload;
+};
+export type PhysicalLimbObservation = PhysicalLimbTouchObservation | PhysicalLimbTranscriptObservation;
+export type PhysicalLimbMotionPayload = {
+    readonly yawDeg: number;
+    readonly pitchDeg: number;
+    readonly speedDps: number;
+    readonly accelerationDps2: number;
+};
+export type PhysicalLimbDisplayPayload = {
+    readonly expression: string;
+    readonly expressionSource: PhysicalLimbExpressionSource;
+};
+export type PhysicalLimbRgb = readonly [number, number, number];
+export type PhysicalLimbLightPayload = {
+    readonly colors: readonly PhysicalLimbRgb[];
+};
+export type PhysicalLimbSpeakerPayload = {
+    readonly text: string;
+    readonly voiceProfileRef: PhysicalLimbIdentifier;
+    readonly volumePercent: number;
+};
+export type PhysicalLimbMotionAction = {
+    readonly v: 1;
+    readonly actionId: PhysicalLimbIdentifier;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly deadlineUnixMs: number;
+    readonly timeoutMs: number;
+    readonly cancelToken: PhysicalLimbIdentifier;
+    readonly kind: 'motion';
+    readonly payload: PhysicalLimbMotionPayload;
+};
+export type PhysicalLimbDisplayAction = {
+    readonly v: 1;
+    readonly actionId: PhysicalLimbIdentifier;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly deadlineUnixMs: number;
+    readonly timeoutMs: number;
+    readonly cancelToken: PhysicalLimbIdentifier;
+    readonly kind: 'display';
+    readonly payload: PhysicalLimbDisplayPayload;
+};
+export type PhysicalLimbLightAction = {
+    readonly v: 1;
+    readonly actionId: PhysicalLimbIdentifier;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly deadlineUnixMs: number;
+    readonly timeoutMs: number;
+    readonly cancelToken: PhysicalLimbIdentifier;
+    readonly kind: 'light';
+    readonly payload: PhysicalLimbLightPayload;
+};
+export type PhysicalLimbSpeakerAction = {
+    readonly v: 1;
+    readonly actionId: PhysicalLimbIdentifier;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly deadlineUnixMs: number;
+    readonly timeoutMs: number;
+    readonly cancelToken: PhysicalLimbIdentifier;
+    readonly kind: 'speaker';
+    readonly payload: PhysicalLimbSpeakerPayload;
+};
+export type PhysicalLimbAction = PhysicalLimbMotionAction | PhysicalLimbDisplayAction | PhysicalLimbLightAction | PhysicalLimbSpeakerAction;
+export type PhysicalLimbCancel = {
+    readonly v: 1;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly actionId: PhysicalLimbIdentifier;
+    readonly cancelToken: PhysicalLimbIdentifier;
+    readonly reason: 'user' | 'timeout' | 'lease_lost' | 'host_lost' | 'superseded';
+};
+export type PhysicalLimbActionResult = {
+    readonly v: 1;
+    readonly actionId: PhysicalLimbIdentifier;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly outcome: 'succeeded' | 'refused' | 'failed' | 'canceled';
+    readonly reason?: string;
+    readonly observedAt: string;
+};
+export type PhysicalLimbReadinessReason = 'gateway_disconnected' | 'device_disconnected' | 'firmware_incompatible' | 'sensor_unavailable' | 'speech_dependency_missing' | 'skin_unavailable' | 'grant_revoked' | 'host_unavailable';
+export type PhysicalLimbReadyReadiness = {
+    readonly v: 1;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly status: 'ready';
+    readonly observedAt: string;
+};
+export type PhysicalLimbUnavailableReadiness = {
+    readonly v: 1;
+    readonly nodeId: PhysicalLimbIdentifier;
+    readonly status: 'degraded' | 'offline';
+    readonly reason: PhysicalLimbReadinessReason;
+    readonly observedAt: string;
+};
+export type PhysicalLimbReadiness = PhysicalLimbReadyReadiness | PhysicalLimbUnavailableReadiness;
+export type DocxMaterializationText = string;
+export type DocxMaterializationAuthor = string;
+export type DocxMaterializationBytes = string;
+export type DocxMaterializationAnchor = {
+    readonly paragraphId: string;
+    readonly textQuote: string;
+};
+export type DocxMaterializationAttribution = {
+    readonly author: DocxMaterializationAuthor;
+    readonly operationId: string;
+    readonly timestamp: string;
+};
+export type DocxMaterializationOperation = {
+    readonly kind: 'inspect';
+    readonly cursor: number;
+    readonly limit: number;
+} | {
+    readonly kind: 'tracked-change';
+    readonly target: DocxMaterializationAnchor;
+    readonly replacement: DocxMaterializationText;
+    readonly attribution: DocxMaterializationAttribution;
+} | {
+    readonly kind: 'comment';
+    readonly target: DocxMaterializationAnchor;
+    readonly body: DocxMaterializationText;
+    readonly attribution: DocxMaterializationAttribution;
+};
+export type DocxMaterializationRequest = {
+    readonly protocolVersion: '1.0.0';
+    readonly requestId: string;
+    readonly mediaType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+    readonly bytesBase64: DocxMaterializationBytes;
+    readonly operation: DocxMaterializationOperation;
+};
+export type DocxMaterializationResult = {
+    readonly kind: 'inspection';
+    readonly paragraphs: readonly ({
+        readonly target: DocxMaterializationAnchor;
+        readonly editable: boolean;
+    })[];
+    readonly nextCursor: number | null;
+} | {
+    readonly kind: 'document';
+    readonly bytesBase64: DocxMaterializationBytes;
+} | {
+    readonly kind: 'rejected';
+    readonly code: 'INVALID_DOCX' | 'TARGET_MISMATCH' | 'UNSUPPORTED_TARGET' | 'LIMIT_EXCEEDED' | 'INVALID_REQUEST';
+};
+export type DocxMaterializationResponse = {
+    readonly protocolVersion: '1.0.0';
+    readonly requestId: string;
+    readonly result: DocxMaterializationResult;
+};
+export type CompanionSelectionId = string;
+export type CompanionScreenFrame = {
+    readonly image: string;
+    readonly width: number;
+    readonly height: number;
+    readonly frameId: string;
+    readonly sourceLabel: string;
+    readonly observedAt: number;
+};
+export type CompanionCommand = {
+    readonly kind: 'state';
+} | {
+    readonly kind: 'prepare';
+} | {
+    readonly kind: 'audio.connect';
+    readonly mode?: 'receive_only';
+} | {
+    readonly kind: 'audio.close';
+} | {
+    readonly kind: 'audio.microphone';
+    readonly muted: boolean;
+} | {
+    readonly kind: 'audio.speaker';
+    readonly muted: boolean;
+} | {
+    readonly kind: 'stop';
+} | {
+    readonly kind: 'text';
+    readonly text: string;
+    readonly clientMessageId: string;
+} | {
+    readonly kind: 'documents';
+    readonly allowed: boolean;
+} | {
+    readonly kind: 'screen.pick';
+} | {
+    readonly kind: 'screen.open';
+    readonly selectionId: CompanionSelectionId;
+    readonly label: string;
+} | {
+    readonly kind: 'screen.frame';
+    readonly selectionId: CompanionSelectionId;
+    readonly frame: CompanionScreenFrame;
+} | {
+    readonly kind: 'screen.close';
+} | {
+    readonly kind: 'conversation.open';
+} | {
+    readonly kind: 'decisions.read';
+    readonly offset: number;
+    readonly limit: number;
+} | {
+    readonly kind: 'f221.inspect';
+    readonly proposalId: string;
+} | {
+    readonly kind: 'view.resize';
+    readonly expanded: boolean;
+} | {
+    readonly kind: 'view.layout';
+    readonly panel: 'none' | 'bubble' | 'actions' | 'menu' | 'chat' | 'decisions';
+    readonly width: number;
+    readonly height: number;
+} | {
+    readonly kind: 'view.drag';
+    readonly phase: 'start' | 'end';
+} | {
+    readonly kind: 'view.hide';
+} | {
+    readonly kind: 'conversation.read';
+};
+export type CompanionActor = {
+    readonly catId: string;
+    readonly displayName: string;
+};
+export type CompanionIdentitySnapshotV1 = {
+    readonly v: 1;
+    readonly name: '猫猫球';
+    readonly partner: {
+        readonly catId: string;
+        readonly displayName: string;
+        readonly skin: string;
+    };
+    readonly live: {
+        readonly catId: string;
+        readonly displayName: string;
+        readonly transport: 'gpt_live_v3';
+        readonly verifiedModel: string | null;
+    };
+    readonly deep: {
+        readonly catId: string;
+        readonly displayName: string;
+        readonly verifiedModel: string | null;
+    };
+};
+export type CompanionLiveTransport = {
+    readonly kind: 'gpt_live_v3';
+    readonly verifiedModel: null;
+};
+export type CompanionAudioState = {
+    readonly supportedModes: readonly ('duplex' | 'receive_only')[];
+    readonly activeMode: 'duplex' | 'receive_only' | null;
+};
+export type CompanionNativeWorkEntry = {
+    readonly taskId: string;
+    readonly nativeTurnId: string;
+    readonly kind: 'reasoning' | 'tool' | 'workspace_fetch' | 'workspace_dispatch' | 'screen_read';
+    readonly startedAt: number;
+    readonly expiresAt: number;
+};
+export type CompanionNativeWorkEvent = {
+    readonly eventId: string;
+    readonly taskId: string;
+    readonly kind: 'reasoning' | 'tool' | 'workspace_fetch' | 'workspace_dispatch' | 'screen_read' | 'result';
+    readonly phase: 'started' | 'completed' | 'failed' | 'cancelled' | 'expired' | 'result_handed_to_voice';
+    readonly occurredAt: number;
+    readonly expiresAt: number;
+    readonly resultId?: string;
+    readonly nativeCarrierCatId?: string;
+};
+export type CompanionNativeWork = {
+    readonly scopeId: string | null;
+    readonly revision: number;
+    readonly active: readonly CompanionNativeWorkEntry[];
+    readonly recent: readonly CompanionNativeWorkEvent[];
+};
+export type CompanionState = {
+    readonly kind: 'state';
+    readonly phase: 'idle' | 'preparing' | 'ready' | 'connecting' | 'talking' | 'closed' | 'failed';
+    readonly displayName: string;
+    readonly skin: string;
+    readonly duty: CompanionActor;
+    readonly carrier: CompanionActor;
+    readonly documentsAllowed: boolean;
+    readonly toolsReady: boolean;
+    readonly nativeActivity: 'none' | 'reasoning' | 'tool_running';
+    readonly liveTransport: CompanionLiveTransport;
+    readonly audio?: CompanionAudioState;
+    readonly nativeWork: CompanionNativeWork;
+};
+export type CompanionDecisions = {
+    readonly kind: 'decisions';
+    readonly status: 'available' | 'unavailable';
+    readonly approvalCount: number | null;
+    readonly needsMeCount: number | null;
+    readonly otherNeedsMeCount: number | null;
+    readonly approvals: readonly ({
+        readonly proposalId: string;
+        readonly sourceFeatureId: string;
+        readonly summary: string;
+        readonly resolution: 'open' | 'accepted' | 'rejected' | 'closed_without_decision';
+        readonly materializationState: 'not_started' | 'outcome_unknown' | 'in_progress' | 'succeeded' | 'failed';
+        readonly linkedNeedsMe: boolean;
+    })[];
+    readonly otherNeedsMe: readonly ({
+        readonly subjectRef: string;
+        readonly summary: string;
+    })[];
+    readonly page: {
+        readonly offset: number;
+        readonly limit: number;
+        readonly hasMoreApprovals: boolean;
+        readonly hasMoreNeedsMe: boolean;
+    };
+};
+export type CompanionDecisionTrial = {
+    readonly kind: 'decision-trial';
+    readonly status: 'dismissed' | 'trial_confirmed' | 'stale' | 'unavailable';
+};
+export type CompanionErrorCode = 'invalid_request' | 'permission_required' | 'unavailable' | 'session_required' | 'busy' | 'selection_changed' | 'carrier_unavailable' | 'cancelled' | 'unconfirmed';
+export type CompanionReply = {
+    readonly kind: 'ok';
+} | CompanionState | CompanionDecisions | CompanionDecisionTrial | {
+    readonly kind: 'delivery';
+    readonly delivery: 'accepted' | 'unconfirmed';
+} | {
+    readonly kind: 'selection';
+    readonly selectionId: CompanionSelectionId;
+} | {
+    readonly kind: 'navigation';
+    readonly delivery: 'requested' | 'unconfirmed';
+} | {
+    readonly kind: 'error';
+    readonly code: CompanionErrorCode;
+} | {
+    readonly kind: 'layout';
+    readonly pet: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly panel: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly width: number;
+    readonly height: number;
+} | {
+    readonly kind: 'conversation';
+    readonly threadTitle: string;
+    readonly messages: readonly ({
+        readonly id: string;
+        readonly role: 'user' | 'assistant';
+        readonly text: string;
+        readonly name: string;
+        readonly companionIdentity?: CompanionIdentitySnapshotV1;
+    })[];
+    readonly hasMore: boolean;
+};
+export type CompanionEvent = {
+    readonly kind: 'media-stopped';
+    readonly reason: 'locked' | 'suspended' | 'hidden' | 'closed' | 'revoked';
+} | {
+    readonly kind: 'audio';
+    readonly type: 'connected' | 'recovering' | 'recovered' | 'error';
+} | {
+    readonly kind: 'audio';
+    readonly type: 'transcript';
+    readonly role: 'user' | 'assistant';
+    readonly text: string;
+    readonly turnId?: string;
+    readonly itemId?: string;
+} | {
+    readonly kind: 'audio';
+    readonly type: 'turn-done';
+    readonly role?: 'user' | 'assistant';
+    readonly transcript?: string;
+    readonly turnId?: string;
+} | {
+    readonly kind: 'view-dismiss';
+};
+export declare const DOCX_MATERIALIZATION_TEXT_PATTERN = "^[\\u0009\\u000A\\u0020-\\uD7FF\\uE000-\\uFFFD\\u{10000}-\\u{10FFFF}]*(?![\\s\\S])";
+export declare const DOCX_MATERIALIZATION_AUTHOR_PATTERN = "^[\\u0020-\\uD7FF\\uE000-\\uFFFD\\u{10000}-\\u{10FFFF}]*(?![\\s\\S])";
 export type FixtureMetadata = {
     readonly executor: 'loopback';
     readonly domain: 'messaging';
@@ -302,6 +1103,31 @@ export type FixtureOperation = {
     readonly operation: 'deleteReplayEvents';
     readonly input: DeleteReplayEventsInput;
 };
+export type PluginToHostMethod = 'messaging.send' | 'messaging.appendElements' | 'messaging.subscribe' | 'messaging.read' | 'messaging.ack' | 'messaging.snapshot';
+export type BehaviorExpectationOracle = {
+    readonly kind: 'behavior-expectation';
+};
+export type JsonRpcAdmissionOracle = {
+    readonly kind: 'json-rpc-error';
+    readonly code: -32602;
+    readonly sideEffects: 'behavior-expectation';
+};
+export type BehaviorExecution = {
+    readonly plane: 'plugin-to-host-wire';
+    readonly method: PluginToHostMethod;
+    readonly verdictOracle: BehaviorExpectationOracle;
+} | {
+    readonly plane: 'wire-admission';
+    readonly method: PluginToHostMethod;
+    readonly verdictOracle: JsonRpcAdmissionOracle;
+} | {
+    readonly plane: 'host-to-plugin-delivery';
+    readonly method: 'host.messaging.deliver';
+    readonly verdictOracle: BehaviorExpectationOracle;
+} | {
+    readonly plane: 'host-control';
+    readonly verdictOracle: BehaviorExpectationOracle;
+};
 export type SendOperationInput = {
     readonly address: Readonly<Record<string, unknown>>;
     readonly idempotencyKey: string;
@@ -344,7 +1170,7 @@ export type PermissionMatrixEntry = {
     readonly firstPartyPreset: boolean;
 };
 export type PermissionMatrixInput = {
-    readonly entries: readonly PermissionMatrixEntry[];
+    readonly entries: readonly [PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry, PermissionMatrixEntry];
 };
 export type DeleteReplayEventsInput = {
     readonly subscriptionId: string;
@@ -352,19 +1178,159 @@ export type DeleteReplayEventsInput = {
 };
 export type SideEffectAssertion = {
     readonly target: 'messages' | 'output_events' | 'idempotency_ledger' | 'subscription' | 'snapshot' | 'reply_preview' | 'provenance' | 'grant_state' | 'permission_matrix' | 'replay_events';
-    readonly assertion: 'unchanged' | 'none' | 'state_equals' | 'round_trip' | 'matches';
-    readonly value?: unknown;
+    readonly assertion: 'unchanged';
+    readonly value?: never;
+} | {
+    readonly target: 'messages' | 'output_events' | 'idempotency_ledger' | 'subscription' | 'snapshot' | 'reply_preview' | 'provenance' | 'grant_state' | 'permission_matrix' | 'replay_events';
+    readonly assertion: 'none';
+    readonly value?: never;
+} | {
+    readonly target: 'messages' | 'output_events' | 'idempotency_ledger' | 'subscription' | 'snapshot' | 'reply_preview' | 'provenance' | 'grant_state' | 'permission_matrix' | 'replay_events';
+    readonly assertion: 'state_equals';
+    readonly value: unknown;
+} | {
+    readonly target: 'messages' | 'output_events' | 'idempotency_ledger' | 'subscription' | 'snapshot' | 'reply_preview' | 'provenance' | 'grant_state' | 'permission_matrix' | 'replay_events';
+    readonly assertion: 'round_trip';
+    readonly value: unknown;
+} | {
+    readonly target: 'messages' | 'output_events' | 'idempotency_ledger' | 'subscription' | 'snapshot' | 'reply_preview' | 'provenance' | 'grant_state' | 'permission_matrix' | 'replay_events';
+    readonly assertion: 'matches';
+    readonly value: unknown;
 };
 export type ExpectedVerdict = {
-    readonly status: 'success' | 'error';
-    readonly errorCode?: MessagingErrorCode;
+    readonly status: 'success';
+    readonly errorCode?: never;
+    readonly sideEffects: readonly SideEffectAssertion[];
+} | {
+    readonly status: 'error';
+    readonly errorCode: MessagingErrorCode;
     readonly sideEffects: readonly SideEffectAssertion[];
 };
 export type BehaviorCase = {
     readonly id: string;
     readonly invariant: string;
+    readonly execution: Extract<BehaviorExecution, {
+        readonly plane: 'plugin-to-host-wire';
+    }> & {
+        readonly method: 'messaging.send';
+    } | Extract<BehaviorExecution, {
+        readonly plane: 'wire-admission';
+    }> & {
+        readonly method: 'messaging.send';
+    };
+    readonly given: FixtureSetup;
+    readonly when: Extract<FixtureOperation, {
+        readonly operation: 'send';
+    }>;
+    readonly expect: ExpectedVerdict;
+} | {
+    readonly id: string;
+    readonly invariant: string;
+    readonly execution: Extract<BehaviorExecution, {
+        readonly plane: 'plugin-to-host-wire';
+    }> & {
+        readonly method: 'messaging.appendElements';
+    } | Extract<BehaviorExecution, {
+        readonly plane: 'wire-admission';
+    }> & {
+        readonly method: 'messaging.appendElements';
+    };
+    readonly given: FixtureSetup;
+    readonly when: Extract<FixtureOperation, {
+        readonly operation: 'appendElements';
+    }>;
+    readonly expect: ExpectedVerdict;
+} | {
+    readonly id: string;
+    readonly invariant: string;
+    readonly execution: Extract<BehaviorExecution, {
+        readonly plane: 'plugin-to-host-wire';
+    }> & {
+        readonly method: 'messaging.subscribe';
+    } | Extract<BehaviorExecution, {
+        readonly plane: 'wire-admission';
+    }> & {
+        readonly method: 'messaging.subscribe';
+    };
+    readonly given: FixtureSetup;
+    readonly when: Extract<FixtureOperation, {
+        readonly operation: 'subscribe';
+    }>;
+    readonly expect: ExpectedVerdict;
+} | {
+    readonly id: string;
+    readonly invariant: string;
+    readonly execution: Extract<BehaviorExecution, {
+        readonly plane: 'plugin-to-host-wire';
+    }> & {
+        readonly method: 'messaging.read';
+    } | Extract<BehaviorExecution, {
+        readonly plane: 'wire-admission';
+    }> & {
+        readonly method: 'messaging.read';
+    };
+    readonly given: FixtureSetup;
+    readonly when: Extract<FixtureOperation, {
+        readonly operation: 'read';
+    }>;
+    readonly expect: ExpectedVerdict;
+} | {
+    readonly id: string;
+    readonly invariant: string;
+    readonly execution: Extract<BehaviorExecution, {
+        readonly plane: 'plugin-to-host-wire';
+    }> & {
+        readonly method: 'messaging.ack';
+    } | Extract<BehaviorExecution, {
+        readonly plane: 'wire-admission';
+    }> & {
+        readonly method: 'messaging.ack';
+    };
+    readonly given: FixtureSetup;
+    readonly when: Extract<FixtureOperation, {
+        readonly operation: 'ack';
+    }>;
+    readonly expect: ExpectedVerdict;
+} | {
+    readonly id: string;
+    readonly invariant: string;
+    readonly execution: Extract<BehaviorExecution, {
+        readonly plane: 'plugin-to-host-wire';
+    }> & {
+        readonly method: 'messaging.snapshot';
+    } | Extract<BehaviorExecution, {
+        readonly plane: 'wire-admission';
+    }> & {
+        readonly method: 'messaging.snapshot';
+    };
+    readonly given: FixtureSetup;
+    readonly when: Extract<FixtureOperation, {
+        readonly operation: 'snapshot';
+    }>;
+    readonly expect: ExpectedVerdict;
+} | {
+    readonly id: string;
+    readonly invariant: string;
+    readonly execution: Extract<BehaviorExecution, {
+        readonly plane: 'host-to-plugin-delivery';
+    }> & {
+        readonly method: 'host.messaging.deliver';
+    };
+    readonly given: FixtureSetup;
+    readonly when: Extract<FixtureOperation, {
+        readonly operation: 'deliverOnMessage';
+    }>;
+    readonly expect: ExpectedVerdict;
+} | {
+    readonly id: string;
+    readonly invariant: string;
+    readonly execution: Extract<BehaviorExecution, {
+        readonly plane: 'host-control';
+    }>;
     readonly given: FixtureSetup;
-    readonly when: FixtureOperation;
+    readonly when: Extract<FixtureOperation, {
+        readonly operation: 'applyGrantPreset' | 'revokeGrant' | 'checkPermissionMatrix' | 'deleteReplayEvents';
+    }>;
     readonly expect: ExpectedVerdict;
 };
 export type BehaviorFixture = {
@@ -400,6 +1366,12 @@ export declare const MESSAGING_BOUNDS: {
     readonly maxElementIdLength: 128;
     readonly maxElementsPerMessage: 128;
     readonly maxAppendOpsPerMessage: 64;
+    readonly maxMessageIdLength: 512;
+    readonly maxThreadIdLength: 512;
+    readonly maxActorIdLength: 512;
+    readonly maxMessageHandleTokenLength: 512;
+    readonly maxEventIdLength: 720;
+    readonly maxOccurredAtLength: 27;
 };
 /**
  * @signed(G-0 2026-07-15)