@makinbakin/sdk 0.0.1-rc.4 → 0.0.1-rc.40

package/_internal/core/plugin-types.d.ts

@@ -1,8 +1,24 @@
 /**
- * Plugin system type definitions for Bakin.
- * All plugin interfaces are defined here — no behavioral changes.
+ * Plugin system type definitions for Bakin (the internal, in-process surface).
+ *
+ * Two-tier contract — read before "deduplicating" against the SDK:
+ * `@makinbakin/sdk/types` is the PUBLISHED, self-contained, deliberately
+ * NARROWER plugin-author surface; this file is the INTERNAL surface that
+ * in-process core plugins actually receive. They are NOT a fork to collapse.
+ * Concretely:
+ *   - `PluginContext.runtime` here is the FULL `AgentRuntimeAdapter`
+ *     (adapters/runtime/concepts.ts: agents×11, tools, sessions, memory,
+ *     config, images, media, restart…). Core plugins use ~15 full-only
+ *     methods. The SDK exposes a curated subset.
+ *   - `ctx.tasks` here returns the `PluginTask` projection; the SDK returns
+ *     `Task`. `BakinPlugin` here adds `routes?`. `StorageAdapter`/`NavItem`/
+ *     `APIRoute`/`HookAPI`/`SkillDefinition` are intentionally fuller here.
+ * Genuinely-identical LEAF data types (health, exec-result, search, manifest,
+ * EventBus/ActivityAPI/PluginLogger, TaskLogEntry, …) ARE single-homed in the
+ * SDK and re-exported below. Collapsing the boundary itself is WS2 work.
  */
-import type { ZodRawShape, ZodType } from 'zod';
+import type { z, ZodRawShape, ZodType } from 'zod';
+import type { ActivityAPI, ActivityClass, ConversationTurnsAPI, EventBus, ExecToolResult, HealthCheckRegistrationInput, HealthOwner, HealthRepairActionDefinition, PluginLogger, SearchAPI, TaskLogEntry } from '@makinbakin/sdk/types';
 import type { ContractStability, ContractVisibility, DocsExample, SchemaLike, SourceLocation } from './docs';
 import type { AgentRuntimeAdapter } from './adapters/runtime';
 import type { APIRoute as DeclarativeAPIRoute, PluginContextLite } from './routing/types';
@@ -12,23 +28,25 @@ export interface ApprovalActor {
     source: 'channel' | 'web' | 'system';
 }
 export interface StorageAdapter {
+    /** Absolute private root when backed by a local filesystem. Not browser assets. */
+    readonly localRoot?: string;
     read(path: string): string | null;
     write(path: string, content: string): void;
     append(path: string, content: string): void;
     exists(path: string): boolean;
     readAll(): Record<string, string>;
-    list?(path?: string): string[];
-    remove?(path: string): void;
-    rename?(from: string, to: string): void;
-    stat?(path: string): {
+    list(path?: string): string[];
+    remove(path: string): void;
+    rename(from: string, to: string): void;
+    stat(path: string): {
         path: string;
         size: number;
         mtimeMs: number;
         isFile: boolean;
         isDirectory: boolean;
     } | null;
-    readJson?<T = unknown>(path: string): T | null;
-    writeJson?(path: string, value: unknown): void;
+    readJson<T = unknown>(path: string): T | null;
+    writeJson(path: string, value: unknown): void;
     /**
      * Convert a plugin-storage-relative path or glob to the content-dir-relative
      * path seen by file-backed search/watch APIs. Implementations never return
@@ -36,11 +54,8 @@ export interface StorageAdapter {
      */
     searchPath?(path: string): string;
 }
-export interface EventBus {
-    emit(event: string, data?: Record<string, unknown>): void;
-    on(pattern: string, handler: (event: string, data: Record<string, unknown>) => void): () => void;
-    once(pattern: string, handler: (event: string, data: Record<string, unknown>) => void): () => void;
-}
+export type { EventBus } from '@makinbakin/sdk/types';
+export type NavSection = 'plan-and-automate' | 'create' | 'operations';
 export interface NavItem {
     id: string;
     label: string;
@@ -48,9 +63,17 @@ export interface NavItem {
     href: string;
     order?: number;
     children?: NavItem[];
-    alwaysExpanded?: boolean;
+    section?: NavSection;
 }
-export interface APIRoute {
+/**
+ * INTERNAL registered-route record — the erased shape routes take inside the
+ * plugin registry's state after declarative registration (typed schemas
+ * survive as extra fields the dispatcher reads). NOT a public authoring
+ * type: plugin authors declare routes with `defineRoute()` and the
+ * declarative-generic `APIRoute<C, P, Q, B>` from `@bakin/core/routing` /
+ * `@makinbakin/sdk` (audit 2026-07 H3 collapsed the two same-named types).
+ */
+export interface RegisteredAPIRoute {
     path: string;
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     handler: (req: Request, ctx: PluginContext) => Response | Promise<Response>;
@@ -64,6 +87,7 @@ export interface APIRoute {
     examples?: DocsExample[];
     source?: SourceLocation;
     permissions?: string[];
+    activityClass?: ActivityClass;
 }
 export interface UISlotRegistration {
     slot: string;
@@ -73,16 +97,14 @@ export interface UISlotRegistration {
 export interface ContentFile {
     path: string;
 }
-/** Result returned by execution tool handlers */
-export interface ExecToolResult {
-    ok: boolean;
-    error?: string;
-    details?: unknown;
-    [key: string]: unknown;
-}
+export type { ExecToolResult } from '@makinbakin/sdk/types';
 /** Definition for a registerable execution tool */
 /** Context available to exec tool handlers — provides access to plugin services */
 export interface PluginToolContext {
+    /** Set only by a verified transport, never from tool parameters. */
+    invocation?: {
+        agentId: string;
+    };
     storage: StorageAdapter;
     events: EventBus;
     pluginId: string;
@@ -94,13 +116,17 @@ export interface PluginToolContext {
     activity: ActivityAPI;
     getSettings<T = Record<string, unknown>>(): T;
 }
-export interface ExecToolDefinition {
+export interface ExecToolDefinition<Shape extends ZodRawShape = ZodRawShape> {
+    /** Reject unverified HTTP/MCP callers before invoking the handler. */
+    requiresVerifiedAgent?: boolean;
     name: string;
     description: string;
     label?: string;
     activityDuplicate?: boolean;
-    parameters: ZodRawShape;
-    handler: (params: Record<string, unknown>, agent: string, ctx?: PluginToolContext) => Promise<ExecToolResult>;
+    activityClass?: ActivityClass;
+    parameters: Shape;
+    /** Params are inferred from `parameters` — declare the shape once, get typed params. */
+    handler: (params: z.infer<z.ZodObject<Shape>>, agent: string, ctx?: PluginToolContext) => Promise<ExecToolResult>;
     source?: string;
 }
 /** A skill that can be registered by plugins or loaded from disk */
@@ -109,6 +135,16 @@ export interface SkillDefinition {
     instructions: string;
     output_schema?: Record<string, unknown>;
     source?: string;
+    /** Absolute source markdown file path when the skill was loaded from a managed package/plugin file. */
+    sourcePath?: string;
+}
+export interface WorkflowLayoutInput {
+    positions?: Record<string, {
+        x: number;
+        y: number;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
 }
 export interface WorkflowDefinitionInput {
     /** Stable workflow id. Falls back to slug(name) when omitted. */
@@ -117,23 +153,11 @@ export interface WorkflowDefinitionInput {
     description: string;
     version: number;
     inputs?: Record<string, unknown>;
+    layout?: WorkflowLayoutInput;
     steps: unknown[];
+    [key: string]: unknown;
 }
-export interface ActivityAPI {
-    /** Log a human-readable message to the live activity feed */
-    log(agent: string, message: string, opts?: {
-        taskId?: string;
-        category?: string;
-    }): void;
-    /** Log a structured audit event */
-    audit(event: string, agent: string, data?: Record<string, unknown>): void;
-}
-export interface PluginLogger {
-    debug(message: string, data?: Record<string, unknown>): void;
-    info(message: string, data?: Record<string, unknown>): void;
-    warn(message: string, errorOrData?: unknown, data?: Record<string, unknown>): void;
-    error(message: string, errorOrData?: unknown, data?: Record<string, unknown>): void;
-}
+export type { ActivityAPI, PluginLogger } from '@makinbakin/sdk/types';
 export interface HookAPI {
     /** Register a handler for a named hook. Returns unsubscribe function. */
     register(name: string, handler: (data: any) => any, metadata?: HookRegistrationMetadata): () => void;
@@ -200,7 +224,7 @@ export interface PluginNodeTypeInput<T = unknown> {
  * is prepended to `id` automatically (`{pluginId}.{id}`), matching the node-
  * type precedent. Built-in workflows-plugin runtime channels (general,
  * announcements, alerts, email) self-register at module load in
- * `plugins/workflows/lib/notification-channel-registry.ts`.
+ * `packages/core/src/workflows/notification-channel-registry.ts`.
  */
 export interface PluginNotificationChannelInput {
     id: string;
@@ -215,71 +239,18 @@ export interface NotificationChannelDef extends PluginNotificationChannelInput {
     /** Set when runtime === 'plugin'; identifies the owning plugin. */
     pluginId?: string;
 }
-/**
- * Canonical result shape for a single doctor check row.
- */
-export interface HealthCheckResult {
-    check: string;
-    status: 'ok' | 'warn' | 'error' | 'fixed';
-    message: string;
-    autoFixable: boolean;
-}
-export type HealthRepairSafety = 'safe' | 'manual' | 'destructive';
-export interface HealthRepairChange {
-    kind: 'file' | 'setting' | 'service' | 'runtime' | 'task' | 'other';
-    target: string;
-    action: 'create' | 'update' | 'delete' | 'install' | 'invoke';
-    description: string;
-}
-export interface HealthRepairPlanItem {
+export type { ActionIncidentInput, AdvisoryIncidentInput, CanonicalErrorObservation, CanonicalHealthyObservation, CanonicalUnknownObservation, CanonicalWarningObservation, ErrorObservationInput, HealthCheckExecution, HealthCheckRegistrationInput, HealthCheckRunContext, HealthCheckRunInput, HealthCheckSnapshot, HealthCheckState, HealthDisposition, HealthFullSweep, HealthGroup, HealthIncident, HealthIncidentInput, HealthInstructionsResolution, HealthNavigateResolution, HealthNonEmptyArray, HealthObservation, HealthObservationInput, HealthObservationStatus, HealthOwner, HealthOwnerKind, HealthRepairActionDefinition, HealthRepairApplyRequest, HealthRepairApplyResult, HealthRepairSafety, HealthRepairChange, HealthRepairPlanItem, HealthRepairPlan, HealthRepairPrecondition, HealthRepairResolution, HealthRepairTarget, HealthReport, HealthReportStatus, HealthReportSummary, HealthResolution, HealthResource, HealthResourceKind, HealthRerunResolution, HealthyObservationInput, JsonObject, JsonValue, NotApplicableHealthCheckRunInput, ObservedHealthCheckRunInput, SearchReadiness, SearchReadinessStage, SearchReadinessStageKey, SearchReadinessStatus, SearchStageStatus, UnknownObservationInput, WarningObservationInput, WatchIncidentInput, } from '@makinbakin/sdk/types';
+/** Core-internal canonical registration with its resolved owner and local id. */
+export interface HealthCheckDef extends HealthCheckRegistrationInput {
     id: string;
-    checkId: string;
-    title: string;
-    reason: string;
-    safety: HealthRepairSafety;
-    requiresConfirmation: boolean;
-    changes: HealthRepairChange[];
+    localId: string;
+    owner: HealthOwner;
 }
-export interface HealthRepairApplyResult {
+/** Core-internal canonical repair action with its resolved owner and local id. */
+export interface HealthRepairActionDef extends HealthRepairActionDefinition {
     id: string;
-    checkId: string;
-    status: 'applied' | 'skipped' | 'failed';
-    message: string;
-    changes: HealthRepairChange[];
-}
-export interface HealthRepairHandler {
-    plan(rows: HealthCheckResult[]): Promise<HealthRepairPlanItem[]>;
-    apply(items: HealthRepairPlanItem[]): Promise<HealthRepairApplyResult[]>;
-}
-/**
- * Input shape plugins pass to `ctx.registerHealthCheck`. The plugin id is
- * auto-namespaced as `{pluginId}.{id}`. `run()` returns an array so one
- * registered check can contribute multiple result rows (mirrors how the
- * existing `checkPersonas` returns one per agent).
- */
-export interface PluginHealthCheckInput {
-    id: string;
-    name: string;
-    /**
-     * Runs the check, returns any number of result rows. Throws/rejects are
-     * caught by the doctor orchestrator and converted to a synthetic error
-     * result — a single bad handler never crashes the sweep.
-     */
-    run: () => Promise<HealthCheckResult[]>;
-    /**
-     * Legacy advisory flag for older admin surfaces. New code should derive
-     * repairability from `repair`.
-     */
-    autoFix?: boolean;
-    /**
-     * Optional explicit repair contract. Diagnostics call only `run()`; repair
-     * flows call `plan()` first, then `apply()` after explicit confirmation.
-     */
-    repair?: HealthRepairHandler;
-}
-export interface HealthCheckDef extends PluginHealthCheckInput {
-    runtime: 'plugin';
-    pluginId: string;
+    localId: string;
+    owner: HealthOwner;
 }
 export interface PluginContext {
     storage: StorageAdapter;
@@ -289,25 +260,17 @@ export interface PluginContext {
     tasks: PluginTaskService;
     assets: AssetsAPI;
     registerNav(items: NavItem[]): void;
-    /**
-     * @deprecated Use `definePlugin({ routes: [defineRoute({...})] })` to declare
-     * routes. This adapter remains during the migration window for any
-     * out-of-tree plugin that still calls `ctx.registerRoute(...)` from
-     * `activate()`. In-repo plugins migrated in T6–T13 / T20 — none of them
-     * call this. The dispatcher adapts the legacy shape (input → body,
-     * output → responses[200]) when invoked through this path.
-     */
-    registerRoute(route: APIRoute): void;
     registerSlot(registration: UISlotRegistration): void;
-    registerExecTool(tool: ExecToolDefinition): void;
+    registerExecTool<Shape extends ZodRawShape>(tool: ExecToolDefinition<Shape>): void;
     registerSkill(skill: SkillDefinition): void;
     /**
      * Register a workflow definition shipped by this plugin. Disk-resident
      * user definitions in `~/.bakin/workflows/definitions/` always win on id
      * collision (user-wins). A second plugin claiming an id already taken by
-     * another plugin is a containment error: it's logged but does not throw
-     * out of `activate()`. Re-registering the same id from the same plugin
-     * is idempotent (newer wins) so hot reload works.
+     * another plugin THROWS out of `activate()` (R18 — the activation fails
+     * and the plugin's partial registrations are swept). Re-registering the
+     * same id from the same plugin is an update (newer wins) so hot reload
+     * works.
      */
     registerWorkflow(definition: WorkflowDefinitionInput, opts?: {
         readOnly?: boolean;
@@ -334,7 +297,9 @@ export interface PluginContext {
      * sweep — throws are isolated, a single bad check never crashes the
      * doctor. Returns the namespaced id.
      */
-    registerHealthCheck(def: PluginHealthCheckInput): string;
+    registerHealthCheck(def: HealthCheckRegistrationInput): string;
+    /** Register an owner-local repair action referenced by Health observations. */
+    registerHealthRepairAction(def: HealthRepairActionDefinition): string;
     watchFiles(patterns: string[]): void;
     /** Read this plugin's persisted settings */
     getSettings<T = Record<string, unknown>>(): T;
@@ -342,12 +307,14 @@ export interface PluginContext {
     updateSettings(patch: Record<string, unknown>): void;
     /** Structured activity logging */
     activity: ActivityAPI;
-    /** Plugin-scoped server log. Prefer this over console.* for lifecycle logs. */
-    log?: PluginLogger;
+    /** Plugin-scoped server log. Always provided; prefer over console.*. */
+    log: PluginLogger;
     /** Cross-plugin hook registration */
     hooks: HookAPI;
     /** Adapter-backed search — register content types, index, query */
     search: SearchAPI;
+    /** Shared conversation turn engine — background turns for chat-like surfaces (#703) */
+    conversations: ConversationTurnsAPI;
 }
 export type PluginTaskColumn = 'backlog' | 'todo' | 'inProgress' | 'review' | 'done' | 'blocked' | 'archived';
 export interface PluginTask {
@@ -366,6 +333,7 @@ export interface PluginTask {
     workflowId?: string;
     scheduleJobId?: string;
     projectId?: string;
+    brandId?: string;
     availableAt?: string;
     dueAt?: string;
     source?: PluginTaskSource;
@@ -379,12 +347,7 @@ export interface PluginTaskSource {
     entityId?: string;
     purpose?: string;
 }
-export interface TaskLogEntry {
-    timestamp: string;
-    author: string;
-    message: string;
-    data?: Record<string, unknown>;
-}
+export type { TaskLogEntry } from '@makinbakin/sdk/types';
 export interface PluginTaskCreateInput {
     id?: string;
     title: string;
@@ -395,6 +358,7 @@ export interface PluginTaskCreateInput {
     date?: string;
     workflowId?: string;
     projectId?: string;
+    brandId?: string;
     parentId?: string | null;
     availableAt?: string;
     dueAt?: string;
@@ -413,6 +377,7 @@ export interface PluginTaskUpdateInput {
     workflowId?: string;
     scheduleJobId?: string;
     projectId?: string;
+    brandId?: string;
     parentId?: string | null;
     availableAt?: string | null;
     dueAt?: string | null;
@@ -428,349 +393,154 @@ export interface PluginTaskService {
         column?: PluginTaskColumn;
         agent?: string;
         projectId?: string;
+        brandId?: string;
     }): Promise<PluginTask[]>;
     appendLog(id: string, entry: TaskLogEntry): Promise<void>;
 }
-export interface AssetVariantMeta {
-    role: 'thumbnail' | 'optimized' | 'webp';
-    path: string;
-    filename: string;
-    size: number;
-    mimeType: string;
-}
-export interface AssetMeta {
-    path: string;
-    filename: string;
-    type: 'text' | 'images' | 'video' | 'audio' | 'plans' | 'research' | 'pdf' | 'data' | 'other';
-    mimeType: string;
-    size: number;
-    mtimeMs?: number;
-    metadata: {
-        agent: string;
-        taskId: string | null;
-        created: string;
-        tool?: string;
-        description?: string;
-        tags?: string[];
-        originalFilename?: string;
+/** The asset type taxonomy (mirrors ASSET_TYPES in the assets plugin). */
+export type AssetTypeName = 'text' | 'images' | 'video' | 'audio' | 'plans' | 'research' | 'pdf' | 'data' | 'other';
+/** Per-version generation provenance (matches the manifest's `generation` block). */
+export interface AssetGenerationInfo {
+    provider: string;
+    model: string;
+    surface: string;
+    /** Honored only on the shim path; native generations omit it (#379). */
+    quality?: string;
+    routeSource: string;
+    routeReason?: string;
+    /** Reference/context images that conditioned this generation (#418). */
+    references?: Array<{
+        assetId: string;
+        version: number;
+    }>;
+    /** Brand provenance (#419): brand id + content fingerprint as-used. */
+    brandId?: string;
+    brandFingerprint?: string;
+}
+/** Create a new versioned asset (v1) from a source file. */
+export interface AssetCreateInput {
+    sourceFilePath: string;
+    type: AssetTypeName;
+    agent: string;
+    taskId: string | null;
+    slug?: string;
+    op?: 'generate' | 'upload' | 'import';
+    tool?: string | null;
+    prompt?: string | null;
+    promptHash?: string | null;
+    description?: string;
+    tags?: string[];
+    source?: {
+        kind: 'generated' | 'upload' | 'import' | 'clipboard' | 'workspace-file';
+        path: string | null;
     };
-    variants?: AssetVariantMeta[];
-}
-export interface AssetFileRef {
-    kind: 'asset';
-    filename: string;
-    mimeType?: string;
-}
-export interface AssetsAPI {
-    getByFilename(filename: string): Promise<AssetMeta | null>;
-    list(filter?: {
-        type?: AssetMeta['type'];
-        taskId?: string | null;
-    }): Promise<AssetMeta[]>;
-    exists(filename: string): Promise<boolean>;
-    fileRef(filename: string): Promise<AssetFileRef>;
-}
-/** Field type for search content type schemas */
-export interface SearchSchemaField {
-    type: 'text' | 'keyword' | 'number' | 'boolean' | 'datetime' | 'array';
+    generation?: AssetGenerationInfo | null;
 }
 /**
- * One vector index on a search table. A content type can declare multiple
- * indexes to embed the same document into several vector spaces — e.g. a
- * text index using BGE and a visual index using CLIP on the assets table.
- * Each index has its own embedder (resolved via embedderRef), input
- * declaration, and optional chunker config.
+ * Append a new version to an existing asset. Note: no `tags` — tags are an
+ * asset-level organizational namespace that versioning never touches.
  */
-export interface SearchIndexDefinition {
-    /** Index name as stored by the search adapter. Must be stable across restarts. */
-    name: string;
-    /** Ref into settings.search.settings.embedders — 'default', 'visual', or custom. */
-    embedderRef: string;
-    /** Handlebars template for this index's text embedding input. */
-    embeddingTemplate?: string;
-    /**
-     * Document field containing a URL to media bytes for visual/multimodal
-     * embedding input. The search adapter owns provider-specific helper syntax.
-     */
-    mediaUrlField?: string;
-    /** Per-index chunker config, overrides any table-level default. */
-    chunker?: {
-        enabled: boolean;
-        targetTokens?: number;
-        overlapTokens?: number;
-    };
-}
-/** Definition for a searchable content type registered by a plugin */
-export interface SearchContentTypeDefinition {
-    /** Table name — auto-prefixed with `bakin_`. E.g., 'tasks' → 'bakin_tasks' */
-    table: string;
-    /** Schema for the document fields */
-    schema: Record<string, SearchSchemaField>;
-    /** Fields to include in full-text search */
-    searchableFields: string[];
-    /**
-     * Handlebars template for embedding generation. Used when `indexes` is
-     * not provided — the registry synthesizes a single default index named
-     * `embeddings` with this template and the default embedder.
-     */
-    embeddingTemplate: string;
-    /**
-     * Optional per-index definitions. When provided, overrides
-     * `embeddingTemplate` and creates one embedding index per entry with
-     * its own embedder. Used by content types that want multimodal indexing
-     * (e.g. assets with both a text index and a visual index).
-     */
-    indexes?: SearchIndexDefinition[];
-    /** Fields to expose as aggregatable facets */
-    facets?: string[];
-    /**
-     * Document field to use as input for the cross-encoder reranker. When
-     * set, queries against this content type attach the configured reranker
-     * and score the query-document pair using the value at this field.
-     * When unset, queries skip reranking for this content type.
-     */
-    rerankField?: string;
-    /** TTL duration (Go format: '24h', '7d', '30d') */
-    ttl?: string;
-    /** TTL field (defaults to 'created_at') */
-    ttlField?: string;
-    /** Chunking config for long documents — used by the synthesized default index. */
-    chunker?: {
-        enabled: boolean;
-        targetTokens?: number;
-        overlapTokens?: number;
-    };
-    /**
-     * Backfill function — called during full/per-table reindex.
-     * Must yield ALL documents for this content type from source.
-     */
-    reindex: () => AsyncGenerator<{
-        key: string;
-        doc: Record<string, unknown>;
-    }>;
-    /**
-     * Existence check — called during orphan cleanup.
-     * Returns true if the source document for this key still exists.
-     */
-    verifyExists: (key: string) => Promise<boolean>;
-}
-/** Parameters for a search query */
-export interface SearchQueryParams {
-    /** Search query string */
-    q: string;
-    /** Structured keyword filters */
-    filters?: Record<string, string | boolean | number>;
-    /** Facets to include in aggregations */
-    facets?: string[];
-    /** Max results */
-    limit?: number;
-    /** Result offset for pagination */
-    offset?: number;
-    /**
-     * Whether to run the cross-encoder reranker on results. Defaults to
-     * true when the reranker is enabled in settings. Set false for latency-
-     * sensitive paths (facet-only queries, ID lookups, bulk scans) where
-     * the extra ~100-500ms isn't worth it.
-     */
-    rerank?: boolean;
-    /**
-     * Raw adapter-specific aggregations passed through unchanged to the query layer.
-     * Use for date histograms, range buckets, stats aggregations, or any
-     * other shape beyond the term-facet convenience in `facets`. Merged
-     * with facet-derived aggregations (these win on key collision).
-     * See the active search adapter docs for the aggregation schema.
-     */
-    aggregations?: Record<string, unknown>;
-    /**
-     * Search strategy override. Defaults to the site-wide search strategy.
-     * Pass 'full_text_only' for filter-driven
-     * counts or ID lookups — semantic search rejects `limit: 0` queries
-     * with the "semantic search requires topk limit to be positive" error.
-     */
-    strategy?: 'rrf' | 'semantic_only' | 'full_text_only';
-}
-/** A single search result */
-export interface SearchResult {
-    id: string;
-    table: string;
-    score: number;
-    fields: Record<string, unknown>;
-    /** Cross-encoder reranker score (present when a reranker was used). */
-    rerankScore?: number;
-}
-/** Search response from a query */
-export interface SearchResponse {
-    results: SearchResult[];
-    /**
-     * Mapped term-facet aggregations — keyed by facet field, each a list
-     * of { value, count }. Populated from `params.facets` for convenience.
-     */
-    aggregations?: Record<string, Array<{
-        value: string;
-        count: number;
-    }>>;
-    /**
-     * Raw aggregation response from the search adapter, unmodified. Populated whenever
-     * the underlying query returned aggregations — use this for non-term
-     * shapes like date_histogram, range, stats, etc.
-     */
-    rawAggregations?: Record<string, unknown>;
-    meta: {
-        query: string;
-        total: number;
-        took_ms: number;
-        source: 'search' | 'fallback';
-    };
-}
-export interface SearchHealthIndex {
-    name: string;
-    type: string;
-    totalIndexed: number;
-    walBacklog: number;
-    error?: string;
-    rebuilding: boolean;
-    backfillProgress?: number;
-}
-export interface SearchHealthTable {
-    table: string;
-    pluginId: string;
-    stats: Record<string, unknown> | null;
-    indexHealth?: SearchHealthIndex[];
-    healthy: boolean;
-}
-export interface SearchHealthSnapshot {
-    enabled: boolean;
-    tables: SearchHealthTable[];
+export interface AssetVersionCreateInput {
+    sourceFilePath: string;
+    op?: 'edit' | 'generate' | 'upload' | 'import';
+    tool?: string | null;
+    prompt?: string | null;
+    promptHash?: string | null;
+    description?: string;
+    generation?: AssetGenerationInfo | null;
+}
+/** Render a derived export of a version (keyed/idempotent by surface). */
+export interface AssetExportRequest {
+    fromVersion?: number;
+    surface: string;
+    format: 'jpg' | 'png' | 'webp';
+    width: number;
+    height: number;
+    quality?: number;
+}
+export interface VersionedAssetRef {
+    assetId: string;
+    version: number;
 }
-/** Atomic transform operation (update fields without re-embedding) */
-export interface SearchTransformOp {
-    op: '$set' | '$inc' | '$push';
-    field?: string;
-    value: unknown;
+export interface AssetVersionFileRef {
+    absPath: string;
+    mimeType: string;
+    version: number;
 }
-/**
- * One file-pattern → mapper pair used by `FileBackedContentTypeDefinition`.
- * A registration may carry multiple of these when a single content type
- * draws from several distinct file shapes (e.g. workflows store
- * definitions as `.yaml` and instances as `.json`, both indexed into the
- * same `bakin_workflows` table with different key prefixes).
- */
-export interface FilePatternMapper {
-    /** Glob pattern relative to contentDir. First-match-wins across the patterns array. */
-    pattern: string;
-    /**
-     * Derive the search key for a file matching this pattern. Return null
-     * to skip the file (e.g. it matches the glob but is missing required
-     * companion data).
-     */
-    fileToId: (relPath: string) => string | null;
-    /**
-     * Build the search document for a file matching this pattern.
-     * `content` is the raw file bytes as a UTF-8 string (empty for binary
-     * assets, which the watcher recognizes by their `assets/` prefix).
-     * Return null to skip indexing (e.g. derived state isn't ready yet).
-     */
-    fileToDoc: (relPath: string, content: string) => Promise<Record<string, unknown> | null>;
+/** Current-version summary of an asset, addressed by id. */
+export interface AssetSummary {
+    assetId: string;
+    type: AssetTypeName;
+    agent: string;
+    taskId: string | null;
+    created: string;
+    updated: string;
+    currentVersion: number;
+    versionCount: number;
+    description: string;
+    tags: string[];
+    mimeType: string;
+    width: number | null;
+    height: number | null;
+    size: number;
+    hasThumb: boolean;
 }
 /**
- * A content type whose source of truth is one or more files under
- * `~/.bakin/`. Registering via `registerFileBackedContentType` wires up:
- *
- *   1. Standard `registerContentType` (table creation, schema, reindex).
- *   2. A watcher sync hook that re-indexes on add/change.
- *   3. A watcher unlink hook that removes on delete.
- *   4. A startup reconcile that detects mtime drift and corrects it.
- *
- * Plugins should reach for this helper first. Use raw `registerContentType`
- * only when the source of truth is NOT the filesystem (e.g. SQLite,
- * external API, runtime adapter).
+ * Per-version detail of a versioned asset (mirrors the manifest's version
+ * entries — provenance fields are null when the version wasn't produced by a
+ * generation tool).
  */
-export interface FileBackedContentTypeDefinition extends SearchContentTypeDefinition {
-    /**
-     * One or more file-pattern mappers. Patterns should not overlap;
-     * first match wins. A file that matches no pattern is ignored.
-     */
-    filePatterns: FilePatternMapper[];
-    /**
-     * Optional exclude patterns applied BEFORE any mapper matches. Useful
-     * for skipping subdirectories like `assets/**\/.trash/**` or sidecar
-     * files like `**\/*.meta.json`.
-     */
-    excludePatterns?: string[];
-    /**
-     * Escape hatch for sync events. When provided, the helper invokes
-     * this instead of the default `fileToDoc → ctx.search.index` flow for
-     * any file matching this content type's patterns. The plugin takes
-     * full responsibility for indexing.
-     *
-     * Use when pairing logic (e.g. assets' binary↔sidecar coupling) can't
-     * be expressed as a single mapper. The matched `FilePatternMapper` is
-     * still consulted for `fileToId` if the plugin needs the canonical key.
-     */
-    onSync?: (relPath: string, content: string) => Promise<void>;
-    /**
-     * Escape hatch for unlink events. Same story as `onSync`. If unset,
-     * the helper calls the matched mapper's `fileToId(relPath)` and then
-     * `ctx.search.remove(id)`.
-     */
-    onUnlink?: (relPath: string) => Promise<void>;
-    /**
-     * Whether to run the startup reconcile loop on plugin activation.
-     * Defaults to true. Set false only when the plugin wants to drive its
-     * own initial population (rare).
-     */
-    buildOnStartup?: boolean;
+export interface AssetVersionDetail {
+    version: number;
+    /** Version file name inside the asset directory (e.g. `v2.png`). */
+    file: string;
+    width: number | null;
+    height: number | null;
+    op: 'generate' | 'edit' | 'upload' | 'import';
+    tool: string | null;
+    prompt: string | null;
+    promptHash: string | null;
+    generation: AssetGenerationInfo | null;
 }
-/** Search API provided to plugins via ctx.search */
-export interface SearchAPI {
-    /**
-     * Register a content type this plugin will index.
-     * Must be called during activate(). Creates the search table if needed.
-     *
-     * Prefer `registerFileBackedContentType` when the source of truth is
-     * a file under `~/.bakin/` — it wires up watcher hooks and startup
-     * reconcile automatically. Use this raw form only for non-filesystem
-     * sources (SQLite, external APIs, runtime adapters).
-     */
-    registerContentType(def: SearchContentTypeDefinition): void;
-    /**
-     * Register a file-backed content type. Wraps `registerContentType` and
-     * additionally wires watcher sync + unlink hooks scoped to the declared
-     * file patterns, plus a startup reconcile that detects mtime drift on
-     * boot. This is the blessed API for any plugin whose data lives in the
-     * filesystem under `~/.bakin/`.
-     */
-    registerFileBackedContentType(def: FileBackedContentTypeDefinition): void;
-    /** Index or update a document. Fire-and-forget. */
-    index(key: string, doc: Record<string, unknown>): Promise<void>;
-    /** Remove a document from the index. */
-    remove(key: string): Promise<void>;
-    /** Atomic field update without re-embedding. For metadata-only changes. */
-    transform(key: string, operations: SearchTransformOp[]): Promise<void>;
-    /** Search this plugin's content type. */
-    query(params: SearchQueryParams): Promise<SearchResponse>;
-    /** Global search adapter and registered-table health snapshot. */
-    health?(): Promise<SearchHealthSnapshot>;
+export interface AssetsAPI {
+    createAsset(input: AssetCreateInput): Promise<VersionedAssetRef>;
+    /** Read an asset's current-version summary by id (metadata: type/description/tags/etc.), or null. */
+    getAsset(assetId: string): Promise<AssetSummary | null>;
+    addVersion(assetId: string, input: AssetVersionCreateInput): Promise<VersionedAssetRef>;
+    addExport(assetId: string, input: AssetExportRequest): Promise<{
+        name: string;
+        file: string;
+    }>;
+    resolveVersionFile(assetId: string, version?: number): Promise<AssetVersionFileRef | null>;
+    /** List asset summaries, optionally filtered by type and/or owning task. */
+    listAssets(filter?: {
+        type?: AssetTypeName;
+        taskId?: string;
+    }): Promise<AssetSummary[]>;
+    /** Read an asset's version history (current pointer + per-version detail), or null. */
+    getAssetVersions(assetId: string): Promise<{
+        currentVersion: number;
+        versions: AssetVersionDetail[];
+    } | null>;
+    /**
+     * Source-path-keyed upsert: create v1 if no asset tracks `sourcePath`,
+     * append a version if its content changed, or no-op if identical
+     * (`changed: false`). A path inside the asset store reflects to the asset
+     * it already belongs to — never a duplicate.
+     */
+    upsertFromSource(sourcePath: string, input: AssetCreateInput): Promise<VersionedAssetRef & {
+        changed: boolean;
+    }>;
     /**
-     * Plugin-scoped maintenance operations for indexers that own non-file-backed
-     * tables. This is intentionally narrower than the raw adapter: callers can
-     * only touch their own registered content type.
+     * Map an absolute path INSIDE the asset store back to its asset identity.
+     * `absPath` in the result is always the REAL version file (never the thumb).
+     * Null for anything outside the store or store-internal non-version files.
      */
-    maintenance?: SearchMaintenanceAPI;
-}
-export interface SearchMaintenanceAPI {
-    /** Whether the backing search service is reachable. */
-    available(): Promise<boolean>;
-    /** Iterate every document in this plugin's registered content type. */
-    scan(): AsyncIterable<{
-        key: string;
-        document: Record<string, unknown>;
-    }>;
-    /** Remove several documents from this plugin's registered content type. */
-    batchRemove(keys: string[]): Promise<number>;
-    /** Drop and recreate this plugin's registered content type table. */
-    resetContentType(): Promise<void>;
+    resolveStoreFile(absPath: string): Promise<(VersionedAssetRef & {
+        absPath: string;
+    }) | null>;
 }
+export type { SearchSchemaField, SearchIndexDefinition, SearchContentTypeDefinition, SearchQueryParams, SearchResult, SearchResponse, SearchHealthIndex, SearchHealthTable, SearchHealthSnapshot, SearchReindexItem, SearchTransformOp, SearchScanOptions, FilePatternMapper, FileBackedContentTypeDefinition, SearchAPI, SearchMaintenanceAPI, } from '@makinbakin/sdk/types';
 interface BaseSettingsField {
     key: string;
     label: string;
@@ -818,7 +588,16 @@ export interface ListSettingsField extends BaseSettingsField {
      */
     uniqueField?: string;
 }
-export type SettingsField = StringSettingsField | NumberSettingsField | BooleanSettingsField | SelectSettingsField | ListSettingsField;
+/**
+ * Per-agent on/off grid. Renders every roster agent with its avatar and a
+ * toggle; the persisted value is the array of enabled agent ids. Reusable by
+ * any plugin that gates a feature per agent.
+ */
+export interface AgentTogglesSettingsField extends BaseSettingsField {
+    type: 'agent-toggles';
+    default?: string[];
+}
+export type SettingsField = StringSettingsField | NumberSettingsField | BooleanSettingsField | SelectSettingsField | ListSettingsField | AgentTogglesSettingsField;
 export interface PluginSettingsSchema {
     fields: SettingsField[];
 }
@@ -833,6 +612,18 @@ export interface BakinPlugin {
     onShutdown?(): void | Promise<void>;
     /** Called when this plugin's settings are updated */
     onSettingsChange?(settings: Record<string, unknown>): void | Promise<void>;
+    /**
+     * Validate a whole settings document BEFORE the generic
+     * `PUT /api/plugin-settings/{id}` writes it. A plugin whose settings are
+     * money or policy (the spend plugin) refuses documents its own routes
+     * would refuse, so no side door can leave an invalid file on disk.
+     */
+    validateSettings?(value: unknown): {
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    };
     /**
      * Called by `bakin plugins remove` BEFORE Bakin tears down the plugin's
      * own bookkeeping (registry rows, settings JSON, plugin dir, etc.).
@@ -846,6 +637,8 @@ export interface BakinPlugin {
      * a half-removed state.
      */
     onUninstall?(ctx: PluginContext): void | Promise<void>;
+    /** Preflight before destructive removal. A rejection aborts removal. */
+    beforeUninstall?(ctx: PluginContext): void | Promise<void>;
     /** Declarative settings schema for auto-generated settings UI */
     settingsSchema?: PluginSettingsSchema;
     navItems?: NavItem[];
@@ -859,52 +652,7 @@ export interface BakinPlugin {
      * a bare `routes: APIRoute[]` annotation widens types and breaks the
      * per-route inference that drives the dispatcher's typed `parsed` argument.
      *
-     * Optional during the migration window (T1–T16); plugins still using
-     * `ctx.registerRoute(...)` from `activate()` continue to work via the
-     * dispatcher adapter.
      */
     routes?: ReadonlyArray<DeclarativeAPIRoute<PluginContextLite, any, any, any>>;
 }
-export interface PluginManifestSignature {
-    algorithm: 'ed25519';
-    signer: string;
-    publicKey: string;
-    signature: string;
-}
-export interface SecretDeclaration {
-    /** Canonical environment variable name, for example `ANTHROPIC_API_KEY`. */
-    name: string;
-    /** Human-readable setup note. Never include a secret value here. */
-    description: string;
-    /** Missing required secrets should be reported by setup/health checks. Defaults to true. */
-    required: boolean;
-}
-export interface PluginManifest {
-    id: string;
-    name: string;
-    version: string;
-    bakin: string;
-    description: string;
-    entry: {
-        server: string;
-        client?: string;
-    };
-    contentFiles?: string[];
-    secrets?: SecretDeclaration[];
-    tests?: string;
-    dependencies?: string[];
-    permissions?: string[];
-    signature?: PluginManifestSignature;
-}
-export interface PluginEntry {
-    path: string;
-    enabled?: boolean;
-}
-export interface BakinConfig {
-    plugins: PluginEntry[];
-    theme?: Record<string, string>;
-    storage?: {
-        contentDir?: string;
-    };
-}
-export {};
+export type { PluginManifestSignature, SecretDeclaration, PluginManifest, PluginEntry, BakinConfig, } from '@makinbakin/sdk/types';