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

package/types/index.js

@@ -1 +1,2 @@
 // @bun
+var HEALTH_INCIDENT_CLASSES=["service_failure","data_integrity","budget_block","evidence_gap","usage_anomaly","unattributed_usage","runaway_usage","cleanup_backlog","policy_denial","unsupported_surface"];export{HEALTH_INCIDENT_CLASSES};

package/types/manifest.d.ts

@@ -0,0 +1,255 @@
+import type { HttpMethod } from './primitives';
+import type { NavItem } from './registration';
+/** Capability a plugin can request in its manifest (gates access to APIs). */
+export type PluginPermission = 'storage.read' | 'storage.write' | 'events.emit' | 'runtime.read' | 'runtime.agents' | 'runtime.messaging' | 'runtime.channels' | 'runtime.cron' | 'runtime.skills' | 'runtime.models' | 'runtime.images' | 'tasks.read' | 'tasks.write' | 'search.read' | 'search.write' | 'assets.read' | 'assets.write';
+/** Runtime feature a plugin declares it needs (used by doctor/health checks). */
+export type RuntimeCapability = 'agents' | 'messaging' | 'channels.message' | 'channels.rich-content' | 'channels.interactive-approval' | 'channels.threaded-replies' | 'cron' | 'skills' | 'models' | 'tasks' | 'search';
+/** Secret (env var) a plugin declares it needs (rendered in setup/health). */
+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;
+}
+/** Manifest declaration of an HTTP route the plugin exposes. */
+export interface ApiRouteContribution {
+    method: HttpMethod;
+    /** Plugin-relative path. Exposed as `/api/plugins/{pluginId}{path}`. */
+    path: string;
+    summary: string;
+    description?: string;
+    operationId?: string;
+    tags?: string[];
+    visibility?: 'public' | 'internal' | 'experimental';
+    stability?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+    parameters?: ApiParameterContribution[];
+    requestBody?: ApiRequestBodyContribution;
+    responses?: Record<string, ApiResponseContribution>;
+    permissions?: PluginPermission[];
+}
+/** Raw JSON Schema object embedded in API contributions. */
+export type JsonSchemaContribution = Record<string, unknown>;
+/** Path/query/header/cookie parameter declaration for an API route. */
+export interface ApiParameterContribution {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    description?: string;
+    schema?: JsonSchemaContribution;
+    example?: unknown;
+}
+/** Request body declaration for an API route. */
+export interface ApiRequestBodyContribution {
+    description?: string;
+    required?: boolean;
+    contentType?: string;
+    schema?: JsonSchemaContribution;
+    example?: unknown;
+}
+/** Response declaration for one HTTP status code on an API route. */
+export interface ApiResponseContribution {
+    description: string;
+    contentType?: string;
+    schema?: JsonSchemaContribution;
+    example?: unknown;
+}
+/** Manifest declaration of a client-side route the plugin contributes. */
+export interface ClientRouteContribution {
+    /** Absolute app route, e.g. `/messaging/calendar`. */
+    path: string;
+    summary: string;
+    slot?: string;
+}
+/**
+ * Manifest declaration of one client route *pattern* the plugin's client
+ * registers via `registerPlugin({ routes })`. Unlike `clientRoutes` (concrete
+ * documentation paths), these patterns must exactly match the keys passed to
+ * `registerPlugin({ routes })` — including dynamic segments (`/projects/[id]`)
+ * — so the host knows which plugin owns a path before its client has loaded.
+ */
+export interface ClientRoutePatternContribution {
+    /** Route pattern, e.g. `/projects/[id]`. Supports `[id]`, `:id`, `$id` segments. */
+    path: string;
+    summary?: string;
+}
+/** Manifest declaration of an MCP exec tool the plugin exposes. */
+export interface ExecToolContribution {
+    name: string;
+    summary: string;
+    description?: string;
+    permissions?: PluginPermission[];
+}
+/** Manifest declaration of a CLI command the plugin contributes. */
+export interface CliCommandContribution {
+    name: string;
+    usage: string;
+    summary: string;
+    description?: string;
+    aliases?: string[];
+    /** Optional. When present, the manifest-driven CLI dispatcher routes the
+     *  command through either the named exec-tool or the given API route.
+     *  When absent, the command is documentation-only — its real
+     *  implementation lives in `cli/bakin.ts`'s imperative switch. */
+    dispatch?: {
+        type: 'apiRoute';
+        method: HttpMethod;
+        path: string;
+    } | {
+        type: 'execTool';
+        name: string;
+    };
+}
+/** Manifest declaration of a settings key the plugin owns. */
+export interface SettingsContribution {
+    key: string;
+    summary: string;
+}
+/** Manifest declaration of the plugin's docs page slug. */
+export interface DocsContribution {
+    slug: string;
+}
+/** The full contributions block in `bakin-plugin.json` — everything a plugin adds to the host. */
+export interface PluginContributions {
+    /** HTTP routes the plugin exposes under `/api/plugins/{id}/...`. */
+    apiRoutes?: ApiRouteContribution[];
+    /** Client-side routes the plugin renders (sidebar nav targets). */
+    clientRoutes?: ClientRouteContribution[];
+    /** MCP exec tools agents can call. */
+    execTools?: ExecToolContribution[];
+    /** CLI commands the plugin contributes to the `bakin` binary. */
+    cliCommands?: CliCommandContribution[];
+    /** Settings keys this plugin owns in the settings UI. */
+    settings?: SettingsContribution[];
+    /** Optional docs page slug. */
+    docs?: DocsContribution;
+    /**
+     * Declarative sidebar nav items. Rendered from manifest JSON before the
+     * plugin's client bundle loads — this is what makes lazy loading possible.
+     * A plugin that also passes `navItems` to `registerPlugin` at runtime
+     * overrides its manifest nav (the conditional-nav escape hatch); the two
+     * are compared by the drift validation check.
+     */
+    nav?: NavItem[];
+    /**
+     * Client route patterns the plugin's client registers via
+     * `registerPlugin({ routes })`. Must exactly match the registered keys —
+     * the host uses these to lazy-load the client on first navigation.
+     */
+    routes?: ClientRoutePatternContribution[];
+    /**
+     * Slot names the plugin's client fills via `registerPlugin({ slots })`
+     * (e.g. `page:/tasks`, `task-assets`). The host lazy-loads the client the
+     * first time one of these slots renders.
+     */
+    slots?: string[];
+    /**
+     * Load the client bundle at boot instead of on first demand. The escape
+     * hatch for plugins with background providers (`nav-badge-providers`),
+     * conditional nav, or other module-load side effects the shell needs
+     * immediately. Plugins with a client but no declarative `nav`/`routes`/
+     * `slots` metadata are treated as eager for backward compatibility.
+     */
+    eager?: boolean;
+}
+/** Optional Ed25519 signature block proving manifest authenticity. */
+export interface PluginManifestSignature {
+    algorithm: 'ed25519';
+    /** Human-readable signer label. Trust is bound to publicKey/fingerprint, not this label. */
+    signer: string;
+    /** Base64-encoded Ed25519 SPKI DER public key. */
+    publicKey: string;
+    /** Base64-encoded signature over the canonical manifest without this signature block. */
+    signature: string;
+}
+/** The `bakin-plugin.json` manifest. Required for every plugin. */
+/** Platform keys follow `process.platform-process.arch`. */
+export type PluginBinPlatform = 'darwin-arm64' | 'darwin-x64' | 'linux-x64' | 'linux-arm64';
+/** One pinned, sha256-verified download of a required binary. */
+export interface PluginBinDownload {
+    /** https URL (loopback http allowed for local fixtures). */
+    url: string;
+    /** Hex sha256 of the download (the archive when `archive` is set). */
+    sha256: string;
+    /** Present when the download is a tarball; `member` is the file extracted as the binary. */
+    archive?: {
+        format: 'tar.gz';
+        member: string;
+    };
+    /** Download size in bytes, shown in consent/install UIs when present. */
+    sizeBytes?: number;
+}
+/**
+ * A binary Bakin installs into `~/.bakin/bin` with the plugin — disclosed at
+ * install consent, verified by the doctor, removed with the plugin unless
+ * another owner still pins it.
+ */
+export interface PluginBinRequirement {
+    /** Name as invoked from PATH. */
+    name: string;
+    version: string;
+    /** Per-platform downloads; a platform without an entry fails install preflight on that platform. */
+    install: Partial<Record<PluginBinPlatform, PluginBinDownload>>;
+    /** Args for the verify-then-commit probe run (e.g. `["-V"]`). */
+    verifyArgs?: string[];
+}
+export interface PluginManifest {
+    /** Removal must run the loaded plugin's beforeUninstall hook successfully. */
+    uninstallPreflightRequired?: boolean;
+    /** Unique plugin identifier (kebab-case). */
+    id: string;
+    /** Human-readable plugin name. */
+    name: string;
+    /** Plugin version (semver). */
+    version: string;
+    /**
+     * Semver range of Bakin host versions this plugin supports (e.g.
+     * `">=0.5.0"`). Enforced at install and at activation: an incompatible or
+     * malformed range rejects with an actionable error. Dev-source hosts
+     * (version `0.0.0-dev`) skip the satisfaction check but still reject
+     * malformed ranges.
+     */
+    bakin: string;
+    /** One-line summary shown in the plugin manager. */
+    description: string;
+    /** Static content files the plugin ships (rendered as docs/pages). */
+    contentFiles?: string[];
+    /** Environment-variable secrets the plugin requires. */
+    secrets?: SecretDeclaration[];
+    /** Other plugin IDs this plugin depends on. */
+    dependencies?: string[];
+    /** Capabilities this plugin requests access to. */
+    permissions?: PluginPermission[];
+    /** Runtime features this plugin needs to function. */
+    runtimeCapabilities?: RuntimeCapability[];
+    /** Everything the plugin adds to the host (routes, tools, settings, etc.). */
+    contributes?: PluginContributions;
+    /** File globs that trigger a hot reload in dev. */
+    devWatch?: string[];
+    /** Optional Ed25519 signature for authenticity. */
+    signature?: PluginManifestSignature;
+    /** Binaries Bakin installs with the plugin (`requires.bins`). */
+    requires?: {
+        bins?: PluginBinRequirement[];
+    };
+}
+/** The `bakin.config.ts` shape — root configuration for a Bakin installation. */
+export interface BakinConfig {
+    /** Plugins to load at startup. */
+    plugins: PluginEntry[];
+    /** Theme overrides for CSS custom properties. */
+    theme?: Record<string, string>;
+    /** Storage configuration. */
+    storage?: {
+        /** Override the default content directory. */
+        contentDir?: string;
+    };
+}
+/** A plugin entry in `bakin.config.ts`. */
+export interface PluginEntry {
+    /** Path or package specifier resolving to the plugin's entry file. */
+    path: string;
+    /** If false, the plugin is loaded but not activated. Default true. */
+    enabled?: boolean;
+}

package/types/primitives.d.ts

@@ -0,0 +1,33 @@
+/** HTTP method literal used in route and contribution definitions. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** Visibility tier for a documented contract (route, hook, tool, etc.). */
+export type ContractVisibility = 'public' | 'internal' | 'experimental';
+/** Stability tier for a documented contract. */
+export type ContractStability = 'stable' | 'beta' | 'experimental' | 'deprecated';
+/** Minimal interface a validation schema must satisfy (Zod-compatible). */
+export interface SchemaLike<T = unknown> {
+    parse(data: unknown): T;
+    safeParse?(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: unknown;
+    };
+}
+/** Pointer to a symbol's source file location, used in generated docs. */
+export interface SourceLocation {
+    file: string;
+    symbol?: string;
+    line?: number;
+}
+/** Reference example for a documented contract (request/response or code snippet). */
+export interface DocsExample {
+    title: string;
+    description?: string;
+    code?: string;
+    request?: unknown;
+    response?: unknown;
+    test?: 'automated' | 'schema' | 'illustrative';
+    reason?: string;
+}

package/types/registration.d.ts

@@ -0,0 +1,281 @@
+import type { ComponentType } from 'react';
+import type { z, ZodRawShape } from 'zod';
+import type { ActivityAPI, EventBus, HookAPI, StorageAdapter } from './context';
+import type { SchemaLike } from './primitives';
+import type { AgentRuntimeAdapter } from './runtime';
+import type { AssetsAPI, SearchAPI, TaskService } from './services';
+import type { ActivityClass } from './api-route';
+/** Visual tone for a {@link NavBadge}. Maps to a fixed palette in the sidebar.
+ *  Ordered by severity: `error` (red) is the most urgent and wins rollups. */
+export type NavBadgeTone = 'error' | 'attention' | 'info' | 'success';
+/**
+ * Runtime badge attached to a nav item. Both fields are optional:
+ *   - `count` present → renders as a small pill (clamped at `99+`).
+ *   - `count` omitted but object present → renders as a small dot.
+ *   - `count: 0` or passing `null` to `setNavBadge` clears the badge.
+ * `tone` defaults to `'attention'`.
+ */
+export interface NavBadge {
+    count?: number;
+    tone?: NavBadgeTone;
+}
+/** Host-defined sidebar section a top-level plugin nav item may join. */
+export type NavSection = 'plan-and-automate' | 'create' | 'operations';
+/** Sidebar navigation item registered by a plugin via `ctx.registerNav()`. */
+export interface NavItem {
+    /** Unique nav item id (used for active-state tracking and badge keying). */
+    id: string;
+    /** Display label in the sidebar. */
+    label: string;
+    /** Lucide icon name (e.g. "tasks", "calendar"). */
+    icon?: string;
+    /** Target route path. */
+    href?: string;
+    /** Sort order within the parent group. Lower renders first. */
+    order?: number;
+    /** Optional nested nav items for groups. */
+    children?: NavItem[];
+    /** Top-level destination. Omit to render under Mix-ins. */
+    section?: NavSection;
+    /**
+     * Initial badge state. Runtime updates flow through `setNavBadge` — the
+     * rendered badge for an item is `runtimeRegistry.get(id) ?? item.badge`.
+     * Most plugins leave this undefined and set badges purely at runtime.
+     */
+    badge?: NavBadge;
+}
+/** Slot registration record: place a component at a named extension point. */
+export interface UISlotRegistration {
+    slot: string;
+    component: ComponentType<Record<string, unknown>>;
+    order?: number;
+}
+/** Static content file shipped with a plugin (e.g. README, docs page). */
+export interface ContentFile {
+    path: string;
+}
+/** Result returned from an exec tool handler. */
+export interface ExecToolResult {
+    ok: boolean;
+    error?: string;
+    details?: unknown;
+    [key: string]: unknown;
+}
+/** Context passed to an exec tool handler. Subset of PluginContext sans UI registration. */
+export interface PluginToolContext {
+    /** Verified caller, set by the host transport and absent on untrusted calls. */
+    invocation?: {
+        agentId: string;
+    };
+    /** Plugin-scoped storage adapter. */
+    storage: StorageAdapter;
+    /** Cross-plugin event bus. */
+    events: EventBus;
+    /** ID of the plugin owning this tool. */
+    pluginId: string;
+    /** Agent runtime adapter (messaging, agents, channels, cron). */
+    runtime: AgentRuntimeAdapter;
+    /** Task CRUD service. */
+    tasks: TaskService;
+    /** Search API. */
+    search: SearchAPI;
+    /** Assets API. */
+    assets: AssetsAPI;
+    /** Hook registry. */
+    hooks: HookAPI;
+    /** Activity feed and audit log. */
+    activity: ActivityAPI;
+    /** Read this plugin's persisted settings. */
+    getSettings<T = Record<string, unknown>>(): T;
+}
+/** MCP exec tool definition registered via `ctx.registerExecTool()`. */
+export interface ExecToolDefinition<Shape extends ZodRawShape = ZodRawShape> {
+    /** Requires a runtime-bound or credential-verified caller. */
+    requiresVerifiedAgent?: boolean;
+    /** Tool name. Convention: `bakin_exec_{pluginId}_{action}`. */
+    name: string;
+    /** Description shown to the agent (used for tool selection). */
+    description: string;
+    /** Optional UI label for the activity feed. */
+    label?: string;
+    /** If true, this tool can fire multiple times in a single agent turn. */
+    activityDuplicate?: boolean;
+    /** Usage classification propagated by every generic exec-tool transport. Defaults to foreground user activity. */
+    activityClass?: ActivityClass;
+    /** Zod raw shape describing the tool's parameters. */
+    parameters: Shape;
+    /** Handler. Params are inferred from `parameters` — declare once, get typed params. */
+    handler: (params: z.infer<z.ZodObject<Shape>>, agent: string, ctx?: PluginToolContext) => Promise<ExecToolResult>;
+    /** Optional source-file path for generated docs. */
+    source?: string;
+}
+/** Runtime skill definition registered via `ctx.registerSkill()`. */
+export interface SkillDefinition {
+    name: string;
+    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;
+}
+/** Layout hints for a workflow's canvas rendering. */
+export interface WorkflowLayoutInput {
+    positions?: Record<string, {
+        x: number;
+        y: number;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+}
+/** Plugin-contributed workflow definition input shape. */
+export interface WorkflowDefinitionInput {
+    id?: string;
+    name: string;
+    description: string;
+    version: number;
+    inputs?: Record<string, unknown>;
+    layout?: WorkflowLayoutInput;
+    steps: unknown[];
+    [key: string]: unknown;
+}
+/** Field types supported by FormField. */
+export type FormFieldType = 'string' | 'text' | 'number' | 'boolean' | 'select' | 'agent' | 'skill' | 'list';
+/** Form field descriptor for plugin-contributed workflow nodes. */
+export interface FormField {
+    name: string;
+    type: FormFieldType;
+    required?: boolean;
+    description?: string;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+/** Edge constraints for a plugin-contributed workflow node type. */
+export interface EdgeRules {
+    maxInbound?: number;
+    maxOutbound?: number;
+}
+/** Workflow node type contributed by a plugin (custom step kind). */
+export interface PluginNodeTypeInput<T = unknown> {
+    kind: string;
+    zodSchema: SchemaLike<T>;
+    formFields: FormField[];
+    edgeRules?: EdgeRules;
+}
+/** Notification channel definition contributed by a plugin. */
+export interface PluginNotificationChannelInput {
+    id: string;
+    label: string;
+    initials?: string;
+    icon?: string;
+}
+interface BaseSettingsField {
+    key: string;
+    label: string;
+    description?: string;
+    required?: boolean;
+}
+/** Single-line text settings field. */
+export interface StringSettingsField extends BaseSettingsField {
+    type: 'string';
+    default?: string;
+}
+/** Numeric settings field with optional default. */
+export interface NumberSettingsField extends BaseSettingsField {
+    type: 'number';
+    default?: number;
+}
+/** Boolean toggle settings field. */
+export interface BooleanSettingsField extends BaseSettingsField {
+    type: 'boolean';
+    default?: boolean;
+}
+/** Dropdown settings field with predefined options. */
+export interface SelectSettingsField extends BaseSettingsField {
+    type: 'select';
+    options: {
+        value: string;
+        label: string;
+    }[];
+    default?: string;
+}
+/** Repeatable list settings field with per-item shape. */
+export interface ListSettingsField extends BaseSettingsField {
+    type: 'list';
+    itemShape: Record<string, StringSettingsField | NumberSettingsField | BooleanSettingsField | SelectSettingsField>;
+    default?: unknown[];
+    addLabel?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueField?: string;
+}
+/**
+ * Per-agent on/off grid. The renderer lists every agent in the roster with its
+ * avatar and a toggle; the stored value is the array of enabled agent ids.
+ */
+export interface AgentTogglesSettingsField extends BaseSettingsField {
+    type: 'agent-toggles';
+    default?: string[];
+}
+/** Union of all supported settings field types. */
+export type SettingsField = StringSettingsField | NumberSettingsField | BooleanSettingsField | SelectSettingsField | ListSettingsField | AgentTogglesSettingsField;
+/** Plugin settings schema — declares fields rendered on the settings page. */
+export interface PluginSettingsSchema {
+    /** Ordered list of settings fields for the form. */
+    fields: SettingsField[];
+}
+/** A workflow definition stored on disk (YAML or programmatic). */
+export interface WorkflowDefinition {
+    id?: string;
+    name: string;
+    description?: string;
+    version?: number;
+    steps: unknown[];
+    [key: string]: unknown;
+}
+/** A running instance of a workflow attached to a task. */
+/**
+ * A running workflow instance (permissive view of the wire shape produced by
+ * the workflows plugin). The key field is `instanceId` — NOT `id`. The full
+ * typed shape (stepStates, history, …) is internal to the workflows plugin;
+ * this published view types the commonly-read fields and stays open via the
+ * index signature.
+ */
+export interface WorkflowInstance {
+    instanceId: string;
+    workflowId?: string;
+    taskId?: string;
+    currentStepId?: string;
+    status?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+/** Alias for WorkflowDefinition when used as a reusable template. */
+export type WorkflowTemplate = WorkflowDefinition;
+/**
+ * How one search hit of a given content type renders in the global (⌘K)
+ * search overlay. Plain DATA mapping — the overlay owns row layout,
+ * keyboard focus, and debug-badge placement uniformly.
+ */
+export interface SearchHitDescriptor {
+    title: string;
+    subtitle?: string;
+    /** Deep link for Enter/click. `null` = renderable but non-navigable. */
+    href: string | null;
+    thumbnailUrl?: string;
+    /** Lucide icon name fallback when there is no thumbnail. */
+    icon?: string;
+    /** Small meta line (type · agent · date) shown under the subtitle. */
+    meta?: string;
+}
+/** Minimal hit shape passed to renderers (matches useSearch's SearchResult). */
+export interface SearchHitInput {
+    id: string;
+    table: string;
+    score: number;
+    fields: Record<string, unknown>;
+}
+export type SearchHitRenderer = (hit: SearchHitInput) => SearchHitDescriptor;
+export {};