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

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

@@ -17,7 +17,19 @@ export type RuntimeErrorKind =
 /** Provider/auth cooldown — model provider unavailable, retry later. */
  | 'provider_cooldown'
 /** Structured runtime failure (HTTP-status class, CLI exit, protocol). */
- | 'runtime_failed';
+ | 'runtime_failed'
+/**
+ * The caller intentionally cancelled the turn (MessageArgs.signal) —
+ * terminal: never retried, never diagnosed, never enters the recovery
+ * ladder.
+ */
+ | 'aborted'
+/**
+ * A CRUD mutation addressed an entity (agent, skill, cron job) that does
+ * not exist on the runtime. Reads return `null` for absence; only
+ * mutations reject with this kind (R28).
+ */
+ | 'not_found';
 /**
  * Structured provider metadata for `provider_cooldown` failures, extracted by
  * the adapter from provider-specific error payloads so core never parses

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

@@ -1,5 +1,24 @@
 import type { AgentRuntimeAdapter, RuntimeAgent } from './concepts';
+/**
+ * Resolve the runtime's ORCHESTRATOR from its roster (P2.6) — a
+ * runtime-declared fact, never a baked constant. Ladder:
+ *
+ *   1. id 'main'           — the declared-id convention both adapters seed.
+ *   2. role 'orchestrator' — the declared-role generalization: a runtime
+ *      whose orchestrator has a different id resolves here.
+ *   3. first agent         — degraded last resort so single-agent rosters
+ *      always resolve.
+ *
+ * The id rung leads deliberately: role text is fuzzy (OpenClaw derives it
+ * from IDENTITY.md, which agent packages can set) — an installed persona
+ * claiming "Orchestrator" must never outrank the declared main agent.
+ */
 export declare function selectRuntimeMainAgent(agents: RuntimeAgent[]): RuntimeAgent | null;
 export declare function getRuntimeMainAgent(runtime: AgentRuntimeAdapter): Promise<RuntimeAgent | null>;
+/**
+ * Resolved orchestrator id. The `fallback` applies ONLY to an empty/unreadable
+ * roster (degraded mode: runtime down mid-flight) — callers that can degrade
+ * differently should pass their own.
+ */
 export declare function getRuntimeMainAgentId(runtime: AgentRuntimeAdapter, fallback?: string): Promise<string>;
 export declare function getRuntimeMainAgentName(runtime: AgentRuntimeAdapter, fallback?: string): Promise<string>;

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

@@ -1,7 +1,10 @@
-export type { AdapterAuditEvent, AdapterHealthCheckDefinition, AdapterHealthCheckResult, AdapterInitOpts, AdapterLogger, Unsubscribe, } from '../shared';
+export type { AdapterAuditEvent, AdapterInitOpts, AdapterLogger, AdapterToolActivityEvent, AdapterTurnActivityEvent, RuntimeExecToolDescriptor, RuntimeExecToolInvokeResult, RuntimeExecToolProvider, Unsubscribe, } from '../shared';
+export { beginAdapterTurnActivity } from './turn-activity';
+export type { AdapterTurnActivityReporter, BeginAdapterTurnActivityOptions } from './turn-activity';
 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, 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';
+export type { AgentRuntimeAdapter, ApprovalDelivery, ApprovalOption, ApprovalPatch, ApprovalRenderRef, ApprovalRenderResult, ApprovalResolveEvent, ApprovalResponse, CancelApprovalArgs, ChannelInfo, ChannelMessageArgs, ChatChunk, ChatTextFormat, ContentDeliveryArgs, CreateApprovalArgs, CreateCronJobInput, CreateRuntimeAgentInput, CronJob, CronRun, DeliveryResult, DurableApprovalRecord, EditApprovalArgs, MessageArgs, MessageAttachment, MessageResult, MessageUsage, NotificationArgs, ResolveApprovalArgs, RuntimeAgent, RuntimeAllowlistPatch, RuntimeToolActivity, RuntimeAvailableModel, RuntimeCapabilities, CapabilityMode, ToolAccessStyle, RuntimeToolAccess, ToolAccessProvisioningStatus, RuntimeCredentialStatus, RuntimeRoutingPolicy, RuntimeRoutingSupport, CapabilitySet, RuntimeImageBackground, RuntimeImageEditInput, RuntimeImageFile, RuntimeImageGenerateInput, RuntimeImageGenerationResult, RuntimeImageOutputFormat, RuntimeImageProvider, RuntimeImageProviderCapabilities, RuntimeImagesAccess, RuntimeExtensionInfo, RuntimeExtensionsAccess, RuntimeMemoryEntry, RuntimeMemoryEntryStat, RuntimeMemoryPathMatch, RuntimeMemoryReadRange, RuntimeMemorySearchResult, RuntimeMemoryTier, RuntimeMessageToolPolicy, RuntimeMessageToolsMode, RuntimeMetadata, RawCronSnapshot, RuntimeSession, RuntimeSessionStoreStats, RuntimeSkill, UpdateCronJobInput, UpdateRuntimeAgentInput, WorkspaceFile, WorkspaceFileStat, } from './concepts';
+export { RUNTIME_MEDIA_URI_SCHEME, DEFAULT_OVERSIZED_OUTPUT_BYTES } from './concepts';

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

@@ -0,0 +1,79 @@
+import type { AgentRuntimeAdapter } from './concepts';
+/**
+ * Opt-in channels surface for the mock (delivery capability pairs with it —
+ * see createMockRuntimeAdapter). The DEFAULT mock omits `channels` entirely:
+ * it is an optional contract member (Pi omits it in production), so plugin
+ * code must feature-detect. A bare `runtime.channels.x()` against the default
+ * mock now throws instead of silently passing (audit finding H2).
+ *
+ * Usage: `createMockRuntimeAdapter({ channels: mockChannels() })`
+ */
+export declare function mockChannels(): NonNullable<AgentRuntimeAdapter['channels']>;
+/**
+ * Opt-in cron surface for the mock — same rationale as mockChannels():
+ * `cron` is an optional contract member (Pi omits it), so the default mock
+ * omits it and consumers feature-detect.
+ *
+ * Usage: `createMockRuntimeAdapter({ cron: mockCron() })`
+ */
+/**
+ * Filename the isolation-honoring mock drops into each turn's runWorkspace —
+ * the conformance isolation probe's observable (same-agent-concurrency D1).
+ */
+export declare const MOCK_ISOLATION_PROBE = "cwd-probe.txt";
+/**
+ * Opt-in same-agent-turn isolation for the mock: declares
+ * `concurrency.sameAgentTurns: 'isolated'` and honors
+ * `MessageArgs.runWorkspace` by dropping MOCK_ISOLATION_PROBE into the
+ * handed directory before delegating — the minimal observable proof the
+ * conformance isolation check requires. The DEFAULT mock stays
+ * 'serialized' (minimal shape).
+ *
+ * Usage: `withMockIsolation(createMockRuntimeAdapter())`
+ */
+export declare function withMockIsolation(base: AgentRuntimeAdapter): AgentRuntimeAdapter;
+export declare function mockCron(): NonNullable<AgentRuntimeAdapter['cron']>;
+export declare function createMockRuntimeAdapter(overrides?: Partial<AgentRuntimeAdapter>): AgentRuntimeAdapter;
+/**
+ * Opt-in image-input capability override for attachment tests:
+ * `createMockRuntimeAdapter({ capabilities: mockImageInputCapabilities() })`.
+ * The default mock declares `imageInput: false` (minimal shape); streams
+ * still echo attachments in the reply text so pass-through is assertable
+ * either way.
+ */
+export declare function mockImageInputCapabilities(): (opts?: {
+    agentId?: string;
+}) => Promise<ReturnType<typeof mockCapabilities>>;
+declare function mockCapabilities(deliveryNative: boolean): {
+    toolCalling: {
+        mode: "native";
+        access: {
+            style: "mcp";
+            mcpServerTemplate: string;
+            perTurnExecToolFiltering: boolean;
+        };
+    };
+    delivery: {
+        mode: "unavailable" | "native";
+    };
+    imageGen: {
+        mode: "unavailable";
+    };
+    memory: {
+        mode: "native";
+    };
+    sessions: {
+        mode: "native";
+    };
+    workspaceFiles: {
+        mode: "native";
+    };
+    input: {
+        imageInput: boolean;
+        audioInput: boolean;
+    };
+    concurrency: {
+        sameAgentTurns: "serialized";
+    };
+};
+export {};

package/_internal/core/adapters/runtime/turn-activity.d.ts

@@ -0,0 +1,23 @@
+import type { AdapterTurnActivityEvent } from '../shared';
+type TurnResultEvent = Extract<AdapterTurnActivityEvent, {
+    phase: 'result';
+}>;
+export interface AdapterTurnActivityReporter {
+    readonly turnId: string;
+    finish(result: Pick<TurnResultEvent, 'status'> & Partial<Pick<TurnResultEvent, 'resultId' | 'usage'>>): void;
+}
+export interface BeginAdapterTurnActivityOptions {
+    onActivity?: (event: AdapterTurnActivityEvent) => void;
+    onCallbackError?: (error: unknown) => void;
+    agentId: string;
+    activityClass: AdapterTurnActivityEvent['activityClass'];
+    threadId?: string;
+    operation: AdapterTurnActivityEvent['operation'];
+}
+/**
+ * Start one adapter messaging lifecycle and return its exactly-once finisher.
+ * Both the observer and its error reporter are contained: observability is
+ * never allowed to change a turn's outcome.
+ */
+export declare function beginAdapterTurnActivity(options: BeginAdapterTurnActivityOptions): AdapterTurnActivityReporter;
+export {};

package/_internal/core/adapters/shared.d.ts

@@ -1,3 +1,4 @@
+import type { ActivityClass } from '@makinbakin/sdk/types';
 export type Unsubscribe = () => void;
 export interface AdapterLogger {
     debug(message: string, data?: unknown): void;
@@ -12,26 +13,135 @@ export interface AdapterAuditEvent {
     data?: Record<string, unknown>;
     at?: string;
 }
+/**
+ * One Bakin exec tool as offered across the adapter boundary. The zod
+ * shapes stay core-side; adapters receive plain JSON Schema so no
+ * validation library leaks into the contract.
+ */
+export interface RuntimeExecToolDescriptor {
+    name: string;
+    description: string;
+    /** JSON Schema (object) for the tool's parameters. */
+    parametersSchema: Record<string, unknown>;
+}
+export interface RuntimeExecToolInvokeResult {
+    ok: boolean;
+    /** Model-facing result text (JSON on success, `ERROR: …` on failure). */
+    text: string;
+}
+/** 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;
+}
+/**
+ * One normalized runtime-native tool lifecycle event observed by an adapter.
+ * The host uses result events for cross-runtime observability; call events are
+ * included so it can derive duration when the runtime does not report one.
+ */
+interface AdapterToolActivityBase {
+    agentId: string;
+    /** Producer-assigned classification from the originating runtime turn. */
+    activityClass: ActivityClass;
+    /** Owning adapter turn; required so terminal reconciliation cannot silently opt out. */
+    turnId: string;
+    threadId?: string;
+    callId?: string;
+    toolName: string;
+}
+/**
+ * One normalized tool lifecycle event. Runtime-private status aliases must be
+ * resolved by the adapter before crossing this boundary.
+ */
+export type AdapterToolActivityEvent = AdapterToolActivityBase & {
+    phase: 'call';
+    status: 'running';
+} | AdapterToolActivityBase & {
+    phase: 'result';
+    status: 'completed' | 'failed' | 'aborted';
+    durationMs?: number;
+};
+interface AdapterTurnActivityBase {
+    agentId: string;
+    /** Producer-assigned classification from the originating runtime turn. */
+    activityClass: ActivityClass;
+    threadId?: string;
+    /** Messaging surface that owns the turn. */
+    operation: 'send' | 'stream';
+    /** Adapter-generated identity shared by this turn's start and result. */
+    turnId: string;
+}
+/**
+ * One normalized messaging turn lifecycle event observed at the adapter
+ * boundary. Every executed send/stream emits exactly one start and one result.
+ * Result identity and usage are present when the messaging surface reports
+ * them (currently send); adapters never fabricate usage.
+ */
+export type AdapterTurnActivityEvent = AdapterTurnActivityBase & {
+    phase: 'start';
+    status: 'running';
+} | AdapterTurnActivityBase & {
+    phase: 'result';
+    status: 'completed' | 'failed' | 'aborted';
+    durationMs: number;
+    resultId?: string;
+    usage?: MessageUsage;
+};
+/**
+ * Bakin's exec-tool registry offered to runtimes that deliver tools
+ * in-process (Pi registers these as native session tools). Out-of-band
+ * runtimes (OpenClaw reaches the same registry over its native MCP client)
+ * ignore it. `list()` reads the LIVE registry — call it at session build
+ * time so late plugin registrations and hot reloads are visible.
+ * Usage recording + audit happen inside `invoke`; adapters add nothing.
+ */
+export interface RuntimeExecToolProvider {
+    list(): RuntimeExecToolDescriptor[];
+    invoke(name: string, params: Record<string, unknown>, agentId: string): Promise<RuntimeExecToolInvokeResult>;
+}
 export interface AdapterInitOpts {
     contentDir: string;
     settings?: Record<string, unknown>;
+    /**
+     * LIVE view of the adapter-private settings bag. `settings` is a boot-time
+     * snapshot; surfaces whose behavior must track settings edits WITHOUT a
+     * restart (extension trust policy, per-turn knobs) read through this.
+     * Optional: tests and thin callers may omit it (snapshot semantics).
+     */
+    getLiveSettings?: () => Record<string, unknown> | undefined;
     logger?: AdapterLogger;
     audit?: (event: AdapterAuditEvent) => void;
-}
-export interface AdapterHealthCheckResult {
-    check: string;
-    status: 'ok' | 'warn' | 'error' | 'fixed';
-    message: string;
-    autoFixable: boolean;
-}
-export interface AdapterHealthCheckDefinition {
-    id: string;
-    name: string;
-    run(): Promise<AdapterHealthCheckResult[]>;
-    autoFix?: boolean;
+    execTools?: RuntimeExecToolProvider;
+    /**
+     * Best-effort host observability tap for tool activity across every runtime
+     * messaging surface. Adapters contain callback failures so telemetry can
+     * never fail an agent turn.
+     */
+    onToolActivity?: (event: AdapterToolActivityEvent) => void;
+    /**
+     * Best-effort host observability tap for every messaging send/stream turn.
+     * Adapters contain callback failures so telemetry can never fail a turn.
+     */
+    onTurnActivity?: (event: AdapterTurnActivityEvent) => void;
+    /**
+     * Base URL of Bakin's MCP server (e.g. `http://localhost:3737`) — the seam
+     * a runtime whose agents reach Bakin over MCP (OpenClaw) needs to write its
+     * per-agent server entries during `provisionToolAccess`. Core knows the
+     * port; the adapter does not, so it is threaded here. In-process runtimes
+     * (Pi) ignore it.
+     */
+    bakinMcpBaseUrl?: string;
 }
 export interface AdapterVersionInfo {
     readonly name: string;
     readonly version: string;
     readonly requiredCoreVersion?: string;
 }
+export {};

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

@@ -28,9 +28,17 @@ export interface BakinPaths {
     inbox: string;
     tasks: string;
     workflows: string;
+    /** Brand records — per-brand dirs with manifest + guidelines + lessons (#419). */
+    brands: string;
+    /** Chat plugin transcripts + index (Bakin-owned UI data). */
+    chat: string;
     settings: string;
     logs: string;
+    /** Data dir for Bakin's private antfly instance (created on demand by the adapter). */
+    antfly: string;
     db: string;
+    /** Bakin-owned bin dir for capability-pack binaries; prepended to PATH at server boot. */
+    bin: string;
 }
 export declare function getBakinPaths(): BakinPaths;
 /**

package/_internal/core/docs/route.d.ts

@@ -1,4 +1,4 @@
-import type { APIRoute } from '../plugin-types';
+import type { RegisteredAPIRoute as APIRoute } from '../plugin-types';
 export type DocsAwareAPIRoute = APIRoute & {
     summary: string;
     description: string;

package/_internal/core/format/structured.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Human-readable rendering of structured (JSON-ish) values — the shared home
+ * (#608) so UI surfaces, channels, and tool-activity feeds never dump raw
+ * JSON blobs at people. Client + server safe (pure, no deps).
+ *
+ * Variants:
+ *   - formatStructured(value, { markdown }) → labeled multi-line prose
+ *     (`Label: value`, nested objects indented; markdown bolds the labels
+ *     for channel messages).
+ *   - summarizeStructured(value, cap) → ONE compact line for chips/badges.
+ *   - unwrapToolResult(value) → peel a runtime tool-result envelope
+ *     (`{content:[{type:'text',text}]}`) down to its meaningful payload,
+ *     parsing an inner JSON string when present.
+ */
+export declare function humanizeKey(key: string): string;
+export interface FormatStructuredOptions {
+    /** Bold labels for markdown surfaces (channel messages). */
+    markdown?: boolean;
+    /** Override the section heading; a blank line follows it. Omit for no heading. */
+    heading?: string;
+    /** Cap the rendered body; appends a truncation marker when exceeded. */
+    cap?: number;
+}
+/**
+ * Labeled prose for a structured value. Returns '' when there's nothing
+ * human-reviewable (empty object / all-empty fields) — callers show nothing
+ * rather than a bare "{}". A scalar renders as itself.
+ */
+export declare function formatStructured(value: unknown, opts?: FormatStructuredOptions): string;
+/**
+ * ONE compact line for chips/badges. Skips status noise (`ok: true` is shown
+ * by the chip's color, not its text), prefers a descriptive field, and
+ * describes collections by count rather than dropping them.
+ */
+export declare function summarizeStructured(value: unknown, cap?: number): string;
+/**
+ * Peel a runtime tool-result envelope to its meaningful payload:
+ *   { content: [{ type:'text', text }] } → the joined text, JSON-parsed when
+ *   the text is itself a JSON document (bakin exec tools return JSON strings).
+ * Peels REPEATEDLY — an agent that shells a tool via bash produces a
+ * doubly-wrapped envelope (runtime content → shell stdout → MCP content).
+ * Non-envelope values pass through unchanged. Never throws.
+ */
+export declare function unwrapToolResult(value: unknown, depth?: number): unknown;

package/_internal/core/format.d.ts

@@ -7,9 +7,13 @@ export declare function formatAge(timestamp: string): string;
  * 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. */
+/**
+ * Human-readable elapsed duration from a millisecond count, rolling up through
+ * units ("850ms" / "42s" / "3m 5s" / "2h 5m" / "3d 2h"); 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) */
 export declare function isStale(timestamp: string, thresholdMs?: number): boolean;
+export { humanizeKey, formatStructured, summarizeStructured, unwrapToolResult, type FormatStructuredOptions, } from './format/structured';

package/_internal/core/media/downscale.d.ts

@@ -0,0 +1,18 @@
+export declare const INLINE_ATTACHMENT_LIMIT_BYTES = 2000000;
+export interface PreparedAttachment {
+    path: string;
+    mimeType: string;
+    downscaled: boolean;
+}
+/**
+ * Returns the original when it already fits; otherwise a downscaled temp
+ * JPEG. Throws (loudly, with the silent-degradation rationale) when the
+ * image cannot be brought under the cap — never sends an oversized file.
+ */
+export declare function prepareImageAttachment(path: string, mimeType: string): Promise<PreparedAttachment>;
+/**
+ * Remove the temp dir a downscale created. Callers own the lifetime — e.g.
+ * the enrichment engine calls this after its LAST send (the corrective
+ * re-ask reuses the file). No-op for originals.
+ */
+export declare function cleanupPreparedAttachment(prepared: PreparedAttachment): void;

package/_internal/core/media/sharp-loader.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The subset of the sharp API Bakin uses, typed STRUCTURALLY — a
+ * `typeof` import of the sharp module here would put the sharp package
+ * into the declaration graph of everything that can reach this file
+ * (including the published SDK testing bundle since #703), and sharp
+ * deliberately has no declared version anywhere. Extend this interface
+ * when new call sites need more of sharp's surface.
+ */
+export interface SharpResizeOptions {
+    width?: number;
+    height?: number;
+    fit?: 'inside' | 'cover' | 'contain' | 'fill' | 'outside';
+    withoutEnlargement?: boolean;
+}
+export interface SharpPipeline {
+    rotate(): SharpPipeline;
+    resize(options: SharpResizeOptions): SharpPipeline;
+    resize(width?: number, height?: number, options?: SharpResizeOptions): SharpPipeline;
+    jpeg(options?: {
+        quality?: number;
+    }): SharpPipeline;
+    png(options?: {
+        quality?: number;
+    }): SharpPipeline;
+    webp(options?: {
+        quality?: number;
+    }): SharpPipeline;
+    metadata(): Promise<{
+        width?: number;
+        height?: number;
+        format?: string;
+    }>;
+    toFile(path: string): Promise<unknown>;
+}
+export type Sharp = (input: string) => SharpPipeline;
+export declare function loadSharp(): Promise<Sharp | null>;