@opencode/client 0.0.0-beta-19275

package/dist/promise/generated/types.js

@@ -0,0 +1,30 @@
+export const isInvalidRequestError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "InvalidRequestError";
+export const isUnauthorizedError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "UnauthorizedError";
+export const isAgentNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "AgentNotFoundError";
+export const isServiceUnavailableError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ServiceUnavailableError";
+export const isInvalidCursorError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "InvalidCursorError";
+export const isSessionNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "SessionNotFoundError";
+export const isConflictError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ConflictError";
+export const isUnknownError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "UnknownError";
+export const isMessageNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "MessageNotFoundError";
+export const isCommandNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "CommandNotFoundError";
+export const isCommandExecutionError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "CommandExecutionError";
+export const isSkillNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "SkillNotFoundError";
+export const isSessionBusyError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "SessionBusyError";
+export const isInstructionEntryValueTooLargeError = (value) => typeof value === "object" &&
+    value !== null &&
+    "_tag" in value &&
+    value["_tag"] === "InstructionEntryValueTooLargeError";
+export const isProviderNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ProviderNotFoundError";
+export const isMcpServerNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "McpServerNotFoundError";
+export const isProjectNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ProjectNotFoundError";
+export const isFormNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "FormNotFoundError";
+export const isFormInvalidAnswerError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "FormInvalidAnswerError";
+export const isFormAlreadySettledError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "FormAlreadySettledError";
+export const isPermissionNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "PermissionNotFoundError";
+export const isRpcError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "RpcError";
+export const isRpcInternalError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "RpcInternalError";
+export const isPtyNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "PtyNotFoundError";
+export const isForbiddenError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ForbiddenError";
+export const isShellNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ShellNotFoundError";
+export const isWorktreeError = (value) => typeof value === "object" && value !== null && "name" in value && value["name"] === "WorktreeError";

package/dist/promise/index.d.ts

@@ -0,0 +1,6 @@
+import type { OpenCode } from "./client.js";
+export * from "./generated/index.js";
+export { OpenCode } from "./client.js";
+export type { AgentApi, CatalogApi, CommandApi, ConfigApi, EventApi, IntegrationApi, ModelApi, PluginApi, ProviderApi, ReferenceApi, RpcApi, RpcCallOptions, RpcClient, RpcEventPayload, WebSearchApi, SessionApi, SkillApi, } from "./api.js";
+export type { EventSubscribeOutput as OpenCodeEvent } from "./generated/types.js";
+export type OpenCodeClient = ReturnType<typeof OpenCode.make>;

package/dist/promise/index.js

@@ -0,0 +1,2 @@
+export * from "./generated/index.js";
+export { OpenCode } from "./client.js";

package/dist/promise/rpc.d.ts

@@ -0,0 +1,32 @@
+import type { Rpc } from "@opencode/schema/rpc";
+import type { make, RequestOptions } from "./generated/client.js";
+import type { EventSubscribeOutput, LocationGetInput } from "./generated/types.js";
+type RpcEvent = Extract<EventSubscribeOutput, {
+    type: `rpc.${string}`;
+}>;
+export interface RpcCallOptions extends RequestOptions {
+    readonly location?: LocationGetInput["location"];
+}
+export type RpcArguments<Input, Options> = unknown extends Input ? [input: Input, options?: Options] : undefined extends Input ? [input?: Input, options?: Options] : [input: Input, options?: Options];
+export type RpcClient<D extends Rpc.PortableDefinition, Options = RpcCallOptions> = {
+    readonly [Name in keyof D["methods"]]: (...args: RpcArguments<Rpc.Input<D["methods"][Name]["input"]>, Options>) => Promise<Rpc.Output<D["methods"][Name]["output"]>>;
+} & {
+    readonly events: {
+        readonly subscribe: <Name extends keyof D["events"] & string>(name: Name, options?: Pick<RequestOptions, "signal">) => AsyncIterable<RpcEventPayload<D, Name>>;
+        readonly on: <Name extends keyof D["events"] & string>(name: Name, handler: (event: RpcEventPayload<D, Name>) => Promise<void> | void, options?: Pick<RequestOptions, "signal">) => () => void;
+    };
+};
+type RpcEventPayloadFor<D extends Rpc.PortableDefinition, Name extends keyof D["events"] & string> = Omit<RpcEvent, "type" | "data"> & {
+    type: `rpc.${D["id"]}.${Name}`;
+    data: Rpc.EventData<D["events"][Name]["schema"]>;
+};
+export type RpcEventPayload<D extends Rpc.PortableDefinition, Name extends keyof D["events"] & string = keyof D["events"] & string> = {
+    [K in Name]: RpcEventPayloadFor<D, K>;
+}[Name];
+export interface RpcApi<Options = RpcCallOptions> {
+    <D extends Rpc.PortableDefinition>(definition: D): RpcClient<D, Options>;
+}
+export declare function makeRpc(raw: ReturnType<typeof make>, events: {
+    subscribe(options?: Pick<RequestOptions, "signal">): AsyncIterable<EventSubscribeOutput>;
+}): RpcApi;
+export {};

package/dist/promise/rpc.js

@@ -0,0 +1,86 @@
+import { isRpcError, isRpcInternalError } from "./generated/types.js";
+export function makeRpc(raw, events) {
+    return (definition) => {
+        const subscribe = (name, options) => {
+            if (!Object.hasOwn(definition.events, name))
+                throw new Error(`Unknown RPC event: ${definition.id}.${name}`);
+            const type = eventType(definition, name);
+            return {
+                [Symbol.asyncIterator]() {
+                    const controller = new AbortController();
+                    const signal = options?.signal ? AbortSignal.any([controller.signal, options.signal]) : controller.signal;
+                    const iterator = (async function* () {
+                        try {
+                            for await (const published of events.subscribe({ signal })) {
+                                if (signal.aborted)
+                                    return;
+                                if (published.type !== type)
+                                    continue;
+                                // SAFETY: The exact RPC type was selected above; Promise contracts require no client-side transform.
+                                // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
+                                yield published;
+                            }
+                        }
+                        catch (error) {
+                            if (!signal.aborted)
+                                throw error;
+                        }
+                        finally {
+                            controller.abort();
+                        }
+                    })();
+                    return {
+                        next: () => iterator.next(),
+                        return: () => {
+                            // Interrupt a pending source read before closing the generator.
+                            controller.abort();
+                            return iterator.return();
+                        },
+                    };
+                },
+            };
+        };
+        // SAFETY: Every runtime key comes from this definition's method and event maps, which define RpcClient's mapped keys.
+        // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
+        return Object.assign(Object.fromEntries(Object.keys(definition.methods).map((name) => [
+            name,
+            async (input, options) => {
+                try {
+                    const result = await raw.rpc.call({
+                        rpcID: definition.id,
+                        method: name,
+                        // SAFETY: The method schema defines the accepted input; this assertion bridges it to the generic JSON transport.
+                        // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
+                        input: input,
+                        location: options?.location,
+                    }, { signal: options?.signal, headers: options?.headers });
+                    return result.output;
+                }
+                catch (error) {
+                    if (!isRpcError(error) && !isRpcInternalError(error))
+                        throw error;
+                    throw error.data === undefined
+                        ? { type: error.type, message: error.message }
+                        : { type: error.type, message: error.message, data: error.data };
+                }
+            },
+        ])), {
+            events: {
+                subscribe,
+                on: (name, handler, options) => {
+                    const controller = new AbortController();
+                    const signal = options?.signal ? AbortSignal.any([controller.signal, options.signal]) : controller.signal;
+                    const source = subscribe(name, { signal });
+                    void (async () => {
+                        for await (const event of source)
+                            await handler(event);
+                    })().catch((error) => console.error(error));
+                    return () => controller.abort();
+                },
+            },
+        });
+    };
+}
+function eventType(definition, name) {
+    return `rpc.${definition.id}.${name}`;
+}

package/dist/promise/service.d.ts

@@ -0,0 +1,26 @@
+import type { DiscoverOptions, Endpoint, EnsureOptions, StopOptions } from "../service.js";
+export * from "../service.js";
+/** Discover a healthy, compatible local service without starting one. */
+export declare function discover(options?: DiscoverOptions): Promise<{
+    url: string;
+    auth: {
+        type: "basic";
+        username: string;
+        password: string;
+    } | undefined;
+} | undefined>;
+/** Ensure a healthy, compatible local service is running. */
+export declare function ensure(options?: EnsureOptions): Promise<Endpoint>;
+/** Stop the registered local service. */
+export declare function stop(options?: StopOptions): Promise<void>;
+/** Create HTTP authentication headers for a service endpoint. */
+export declare function headers(endpoint: Endpoint): {
+    authorization: string;
+} | undefined;
+/** Promise-based local service lifecycle operations. */
+export declare const Service: {
+    discover: typeof discover;
+    ensure: typeof ensure;
+    stop: typeof stop;
+    headers: typeof headers;
+};

package/dist/promise/service.js

@@ -0,0 +1,247 @@
+import { readFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { contenderFailure, contenderFinished, spawnServiceContender, } from "../service-contender.js";
+import { defaultEnsureTiming, ensureTiming } from "../service-timing.js";
+import { matchesVersion } from "../service-version.js";
+import { PtyHandoff } from "../pty-handoff.js";
+export * from "../service.js";
+// Find, start, and stop the local opencode background service.
+//
+// The registration file is the complete discovery contract. This module is
+// intentionally implemented with Node APIs so Promise clients do not need
+// Effect or @effect/platform-node at runtime.
+/** Discover a healthy, compatible local service without starting one. */
+export async function discover(options = {}) {
+    const found = (await registered(options.file)).service;
+    if (found?.state !== "ready")
+        return undefined;
+    if (!matchesVersion(found.version, options))
+        return undefined;
+    return found.endpoint;
+}
+/** Ensure a healthy, compatible local service is running. */
+export async function ensure(options = {}) {
+    const timing = ensureTiming(options);
+    const deadline = Date.now() + timing.promiseTimeout;
+    const contenders = new Set();
+    let timeouts;
+    let announced = false;
+    let lastSpawn = 0;
+    let spawnDelay = timing.spawnDelay;
+    const announce = (reason, previousVersion) => {
+        if (announced)
+            return;
+        announced = true;
+        options.onStart?.(reason, previousVersion);
+    };
+    const spawnContender = async () => {
+        const [command, ...args] = options.command ?? ["opencode", "serve", "--service"];
+        if (command === undefined)
+            throw new Error("Missing service command");
+        try {
+            return spawnServiceContender(command, args, await PtyHandoff.environment(options.file ?? fallback(), options.env));
+        }
+        catch (cause) {
+            throw new Error("Failed to start server", { cause });
+        }
+    };
+    try {
+        while (true) {
+            if (Date.now() >= deadline)
+                throw new Error("Timed out waiting for the background service to start");
+            const registration = await registered(options.file, true, timing.requestTimeout);
+            if (registration.timedOut && registration.info !== undefined) {
+                timeouts = {
+                    info: registration.info,
+                    count: timeouts !== undefined && same(timeouts.info, registration.info) ? timeouts.count + 1 : 1,
+                };
+                if (timeouts.count >= 3) {
+                    announce("missing");
+                    console.warn("Background service is unresponsive; recovery cannot preserve persistent terminals");
+                    await PtyHandoff.clear(options.file ?? fallback());
+                    await terminate(registration.info, options, timing);
+                    timeouts = undefined;
+                    lastSpawn = Date.now() - spawnDelay;
+                }
+            }
+            else
+                timeouts = undefined;
+            if (registration.service !== undefined) {
+                spawnDelay = timing.spawnDelay;
+                const service = registration.service;
+                const compatible = !service.legacy && matchesVersion(service.version, options);
+                if (compatible && service.state === "ready") {
+                    await PtyHandoff.complete(options.file ?? fallback(), service.info);
+                    return service.endpoint;
+                }
+                if (compatible && service.state === "failed")
+                    throw new Error("Background service failed to start");
+                if (!compatible) {
+                    announce("version-mismatch", service.version);
+                    if (!service.legacy && service.state !== "ready")
+                        console.warn("Background service is not ready; replacement cannot preserve persistent terminals");
+                    await stop({
+                        file: options.file,
+                        pty: !service.legacy && service.state === "ready" ? "handoff" : "clear",
+                    }).catch(() => undefined);
+                    lastSpawn = 0;
+                }
+            }
+            else {
+                if (lastSpawn === 0 && registration.info !== undefined)
+                    lastSpawn = Date.now();
+                const finished = [...contenders].filter(contenderFinished);
+                const failure = finished.map(contenderFailure).find((error) => error !== undefined);
+                if (finished.some((item) => item.child.exitCode === 0)) {
+                    spawnDelay = Math.min(spawnDelay * 2, timing.maxSpawnDelay);
+                }
+                finished.forEach((item) => contenders.delete(item));
+                if (failure !== undefined && contenders.size === 0)
+                    throw failure;
+                // Keep one candidate plus one lock probe so a pre-lock stall cannot block recovery.
+                if (contenders.size < 2 && Date.now() - lastSpawn >= spawnDelay) {
+                    announce("missing");
+                    contenders.add(await spawnContender());
+                    lastSpawn = Date.now();
+                }
+            }
+            await delay(timing.pollInterval);
+        }
+    }
+    finally {
+        contenders.forEach((contender) => contender.release());
+    }
+}
+/** Stop the registered local service. */
+export async function stop(options = {}) {
+    const info = await read(options.file);
+    if (options.pty === "handoff" && info !== undefined)
+        await PtyHandoff.prepare(options.file ?? fallback(), info, defaultEnsureTiming.requestTimeout);
+    else
+        await PtyHandoff.clear(options.file ?? fallback());
+    if (info !== undefined)
+        await terminate(info, options, defaultEnsureTiming);
+}
+function fallback() {
+    return join(process.env["XDG_STATE_HOME"] ?? join(homedir(), ".local", "state"), "opencode", "service.json");
+}
+/** Create HTTP authentication headers for a service endpoint. */
+export function headers(endpoint) {
+    if (endpoint.auth === undefined)
+        return undefined;
+    return {
+        authorization: "Basic " + Buffer.from(endpoint.auth.username + ":" + endpoint.auth.password).toString("base64"),
+    };
+}
+async function read(file) {
+    const text = await readFile(file ?? fallback(), "utf8").catch(() => undefined);
+    if (text === undefined)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function probeResult(info, allowLegacy = false, timeout = defaultEnsureTiming.requestTimeout) {
+    const endpoint = {
+        url: info.url,
+        auth: info.password === undefined
+            ? undefined
+            : { type: "basic", username: "opencode", password: info.password },
+    };
+    const signal = AbortSignal.timeout(timeout);
+    const result = await fetch(new URL("/api/health", info.url), {
+        headers: headers(endpoint),
+        signal,
+    })
+        .then(async (response) => ({
+        response,
+        body: (await response.json()),
+    }))
+        .then((value) => ({ value }), (cause) => ({ cause }));
+    if ("cause" in result)
+        return { service: undefined, timedOut: signal.aborted };
+    const response = result.value.response;
+    const body = result.value.body;
+    if (body !== undefined && "version" in body && "pid" in body) {
+        if (body.pid !== info.pid)
+            return { service: undefined, timedOut: false };
+        if (info.version !== undefined && body.version !== info.version)
+            return { service: undefined, timedOut: false };
+        return {
+            service: {
+                info,
+                endpoint,
+                version: body.version,
+                state: response.ok ? "ready" : response.status === 500 ? "failed" : "waiting",
+                legacy: false,
+            },
+            timedOut: false,
+        };
+    }
+    if (!allowLegacy || body?.healthy !== true)
+        return { service: undefined, timedOut: false };
+    return {
+        service: { info, endpoint, state: "ready", legacy: true },
+        timedOut: false,
+    };
+}
+async function registered(file, allowLegacy = false, timeout) {
+    const info = await read(file);
+    if (info === undefined)
+        return { info: undefined, service: undefined, timedOut: false };
+    return { info, ...(await probeResult(info, allowLegacy, timeout)) };
+}
+function signal(pid, name) {
+    try {
+        process.kill(pid, name);
+    }
+    catch { }
+}
+function stopped(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+async function waitUntilStopped(pid, timing) {
+    for (let attempt = 0; attempt <= timing.stopPollAttempts; attempt++) {
+        if (stopped(pid))
+            return true;
+        if (attempt < timing.stopPollAttempts)
+            await delay(timing.stopPollInterval);
+    }
+    return false;
+}
+function same(left, right) {
+    return left.id === right.id && left.version === right.version && left.url === right.url && left.pid === right.pid;
+}
+async function terminate(info, options, timing) {
+    const current = await read(options.file);
+    if (current === undefined || !same(current, info))
+        return;
+    signal(info.pid, "SIGTERM");
+    if (!(await waitUntilStopped(info.pid, timing))) {
+        const latest = await read(options.file);
+        if (latest === undefined || !same(latest, info))
+            return;
+        signal(info.pid, "SIGKILL");
+        if (!(await waitUntilStopped(info.pid, timing)))
+            throw new Error(`Server process ${info.pid} is still running`);
+    }
+    const latest = await read(options.file);
+    if (latest === undefined || !same(latest, info))
+        return;
+    await rm(options.file ?? fallback(), { force: true });
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+/** Promise-based local service lifecycle operations. */
+export const Service = { discover, ensure, stop, headers };

package/dist/pty-handoff.d.ts

@@ -0,0 +1,9 @@
+export * as PtyHandoff from "./pty-handoff.js";
+import type { Info } from "./service.js";
+/** Publish the ticket before stopping its owner so every replacement contender can adopt it. */
+export declare function prepare(file: string, info: Info, timeout: number): Promise<void>;
+export declare function environment(file: string, env?: Readonly<Record<string, string>>): Promise<{
+    OPENCODE_PTY_HANDOFF: string | undefined;
+}>;
+export declare function complete(file: string, info: Info): Promise<void>;
+export declare function clear(file: string): Promise<void>;

package/dist/pty-handoff.js

@@ -0,0 +1,121 @@
+export * as PtyHandoff from "./pty-handoff.js";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+/** Publish the ticket before stopping its owner so every replacement contender can adopt it. */
+export async function prepare(file, info, timeout) {
+    const existing = await read(file);
+    if (existing !== undefined && existing.expiresAt > Date.now() && same(existing.source, info))
+        return;
+    const { ClientError, OpenCode } = await import("./promise/index.js");
+    const client = OpenCode.make({
+        baseUrl: info.url,
+        headers: info.password === undefined
+            ? undefined
+            : { authorization: "Basic " + Buffer.from(`opencode:${info.password}`).toString("base64") },
+    });
+    const missing = (error) => error instanceof ClientError &&
+        error.reason === "UnexpectedStatus" &&
+        typeof error.cause === "object" &&
+        error.cause !== null &&
+        "status" in error.cause &&
+        error.cause.status === 404;
+    const result = await client.experimental.persistentPty.handoff({ signal: AbortSignal.timeout(timeout) }).then((value) => ({ value }), (cause) => ({ cause }));
+    if ("cause" in result) {
+        // Another caller may already have prepared and stopped this server.
+        const concurrent = await read(file);
+        if (concurrent !== undefined && concurrent.expiresAt > Date.now() && same(concurrent.source, info))
+            return;
+        if (!missing(result.cause))
+            throw new Error("Failed to prepare persistent terminals for service replacement", { cause: result.cause });
+        console.warn("Background service cannot hand off persistent terminals; shutting them down before replacement");
+        await client.experimental.persistentPty
+            .shutdown({ signal: AbortSignal.timeout(timeout) })
+            .catch((cause) => {
+            if (missing(cause))
+                return;
+            throw new Error("Failed to shut down persistent terminals before service replacement", { cause });
+        });
+        await publish(file, info, null);
+        return;
+    }
+    const body = result.value;
+    if (typeof body !== "object" || body === null || !("handoff" in body))
+        throw new Error("Invalid persistent terminal handoff response");
+    if (body.handoff === null) {
+        await publish(file, info, null);
+        return;
+    }
+    if (!isHandoff(body.handoff) || body.handoff.expiresAt <= Date.now())
+        throw new Error("Invalid or expired persistent terminal handoff");
+    await publish(file, info, body.handoff);
+}
+async function publish(file, info, handoff) {
+    const temporary = `${file}.pty-handoff.${crypto.randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify({
+        source: { id: info.id, pid: info.pid, url: info.url },
+        handoff,
+        expiresAt: handoff?.expiresAt ?? Date.now() + 30_000,
+    }), { mode: 0o600, flag: "wx" });
+    await rename(temporary, file + ".pty-handoff").finally(() => rm(temporary, { force: true }));
+}
+export async function environment(file, env) {
+    const record = await read(file);
+    const current = await readFile(file, "utf8")
+        .then((text) => JSON.parse(text))
+        .catch(() => undefined);
+    const handoff = record !== undefined && record.expiresAt > Date.now() && (current === undefined || same(record.source, current))
+        ? record.handoff
+        : undefined;
+    return { ...env, OPENCODE_PTY_HANDOFF: handoff == null ? undefined : JSON.stringify(handoff) };
+}
+export async function complete(file, info) {
+    const record = await read(file);
+    if (record !== undefined && !same(record.source, info))
+        await clear(file);
+}
+export async function clear(file) {
+    await rm(file + ".pty-handoff", { force: true });
+}
+async function read(file) {
+    const value = await readFile(file + ".pty-handoff", "utf8")
+        .then((text) => JSON.parse(text))
+        .catch(() => undefined);
+    if (typeof value !== "object" || value === null || !("source" in value) || !("handoff" in value))
+        return;
+    if (typeof value.source !== "object" || value.source === null)
+        return;
+    if (!("pid" in value.source) || typeof value.source.pid !== "number")
+        return;
+    if (!("url" in value.source) || typeof value.source.url !== "string")
+        return;
+    if ("id" in value.source && typeof value.source.id !== "string")
+        return;
+    if (value.handoff !== null && !isHandoff(value.handoff))
+        return;
+    if (!("expiresAt" in value) || typeof value.expiresAt !== "number" || !Number.isFinite(value.expiresAt))
+        return;
+    return {
+        source: {
+            id: "id" in value.source && typeof value.source.id === "string" ? value.source.id : undefined,
+            pid: value.source.pid,
+            url: value.source.url,
+        },
+        handoff: value.handoff,
+        expiresAt: value.expiresAt,
+    };
+}
+function same(left, right) {
+    return left.id === right.id && left.pid === right.pid && left.url === right.url;
+}
+function isHandoff(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "directory" in value &&
+        typeof value.directory === "string" &&
+        "instanceID" in value &&
+        typeof value.instanceID === "string" &&
+        "ticket" in value &&
+        typeof value.ticket === "string" &&
+        "expiresAt" in value &&
+        typeof value.expiresAt === "number" &&
+        Number.isFinite(value.expiresAt));
+}

package/dist/rpc-runtime.d.ts

@@ -0,0 +1,21 @@
+export * as RpcRuntime from "./rpc-runtime.js";
+import type { Rpc } from "@opencode/schema/rpc";
+import { Effect, Schema } from "effect";
+export declare function read(schema: Rpc.Method["output"], value: unknown): Effect.Effect<unknown, Schema.SchemaError, never>;
+export declare function readError(method: Rpc.Method, error: unknown): Effect.Effect<never, unknown>;
+export declare const event: <D extends Rpc.Definition, Name extends keyof D["events"] & string>(definition: D, name: Name, schema: Rpc.EventDefinition, event: {
+    readonly id: string & import("effect/Brand").Brand<"Event.ID">;
+    readonly location: {
+        readonly directory: string & import("effect/Brand").Brand<"AbsolutePath">;
+        readonly workspaceID?: (string & import("effect/Brand").Brand<"Workspace.ID">) | undefined;
+    };
+    readonly data: {
+        readonly [x: string]: unknown;
+    };
+    readonly type: `rpc.${string}`;
+    readonly created: number;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+}) => Effect.Effect<Rpc.EventPayload<D, Name>, unknown, never>;
+export declare function eventType<const D extends Rpc.Definition, const Name extends keyof D["events"] & string>(definition: D, name: Name): `rpc.${D["id"]}.${Name}`;

package/dist/rpc-runtime.js

@@ -0,0 +1,32 @@
+export * as RpcRuntime from "./rpc-runtime.js";
+import { RpcError, RpcInternalError } from "@opencode/protocol/errors";
+import { Effect, Schema } from "effect";
+export function read(schema, value) {
+    // Standard Schema results have already been parsed by the server.
+    return Schema.isSchema(schema) ? Schema.decodeUnknownEffect(schema)(value) : Effect.succeed(value);
+}
+export function readError(method, error) {
+    if (!(error instanceof RpcError) && !(error instanceof RpcInternalError))
+        return Effect.fail(error);
+    if (!method.errors || !Object.hasOwn(method.errors, error.type)) {
+        return Effect.fail(error.data === undefined
+            ? { type: error.type, message: error.message }
+            : { type: error.type, message: error.message, data: error.data });
+    }
+    return read(method.errors[error.type], error.data).pipe(Effect.catch((cause) => Effect.die(cause)), Effect.flatMap((data) => Effect.fail(data === undefined
+        ? { type: error.type, message: error.message }
+        : { type: error.type, message: error.message, data })));
+}
+export const event = Effect.fn("Client.Rpc.event")(function* (definition, name, schema, event) {
+    const data = yield* read(schema.schema, event.data);
+    // SAFETY: The event type was selected by the caller and data was decoded with this event's schema.
+    // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
+    return {
+        ...event,
+        type: eventType(definition, name),
+        data,
+    };
+});
+export function eventType(definition, name) {
+    return `rpc.${definition.id}.${name}`;
+}

package/dist/service-contender.d.ts

@@ -0,0 +1,11 @@
+import { type ChildProcess } from "node:child_process";
+export type ServiceContender = {
+    readonly child: ChildProcess;
+    readonly error: () => Error | undefined;
+    readonly closed: () => boolean;
+    readonly stderr: () => string;
+    readonly release: () => void;
+};
+export declare function spawnServiceContender(command: string, args: ReadonlyArray<string>, env?: Readonly<Record<string, string | undefined>>): ServiceContender;
+export declare function contenderFailure(contender: ServiceContender): Error | undefined;
+export declare function contenderFinished(contender: ServiceContender): boolean;