super-dsh 0.1.9 → 0.1.10

package/agent-omp-sdk/dist/sdk-client.d.ts

@@ -0,0 +1,160 @@
+/**
+ * SDK-line replacement for `OmpRpcClient` (apps/omp-web/src/rpc.ts).
+ *
+ * Same public surface — `on` / `onFailure` / `sendRaw` / `send` / `getState`
+ * / `getMessages` / `getSessionStats` / `getSubagents` / `prompt` / `followUp`
+ * / `steer` / `setModel` / `abort` / `newSession` / `close` — so the ported
+ * adapter layer (agent.ts / index.ts / …) compiles unchanged. Instead of one
+ * `omp --mode rpc` child per session, all clients multiplex ONE bun sidecar
+ * process that embeds the OMP agent core via the SDK (app-level
+ * authStorage / modelRegistry are shared; sessions are handle-addressed).
+ *
+ * Type-only imports keep the OMP wire shapes identical to the RPC line.
+ */
+import type { OmpMessage, OmpSessionStats, OmpState, RpcEvent, RpcResponse } from "./rpc-types.js";
+import { OmpSdkSidecar, type SidecarRuntimeFetch, type SidecarSpawn } from "./sidecar-client.js";
+/**
+ * The per-process sidecar pool: ONE bun child shared by every session in this
+ * dsh process, refcounted, plus the two bridge-level call helpers that ride the
+ * same instance.
+ */
+export interface OmpSdkSidecarPool {
+    /** Start a session on the shared sidecar (the SDK has no separate client). */
+    spawnSession(args?: string[], cwd?: string): Promise<OmpSdkClient>;
+    /** Whether the shared sidecar exists right now (someone holds/wants it). */
+    isLive(): boolean;
+    /** One call ONLY when the sidecar is already alive; `undefined` when cold. */
+    callIfLive<T>(method: string, params?: unknown): Promise<T | undefined>;
+    /** One call that MAY start the sidecar (the real-need path). */
+    call<T>(method: string, params?: unknown): Promise<T>;
+    /** The world home whose `<home>/sdk-runtime/` the child runs from. */
+    readonly worldHome: string;
+}
+/**
+ * Build a sidecar pool over one world home.
+ *
+ * Exactly ONE construction per acquire cycle: a leaked merge once left a
+ * duplicate pair here, so every acquire started a second child with `OMP_HOME`
+ * unset and abandoned the first (started, unreferenced, never stopped) — 350
+ * live processes down the line. Whatever else changes, this block must build
+ * the child at most once and must pin the app home on it.
+ *
+ * `runtimeFetch` is injectable ONLY so tests can prove the singleton invariant
+ * and the lazy trigger without downloading ~900 MB: production always uses
+ * {@link OmpSdkSidecar}'s default, which awaits `ensureSdkRuntime` inside
+ * `start()` — i.e. on the first real dispatch and nowhere else.
+ */
+export declare function createOmpSdkSidecarPool(options: {
+    worldHome: string;
+    env?: Record<string, string>;
+    runtimeFetch?: SidecarRuntimeFetch;
+    /** Test seam: replace the child spawn (see {@link SidecarSpawn}). */
+    spawnProcess?: SidecarSpawn;
+}): OmpSdkSidecarPool;
+/**
+ * The default pool, built lazily on first use so importing this module never
+ * resolves a home, touches disk, or spawns anything.
+ */
+export declare function defaultOmpSdkSidecarPool(): OmpSdkSidecarPool;
+/** Whether the shared sidecar exists right now (someone holds/wants it). */
+export declare function isSharedSidecarLive(): boolean;
+/**
+ * Run one bridge-level call ONLY when the shared sidecar is already alive
+ * (a live session or an in-flight on-demand op holds it). Cold → `undefined`
+ * with ZERO processes: this is the periodic path's entry (model-catalog
+ * refresh) so the reconcile tick can never conjure a sidecar.
+ */
+export declare function callSharedIfLive<T = unknown>(method: string, params?: unknown): Promise<T | undefined>;
+/**
+ * Run one bridge-level (non-session) data-plane call on the shared sidecar:
+ * acquire the refcounted singleton, await startup, call `method`, then release.
+ * Used by `omp-cli.ts` for `models.list` and `settings.modelRoles.get/set` so
+ * those paths share the SAME sidecar process as live sessions — never a second
+ * one. Fails with a rejection when the sidecar cannot start or the method
+ * throws; callers translate that into `undefined`/`false` (fail-soft).
+ */
+export declare function callShared<T = unknown>(method: string, params?: unknown): Promise<T>;
+/** One OMP skill's discovery metadata (name/description + body location). */
+export interface OmpSkill {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    source: string;
+}
+/** One OMP slash command's discovery metadata. */
+export interface OmpSlashCommand {
+    name: string;
+    description: string;
+    content: string;
+    source: string;
+}
+/** Discover OMP skills for a workspace (fail-soft: [] on sidecar error). */
+export declare function listSkills(cwd?: string): Promise<OmpSkill[]>;
+/** Discover OMP slash commands for a workspace (fail-soft: [] on sidecar error). */
+export declare function listSlashCommands(cwd?: string): Promise<OmpSlashCommand[]>;
+export declare class OmpSdkClient {
+    #private;
+    constructor(sidecar: OmpSdkSidecar, handle: string, release: () => void);
+    /** Register an OMP session-title listener; returns the unsubscriber. */
+    onTitle(listener: (title: string) => void): () => void;
+    /** Register an OMP event listener; returns the unsubscriber. */
+    on(listener: (event: RpcEvent) => void): () => void;
+    /** Register a failure listener; returns the unsubscriber. */
+    onFailure(listener: (error: Error) => void): () => void;
+    /**
+     * Raw-command escape hatch. The SDK line has no stdio command channel, so
+     * the RPC-specific `extension_ui_response` (approval-card answers) is
+     * accepted and logged — approval flows route through SDK-side approval
+     * events instead (parity work item, see README).
+     */
+    sendRaw(command: Record<string, unknown>): void;
+    /**
+     * Generic command sender for compatibility. The RPC line's free-form
+     * command channel does not exist here; supported commands are mapped onto
+     * sidecar methods, everything else fails loudly.
+     */
+    send(command: Record<string, unknown>): Promise<RpcResponse>;
+    /** Query session state; returns the `get_state`-shaped payload. */
+    getState(): Promise<OmpState>;
+    /** Query the full conversation. */
+    getMessages(): Promise<OmpMessage[]>;
+    /** Live token/context/cost accounting (live sessions only). */
+    getSessionStats(): Promise<OmpSessionStats>;
+    /** Live subagent registry (fail-soft: [] until the SDK exposes it). */
+    getSubagents(): Promise<unknown[]>;
+    /** Render the live session's full base system prompt (fail-soft). */
+    getSystemPrompt(): Promise<string | undefined>;
+    /** Start a turn with a user prompt (fire-and-forget acceptance). */
+    prompt(message: string): Promise<RpcResponse>;
+    /** Queue a follow-up on a busy session. */
+    followUp(message: string): Promise<RpcResponse>;
+    /** Steer an in-flight turn. */
+    steer(message: string): Promise<RpcResponse>;
+    /** Select the active model by provider + model id. */
+    setModel(provider: string, modelId: string): Promise<RpcResponse>;
+    /** Abort the current streaming run. */
+    abort(): Promise<RpcResponse>;
+    /**
+     * Run OMP's own context compaction on the live session (the TUI /compact
+     * handler's exact call). Resolves when the compaction settles.
+     */
+    compact(instructions?: string): Promise<RpcResponse>;
+    /** Context-usage snapshot for pre/post compact metering (fail-soft). */
+    contextUsage(): Promise<{
+        tokens?: number;
+        percent?: number;
+    } | undefined>;
+    /** Discard the current conversation and start a fresh session (same handle). */
+    newSession(): Promise<RpcResponse>;
+    /**
+     * Lazy-surface parity: a real client is born live, so "ensure started" is a
+     * no-op (LazyOmpRpc implements the real deferred spawn behind the same
+     * OmpAgentRpc interface).
+     */
+    ensureStarted(): Promise<void>;
+    /** Always true for a real client (see OmpAgentRpc.spawned). */
+    get spawned(): boolean;
+    /** Discard the current conversation and start a fresh session (same handle). */
+    close(): void;
+}

package/{agent-omp → agent-omp-sdk}/dist/sdk-client.js

@@ -1,5 +1,6 @@
 import { OmpSdkSidecar } from "./sidecar-client.js";
 import { OMP_HOME } from "./knobs.js";
+import { resolveOmpSdkWorldHome } from "./world-home.js";
 /**
  * Parse the CLI args the RPC line passed to `omp --mode rpc`. Only the subset
  * the bridge actually uses is understood; unknown flags fail loudly rather
@@ -31,34 +32,118 @@ let shared = null;
 let sharedStart = null;
 let refcount = 0;
 /**
- * Acquire the process-wide shared sidecar (one per world root, refcounted).
+ * Build a sidecar pool over one world home.
  *
  * Exactly ONE construction per acquire cycle: a leaked merge once left a
  * duplicate pair here, so every acquire started a second child with `OMP_HOME`
  * unset and abandoned the first (started, unreferenced, never stopped) — 350
  * live processes down the line. Whatever else changes, this block must build
  * the child at most once and must pin the app home on it.
+ *
+ * `runtimeFetch` is injectable ONLY so tests can prove the singleton invariant
+ * and the lazy trigger without downloading ~900 MB: production always uses
+ * {@link OmpSdkSidecar}'s default, which awaits `ensureSdkRuntime` inside
+ * `start()` — i.e. on the first real dispatch and nowhere else.
  */
-function acquire() {
-    if (shared === null) {
-        shared = new OmpSdkSidecar({ env: { OMP_HOME } });
-        sharedStart = shared.start().then(() => undefined);
+export function createOmpSdkSidecarPool(options) {
+    let shared = null;
+    let sharedStart = null;
+    let refcount = 0;
+    function acquire() {
+        if (shared === null) {
+            shared = new OmpSdkSidecar({
+                worldHome: options.worldHome,
+                env: { ...(options.env ?? {}) },
+                ...(options.runtimeFetch === undefined ? {} : { runtimeFetch: options.runtimeFetch }),
+                ...(options.spawnProcess === undefined ? {} : { spawnProcess: options.spawnProcess }),
+            });
+            const start = shared.start().then(() => undefined);
+            // A late spawn/ready failure must not be an unhandled rejection: observe
+            // it here (the raw promise below still rejects for real callers).
+            void start.catch(() => undefined);
+            sharedStart = start;
+        }
+        refcount++;
+        return shared;
+    }
+    function release() {
+        refcount = Math.max(0, refcount - 1);
+        if (refcount === 0 && shared !== null) {
+            const dying = shared;
+            shared = null;
+            sharedStart = null;
+            void dying.stop();
+        }
+    }
+    async function callWith(sidecar, method, params) {
+        await sharedStart;
+        return await sidecar.call(method, params);
     }
-    refcount++;
-    return shared;
+    return {
+        worldHome: options.worldHome,
+        async spawnSession(args = [], cwd) {
+            const { approvalMode, resumeFile } = parseSpawnArgs(args);
+            const sidecar = acquire();
+            try {
+                await sharedStart;
+                const created = await sidecar.call("session.create", {
+                    cwd,
+                    persistence: "file",
+                    ...(approvalMode === undefined ? {} : { approvalMode }),
+                    ...(resumeFile === undefined ? {} : { resumeFile }),
+                });
+                return new OmpSdkClient(sidecar, created.handle, release);
+            }
+            catch (error) {
+                release();
+                throw error;
+            }
+        },
+        isLive() {
+            return shared !== null;
+        },
+        async callIfLive(method, params) {
+            if (shared === null)
+                return undefined;
+            const sidecar = acquire();
+            try {
+                return await callWith(sidecar, method, params);
+            }
+            finally {
+                release();
+            }
+        },
+        async call(method, params) {
+            const sidecar = acquire();
+            try {
+                return await callWith(sidecar, method, params);
+            }
+            finally {
+                release();
+            }
+        },
+    };
 }
-function release() {
-    refcount = Math.max(0, refcount - 1);
-    if (refcount === 0 && shared !== null) {
-        const dying = shared;
-        shared = null;
-        sharedStart = null;
-        void dying.stop();
+// ---------------------------------------------------------------------------
+// The process-wide default pool (the world plugin's world home)
+// ---------------------------------------------------------------------------
+let defaultPool = null;
+/**
+ * The default pool, built lazily on first use so importing this module never
+ * resolves a home, touches disk, or spawns anything.
+ */
+export function defaultOmpSdkSidecarPool() {
+    if (defaultPool === null) {
+        defaultPool = createOmpSdkSidecarPool({
+            worldHome: resolveOmpSdkWorldHome(),
+            env: { OMP_HOME },
+        });
     }
+    return defaultPool;
 }
 /** Whether the shared sidecar exists right now (someone holds/wants it). */
 export function isSharedSidecarLive() {
-    return shared !== null;
+    return defaultPool !== null && defaultPool.isLive();
 }
 /**
  * Run one bridge-level call ONLY when the shared sidecar is already alive
@@ -67,16 +152,9 @@ export function isSharedSidecarLive() {
  * refresh) so the reconcile tick can never conjure a sidecar.
  */
 export async function callSharedIfLive(method, params) {
-    if (shared === null)
+    if (defaultPool === null)
         return undefined;
-    const sidecar = acquire();
-    try {
-        await sharedStart;
-        return await sidecar.call(method, params);
-    }
-    finally {
-        release();
-    }
+    return await defaultPool.callIfLive(method, params);
 }
 /**
  * Run one bridge-level (non-session) data-plane call on the shared sidecar:
@@ -87,14 +165,7 @@ export async function callSharedIfLive(method, params) {
  * throws; callers translate that into `undefined`/`false` (fail-soft).
  */
 export async function callShared(method, params) {
-    const sidecar = acquire();
-    try {
-        await sharedStart;
-        return await sidecar.call(method, params);
-    }
-    finally {
-        release();
-    }
+    return await defaultOmpSdkSidecarPool().call(method, params);
 }
 /** Discover OMP skills for a workspace (fail-soft: [] on sidecar error). */
 export async function listSkills(cwd) {
@@ -119,6 +190,8 @@ export async function listSlashCommands(cwd) {
 // ---------------------------------------------------------------------------
 export class OmpSdkClient {
     #sidecar;
+    /** The pool's refcount release — dropped when this client closes. */
+    #release;
     #handle;
     #listeners = new Set();
     #titleListeners = new Set();
@@ -126,7 +199,8 @@ export class OmpSdkClient {
     #closed = false;
     #failure = null;
     #unsub;
-    constructor(sidecar, handle) {
+    constructor(sidecar, handle, release) {
+        this.#release = release;
         this.#sidecar = sidecar;
         this.#handle = handle;
         this.#unsub = sidecar.onEvent((frame) => {
@@ -162,28 +236,6 @@ export class OmpSdkClient {
             }
         });
     }
-    /**
-     * Start a session on the shared sidecar and resolve once it is ready.
-     * Mirrors `OmpRpcClient.spawn(args, cwd)`.
-     */
-    static async spawn(args = [], cwd) {
-        const { approvalMode, resumeFile } = parseSpawnArgs(args);
-        const sidecar = acquire();
-        try {
-            await sharedStart;
-            const created = await sidecar.call("session.create", {
-                cwd,
-                persistence: "file",
-                ...(approvalMode === undefined ? {} : { approvalMode }),
-                ...(resumeFile === undefined ? {} : { resumeFile }),
-            });
-            return new OmpSdkClient(sidecar, created.handle);
-        }
-        catch (error) {
-            release();
-            throw error;
-        }
-    }
     /** Register an OMP session-title listener; returns the unsubscriber. */
     onTitle(listener) {
         this.#titleListeners.add(listener);
@@ -352,7 +404,7 @@ export class OmpSdkClient {
         this.#closed = true;
         this.#unsub();
         void this.#sidecar.call("session.dispose", { handle: this.#handle }).catch(() => { });
-        release();
+        this.#release();
         this.#fail(new Error("omp sdk client closed"));
     }
     #call(method, params) {

package/agent-omp-sdk/dist/sdk-runtime.d.ts

@@ -0,0 +1,211 @@
+/**
+ * sdk-runtime.ts — the lazy, durable SDK runtime the opt-in `omp-sdk` line runs on.
+ *
+ * 2026-10-03 user ruling (spec §2.4): this package declares NO SDK and NO `bun`
+ * dependency and ships NO postinstall/allow-scripts hook. Nothing is fetched at
+ * install time; the FIRST real prompt fetches the runtime into the world home,
+ * where it is durable across sessions, restarts and package upgrades. A second
+ * use reuses it (idempotent), and a FAILED fetch leaves a trace on disk instead
+ * of silently degrading into a confusing sidecar crash.
+ *
+ * Why the world home rather than the package root: the package root is the
+ * installed tarball — read-only in every real consumer install, and shared by
+ * every world. The world home is per-runtime, writable, and already the home of
+ * this adapter's own state.
+ *
+ * What lands where (bun resolves `node_modules` from the runtime dir, so the
+ * sidecar must live there):
+ *
+ *   <worldHome>/sdk-runtime/
+ *     bin/bun                      (a) the bun release, unzipped into place
+ *     package.json / node_modules/ (b) installed with that bun
+ *     sidecar/main.ts              (c) copied from this package
+ *     dist/protocol.js             (c) copied from this package
+ *   <worldHome>/sdk-runtime.json       marker — written LAST, its presence is the contract
+ *   <worldHome>/sdk-runtime.lock       atomic (mkdir) bootstrap lock
+ *   <worldHome>/sdk-runtime.error.log  written ONLY by a failed fetch
+ *
+ * Every step is idempotent, so a half-built runtime heals in place: an existing
+ * `bin/bun` is not re-downloaded, and a missing marker simply re-runs the
+ * remaining steps.
+ *
+ * Measured cost (2026-10-03 probe, spec §1 + §3.3). bun release zip 36.6 MB,
+ * `bun add` ~2-5 s. A FULL install is 1133 MB / 114 packages, but the largest
+ * chunk of that is dead weight here: `@huggingface/transformers` +
+ * `onnxruntime-{node,web}` (~234 MB) come in through `optionalDependencies` and
+ * their native postinstall is blocked by `--ignore-scripts` anyway.
+ * `--omit=optional` alone is 535 MB but BREAKS the import — `@oh-my-pi/pi-natives`
+ * declares its platform binding in `optionalDependencies`, so bun drops
+ * `@oh-my-pi/pi-natives-<platform>` and the sidecar dies with `Failed to load
+ * pi_natives native addon for <platform>`. Re-adding that platform package
+ * explicitly is the fix: **899 MB / 84 packages, import passes**. Escape hatch:
+ * `OMP_SDK_KEEP_OPTIONAL=1` drops `--omit=optional` and reinstates the full
+ * 1133 MB tree.
+ *
+ * bun's install cache is another ~1.2 GB, so it is redirected to
+ * `<runtime>/.cache` and deleted once the install succeeds.
+ *
+ * The pin defaults to 18.5.0 because 18.4.9 is BROKEN for source-level import:
+ * its `src/sdk.ts` imports `./ratchet/prelude` extensionless, so bun resolves
+ * the template file `src/ratchet/prelude.js` instead of the real module and
+ * `bun -e 'await import("@oh-my-pi/pi-coding-agent")'` dies with
+ * `SyntaxError: Export named 'createRatchetPrelude' not found in module
+ * '.../src/ratchet/prelude.js'`. Upstream fixed it in 18.5.0 by renaming the
+ * real module to `./ratchet/prelude-definition`. The smoke step in
+ * {@link ensureSdkRuntime} pins that diagnosis down at fetch time; 18.2.11 is
+ * the last known-good fallback (`OMP_SDK_PACKAGE_VERSION=18.2.11`).
+ *
+ * Probe evidence: 18.5.0 slim = 84 packages / 899 MB / smoke ✅; 18.5.0 full =
+ * 114 packages / 1133 MB / smoke ✅; 18.4.9 = smoke ❌ (`createRatchetPrelude`);
+ * 18.2.11 = smoke ✅ (no `src/ratchet/` at all).
+ */
+/** The coding-agent package the sidecar imports (same program as the `omp` binary). */
+export declare const SDK_PACKAGE = "@oh-my-pi/pi-coding-agent";
+/** Prefix of the per-platform native binding package (`-<platform>` is appended). */
+export declare const SDK_NATIVES_PACKAGE_PREFIX = "@oh-my-pi/pi-natives";
+/**
+ * Pin of {@link SDK_PACKAGE} (and of the native binding package). Defaults to
+ * the operator's local `omp --version` family (18.5.0) so both OMP faces run
+ * the same code; `OMP_SDK_PACKAGE_VERSION` overrides it. Do not go back to
+ * 18.4.9 — see the module doc (broken source-level import).
+ */
+export declare const SDK_PACKAGE_VERSION: string;
+/** The bun release the sidecar runs on; `OMP_SDK_BUN_VERSION` overrides it. */
+export declare const SDK_BUN_VERSION: string;
+/** The bun release platform archive this adapter fetches (worlds run on linux-x64). */
+export declare const SDK_BUN_PLATFORM = "linux-x64";
+/** `@oh-my-pi/pi-natives` ships one binding package per platform tuple. */
+export type SdkNativesPlatform = "linux-x64" | "linux-arm64" | "darwin-x64" | "darwin-arm64" | "win32-x64" | "win32-arm64";
+/**
+ * Pure `process.platform`/`process.arch` → natives binding key.
+ * Throws for a tuple `@oh-my-pi/pi-natives` does not publish (fail loud rather
+ * than install a runtime whose addon cannot load).
+ */
+export declare function sdkNativesPlatform(platform?: string, arch?: string): SdkNativesPlatform;
+/** The exact natives binding package name for a platform key. */
+export declare function sdkNativesPackage(platform: SdkNativesPlatform): string;
+/**
+ * The install argv (pure, so the slim-install recipe is testable).
+ *
+ * `--omit=optional` drops the ~234 MB transformers/onnxruntime weight; the
+ * explicit natives package restores the one optional dependency the import
+ * actually needs. `keepOptional` (env `OMP_SDK_KEEP_OPTIONAL=1`) reinstates the
+ * full tree.
+ */
+export declare function sdkInstallArgv(packageVersion: string, platform: SdkNativesPlatform, keepOptional?: boolean): string[];
+/** The exact GitHub release asset URL of a bun version's linux-x64 build. */
+export declare function bunReleaseZipUrl(bunVersion: string): string;
+/** Layout of the durable SDK runtime inside a world home. */
+export interface SdkRuntimeLayout {
+    /** The runtime root (holds `bin/`, `node_modules/`, `sidecar/`, `dist/`). */
+    dir: string;
+    /** The fetched bun binary the sidecar is spawned with. */
+    bun: string;
+    /** Written LAST; presence + matching identity means the runtime is complete. */
+    marker: string;
+    /** Bootstrap lock directory (mkdir is atomic on POSIX). */
+    lock: string;
+    /** Failure trace — only ever written by a failed fetch. */
+    errorLog: string;
+    /** Destination directory of the copied sidecar. */
+    sidecarDir: string;
+    /** The sidecar entrypoint inside the runtime dir (bun resolves modules from here). */
+    sidecarEntry: string;
+    /** Destination directory of the copied compiled protocol module. */
+    protocolDir: string;
+}
+export declare function sdkRuntimeLayout(worldHome: string): SdkRuntimeLayout;
+/** Destination of the compiled protocol module copied beside the sidecar. */
+export declare function sdkRuntimeProtocolEntry(layout: SdkRuntimeLayout): string;
+/** The install marker: identity of the runtime plus where/when it landed. */
+export interface SdkRuntimeRecord {
+    /** Version of this adapter package at fetch time. */
+    pluginVersion: string;
+    /** Installed version of {@link SDK_PACKAGE}. */
+    packageVersion: string;
+    /** Installed bun version. */
+    bunVersion: string;
+    /** Absolute path of the fetched bun binary. */
+    bunPath: string;
+    /** ISO timestamp of the successful fetch. */
+    installedAt: string;
+}
+/** The part of a record a caller can know before fetching (used for the compare). */
+export interface SdkRuntimeIdentity {
+    pluginVersion: string;
+    packageVersion: string;
+    bunVersion: string;
+}
+/** Read the install marker; undefined when absent or unreadable. */
+export declare function readSdkRuntimeRecord(worldHome: string): SdkRuntimeRecord | undefined;
+/**
+ * Fast path: the runtime is complete AND matches `identity` → its record.
+ *
+ * Returns undefined when the marker is absent/corrupt, when any identity field
+ * differs (the adapter or a pin changed), or when the recorded bun binary is
+ * gone — in every such case the caller must (re)fetch.
+ */
+export declare function sdkRuntimeReady(worldHome: string, identity: SdkRuntimeIdentity): SdkRuntimeRecord | undefined;
+/** Options for a single {@link SdkRuntimeDeps.run} invocation. */
+export interface SdkRuntimeRunOptions {
+    /** Working directory for the command. */
+    cwd?: string;
+    /**
+     * Environment OVERRIDES merged on top of the inherited environment (so PATH
+     * and friends survive). Used to redirect bun's install cache and to keep the
+     * smoke import out of the operator's native `~/.omp`.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Everything {@link ensureSdkRuntime} touches outside its own filesystem work,
+ * injected so the bootstrap is testable with zero network and zero real bun.
+ */
+export interface SdkRuntimeDeps {
+    /** Fetch `url` to the file `dest` (real implementation shells out to curl). */
+    download(url: string, dest: string): Promise<void>;
+    /** Run a command to completion; must throw on a non-zero exit. */
+    run(cmd: string, args: string[], opts?: SdkRuntimeRunOptions): Promise<void>;
+    /** Copy a regular file (the sidecar source and the compiled protocol module). */
+    copy(from: string, to: string): void;
+    /** Version of this adapter package — part of the marker identity. */
+    pluginVersion: string;
+    /** Absolute path of this package's root (`sidecar/`, `dist/` sources live there). */
+    pluginDir: string;
+    /** One human-readable progress line. */
+    log(line: string): void;
+}
+/**
+ * The PRODUCTION {@link SdkRuntimeDeps}: everything the bootstrap touches
+ * outside its own filesystem work, wired to real OS primitives.
+ *
+ * Kept IN THE MODULE (not in `scripts/fetch-sdk-runtime.mjs`) so the manual
+ * pre-warm script and the first-prompt lazy fetch (sidecar `start()`) share ONE
+ * implementation: a second copy is exactly how the two paths would drift.
+ *
+ * `pluginDir` defaults to this package's root (the parent of the compiled
+ * `dist/`), from which the sidecar source and the compiled protocol module are
+ * copied into the runtime; the marker identity reads the package's own version.
+ *
+ * @param pluginDir - package root holding `sidecar/main.ts` + `dist/protocol.js`.
+ * @returns deps for {@link ensureSdkRuntime}.
+ */
+export declare function createSdkRuntimeDeps(pluginDir?: string): SdkRuntimeDeps;
+/** The version of the adapter package at `pluginDir` (the marker identity half). */
+export declare function readPluginVersion(pluginDir: string): string;
+/**
+ * Return the record for `<worldHome>`'s durable SDK runtime, fetching it first
+ * when it is absent, incomplete or does not match the running adapter.
+ *
+ * Idempotent: a complete, matching runtime short-circuits without touching the
+ * network. Concurrent callers: the bootstrap is guarded by a `mkdir` lock — a
+ * second caller that finds a FRESH lock throws a clear "fetch in progress"
+ * error (no waiting; the SDK transport is a per-process singleton, so the real
+ * race is another dsh process on the same world home), while an abandoned lock
+ * (older than {@link LOCK_STALE_MS}) is reclaimed so a crashed fetch cannot
+ * brick the line.
+ *
+ * Failures append to `<worldHome>/sdk-runtime.error.log` and throw a single
+ * actionable error — never a partial runtime behind a success marker.
+ */
+export declare function ensureSdkRuntime(worldHome: string, deps: SdkRuntimeDeps): Promise<SdkRuntimeRecord>;