@joeybuilt/plexo-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1925 @@
+/**
+ * PEX — Context Layer Types
+ * Corresponds to §7.7 of the Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Push-based mechanism for extensions to contribute structured, prioritized
+ * context blocks injected into LLM system prompt at execution time.
+ */
+/**
+ * A context block contributed by an extension.
+ * Declared in the extension manifest's `contexts` array or registered at runtime.
+ */
+interface ContextArtifact {
+    /** Unique within the extension */
+    id: string;
+    /** Max 100 chars */
+    name: string;
+    /** Max 500 chars */
+    description: string;
+    /** Static text or {{variable}} template */
+    content: string;
+    /** MIME type; default: "text/plain" */
+    contentType?: string;
+    /** Injection priority */
+    priority: 'low' | 'normal' | 'high' | 'critical';
+    /** Seconds; undefined = no expiry */
+    ttl?: number;
+    /** Max 10, for discovery */
+    tags?: string[];
+    /** For budget allocation */
+    estimatedTokens?: number;
+}
+/**
+ * Registration payload passed to sdk.registerContext() during activate().
+ */
+interface ContextRegistration {
+    id: string;
+    name: string;
+    description: string;
+    content: string;
+    contentType?: string;
+    priority: 'low' | 'normal' | 'high' | 'critical';
+    ttl?: number;
+    tags?: string[];
+    estimatedTokens?: number;
+}
+/**
+ * Summary returned by sdk.context.list().
+ */
+interface ContextSummary {
+    id: string;
+    name: string;
+    description: string;
+    priority: 'low' | 'normal' | 'high' | 'critical';
+    ownerExtension: string;
+    enabled: boolean;
+    estimatedTokens?: number;
+    expired: boolean;
+}
+
+/**
+ * PEX — Prompt Library Types
+ * Corresponds to §7.6 of the Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Extension-contributed prompt templates that are versioned, discovered,
+ * and resolved across extensions. Host maps these to LLM prompt primitives
+ * at runtime.
+ */
+/**
+ * A prompt template contributed by an extension.
+ * Declared in the extension manifest's `prompts` array.
+ */
+interface PromptArtifact {
+    /** Unique within the extension */
+    id: string;
+    /** Max 100 chars */
+    name: string;
+    /** Max 500 chars */
+    description: string;
+    /** Template text with {{variable}} placeholders */
+    template: string;
+    /** Variables the host must resolve before injection */
+    variables?: PromptVariable[];
+    /** Max 10, for discovery */
+    tags?: string[];
+    /** Semver, independent of extension version */
+    version: string;
+    /** Injection priority */
+    priority?: 'low' | 'normal' | 'high' | 'critical';
+    /** Format: "context:<name>:<id>" */
+    dependencies?: string[];
+}
+/**
+ * A variable declared in a prompt template.
+ * Host resolves all required variables before injection.
+ */
+interface PromptVariable {
+    name: string;
+    description: string;
+    type: 'string' | 'number' | 'boolean' | 'enum';
+    /** Default: true */
+    required?: boolean;
+    default?: string | number | boolean;
+    enum?: string[];
+}
+/**
+ * Registration payload passed to sdk.registerPrompt() during activate().
+ */
+interface PromptRegistration {
+    id: string;
+    name: string;
+    description: string;
+    template: string;
+    variables?: PromptVariable[];
+    tags?: string[];
+    version: string;
+    priority?: 'low' | 'normal' | 'high' | 'critical';
+    dependencies?: string[];
+}
+/**
+ * Summary returned by sdk.prompts.list().
+ */
+interface PromptSummary {
+    id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+    version: string;
+    priority: 'low' | 'normal' | 'high' | 'critical';
+    ownerExtension: string;
+    enabled: boolean;
+}
+
+/**
+ * §17 — Extension Trust Tiers
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Tier     | Who                                      | Capability Ceiling
+ * ---------|------------------------------------------|------------------------------------
+ * owner    | Built and signed by the host operator    | Full: memory:read:*, audit:read,
+ *          |                                          | entity creation, model:override
+ * verified | Reviewed and signed by Plexo extension registry   | Standard caps, no wildcard memory,
+ *          |                                          | no audit access
+ * community| Unreviewed public extensions             | Restricted caps, explicit user
+ *          |                                          | approval per capability token
+ *
+ * Rules:
+ *   - Hosts MUST declare trust tier policy in their compliance declaration
+ *   - plexo.json MAY declare trust: 'owner' — host validates against signing key
+ *   - Capability tokens exceeding declared tier MUST be rejected at install, not runtime
+ */
+type TrustTier = 'owner' | 'verified' | 'community';
+interface TrustTierPolicy {
+    /** Default tier for extensions without explicit trust declaration */
+    defaultTier: TrustTier;
+    /** Whether the host enforces tier-based capability ceilings */
+    enforceTierCeilings: boolean;
+    /** Signing key fingerprint for owner-tier validation */
+    ownerSigningKeyId?: string;
+    /** Registry endpoint for verified-tier signature checks */
+    registryEndpoint?: string;
+}
+/**
+ * Capability ceilings per trust tier.
+ * Hosts use this to reject capabilities that exceed an extension's tier.
+ */
+interface TrustTierCeilings {
+    owner: {
+        allowWildcardMemory: true;
+        allowAuditRead: true;
+        allowEntityCreation: true;
+        allowModelOverride: true;
+    };
+    verified: {
+        allowWildcardMemory: false;
+        allowAuditRead: false;
+        allowEntityCreation: true;
+        allowModelOverride: false;
+    };
+    community: {
+        allowWildcardMemory: false;
+        allowAuditRead: false;
+        allowEntityCreation: false;
+        allowModelOverride: false;
+    };
+}
+
+/**
+ * §19 — Data Residency Declaration
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * All Extensions MUST declare external data destinations in their manifest.
+ *
+ * Rules:
+ *   - Extensions with sendsDataExternally: false making external HTTP calls
+ *     MUST be flagged non-compliant at runtime
+ *   - Hosts MAY enforce an allowlist of permitted external destinations
+ *   - Omitted dataResidency field treated as sendsDataExternally: true with
+ *     unknown destinations — blocked at Full compliance
+ *   - Declaration surfaced verbatim to users at install
+ */
+
+interface ExternalDestination {
+    /** Hostname of the external service */
+    host: string;
+    /** Human-readable purpose */
+    purpose: string;
+    /** Entity types sent to this destination */
+    dataTypes?: EntityTypeName[];
+}
+interface DataResidencyDeclaration {
+    sendsDataExternally: boolean;
+    externalDestinations?: ExternalDestination[];
+}
+
+/**
+ * §23 — Human Oversight & Escalation Contract
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * A formal escalation contract all Agent implementations MUST support.
+ * No formal spec for when an Agent must pause and request human approval
+ * is a critical governance gap for autonomous software touching email,
+ * calendar, and finances.
+ *
+ * Rules:
+ *   - Hosts MUST implement at minimum IRREVERSIBLE_ACTION and CAPABILITY_EXPANSION triggers
+ *   - Extensions MUST NOT bypass escalation by splitting irreversible actions
+ *     into smaller reversible steps — host detects composite irreversibility
+ *   - Standing approval rules are user-owned — Extensions cannot create or modify them
+ *   - Escalation timeout: no user response within configured window → action denied and logged
+ */
+type EscalationTrigger = 'HIGH_VALUE_ACTION' | 'IRREVERSIBLE_ACTION' | 'NOVEL_PATTERN' | 'CONFIDENCE_BELOW' | 'CROSS_BOUNDARY' | 'CAPABILITY_EXPANSION';
+interface EscalationRequest {
+    trigger: EscalationTrigger;
+    /** The action the agent wants to take */
+    action: string;
+    /** Relevant context for the user to make a decision */
+    context: unknown;
+    /** Agent's recommendation (approve/deny) with reasoning */
+    recommendation?: {
+        decision: 'approve' | 'deny';
+        reasoning: string;
+    };
+}
+type EscalationUserResponse = 'approve' | 'deny' | 'approve-and-remember';
+interface EscalationResult {
+    response: EscalationUserResponse;
+    /** User-provided feedback or instructions */
+    feedback?: string;
+    /** Timestamp of user response */
+    respondedAt: string;
+}
+interface StandingApproval {
+    id: string;
+    /** The trigger type this approval covers */
+    trigger: EscalationTrigger;
+    /** Pattern matching for the action (e.g. 'channel:send to @internal/*') */
+    actionPattern: string;
+    /** Who created this rule */
+    createdBy: 'user';
+    createdAt: string;
+    /** Optional expiration */
+    expiresAt?: string;
+}
+interface EscalationDeclaration {
+    /** Actions this extension considers irreversible */
+    irreversibleActions?: string[];
+    /** Whether this extension requests standing approval capability */
+    requestsStandingApprovals?: boolean;
+}
+
+/**
+ * §24 — LLM Identity & Model Context
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * When an Agent acts, the LLM powering it must be visible to the audit trail,
+ * the user, and the system. Different models produce different decisions from
+ * the same Agent — making logs incomplete, behavior non-reproducible, and
+ * user consent uninformed.
+ *
+ * Rules:
+ *   - If localModelAcceptable: false and host resolves to a cloud provider,
+ *     the Agent's dataResidency MUST list that provider as an external destination
+ *   - If host policy prohibits external model calls, Agents declaring
+ *     localModelAcceptable: false MUST be rejected at install
+ *   - Hosts MUST surface which model powers each active Agent in admin UI
+ *   - Model changes require user re-acknowledgment for Agents with
+ *     IRREVERSIBLE_ACTION escalation triggers
+ *   - Capability token: model:override — required for Agents that dynamically
+ *     select their own model at runtime
+ */
+interface ModelRequirements {
+    minimumContextWindow?: number;
+    requiresFunctionCalling?: boolean;
+    localModelAcceptable?: boolean;
+    prohibitedProviders?: string[];
+    preferredProviders?: string[];
+}
+interface ModelContextEntry {
+    /** e.g. 'claude-sonnet-4-5', 'llama-3.3-70b' */
+    modelId: string;
+    /** Exact version or hash if self-hosted */
+    modelVersion?: string;
+    /** e.g. 'anthropic', 'openai', 'ollama', 'self-hosted' */
+    modelProvider: string;
+    /** true if on-host, false if external API */
+    isLocal: boolean;
+    /** Tokens used in this call */
+    contextWindowUsed?: number;
+}
+
+/**
+ * Extension subtypes — filter badges in host UI.
+ * 'skill'       — composite capability package (registers tools, schedules, widgets)
+ * 'channel'     — messaging bridge (inbound/outbound)
+ * 'tool'        — stateless, single-purpose, called on demand
+ * 'connector'   — bridges an external MCP server (formerly 'mcp-server')
+ */
+type ExtensionSubtype = 'skill' | 'channel' | 'tool' | 'connector';
+/**
+ * The manifest type field — covers both Extensions and Agents.
+ * Agent is a separate pillar but shares the manifest format.
+ */
+type ManifestType = ExtensionSubtype | 'agent';
+/**
+ * @deprecated Use ManifestType instead. Kept for backwards compatibility with pre-0.4.0 manifests.
+ */
+type ExtensionType = ManifestType | 'function' | 'mcp-server';
+/** Personal entity types defined in §16 */
+type EntityTypeName = 'person' | 'task' | 'thread' | 'note' | 'transaction' | 'calendar_event' | 'file';
+/**
+ * Capability tokens an extension or agent declares in its manifest.
+ *
+ * Memory capabilities are now entity-scoped (§4 edit):
+ *   memory:read:<entity_type>    — read access to a specific entity type
+ *   memory:write:<entity_type>   — write access to a specific entity type
+ *
+ * Unscoped memory:read / memory:write are DEPRECATED at Standard + Full compliance.
+ * memory:read:* wildcard is allowed only at trust tier: owner.
+ */
+type CapabilityToken = `memory:read:${EntityTypeName}` | `memory:write:${EntityTypeName}` | 'memory:read:*' | 'memory:write:*' | 'memory:read' | 'memory:write' | 'memory:delete' | 'channel:send' | 'channel:send-direct' | 'channel:receive' | 'schedule:register' | 'schedule:manage' | 'ui:register-widget' | 'ui:notify' | 'tasks:create' | 'tasks:read' | 'tasks:read-all' | 'events:subscribe' | 'events:publish' | 'storage:read' | 'storage:write' | 'prompts:register' | 'prompts:read' | 'context:register' | 'context:write' | 'context:read' | `connections:${string}` | `host:${string}:${string}` | 'self:read' | 'self:write' | 'audit:read' | 'identity:present' | 'a2a:delegate' | 'model:override' | `entity:create:${EntityTypeName}` | `entity:modify:${EntityTypeName}` | `entity:delete:${EntityTypeName}`;
+type HostComplianceLevel = 'core' | 'standard' | 'full';
+interface MCPServerConfig {
+    transport: 'stdio' | 'sse';
+    /** Required when transport is 'stdio' */
+    command?: string;
+    /** Required when transport is 'sse' */
+    url?: string;
+}
+interface AgentHints {
+    taskTypes?: string[];
+    minConfidence?: number;
+}
+interface ResourceHints {
+    maxMemoryMB?: number;
+    maxCpuShares?: number;
+    maxInvocationMs?: number;
+}
+interface JSONSchema {
+    type: string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    items?: JSONSchema;
+    [key: string]: unknown;
+}
+interface BehaviorRuleDefinition {
+    key: string;
+    label: string;
+    description: string;
+    type: 'safety_constraint' | 'operational_rule' | 'communication_style' | 'domain_knowledge' | 'persona_trait' | 'tool_preference' | 'quality_gate';
+    defaultValue: {
+        type: 'boolean' | 'string' | 'number' | 'enum' | 'text_block' | 'json';
+        value: unknown;
+        options?: string[];
+        min?: number;
+        max?: number;
+    };
+    locked: boolean;
+}
+/**
+ * The Plexo extension manifest — shared by both Extensions and Agents.
+ *
+ * v0.4.0 additions:
+ *   - prompts / contexts (§7.6, §7.7)
+ *   - 'connector' type (replaces 'mcp-server')
+ *   - 5-type model (agent, skill, channel, tool, connector)
+ *
+ * v0.3.0 additions:
+ *   - trust          (§17)
+ *   - dataResidency  (§19)
+ *   - escalation     (§23)
+ *   - modelRequirements (§24)
+ *   - did            (§21)
+ */
+interface ExtensionManifest {
+    /** PEX spec version this manifest targets. Must be valid semver. */
+    plexo: string;
+    /** Scoped package name. Must match @scope/name format. */
+    name: string;
+    /** Extension or Agent version. Must be valid semver. */
+    version: string;
+    /** Manifest type — 'function' | 'channel' | 'mcp-server' for Extensions, 'agent' for Agents. */
+    type: ManifestType;
+    /** Relative path to entry point from package root. */
+    entry: string;
+    /** Capability tokens this extension or agent requires. */
+    capabilities: CapabilityToken[];
+    /** Human-readable name shown in host UI and registry. Max 50 chars. */
+    displayName: string;
+    /** Short description. Max 280 characters. */
+    description: string;
+    /** Publisher name or organization. */
+    author: string;
+    /** SPDX license identifier. */
+    license: string;
+    minHostLevel?: HostComplianceLevel;
+    minPexVersion?: string;
+    homepage?: string;
+    repository?: string;
+    keywords?: string[];
+    icon?: string;
+    screenshots?: string[];
+    /** For connector type extensions (bridges an MCP server). */
+    mcpServer?: MCPServerConfig;
+    /** For agent type only. */
+    agentHints?: AgentHints;
+    /** For channel type only. Rendered as setup form. */
+    channelConfig?: JSONSchema;
+    /**
+     * Channel transport mode (channel type only).
+     *   'worker' — extension runs in a sandboxed worker with a channel adapter (default)
+     *   'api'    — the app uses Plexo's chat API for transport; no worker needed
+     */
+    channelTransport?: 'worker' | 'api';
+    /** For skill type only. Rendered as settings form. */
+    skillConfig?: JSONSchema;
+    /** For tool type only. Rendered as settings form. */
+    toolConfig?: JSONSchema;
+    resourceHints?: ResourceHints;
+    peerExtensions?: string[];
+    behaviorRules?: BehaviorRuleDefinition[];
+    /** §7.6 — Prompt templates contributed by this extension. */
+    prompts?: PromptArtifact[];
+    /** §7.7 — Context blocks contributed by this extension. */
+    contexts?: ContextArtifact[];
+    /** §7.7 — Context dependencies required by this extension. */
+    contextDependencies?: string[];
+    /**
+     * §3.3 — Per-capability human-readable rationale surfaced in the install dialog.
+     *
+     * Keys MUST be entries in `capabilities[]`. Values are short (max 200 chars)
+     * plain-text explanations shown to the user alongside each requested capability
+     * so they can judge whether the request is appropriate.
+     *
+     * Enforcement:
+     *   - `trust: 'owner' | 'verified'` — REQUIRED. Publish is rejected if any
+     *     declared capability is missing a rationale entry (warning entries for
+     *     universally-safe caps like `storage:read` are tolerated; see validator).
+     *   - `trust: 'community'` — optional but strongly encouraged. UI renders a
+     *     "no explanation provided" warning per capability without one.
+     *   - `trust: 'local'` (sideload) — optional, never enforced.
+     */
+    capabilitiesRationale?: Record<string, string>;
+    /** §17 — Trust tier declaration. Host validates against signing key. */
+    trust?: TrustTier;
+    /** §19 — Data residency declaration. External data destinations. */
+    dataResidency?: DataResidencyDeclaration;
+    /** §21 — W3C Decentralized Identifier for cross-host identity. */
+    did?: string;
+    /** §23 — Escalation contract for human oversight. */
+    escalation?: EscalationDeclaration;
+    /** §24 — LLM model requirements for agent-type manifests. */
+    modelRequirements?: ModelRequirements;
+    /**
+     * @deprecated Use skillConfig instead. Kept for backwards compatibility with pre-0.4.0 manifests.
+     */
+    functionConfig?: JSONSchema;
+}
+/**
+ * An Agent Stack is a pre-configured Agent + Extension bundle.
+ * Hosts SHOULD surface these as saveable, nameable presets.
+ */
+interface AgentStackManifest {
+    /** PEX spec version. */
+    plexo: string;
+    /** Scoped package name for the stack. */
+    name: string;
+    version: string;
+    displayName: string;
+    description: string;
+    author: string;
+    license: string;
+    /** The Agent manifest name this stack configures. */
+    agent: string;
+    /** Extension manifest names this Agent should load. */
+    extensions: string[];
+    /** Connection service identifiers required by this stack. */
+    connections: string[];
+    /** Optional pre-configured behavior rules for the Agent. */
+    behaviorOverrides?: Record<string, unknown>;
+}
+
+/**
+ * §16 — Personal Entity Schema
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Standard first-class personal entity types all PEX-compatible hosts
+ * must support. When multiple Extensions reference the same person, task,
+ * or thread, entity resolution prevents fragmentation.
+ *
+ * Rules:
+ *   - Entity IDs are host-scoped UUIDs, stable across sessions
+ *   - Extensions reference entities by ID — no duplicating entity data
+ *   - Hosts MUST provide a resolution API: entities.resolve(type, id)
+ *     and entities.search(type, query)
+ *   - Extensions MAY create new entities with entity:create:<type> capability
+ *   - Cross-entity linking uses linkedEntities[] — a typed reference array
+ */
+
+interface LinkedEntity {
+    type: EntityTypeName;
+    id: string;
+}
+interface PersonEntity {
+    id: string;
+    name: string;
+    email?: string[];
+    phone?: string[];
+    tags?: string[];
+    source?: string;
+    linkedEntities?: LinkedEntity[];
+}
+interface TaskEntity {
+    id: string;
+    title: string;
+    status: string;
+    due?: string;
+    assignee?: string;
+    tags?: string[];
+    linkedEntities?: LinkedEntity[];
+}
+interface ThreadEntity {
+    id: string;
+    participants: string[];
+    subject?: string;
+    channel?: string;
+    lastActivity?: string;
+    linkedEntities?: LinkedEntity[];
+}
+interface NoteEntity {
+    id: string;
+    body: string;
+    tags?: string[];
+    createdAt: string;
+    linkedEntities?: LinkedEntity[];
+}
+interface TransactionEntity {
+    id: string;
+    amount: number;
+    currency: string;
+    direction: 'inbound' | 'outbound';
+    merchant?: string;
+    category?: string;
+    date: string;
+    tags?: string[];
+    linkedEntities?: LinkedEntity[];
+}
+interface CalendarEventEntity {
+    id: string;
+    title: string;
+    start: string;
+    end: string;
+    attendees?: string[];
+    location?: string;
+    tags?: string[];
+    linkedEntities?: LinkedEntity[];
+}
+interface FileEntity {
+    id: string;
+    name: string;
+    type: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    capturedAt?: string;
+    source?: string;
+    tags?: string[];
+    storageUri?: string;
+    checksum?: string;
+    linkedEntities?: LinkedEntity[];
+}
+type PlexoEntity = PersonEntity | TaskEntity | ThreadEntity | NoteEntity | TransactionEntity | CalendarEventEntity | FileEntity;
+/** Maps entity type names to their TypeScript interfaces */
+interface EntityTypeMap {
+    person: PersonEntity;
+    task: TaskEntity;
+    thread: ThreadEntity;
+    note: NoteEntity;
+    transaction: TransactionEntity;
+    calendar_event: CalendarEventEntity;
+    file: FileEntity;
+}
+interface EntitySearchQuery {
+    text?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+}
+interface EntitySearchResult<T extends PlexoEntity = PlexoEntity> {
+    entities: T[];
+    total: number;
+    hasMore: boolean;
+}
+
+/**
+ * §20 — Persistent UserSelf
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * A host-managed UserSelf graph readable by owner and verified Extensions
+ * with field-level scoping. Persists across sessions and survives Extension uninstall.
+ *
+ * Rules:
+ *   - UserSelf is host-owned — no Extension owns it
+ *   - Extensions contribute via structured proposals: self.propose(...)
+ *   - Host resolves conflicts (last-write, confidence-weighted, or user-confirmed)
+ *   - Extensions read via self.read(fields[]) — field-level scoping
+ *   - Capability tokens: self:read, self:write
+ *   - Agents read UserSelf to personalize behavior across all their loaded Extensions
+ */
+interface UserIdentity {
+    name?: string;
+    timezone?: string;
+    locale?: string;
+    primaryEmail?: string;
+}
+interface UserCommunicationStyle {
+    formality?: 'casual' | 'neutral' | 'formal';
+    verbosity?: 'concise' | 'moderate' | 'detailed';
+    preferredChannels?: string[];
+}
+interface UserContext {
+    summary: string;
+    lastUpdated: string;
+}
+type UserSelfField = 'identity' | 'preferences' | 'relationships' | 'contexts' | 'communicationStyle';
+interface UserSelf {
+    identity: UserIdentity;
+    /** Extensible, typed key-value preferences */
+    preferences: Record<string, unknown>;
+    /** Person entity IDs, ranked by recency/frequency */
+    relationships: string[];
+    /** Named contexts: work, finance, health, etc. */
+    contexts: Record<string, UserContext>;
+    communicationStyle: UserCommunicationStyle;
+}
+interface UserSelfProposal {
+    field: UserSelfField;
+    /** Dot-path within the field, e.g. 'identity.timezone' */
+    path?: string;
+    value: unknown;
+    /** Extension proposing this change */
+    source: string;
+    /** 0–1 confidence in the proposed value */
+    confidence: number;
+}
+type UserSelfConflictResolution = 'last-write' | 'confidence-weighted' | 'user-confirmed';
+
+/**
+ * §18 — Audit Trail Requirement
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Standard and Full compliance hosts MUST maintain an immutable audit ledger
+ * per Extension per session. Trust in autonomous behavior requires verifiability.
+ *
+ * Rules:
+ *   - audit:read capability required for owner-tier Extensions to query the ledger
+ *   - Ledger entries MUST be immutable — no Extension modifies or deletes its own trail
+ *   - Hosts MUST surface audit logs in admin UI
+ *   - Audit log data residency follows host's declared policy (§19)
+ */
+
+type AuditAction = 'function_invoked' | 'memory_read' | 'memory_write' | 'channel_send' | 'schedule_fired' | 'entity_created' | 'entity_modified' | 'external_request' | 'escalation_triggered' | 'escalation_resolved';
+type AuditOutcome = 'success' | 'failure' | 'denied';
+type EscalationOutcome = 'approve' | 'deny' | 'approve-and-remember';
+interface AuditEntry {
+    extensionId: string;
+    /** Which Agent invoked this Extension, if any */
+    agentId?: string;
+    sessionId: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    action: AuditAction;
+    /** Entity ID, function name, channel, or external URL */
+    target: string;
+    /** SHA-256 of input — not plaintext */
+    payloadHash: string;
+    outcome: AuditOutcome;
+    /** §24 — LLM model context for this action */
+    modelContext?: ModelContextEntry;
+    /** Escalation outcome if applicable */
+    escalationOutcome?: EscalationOutcome;
+}
+interface AuditQuery {
+    extensionId?: string;
+    agentId?: string;
+    sessionId?: string;
+    action?: AuditAction;
+    outcome?: AuditOutcome;
+    /** ISO 8601 range start */
+    from?: string;
+    /** ISO 8601 range end */
+    to?: string;
+    limit?: number;
+    offset?: number;
+}
+interface AuditQueryResult {
+    entries: AuditEntry[];
+    total: number;
+    hasMore: boolean;
+}
+
+/**
+ * §22 — A2A Bridge Layer
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Full compliance hosts MUST expose an A2A-compatible endpoint for each Agent,
+ * enabling external A2A clients to discover and invoke Plexo Agents as remote agents.
+ *
+ * Protocol stack:
+ *   MCP    : agent ↔ tool (already supported via MCP Server Extension type)
+ *   A2A    : agent ↔ agent (this section)
+ *   PEX : defines how all of the above is packaged, permissioned, isolated, and managed
+ *
+ * Rules:
+ *   - External agents treated as community trust tier unless presenting a VC elevating trust
+ *   - Inbound tasks route through host's Task Router — same isolation and enforcement
+ *   - Delegated tasks logged in audit trail with external agent's DID or endpoint
+ *   - Requires a2a:delegate capability token for outbound delegation
+ */
+/**
+ * A2A Agent Card generated from a Plexo Agent manifest.
+ * Conforms to the A2A (Agentic AI Foundation) Agent Card specification.
+ */
+interface A2AAgentCard {
+    name: string;
+    description: string;
+    version: string;
+    /** A2A endpoint URL: https://host/a2a/agents/:id */
+    endpoint: string;
+    capabilities: Record<string, unknown>;
+    authentication: {
+        schemes: ('oauth2' | 'did' | 'api_key')[];
+    };
+    /** Plexo DID for this agent, if assigned */
+    plexoDID?: string;
+}
+/**
+ * A2A Task — represents work delegated between agents.
+ */
+interface A2ATask {
+    id: string;
+    /** Human-readable task description */
+    description: string;
+    /** Structured input data */
+    input: unknown;
+    /** Expected output schema, if known */
+    expectedOutput?: Record<string, unknown>;
+}
+type A2ATaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+interface A2ATaskResult {
+    taskId: string;
+    status: A2ATaskStatus;
+    output?: unknown;
+    error?: string;
+}
+/**
+ * Inbound A2A request — external agent invoking a Plexo Agent.
+ */
+interface A2AInboundRequest {
+    /** A2A Agent Card of the requesting agent */
+    sourceAgent: A2AAgentCard;
+    task: A2ATask;
+    /** Verifiable credential if presenting elevated trust */
+    credential?: unknown;
+}
+/**
+ * Outbound A2A delegation — Plexo Agent delegating to an external A2A agent.
+ * Requires a2a:delegate capability.
+ */
+interface A2ADelegation {
+    /** A2A endpoint of the target agent */
+    targetEndpoint: string;
+    task: A2ATask;
+    /** Timeout in milliseconds for the delegated task */
+    timeoutMs?: number;
+}
+
+/**
+ * Plexo SDK Interface
+ * The complete API available to extensions and agents via the sdk parameter in activate()
+ * Corresponds to Appendix A of the Plexo Extension Protocol (PEX) Specification v0.4.0
+ */
+
+type NotificationLevel = 'info' | 'warning' | 'error';
+type ExtensionName = `@${string}/${string}`;
+interface HostInfo {
+    pexVersion: string;
+    complianceLevel: HostComplianceLevel;
+    name: string;
+    version: string;
+    capabilities?: {
+        prompts?: boolean;
+        context?: boolean;
+        tokenBudgeting?: boolean;
+    };
+}
+interface MemoryEntry {
+    id: string;
+    content: string;
+    tags?: string[];
+    authorExtension: ExtensionName | 'host';
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+    ttl?: number;
+    /** §16 — Entity type this memory entry relates to, if any */
+    entityType?: EntityTypeName;
+    /** §16 — Entity ID this memory entry relates to, if any */
+    entityId?: string;
+}
+interface ConnectionCredentials {
+    type: 'api_key' | 'oauth2' | 'basic' | 'webhook';
+    data: Record<string, string>;
+}
+interface ScheduleRegistration {
+    name: string;
+    /** 5-field cron expression */
+    schedule: string;
+    /** IANA timezone string. Defaults to 'UTC'. */
+    timezone?: string;
+    handler(): Promise<void>;
+}
+interface WidgetRegistration {
+    name: string;
+    displayName: string;
+    displayType: 'metric' | 'chart' | 'list' | 'status' | 'custom';
+    /** Refresh interval in seconds */
+    refreshInterval: number;
+    dataHandler(config: unknown): Promise<unknown>;
+}
+interface ToolRegistration {
+    /** Alphanumeric and underscores. Unique within the extension. */
+    name: string;
+    /** Max 500 characters. Shown to agents. */
+    description: string;
+    /** Must be type "object" at top level. */
+    parameters: JSONSchema;
+    hints?: {
+        estimatedMs?: number;
+        /** Hard timeout in ms. Host will abort if exceeded. Defaults to 30_000. */
+        timeoutMs?: number;
+        hasSideEffects?: boolean;
+        idempotent?: boolean;
+    };
+    handler(params: unknown, context: InvokeContext): Promise<unknown>;
+}
+interface InvokeContext {
+    workspaceId: string;
+    taskId?: string;
+    requestId: string;
+    /** Better Auth tenant identifier (multi-tenant scoping). */
+    tenantId: string;
+    /** Authenticated user the invocation is acting on behalf of. */
+    userId: string;
+    /** ADR-09 — per-tool OAuth account override (optional). */
+    accountId?: string;
+    /** Conversation continuity identifier across multi-turn flows (optional). */
+    sessionId?: string;
+    /** ADR-04 — links to run_id for cross-system tracing. */
+    traceId: string;
+}
+interface ToolSummary {
+    name: string;
+    description: string;
+    ownerExtension: string;
+}
+interface TaskCreateOptions {
+    title: string;
+    type: string;
+    context?: unknown;
+}
+interface TaskFilter {
+    status?: string;
+    type?: string;
+}
+/**
+ * The complete Plexo SDK interface.
+ * All extension and agent types receive this in their activate() call.
+ * Methods only work if the corresponding capability is declared in plexo.json.
+ *
+ * v0.4.0 additions:
+ *   - registerPrompt / registerContext (§7.6, §7.7)
+ *   - prompts.*     (§7.6 — Prompt Library)
+ *   - context.*     (§7.7 — Context Layer)
+ *
+ * v0.3.0 additions:
+ *   - entities.*    (§16 — Personal Entity Schema)
+ *   - self.*        (§20 — Persistent UserSelf)
+ *   - audit.*       (§18 — Audit Trail)
+ *   - escalate()    (§23 — Escalation Contract)
+ *   - a2a.*         (§22 — A2A Bridge Layer)
+ */
+interface PlexoSDK {
+    /** Information about the host runtime */
+    host: HostInfo;
+    /**
+     * Registration methods. Only valid during activate().
+     * Calling after activation completes is a no-op with a warning.
+     */
+    registerTool(tool: ToolRegistration): void;
+    registerSchedule(job: ScheduleRegistration): void;
+    registerWidget(widget: WidgetRegistration): void;
+    /** §7.6 — Requires prompts:register */
+    registerPrompt(prompt: PromptRegistration): void;
+    /** §7.7 — Requires context:register */
+    registerContext(context: ContextRegistration): void;
+    memory: {
+        /** Requires memory:read or memory:read:<entity_type> */
+        read(query: string, options?: {
+            tags?: string[];
+            limit?: number;
+            /** §16 — Filter to a specific entity type */
+            entityType?: EntityTypeName;
+        }): Promise<MemoryEntry[]>;
+        /** Requires memory:write or memory:write:<entity_type> */
+        write(entry: {
+            content: string;
+            tags?: string[];
+            metadata?: Record<string, unknown>;
+            ttl?: number;
+            /** §16 — Associate with an entity type */
+            entityType?: EntityTypeName;
+            /** §16 — Associate with an entity ID */
+            entityId?: string;
+        }): Promise<MemoryEntry>;
+        /** Requires memory:delete */
+        delete(id: string): Promise<void>;
+    };
+    entities: {
+        /**
+         * Resolve a single entity by type and ID.
+         * Requires memory:read:<entity_type>
+         */
+        resolve<T extends EntityTypeName>(type: T, id: string): Promise<EntityTypeMap[T] | null>;
+        /**
+         * Search for entities of a given type.
+         * Requires memory:read:<entity_type>
+         */
+        search<T extends EntityTypeName>(type: T, query: EntitySearchQuery): Promise<EntitySearchResult<EntityTypeMap[T]>>;
+        /**
+         * Create a new entity.
+         * Requires entity:create:<entity_type>
+         */
+        create<T extends EntityTypeName>(type: T, data: Omit<EntityTypeMap[T], 'id'>): Promise<EntityTypeMap[T]>;
+        /**
+         * Link two entities together.
+         * Requires entity:modify:<entity_type> for the source entity.
+         */
+        link(source: {
+            type: EntityTypeName;
+            id: string;
+        }, target: LinkedEntity): Promise<void>;
+    };
+    connections: {
+        /** Requires connections:<service> */
+        getCredentials(service: string): Promise<ConnectionCredentials>;
+        isConnected(service: string): Promise<boolean>;
+    };
+    channel: {
+        /** Requires channel:send */
+        send(message: {
+            text: string;
+            priority?: 'normal' | 'high' | 'urgent';
+            attachments?: unknown[];
+        }): Promise<void>;
+        /** Requires channel:send-direct */
+        sendDirect(channelId: string, message: unknown): Promise<void>;
+        /**
+         * §9 — Multi-channel dispatch with idempotency (ADR-15) and per-tool scope override.
+         * Requires channel:dispatch.
+         * `channel` is one of: 'telegram' | 'email' | 'push' | 'sms'.
+         * `idempotencyKey` MUST be unique per logical send; same key returns the prior result.
+         * `scopeOverrides` narrows OAuth scopes for this dispatch (ADR-09).
+         */
+        dispatch(params: {
+            channel: string;
+            recipientUserId: string;
+            message: {
+                text: string;
+                attachments?: unknown[];
+                metadata?: Record<string, unknown>;
+            };
+            idempotencyKey: string;
+            scopeOverrides?: string[];
+        }): Promise<{
+            messageId?: string;
+            deliveryStatus?: string;
+        }>;
+    };
+    tasks: {
+        /** Requires tasks:create (agent type only) */
+        create(options: TaskCreateOptions): Promise<{
+            taskId: string;
+        }>;
+        /** Requires tasks:read */
+        get(taskId: string): Promise<unknown>;
+        /** Requires tasks:read-all */
+        list(filter?: TaskFilter): Promise<unknown[]>;
+    };
+    events: {
+        /** Requires events:subscribe */
+        subscribe(topic: string, handler: (payload: unknown) => void): void;
+        /** Requires events:publish — namespace enforced to ext.<scope>.* */
+        publish(topic: string, payload: unknown): Promise<void>;
+    };
+    storage: {
+        /** Requires storage:read */
+        get(key: string): Promise<string | null>;
+        /** Requires storage:write */
+        set(key: string, value: string, options?: {
+            ttlSeconds?: number;
+        }): Promise<void>;
+        /** Requires storage:write */
+        delete(key: string): Promise<void>;
+    };
+    ui: {
+        /** Requires ui:notify */
+        notify(message: string, level?: NotificationLevel): Promise<void>;
+    };
+    self: {
+        /** Requires self:read — field-level scoping */
+        read(fields: UserSelfField[]): Promise<Partial<UserSelf>>;
+        /** Requires self:write — contribute via structured proposals */
+        propose(proposal: UserSelfProposal): Promise<void>;
+    };
+    audit: {
+        /** Requires audit:read — query the immutable audit ledger */
+        query(query: AuditQuery): Promise<AuditQueryResult>;
+    };
+    /**
+     * Signal that the agent needs human approval before proceeding.
+     * Host pauses execution, notifies user, and returns the result.
+     * Requires agent type.
+     */
+    escalate(request: EscalationRequest): Promise<EscalationResult>;
+    a2a: {
+        /**
+         * Discover external A2A agents by endpoint.
+         * Requires a2a:delegate
+         */
+        discover(endpoint: string): Promise<A2AAgentCard | null>;
+        /**
+         * Delegate a task to an external A2A agent.
+         * Requires a2a:delegate. Logged in audit trail.
+         */
+        delegate(delegation: A2ADelegation): Promise<A2ATaskResult>;
+    };
+    prompts: {
+        /** Requires prompts:read */
+        list(options?: {
+            tags?: string[];
+        }): Promise<PromptSummary[]>;
+        /** Requires prompts:read — resolve template with variables */
+        resolve(promptId: string, variables?: Record<string, unknown>): Promise<string>;
+    };
+    context: {
+        /** Requires context:write — update content for a registered context block */
+        update(contextId: string, content: string, options?: {
+            ttl?: number;
+            estimatedTokens?: number;
+        }): Promise<void>;
+        /** Requires context:read */
+        list(): Promise<ContextSummary[]>;
+    };
+}
+
+/**
+ * PEX Message Protocol Types
+ * Corresponds to §6 of the Plexo Extension Protocol (PEX) Specification v0.4.0
+ */
+type MessageType = 'invoke' | 'invoke_result' | 'event' | 'channel_message' | 'channel_send' | 'channel_health_check' | 'channel_health_result' | 'activate' | 'deactivate' | 'error' | 'escalation_request' | 'escalation_response' | 'entity_resolve' | 'entity_resolve_result' | 'a2a_inbound' | 'a2a_outbound' | 'self_read' | 'self_propose' | 'audit_query';
+type ErrorCode = 'CAPABILITY_DENIED' | 'TOOL_NOT_FOUND' | 'TIMEOUT' | 'INTERNAL_ERROR' | 'INVALID_PARAMS' | 'COMPLIANCE_INSUFFICIENT' | 'NOT_IMPLEMENTED' | 'EXTENSION_CRASHED' | 'TRUST_TIER_EXCEEDED' | 'DATA_RESIDENCY_VIOLATION' | 'ESCALATION_DENIED' | 'ESCALATION_TIMEOUT' | 'ENTITY_NOT_FOUND' | 'DID_VERIFICATION_FAILED' | 'MODEL_REQUIREMENTS_UNMET' | 'SCOPED_MEMORY_REQUIRED';
+interface PexMessage {
+    /** PEX spec version */
+    plexo: '0.4.0';
+    /** Unique message ID */
+    id: string;
+    type: MessageType;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    payload: unknown;
+}
+interface PexError {
+    code: ErrorCode;
+    message: string;
+    /** Original error detail — stripped in production */
+    detail?: string;
+    retryable: boolean;
+}
+type MessagePriority = 'normal' | 'high' | 'urgent';
+interface Attachment {
+    type: 'image' | 'file' | 'link';
+    url: string;
+    name?: string;
+    mimeType?: string;
+}
+interface InboundMessage {
+    id: string;
+    channelId: string;
+    senderId: string;
+    text: string;
+    priority: MessagePriority;
+    attachments?: Attachment[];
+    replyToId?: string;
+    timestamp: string;
+}
+
+/**
+ * PEX Agent Contract Types
+ * Corresponds to §8 of the Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * An Agent is NOT a subtype of Extension. An Agent is an autonomous actor
+ * with a goal, a planning loop, and an identity. It orchestrates any number
+ * of Extensions to accomplish work.
+ *
+ * §23 integration: Agents MUST implement escalate() for human oversight.
+ * §22 integration: Agents MAY delegate to external A2A agents.
+ * §24 integration: Agent actions are logged with model context in the audit trail.
+ */
+
+type OneWayDoorType = 'irreversible_action' | 'external_write' | 'financial_transaction' | 'data_deletion' | 'permission_escalation';
+interface OneWayDoor {
+    type: OneWayDoorType;
+    description: string;
+    /** What the agent intends to do */
+    action: string;
+    /** What happens if user approves */
+    consequence: string;
+    /** Whether this can be undone */
+    reversible: false;
+}
+type EscalationReason = 'ambiguous_goal' | 'one_way_door' | 'low_confidence' | 'missing_capability' | 'recovery_needed' | 'max_retries_exceeded' | 'high_value_action' | 'irreversible_action' | 'novel_pattern' | 'confidence_below_threshold' | 'cross_boundary' | 'capability_expansion';
+interface ToolCall {
+    tool: string;
+    params: Record<string, unknown>;
+}
+interface PlanStep {
+    id: string;
+    description: string;
+    toolCall?: ToolCall;
+    /** If true, requires approval before execution */
+    oneWayDoor?: OneWayDoor;
+    dependsOn?: string[];
+    /** §23 — Escalation trigger type, if this step requires escalation */
+    escalationTrigger?: EscalationTrigger;
+}
+interface Plan {
+    steps: PlanStep[];
+    /** Estimated total duration in seconds */
+    estimatedSeconds?: number;
+    confidence: number;
+}
+interface StepResult {
+    stepId: string;
+    ok: boolean;
+    output?: unknown;
+    error?: string;
+    durationMs: number;
+}
+interface ShouldActivateResult {
+    activate: boolean;
+    confidence: number;
+    reasoning?: string;
+}
+interface EscalationResponse {
+    approved: boolean;
+    feedback?: string;
+}
+interface AgentExtension {
+    /**
+     * Called for every new task. Return { activate: true, confidence: 0–1 }
+     * to claim the task. Host routes to highest-confidence claimant.
+     */
+    shouldActivate(task: {
+        title: string;
+        type: string;
+        context?: unknown;
+    }): Promise<ShouldActivateResult>;
+    /**
+     * Called if agent wins the routing competition.
+     * Must return a plan — array of steps to execute.
+     */
+    plan(task: {
+        title: string;
+        type: string;
+        context?: unknown;
+    }): Promise<Plan>;
+    /**
+     * Called once per step by the host executor.
+     */
+    executeStep(step: PlanStep, context: {
+        workspaceId: string;
+        taskId: string;
+    }): Promise<StepResult>;
+    /**
+     * Called after each step. Return { ok: true } to continue, { ok: false } to escalate.
+     */
+    verifyStep(result: StepResult): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /**
+     * §23 — Called when escalation is required.
+     * Agent MUST pause and wait for host to relay user response.
+     * Hosts MUST implement at minimum IRREVERSIBLE_ACTION and CAPABILITY_EXPANSION triggers.
+     */
+    onEscalation(reason: EscalationReason, context: unknown): Promise<EscalationResponse>;
+}
+
+/**
+ * PEX Channel Contract Types
+ * Corresponds to §2.3 and §9.2 of the Plexo Extension Protocol (PEX) Specification v0.4.0
+ */
+
+interface ChannelHealthResult {
+    healthy: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+interface ChannelSendResult {
+    ok: boolean;
+    messageId?: string;
+    error?: string;
+}
+interface ChannelExtension {
+    /**
+     * Called on activate. Channel should start listening for inbound messages
+     * and call sdk.channel.send() to route them into the host.
+     */
+    onActivate(): Promise<void>;
+    /**
+     * Called when the host wants to send a message via this channel.
+     * Requires channel:receive capability.
+     */
+    onMessage(message: InboundMessage): Promise<void>;
+    /**
+     * Called periodically by the host Channel Router.
+     * Return healthy: false to trigger failover.
+     */
+    healthCheck(): Promise<ChannelHealthResult>;
+    /**
+     * Called on deactivate. Channel should stop listeners and clean up.
+     */
+    onDeactivate(): Promise<void>;
+}
+type PexVersion = '0.4.0';
+declare const PEX_VERSION: PexVersion;
+/** Channel runtime types known to Plexo. Mirrors `channel_type` enum. */
+type ChannelType = 'telegram' | 'slack' | 'discord' | 'whatsapp' | 'signal' | 'matrix' | 'irc' | 'webchat' | 'twilio' | 'gmail' | 'gmessages';
+/** Connection state machine surfaced to subscribers (ADR-0004 + ADR-0005). */
+type ConnectionState = 'paired' | 'active' | 'refreshing' | 'expired' | 'revoked' | 'errored';
+interface ChannelAttachmentRef {
+    /** Plexo-side attachment ID, resolvable via the attachment store. */
+    id: string;
+    /** MIME type if known. */
+    mimeType?: string;
+    /** Display filename. */
+    filename?: string;
+    /** Size in bytes if known. */
+    sizeBytes?: number;
+    /** Optional thumbnail attachment ID for image/video previews. */
+    thumbnailId?: string;
+}
+/** Canonical message envelope used by every Channel subscriber. */
+interface ChannelMessage {
+    id: string;
+    channelId: string;
+    threadId: string;
+    direction: 'inbound' | 'outbound';
+    /** Plain text body. Markdown is not parsed by Plexo's generic viewer. */
+    text: string;
+    attachments?: ChannelAttachmentRef[];
+    /** Sender identifier in the channel's native namespace (phone number, handle, etc.). */
+    senderId: string;
+    /** Display name if the channel resolves one. */
+    senderName?: string;
+    /** ISO-8601 timestamp when the message was authored upstream. */
+    sentAt: string;
+    /** Channel-specific metadata — RCS feature flags, read receipts, etc. */
+    metadata?: Record<string, unknown>;
+    pexVersion: PexVersion;
+}
+interface ChannelThread {
+    id: string;
+    channelId: string;
+    /** Display title. For 1:1 threads this is typically the contact name or phone. */
+    title: string;
+    /** Most recent message preview (text-only, truncated). */
+    lastMessagePreview?: string;
+    lastMessageAt?: string;
+    unreadCount?: number;
+    /** Channel-specific metadata (e.g., is_rcs flag for gmessages). */
+    metadata?: Record<string, unknown>;
+    pexVersion: PexVersion;
+}
+interface ChannelDescriptor {
+    id: string;
+    workspaceId: string;
+    type: ChannelType;
+    name: string;
+    state: ConnectionState;
+    enabled: boolean;
+    lastMessageAt?: string;
+    pexVersion: PexVersion;
+}
+/** Connection (credential) descriptor — paired-session metadata, no secrets. */
+interface PairedConnectionDescriptor {
+    id: string;
+    workspaceId: string;
+    registryId: string;
+    state: ConnectionState;
+    pairedAt?: string;
+    lastInboundAt?: string;
+    decodeErrorCount?: number;
+    pexVersion: PexVersion;
+}
+type ChannelEvent = {
+    type: 'message.received';
+    channelId: string;
+    threadId: string;
+    message: ChannelMessage;
+    pexVersion: PexVersion;
+} | {
+    type: 'message.sent';
+    channelId: string;
+    threadId: string;
+    message: ChannelMessage;
+    pexVersion: PexVersion;
+} | {
+    type: 'connection.state_changed';
+    channelId: string;
+    state: ConnectionState;
+    pexVersion: PexVersion;
+};
+interface ChannelSubscription {
+    id: string;
+    appId: string;
+    channelId: string;
+    scopes: ChannelScope[];
+    createdAt: string;
+}
+type ChannelScope = 'channels:list' | 'channels:subscribe' | 'channels:read' | 'channels:send' | 'channels:events';
+interface ChannelSendRequest {
+    text: string;
+    attachments?: ChannelAttachmentRef[];
+    /** Caller-supplied idempotency token; Plexo dedupes within a 24h window. */
+    idempotencyKey: string;
+}
+interface ChannelMessagePage {
+    messages: ChannelMessage[];
+    nextCursor?: string;
+}
+interface ChannelThreadPage {
+    threads: ChannelThread[];
+    nextCursor?: string;
+}
+
+interface ChannelClientOptions {
+    /** Plexo Core base URL (e.g. https://plexo.example.com). No trailing slash required. */
+    baseUrl: string;
+    /** PLEXO_SERVICE_KEY shared secret used for HMAC body signatures. */
+    serviceKey: string;
+    /** App identity, mirrored back to Plexo via X-App-Id for scope enforcement. */
+    appId: string;
+    /** Optional fetch override (testing, custom retry). */
+    fetchImpl?: typeof fetch;
+}
+interface ChannelClient {
+    list(opts?: {
+        workspaceId?: string;
+    }): Promise<ChannelDescriptor[]>;
+    subscribe(channelId: string, scopes: ChannelScope[]): Promise<ChannelSubscription>;
+    unsubscribe(channelId: string, subscriptionId: string): Promise<void>;
+    threads(channelId: string, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<ChannelThreadPage>;
+    messages(channelId: string, threadId: string, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<ChannelMessagePage>;
+    send(channelId: string, threadId: string, payload: ChannelSendRequest): Promise<ChannelMessage>;
+    /**
+     * Async iterator over the SSE event stream. The generator reconnects with
+     * `Last-Event-ID` on transient drops; callers may abort via the
+     * `AbortSignal` parameter.
+     */
+    events(channelId: string, opts?: {
+        signal?: AbortSignal;
+        lastEventId?: string;
+    }): AsyncIterable<ChannelEvent>;
+}
+declare function createChannelClient(opts: ChannelClientOptions): ChannelClient;
+
+/**
+ * PEX Event Bus Types
+ * Corresponds to §7.4 of the Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Extensions may only publish to ext.<scope>.* namespace.
+ * Standard topics are published by the host.
+ *
+ * v0.4.0 additions:
+ *   - prompt.* topics (§7.6)
+ *   - context.* topics (§7.7)
+ *
+ * v0.3.0 additions:
+ *   - entity.* topics (§16)
+ *   - escalation.* topics (§23)
+ *   - audit.* topics (§18)
+ *   - self.* topics (§20)
+ *   - agent.* topics (core architecture)
+ *   - a2a.* topics (§22)
+ */
+
+/** Standard topics published by the host. Extensions subscribe but cannot publish these. */
+declare const TOPICS: {
+    readonly TASK_CREATED: "task.created";
+    readonly TASK_COMPLETED: "task.completed";
+    readonly TASK_FAILED: "task.failed";
+    readonly TASK_BLOCKED: "task.blocked";
+    readonly CHANNEL_MESSAGE_RECEIVED: "channel.message.received";
+    readonly CHANNEL_HEALTH_CHANGED: "channel.health.changed";
+    readonly EXTENSION_ACTIVATED: "extension.activated";
+    readonly EXTENSION_DEACTIVATED: "extension.deactivated";
+    readonly EXTENSION_CRASHED: "extension.crashed";
+    readonly CONNECTION_ADDED: "connection.added";
+    readonly CONNECTION_REMOVED: "connection.removed";
+    readonly MEMORY_WRITTEN: "memory.written";
+    readonly ENTITY_CREATED: "entity.created";
+    readonly ENTITY_MODIFIED: "entity.modified";
+    readonly ENTITY_DELETED: "entity.deleted";
+    readonly ENTITY_LINKED: "entity.linked";
+    readonly ESCALATION_TRIGGERED: "escalation.triggered";
+    readonly ESCALATION_RESOLVED: "escalation.resolved";
+    readonly ESCALATION_TIMED_OUT: "escalation.timed_out";
+    readonly AUDIT_ENTRY_CREATED: "audit.entry.created";
+    readonly SELF_UPDATED: "self.updated";
+    readonly SELF_PROPOSAL_RECEIVED: "self.proposal.received";
+    readonly AGENT_ACTIVATED: "agent.activated";
+    readonly AGENT_DEACTIVATED: "agent.deactivated";
+    readonly AGENT_PLAN_CREATED: "agent.plan.created";
+    readonly AGENT_STEP_COMPLETED: "agent.step.completed";
+    readonly AGENT_STEP_FAILED: "agent.step.failed";
+    readonly A2A_INBOUND_RECEIVED: "a2a.inbound.received";
+    readonly A2A_DELEGATION_SENT: "a2a.delegation.sent";
+    readonly A2A_DELEGATION_COMPLETED: "a2a.delegation.completed";
+    readonly PROMPT_REGISTERED: "prompt.registered";
+    readonly PROMPT_ENABLED: "prompt.enabled";
+    readonly CONTEXT_REGISTERED: "context.registered";
+    readonly CONTEXT_UPDATED: "context.updated";
+    readonly CONTEXT_EXPIRED: "context.expired";
+};
+type StandardTopic = (typeof TOPICS)[keyof typeof TOPICS];
+/**
+ * Build an extension-scoped topic name.
+ * Extensions MUST use this for events they publish.
+ * @example customTopic('acme', 'stripe-monitor', 'mrr.updated')
+ * // => 'ext.acme.stripe-monitor.mrr.updated'
+ */
+declare function customTopic(scope: string, name: string, event: string): string;
+interface TaskCreatedPayload {
+    taskId: string;
+    title: string;
+    type: string;
+    workspaceId: string;
+}
+interface TaskCompletedPayload {
+    taskId: string;
+    durationMs: number;
+    workspaceId: string;
+    /** Domain mastery: inferred domain tag for this task. Null when domain mastery is off. */
+    domainTag?: string | null;
+    /** Quality score from the quality judge (0-1). */
+    qualityScore?: number | null;
+    /** Task type classification. */
+    taskType?: string;
+}
+interface TaskFailedPayload {
+    taskId: string;
+    error: string;
+    workspaceId: string;
+}
+interface TaskBlockedPayload {
+    taskId: string;
+    reason: string;
+    workspaceId: string;
+}
+interface ChannelMessageReceivedPayload {
+    channelId: string;
+    messageId: string;
+    senderId: string;
+}
+interface ChannelHealthChangedPayload {
+    channelId: string;
+    healthy: boolean;
+    latencyMs?: number;
+}
+interface ExtensionActivatedPayload {
+    name: string;
+    version: string;
+    type: string;
+    workspaceId: string;
+}
+interface ExtensionDeactivatedPayload {
+    name: string;
+    workspaceId: string;
+}
+interface ExtensionCrashedPayload {
+    name: string;
+    error: string;
+    workspaceId: string;
+}
+interface ConnectionAddedPayload {
+    service: string;
+    workspaceId: string;
+}
+interface ConnectionRemovedPayload {
+    service: string;
+    workspaceId: string;
+}
+interface MemoryWrittenPayload {
+    id: string;
+    tags?: string[];
+    authorExtension: string;
+    workspaceId: string;
+}
+interface EntityCreatedPayload {
+    entityType: EntityTypeName;
+    entityId: string;
+    createdBy: string;
+    workspaceId: string;
+}
+interface EntityModifiedPayload {
+    entityType: EntityTypeName;
+    entityId: string;
+    modifiedBy: string;
+    workspaceId: string;
+}
+interface EntityDeletedPayload {
+    entityType: EntityTypeName;
+    entityId: string;
+    deletedBy: string;
+    workspaceId: string;
+}
+interface EntityLinkedPayload {
+    sourceType: EntityTypeName;
+    sourceId: string;
+    targetType: EntityTypeName;
+    targetId: string;
+    workspaceId: string;
+}
+interface EscalationTriggeredPayload {
+    extensionId: string;
+    agentId?: string;
+    trigger: EscalationTrigger;
+    action: string;
+    workspaceId: string;
+}
+interface EscalationResolvedPayload {
+    extensionId: string;
+    agentId?: string;
+    trigger: EscalationTrigger;
+    response: EscalationUserResponse;
+    workspaceId: string;
+}
+interface EscalationTimedOutPayload {
+    extensionId: string;
+    agentId?: string;
+    trigger: EscalationTrigger;
+    workspaceId: string;
+}
+interface AuditEntryCreatedPayload {
+    extensionId: string;
+    action: AuditAction;
+    outcome: AuditOutcome;
+    target: string;
+}
+interface SelfUpdatedPayload {
+    field: string;
+    updatedBy: string;
+}
+interface SelfProposalReceivedPayload {
+    field: string;
+    source: string;
+    confidence: number;
+}
+interface AgentActivatedPayload {
+    name: string;
+    version: string;
+    workspaceId: string;
+}
+interface AgentDeactivatedPayload {
+    name: string;
+    workspaceId: string;
+}
+interface AgentPlanCreatedPayload {
+    agentName: string;
+    taskId: string;
+    stepCount: number;
+    workspaceId: string;
+}
+interface AgentStepCompletedPayload {
+    agentName: string;
+    taskId: string;
+    stepId: string;
+    durationMs: number;
+    workspaceId: string;
+}
+interface AgentStepFailedPayload {
+    agentName: string;
+    taskId: string;
+    stepId: string;
+    error: string;
+    workspaceId: string;
+}
+interface A2AInboundReceivedPayload {
+    sourceEndpoint: string;
+    taskId: string;
+    workspaceId: string;
+}
+interface A2ADelegationSentPayload {
+    targetEndpoint: string;
+    taskId: string;
+    agentName: string;
+    workspaceId: string;
+}
+interface A2ADelegationCompletedPayload {
+    targetEndpoint: string;
+    taskId: string;
+    status: string;
+    workspaceId: string;
+}
+interface PromptRegisteredPayload {
+    extensionName: string;
+    promptId: string;
+    workspaceId: string;
+}
+interface PromptEnabledPayload {
+    promptId: string;
+    workspaceId: string;
+}
+interface ContextRegisteredPayload {
+    extensionName: string;
+    contextId: string;
+    workspaceId: string;
+}
+interface ContextUpdatedPayload {
+    extensionName: string;
+    contextId: string;
+    workspaceId: string;
+}
+interface ContextExpiredPayload {
+    extensionName: string;
+    contextId: string;
+    workspaceId: string;
+}
+
+/**
+ * §21 — Agent + Extension Identity via DID + Verifiable Credentials
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Each Extension and Agent MAY be assigned a W3C Decentralized Identifier (DID).
+ * Full compliance hosts MUST assign DIDs for any cross-host interaction.
+ *
+ * Rules:
+ *   - Extension and Agent DIDs resolvable via Extension Registry Protocol (§12)
+ *   - Cross-host actions MUST be signed with the Extension's or Agent's private key
+ *   - Revoked or expired VCs cause immediate capability rejection
+ *   - Capability token: identity:present — required for cross-host interactions
+ */
+
+/**
+ * W3C DID Document fields for Plexo entities.
+ * @example did:plexo:host-id:extension-id
+ */
+interface PlexoDIDDocument {
+    /** W3C DID string, e.g. 'did:plexo:host-id:extension-id' */
+    did: string;
+    /** Public key for signing agent actions and authenticating */
+    publicKey: string;
+    /** Communication endpoints */
+    serviceEndpoints?: Record<string, string>;
+    /** URL that resolves to plexo.json */
+    extensionManifest?: string;
+    /** Trust tier of this entity */
+    trustTier: TrustTier;
+    /** DID of the issuing host or registry */
+    issuedBy: string;
+}
+/**
+ * Verifiable Credential issued by a host at install time,
+ * attesting to capability grants.
+ */
+interface PlexoVerifiableCredential {
+    /** Unique credential ID */
+    id: string;
+    /** W3C VC type */
+    type: 'VerifiableCredential' | 'PlexoCapabilityCredential';
+    /** DID of the issuer (host) */
+    issuer: string;
+    /** DID of the subject (extension or agent) */
+    subject: string;
+    /** ISO 8601 issuance date */
+    issuanceDate: string;
+    /** ISO 8601 expiration date */
+    expirationDate?: string;
+    /** Granted capability tokens */
+    capabilities: string[];
+    /** Cryptographic proof */
+    proof: {
+        type: string;
+        created: string;
+        proofPurpose: string;
+        verificationMethod: string;
+        /** Signature value */
+        jws: string;
+    };
+}
+/**
+ * Selective disclosure request — prove a specific capability
+ * without revealing all grants.
+ */
+interface SelectiveDisclosureRequest {
+    /** Capabilities the verifier wants proof of */
+    requestedCapabilities: string[];
+    /** DID of the requesting party */
+    verifier: string;
+    /** Nonce to prevent replay */
+    nonce: string;
+}
+interface SelectiveDisclosureResponse {
+    /** Derived credential proving only requested capabilities */
+    credential: PlexoVerifiableCredential;
+    /** Nonce from the request */
+    nonce: string;
+}
+
+/**
+ * §25 — Plexo-Native Service Discovery
+ * Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Any service supporting Plexo natively MUST expose:
+ *   GET /.well-known/plexo.json
+ *
+ * Detection flow:
+ *   1. User initiates a Connection to an external service
+ *   2. Host pings {serviceBaseUrl}/.well-known/plexo.json
+ *   3. Valid manifest → Plexo-native: verify DID, surface shield badge,
+ *      full disclosure pre-connection
+ *   4. 404 or invalid → Standard Connection: no badge, OAuth/API key fallback,
+ *      manual trust assumed
+ *
+ * Rules:
+ *   - MUST be served over HTTPS, publicly accessible, no authentication required
+ *   - MUST return Content-Type: application/json
+ *   - Response MUST validate against Plexo manifest schema
+ *   - DID MUST resolve via Extension Registry
+ */
+interface WellKnownPlexo {
+    /** PEX spec version (e.g. '0.4.0') */
+    plexo: string;
+    /** Service display name */
+    name: string;
+    /** W3C DID of this service */
+    did?: string;
+    capabilities: {
+        /** Connection identifiers offered by this service */
+        offered?: string[];
+        /** Pre-built extensions available for this service */
+        extensions?: WellKnownExtensionRef[];
+    };
+    dataResidency?: {
+        sendsDataExternally: boolean;
+        regions?: string[];
+    };
+    auth: {
+        schemes: ('oauth2' | 'api_key' | 'did')[];
+        oauth2?: {
+            authorizationUrl: string;
+            tokenUrl: string;
+        };
+    };
+    escalation?: {
+        /** Whether this service supports escalation callback webhooks */
+        supportsEscalationCallbacks: boolean;
+        webhookEndpoint?: string;
+    };
+}
+interface WellKnownExtensionRef {
+    /** Scoped extension name */
+    name: string;
+    /** Registry URL where the extension is published */
+    registry: string;
+}
+/**
+ * Result of a Plexo-native service discovery probe.
+ */
+type ServiceDiscoveryResult = {
+    native: true;
+    manifest: WellKnownPlexo;
+} | {
+    native: false;
+    reason: 'not_found' | 'invalid_manifest' | 'network_error';
+};
+
+/**
+ * PEX manifest validation
+ * Corresponds to §3.3 of the Plexo Extension Protocol (PEX) Specification v0.4.0
+ *
+ * Used by:
+ * - POST /api/plugins (host install validation)
+ * - @plexo/cli (publish validation)
+ */
+
+interface ValidationError {
+    field: string;
+    message: string;
+    severity?: 'error' | 'warning';
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+interface ValidationOptions {
+    /** Host compliance level — affects which capabilities are valid */
+    hostComplianceLevel?: HostComplianceLevel;
+    /**
+     * Install source context. When set to `'sideload'` the validator applies
+     * the sideload capability ceiling (rejects owner-only tokens regardless of
+     * the declared `trust` value). Default: `'registry'`.
+     */
+    source?: 'registry' | 'sideload';
+}
+declare function validateManifest(raw: unknown, options?: ValidationOptions): ValidationResult;
+
+/**
+ * Extension package signature verification.
+ *
+ * v1 strategy (documented in `docs/security/extension-security-model.md` §Q1):
+ *
+ *   Sigstore / cosign with GitHub OIDC — keyless signing tied to the GitHub
+ *   Actions workflow that publishes to the registry. No long-lived keys to
+ *   lose. The host verifies that the signature's signer identity resolves to
+ *   `*@joeybuilt-official` (the owner) or to a key on the verified-publisher
+ *   key set.
+ *
+ * This module ships a **stub** verifier for v1. The intent is:
+ *
+ *   - The registry stores signature metadata alongside every manifest row
+ *     (`signature`, `signature_type`, `signer_identity`, `signed_at`) — see
+ *     migration 0068.
+ *   - Install-time, the host calls `verifySignature(manifest, meta)` and, on
+ *     success, trusts the manifest's declared `trust` value.
+ *   - On failure (or `null` meta), the host downgrades `trust` to `community`
+ *     (for registry installs) or `local` (for sideloads), exactly as §8.4 of
+ *     the security spec requires.
+ *
+ * The real verifier will call `cosign verify` against the Rekor log, or fall
+ * back to a local ECDSA P-256 public key check. For v1 we accept any Sigstore
+ * metadata whose `signer_identity` ends in `@joeybuilt-official` — this lets
+ * us wire the call sites now and swap the implementation later without
+ * churning the install route.
+ */
+
+type SignatureType = 'sigstore' | 'ecdsa-p256' | 'none';
+interface SignatureMetadata {
+    /** Opaque signature payload (base64 for ECDSA, JSON bundle for Sigstore). */
+    signature: string;
+    /** Discriminator for which verifier to use. */
+    signatureType: SignatureType;
+    /** Human-readable signer identity (e.g. `plexo-bot@joeybuilt-official`). */
+    signerIdentity: string;
+    /** ISO 8601 timestamp the signature was produced. */
+    signedAt: string;
+}
+interface SignatureVerificationResult {
+    ok: boolean;
+    /** Matches the input `signatureType` on success, `'none'` on failure. */
+    signatureType: SignatureType;
+    /** Signer identity extracted from the verified signature, if any. */
+    signerIdentity: string | null;
+    /** The effective trust tier AFTER verification. May downgrade to 'community'. */
+    effectiveTrust: TrustTier;
+    /** Human-readable message for the UI. */
+    message: string;
+}
+/**
+ * Verify a manifest's signature. v1 stub behavior:
+ *
+ *   - `meta === null`               → unsigned, downgrade to `community`
+ *   - `signatureType === 'none'`    → unsigned, downgrade to `community`
+ *   - `signatureType === 'sigstore'`:
+ *        - signer_identity endsWith an OWNER_IDENTITY_SUFFIX → accept as `owner`
+ *        - otherwise                                          → accept as `verified`
+ *   - `signatureType === 'ecdsa-p256'`:
+ *        - accept as `verified` (real verification TBD)
+ *
+ * The declared `manifest.trust` is the ceiling — we never upgrade above it.
+ * An unsigned extension claiming `owner` is downgraded to `community`. A
+ * signed extension claiming `community` stays at `community`.
+ */
+declare function verifySignature(manifest: ExtensionManifest, meta: SignatureMetadata | null): SignatureVerificationResult;
+
+export { type A2AAgentCard, type A2ADelegation, type A2ADelegationCompletedPayload, type A2ADelegationSentPayload, type A2AInboundReceivedPayload, type A2AInboundRequest, type A2ATask, type A2ATaskResult, type A2ATaskStatus, type AgentActivatedPayload, type AgentDeactivatedPayload, type AgentExtension, type AgentHints, type AgentPlanCreatedPayload, type AgentStackManifest, type AgentStepCompletedPayload, type AgentStepFailedPayload, type AuditAction, type AuditEntry, type AuditEntryCreatedPayload, type AuditOutcome, type AuditQuery, type AuditQueryResult, type BehaviorRuleDefinition, type CalendarEventEntity, type CapabilityToken, type ChannelAttachmentRef, type ChannelClient, type ChannelClientOptions, type ChannelDescriptor, type ChannelEvent, type ChannelExtension, type ChannelHealthChangedPayload, type ChannelHealthResult, type ChannelMessage, type ChannelMessagePage, type ChannelMessageReceivedPayload, type ChannelScope, type ChannelSendRequest, type ChannelSendResult, type ChannelSubscription, type ChannelThread, type ChannelThreadPage, type ChannelType, type ConnectionAddedPayload, type ConnectionCredentials, type ConnectionRemovedPayload, type ConnectionState, type ContextArtifact, type ContextExpiredPayload, type ContextRegisteredPayload, type ContextRegistration, type ContextSummary, type ContextUpdatedPayload, type DataResidencyDeclaration, type EntityCreatedPayload, type EntityDeletedPayload, type EntityLinkedPayload, type EntityModifiedPayload, type EntitySearchQuery, type EntitySearchResult, type EntityTypeMap, type EntityTypeName, type ErrorCode, type EscalationDeclaration, type EscalationOutcome, type EscalationReason, type EscalationRequest, type EscalationResolvedPayload, type EscalationResponse, type EscalationResult, type EscalationTimedOutPayload, type EscalationTrigger, type EscalationTriggeredPayload, type EscalationUserResponse, type ExtensionActivatedPayload, type ExtensionCrashedPayload, type ExtensionDeactivatedPayload, type ExtensionManifest, type ExtensionSubtype, type ExtensionType, type ExternalDestination, type FileEntity, type HostComplianceLevel, type HostInfo, type InvokeContext, type JSONSchema, type LinkedEntity, type MCPServerConfig, type ManifestType, type MemoryEntry, type MemoryWrittenPayload, type MessageType, type ModelContextEntry, type ModelRequirements, type NoteEntity, type NotificationLevel, type OneWayDoor, type OneWayDoorType, PEX_VERSION, type PairedConnectionDescriptor, type PersonEntity, type PexError, type PexMessage, type PexVersion, type Plan, type PlanStep, type PlexoDIDDocument, type PlexoEntity, type PlexoSDK, type PlexoVerifiableCredential, type PromptArtifact, type PromptEnabledPayload, type PromptRegisteredPayload, type PromptRegistration, type PromptSummary, type PromptVariable, type ResourceHints, type ScheduleRegistration, type SelectiveDisclosureRequest, type SelectiveDisclosureResponse, type SelfProposalReceivedPayload, type SelfUpdatedPayload, type ServiceDiscoveryResult, type ShouldActivateResult, type SignatureMetadata, type SignatureType, type SignatureVerificationResult, type StandardTopic, type StandingApproval, type StepResult, TOPICS, type TaskBlockedPayload, type TaskCompletedPayload, type TaskCreateOptions, type TaskCreatedPayload, type TaskEntity, type TaskFailedPayload, type TaskFilter, type ThreadEntity, type ToolCall, type ToolRegistration, type ToolSummary, type TransactionEntity, type TrustTier, type TrustTierCeilings, type TrustTierPolicy, type UserCommunicationStyle, type UserContext, type UserIdentity, type UserSelf, type UserSelfConflictResolution, type UserSelfField, type UserSelfProposal, type ValidationError, type ValidationOptions, type ValidationResult, type WellKnownExtensionRef, type WellKnownPlexo, type WidgetRegistration, createChannelClient, customTopic, validateManifest, verifySignature };