@makinbakin/sdk 0.0.0-bootstrap.0

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

@@ -0,0 +1,458 @@
+import type { AdapterHealthCheckDefinition, AdapterInitOpts, Unsubscribe } from '../shared';
+import type { ChannelCapability } from './capabilities';
+export type RuntimeMetadata = Record<string, unknown>;
+export interface RuntimeAgent {
+    id: string;
+    name: string;
+    role?: string;
+    model?: string;
+    status?: 'active' | 'inactive' | 'unknown';
+    metadata?: RuntimeMetadata;
+}
+export interface CreateRuntimeAgentInput {
+    id?: string;
+    name: string;
+    role?: string;
+    model?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface UpdateRuntimeAgentInput {
+    name?: string;
+    role?: string;
+    model?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimePermissionPatch {
+    allow?: string[];
+    deny?: string[];
+    replace?: boolean;
+}
+export interface RuntimeAllowlistPatch {
+    add?: string[];
+    remove?: string[];
+    replace?: string[];
+}
+export interface WorkspaceFile {
+    path: string;
+    content: string;
+    updatedAt?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface MessageArgs {
+    agentId: string;
+    content: string;
+    threadId?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface MessageResult {
+    id: string;
+    content?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface ChatChunk {
+    type: 'text' | 'tool' | 'status' | 'done' | 'error';
+    content?: string;
+    data?: unknown;
+}
+export interface ToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}
+export interface ToolResult {
+    ok: boolean;
+    output?: unknown;
+    error?: {
+        message: string;
+        recoverable: boolean;
+    };
+}
+export interface ChannelInfo {
+    id: string;
+    platform: string;
+    label: string;
+    capabilities: ChannelCapability[];
+    metadata?: RuntimeMetadata;
+}
+export interface DeliveryResult {
+    deliveries: ApprovalDelivery[];
+}
+export interface NotificationArgs {
+    channels: string[];
+    notification: {
+        severity: 'info' | 'warn' | 'error' | 'success';
+        title: string;
+        body: string;
+        fields?: {
+            label: string;
+            value: string;
+        }[];
+        metadata?: RuntimeMetadata;
+    };
+}
+export interface ChannelMessageArgs {
+    channels: string[];
+    message: {
+        body: string;
+        title?: string;
+        threadId?: string;
+        metadata?: RuntimeMetadata;
+    };
+}
+export interface ContentDeliveryArgs {
+    channels: string[];
+    content: {
+        title: string;
+        body?: string;
+        url?: string;
+        files?: Array<{
+            name: string;
+            path: string;
+            contentType?: string;
+        } | {
+            kind: 'asset';
+            filename: string;
+            mimeType?: string;
+        }>;
+        metadata?: RuntimeMetadata;
+    };
+}
+export interface ApprovalOption {
+    id: string;
+    label: string;
+    variant?: 'primary' | 'destructive' | 'neutral';
+}
+export interface ApprovalDelivery {
+    channelId: string;
+    ref: string;
+    renderedAt: string;
+}
+export interface ApprovalPatch {
+    body?: string;
+    options?: ApprovalOption[];
+    expiresAt?: string;
+    context?: RuntimeMetadata;
+}
+export interface ApprovalResponse {
+    selectedOption: string;
+    respondedAt: string;
+    actor: {
+        type: 'agent' | 'human';
+        id: string;
+        displayName?: string;
+    };
+    comment?: string;
+}
+export interface ApprovalRenderResult {
+    deliveries: ApprovalDelivery[];
+}
+export interface ApprovalRenderRef {
+    approvalId: string;
+    deliveries: ApprovalDelivery[];
+}
+export interface CreateApprovalArgs {
+    approvalId: string;
+    channels: string[];
+    request: {
+        title: string;
+        body: string;
+        options: ApprovalOption[];
+        expiresAt?: string;
+        context?: RuntimeMetadata;
+    };
+}
+export interface EditApprovalArgs extends ApprovalRenderRef {
+    patch: ApprovalPatch;
+}
+export interface CancelApprovalArgs extends ApprovalRenderRef {
+    reason?: string;
+}
+export interface ResolveApprovalArgs extends ApprovalRenderRef {
+    response: ApprovalResponse;
+}
+export interface ApprovalResolveEvent {
+    approvalId: string;
+    response: ApprovalResponse;
+    channelId: string;
+}
+export interface 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: {
+        workflowId: string;
+        runId: string;
+        stepId: string;
+        taskId?: string;
+    };
+    status: 'pending' | 'approved' | 'rejected' | 'cancelled' | 'expired';
+    request: CreateApprovalArgs['request'];
+    deliveries: ApprovalDelivery[];
+    response?: ApprovalResponse;
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt?: string;
+}
+export interface RuntimeSkill {
+    name: string;
+    path?: string;
+    instructions?: string;
+    files?: Record<string, string>;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeSession {
+    id: string;
+    agentId: string;
+    title?: string;
+    startedAt?: string;
+    updatedAt?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeMemoryTier {
+    id: string;
+    label: string;
+    description?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeMemoryEntry {
+    id: string;
+    tierId: string;
+    agentId?: string;
+    path?: string;
+    content: string;
+    updatedAt?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeMemoryEntryStat {
+    size: number;
+    mtimeMs: number;
+    updatedAt?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeMemoryReadRange {
+    content: string;
+    size: number;
+    mtimeMs?: number;
+    updatedAt?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeMemoryPathMatch {
+    tierId: string;
+    id: string;
+    agentId?: string;
+    path: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeMemorySearchResult {
+    results: unknown[];
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeAvailableModel {
+    id: string;
+    name?: string;
+    input?: string;
+    contextWindow?: number;
+    local?: boolean;
+    available?: boolean;
+    tags?: string[];
+    metadata?: RuntimeMetadata;
+}
+export interface TaskDispatchArgs {
+    bakinTaskId: string;
+    agentId?: string;
+    title: string;
+    description?: 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;
+    metadata?: RuntimeMetadata;
+}
+export interface ListExecutionsOpts {
+    bakinTaskId?: string;
+    agentId?: string;
+    state?: TaskExecutionStatus['state'];
+    limit?: number;
+}
+export interface TaskExecutionEvent {
+    flowId: string;
+    bakinTaskId?: string;
+    status: TaskExecutionStatus;
+}
+export interface CronJob {
+    id: string;
+    name: string;
+    schedule: string;
+    command: string;
+    enabled: boolean;
+    toolsAllow?: string[];
+    metadata?: RuntimeMetadata;
+}
+export interface CronRun {
+    id: string;
+    jobId: string;
+    status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+    startedAt?: string;
+    endedAt?: string;
+    output?: string;
+    error?: string;
+}
+export interface CreateCronJobInput {
+    id?: string;
+    name: string;
+    schedule: string;
+    command: string;
+    enabled?: boolean;
+    toolsAllow?: string[];
+    metadata?: RuntimeMetadata;
+}
+export type UpdateCronJobInput = Partial<Omit<CreateCronJobInput, 'id' | 'toolsAllow'>> & {
+    toolsAllow?: string[] | null;
+};
+export interface RawCronSnapshot {
+    provider: string;
+    capturedAt: string;
+    snapshot: unknown;
+}
+export interface RuntimeConfigAccess {
+    get<T = Record<string, unknown>>(): Promise<T>;
+    update(patch: Record<string, unknown>): Promise<void>;
+    replace<T = Record<string, unknown>>(next: T, reason: string): Promise<void>;
+    raw<T = unknown>(key: string, reason: string): Promise<T>;
+}
+export interface AgentRuntimeAdapter {
+    readonly name: string;
+    readonly version: string;
+    readonly requiredCoreVersion: string;
+    initialize(opts: AdapterInitOpts): Promise<void>;
+    shutdown(): Promise<void>;
+    ping(): Promise<boolean>;
+    restart(): Promise<void>;
+    getHealthChecks(): AdapterHealthCheckDefinition[];
+    agents: {
+        list(): Promise<RuntimeAgent[]>;
+        get(agentId: string): Promise<RuntimeAgent | null>;
+        create(input: CreateRuntimeAgentInput): Promise<RuntimeAgent>;
+        update(agentId: string, input: UpdateRuntimeAgentInput): Promise<RuntimeAgent>;
+        remove(agentId: string): Promise<void>;
+        listWorkspaceFiles(agentId: string): Promise<string[]>;
+        readWorkspaceFile(agentId: string, path: string): Promise<WorkspaceFile | null>;
+        writeWorkspaceFile(agentId: string, file: WorkspaceFile): Promise<void>;
+        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>;
+        stream(args: MessageArgs): AsyncIterable<ChatChunk>;
+    };
+    tools: {
+        invoke(agentId: string, name: string, args: unknown): Promise<ToolResult>;
+        list(agentId: string): Promise<ToolDefinition[]>;
+    };
+    channels: {
+        list(): Promise<ChannelInfo[]>;
+        sendNotification(args: NotificationArgs): Promise<DeliveryResult>;
+        sendMessage(args: ChannelMessageArgs): Promise<DeliveryResult>;
+        deliverContent(args: ContentDeliveryArgs): Promise<DeliveryResult>;
+        createApproval(args: CreateApprovalArgs): Promise<ApprovalRenderResult>;
+        editApproval(args: EditApprovalArgs): Promise<ApprovalRenderResult>;
+        cancelApproval(args: CancelApprovalArgs): Promise<void>;
+        resolveApproval(args: ResolveApprovalArgs): Promise<void>;
+        subscribeApprovalResponses(handler: (event: ApprovalResolveEvent) => void): Unsubscribe;
+        onMessage(handler: (event: ChannelMessageEvent) => void): Unsubscribe;
+        onInteraction(handler: (event: ChannelInteractionEvent) => void): Unsubscribe;
+    };
+    skills: {
+        list(agentId?: string): Promise<RuntimeSkill[]>;
+        get(name: string, agentId?: string): Promise<RuntimeSkill | null>;
+        write(skill: RuntimeSkill, agentId?: string): Promise<void>;
+        remove(name: string, agentId?: string): Promise<void>;
+    };
+    sessions: {
+        list(agentId?: string): Promise<RuntimeSession[]>;
+        get(sessionId: string): Promise<RuntimeSession | null>;
+    };
+    memory: {
+        listTiers(): Promise<RuntimeMemoryTier[]>;
+        listEntries(tierId: string, opts?: {
+            agentId?: string;
+        }): Promise<RuntimeMemoryEntry[]>;
+        getEntry(tierId: string, id: string, opts?: {
+            agentId?: string;
+        }): Promise<RuntimeMemoryEntry | null>;
+        statEntry(tierId: string, id: string, opts?: {
+            agentId?: string;
+        }): Promise<RuntimeMemoryEntryStat | null>;
+        readEntryRange(tierId: string, id: string, opts?: {
+            agentId?: string;
+            offset?: number;
+            length?: number;
+        }): Promise<RuntimeMemoryReadRange | null>;
+        resolvePath(path: string): Promise<RuntimeMemoryPathMatch | null>;
+        watchPaths(): Promise<string[]>;
+        search(query: string, opts?: {
+            agentId?: string;
+            limit?: number;
+        }): Promise<RuntimeMemorySearchResult>;
+    };
+    models: {
+        listAvailable(opts?: {
+            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;
+    };
+    cron: {
+        list(): Promise<CronJob[]>;
+        get(id: string): Promise<CronJob | null>;
+        create(input: CreateCronJobInput): Promise<CronJob>;
+        update(id: string, patch: UpdateCronJobInput): Promise<CronJob>;
+        remove(id: string): Promise<void>;
+        runNow(id: string): Promise<CronRun>;
+        listRuns(jobId: string): Promise<CronRun[]>;
+        getRaw(id: string, reason: string): Promise<unknown | null>;
+        restoreRaw(id: string, snapshot: unknown, reason: string): Promise<CronJob>;
+    };
+    config: RuntimeConfigAccess;
+}

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

@@ -0,0 +1,5 @@
+import type { AgentRuntimeAdapter, RuntimeAgent } from './concepts';
+export declare function selectRuntimeMainAgent(agents: RuntimeAgent[]): RuntimeAgent | null;
+export declare function getRuntimeMainAgent(runtime: AgentRuntimeAdapter): Promise<RuntimeAgent | null>;
+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

@@ -0,0 +1,5 @@
+export type { AdapterAuditEvent, AdapterHealthCheckDefinition, AdapterHealthCheckResult, AdapterInitOpts, AdapterLogger, Unsubscribe, } from '../shared';
+export type { ChannelCapability } from './capabilities';
+export { hasChannelCapability } from './capabilities';
+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, RuntimeAvailableModel, RuntimeConfigAccess, RuntimeMemoryEntry, RuntimeMemoryEntryStat, RuntimeMemoryPathMatch, RuntimeMemoryReadRange, RuntimeMemorySearchResult, RuntimeMemoryTier, RuntimeMetadata, RuntimePermissionPatch, RawCronSnapshot, RuntimeSession, RuntimeSkill, TaskDispatchArgs, TaskDispatchResult, TaskExecutionEvent, TaskExecutionStatus, ToolDefinition, ToolResult, UpdateCronJobInput, UpdateRuntimeAgentInput, WorkspaceFile, } from './concepts';

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

@@ -0,0 +1,37 @@
+export type Unsubscribe = () => void;
+export interface AdapterLogger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+export interface AdapterAuditEvent {
+    adapter: string;
+    action: string;
+    subject?: string;
+    data?: Record<string, unknown>;
+    at?: string;
+}
+export interface AdapterInitOpts {
+    contentDir: string;
+    settings?: Record<string, unknown>;
+    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;
+}
+export interface AdapterVersionInfo {
+    readonly name: string;
+    readonly version: string;
+    readonly requiredCoreVersion?: string;
+}

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

@@ -0,0 +1,2 @@
+export * from './metadata';
+export * from './route';

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

@@ -0,0 +1,92 @@
+export type ContractVisibility = 'public' | 'internal' | 'experimental';
+export type ContractStability = 'stable' | 'beta' | 'experimental' | 'deprecated';
+export type HookKind = 'rpc' | 'event' | 'waterfall';
+export interface SchemaLike<T = unknown> {
+    parse(data: unknown): T;
+    safeParse?(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: unknown;
+    };
+}
+export interface SourceLocation {
+    file: string;
+    symbol?: string;
+    line?: number;
+}
+export interface DocsExample {
+    title: string;
+    description?: string;
+    code?: string;
+    request?: unknown;
+    response?: unknown;
+    test?: 'automated' | 'schema' | 'illustrative';
+    reason?: string;
+}
+export interface ContractMetadata {
+    summary: string;
+    description: string;
+    visibility: ContractVisibility;
+    stability: ContractStability;
+    since?: string;
+    deprecated?: {
+        since?: string;
+        removeIn?: string;
+        replacement?: string;
+    };
+    source?: SourceLocation;
+    examples?: DocsExample[];
+    related?: string[];
+}
+export interface RouteContract<Input = unknown, Output = unknown> extends ContractMetadata {
+    kind: 'route';
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    input?: SchemaLike<Input>;
+    output?: SchemaLike<Output>;
+    permissions?: string[];
+}
+export interface CliCommandContract extends ContractMetadata {
+    kind: 'cli';
+    name: string;
+    usage: string;
+    group?: string;
+    aliases?: string[];
+    options?: Array<{
+        name: string;
+        description: string;
+        value?: string;
+        required?: boolean;
+    }>;
+    environment?: string[];
+}
+export interface HookContract<Input = unknown, Output = unknown> extends ContractMetadata {
+    kind: 'hook';
+    name: string;
+    hookKind: HookKind;
+    input?: SchemaLike<Input>;
+    output?: SchemaLike<Output>;
+}
+export interface SlotContract<Props = unknown> extends ContractMetadata {
+    kind: 'slot';
+    name: string;
+    props?: SchemaLike<Props>;
+    renderLocation: string;
+    ordering?: string;
+    fallback?: string;
+}
+export interface ExecToolContract<Input = unknown, Output = unknown> extends ContractMetadata {
+    kind: 'exec-tool';
+    name: string;
+    input?: SchemaLike<Input>;
+    output?: SchemaLike<Output>;
+    permissions?: string[];
+}
+export type PublicContract = RouteContract | CliCommandContract | HookContract | SlotContract | ExecToolContract;
+export declare function defineRouteContract<const T extends RouteContract>(contract: T): T;
+export declare function defineCliCommandContract<const T extends CliCommandContract>(contract: T): T;
+export declare function defineHookContract<const T extends HookContract>(contract: T): T;
+export declare function defineSlotContract<const T extends SlotContract>(contract: T): T;
+export declare function defineExecToolContract<const T extends ExecToolContract>(contract: T): T;

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

@@ -0,0 +1,9 @@
+import type { APIRoute } from '../plugin-types';
+export type DocsAwareAPIRoute = APIRoute & {
+    summary: string;
+    description: string;
+    visibility: NonNullable<APIRoute['visibility']>;
+    stability: NonNullable<APIRoute['stability']>;
+};
+export declare function defineApiRoute<const T extends DocsAwareAPIRoute>(route: T): T;
+export declare const definePluginRoute: typeof defineApiRoute;

package/_internal/core/format.d.ts

@@ -0,0 +1,6 @@
+/** Human-readable relative time from an ISO timestamp */
+export declare function formatAge(timestamp: string): string;
+/** 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;

package/_internal/core/openapi/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared error envelope and global response builders for the dispatcher.
+ *
+ * The dispatcher emits these automatically:
+ *   - 400 on params/query/body parse failure (when any are declared)
+ *   - 415 on body content-type mismatch (when body is declared)
+ *
+ * Routes don't repeat them in their `responses` map; OpenAPI emission picks
+ * them up from `globalErrorResponses` based on the route's input declarations.
+ */
+import { z } from 'zod';
+export declare const errorEnvelope: z.ZodObject<{
+    error: z.ZodString;
+    issues: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ErrorEnvelope = z.infer<typeof errorEnvelope>;
+export interface GlobalErrorOptions {
+    /** True when `params`, `query`, or `body` is declared. */
+    hasInput: boolean;
+    /** True when `body` is declared. */
+    hasBody: boolean;
+}
+/**
+ * Returns the global error responses (`400`/`415`) appropriate for a route
+ * given its declared inputs. Empty object when nothing applies.
+ */
+export declare function globalErrorResponses(opts: GlobalErrorOptions): Record<string, unknown>;
+/** Build a JSON error response body. */
+export declare function errorResponseBody(error: string, issues?: unknown[]): ErrorEnvelope;

package/_internal/core/openapi/zod-to-openapi.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Wraps `z.toJSONSchema` for embedding in OpenAPI 3.1 documents.
+ *
+ * Targets `openapi-3.1` so emitted schemas omit the JSON Schema `$schema`
+ * draft link (which would clutter the OpenAPI document).
+ */
+import { z } from 'zod';
+export type OpenApiSchema = Record<string, unknown>;
+export declare function zodToOpenApi(schema: z.ZodType<unknown>): OpenApiSchema;
+/**
+ * Convert a route path with `:param` placeholders to OpenAPI's `{param}`.
+ * Idempotent — paths already in OpenAPI form pass through.
+ */
+export declare function normalizeOpenApiPath(path: string): string;