@vonzio/plugin-api 0.1.0

package/index.d.ts

@@ -0,0 +1,945 @@
+import type { FastifyInstance } from "fastify";
+/**
+ * Current plugin-api version. Plugins encode the version they were built
+ * against in their package.json `vonzio.apiVersion`; the loader rejects
+ * plugins whose major differs or whose minor is ahead of core's (see
+ * `assertApiCompatible`). Bumped to 1.0.0 with the external-loader contract
+ * (docs/PLUGIN_LOADER_SPEC.md) — the loader surface is now a stability
+ * commitment.
+ */
+export declare const PLUGIN_API_VERSION = "1.0.0";
+/**
+ * The shape every plugin's default export must satisfy. Generic over
+ * the plugin's own config type so init() receives a fully-typed config.
+ */
+export interface VonzioPlugin<TConfig = unknown> {
+    /**
+     * Stable identifier. Used for the auto-route prefix, log scope, and
+     * the migration namespace in the `_migrations` table. Conventionally
+     * matches the npm package's unscoped name (e.g. `telegram` for
+     * `@vonzio/plugin-telegram`).
+     */
+    name: string;
+    /**
+     * Semver of `@vonzio/plugin-api` this plugin was built against. The
+     * loader compares the major against core's PLUGIN_API_VERSION and
+     * refuses to load plugins targeting a newer major.
+     */
+    apiVersion: string;
+    /**
+     * Zod schema for the plugin's env-derived config. The loader calls
+     * `.parse(process.env)` on it and rejects malformed values with a
+     * useful error. Plugins should namespace their env vars
+     * (`SLACK_CLIENT_ID`, `TELLER_API_KEY`, etc.) to avoid collisions.
+     *
+     * Typed as `ConfigSchemaLike` (a structural shape with just
+     * `.parse()`) rather than `z.ZodType<TConfig>` for two reasons:
+     *  1. The workspace can have zod v3 and v4 simultaneously (different
+     *     deps pin different majors); using zod's strong types here
+     *     would force every plugin's schema to be the same major
+     *     instance as plugin-api's.
+     *  2. ZodObject is technically a ZodType subtype, but TS variance
+     *     rules reject ZodObject<T> as a ZodType<T> in many cases.
+     * The plugin's TConfig flows from `.parse()`'s return value at the
+     * use site, so typing stays useful where it matters.
+     */
+    configSchema: ConfigSchemaLike<TConfig>;
+    /**
+     * SQL migrations owned by this plugin. The core migration runner
+     * applies them in order interleaved with core's own, tagged in
+     * `_migrations` as `<plugin-name>_<migration-name>`. Plugins should
+     * keep migrations idempotent (CREATE TABLE IF NOT EXISTS, etc.) so
+     * partial-apply failures don't poison subsequent boots.
+     */
+    migrations?: PluginMigration[];
+    /**
+     * Where this plugin's routes live in the URL space. Default
+     * (`{ kind: "auto" }`) mounts everything under `/plugins/<name>/*`.
+     * Plugins with externally-registered URLs (Slack OAuth callback,
+     * Telegram webhook secret in the Telegram app config, etc.) can
+     * use `{ kind: "absolute", prefix }` to keep their legacy URLs and
+     * avoid forcing every self-hoster to update their third-party app
+     * configuration.
+     */
+    routePrefix?: PluginRoutePrefix;
+    /**
+     * Called once at server boot, after config parsing and after this
+     * plugin's migrations have been applied. The plugin registers its
+     * handlers via `ctx.server`, `ctx.notificationBus`,
+     * `ctx.mcpRegistry`, and `ctx.scheduler`. init() must not block on
+     * external services (e.g. an API call) -- those belong in scheduled
+     * jobs or lazy on-first-request initialization, so a flaky upstream
+     * doesn't block server startup.
+     */
+    init: (ctx: PluginContext<TConfig>) => Promise<void> | void;
+    /**
+     * Called on graceful server shutdown. Plugins MUST clear timers,
+     * cancel intervals, close sockets, and stop any worker threads they
+     * spawned. The scheduler-registered jobs are cancelled by core
+     * automatically, but anything the plugin spawned outside that
+     * channel is its own responsibility.
+     */
+    teardown?: () => Promise<void> | void;
+}
+/**
+ * Where the plugin's routes live. `auto` mounts under
+ * `/plugins/<plugin-name>/*` which is the recommended default --
+ * keeps URLs collision-free and self-documenting. `absolute` is the
+ * escape hatch for plugins that need a stable legacy URL (e.g. Slack
+ * OAuth callback is registered in the Slack app config; changing it
+ * would force every self-hoster to update their Slack app).
+ */
+export type PluginRoutePrefix = {
+    kind: "auto";
+} | {
+    kind: "absolute";
+    prefix: string;
+};
+/**
+ * One SQL migration. The core migration runner applies these in the
+ * order the plugin lists them, and records `<plugin-name>_<name>` in
+ * the `_migrations` table so a partial apply can resume cleanly.
+ */
+export interface PluginMigration {
+    /**
+     * Migration name. Conventionally `NNNN_short_description.sql`-style
+     * (e.g. `0001_initial_schema`, `0002_add_thread_label`).
+     * Combined with the plugin name to form the key core stores.
+     */
+    name: string;
+    /** Idempotent SQL. Plugins should use CREATE ... IF NOT EXISTS etc. */
+    up: string;
+}
+/**
+ * What init() receives. Everything a plugin needs to integrate with
+ * core lives here -- plugins should never `import` from
+ * `@vonzio/core-server` directly.
+ */
+export interface PluginContext<TConfig = unknown> {
+    /**
+     * Fastify scope. Routes registered here are auto-prefixed if the
+     * plugin uses the default `routePrefix`. The plugin still owns the
+     * relative URL space inside its prefix.
+     */
+    server: FastifyInstance;
+    /** The result of `configSchema.parse(process.env)`. */
+    config: TConfig;
+    /** Logger pre-tagged with `{ plugin: name }`. */
+    log: PluginLogger;
+    /**
+     * Versioned access to core services. At runtime this is a capability
+     * MEMBRANE (a revocable Proxy) — accessing a `core` surface the plugin
+     * did not declare + get granted throws `CapabilityViolationError` and is
+     * audited. The membrane is hygiene against honest mistakes via THIS
+     * reference; it is not a sandbox against `require('@vonzio/core-server')`.
+     * See docs/PLUGIN_LOADER_SPEC.md §2, §7.
+     */
+    core: PluginCore;
+    /**
+     * Per-plugin namespaced key/value store. Present only when the plugin
+     * declared `storage.kv` and the operator granted it; otherwise accessing
+     * it throws `CapabilityViolationError`. Preferred over `db.*` for new
+     * plugins (§5).
+     */
+    storage: PluginStorageKv;
+    /**
+     * Audited outbound HTTP. Present only when the plugin declared
+     * `http.outbound` (with a non-empty `outboundHosts`) and the operator
+     * granted it. Every call is SSRF-checked, allowlist-checked against
+     * manifest∩policy hosts, and logged. See §10.
+     */
+    http: PluginHttp;
+    /** Where the plugin claims a notification channel kind. */
+    notificationBus: NotificationBus;
+    /** Where the plugin contributes an MCP server. */
+    mcpRegistry: McpRegistry;
+    /**
+     * Resolve the per-task bearer token core attaches when it injects this
+     * plugin's MCP server into an agent container. Present only when the plugin
+     * declared `mcp.register` and the operator granted it; otherwise accessing it
+     * throws `CapabilityViolationError`. See §10.
+     */
+    mcpSessions: McpSessions;
+    /** Where the plugin schedules background work. */
+    scheduler: Scheduler;
+    /**
+     * Subscribe to session-lifecycle events emitted by the orchestrator.
+     * Used by integrations that relay task progress to external
+     * surfaces (e.g. Telegram chat, Slack thread).
+     */
+    sessionEvents: SessionEvents;
+    /**
+     * Resolve operator-provisioned secret material into opaque references.
+     * Present only when the plugin declared `secrets.mtls` (with a non-empty
+     * `manifest.mtlsSecrets`) and the operator both granted it and provisioned
+     * the cert/key files in policy; otherwise accessing it throws
+     * `CapabilityViolationError`. v1 covers mTLS client certs only. See §5, §10.
+     */
+    secrets: PluginSecrets;
+}
+/**
+ * One user's integration row, as seen by a plugin. Used by
+ * notification handlers to resolve `req.recipient` (an integration
+ * id) into the bot token / channel / chat id / etc. needed to send a
+ * message.
+ *
+ * `config` is type-erased on this contract -- the actual shape is
+ * provider-specific (Telegram: bot_token + owner_tg_user_id;
+ * Slack: bot_token + authed_user_id; etc.) and is the plugin's
+ * responsibility to assert. With `opts.decrypt: true` the loader
+ * runs the standard decrypt pass against config before returning.
+ */
+export interface PluginIntegration {
+    id: string;
+    user_id: string;
+    type: string;
+    config: Record<string, unknown>;
+    enabled: boolean;
+    /**
+     * Last-modified timestamp (ISO-8601). Plugins use this for
+     * optimistic-locking writes -- see `update({...}, { expectUpdatedAt })`.
+     */
+    updated_at: string;
+}
+/**
+ * Adapter around core's IntegrationService. Plugins use this to look
+ * up + manage user-integration rows (Slack tokens, Telegram bots,
+ * Gmail OAuth grants, etc.). All eight methods mirror core's
+ * IntegrationService surface 1:1 -- the structural shape lets the
+ * loader pass the real service through without leaking the concrete
+ * class type into plugin-api.
+ */
+export interface PluginIntegrationLookup {
+    get(id: string, opts?: {
+        decrypt?: boolean;
+    }): Promise<PluginIntegration | null>;
+    getByUserAndType(userId: string, type: string, opts?: {
+        decrypt?: boolean;
+    }): Promise<PluginIntegration | null>;
+    listByType(type: string, opts?: {
+        decrypt?: boolean;
+    }): Promise<PluginIntegration[]>;
+    listByUserAndType(userId: string, type: string, opts?: {
+        decrypt?: boolean;
+    }): Promise<PluginIntegration[]>;
+    findByTypeAndExternalId(type: string, externalId: string, opts?: {
+        decrypt?: boolean;
+    }): Promise<PluginIntegration | null>;
+    /**
+     * Multi-result variant for the case where a single external id maps
+     * to multiple integrations -- e.g. the platform Telegram bot has
+     * one bot_user_id but many user-integration rows (one per paired
+     * user). The relay routes by `(user_id, external_id)` to disambiguate.
+     */
+    listByTypeAndExternalId(type: string, externalId: string, opts?: {
+        decrypt?: boolean;
+    }): Promise<PluginIntegration[]>;
+    /**
+     * Lazy backfill of the indexed `external_id` column for legacy rows
+     * that pre-date the column. The plugin calls this on first read of
+     * a row that's missing the index -- avoids a one-time migration
+     * that would need decryption inside the migration runner.
+     */
+    backfillExternalId(id: string): Promise<void>;
+    create(userId: string, type: string, config: Record<string, unknown>, scopeInput?: unknown): Promise<PluginIntegration>;
+    /**
+     * Update an integration row. `opts.expectUpdatedAt` gates the write
+     * on the matching `updated_at` value -- used by the chat-surface
+     * pairing flow to make /link claims race-safe (the loser sees a
+     * null return and refuses without echoing "Linked.").
+     */
+    update(id: string, input: Partial<{
+        config: Record<string, unknown>;
+        enabled: boolean;
+        scope: string;
+        profile_ids: string[];
+    }>, opts?: {
+        expectUpdatedAt?: string;
+    }): Promise<PluginIntegration | null>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * Narrow read-only profile lookup. Plugins use this when validating
+ * that a user-supplied profile_id (e.g. for binding a Telegram bot to
+ * a specific agent profile) actually belongs to the caller.
+ *
+ * Use `profileResolver.getResolved` (separate field on PluginCore) for
+ * the full ResolvedProfile shape with credentials, tools, claude_md,
+ * etc. This narrow surface keeps plugins that only need slug/name
+ * from pulling in that wider type tree.
+ */
+export interface PluginProfileLookup {
+    /**
+     * Returns the full Profile shape (slug, name, model, default_tools,
+     * persistent_sessions, bound_profile_id, ...). Chat-surface pickers
+     * need most of these fields; mirroring a narrow subset structurally
+     * would silently drift as features land.
+     */
+    list(userId: string): Promise<Array<import("@vonzio/shared").Profile>>;
+    /**
+     * Single-row fetch by id. Same full Profile shape as `list`. Use
+     * `profileResolver.getResolved` when you need the resolved variant
+     * (credentials, env, setup_commands, ...).
+     */
+    get(profileId: string): Promise<import("@vonzio/shared").Profile | null>;
+}
+/**
+ * Workspace lookup + lightweight mutations. Plugins use this for:
+ *  - ownership checks before exposing a workspace-bound resource
+ *    (`get`)
+ *  - chat-side `/list` commands that show the user their recent
+ *    workspaces (`list`)
+ *  - chat-side `/model` overrides and "set workspace title from first
+ *    line of chat" updates (`update`)
+ */
+export interface PluginWorkspaceLookup {
+    /**
+     * Returns the full Workspace shape from @vonzio/shared (session_id,
+     * user_id, profile_id, container_id, name, status, model_override,
+     * tags, ...). Chat surfaces use most of these for cross-resume,
+     * model display, and title updates.
+     */
+    get(sessionId: string): import("@vonzio/shared").Workspace | null;
+    list(filters: {
+        userId?: string;
+        orgId?: string;
+        status?: "active" | "resumable" | "idle" | "expired";
+        includeArchived?: boolean;
+        starredOnly?: boolean;
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        workspaces: Array<import("@vonzio/shared").Workspace>;
+        total: number;
+    }>;
+    update(sessionId: string, fields: {
+        name?: string;
+        starred?: boolean;
+        pinned?: boolean;
+        archived?: boolean;
+        tags?: string[];
+        public_preview?: boolean;
+        model_override?: string | null;
+        last_run_model?: string | null;
+    }, opts?: {
+        orgId?: string;
+    }): Promise<import("@vonzio/shared").Workspace | null>;
+}
+/**
+ * Telegram platform-bot surface. As of Phase 3D.1d.1 the concrete
+ * class is plugin-internal (@vonzio/plugin-telegram/services/
+ * platform-bot-service.ts); this interface is the structural shape
+ * the plugin's own setup routes accept so they don't reach into the
+ * service module directly.
+ *
+ * No longer exposed on PluginCore -- other plugins should ignore it.
+ * Kept exported so the telegram plugin's setup-routes signature can
+ * reference the contract type instead of the concrete class.
+ */
+export interface PluginTelegramPlatformBot {
+    getMetadata(): {
+        botUserId: string;
+        botUsername: string;
+    } | null;
+    getToken(): string | null;
+    getWebhookSecret(): string | null;
+    isConfigured(): boolean;
+}
+/**
+ * Session-lifecycle events emitted by the orchestrator. Plugins
+ * subscribe via `ctx.sessionEvents.on(event, handler)` to react to
+ * task progress without core having to know they exist -- e.g. the
+ * telegram plugin's relay echoes `task:token` to the user's Telegram
+ * chat, and `task:done` posts the final result.
+ *
+ * The signatures mirror orchestrator's existing `emit("task:*", ...)`
+ * calls exactly so the typed facade is a zero-overhead pass-through.
+ * sessionId may be `undefined` for tasks not bound to a session
+ * (one-off API calls); plugins typically early-return in that case.
+ *
+ * Handlers are NOT async-awaited by core -- they fire in parallel.
+ * Plugins that need ordering must coordinate via their own queues.
+ */
+export interface SessionEvents {
+    on(event: "task:token", handler: (taskId: string, sessionId: string | undefined, text: string) => void): void;
+    on(event: "task:tool_use", handler: (taskId: string, sessionId: string | undefined, tool: string, input?: unknown) => void): void;
+    on(event: "task:ask_user", handler: (taskId: string, sessionId: string | undefined, input: unknown) => void | Promise<void>): void;
+    on(event: "task:done", handler: (taskId: string, sessionId: string | undefined, result?: {
+        text?: string;
+    }) => void | Promise<void>): void;
+    on(event: "task:failed", handler: (taskId: string, sessionId: string | undefined, error?: string) => void | Promise<void>): void;
+    /**
+     * Bulk unsubscribe -- called by core during plugin teardown so a
+     * reloaded plugin doesn't double up subscriptions. Plugins normally
+     * don't call this themselves.
+     */
+    off(event: SessionEventName, handler: (...args: never[]) => void): void;
+}
+export type SessionEventName = "task:token" | "task:tool_use" | "task:ask_user" | "task:done" | "task:failed";
+/**
+ * Agent-facing description of one chat surface. Surfaced verbatim in
+ * the system-prompt Reachability section that tells the agent where a
+ * `AskUserQuestion` call will be delivered. `label` is the human
+ * sentence shown to the agent ("Telegram (chat bound — may take
+ * minutes if the user isn't near their phone)"); `slow` is true for
+ * surfaces with phone-typing latency, which triggers the
+ * "phrase as 2-4 button options" steer.
+ */
+export interface PresenceSurfaceMetadata {
+    label: string;
+    slow?: boolean;
+}
+/**
+ * One chat-surface provider that core's presence/fallback logic walks
+ * to decide whether a session is reachable. Plugins register one of
+ * these for each surface they own (e.g. the telegram plugin
+ * registers `{ surface: "telegram", ... }`). Implementations may
+ * leave optional methods undefined when they don't apply -- the
+ * registry tolerates partial providers.
+ *
+ * The provider replaces the direct `db.select().from(schema.<plugin-
+ * table>)` calls that core used to do for each surface, breaking the
+ * reverse-coupling that blocks plugin schema moves.
+ */
+export interface SessionPresenceProvider {
+    /**
+     * Stable surface key. Used for dedup (registering two providers
+     * for the same key throws at boot) and for logging. Conventionally
+     * matches the plugin name.
+     */
+    surface: string;
+    /** Agent-visible description; rendered verbatim. */
+    metadata: PresenceSurfaceMetadata;
+    /**
+     * "Is this session bound to a chat on my surface?" Used by the
+     * orchestrator's Reachability section and by ask-user fallback's
+     * in-band-suppression check. Errors are swallowed by the registry
+     * (treated as "no surface") so a flaky provider can't block a task.
+     */
+    hasSession(sessionId: string): Promise<boolean>;
+    /**
+     * "Will my surface deliver to this user's account-wide channel,
+     * regardless of session binding?" Telegram returns true if the user
+     * has a linked bot DM; Slack returns true if the user has a linked
+     * workspace DM. Used only by ask-user fallback to suppress its
+     * plain-text notification when the in-band relay will fire.
+     */
+    hasOwnerSurface?(userId: string): Promise<boolean>;
+    /**
+     * Session ids the user has actively engaged with via this surface
+     * (e.g. claimed a playbook thread). Used by the workspace list to
+     * keep these visible even when the standard "hide playbook
+     * executions" filter would drop them.
+     */
+    listEngagedSessionIds?(): Promise<Set<string>>;
+    /**
+     * Fallback user_id lookup when the session isn't in the in-process
+     * registry (e.g. a brand-new chat-initiated session hasn't reached
+     * the workspace registry yet). Walked by ask-user fallback in
+     * registry order; first non-null wins.
+     */
+    resolveUserIdBySession?(sessionId: string): Promise<string | null>;
+}
+/**
+ * Registration-side surface plugins program against. Plugins receive
+ * this via `PluginCore.sessionPresence` and call `register(provider)`
+ * at init() to contribute their surface. The query-side (used by
+ * core's orchestrator + fallback + workspace-service) is internal --
+ * plugins never iterate the registry themselves.
+ */
+export interface PluginSessionPresenceRegistry {
+    register(provider: SessionPresenceProvider): void;
+}
+/**
+ * Subset of `SubmitTaskInput` plugins use when handing core a new
+ * task. Mirrors core's interface 1:1 but lives in plugin-api so
+ * plugins don't have to import from core-server. New optional fields
+ * can be added; required-field changes need an apiVersion bump.
+ */
+export interface PluginTaskInput {
+    mode?: "session" | "batch" | "pooled" | "single";
+    prompt: string;
+    profile_id?: string;
+    session_id?: string;
+    allowed_tools?: string[];
+    egress_domains?: string[];
+    max_turns?: number;
+    max_budget_usd?: number;
+    model?: string;
+    effort?: string;
+    timeout_seconds?: number;
+    /**
+     * Inline file attachments (images, PDFs, text docs) the chat
+     * surface received with this message. Forwarded to the agent
+     * verbatim; the orchestrator handles MIME-typed presentation.
+     */
+    attachments?: Array<import("@vonzio/shared").TaskAttachment>;
+}
+/**
+ * Narrow facade over `TaskService.submit` for plugins that launch
+ * tasks from external triggers (e.g. a chat message arrives ->
+ * submit a session task). callerProfileIds gates which profiles the
+ * caller is allowed to submit against; plugins typically pass
+ * `[input.profile_id!]` since the trigger is bound to one profile.
+ */
+export interface PluginTaskSubmitter {
+    submit(input: PluginTaskInput, callerProfileIds: string[]): Promise<{
+        task_id: string;
+        status: string;
+        created_at: string;
+    }>;
+}
+/**
+ * Session lifecycle mutations the plugin needs for chat-initiated
+ * sessions (e.g. /new in Telegram creates a session before any
+ * dashboard tab has bound to it). Read-only ownership stays on
+ * `core.workspaces`; this surface is for create-and-mutate.
+ */
+export interface PluginSessionLifecycle {
+    /**
+     * Insert a new workspace row + in-memory entry. `persistent` true
+     * survives container teardown; `orgId` defaults to null on OSS.
+     */
+    register(sessionId: string, userId: string, profileId: string, opts?: {
+        persistent?: boolean;
+        orgId?: string | null;
+    }): Promise<{
+        session_id: string;
+        user_id: string;
+        profile_id: string;
+    }>;
+    /** Push expiry forward (ISO-8601 timestamp). */
+    extendExpiry(sessionId: string, expiresAtIso: string): Promise<void>;
+    /** Move the session between status states (e.g. "idle" -> "active"). */
+    setStatus(sessionId: string, status: "active" | "resumable" | "idle" | "expired"): Promise<void>;
+    /** Set of session_ids the dashboard currently has WS-connected. */
+    getConnectedSessionIds(): Set<string>;
+}
+/**
+ * Narrow orchestrator surface plugins call directly. Today this is
+ * just wakeWorkspaceContainer (the "boot a container for this session
+ * before submitting a task to it" call). More methods land here only
+ * with clear plugin need + a justification block on the field.
+ *
+ * `ResolvedProfile` is imported from @vonzio/shared rather than
+ * mirrored structurally -- the type is wide (env, tools, claude_md,
+ * setup_commands, persistent_sessions, ...) and the orchestrator
+ * reads more of it as features land. Mirroring would silently drift.
+ */
+export interface PluginOrchestrator {
+    wakeWorkspaceContainer(sessionId: string, profile: import("@vonzio/shared").ResolvedProfile): Promise<string | null>;
+}
+/**
+ * Append-only session event log used by the dashboard's replay view.
+ * Plugins that bridge an external surface to a session (telegram /new
+ * inbound, slack reply) append user_message events so the dashboard
+ * timeline shows them. Read is used by webhook callback handlers
+ * that need to replay context.
+ */
+export interface PluginEventLog {
+    append(sessionId: string, type: string, data: Record<string, unknown>): void;
+    read(sessionId: string, afterSeq?: number): Array<{
+        seq: number;
+        type: string;
+        data: Record<string, unknown>;
+        ts: number;
+    }>;
+}
+/**
+ * Dashboard WS push. Plugins call this to broadcast an event to the
+ * dashboard tab(s) watching a session (e.g. "an external chat reply
+ * just landed -- here it is in real time"). Same channel core uses
+ * for orchestrator events.
+ */
+export interface PluginConnectionManager {
+    sendToSession(sessionId: string, message: Record<string, unknown>): void;
+}
+/**
+ * Image rewriter for inline `![alt](url)` markdown in agent output.
+ * Chat surfaces that don't render inline images (Telegram) need to
+ * strip the references and queue the URLs for a separate sendPhoto
+ * call. forSession signs the URLs so chat backends fetching them
+ * can authenticate against the preview gateway.
+ */
+export interface PluginImageRewriter {
+    forSession(sessionId: string, text: string): Promise<{
+        textWithUrls: string;
+        textWithoutImages: string;
+        images: Array<{
+            url: string;
+            alt: string;
+            originalUrl: string;
+        }>;
+    } | null>;
+}
+/**
+ * Model picker for chat-side "switch model" interactions. Returns the
+ * available list + the profile's current default so the picker can
+ * mark a "current" pin without a second profile fetch.
+ */
+export interface PluginModelList {
+    listForProfile(profileId: string): Promise<{
+        ok: true;
+        models: Array<{
+            id: string;
+            display_name: string | null;
+            provider: "anthropic" | "ollama";
+        }>;
+        profileDefault: string | null;
+    } | {
+        ok: false;
+        status: number;
+        error: string;
+    }>;
+}
+/**
+ * Extended profile lookup. The existing `PluginProfileLookup` only
+ * does `list(userId)`; chat surfaces also need to resolve a single
+ * profile's full ResolvedProfile (model defaults, allowed tools,
+ * setup commands, etc.) to hand to `core.orchestrator.wakeWorkspaceContainer`.
+ *
+ * Kept on a separate field rather than widening PluginProfileLookup
+ * so plugins that need only `.list()` aren't forced to depend on the
+ * full ResolvedProfile type tree.
+ */
+export interface PluginProfileResolver {
+    getResolved(profileId: string): Promise<import("@vonzio/shared").ResolvedProfile | null>;
+}
+/**
+ * Core services exposed to plugins. Add fields here only with strong
+ * justification -- the surface is a stability commitment.
+ */
+export interface PluginCore {
+    /**
+     * Drizzle handle. Plugins should only query their own tables; cross-
+     * table access requires going through a documented core call (none
+     * yet defined for v0.1). Typed as `unknown` in the contract -- the
+     * loader injects the real handle. Plugins cast to
+     * `NodePgDatabase<typeof pluginSchema>`.
+     */
+    db: unknown;
+    /**
+     * AES-256-GCM wrapper around the master vault key. Use this for
+     * any plugin-owned secret that lands in the DB (OAuth tokens, API
+     * keys, bot tokens). Never log decrypted values; never persist them
+     * outside the encryption flow.
+     */
+    encryption: {
+        encrypt(plaintext: string): string;
+        decrypt(ciphertext: string): string;
+    };
+    /**
+     * Integration lookup. Plugins resolve `req.recipient` against this
+     * to get the credentials + config for the user's connected
+     * provider (Slack workspace, Telegram bot, etc.).
+     */
+    integrations: PluginIntegrationLookup;
+    /**
+     * Profile lookup (read-only). Plugins use this when validating
+     * profile_ids in their own routes.
+     */
+    profiles: PluginProfileLookup;
+    /**
+     * Workspace lookup (read-only). Plugins use this for ownership
+     * checks on workspace-bound resources.
+     */
+    workspaces: PluginWorkspaceLookup;
+    /**
+     * Auth hook plugins can opt into. Plugins with routes that need
+     * authenticated access call
+     * `server.addHook("onRequest", ctx.core.authHook)` inside their
+     * route registration scope. v0.1 mirrors what core wires onto the
+     * /v1 fastify subscope -- a session-cookie-or-bearer check that
+     * populates request.user on success and returns 401 otherwise.
+     *
+     * Plugins whose routes are public (e.g. webhook receivers verified
+     * via a shared secret) skip this entirely.
+     */
+    authHook: import("fastify").onRequestHookHandler;
+    /**
+     * Where plugins contribute a chat-surface presence provider. Lets
+     * core's orchestrator + ask-user-fallback + workspace-service ask
+     * "is this session reachable on a chat surface?" without reading
+     * plugin-owned tables directly. The plugin's provider does the
+     * actual DB read.
+     */
+    sessionPresence: PluginSessionPresenceRegistry;
+    /**
+     * Submit new tasks from a plugin (e.g. a chat surface received a
+     * user message; submit a session task with the prompt). Same gate
+     * as the dashboard's submit route: caller must have access to the
+     * profile via callerProfileIds.
+     */
+    tasks: PluginTaskSubmitter;
+    /**
+     * Mutate session state. Used by chat surfaces that initiate
+     * sessions from outside the dashboard (e.g. Telegram /new).
+     */
+    sessionLifecycle: PluginSessionLifecycle;
+    /**
+     * Orchestrator surface: wake a workspace container for a session
+     * before submitting a task. Plugins call this from their session-
+     * resume codepath after pairing a chat message with an existing
+     * workspace.
+     */
+    orchestrator: PluginOrchestrator;
+    /**
+     * Append-only event log. Plugins write user_message events when
+     * relaying inbound chat messages so they show up in the dashboard
+     * timeline; read is used by webhook handlers that need session
+     * context.
+     */
+    eventLog: PluginEventLog;
+    /**
+     * Dashboard WS push surface. Plugins use it to broadcast events
+     * sourced from the external chat into the dashboard view of the
+     * session.
+     */
+    connectionManager: PluginConnectionManager;
+    /**
+     * Image rewriter for chat surfaces that don't render inline
+     * markdown images. Returns the stripped text + a signed-URL list
+     * the plugin can hand to the chat API's sendPhoto-equivalent.
+     */
+    imageRewriter: PluginImageRewriter;
+    /**
+     * Model list lookup for chat-side model pickers.
+     */
+    modelList: PluginModelList;
+    /**
+     * Resolved profile lookup (full ResolvedProfile shape). Required
+     * before calling `orchestrator.wakeWorkspaceContainer`. Separate
+     * from `profiles.list` to keep plugins that need only listing from
+     * pulling in the wider type tree.
+     */
+    profileResolver: PluginProfileResolver;
+}
+/** Minimal logger contract. Backed by core's pino logger at runtime. */
+export interface PluginLogger {
+    info(meta: Record<string, unknown> | string, msg?: string): void;
+    warn(meta: Record<string, unknown> | string, msg?: string): void;
+    error(meta: Record<string, unknown> | string, msg?: string): void;
+    debug(meta: Record<string, unknown> | string, msg?: string): void;
+}
+/**
+ * One outbound notification request. Core services hand these to the
+ * notification bus, which dispatches to whichever plugin claimed the
+ * `kind`.
+ */
+export interface NotificationRequest {
+    /**
+     * The channel family this request targets. Plugins claim a kind in
+     * `init()` via `notificationBus.registerHandler(kind, handler)`.
+     * Examples: `"telegram"`, `"slack"`, `"email"`.
+     */
+    kind: string;
+    /**
+     * Plugin-specific recipient identifier. For most plugins this is
+     * the user-integration id; the plugin uses it to look up the right
+     * bot token, channel, thread, etc. in its own DB.
+     */
+    recipient: string;
+    /** Human-readable body. Plugins may format-translate before sending. */
+    text: string;
+    /** Free-form per-message metadata (e.g. priority, thread anchors). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Plugin-side notification handler. Returns a result so callers (and
+ * core's retry/circuit-breaker machinery) can react. Never throws --
+ * unexpected errors should be wrapped into `{ ok: false, retryable }`.
+ */
+export type NotificationHandler = (req: NotificationRequest) => Promise<NotificationResult>;
+export type NotificationResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    retryable: boolean;
+};
+/**
+ * Where plugins register notification handlers. One handler per
+ * kind -- attempting to register a second handler for the same kind
+ * is an error (caught at boot).
+ */
+export interface NotificationBus {
+    registerHandler(kind: string, handler: NotificationHandler): void;
+}
+/**
+ * Spec for an MCP server the plugin contributes. The loader hands
+ * these to the core MCP runtime, which exposes them to agents
+ * according to the agent's profile config.
+ */
+export interface McpServerSpec {
+    /** Identifier shown in agent-side MCP listings. */
+    name: string;
+    /**
+     * How agents reach the server. `stdio` = spawn a process per agent
+     * session; `http` = a single endpoint reachable by all sessions.
+     *
+     * For `http`, `url` MUST be an absolute PATH (e.g. `/plugins/teller/mcp`) — the
+     * plugin serves its MCP route via `ctx.server` and core resolves the path
+     * against its internal server URL at injection time, so the plugin needn't
+     * know the internal host. External / protocol-relative / traversing urls are
+     * REFUSED at `registerServer`: core attaches a per-task bearer token and that
+     * token must never leave the deployment. Core adds the `Authorization` header
+     * itself; the plugin's route resolves it via {@link McpSessions.resolve}.
+     */
+    transport: {
+        type: "stdio";
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+    } | {
+        type: "http";
+        url: string;
+    };
+}
+export interface McpRegistry {
+    registerServer(spec: McpServerSpec): void;
+}
+/**
+ * Identity behind a per-task token core minted when it injected the plugin's
+ * MCP server into an agent container. The plugin's MCP HTTP route reads the
+ * `Authorization: Bearer <token>` header and resolves it here to scope the
+ * call to the right user / profile / tenant. Gated by `mcp.register`.
+ */
+export interface McpSessions {
+    /** Resolve a per-task MCP token, or null if unknown/expired. */
+    resolve(token: string): {
+        userId: string;
+        profileId: string;
+        orgId: string | null;
+    } | null;
+}
+/**
+ * Scheduled work the plugin owns. Core cancels everything registered
+ * here during teardown; plugins don't need to track timer handles.
+ */
+export interface Scheduler {
+    /**
+     * Standard 5-field cron expression, evaluated in UTC. `name` is for
+     * logging + dedup -- registering the same name twice is an error.
+     */
+    cron(name: string, schedule: string, fn: () => Promise<void>): void;
+    /**
+     * Fixed-interval job. `ms` is the gap BETWEEN runs (not from start),
+     * so a slow fn won't queue up backlog.
+     */
+    interval(name: string, ms: number, fn: () => Promise<void>): void;
+}
+/**
+ * The auth-decorated user attached to a FastifyRequest by core's
+ * userAuthHook. Plugins receive this as `request.user` inside any
+ * route that runs under an auth-gated scope (e.g. /v1/*).
+ *
+ * Plugins typed against this interface should cast at the request
+ * site -- `const user = request.user as AuthUser` -- because the
+ * module augmentation that sets `user?: AuthUser` on FastifyRequest
+ * lives in core-server's auth/user-auth.ts; declaring it again here
+ * would create a conflicting declaration in plugin-api's tsconfig
+ * project.
+ *
+ * The shape mirrors core's AuthUser (id + email + role + minor
+ * fields) but is structurally typed here so plugin-api doesn't have
+ * to import from core-server.
+ */
+export interface AuthUser {
+    id: string;
+    email: string;
+    name?: string;
+    role: string;
+    feature_flags?: string;
+}
+/**
+ * Per-plugin key/value store (`ctx.storage`). Backed by the core-owned
+ * `plugin_storage` table; every read/write is filtered server-side by the
+ * plugin's id, so one plugin cannot read another's keys via this surface.
+ * Gated by the `storage.kv` capability. See §5.
+ */
+export interface PluginStorageKv {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
+}
+/**
+ * Audited outbound HTTP/WS surface (`ctx.http`). Gated by `http.outbound`.
+ * Every call resolves the hostname, blocks SSRF targets (private/link-local
+ * IPs, DNS rebinding), and requires the host to match the manifest∩policy
+ * `outboundHosts` allowlist. See §10.
+ *
+ * `fetch` returns a real WHATWG `Response`, so existing `.json()` / `.ok` /
+ * `.text()` / `.arrayBuffer()` call sites keep working — binary downloads use
+ * `.arrayBuffer()` and are not corrupted (the bytes are preserved end to end).
+ */
+export interface PluginHttpInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array | FormData;
+    /** Per-call timeout override (ms), capped at 30s. */
+    timeoutMs?: number;
+    /** Per-call max response size override (bytes), capped at 5 MiB. */
+    maxResponseBytes?: number;
+    /**
+     * Present a client certificate for mutual TLS on this call. Pass an
+     * {@link MtlsRef} obtained from `ctx.secrets.mtls(name)` — core reads the
+     * operator-provisioned cert/key files server-side at request time; the cert
+     * material never passes through plugin code. Gated by `secrets.mtls`. See §10.
+     */
+    mtls?: MtlsRef;
+}
+export interface PluginHttp {
+    fetch(url: string, init?: PluginHttpInit): Promise<Response>;
+}
+/**
+ * Opaque handle to operator-provisioned mTLS client material, resolved from a
+ * logical name the plugin declared in `manifest.mtlsSecrets`. The plugin CANNOT
+ * read the cert/key bytes through this object — it carries only the logical
+ * `name`. The cert/key files are read server-side when the ref is passed to
+ * `ctx.http.fetch({ mtls })`. See §5, §10.
+ */
+export interface MtlsRef {
+    /** Brand: lets the HTTP surface recognize a genuine ref and keeps the type
+     *  nominal to plugin authors. */
+    readonly __vonzioMtls: true;
+    /** The logical secret name — the only field a plugin can observe. */
+    readonly name: string;
+}
+/**
+ * Secret-material resolution surface (`ctx.secrets`). Gated by `secrets.mtls`.
+ * v1 exposes only mTLS client certs as opaque {@link MtlsRef}s; the bytes are
+ * never readable through this surface (the operator provisions them as host
+ * files in policy and core loads them server-side at request time).
+ */
+export interface PluginSecrets {
+    /**
+     * Resolve a declared mTLS secret `name` (from `manifest.mtlsSecrets`) into an
+     * opaque ref for `ctx.http.fetch({ mtls })`. Throws `CapabilityViolationError`
+     * if the name was not declared + provisioned.
+     */
+    mtls(name: string): MtlsRef;
+}
+export { PLUGIN_CAPABILITIES, CAPABILITY_SURFACE_MAP, ROOT_EQUIVALENT_COMBINATIONS, BUILTIN_ONLY_CAPABILITIES, isPluginCapability, } from "./capabilities.js";
+export type { PluginCapability, CapabilitySurface, SurfaceKind } from "./capabilities.js";
+export { MANIFEST_ALLOWED_KEYS, POLICY_ENTRY_ALLOWED_KEYS, SCHEMA_PREFIX_PATTERN, MTLS_SECRET_NAME_PATTERN, } from "./manifest.js";
+export type { PluginManifest, ManifestRoutePrefix, MtlsSecretFiles, PluginSource, PolicyEntry, OperatorPolicy, } from "./manifest.js";
+export { validateManifest, validatePolicy, matchOutboundHost, normalizeHostPattern, } from "./manifest-validate.js";
+export type { ManifestValidationResult } from "./manifest-validate.js";
+export { CapabilityViolationError, OutboundHostViolationError, DbScopeViolationError, PluginRefusedError, PolicyViolationError, REFUSAL_REASONS, } from "./errors.js";
+export type { RefusalReason } from "./errors.js";
+export { assertApiCompatible } from "./version.js";
+/**
+ * Structural shape the loader needs from a plugin's `configSchema`.
+ * Both zod v3 and v4 satisfy this naturally -- they both expose a
+ * `parse(input): T` method. Plugins typically use `z.object({...})`
+ * which yields a `ZodObject` whose `.parse()` returns the inferred
+ * shape; the inference flows into TConfig.
+ */
+export interface ConfigSchemaLike<TConfig> {
+    parse(input: unknown): TConfig;
+}
+//# sourceMappingURL=index.d.ts.map