@makinbakin/sdk 0.0.1-rc.2 → 0.0.1-rc.20

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

@@ -58,11 +58,34 @@ export interface MessageArgs extends RuntimeMessageToolPolicy {
      * same agentId + threadId pair to the same provider/runtime session.
      */
     threadId?: string;
+    /**
+     * Per-turn model override (`provider/model` id). Omit to use the agent's
+     * configured model. The caller (Bakin's routing policy) resolves it.
+     */
+    model?: string;
+    /**
+     * Per-turn thinking level. Omit to use the runtime/agent default.
+     */
+    thinking?: string;
     metadata?: RuntimeMetadata;
 }
+/** Token usage for one agent turn, when the runtime reports it. */
+export interface MessageUsage {
+    input?: number;
+    output?: number;
+    total?: number;
+    /** Cached-input tokens read (priced far below fresh input when known). */
+    cacheRead?: number;
+    /** Cached-input tokens written (cache creation). */
+    cacheWrite?: number;
+    /** Resolved model the runtime ran, when known. */
+    model?: string;
+}
 export interface MessageResult {
     id: string;
     content?: string;
+    /** Per-turn token usage, omitted when the runtime reported none. */
+    usage?: MessageUsage;
     metadata?: RuntimeMetadata;
 }
 export interface RuntimeToolActivity {
@@ -82,11 +105,6 @@ export interface ChatChunk {
     content?: string;
     data?: RuntimeMetadata | RuntimeToolActivity;
 }
-export interface ToolDefinition {
-    name: string;
-    description?: string;
-    inputSchema?: unknown;
-}
 export interface ToolResult {
     ok: boolean;
     output?: unknown;
@@ -203,31 +221,6 @@ export interface ApprovalResolveEvent {
     response: ApprovalResponse;
     channelId: string;
 }
-export interface ChannelMessageEvent {
-    channelId: string;
-    messageId: string;
-    actor: {
-        type: 'agent' | 'human';
-        id: string;
-        displayName?: string;
-    };
-    body: string;
-    threadId?: string;
-    receivedAt: string;
-    metadata?: RuntimeMetadata;
-}
-export interface ChannelInteractionEvent {
-    channelId: string;
-    interactionId: string;
-    actor: {
-        type: 'agent' | 'human';
-        id: string;
-        displayName?: string;
-    };
-    kind: string;
-    payload: RuntimeMetadata;
-    receivedAt: string;
-}
 export interface DurableApprovalRecord {
     approvalId: string;
     owner: {
@@ -259,6 +252,19 @@ export interface RuntimeSession {
     updatedAt?: string;
     metadata?: RuntimeMetadata;
 }
+export interface RuntimeSessionStoreStats {
+    agentId: string;
+    /** Live entries in the runtime's session store for this agent. */
+    storeEntries: number;
+    /**
+     * Top-level files in the agent's sessions directory (session artifacts,
+     * including the store itself) — cache subtrees are excluded so the
+     * orphaned-artifact ratio stays meaningful.
+     */
+    fileCount: number;
+    /** Total bytes of the agent's sessions directory, subtrees included. */
+    diskBytes: number;
+}
 export interface RuntimeMemoryTier {
     id: string;
     label: string;
@@ -308,38 +314,100 @@ export interface RuntimeAvailableModel {
     tags?: string[];
     metadata?: RuntimeMetadata;
 }
-export interface TaskDispatchArgs {
-    bakinTaskId: string;
-    agentId?: string;
-    title: string;
-    description?: string;
+export type RuntimeImageOutputFormat = 'png' | 'jpeg' | 'jpg' | 'webp';
+export type RuntimeImageBackground = 'transparent' | 'opaque' | 'auto';
+/**
+ * Image capability is intentionally all-optional. A thin runtime that exposes a
+ * single image tool maps on by filling minimal fields (e.g. one synthesized
+ * provider with a defaultModel); a rich runtime fills more. Consumers MUST
+ * treat a sparse capability as normal and never require a field a thin runtime
+ * cannot provide — gaps are filled below, in the adapter/shim, not pushed up
+ * into plugins. See .claude/knowledge/media-generation-adapter-architecture.md.
+ */
+export interface RuntimeImageProviderCapabilities {
+    generate?: {
+        maxCount?: number;
+        supportsSize?: boolean;
+        supportsAspectRatio?: boolean;
+        supportsResolution?: boolean;
+    };
+    edit?: {
+        enabled?: boolean;
+        maxCount?: number;
+        maxInputImages?: number;
+        supportsSize?: boolean;
+        supportsAspectRatio?: boolean;
+        supportsResolution?: boolean;
+    };
+    geometry?: {
+        sizes?: string[];
+        aspectRatios?: string[];
+        resolutions?: string[];
+    };
+    output?: {
+        formats?: string[];
+        qualities?: string[];
+        backgrounds?: string[];
+    };
     metadata?: RuntimeMetadata;
 }
-export interface TaskDispatchResult {
-    flowId: string;
-}
-export interface TaskExecutionStatus {
-    flowId: string;
-    bakinTaskId?: string;
-    state: 'queued' | 'running' | 'blocked' | 'succeeded' | 'failed' | 'cancelled' | 'unknown';
-    currentStep?: string | null;
-    blockingReason?: string | null;
-    retryCount?: number;
-    startedAt?: string | null;
-    endedAt?: string | null;
-    updatedAt?: string | null;
+export interface RuntimeImageProvider {
+    id: string;
+    label?: string;
+    defaultModel?: string;
+    models?: string[];
+    available?: boolean;
+    configured?: boolean;
+    selected?: boolean;
+    capabilities?: RuntimeImageProviderCapabilities;
     metadata?: RuntimeMetadata;
 }
-export interface ListExecutionsOpts {
-    bakinTaskId?: string;
-    agentId?: string;
-    state?: TaskExecutionStatus['state'];
-    limit?: number;
+export interface RuntimeImageGenerateInput {
+    prompt: string;
+    provider?: string;
+    model?: string;
+    count?: number;
+    width?: number;
+    height?: number;
+    size?: string;
+    aspectRatio?: string;
+    resolution?: string;
+    outputFormat?: RuntimeImageOutputFormat;
+    background?: RuntimeImageBackground;
+    /**
+     * Reference/context image file paths conditioning the generation. The caller
+     * (Bakin) resolves managed asset ids to concrete paths before the adapter
+     * sees them. Native generation has no file input, so a generate carrying
+     * references is routed through the edit-style invocation (#418).
+     */
+    referenceImages?: string[];
+    timeoutMs?: number;
+    metadata?: RuntimeMetadata;
 }
-export interface TaskExecutionEvent {
-    flowId: string;
-    bakinTaskId?: string;
-    status: TaskExecutionStatus;
+export interface RuntimeImageEditInput extends RuntimeImageGenerateInput {
+    files: string[];
+}
+export interface RuntimeImageFile {
+    filePath: string;
+    mimeType?: string;
+    width?: number;
+    height?: number;
+    provider?: string;
+    model?: string;
+    url?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeImageGenerationResult {
+    images: RuntimeImageFile[];
+    provider?: string;
+    model?: string;
+    providerText?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeImagesAccess {
+    providers(): Promise<RuntimeImageProvider[]>;
+    generate(input: RuntimeImageGenerateInput): Promise<RuntimeImageGenerationResult>;
+    edit(input: RuntimeImageEditInput): Promise<RuntimeImageGenerationResult>;
 }
 export interface CronJob {
     id: string;
@@ -403,7 +471,6 @@ export interface AgentRuntimeAdapter {
         removeWorkspaceFile(agentId: string, path: string): Promise<void>;
         updatePermissions(agentId: string, patch: RuntimePermissionPatch): Promise<void>;
         updateAllowlist(agentId: string, patch: RuntimeAllowlistPatch): Promise<void>;
-        heartbeat(agentId: string): Promise<boolean>;
     };
     messaging: {
         send(args: MessageArgs): Promise<MessageResult>;
@@ -411,7 +478,6 @@ export interface AgentRuntimeAdapter {
     };
     tools: {
         invoke(agentId: string, name: string, args: unknown): Promise<ToolResult>;
-        list(agentId: string): Promise<ToolDefinition[]>;
     };
     channels: {
         list(): Promise<ChannelInfo[]>;
@@ -423,8 +489,6 @@ export interface AgentRuntimeAdapter {
         cancelApproval(args: CancelApprovalArgs): Promise<void>;
         resolveApproval(args: ResolveApprovalArgs): Promise<void>;
         subscribeApprovalResponses(handler: (event: ApprovalResolveEvent) => void): Unsubscribe;
-        onMessage(handler: (event: ChannelMessageEvent) => void): Unsubscribe;
-        onInteraction(handler: (event: ChannelInteractionEvent) => void): Unsubscribe;
     };
     skills: {
         list(agentId?: string): Promise<RuntimeSkill[]>;
@@ -435,6 +499,12 @@ export interface AgentRuntimeAdapter {
     sessions: {
         list(agentId?: string): Promise<RuntimeSession[]>;
         get(sessionId: string): Promise<RuntimeSession | null>;
+        /**
+         * Per-agent session-store disk stats. Optional: runtimes without a
+         * file-backed session store omit it, and callers must treat absence
+         * as "stats unavailable" — skip, never error.
+         */
+        storeStats?(): Promise<RuntimeSessionStoreStats[]>;
     };
     memory: {
         listTiers(): Promise<RuntimeMemoryTier[]>;
@@ -464,12 +534,16 @@ export interface AgentRuntimeAdapter {
             includeUnavailable?: boolean;
         }): Promise<RuntimeAvailableModel[]>;
     };
-    tasks: {
-        dispatch(args: TaskDispatchArgs): Promise<TaskDispatchResult>;
-        getExecutionStatus(flowId: string): Promise<TaskExecutionStatus>;
-        listExecutions(opts?: ListExecutionsOpts): Promise<TaskExecutionStatus[]>;
-        cancelExecution(flowId: string): Promise<void>;
-        subscribeExecutionUpdates(handler: (event: TaskExecutionEvent) => void): Unsubscribe;
+    images?: RuntimeImagesAccess;
+    /**
+     * Access to the runtime's private media store (e.g. channel attachments).
+     * `resolveUri` maps a runtime-private URI (OpenClaw's `media://…`) to an
+     * absolute local file path; null for unknown schemes or missing files —
+     * never throws for not-found. Optional: runtimes without a media store
+     * omit it, and callers must treat absence as "cannot resolve".
+     */
+    media?: {
+        resolveUri(uri: string): Promise<string | null>;
     };
     cron: {
         list(): Promise<CronJob[]>;

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

@@ -0,0 +1,86 @@
+/**
+ * Typed runtime-failure contracts crossing the adapter boundary.
+ *
+ * Adapters map every provider failure to a `RuntimeError` with a structural
+ * `kind` before it leaves the adapter package. Core (dispatch) classifies on
+ * `kind` exclusively — never on error-message text. The original provider
+ * error is always preserved on `cause` so transport-level codes
+ * (ECONNRESET, AbortError, …) survive the boundary for logging/diagnostics.
+ */
+export type RuntimeErrorKind = 
+/** Socket drop, disconnect, not-connected, fetch failure — transient. */
+'transport'
+/** An RPC/transport timer fired without a final response. */
+ | 'timeout'
+/** The provider session died mid-turn; carries a RuntimeTurnDiagnosis. */
+ | 'session_death'
+/** Provider/auth cooldown — model provider unavailable, retry later. */
+ | 'provider_cooldown'
+/** Structured runtime failure (HTTP-status class, CLI exit, protocol). */
+ | 'runtime_failed';
+/**
+ * Structured provider metadata for `provider_cooldown` failures, extracted by
+ * the adapter from provider-specific error payloads so core never parses
+ * provider strings.
+ */
+export interface RuntimeProviderInfo {
+    provider?: string;
+    model?: string;
+    /** e.g. 'timeout' when the provider entered cooldown after a timeout. */
+    cooldownReason?: string;
+    /** No auth profile was available (vs. an active profile in cooldown). */
+    authProfileUnavailable?: boolean;
+}
+export interface RuntimeErrorOptions {
+    kind: RuntimeErrorKind;
+    cause?: unknown;
+    providerInfo?: RuntimeProviderInfo;
+}
+export declare class RuntimeError extends Error {
+    readonly kind: RuntimeErrorKind;
+    readonly providerInfo?: RuntimeProviderInfo;
+    constructor(message: string, options: RuntimeErrorOptions);
+}
+export type RuntimeTurnFailureReason = 
+/** session.ended with a non-success status that was not a runtime timeout. */
+'session_interrupted'
+/** The session/turn genuinely timed out server-side. */
+ | 'runtime_timeout';
+/**
+ * Post-mortem of a dead provider turn, assembled entirely inside the runtime
+ * adapter (Bakin core never reads provider files). Every field is optional
+ * evidence — a partial diagnosis is still more useful than a generic timeout.
+ */
+export interface RuntimeTurnDiagnosis {
+    reason: RuntimeTurnFailureReason;
+    /** Provider session id the turn ran in. */
+    sessionId?: string;
+    /** Raw provider session end status, e.g. 'interrupted'. */
+    sessionStatus?: string;
+    /** Provider-reported timeout flag from the session end event. */
+    timedOut?: boolean;
+    /** Total bytes of the final assistant output that killed the turn. */
+    completionBytes?: number;
+    /** Provider truncated the recorded completion (trajectory size limit). */
+    outputTruncated?: boolean;
+    /** completionBytes exceeded the configured oversized-output threshold. */
+    oversizedOutput?: boolean;
+    /** Last tool the agent invoked before the turn died. */
+    lastToolCall?: string;
+    /** Truncated completion text preserved for salvage (capped by the adapter). */
+    salvagedText?: string;
+    /** Token usage recorded for the fatal completion, when available. */
+    usage?: {
+        input?: number;
+        output?: number;
+        total?: number;
+    };
+    /** One-line human-readable diagnosis. */
+    detail?: string;
+}
+export declare class RuntimeTurnError extends RuntimeError {
+    readonly diagnosis: RuntimeTurnDiagnosis;
+    constructor(diagnosis: RuntimeTurnDiagnosis, options?: {
+        cause?: unknown;
+    });
+}

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

@@ -1,5 +1,7 @@
 export type { AdapterAuditEvent, AdapterHealthCheckDefinition, AdapterHealthCheckResult, AdapterInitOpts, AdapterLogger, Unsubscribe, } from '../shared';
 export type { ChannelCapability } from './capabilities';
 export { hasChannelCapability } from './capabilities';
+export { RuntimeError, RuntimeTurnError } from './errors';
+export type { RuntimeErrorKind, RuntimeErrorOptions, RuntimeProviderInfo, RuntimeTurnDiagnosis, RuntimeTurnFailureReason, } from './errors';
 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, RuntimeToolActivity, RuntimeAvailableModel, RuntimeConfigAccess, RuntimeMemoryEntry, RuntimeMemoryEntryStat, RuntimeMemoryPathMatch, RuntimeMemoryReadRange, RuntimeMemorySearchResult, RuntimeMemoryTier, RuntimeMessageToolPolicy, RuntimeMessageToolsMode, 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, ChannelMessageArgs, ChatChunk, ContentDeliveryArgs, CreateApprovalArgs, CreateCronJobInput, CreateRuntimeAgentInput, CronJob, CronRun, DeliveryResult, DurableApprovalRecord, EditApprovalArgs, MessageArgs, MessageResult, MessageUsage, NotificationArgs, ResolveApprovalArgs, RuntimeAgent, RuntimeAllowlistPatch, RuntimeToolActivity, RuntimeAvailableModel, RuntimeConfigAccess, RuntimeImageBackground, RuntimeImageEditInput, RuntimeImageFile, RuntimeImageGenerateInput, RuntimeImageGenerationResult, RuntimeImageOutputFormat, RuntimeImageProvider, RuntimeImageProviderCapabilities, RuntimeImagesAccess, RuntimeMemoryEntry, RuntimeMemoryEntryStat, RuntimeMemoryPathMatch, RuntimeMemoryReadRange, RuntimeMemorySearchResult, RuntimeMemoryTier, RuntimeMessageToolPolicy, RuntimeMessageToolsMode, RuntimeMetadata, RuntimePermissionPatch, RawCronSnapshot, RuntimeSession, RuntimeSessionStoreStats, RuntimeSkill, ToolResult, UpdateCronJobInput, UpdateRuntimeAgentInput, WorkspaceFile, } from './concepts';

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

@@ -30,6 +30,7 @@ export interface BakinPaths {
     workflows: string;
     settings: string;
     logs: string;
+    db: string;
 }
 export declare function getBakinPaths(): BakinPaths;
 /**

package/_internal/core/format.d.ts

@@ -1,5 +1,14 @@
 /** Human-readable relative time from an ISO timestamp */
 export declare function formatAge(timestamp: string): string;
+/**
+ * Human-readable absolute date+time with calendar awareness:
+ * "Today 3:45 PM" / "Yesterday 9:02 AM" / "Jan 5 3:45 PM", carrying the year
+ * only for prior-year timestamps (a bare "Jan 5" is ambiguous once runs and
+ * completions outlive the calendar). Falls back to the raw input if unparseable.
+ */
+export declare function formatDateTime(timestamp: string): string;
+/** Human-readable elapsed duration from a millisecond count ("850ms" / "42s" / "3m 5s"); null when undefined. */
+export declare function formatDuration(ms?: number): string | null;
 /** Human-readable file size */
 export declare function formatSize(bytes: number): string;
 /** Check if a heartbeat timestamp is stale (> 15 min) */