@makinbakin/sdk 0.0.1-rc.3 → 0.0.1-rc.30

package/_internal/app/core/conversation-turns.d.ts

@@ -0,0 +1,229 @@
+import type { PluginContext } from '../../core/plugin-types';
+import type { ChatChunk, MessageUsage } from '../../core/adapters/runtime';
+/** The engine needs only messaging + the event bus from a plugin context. */
+export type TurnContext = Pick<PluginContext, 'runtime' | 'events'>;
+export interface TurnAttachment {
+    name: string;
+    mimeType: string;
+    path: string;
+}
+export declare function isRasterAttachment(a: TurnAttachment): boolean;
+/**
+ * THE file-lane note generator (#742) — every chat-like surface (web
+ * composer, Discord inbound) converges here; never hand-roll this note.
+ * PDFs point at the blessed pdf tool rendered in the active runtime's
+ * calling style; other files get the generic file-tools wording.
+ */
+export declare function fileLaneNote(a: TurnAttachment, agentId: string, renderCall?: (tool: string, args: string) => string): string;
+/**
+ * The durable transcript row shape (identical to chat's schema-v2 rows —
+ * user attachments are path-addressed server-side; display URLs are a
+ * client concern).
+ */
+export type ConversationTurnRow = {
+    kind: 'user';
+    ts: string;
+    content: string;
+    attachments?: TurnAttachment[];
+} | {
+    kind: 'assistant';
+    ts: string;
+    turnId?: string;
+    content: string;
+} | {
+    kind: 'tool';
+    ts: string;
+    turnId?: string;
+    callId?: string;
+    toolName: string;
+    status: 'completed' | 'failed';
+    summary?: string;
+    inputPreview?: string;
+    outputPreview?: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+} | {
+    kind: 'error';
+    ts: string;
+    turnId?: string;
+    message: string;
+    errorKind?: string;
+} | {
+    kind: 'aborted';
+    ts: string;
+    turnId?: string;
+} | {
+    kind: 'done';
+    ts: string;
+    turnId?: string;
+};
+export interface TurnOutcome {
+    aborted: boolean;
+    errored: boolean;
+}
+export type StartTurnResult = 'accepted' | 'not_found' | 'busy' | QueuedStart;
+/**
+ * The queued acceptance (#729) — captured synchronously at push time so
+ * callers get THEIR item's id, never a tail re-read that a concurrent
+ * enqueue could poison (review finding: the awaited persist can park
+ * behind streaming transcript writes, making post-await reads stale).
+ */
+export interface QueuedStart {
+    queued: true;
+    queueId: string;
+    queueLength: number;
+}
+/**
+ * A message accepted while the slot was busy (#729). Queued messages are a
+ * consumer-durable snapshot (the `queue.persist` hook) and drain as ONE
+ * combined turn when the active turn settles — done, error, and abort all
+ * drain. `agentId` is the agent resolved at enqueue time; the drain's
+ * synchronous slot reservation uses it, then refreshes from resolveThread
+ * before the runtime call.
+ */
+export interface QueuedMessage {
+    id: string;
+    ts: string;
+    content: string;
+    agentId: string;
+    attachments?: TurnAttachment[];
+}
+export interface InflightTurnInfo {
+    key: string;
+    agentId: string;
+    turnId: string;
+    startedAt: number;
+}
+export interface ConversationTurnServiceConfig {
+    /** Consumer label for log lines (e.g. 'chat', 'projects.brainstorm'). */
+    name: string;
+    /** Bus event names — the consumer's wire contract (e.g. chat.chunk/done/error).
+     *  `started` (optional) fires at turn-accept, BEFORE any runtime chunk —
+     *  attention providers light the working dot instantly instead of waiting
+     *  out model latency for the first chunk (#707). */
+    events: {
+        chunk: string;
+        done: string;
+        error: string;
+        started?: string;
+    };
+    /** Base payload identifying the thread on every event (e.g. key => ({ chatId: key })). */
+    payload: (key: string) => Record<string, unknown>;
+    /** Resolve the thread's agent; null → start() returns 'not_found'. */
+    resolveThread: (key: string) => {
+        agentId: string;
+    } | null | Promise<{
+        agentId: string;
+    } | null>;
+    /** Append one durable transcript row. Failures are logged, never thrown into the turn. */
+    appendRow: (key: string, row: ConversationTurnRow) => void | Promise<void>;
+    /**
+     * Runtime session thread id (e.g. key => `chat:${key}`). Called once per
+     * turn — per-turn thread schemes (brands' ephemeral randomUUID threads)
+     * are legitimate.
+     */
+    threadId: (key: string, agentId: string) => string;
+    /** Per-turn delivery framing appended to the runtime content; never persisted. */
+    framing?: string;
+    /** Run turns as ephemeral runtime sessions (no provider-side accumulation). */
+    ephemeral?: boolean;
+    /**
+     * Persist an invisible `{kind:'done'}` marker row at clean success settle
+     * (#735). Abort/error settles already end on their own terminal rows, so
+     * with this on EVERY settled turn ends on a terminal row — the evidence a
+     * boot sweep needs to stamp partial-output deaths without ever falsely
+     * marking a completed turn. Chat-style sweepable transcripts only:
+     * bounded stores (brands' 300-row brainstorm array) would evict real
+     * rows, and foreign zod schemas would reject the kind.
+     */
+    terminalMarkerRows?: boolean;
+    /**
+     * Opt-in pending queue (#729). Without this, a busy slot always answers
+     * `'busy'` — strict surfaces are unchanged.
+     */
+    queue?: {
+        /**
+         * Full-snapshot persistence after every queue mutation — the restart
+         * durability promise. Failures are logged, never thrown to callers.
+         */
+        persist?: (key: string, items: QueuedMessage[]) => void | Promise<void>;
+        /** Bus event emitted on enqueue (payload + queueId + queueLength). */
+        event?: string;
+    };
+    hooks?: {
+        /** Read-only tap on EVERY runtime chunk (e.g. messaging proposal parsing). */
+        onChunk?: (key: string, chunk: ChatChunk) => void;
+        /** Spend attribution, once per turn — success and abort, never error. */
+        meter?: (info: {
+            key: string;
+            agentId: string;
+            turnId: string;
+            usage?: MessageUsage;
+        }) => Promise<void> | void;
+        /**
+         * Success/abort path only, AFTER final row persistence but BEFORE the
+         * done event — finalize derived state (e.g. messaging's proposal
+         * linking) so it is durable when clients react to done. Errors are
+         * logged, never thrown into the turn.
+         */
+        onTurnComplete?: (info: {
+            key: string;
+            aborted: boolean;
+        }) => Promise<void> | void;
+        /** Runs after the slot releases; waitFor() resolves after it completes. */
+        onSettled?: (info: {
+            ctx: TurnContext;
+            key: string;
+            outcome: TurnOutcome;
+        }) => Promise<unknown> | unknown;
+    };
+}
+export interface StartTurnOptions {
+    attachments?: TurnAttachment[];
+    /** Per-turn agent override (surfaces with an agent picker); default = resolveThread's. */
+    agentId?: string;
+    /**
+     * Busy slot → enqueue instead of `'busy'` (requires `config.queue`).
+     * The busy-check and enqueue happen in one synchronous block (no TOCTOU).
+     * CAVEAT: a QUEUED send keeps only content + attachments — a per-turn
+     * `agentId` override and `runtimeContent` are DISCARDED at drain time
+     * (the combined turn resolves the thread's agent fresh and joins clean
+     * content). Surfaces that need either must not opt into queueing.
+     */
+    queueIfBusy?: boolean;
+    /**
+     * Pre-assembled runtime content for THIS turn (embedded surfaces inject
+     * doc/context prompts here). The persisted user row always keeps the
+     * clean `content`; when omitted, the runtime gets content + framing.
+     */
+    runtimeContent?: string;
+}
+export interface ConversationTurnService {
+    start(ctx: TurnContext, key: string, content: string, opts?: StartTurnOptions): Promise<StartTurnResult>;
+    /** Abort the in-flight turn; false when the thread is idle. Queued messages stay — they drain at settle. */
+    abort(key: string): boolean;
+    /** Snapshot of the pending queue (empty for strict surfaces). */
+    listQueued(key: string): QueuedMessage[];
+    /** Remove one queued message by id; persists. False when absent. */
+    removeQueued(key: string, id: string): boolean;
+    /** Drop the whole queue (delete-thread path); persists empty. */
+    clearQueue(key: string): void;
+    /**
+     * Seed the queue from persisted state (boot path) and drain immediately
+     * when the slot is idle. Does NOT re-persist — the items came from disk.
+     */
+    restore(ctx: TurnContext, key: string, items: QueuedMessage[]): void;
+    isInFlight(key: string): boolean;
+    /** Assistant text streamed so far for the in-flight turn (null when idle) —
+     *  lets GET responses seed mid-turn rehydration without the missing-start gap. */
+    inflightPreview(key: string): string | null;
+    /**
+     * Await the current turn; when called while the turn is in flight this
+     * also covers its onSettled tail. Resolves immediately when idle
+     * (including during onSettled itself — the slot has already released).
+     */
+    waitFor(key: string): Promise<void>;
+    /** Every in-flight turn — consumers build active-turn resolution on top. */
+    listInFlight(): InflightTurnInfo[];
+}
+export declare function createConversationTurnService(config: ConversationTurnServiceConfig): ConversationTurnService;

package/_internal/app/core/logger.d.ts

@@ -0,0 +1 @@
+export { createLogger } from '../../core/logger';

package/_internal/app/core/tool-access.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The ONE renderer for a runtime's tool-access instructions (P1.2).
+ *
+ * A runtime declares HOW its agents reach Bakin's `bakin_exec_*` tools via
+ * `describeToolAccess()` → {@link RuntimeToolAccess}. This module turns that
+ * declaration into the agent-facing instruction block. Both the projected
+ * AGENTS.md role layer and the per-dispatch prompt render through here (P1.4),
+ * so the two surfaces can never drift.
+ *
+ * Style intent:
+ *  - `in-process`  — exec tools are first-class session tools; bare calls,
+ *                    no cheat-sheet (the agent discovers the live set).
+ *  - `mcp`         — tools appear as native MCP tools under a per-agent
+ *                    server; prefixed calls, still discovered live.
+ *  - `cli-shim`    — tools are reached through a shell command; the exhaustive
+ *                    cheat-sheet IS warranted here because the invocation is
+ *                    non-obvious and easy to get wrong.
+ */
+import type { RuntimeToolAccess } from '../../core/adapters/runtime';
+export interface ToolAccessRenderOptions {
+    /** Agent whose per-agent server / shim names to substitute (mcp, cli-shim). */
+    agentId: string;
+}
+/**
+ * Render ONE tool invocation in the runtime's style — the primitive shared by
+ * both the standing tool-access block (below) and the per-dispatch prompt
+ * authors, so invocation bytes cannot drift between the two surfaces.
+ *   - in-process → `bakin_exec_x arg=1`
+ *   - mcp        → `bakin-<agent>.bakin_exec_x arg=1`
+ *   - cli-shim   → the shim command with `<tool>`/`<args>` filled in
+ * `args` may be empty (trailing space is trimmed).
+ */
+export declare function renderToolCall(access: RuntimeToolAccess, opts: {
+    agentId: string;
+    tool: string;
+    args?: string;
+}): string;
+/**
+ * Render the runtime-specific tool-access instruction block for `agentId`.
+ * Returns a single markdown string (no trailing newline).
+ */
+export declare function renderToolAccessInstructions(access: RuntimeToolAccess, opts: ToolAccessRenderOptions): string;

package/_internal/app/hooks/use-available-models.d.ts

@@ -0,0 +1,5 @@
+import type { AvailableModel } from '@makinbakin/sdk/types';
+/** The available-models catalog (empty array until loaded / on failure). */
+export declare function useAvailableModels(): AvailableModel[];
+/** Test-only: reset the module-level cache so tests run with a clean slate. */
+export declare function __resetAvailableModelsCache(): void;

package/_internal/app/hooks/use-content-store.d.ts

@@ -5,18 +5,12 @@ interface AuditEntry {
     agent: string;
     data: Record<string, unknown>;
 }
-interface ReindexProgressEntry {
-    indexed: number;
-    done: boolean;
-}
 interface ContentStore extends ContentState {
     loading: boolean;
     auditEntries: AuditEntry[];
     activityEvents: ActivityEvent[];
     sseConnected: boolean;
-    taskboardVersion: number;
     debug: boolean;
-    reindexProgress: Record<string, ReindexProgressEntry>;
     setFiles: (files: Record<string, string>) => void;
     updateFile: (key: string, content: string) => void;
     setHeartbeats: (heartbeats: Record<string, Heartbeat>) => void;
@@ -25,11 +19,8 @@ interface ContentStore extends ContentState {
     appendActivityEvent: (event: ActivityEvent) => void;
     setActivityEvents: (events: ActivityEvent[]) => void;
     setSseConnected: (connected: boolean) => void;
-    bumpTaskboard: () => void;
     setDebug: (debug: boolean) => void;
     toggleDebug: () => void;
-    setReindexProgress: (table: string, indexed: number, done: boolean) => void;
-    clearReindexProgress: () => void;
     initialize: () => Promise<void>;
 }
 export declare const useContentStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ContentStore>>;

package/_internal/app/hooks/use-history-back.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @deprecated Import `useHistoryBack` from `@makinbakin/sdk/navigation`.
+ * This module remains as a compatibility adapter for existing consumers.
+ */
+export { useHistoryBack } from '@makinbakin/sdk/navigation';

package/_internal/app/hooks/use-horizontal-resize.d.ts

@@ -0,0 +1,21 @@
+import { type ResizeHandleProps } from './use-resizable-pane';
+interface Options {
+    defaultWidth: number;
+    minWidth: number;
+    maxWidth: number;
+    /** When set, width is persisted in localStorage under `bakin-hresize:${storageKey}`. */
+    storageKey?: string;
+}
+interface Return {
+    width: number;
+    setWidth: (w: number) => void;
+    handleProps: ResizeHandleProps;
+}
+/**
+ * Resize a right-anchored panel by dragging its left edge. The handle lives at
+ * the left of the element; dragging left grows the panel, dragging right
+ * shrinks it. Keyboard: ArrowLeft/ArrowRight (Shift for a larger step).
+ * Thin wrapper over {@link useResizablePane} for side-by-side split panes.
+ */
+export declare function useHorizontalResize({ defaultWidth, minWidth, maxWidth, storageKey }: Options): Return;
+export {};

package/_internal/app/hooks/use-json-fetch.d.ts

@@ -0,0 +1,36 @@
+export interface UseJsonFetchResult<T> {
+    /** Parsed JSON body, or null before the first successful load. */
+    data: T | null;
+    /** True while a request is in flight. */
+    loading: boolean;
+    /** Error message on a non-2xx response or a network/parse failure; null otherwise. */
+    error: string | null;
+    /** Re-run the fetch (e.g. after a mutation). */
+    refresh: () => void;
+}
+export interface UseJsonFetchOptions extends RequestInit {
+    /**
+     * Abort the request after this many milliseconds and report it as a timeout
+     * rather than a silent hang. Endpoints that scan the filesystem or call the
+     * runtime can stall indefinitely; without a deadline the caller shows a
+     * spinner forever.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Cancellable JSON GET with the standard `{ data, loading, error, refresh }` lifecycle —
+ * the consolidation of the `let cancelled = false` fetch-in-useEffect boilerplate scattered
+ * across plugin components. Aborts the in-flight request on unmount or when `url` changes,
+ * so it never sets state after unmount.
+ *
+ * Pass `url = null` to skip fetching (e.g. until an id is known); `data` resets to null and
+ * `loading` is false while skipped. `opts` is read per-request but does NOT re-trigger on its
+ * own identity — change `url` or call `refresh()` to re-fetch. Set `opts.timeoutMs` to bound
+ * a request that can hang.
+ */
+export declare function useJsonFetch<T>(url: string | null, opts?: UseJsonFetchOptions): UseJsonFetchResult<T>;
+/**
+ * `useJsonFetch` scoped to a plugin's own API: builds `/api/plugins/<id>/<path>`
+ * so components never hand-assemble the prefix. Pass `path = null` to skip.
+ */
+export declare function usePluginJsonFetch<T>(pluginId: string, path: string | null, opts?: UseJsonFetchOptions): UseJsonFetchResult<T>;

package/_internal/app/hooks/use-nav-badge.d.ts

@@ -0,0 +1,13 @@
+import type { NavBadge } from '@makinbakin/sdk/types';
+/**
+ * Sync a nav item's badge to the value passed each render. Calls
+ * `setNavBadge(pluginId, navItemId, badge)` only when the badge's value
+ * actually changes — the effect is keyed on a serialization of `count` +
+ * `tone`, not the object identity (which a parent recreates every render).
+ *
+ * This is the recommended glue for a badge provider: keep your own summary
+ * hook (fetch + refresh) per plugin, derive a `NavBadge | null`, and pass it
+ * here. Teardown is handled by `unregisterPlugin`, so this does not clear on
+ * unmount (which would flicker on dev hot-reload).
+ */
+export declare function useNavBadge(pluginId: string, navItemId: string, badge: NavBadge | null): void;

package/_internal/app/hooks/use-plugin-event.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Subscribe to server-pushed plugin events over the shell's SINGLE EventSource.
+ *
+ * The shell owns one `/api/events` connection (`use-sse.ts`) with reconnect +
+ * backoff. Plugins used to each open their own `new EventSource('/api/events')`
+ * — N connections, no reconnect. Instead the shell fans every
+ * `{ type: 'plugin-event', event, … }` payload into this process-global emitter,
+ * and components subscribe by event name here. The handler receives the full
+ * payload so it can filter on `assetId`/`taskId`/etc.
+ */
+export type PluginEventPayload = Record<string, unknown> & {
+    event?: string;
+};
+type Handler = (payload: PluginEventPayload) => void;
+/** Called by the shell SSE handler for every `plugin-event` payload. */
+export declare function emitPluginEvent(payload: PluginEventPayload): void;
+/** Run `handler` whenever the server pushes a plugin event named `event`. */
+export declare function usePluginEvent(event: string, handler: Handler): void;
+export {};

package/_internal/app/hooks/use-query-state.d.ts

@@ -1,14 +1,5 @@
 /**
- * Syncs a single string value to a URL query parameter.
- * Returns [value, setValue, pushValue] like useState.
- * - setValue uses router.replace (no history entry) — good for filters, search, view toggles
- * - pushValue uses router.push (creates history entry) — good for opening drawers/modals
- * When value equals defaultValue, the param is removed from the URL.
+ * @deprecated Import URL-backed state from `@makinbakin/sdk/navigation`.
+ * This module remains as a compatibility adapter for existing consumers.
  */
-export declare function useQueryState(key: string, defaultValue?: string): [string, (v: string) => void, (v: string) => void];
-/**
- * Syncs a string[] to a URL query parameter (comma-separated).
- * Returns [values, setValues] like useState.
- * When array is empty, the param is removed from the URL.
- */
-export declare function useQueryArrayState(key: string): [string[], (v: string[]) => void];
+export { useQueryArrayState, useQueryState } from '@makinbakin/sdk/navigation';

package/_internal/app/hooks/use-resizable-pane.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared split-pane resize behavior. A pane is anchored to the
+ * trailing edge (bottom for 'y', right for 'x') and resized by dragging the
+ * divider on its leading edge — dragging toward that edge (up / left) grows it.
+ * {@link useHorizontalResize} provides the right-anchored panel wrapper;
+ * keep all drag / persistence / a11y logic here so it lives in exactly one place.
+ */
+export type ResizeAxis = 'x' | 'y';
+interface CoreOptions {
+    axis: ResizeAxis;
+    defaultSize: number;
+    minSize: number;
+    maxSize: number;
+    /** localStorage key suffix; persisted under `${storagePrefix}${storageKey}`. */
+    storageKey?: string;
+    storagePrefix: string;
+}
+export interface ResizeHandleProps {
+    role: 'separator';
+    tabIndex: 0;
+    'aria-orientation': 'horizontal' | 'vertical';
+    'aria-valuenow': number;
+    'aria-valuemin': number;
+    'aria-valuemax': number;
+    onMouseDown: (e: React.MouseEvent) => void;
+    onTouchStart: (e: React.TouchEvent) => void;
+    onKeyDown: (e: React.KeyboardEvent) => void;
+}
+export interface ResizablePane {
+    size: number;
+    setSize: (n: number) => void;
+    handleProps: ResizeHandleProps;
+}
+export declare function useResizablePane({ axis, defaultSize, minSize, maxSize, storageKey, storagePrefix }: CoreOptions): ResizablePane;
+export {};

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

@@ -3,6 +3,8 @@ export interface ScheduleJob {
     displayName: string;
     description?: string;
     agentId?: string;
+    /** Team assignment (#189) — mutually exclusive with agentId. */
+    teamId?: string;
     humanSchedule: string;
     cron?: string;
     paused: boolean;
@@ -31,20 +33,26 @@ export interface ScheduleJob {
     lastRun?: string;
     createdAt?: string;
     updatedAt?: string;
+    /** One-shot ('at') job that has fired: disabled with its consumed instant. */
+    completed?: boolean;
+    completedAt?: string;
 }
 export interface RunEntry {
     runId: string;
     timestamp: string;
-    status: 'success' | 'failure' | 'skipped';
+    status: 'success' | 'failure' | 'skipped' | 'pending';
     taskId?: string;
     error?: string;
+    skippedReason?: string;
 }
 interface UseScheduleOptions {
     agent?: string;
 }
 export declare function useScheduleJobs(options?: UseScheduleOptions): {
     jobs: ScheduleJob[];
+    allJobs: ScheduleJob[];
     loading: boolean;
+    fetchFailed: boolean;
     refresh: () => Promise<void>;
     pauseJob: (jobId: string, pauseUntil?: string) => Promise<boolean>;
     resumeJob: (jobId: string) => Promise<boolean>;
@@ -56,6 +64,44 @@ export declare function useScheduleJobs(options?: UseScheduleOptions): {
     skipNext: (jobId: string, n?: number) => Promise<boolean>;
     duplicateJob: (jobId: string, overrides?: Record<string, unknown>) => Promise<boolean>;
 };
+/** A plugin-contributed dated event rendered alongside job occurrences (#191). */
+export interface ScheduledDomainEvent {
+    id: string;
+    pluginId: string;
+    title: string;
+    startsAt?: string;
+    endsAt?: string;
+    dueAt?: string;
+    kind: string;
+    status?: string;
+    url?: string;
+    reschedulable?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** One server-computed calendar placement — see plugins/schedule/lib/occurrences.ts. */
+export interface ScheduleOccurrence {
+    jobId: string;
+    /** Absolute instant, ISO-8601 UTC — render in the browser's local tz. */
+    at: string;
+    past: boolean;
+    /** Ledger disposition for past Bakin occurrences (absent = never claimed). */
+    disposition?: 'pending' | 'created' | 'skipped' | 'seeded';
+    taskId?: string;
+    skipReason?: string;
+}
+/**
+ * Server-computed occurrences for a time range — the ONLY placement source
+ * for the calendar views (kind-aware, timezone/DST-correct; the old client-
+ * side cron parsing is gone). Refetches on schedule SSE events.
+ */
+export declare function useOccurrences(fromIso: string, toIso: string): {
+    occurrences: ScheduleOccurrence[];
+    events: ScheduledDomainEvent[];
+    unevaluated: string[];
+    droppedProviders: string[];
+    loading: boolean;
+    refresh: () => Promise<void>;
+};
 export declare function useRunHistory(jobId: string | null, limit?: number): {
     runs: RunEntry[];
     loading: boolean;

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;
+};