@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/backends/opencode-event-mapper.d.ts

@@ -0,0 +1,132 @@
+/**
+ * docs/design/appendices/opencode-backend.md §5.3 / §6.3 — defensive normaliser over the
+ * SDK's `EventSubscribeResponse` union. The generated SDK union is
+ * **incomplete** (V9): the server emits event types (`server.heartbeat`,
+ * `permission.asked`) that are not declared, while it never emits some
+ * types the SDK does declare (`message.part.updated`, `permission.replied`,
+ * `session.compacted`, …). Phase 2 therefore widens the input type to a
+ * plain `{ type: string; properties?: unknown }` and dispatches on the
+ * string literal, with a `kind: "unknown"` fallthrough that lets the
+ * dispatcher keep running while new event types accumulate.
+ *
+ * Tool-call / tool-result extraction is intentionally **not** done from
+ * this stream — V9 confirmed `message.part.updated` is never emitted in
+ * opencode 1.14.50, so tool data must be pulled from the final
+ * `session.prompt` response `info.parts` array. See
+ * `extractToolUsesFromParts` and `extractAssistantTextFromParts`.
+ */
+import type { RawOpencodeEvent } from "./opencode-types.js";
+/**
+ * Shape mirrors the runtime payload of an `APIError`-name session.error.
+ * Loose typing — keep optional, since fixtures show field availability
+ * varies across providers / failure modes.
+ */
+export interface OpencodeSessionErrorPayload {
+    /** `MessageAbortedError`, `APIError`, `ProviderAuthError`, `UnknownError`,
+     *  `MessageOutputLengthError`, or anything else opencode invents next. */
+    name: string;
+    data: {
+        message?: string;
+        statusCode?: number;
+        isRetryable?: boolean;
+        providerID?: string;
+        responseHeaders?: Record<string, string>;
+        responseBody?: string;
+        [key: string]: unknown;
+    };
+}
+export interface OpencodePermissionRequestEvent {
+    toolName: string;
+    permissionId: string;
+    sessionId: string;
+    /** Bash-glob patterns the user is asked to allow once. */
+    patterns: string[];
+    /** Bash-glob patterns the user is asked to "always" allow. */
+    alwaysPatterns: string[];
+    tool: {
+        messageID: string;
+        callID: string;
+    };
+}
+export type OpencodeNormalizedEvent = {
+    kind: "server_connected";
+} | {
+    kind: "heartbeat";
+} | {
+    kind: "session_status";
+    sessionId: string;
+    status: string;
+} | {
+    kind: "session_diff";
+    sessionId: string;
+} | {
+    kind: "session_idle";
+    sessionId: string;
+} | {
+    kind: "session_error";
+    sessionId: string;
+    error: OpencodeSessionErrorPayload;
+} | {
+    kind: "text_delta";
+    sessionId: string;
+    messageId: string;
+    partId: string;
+    field: string;
+    delta: string;
+} | ({
+    kind: "permission_request";
+} & OpencodePermissionRequestEvent) | {
+    kind: "unknown";
+    type: string;
+    raw: unknown;
+};
+/**
+ * Normalise a raw opencode event into the dispatch-friendly shape. Never
+ * throws — unknown types fall through to `{ kind: "unknown" }` so the
+ * caller can decide whether to log/alert/skip.
+ */
+export declare function normalize(event: RawOpencodeEvent): OpencodeNormalizedEvent;
+/**
+ * `session.idle` marks the end of a single prompt turn. `session.error`
+ * is also terminal — the dispatcher must stop awaiting deltas. Other
+ * statuses (`busy`, etc.) are non-terminal liveness signals.
+ *
+ * Abort detection: there is **no** `session.aborted` event. The abort
+ * path emits `session.error` with `error.name === "MessageAbortedError"`
+ * followed by `session.idle` (V9 — `events/v9-abort.json`). Both are
+ * terminal here; callers may further inspect `error.name` after the
+ * fact.
+ */
+export declare function isTerminal(event: OpencodeNormalizedEvent): boolean;
+/**
+ * Aborted-via-API detection. The SDK does NOT surface this via a
+ * dedicated event type; the daemon must read it off the assistant
+ * message's `info.error.name` field from the final `session.prompt`
+ * response (or from a streamed `session.error`).
+ */
+export declare function isMessageAborted(event: OpencodeNormalizedEvent | undefined | null): boolean;
+/**
+ * Pull final assistant text from a `session.prompt` response's `parts`
+ * array. opencode 1.14.50 splits the assistant message across multiple
+ * typed parts; only `type: "text"` carries the user-visible response.
+ * `reasoning` / `step-start` / `step-finish` / `tool` / `agent` /
+ * `compaction` parts are ignored here.
+ */
+export declare function extractAssistantTextFromParts(parts: unknown): string;
+export interface ExtractedToolUse {
+    callId: string;
+    toolName: string;
+    status: "pending" | "running" | "completed" | "error";
+    input: Record<string, unknown>;
+    output?: string;
+    errorMessage?: string;
+    durationMs?: number;
+}
+/**
+ * Extract tool calls + results from a `session.prompt` response's
+ * `parts` array. V9 confirmed that `message.part.updated` events are
+ * NOT emitted in opencode 1.14.50; the final response carries the only
+ * authoritative tool-call record. Pure function; safe to call on raw
+ * unknown input.
+ */
+export declare function extractToolUsesFromParts(parts: unknown): ExtractedToolUse[];

package/dist/core/backends/opencode-event-mapper.js

@@ -0,0 +1,197 @@
+/**
+ * docs/design/appendices/opencode-backend.md §5.3 / §6.3 — defensive normaliser over the
+ * SDK's `EventSubscribeResponse` union. The generated SDK union is
+ * **incomplete** (V9): the server emits event types (`server.heartbeat`,
+ * `permission.asked`) that are not declared, while it never emits some
+ * types the SDK does declare (`message.part.updated`, `permission.replied`,
+ * `session.compacted`, …). Phase 2 therefore widens the input type to a
+ * plain `{ type: string; properties?: unknown }` and dispatches on the
+ * string literal, with a `kind: "unknown"` fallthrough that lets the
+ * dispatcher keep running while new event types accumulate.
+ *
+ * Tool-call / tool-result extraction is intentionally **not** done from
+ * this stream — V9 confirmed `message.part.updated` is never emitted in
+ * opencode 1.14.50, so tool data must be pulled from the final
+ * `session.prompt` response `info.parts` array. See
+ * `extractToolUsesFromParts` and `extractAssistantTextFromParts`.
+ */
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+/**
+ * Normalise a raw opencode event into the dispatch-friendly shape. Never
+ * throws — unknown types fall through to `{ kind: "unknown" }` so the
+ * caller can decide whether to log/alert/skip.
+ */
+export function normalize(event) {
+    const props = asRecord(event.properties) ?? {};
+    switch (event.type) {
+        case "server.connected":
+            return { kind: "server_connected" };
+        case "server.heartbeat":
+            return { kind: "heartbeat" };
+        case "session.status": {
+            const status = asRecord(props.status);
+            return {
+                kind: "session_status",
+                sessionId: asString(props.sessionID) ?? "",
+                status: asString(status?.type) ?? "",
+            };
+        }
+        case "session.diff":
+            return {
+                kind: "session_diff",
+                sessionId: asString(props.sessionID) ?? "",
+            };
+        case "session.idle":
+            return {
+                kind: "session_idle",
+                sessionId: asString(props.sessionID) ?? "",
+            };
+        case "session.error": {
+            const error = asRecord(props.error);
+            const data = asRecord(error?.data) ?? {};
+            const errorName = asString(error?.name) ?? "UnknownError";
+            const sessionErr = {
+                name: errorName,
+                data: data,
+            };
+            return {
+                kind: "session_error",
+                sessionId: asString(props.sessionID) ?? "",
+                error: sessionErr,
+            };
+        }
+        case "message.part.delta": {
+            return {
+                kind: "text_delta",
+                sessionId: asString(props.sessionID) ?? "",
+                messageId: asString(props.messageID) ?? "",
+                partId: asString(props.partID) ?? "",
+                field: asString(props.field) ?? "text",
+                delta: asString(props.delta) ?? "",
+            };
+        }
+        case "permission.asked": {
+            const tool = asRecord(props.tool) ?? {};
+            return {
+                kind: "permission_request",
+                toolName: asString(props.permission) ?? "",
+                permissionId: asString(props.id) ?? "",
+                sessionId: asString(props.sessionID) ?? "",
+                patterns: asStringArray(props.patterns),
+                alwaysPatterns: asStringArray(props.always),
+                tool: {
+                    messageID: asString(tool.messageID) ?? "",
+                    callID: asString(tool.callID) ?? "",
+                },
+            };
+        }
+        default:
+            return { kind: "unknown", type: event.type, raw: event };
+    }
+}
+/**
+ * `session.idle` marks the end of a single prompt turn. `session.error`
+ * is also terminal — the dispatcher must stop awaiting deltas. Other
+ * statuses (`busy`, etc.) are non-terminal liveness signals.
+ *
+ * Abort detection: there is **no** `session.aborted` event. The abort
+ * path emits `session.error` with `error.name === "MessageAbortedError"`
+ * followed by `session.idle` (V9 — `events/v9-abort.json`). Both are
+ * terminal here; callers may further inspect `error.name` after the
+ * fact.
+ */
+export function isTerminal(event) {
+    return event.kind === "session_idle" || event.kind === "session_error";
+}
+/**
+ * Aborted-via-API detection. The SDK does NOT surface this via a
+ * dedicated event type; the daemon must read it off the assistant
+ * message's `info.error.name` field from the final `session.prompt`
+ * response (or from a streamed `session.error`).
+ */
+export function isMessageAborted(event) {
+    return (!!event && event.kind === "session_error" && event.error.name === "MessageAbortedError");
+}
+/**
+ * Pull final assistant text from a `session.prompt` response's `parts`
+ * array. opencode 1.14.50 splits the assistant message across multiple
+ * typed parts; only `type: "text"` carries the user-visible response.
+ * `reasoning` / `step-start` / `step-finish` / `tool` / `agent` /
+ * `compaction` parts are ignored here.
+ */
+export function extractAssistantTextFromParts(parts) {
+    if (!Array.isArray(parts))
+        return "";
+    const chunks = [];
+    for (const part of parts) {
+        const rec = asRecord(part);
+        if (!rec)
+            continue;
+        if (rec.type === "text" && typeof rec.text === "string") {
+            chunks.push(rec.text);
+        }
+    }
+    return chunks.join("");
+}
+/**
+ * Extract tool calls + results from a `session.prompt` response's
+ * `parts` array. V9 confirmed that `message.part.updated` events are
+ * NOT emitted in opencode 1.14.50; the final response carries the only
+ * authoritative tool-call record. Pure function; safe to call on raw
+ * unknown input.
+ */
+export function extractToolUsesFromParts(parts) {
+    if (!Array.isArray(parts))
+        return [];
+    const tools = [];
+    for (const part of parts) {
+        const rec = asRecord(part);
+        if (!rec || rec.type !== "tool")
+            continue;
+        const state = asRecord(rec.state);
+        if (!state)
+            continue;
+        const status = asString(state.status);
+        if (status !== "pending"
+            && status !== "running"
+            && status !== "completed"
+            && status !== "error") {
+            continue;
+        }
+        const time = asRecord(state.time);
+        const startVal = time?.start;
+        const endVal = time?.end;
+        const durationMs = typeof startVal === "number" && typeof endVal === "number"
+            ? Math.max(0, endVal - startVal)
+            : undefined;
+        const tool = {
+            callId: asString(rec.callID) ?? "",
+            toolName: asString(rec.tool) ?? "",
+            status,
+            input: asRecord(state.input) ?? {},
+        };
+        if (status === "completed") {
+            tool.output = asString(state.output);
+        }
+        if (status === "error") {
+            tool.errorMessage = asString(state.error);
+        }
+        if (durationMs !== undefined)
+            tool.durationMs = durationMs;
+        tools.push(tool);
+    }
+    return tools;
+}

package/dist/core/backends/opencode-mcp.d.ts

@@ -0,0 +1,81 @@
+/**
+ * docs/design/appendices/opencode-backend.md §5.1 / §5.6 / §6.x — render the daemon's
+ * `McpServer` rows into `OpencodeRuntimeConfig.mcp`.
+ *
+ * Unlike Claude / Codex / Gemini which read on-disk MCP config files
+ * (`.mcp.json`, `.codex/config.toml`, `.gemini/settings.json`),
+ * OpenCode receives MCP config inline via `OPENCODE_CONFIG_CONTENT`
+ * consumed at server-spawn time (§5.1). The daemon therefore produces
+ * the `Record<string, McpLocalConfig | McpRemoteConfig>` map directly
+ * instead of writing a file under the session workdir.
+ *
+ * Pure function — DB / blob-store access happens upstream in
+ * `materializeMcpForSession`'s sibling caller. The renderer takes the
+ * already-filtered server list + resolved secrets and produces:
+ *   - `mcp`: the runtime-config map.
+ *   - `env`: env vars the spawned `opencode serve` process must export
+ *     so the `environment` placeholders resolve at MCP-spawn time.
+ *     OpenCode does NOT do `${VAR}` expansion on stdio env values
+ *     (V7 fixture), so we inline concrete values into `environment` —
+ *     `env` stays empty for stdio servers. For remote servers, header
+ *     values are inlined directly into the `headers` map.
+ *   - `warnings`: server-name lint failures (`_`-containing ids) and
+ *     unsupported-transport notices. Surfaced via dashboard.
+ *
+ * Server-name lint (§5.6): the documented mangling rule
+ *   `mcp__<server>__<tool>` → `<server>_<tool>`
+ * is ambiguous when `<server>` contains `_`. Until the SDK exposes
+ * MCP tool ids (V7 deferred), we reject `_`-containing server names at
+ * config-build time so the daemon never produces a config whose
+ * server→tool boundary cannot be reconstructed.
+ */
+import type { OpencodeMcpServerConfig } from "@aitne/shared";
+import type { McpServer } from "../../services/mcp/types.js";
+/**
+ * Inputs to the renderer. `secrets` is keyed by `<serverId>:<keyName>`
+ * (the same shape `materializeMcpForSession` already produces for the
+ * other backends).
+ */
+export interface OpencodeMcpRenderInput {
+    /** MCP servers, already filtered to enabled + targeting opencode. */
+    servers: readonly McpServer[];
+    /** Resolved secrets, keyed `<serverId>:<keyName>`. */
+    secrets: Record<string, string>;
+    /**
+     * Default tools-listing timeout to apply when the server row carries
+     * none. Omit to let opencode's 5000 ms default apply.
+     */
+    defaultTimeoutMs?: number;
+}
+export interface OpencodeMcpRenderResult {
+    /** Ready to drop into `OpencodeRuntimeConfig.mcp`. */
+    mcp: Record<string, OpencodeMcpServerConfig>;
+    /**
+     * Env vars the daemon must export when spawning `opencode serve` (or
+     * when probing remote server headers that mention `${MCP_…}`). Empty
+     * for inline-only configurations.
+     */
+    env: Record<string, string>;
+    /**
+     * Server-name lint failures + transport rejections. Surface via the
+     * dashboard so operators can rename / fix the upstream `mcp_servers`
+     * row before the next session bounces.
+     */
+    warnings: string[];
+}
+/**
+ * V5/§5.6 server-name lint. Returns null when the id is acceptable,
+ * otherwise a human-readable reason that explains why the server was
+ * dropped. Mirrors Codex's stricter `lowercase + dash only` rule
+ * extended with the opencode-specific `_` prohibition.
+ */
+export declare function isAcceptableOpencodeServerName(id: string): boolean;
+/**
+ * Main entry point. Pure — no I/O, deterministic given the same input.
+ *
+ * Servers whose name fails the lint OR whose required transport field
+ * is missing (stdio without command, http/sse without url) are dropped
+ * with a warning. The daemon then proceeds without that server — same
+ * fail-soft posture as the Claude / Codex / Gemini generators.
+ */
+export declare function renderOpencodeMcp(input: OpencodeMcpRenderInput): OpencodeMcpRenderResult;

package/dist/core/backends/opencode-mcp.js

@@ -0,0 +1,157 @@
+/**
+ * docs/design/appendices/opencode-backend.md §5.1 / §5.6 / §6.x — render the daemon's
+ * `McpServer` rows into `OpencodeRuntimeConfig.mcp`.
+ *
+ * Unlike Claude / Codex / Gemini which read on-disk MCP config files
+ * (`.mcp.json`, `.codex/config.toml`, `.gemini/settings.json`),
+ * OpenCode receives MCP config inline via `OPENCODE_CONFIG_CONTENT`
+ * consumed at server-spawn time (§5.1). The daemon therefore produces
+ * the `Record<string, McpLocalConfig | McpRemoteConfig>` map directly
+ * instead of writing a file under the session workdir.
+ *
+ * Pure function — DB / blob-store access happens upstream in
+ * `materializeMcpForSession`'s sibling caller. The renderer takes the
+ * already-filtered server list + resolved secrets and produces:
+ *   - `mcp`: the runtime-config map.
+ *   - `env`: env vars the spawned `opencode serve` process must export
+ *     so the `environment` placeholders resolve at MCP-spawn time.
+ *     OpenCode does NOT do `${VAR}` expansion on stdio env values
+ *     (V7 fixture), so we inline concrete values into `environment` —
+ *     `env` stays empty for stdio servers. For remote servers, header
+ *     values are inlined directly into the `headers` map.
+ *   - `warnings`: server-name lint failures (`_`-containing ids) and
+ *     unsupported-transport notices. Surfaced via dashboard.
+ *
+ * Server-name lint (§5.6): the documented mangling rule
+ *   `mcp__<server>__<tool>` → `<server>_<tool>`
+ * is ambiguous when `<server>` contains `_`. Until the SDK exposes
+ * MCP tool ids (V7 deferred), we reject `_`-containing server names at
+ * config-build time so the daemon never produces a config whose
+ * server→tool boundary cannot be reconstructed.
+ */
+import { createLogger } from "../../logging.js";
+const logger = createLogger("opencode-mcp");
+/**
+ * V5/§5.6 server-name lint. Returns null when the id is acceptable,
+ * otherwise a human-readable reason that explains why the server was
+ * dropped. Mirrors Codex's stricter `lowercase + dash only` rule
+ * extended with the opencode-specific `_` prohibition.
+ */
+export function isAcceptableOpencodeServerName(id) {
+    return /^[a-z0-9][a-z0-9-]*$/.test(id);
+}
+function joinCommand(server) {
+    const cmd = server.command?.trim();
+    if (!cmd)
+        return [];
+    const argv = server.args ? server.args.filter((a) => typeof a === "string") : [];
+    return [cmd, ...argv];
+}
+/**
+ * Render the stdio-transport variant: opencode treats every entry in
+ * `command` as one argv element (it does not run through a shell). We
+ * pass `environment` inline because opencode's stdio launcher does NOT
+ * expand `${VAR}` references at runtime (V7).
+ */
+function renderLocal(server, secrets, defaultTimeoutMs) {
+    const command = joinCommand(server);
+    if (command.length === 0)
+        return null;
+    const environment = {};
+    for (const key of server.envKeys) {
+        const raw = secrets[`${server.id}:${key}`];
+        if (raw !== undefined)
+            environment[key] = raw;
+    }
+    const local = {
+        type: "local",
+        command,
+        enabled: true,
+    };
+    if (Object.keys(environment).length > 0)
+        local.environment = environment;
+    if (typeof defaultTimeoutMs === "number" && defaultTimeoutMs > 0) {
+        local.timeout = defaultTimeoutMs;
+    }
+    return local;
+}
+/**
+ * Render http / sse transport. The SDK's `McpRemoteConfig` does not
+ * distinguish — both flow through the same shape; opencode's remote
+ * dispatcher negotiates transport. Header values are inlined.
+ */
+function renderRemote(server, secrets, defaultTimeoutMs) {
+    if (!server.url)
+        return null;
+    const headers = {};
+    for (const key of server.headerKeys) {
+        const raw = secrets[`${server.id}:${key}`];
+        if (raw !== undefined)
+            headers[key] = raw;
+    }
+    const remote = {
+        type: "remote",
+        url: server.url,
+        enabled: true,
+    };
+    if (Object.keys(headers).length > 0)
+        remote.headers = headers;
+    if (typeof defaultTimeoutMs === "number" && defaultTimeoutMs > 0) {
+        remote.timeout = defaultTimeoutMs;
+    }
+    return remote;
+}
+/**
+ * Main entry point. Pure — no I/O, deterministic given the same input.
+ *
+ * Servers whose name fails the lint OR whose required transport field
+ * is missing (stdio without command, http/sse without url) are dropped
+ * with a warning. The daemon then proceeds without that server — same
+ * fail-soft posture as the Claude / Codex / Gemini generators.
+ */
+export function renderOpencodeMcp(input) {
+    const mcp = {};
+    const warnings = [];
+    for (const server of input.servers) {
+        if (!server.enabled)
+            continue;
+        if (!isAcceptableOpencodeServerName(server.id)) {
+            warnings.push(`opencode-mcp: server '${server.id}' rejected — opencode-mangled tool ids (mcp__<server>__<tool> → <server>_<tool>) become ambiguous when the server id contains '_'. Rename to lowercase kebab-case.`);
+            continue;
+        }
+        if (server.transport === "stdio") {
+            const local = renderLocal(server, input.secrets, input.defaultTimeoutMs);
+            if (!local) {
+                warnings.push(`opencode-mcp: stdio server '${server.id}' has no 'command'; skipped`);
+                continue;
+            }
+            mcp[server.id] = local;
+            continue;
+        }
+        // `McpTransport` is the closed set { stdio, http, sse } (see
+        // services/mcp/types.ts). After the stdio branch above, only http
+        // and sse remain — both go through `renderRemote`. Extending
+        // `McpTransport` without updating this branch is caught by the
+        // probe / dashboard layers, which won't ever ask opencode to
+        // materialize an unknown transport.
+        const remote = renderRemote(server, input.secrets, input.defaultTimeoutMs);
+        if (!remote) {
+            warnings.push(`opencode-mcp: ${server.transport} server '${server.id}' has no 'url'; skipped`);
+            continue;
+        }
+        mcp[server.id] = remote;
+    }
+    if (Object.keys(mcp).length > 0) {
+        logger.debug({ serverIds: Object.keys(mcp), warningCount: warnings.length }, "rendered opencode mcp map");
+    }
+    return {
+        mcp,
+        // OpenCode's `environment` map already carries inlined values for
+        // stdio servers, and `headers` for remote servers, so no separate
+        // env vector needs to flow into the spawn env. Reserved here so a
+        // future opencode version that supports `${VAR}` expansion can fill
+        // this in without a signature change.
+        env: {},
+        warnings,
+    };
+}

package/dist/core/backends/opencode-server-manager.d.ts

@@ -0,0 +1,113 @@
+/**
+ * docs/design/appendices/opencode-backend.md §5.1 / §6.4 — server lifecycle manager.
+ *
+ * Phase 2 ships only the Managed implementation: one long-lived
+ * `opencode serve` child process per backend slot, with config-diff
+ * triggered bounce. The Remote implementation lands in Phase 5; Phase 2
+ * exposes the interface so wiring is stable.
+ *
+ * Concurrency model: a single `BackendRouter` slot is serialised by the
+ * router's per-backend in-flight gate. Within that gate `ensureConfig`
+ * may block on a bounce, then `client()` returns the live SDK client.
+ * `shutdown()` is wired into `ObserverManager` so graceful daemon exit
+ * stops the child process and releases the loopback port.
+ */
+import { createOpencode, type OpencodeClient } from "@opencode-ai/sdk";
+import type { OpencodeRuntimeConfig } from "@aitne/shared";
+export type OpencodeServerMode = "managed" | "remote";
+/**
+ * docs/design/appendices/opencode-backend.md §5.9 / Phase 4 — handle to a short-lived
+ * isolated server spawned for one tight-permission task. Caller is
+ * responsible for `close()`-ing it in a `finally` so the loopback port
+ * is released even when the inner work throws.
+ */
+export interface EphemeralOpencodeServerHandle {
+    client: OpencodeClient;
+    close: () => Promise<void>;
+}
+export interface OpencodeServerManager {
+    readonly mode: OpencodeServerMode;
+    /**
+     * Ensure the underlying server is running with `desiredConfig`.
+     * Managed: bounces when the canonical-hash of the desired config
+     * differs from the running server's hash. Idempotent on same input.
+     * Remote: no-op in Phase 5+.
+     */
+    ensureConfig(desiredConfig: OpencodeRuntimeConfig): Promise<void>;
+    /** Resolve the live SDK client. Lazily spawns the server on first call. */
+    client(): Promise<OpencodeClient>;
+    /**
+     * docs/design/appendices/opencode-backend.md §5.9 Path A — spawn an isolated ephemeral
+     * server for a single tight-permission task. Used by
+     * `runDelegatedTask` when the operator opts into `isolation: "ephemeral"`
+     * (rare path: operator-supplied MCP context the primary server's
+     * connections cannot be trusted with). Returns an
+     * {@link EphemeralOpencodeServerHandle} the caller MUST close in
+     * `finally` to release the loopback port.
+     *
+     * Managed: spawns a fresh `createOpencode()` independent of the
+     * long-lived primary server's state. Remote: throws — Path A is
+     * unavailable on a server the daemon does not own.
+     */
+    spawnEphemeral(config: OpencodeRuntimeConfig): Promise<EphemeralOpencodeServerHandle>;
+    /** Stop the server child process and release resources. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Hash a desired `OpencodeRuntimeConfig` deterministically so two
+ * equivalent configs (regardless of key ordering or undefined fields)
+ * produce the same hash. Reused for bounce-vs-noop decision.
+ */
+export declare function hashRuntimeConfig(config: OpencodeRuntimeConfig): string;
+export interface ManagedOpencodeServerManagerOptions {
+    /** Loopback host. Default `127.0.0.1`. */
+    hostname?: string;
+    /** Port. `0` ⇒ OS chooses. Default `0`. */
+    port?: number;
+    /** Cold-start timeout per spawn (ms). Default 15 000. */
+    spawnTimeoutMs?: number;
+    /**
+     * Inject the SDK's `createOpencode` for tests. Production code wires
+     * this to the real export. The wrapper signature matches the real
+     * SDK so the production path is type-safe.
+     */
+    createOpencodeImpl?: typeof createOpencode;
+}
+/**
+ * Managed-mode lifecycle. Owns a single child process; bounces on
+ * config-diff.
+ *
+ * Crash recovery: V6 fixtures show `server.close()` is synchronous and
+ * does not throw on a stopped process. The manager treats a missing /
+ * already-stopped server as "respawn on next ensureConfig". We don't
+ * subscribe to `child_process` signals here because the SDK abstracts
+ * them away; the next inbound `ensureConfig` will pay the cost of
+ * detection if the server died.
+ */
+export declare class ManagedOpencodeServerManager implements OpencodeServerManager {
+    readonly mode: "managed";
+    private state;
+    /** Coalesce concurrent ensureConfig / client calls onto a single spawn. */
+    private inflight;
+    private readonly hostname;
+    private readonly port;
+    private readonly spawnTimeoutMs;
+    private readonly createOpencodeImpl;
+    private shutdownRequested;
+    constructor(options?: ManagedOpencodeServerManagerOptions);
+    ensureConfig(desiredConfig: OpencodeRuntimeConfig): Promise<void>;
+    client(): Promise<OpencodeClient>;
+    spawnEphemeral(config: OpencodeRuntimeConfig): Promise<EphemeralOpencodeServerHandle>;
+    shutdown(): Promise<void>;
+    /** Lifecycle introspection — useful for diagnostics and tests. */
+    get isRunning(): boolean;
+    get currentHash(): string | null;
+    private spawn;
+    private doSpawn;
+}
+/**
+ * Phase 2 factory: only the Managed variant exists today. Phase 5 adds
+ * a `RemoteOpencodeServerManager` branch keyed on a runtime setting.
+ * The factory contract keeps callers backend-shape-agnostic.
+ */
+export declare function createOpencodeServerManager(options?: ManagedOpencodeServerManagerOptions): OpencodeServerManager;