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

package/_internal/app/hooks/use-search.d.ts

@@ -4,7 +4,7 @@ export interface SearchResult {
     score: number;
     fields: Record<string, unknown>;
     _table?: string;
-    /** Per-index score breakdown (e.g. { search: 0.8, embeddings: 0.6 }) */
+    /** Per-leg score breakdown keyed by neutral leg names (e.g. { full_text: 0.8, assets_visual: -0.2 }) */
     indexScores?: Record<string, number>;
 }
 export interface SearchResponse {
@@ -17,25 +17,39 @@ export interface SearchResponse {
         query: string;
         total: number;
         took_ms: number;
-        source: 'search' | 'fallback';
+        source: 'search' | 'unavailable';
+        /** True when any source degraded/was omitted under the query budget. */
+        partial?: boolean;
+        tables?: Array<{
+            table: string;
+            hits: number;
+            took_ms: number;
+            budget?: 'degraded' | 'omitted';
+        }>;
     };
 }
+/**
+ * Honest search lifecycle (spec D11). `unavailable` is the explicit
+ * engine-down signal (HTTP 503 `search_unavailable`) — render
+ * `<SearchUnavailable/>`, never a silent lower-quality substitute.
+ */
+export type SearchStatus = 'idle' | 'loading' | 'ok' | 'unavailable' | 'error';
 export interface UseSearchOptions {
     /**
      * Plugin id to route the query to. When set, the hook fetches
      * `/api/plugins/{plugin}/search?q=...` — the plugin owns its table
      * name and the client never sees the raw `bakin_` prefix. Omit for
-     * cross-plugin search, which falls back to `/api/search?q=...`.
+     * cross-plugin search via `/api/search?q=...`.
      */
     plugin?: string;
     /** Max results */
     limit?: number;
     /** Facet fields to include aggregation counts for */
     facets?: string[];
+    /** Restrict cross-plugin search to these content types (tables). */
+    types?: string[];
     /** Debounce delay in ms (default: 250) */
     debounce?: number;
-    /** Fallback filter function when search returns no results or errors */
-    fallback?: (query: string) => SearchResult[];
 }
 export interface UseSearchReturn {
     results: SearchResult[];
@@ -43,11 +57,15 @@ export interface UseSearchReturn {
         value: string;
         count: number;
     }>>;
+    status: SearchStatus;
+    /** True while a request is in flight or debounce-pending (=== status 'loading'). */
     loading: boolean;
     error: string | null;
     meta: SearchResponse['meta'] | null;
     search: (query: string) => void;
     clear: () => void;
+    /** Re-run the last query immediately (Retry in the unavailable state). */
+    retry: () => void;
 }
 /**
  * Given a client-side filtered list and search results, reorder the list
@@ -58,8 +76,9 @@ export declare function reorderBySearchResults<T extends {
     id: string;
 }>(items: T[], searchResults: SearchResult[]): T[];
 /**
- * React hook for Bakin search with debouncing, AbortController, and an
- * optional client-side fallback. Scopes to a plugin via `plugin:` or
- * runs cross-plugin when omitted.
+ * React hook for Bakin search with debouncing and AbortController.
+ * Scopes to a plugin via `plugin:` or runs cross-plugin when omitted.
+ * There is deliberately NO client-side fallback: engine-down is an
+ * explicit `unavailable` status the UI must surface (spec D11).
  */
 export declare function useSearch(options?: UseSearchOptions): UseSearchReturn;

package/_internal/app/hooks/use-task-run-history.d.ts

@@ -0,0 +1,26 @@
+/** Task-level terminal outcome (mirrors plugins/tasks TaskOutcome). */
+export interface TaskOutcome {
+    state: 'done' | 'blocked' | 'archived' | 'in_progress';
+    /** Set when state === 'done' and a completion row exists. */
+    completedAt?: string;
+    /** Agent that recorded the completion, when known. */
+    agent?: string;
+}
+/** One dispatch attempt for a task (mirrors plugins/tasks TaskRunEntry). */
+export interface TaskRunEntry {
+    runId: string;
+    taskId: string;
+    seq: number;
+    agent: string;
+    status: 'running' | 'settled' | 'superseded' | 'lost';
+    startedAt: string;
+    settledAt?: string;
+    settleReason?: string;
+    durationMs?: number;
+}
+/** Fetch a task's dispatch run history (newest-first) + task outcome from the execution ledger. */
+export declare function useTaskRunHistory(taskId: string | null, limit?: number): {
+    runs: TaskRunEntry[];
+    outcome: TaskOutcome | undefined;
+    loading: boolean;
+};

package/_internal/app/hooks/use-toast.d.ts

@@ -4,13 +4,23 @@ export interface Toast {
     message: ReactNode;
     type: 'success' | 'error' | 'info';
     duration?: number;
+    /** Optional heading above the message (the kit Toast's title slot). */
+    title?: ReactNode;
+    /** Optional action row (the kit Toast's action slot). */
+    action?: ReactNode;
+    /**
+     * Stays until dismissed — no timer. For attention the operator must act
+     * on (the spend ladder's 90% and cap toasts); a caller that needs to know
+     * WHEN it was closed subscribes to the store and watches its id go.
+     */
+    persistent?: boolean;
 }
 interface ToastStore {
     toasts: Toast[];
-    add: (toast: Omit<Toast, 'id'>) => void;
+    add: (toast: Omit<Toast, 'id'>) => string;
     dismiss: (id: string) => void;
 }
 export declare const useToastStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ToastStore>>;
-/** Convenience: call from anywhere without hooks */
-export declare function toast(message: ReactNode, type?: Toast['type'], duration?: number): void;
+/** Convenience: call from anywhere without hooks. Returns the toast id for programmatic dismiss. */
+export declare function toast(message: ReactNode, type?: Toast['type'], duration?: number): string;
 export {};

package/_internal/app/lib/browser-notify.d.ts

@@ -1,5 +1,16 @@
+/**
+ * Navigate bridge — the host registers its router here at boot so
+ * notification clicks route client-side instead of full-reloading the shell.
+ * globalThis-based (like __bakinBroadcast) because every plugin bundle
+ * inlines its own copy of this module; a module-level variable would never
+ * reach those copies.
+ */
+type NavigateFn = (url: string) => void;
+export declare function setNotificationNavigator(navigate: NavigateFn): void;
+export declare function navigateToUrl(url: string): void;
 export declare function isNotificationsSupported(): boolean;
 export declare function isNotificationsEnabled(): boolean;
 export declare function requestNotificationPermission(): Promise<boolean>;
 export declare function toggleNotifications(enabled: boolean): void;
-export declare function sendBrowserNotification(title: string, body: string): void;
+export declare function sendBrowserNotification(title: string, body: string, url?: string): void;
+export {};

package/_internal/app/types/index.d.ts

@@ -1,113 +1,8 @@
-export interface TaskLogEntry {
-    timestamp: string;
-    author: string;
-    message: string;
-}
-export interface Task {
-    id: string;
-    title: string;
-    agent?: string;
-    checked: boolean;
-    date?: string;
-    blockedReason?: string;
-    description?: string;
-    log?: TaskLogEntry[];
-}
-export interface TaskColumns {
-    inProgress: Task[];
-    todo: Task[];
-    done: Task[];
-    blocked: Task[];
-}
-export interface TaskBoard {
-    columns: TaskColumns;
-    timestamp?: string;
-}
-export type ColumnId = keyof TaskColumns;
-export interface CalendarEvent {
-    time?: string;
-    text: string;
-}
-export interface CalendarDay {
-    date: string;
-    label?: string;
-    events: CalendarEvent[];
-}
-export interface RecurringEvent {
-    schedule: string;
-    text: string;
-}
-export interface MemoryEntry {
-    type: 'decision' | 'learned' | 'note';
-    text: string;
-}
-export interface MemoryDay {
-    date: string;
-    entries: MemoryEntry[];
-}
 export interface Heartbeat {
     status: 'working' | 'idle' | 'down';
     currentTask?: string;
     timestamp: string;
 }
-export interface ProjectMeta {
-    filename: string;
-    title: string;
-    status?: string;
-    content: string;
-}
-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;
-    };
-    variants?: AssetVariantMeta[];
-}
-export interface TrashedAssetMeta {
-    filename: string;
-    originalFilename: string;
-    type: string;
-    mimeType: string;
-    size: number;
-    deletedAt: string;
-    expiresAt: string;
-    metadata: {
-        agent: string;
-        taskId: string | null;
-        created: string;
-        tool?: string;
-        description?: string;
-        tags?: string[];
-    } | null;
-}
-export interface OfficeData {
-    asciiMap: string;
-    statusTable: {
-        agent: string;
-        status: string;
-        task: string;
-        heartbeat: string;
-    }[];
-    history: string[];
-}
 export interface ActivityEvent {
     id: string;
     ts: string;
@@ -118,6 +13,7 @@ export interface ActivityEvent {
     taskTitle?: string;
     eventName?: string;
     duplicate?: boolean;
+    data?: Record<string, unknown>;
 }
 export interface ContentState {
     files: Record<string, string>;

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

@@ -0,0 +1,231 @@
+/**
+ * Channel/delivery contract types — a LEAF module (imports only
+ * ./capabilities) so both the runtime contract (concepts.ts) and the
+ * delivery-bridge seam (packages/core/src/delivery/bridge.ts, threaded
+ * through AdapterInitOpts in ../shared.ts) can share the surface without an
+ * import cycle: shared -> bridge -> channels and concepts -> channels.
+ */
+import type { ChannelCapability } from './capabilities';
+export type RuntimeMetadata = Record<string, unknown>;
+export interface ChannelInfo {
+    id: string;
+    platform: string;
+    label: string;
+    capabilities: ChannelCapability[];
+    metadata?: RuntimeMetadata;
+}
+export interface DeliveryResult {
+    deliveries: ApprovalDelivery[];
+}
+export interface NotificationArgs {
+    channels: string[];
+    notification: {
+        severity: 'info' | 'warn' | 'error' | 'success';
+        title: string;
+        body: string;
+        fields?: {
+            label: string;
+            value: string;
+        }[];
+        metadata?: RuntimeMetadata;
+    };
+}
+export interface ChannelMessageArgs {
+    channels: string[];
+    message: {
+        body: string;
+        title?: string;
+        threadId?: string;
+        metadata?: RuntimeMetadata;
+    };
+}
+export interface ContentDeliveryArgs {
+    channels: string[];
+    content: {
+        title: string;
+        body?: string;
+        url?: string;
+        /**
+         * Path files are read from disk (trusted plugin/core callers only). For
+         * `{ kind: 'asset' }` refs, `filename` is the ASSET ID — providers
+         * resolve it through the `assets.resolveServe` hook; an unresolvable id
+         * degrades to a visible omission, never a failed delivery.
+         */
+        files?: Array<{
+            name: string;
+            path: string;
+            contentType?: string;
+        } | {
+            kind: 'asset';
+            filename: string;
+            mimeType?: string;
+        }>;
+        metadata?: RuntimeMetadata;
+    };
+}
+export interface CreateThreadArgs {
+    /** Channel ref the anchor message lives in (provider or provider:target). */
+    channel: string;
+    /** Delivery ref of the message to anchor the thread to (e.g. "message:<id>"). */
+    messageRef?: string;
+    name: string;
+}
+export interface CreatedThread {
+    threadId: string;
+    /**
+     * Provider-addressable channel ref for posting INTO the thread (opaque to
+     * callers — provider target syntax stays inside the adapter).
+     */
+    channelRef: string;
+}
+export interface EditChannelMessageArgs {
+    /** Channel ref the message lives in (provider or provider:target). */
+    channel: string;
+    /** Delivery ref of the message to edit (e.g. "message:<id>"). */
+    messageRef: string;
+    body: string;
+}
+export interface ApprovalOption {
+    id: string;
+    label: string;
+    variant?: 'primary' | 'destructive' | 'neutral';
+}
+export interface ApprovalDelivery {
+    channelId: string;
+    ref: string;
+    renderedAt: string;
+}
+export interface ApprovalPatch {
+    body?: string;
+    options?: ApprovalOption[];
+    expiresAt?: string;
+    context?: RuntimeMetadata;
+}
+export interface ApprovalResponse {
+    selectedOption: string;
+    respondedAt: string;
+    actor: {
+        type: 'agent' | 'human';
+        id: string;
+        displayName?: string;
+    };
+    comment?: string;
+}
+export interface ApprovalRenderResult {
+    deliveries: ApprovalDelivery[];
+}
+export interface ApprovalRenderRef {
+    approvalId: string;
+    deliveries: ApprovalDelivery[];
+}
+export interface CreateApprovalArgs {
+    approvalId: string;
+    channels: string[];
+    request: {
+        title: string;
+        body: string;
+        options: ApprovalOption[];
+        expiresAt?: string;
+        context?: RuntimeMetadata;
+    };
+}
+export interface EditApprovalArgs extends ApprovalRenderRef {
+    patch: ApprovalPatch;
+}
+export interface CancelApprovalArgs extends ApprovalRenderRef {
+    reason?: string;
+}
+export interface ResolveApprovalArgs extends ApprovalRenderRef {
+    response: ApprovalResponse;
+}
+export interface ApprovalResolveEvent {
+    approvalId: string;
+    response: ApprovalResponse;
+    channelId: string;
+}
+export interface DurableApprovalRecord {
+    approvalId: string;
+    owner: {
+        workflowId: string;
+        runId: string;
+        stepId: string;
+        taskId?: string;
+    };
+    status: 'pending' | 'approved' | 'rejected' | 'cancelled' | 'expired';
+    request: CreateApprovalArgs['request'];
+    deliveries: ApprovalDelivery[];
+    response?: ApprovalResponse;
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt?: string;
+}
+/** An inbound attachment already materialized to a LOCAL file by the provider. */
+export interface InboundChannelAttachment {
+    name: string;
+    path: string;
+    contentType?: string;
+    size?: number;
+}
+/**
+ * A human message arriving FROM a channel (#669 Phase B). The provider has
+ * already applied its gating (allowlists, mention requirements) — a handler
+ * receiving this may treat the sender as authorized. `channelRef` is
+ * provider-qualified and directly usable as a send target for the reply.
+ */
+export interface InboundChannelMessage {
+    platform: string;
+    channelRef: string;
+    authorId: string;
+    authorName?: string;
+    text: string;
+    attachments?: InboundChannelAttachment[];
+    /** Provider message ref (e.g. "message:<id>"). */
+    messageRef: string;
+    /**
+     * Structured control command (e.g. a slash command) instead of chat text —
+     * when present, `text` is empty and consumers act on the verb ("new-chat"
+     * unbinds the channel's chat so the next message starts fresh). The
+     * provider has already acked the command UI-side.
+     */
+    command?: {
+        name: string;
+    };
+}
+/**
+ * The full channel surface a delivering runtime exposes (see
+ * `AgentRuntimeAdapter.channels` for the capability semantics — the member
+ * is OPTIONAL there; this type is the shape when present).
+ */
+export interface RuntimeChannelSurface {
+    list(): Promise<ChannelInfo[]>;
+    sendNotification(args: NotificationArgs): Promise<DeliveryResult>;
+    sendMessage(args: ChannelMessageArgs): Promise<DeliveryResult>;
+    deliverContent(args: ContentDeliveryArgs): Promise<DeliveryResult>;
+    createApproval(args: CreateApprovalArgs): Promise<ApprovalRenderResult>;
+    editApproval(args: EditApprovalArgs): Promise<ApprovalRenderResult>;
+    cancelApproval(args: CancelApprovalArgs): Promise<void>;
+    resolveApproval(args: ResolveApprovalArgs): Promise<void>;
+    subscribeApprovalResponses(handler: (event: ApprovalResolveEvent) => void): () => void;
+    /**
+     * Optional threading/editing capabilities. Adapters for providers without
+     * threads or message editing omit them; callers MUST feature-detect and
+     * fall back to flat channel messages — never error on absence.
+     */
+    createThread?(args: CreateThreadArgs): Promise<CreatedThread | null>;
+    editMessage?(args: EditChannelMessageArgs): Promise<void>;
+    /**
+     * OPTIONAL inbound stream (#669 Phase B): human messages from the channel
+     * platform, pre-gated by the provider (allowlists fail closed; guild
+     * messages mention-gated). Runtimes that handle inbound themselves
+     * (OpenClaw) OMIT this member — consumers feature-detect.
+     */
+    subscribeInboundMessages?(handler: (message: InboundChannelMessage) => void): () => void;
+    /**
+     * OPTIONAL ephemeral typing/activity signal (#669 Phase B, D10). Providers
+     * without the concept omit it; callers feature-detect and repeat while
+     * work runs (platform typing states expire — Discord's after ~10s).
+     */
+    sendTyping?(args: {
+        channel: string;
+    }): Promise<void>;
+}