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

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

@@ -0,0 +1,105 @@
+/**
+ * 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'
+/**
+ * The provider deterministically rejected the MODEL ID for this account
+ * (retired/unentitled model — the #852 class). Not a cooldown: waiting
+ * never fixes it, so it is never retried. `providerInfo.model` carries the
+ * qualified rejected id; core records it as availability evidence.
+ */
+ | 'model_not_supported'
+/**
+ * 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
+ * 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/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,5 +1,11 @@
-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, 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, ChatTextFormat, ContentDeliveryArgs, CreateApprovalArgs, CreateThreadArgs, CreatedThread, CreateCronJobInput, CreateRuntimeAgentInput, CronJob, CronRun, DeliveryResult, DurableApprovalRecord, EditApprovalArgs, EditChannelMessageArgs, InboundChannelAttachment, InboundChannelMessage, MessageArgs, MessageAttachment, MessageResult, MessageUsage, NotificationArgs, ResolveApprovalArgs, RuntimeAgent, RuntimeAllowlistPatch, RuntimeToolActivity, RuntimeAvailableModel, RuntimeCapabilities, CapabilityMode, ToolAccessStyle, RuntimeToolAccess, ToolAccessProvisioningStatus, RuntimeCredentialStatus, ProviderCredentialStatus, ProviderCredentialInventory, RuntimeConfigChangeKind, RestartAdvice, 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, RuntimeSessionContextStats, RuntimeSkill, UpdateCronJobInput, UpdateRuntimeAgentInput, WorkspaceFile, WorkspaceFileStat, } from './concepts';
+export { RUNTIME_MEDIA_URI_SCHEME, DEFAULT_OVERSIZED_OUTPUT_BYTES } from './concepts';
+export { isSafeSkillFilePath, isExecutableSkillFile, readSkillTree, SKILL_SIDECAR_NAMES } from './skill-files';

package/_internal/core/adapters/runtime/skill-files.d.ts

@@ -0,0 +1,12 @@
+/** Relative path inside a skill dir: no absolute, no backslash, no `..`/empty segments. */
+export declare function isSafeSkillFilePath(path: string): boolean;
+/** Metadata sidecars — never part of a skill's file map. */
+export declare const SKILL_SIDECAR_NAMES: Set<string>;
+/** Scripts get the executable bit at projection: shebang or a script extension. */
+export declare function isExecutableSkillFile(path: string, content: string): boolean;
+/**
+ * Read a skill directory into a relative-path→content map, skipping
+ * symlinks and the metadata sidecars (`.installedBy`/`.userEdited`) at any
+ * depth. Unreadable roots read as empty.
+ */
+export declare function readSkillTree(root: string): Record<string, string>;

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

@@ -0,0 +1,99 @@
+import type { AgentRuntimeAdapter, ProviderCredentialStatus, RestartAdvice } 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 status-only credential inventory for the mock (#907 / #378 slice).
+ * `credentials` is an optional contract member, so the DEFAULT mock omits
+ * it — eligibility code must feature-detect and treat absence as
+ * "credential evidence unavailable" (models read `unknown`, never
+ * `ineligible`). Pass `evidence: 'partial'` to exercise the honest-partial
+ * branch (OpenClaw's CLI probe failing).
+ *
+ * Usage: `createMockRuntimeAdapter({ credentials: mockCredentials([{ providerId: 'mock', configured: true }]) })`
+ */
+export declare function mockCredentials(providers?: ProviderCredentialStatus[], evidence?: 'complete' | 'partial'): NonNullable<AgentRuntimeAdapter['credentials']>;
+/**
+ * Opt-in restart advice for the mock (#878). Optional member; the default
+ * mock omits it so the Models banner's generic-fallback path is what mock
+ * consumers see unless they opt in. The same advice is returned for every
+ * change kind unless a per-kind map is given.
+ *
+ * Usage: `createMockRuntimeAdapter({ restartAdvice: mockRestartAdvice({ needed: false }) })`
+ */
+export declare function mockRestartAdvice(advice: RestartAdvice | Partial<Record<'model-config' | 'roster' | 'routing-policy', RestartAdvice>>): NonNullable<AgentRuntimeAdapter['restartAdvice']>;
+/**
+ * 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,5 @@
+import type { ActivityClass } from '@makinbakin/sdk/types';
+import type { ChannelBridge } from '../delivery/bridge';
 export type Unsubscribe = () => void;
 export interface AdapterLogger {
     debug(message: string, data?: unknown): void;
@@ -12,26 +14,145 @@ 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;
+    /**
+     * Optional runtime-neutral channel bridge (issue #669). Runtimes without a
+     * native delivery layer (Pi) expose `runtime.channels` by delegating to
+     * this handle when `isConfigured()`; natively-delivering runtimes ignore
+     * it. This is a HANDLE only — the server owns `boot()`/`shutdown()`;
+     * adapters never connect transports.
+     */
+    channelBridge?: ChannelBridge;
     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;
+    /** Host-issued credential scoped to a single agent; never log this value. */
+    getMcpCredential?: (agentId: string) => string;
 }
 export interface AdapterVersionInfo {
     readonly name: string;
     readonly version: string;
     readonly requiredCoreVersion?: string;
 }
+export {};

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

@@ -28,8 +28,19 @@ 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;
+    /** Media prebuild store (sharp for compiled binaries, #889) — versioned dirs + receipt. */
+    media: string;
 }
 export declare function getBakinPaths(): BakinPaths;
 /**

package/_internal/core/delivery/bridge.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Runtime-neutral channel bridge contract (issue #669).
+ *
+ * A ChannelBridge gives a runtime WITHOUT a native channel/delivery layer
+ * (Pi) a `runtime.channels` surface by delegation. The concrete Discord
+ * implementation lives in `src/core/delivery/` — app code; this package only
+ * defines the seam so adapter packages can accept a bridge without importing
+ * app modules (adapters never import `src/`).
+ *
+ * Lifecycle: the HANDLE is threaded through `AdapterInitOpts.channelBridge`
+ * at adapter init (cheap, no I/O); `boot()`/`shutdown()` are called by the
+ * server only — never inside `createAppServices()`, which read-only CLI
+ * paths also call. `isConfigured()` must be side-effect-free and callable
+ * before boot: adapters use it to decide whether to expose `channels` and
+ * whether `capabilities().delivery.mode` reports `'shimmed'` or
+ * `'unavailable'`.
+ */
+import type { RuntimeChannelSurface } from '../adapters/runtime/channels';
+/** The full channel surface, contract-identical to a native adapter's. */
+export type ChannelSurface = RuntimeChannelSurface;
+export interface ChannelBridge {
+    /**
+     * True when non-secret config AND the transport secret are present.
+     * Side-effect-free; the gate for exposing `channels` on an adapter.
+     */
+    isConfigured(): boolean;
+    /** Connect transports. Server-boot only; idempotent. */
+    boot(): Promise<void>;
+    /** Disconnect and release transports. Safe when never booted. */
+    shutdown(): Promise<void>;
+    /**
+     * The delegated channel surface. Only meaningful when `isConfigured()`;
+     * adapters must not expose it otherwise.
+     */
+    channels: ChannelSurface;
+}

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

@@ -1,6 +1,30 @@
+export interface FormatAgeOptions {
+    /**
+     * Resolve below a minute ("42s ago") instead of flattening to "just now".
+     *
+     * Live-status surfaces need it: on a heartbeat or an activity feed the
+     * difference between five seconds and fifty is the signal, and minute
+     * granularity erases it. Everything under ten seconds still reads
+     * "just now" so a ticking feed does not flicker through 1s/2s/3s.
+     */
+    precise?: boolean;
+}
 /** Human-readable relative time from an ISO timestamp */
-export declare function formatAge(timestamp: string): string;
+export declare function formatAge(timestamp: string, options?: FormatAgeOptions): 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, 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/health/observation-builders.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Health observation builders — the ONE construction path for check
+ * output, shared by plugins (via `@makinbakin/sdk/utils`, which
+ * re-exports these) and adapter packages (which depend only on
+ * `@bakin/core`).
+ *
+ * The builders CLAMP copy to the health contract's bounds instead of
+ * letting an overlong or blank string invalidate the whole run: a check
+ * that interpolated a long runtime error into its summary used to fail
+ * contract validation wholesale, turning real evidence into a useless
+ * "could not be verified" card (field-diagnosed 2026-07-22). Truncated
+ * copy is honest; discarded evidence is not. Constructing observations
+ * as raw object literals bypasses this protection — always build through
+ * these helpers.
+ */
+import type { ErrorObservationInput, HealthNonEmptyArray, HealthObservationInput, HealthyObservationInput, NotApplicableHealthCheckRunInput, ObservedHealthCheckRunInput, UnknownObservationInput, WarningObservationInput } from '../plugin-types';
+type HealthyObservationFields = Omit<HealthyObservationInput, 'status'>;
+type WarningObservationFields = Omit<WarningObservationInput, 'status'>;
+type ErrorObservationFields = Omit<ErrorObservationInput, 'status'>;
+type UnknownObservationFields = Omit<UnknownObservationInput, 'status'>;
+/** Build a healthy observation. Healthy observations cannot carry incidents. */
+export declare function healthHealthy(input: HealthyObservationFields): HealthyObservationInput;
+/** Build a warning observation with an explicit advisory/watch/action disposition. */
+export declare function healthWarning(input: WarningObservationFields): WarningObservationInput;
+/** Build an error observation. Its incident must require operator action. */
+export declare function healthError(input: ErrorObservationFields): ErrorObservationInput;
+/** Build an Unknown verification observation (watch, or advisory when it self-resolves). */
+export declare function healthUnknown(input: UnknownObservationFields): UnknownObservationInput;
+/** Build a successful observed run. Empty diagnostic output is unrepresentable. */
+export declare function healthObserved(observations: HealthNonEmptyArray<HealthObservationInput>): ObservedHealthCheckRunInput;
+/** Build an explicit successful not-applicable run. */
+export declare function healthNotApplicable(reason: string): NotApplicableHealthCheckRunInput;
+/**
+ * Deterministically coerce arbitrary text (a filesystem path, a table
+ * name, a task id) into the contract's stable resource-id format
+ * (`^[a-z0-9][a-z0-9._:-]{0,127}$`). A raw path used as a resource id
+ * failed contract validation and nuked a REAL finding into a generic
+ * "could not be verified" card for three releases (field-diagnosed
+ * 2026-07-23). Put the human-readable original in `label`, never in `id`.
+ */
+export declare function healthResourceId(raw: string): string;
+export {};

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;