@makinbakin/sdk 0.0.0-bootstrap.0 → 0.0.1-rc.1

package/README.md

@@ -9,6 +9,12 @@ runtime React + `@makinbakin/sdk/*` are externalized and resolved through
 the host's import map — so plugins don't ship a second copy of any of
 them.
 
+Full SDK docs:
+
+- [SDK overview](https://makinbakin.com/docs/extending/sdk/overview/)
+- [SDK reference](https://makinbakin.com/docs/reference/generated/sdk/)
+- [Build a plugin](https://makinbakin.com/docs/extending/plugins/build/)
+
 ## Install
 
 ```sh
@@ -26,7 +32,7 @@ the actual instances at runtime.
 bakin plugins scaffold my-plugin
 cd my-plugin
 bun install
-bakin plugins install .
+bakin plugins install --dev .
 ```
 
 ## Minimal client entry
@@ -84,17 +90,21 @@ component for a slot via `registerPlugin({ slots: { 'slot-name': Component } })`
 
 ## Sub-path imports
 
-The `exports` map covers these sub-paths:
+The public npm package exposes these sub-paths:
 
 | Import path              | What it exposes                              |
 | ------------------------ | -------------------------------------------- |
-| `@makinbakin/sdk`             | `registerPlugin`, top-level re-exports       |
-| `@makinbakin/sdk/ui`          | Base UI components (buttons, cards, inputs)  |
-| `@makinbakin/sdk/hooks`       | Shared React hooks (useQueryState, useDebug) |
-| `@makinbakin/sdk/components`  | Higher-level shell components                |
-| `@makinbakin/sdk/slots`       | Slot runtime + provider                      |
-| `@makinbakin/sdk/types`       | TypeScript types (`BakinPlugin`, `PluginContext`, etc.) |
-| `@makinbakin/sdk/utils`       | Shared utilities                             |
+| `@makinbakin/sdk` | Plugin registration, route helpers, top-level exports |
+| `@makinbakin/sdk/ui` | Base UI components |
+| `@makinbakin/sdk/hooks` | Shared React hooks |
+| `@makinbakin/sdk/components` | Higher-level shell components |
+| `@makinbakin/sdk/slots` | Slot runtime and provider |
+| `@makinbakin/sdk/types` | TypeScript contract types |
+| `@makinbakin/sdk/utils` | Shared utilities |
+| `@makinbakin/sdk/metadata` | Docs-aware contract metadata helpers |
+| `@makinbakin/sdk/routing` | Typed declarative route helpers |
+
+Use `@makinbakin/sdk/*` imports for external plugin code.
 
 ## Repository
 
@@ -104,4 +114,4 @@ This package is developed alongside Bakin in the
 
 ## License
 
-MIT © markhayden
+Apache-2.0

package/_internal/app/components/integrated-brainstorm/activity.d.ts

@@ -0,0 +1,23 @@
+import type { RuntimeChatChunk } from '@makinbakin/sdk/types';
+import type { BrainstormMessage } from './types';
+export interface BrainstormActivityInput {
+    kind: string;
+    content: string;
+    data?: unknown;
+}
+export interface BrainstormTimelineMessageInput {
+    id: string;
+    role: 'user' | 'assistant' | 'agent';
+    content: string;
+    timestamp?: string;
+}
+export interface BrainstormTimelineActivityInput extends BrainstormActivityInput {
+    id: string;
+    timestamp?: string;
+}
+export declare function runtimeChunkToBrainstormActivity(chunk: RuntimeChatChunk): BrainstormActivityInput | null;
+export declare function brainstormActivityMessageFromCustom(name: string, data: unknown): BrainstormMessage | null;
+export declare function toBrainstormTimeline(agentId: string, input: {
+    messages: BrainstormTimelineMessageInput[];
+    activities?: BrainstormTimelineActivityInput[];
+}): BrainstormMessage[];

package/_internal/app/components/integrated-brainstorm/index.d.ts

@@ -1,3 +1,8 @@
 import type { IntegratedBrainstormProps } from './types';
 export type { BrainstormMessage, IntegratedBrainstormProps, BrainstormOnSend, SendContext, AssistantTransformed, } from './types';
-export declare function IntegratedBrainstorm({ messages, onMessagesChange, onSend, agentId, onAgentChange, label, icon, placeholder, emptyState, collapsible, defaultOpen, conversationStartHeight, minHeight, maxHeight, maxInputHeight, storageKey, fitParent, showHeader, readOnly, readOnlyNotice, transformAssistantMessage, }: IntegratedBrainstormProps): import("react/jsx-runtime").JSX.Element;
+export { brainstormActivityMessageFromCustom, runtimeChunkToBrainstormActivity, toBrainstormTimeline, } from './activity';
+export { brainstormThreadId, normalizeBrainstormActivityForStorage, normalizeBrainstormActivityMessageForStorage, } from './session';
+export type { BrainstormActivityInput, BrainstormTimelineActivityInput, BrainstormTimelineMessageInput, } from './activity';
+export type { BrainstormActivityStorageInput, BrainstormActivityStorageRecord, } from './session';
+export { readBrainstormSseResponse } from './sse';
+export declare function IntegratedBrainstorm({ messages, onMessagesChange, onSend, agentId, onAgentChange, label, icon, placeholder, emptyState, collapsible, defaultOpen, defaultHeight, minHeight, maxHeight, maxInputHeight, storageKey, fitParent, showHeader, readOnly, readOnlyNotice, transformAssistantMessage, }: IntegratedBrainstormProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/integrated-brainstorm/session.d.ts

@@ -0,0 +1,16 @@
+import type { BrainstormMessage } from './types';
+export interface BrainstormActivityStorageInput {
+    id?: string;
+    kind?: string;
+    content?: string;
+    data?: unknown;
+    timestamp?: string;
+}
+export interface BrainstormActivityStorageRecord {
+    kind: string;
+    content: string;
+    data?: unknown;
+}
+export declare function brainstormThreadId(scope: string, entityId: string, agentId: string): string;
+export declare function normalizeBrainstormActivityForStorage(activity: BrainstormActivityStorageInput): BrainstormActivityStorageRecord | null;
+export declare function normalizeBrainstormActivityMessageForStorage(activity: BrainstormActivityStorageInput): Pick<BrainstormMessage, 'role' | 'kind' | 'content' | 'data'> | null;

package/_internal/app/components/integrated-brainstorm/sse.d.ts

@@ -0,0 +1,8 @@
+import type { SendContext } from './types';
+interface BrainstormSseReadOptions {
+    onCustomEvent?: (event: string, data: unknown) => boolean | void;
+}
+export declare function readBrainstormSseResponse(response: Response, ctx: SendContext, options?: BrainstormSseReadOptions): Promise<{
+    content: string;
+}>;
+export {};

package/_internal/app/components/integrated-brainstorm/types.d.ts

@@ -2,9 +2,11 @@ import type { LucideIcon } from 'lucide-react';
 import type { ReactNode } from 'react';
 export interface BrainstormMessage {
     id: string;
-    role: 'user' | 'assistant';
+    role: 'user' | 'assistant' | 'activity';
     content: string;
     agentId?: string;
+    kind?: 'runtime_status' | 'tool_call' | 'error' | string;
+    data?: unknown;
     timestamp?: string;
 }
 export interface SendContext {
@@ -38,16 +40,16 @@ export interface IntegratedBrainstormProps {
     position?: 'bottom';
     collapsible?: boolean;
     defaultOpen?: boolean;
-    conversationStartHeight?: number;
+    defaultHeight?: number;
     minHeight?: number;
     maxHeight?: number;
     maxInputHeight?: number;
     storageKey?: string;
     /**
      * Fill parent height via flex-1/h-full instead of a fixed pixel height.
-     * Drops the drag handle (nothing to drag against) and disables auto-expand
-     * (already full-size). Use when the panel IS the pane — e.g. a dedicated
-     * chat route — rather than a bottom sheet above other content.
+     * Drops the drag handle because there is nothing fixed to drag against. Use
+     * when the panel IS the pane — e.g. a dedicated chat route — rather than a
+     * bottom sheet above other content.
      */
     fitParent?: boolean;
     /**

package/_internal/app/components/ui/badge.d.ts

@@ -1,7 +1,7 @@
 import { useRender } from "@base-ui/react/use-render";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: ({
-    variant?: "link" | "destructive" | "default" | "outline" | "secondary" | "ghost" | null | undefined;
+    variant?: "destructive" | "link" | "default" | "outline" | "secondary" | "ghost" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Badge({ className, variant, render, ...props }: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export { Badge, badgeVariants };

package/_internal/app/components/ui/button.d.ts

@@ -1,7 +1,7 @@
 import { Button as ButtonPrimitive } from "@base-ui/react/button";
 import { type VariantProps } from "class-variance-authority";
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "destructive" | "default" | "outline" | "secondary" | "ghost" | "warning" | "accent" | null | undefined;
+    variant?: "destructive" | "link" | "default" | "outline" | "secondary" | "ghost" | "warning" | "accent" | null | undefined;
     size?: "default" | "sm" | "lg" | "icon" | "xs" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Button({ className, variant, size, ...props }: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>): import("react/jsx-runtime").JSX.Element;

package/_internal/core/adapters/runtime/concepts.d.ts

@@ -41,6 +41,10 @@ export interface WorkspaceFile {
 export interface MessageArgs {
     agentId: string;
     content: string;
+    /**
+     * Adapter-neutral durable conversation key. Runtime adapters should map the
+     * same agentId + threadId pair to the same provider/runtime session.
+     */
     threadId?: string;
     metadata?: RuntimeMetadata;
 }
@@ -49,10 +53,22 @@ export interface MessageResult {
     content?: string;
     metadata?: RuntimeMetadata;
 }
+export interface RuntimeToolActivity {
+    phase: 'call' | 'result';
+    callId?: string;
+    toolName: string;
+    status?: 'running' | 'completed' | 'failed' | string;
+    summary?: string;
+    inputPreview?: string;
+    outputPreview?: string;
+    durationMs?: number;
+    exitCode?: number;
+    metadata?: RuntimeMetadata;
+}
 export interface ChatChunk {
     type: 'text' | 'tool' | 'status' | 'done' | 'error';
     content?: string;
-    data?: unknown;
+    data?: RuntimeMetadata | RuntimeToolActivity;
 }
 export interface ToolDefinition {
     name: string;

package/_internal/core/adapters/runtime/index.d.ts

@@ -2,4 +2,4 @@ export type { AdapterAuditEvent, AdapterHealthCheckDefinition, AdapterHealthChec
 export type { ChannelCapability } from './capabilities';
 export { hasChannelCapability } from './capabilities';
 export { getRuntimeMainAgent, getRuntimeMainAgentId, getRuntimeMainAgentName, selectRuntimeMainAgent, } from './helpers';
-export type { AgentRuntimeAdapter, ApprovalDelivery, ApprovalOption, ApprovalPatch, ApprovalRenderRef, ApprovalRenderResult, ApprovalResolveEvent, ApprovalResponse, CancelApprovalArgs, ChannelInfo, ChannelInteractionEvent, ChannelMessageArgs, ChannelMessageEvent, ChatChunk, ContentDeliveryArgs, CreateApprovalArgs, CreateCronJobInput, CreateRuntimeAgentInput, CronJob, CronRun, DeliveryResult, DurableApprovalRecord, EditApprovalArgs, ListExecutionsOpts, MessageArgs, MessageResult, NotificationArgs, ResolveApprovalArgs, RuntimeAgent, RuntimeAllowlistPatch, RuntimeAvailableModel, RuntimeConfigAccess, RuntimeMemoryEntry, RuntimeMemoryEntryStat, RuntimeMemoryPathMatch, RuntimeMemoryReadRange, RuntimeMemorySearchResult, RuntimeMemoryTier, RuntimeMetadata, RuntimePermissionPatch, RawCronSnapshot, RuntimeSession, RuntimeSkill, TaskDispatchArgs, TaskDispatchResult, TaskExecutionEvent, TaskExecutionStatus, ToolDefinition, ToolResult, UpdateCronJobInput, UpdateRuntimeAgentInput, WorkspaceFile, } from './concepts';
+export type { AgentRuntimeAdapter, ApprovalDelivery, ApprovalOption, ApprovalPatch, ApprovalRenderRef, ApprovalRenderResult, ApprovalResolveEvent, ApprovalResponse, CancelApprovalArgs, ChannelInfo, ChannelInteractionEvent, ChannelMessageArgs, ChannelMessageEvent, ChatChunk, ContentDeliveryArgs, CreateApprovalArgs, CreateCronJobInput, CreateRuntimeAgentInput, CronJob, CronRun, DeliveryResult, DurableApprovalRecord, EditApprovalArgs, ListExecutionsOpts, MessageArgs, MessageResult, NotificationArgs, ResolveApprovalArgs, RuntimeAgent, RuntimeAllowlistPatch, RuntimeToolActivity, RuntimeAvailableModel, RuntimeConfigAccess, RuntimeMemoryEntry, RuntimeMemoryEntryStat, RuntimeMemoryPathMatch, RuntimeMemoryReadRange, RuntimeMemorySearchResult, RuntimeMemoryTier, RuntimeMetadata, RuntimePermissionPatch, RawCronSnapshot, RuntimeSession, RuntimeSkill, TaskDispatchArgs, TaskDispatchResult, TaskExecutionEvent, TaskExecutionStatus, ToolDefinition, ToolResult, UpdateCronJobInput, UpdateRuntimeAgentInput, WorkspaceFile, } from './concepts';

package/_internal/core/constants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Core branding and identity constants for Bakin.
+ *
+ * Change these values to rebrand the entire application.
+ * Every file that needs the app name, slug, or paths imports from here.
+ */
+export declare const APP_NAME = "Bakin";
+export declare const APP_SLUG = "bakin";
+export { APP_VERSION } from './generated-version';
+export declare const APP_HOME_DEFAULT = "~/.bakin";
+export declare const CONFIG_FILE = "bakin.config.ts";
+export declare const PLUGIN_MANIFEST_FILE = "bakin-plugin.json";
+export declare const MAIN_AGENT_ROLE = "orchestrator";
+export declare const DEFAULT_PORT = 3737;
+export declare const ENV_PREFIX = "BAKIN";

package/_internal/core/content-dir.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolve the content directory path.
+ */
+export declare function getContentDir(): string;
+/**
+ * Whether the content dir is inside the supported Bakin home contract.
+ */
+export declare function isUsingBakinHome(): boolean;
+/**
+ * Reset the resolved content dir (for testing).
+ */
+export declare function resetContentDir(): void;
+/**
+ * Well-known content paths. Agents and CLI use these instead of constructing paths.
+ */
+export interface BakinPaths {
+    home: string;
+    memoryLog: string;
+    audit: string;
+    assets: string;
+    'assets.store': string;
+    'assets.inbox': string;
+    'assets.trash': string;
+    agents: string;
+    personas: string;
+    team: string;
+    heartbeats: string;
+    inbox: string;
+    tasks: string;
+    workflows: string;
+    settings: string;
+    logs: string;
+}
+export declare function getBakinPaths(): BakinPaths;
+/**
+ * Initialize the ~/.bakin/ directory structure.
+ * Called by `bakin mkdir` CLI command or on first run.
+ */
+export declare function initBakinHome(targetDir?: string): {
+    created: string[];
+    seeded: string[];
+};

package/_internal/core/generated-version.d.ts

@@ -0,0 +1 @@
+export declare const APP_VERSION = "0.0.0-dev";

package/_internal/core/logger.d.ts

@@ -0,0 +1,8 @@
+declare function createLogger(module: string): {
+    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 Logger = ReturnType<typeof createLogger>;
+export { createLogger };

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

@@ -128,6 +128,12 @@ export interface ActivityAPI {
     /** 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 interface HookAPI {
     /** Register a handler for a named hook. Returns unsubscribe function. */
     register(name: string, handler: (data: any) => any, metadata?: HookRegistrationMetadata): () => void;
@@ -218,6 +224,33 @@ export interface HealthCheckResult {
     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 {
+    id: string;
+    checkId: string;
+    title: string;
+    reason: string;
+    safety: HealthRepairSafety;
+    requiresConfirmation: boolean;
+    changes: HealthRepairChange[];
+}
+export interface HealthRepairApplyResult {
+    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
@@ -234,12 +267,15 @@ export interface PluginHealthCheckInput {
      */
     run: () => Promise<HealthCheckResult[]>;
     /**
-     * Advisory flag for admin UIs: `true` if `run()` may perform safe
-     * auto-fixes internally. Pure metadata in v1 — the orchestrator always
-     * invokes every registered check regardless of this value. Plugins that
-     * do internal auto-fixes gate on `getSettings().doctor.*` themselves.
+     * 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';
@@ -306,6 +342,8 @@ 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;
     /** Cross-plugin hook registration */
     hooks: HookAPI;
     /** Adapter-backed search — register content types, index, query */
@@ -328,10 +366,19 @@ export interface PluginTask {
     workflowId?: string;
     scheduleJobId?: string;
     projectId?: string;
+    availableAt?: string;
+    dueAt?: string;
+    source?: PluginTaskSource;
     order?: number;
     createdAt?: string;
     updatedAt?: string;
 }
+export interface PluginTaskSource {
+    pluginId?: string;
+    entityType?: string;
+    entityId?: string;
+    purpose?: string;
+}
 export interface TaskLogEntry {
     timestamp: string;
     author: string;
@@ -349,6 +396,9 @@ export interface PluginTaskCreateInput {
     workflowId?: string;
     projectId?: string;
     parentId?: string | null;
+    availableAt?: string;
+    dueAt?: string;
+    source?: PluginTaskSource;
     skipWorkflowReason?: string;
 }
 export interface PluginTaskUpdateInput {
@@ -364,6 +414,9 @@ export interface PluginTaskUpdateInput {
     scheduleJobId?: string;
     projectId?: string;
     parentId?: string | null;
+    availableAt?: string | null;
+    dueAt?: string | null;
+    source?: PluginTaskSource | null;
 }
 export interface PluginTaskService {
     create(input: PluginTaskCreateInput): Promise<PluginTask>;
@@ -818,6 +871,14 @@ export interface PluginManifestSignature {
     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;
@@ -829,7 +890,7 @@ export interface PluginManifest {
         client?: string;
     };
     contentFiles?: string[];
-    secrets?: string[];
+    secrets?: SecretDeclaration[];
     tests?: string;
     dependencies?: string[];
     permissions?: string[];

package/_internal/core/routing/index.d.ts

@@ -2,7 +2,7 @@
  * `@bakin/core/routing` — typed route contracts.
  *
  * Re-exports the route types and authoring helpers used by both the host and
- * plugin authors (via `@bakin/sdk/routing`).
+ * plugin authors (via `@makinbakin/sdk/routing`).
  */
 export type { HttpMethod, HttpStatus, RouteContext, PluginContextLite, CoreContext, JsonBodySpec, MultipartBodySpec, RawBodySpec, NoBodySpec, BodySpec, JsonResponseSpec, NoContentResponseSpec, NonJsonResponseSpec, ResponseSpec, ParsedInput, APIRoute, PluginWithRoutes, } from './types';
 export { defineRoute, defineCoreRoute, definePlugin } from './define';

package/components/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * `@bakin/sdk/components` — shared layout + compound components.
+ * `@makinbakin/sdk/components` — shared layout + compound components.
  *
  * Plugin-author-visible components that wrap shadcn primitives with Bakin-
  * specific behavior (headers, filters, markdown, agent displays, etc.). Does
@@ -18,7 +18,8 @@ export { ErrorState } from '../_internal/app/components/error-state';
 export { FacetFilter } from '../_internal/app/components/facet-filter';
 export type { FacetOption } from '../_internal/app/components/facet-filter';
 export { IntegratedBrainstorm } from '../_internal/app/components/integrated-brainstorm';
-export type { BrainstormMessage, IntegratedBrainstormProps, BrainstormOnSend, SendContext, AssistantTransformed, } from '../_internal/app/components/integrated-brainstorm';
+export type { BrainstormMessage, IntegratedBrainstormProps, BrainstormOnSend, SendContext, AssistantTransformed, BrainstormActivityInput, BrainstormActivityStorageInput, BrainstormActivityStorageRecord, BrainstormTimelineActivityInput, BrainstormTimelineMessageInput, } from '../_internal/app/components/integrated-brainstorm';
+export { brainstormActivityMessageFromCustom, brainstormThreadId, normalizeBrainstormActivityForStorage, normalizeBrainstormActivityMessageForStorage, readBrainstormSseResponse, runtimeChunkToBrainstormActivity, toBrainstormTimeline, } from '../_internal/app/components/integrated-brainstorm';
 export { MarkdownContent } from '../_internal/app/components/markdown-content';
 export { MarkdownEditor } from '../_internal/app/components/markdown-editor';
 export { ModelSelect } from '../_internal/app/components/model-select';