@opencode/client 0.0.0-reserved → 2.0.1

package/dist/effect/index.d.ts

@@ -0,0 +1,35 @@
+import type { Effect } from "effect";
+import type { OpenCode } from "./client.js";
+export * from "./generated/index";
+export { OpenCode } from "./client.js";
+export type { AgentApi, AppApi, CatalogApi, CommandApi, ConfigApi, EventApi, IntegrationApi, ModelApi, PluginApi, ProviderApi, ReferenceApi, RpcApi, RpcClient, WebSearchApi, SessionApi, SkillApi, } from "./api.js";
+export { Agent } from "@opencode/schema/agent";
+export { Command } from "@opencode/schema/command";
+export { Config } from "@opencode/schema/config";
+export { Credential } from "@opencode/schema/credential";
+export { Event } from "@opencode/schema/event";
+export { EventLog } from "@opencode/schema/event-log";
+export { FileSystem } from "@opencode/schema/filesystem";
+export { Form } from "@opencode/schema/form";
+export { Integration } from "@opencode/schema/integration";
+export { Location } from "@opencode/schema/location";
+export { Model } from "@opencode/schema/model";
+export { Permission } from "@opencode/schema/permission";
+export { PermissionSaved } from "@opencode/schema/permission-saved";
+export { Project } from "@opencode/schema/project";
+export { Worktree } from "@opencode/schema/worktree";
+export { Vcs } from "@opencode/schema/vcs";
+export { Provider } from "@opencode/schema/provider";
+export { Pty } from "@opencode/schema/pty";
+export { Question } from "@opencode/schema/question";
+export { Reference } from "@opencode/schema/reference";
+export { WebSearch } from "@opencode/schema/websearch";
+export { AbsolutePath, RelativePath } from "@opencode/schema/schema";
+export { Session } from "@opencode/schema/session";
+export { SessionInbox } from "@opencode/schema/session-inbox";
+export { SessionMessage } from "@opencode/schema/session-message";
+export { Skill } from "@opencode/schema/skill";
+export { Prompt } from "@opencode/schema/prompt";
+export { PromptInput } from "@opencode/schema/prompt-input";
+export type { OpenCodeEvent } from "@opencode/protocol/groups/event";
+export type OpenCodeClient = Effect.Success<ReturnType<typeof OpenCode.make>>;

package/dist/effect/index.js

@@ -0,0 +1,30 @@
+export * from "./generated/index";
+export { OpenCode } from "./client.js";
+export { Agent } from "@opencode/schema/agent";
+export { Command } from "@opencode/schema/command";
+export { Config } from "@opencode/schema/config";
+export { Credential } from "@opencode/schema/credential";
+export { Event } from "@opencode/schema/event";
+export { EventLog } from "@opencode/schema/event-log";
+export { FileSystem } from "@opencode/schema/filesystem";
+export { Form } from "@opencode/schema/form";
+export { Integration } from "@opencode/schema/integration";
+export { Location } from "@opencode/schema/location";
+export { Model } from "@opencode/schema/model";
+export { Permission } from "@opencode/schema/permission";
+export { PermissionSaved } from "@opencode/schema/permission-saved";
+export { Project } from "@opencode/schema/project";
+export { Worktree } from "@opencode/schema/worktree";
+export { Vcs } from "@opencode/schema/vcs";
+export { Provider } from "@opencode/schema/provider";
+export { Pty } from "@opencode/schema/pty";
+export { Question } from "@opencode/schema/question";
+export { Reference } from "@opencode/schema/reference";
+export { WebSearch } from "@opencode/schema/websearch";
+export { AbsolutePath, RelativePath } from "@opencode/schema/schema";
+export { Session } from "@opencode/schema/session";
+export { SessionInbox } from "@opencode/schema/session-inbox";
+export { SessionMessage } from "@opencode/schema/session-message";
+export { Skill } from "@opencode/schema/skill";
+export { Prompt } from "@opencode/schema/prompt";
+export { PromptInput } from "@opencode/schema/prompt-input";

package/dist/effect/rpc.d.ts

@@ -0,0 +1,20 @@
+export * as RpcClientRuntime from "./rpc.js";
+import type { Rpc } from "@opencode/schema/rpc";
+import type { RpcError, RpcInternalError } from "@opencode/protocol/errors";
+import type { OpenCodeEvent } from "@opencode/protocol/groups/event";
+import { Effect, Schema, Stream } from "effect";
+import type { RpcArguments, RpcCallOptions } from "../promise/rpc.js";
+import type { RpcCallInput, RpcCallOutput } from "./api/api.js";
+type DecodeError<S> = S extends Schema.Top ? Schema.SchemaError : never;
+export type RpcClient<D extends Rpc.Definition, E = never, Options = RpcCallOptions, EventError = E> = {
+    readonly [Name in keyof D["methods"]]: (...args: RpcArguments<Rpc.Input<D["methods"][Name]["input"]>, Options>) => Effect.Effect<Rpc.Output<D["methods"][Name]["output"]>, Rpc.MethodError<D["methods"][Name]> | DecodeError<D["methods"][Name]["output"]> | E>;
+} & {
+    readonly events: {
+        readonly subscribe: <Name extends keyof D["events"] & string>(name: Name) => Stream.Stream<Rpc.EventPayload<D, Name>, DecodeError<D["events"][Name]["schema"]> | EventError>;
+    };
+};
+export interface RpcApi<E = never, Options = RpcCallOptions, EventError = E> {
+    <D extends Rpc.Definition>(definition: D): RpcClient<D, E, Options, EventError>;
+}
+export declare function make<CallError, EventError>(call: (input: RpcCallInput, options?: RpcCallOptions) => Effect.Effect<RpcCallOutput, CallError>, subscribe: () => Stream.Stream<OpenCodeEvent, EventError>): RpcApi<Exclude<CallError, RpcError | RpcInternalError> | Rpc.SystemError, RpcCallOptions, EventError>;
+export declare function aborted(signal: AbortSignal): Effect.Effect<void, never, never>;

package/dist/effect/rpc.js

@@ -0,0 +1,49 @@
+export * as RpcClientRuntime from "./rpc.js";
+import { Effect, Schema, Stream } from "effect";
+import { RpcRuntime } from "../rpc-runtime.js";
+export function make(call, subscribe) {
+    return (definition) => {
+        const methods = Object.fromEntries(Object.entries(definition.methods).map(([name, method]) => [
+            name,
+            (input, options) => {
+                const result = Effect.gen(function* () {
+                    const response = yield* call({
+                        rpcID: definition.id,
+                        method: name,
+                        input,
+                        location: options?.location,
+                    }, options);
+                    return yield* RpcRuntime.read(method.output, response.output);
+                }).pipe(Effect.catch((error) => RpcRuntime.readError(method, error)));
+                const signal = options?.signal;
+                if (!signal)
+                    return result;
+                return Effect.suspend(() => signal.aborted
+                    ? Effect.interrupt
+                    : Effect.raceFirst(result, Effect.andThen(aborted(signal), Effect.interrupt)));
+            },
+        ]));
+        // SAFETY: Every runtime key comes from this definition, and each value is decoded through its corresponding schema.
+        // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
+        return Object.assign(methods, {
+            events: {
+                subscribe: (name) => {
+                    const type = RpcRuntime.eventType(definition, name);
+                    if (!Object.hasOwn(definition.events, name))
+                        return Stream.fail(new Error(`Unknown RPC event: ${type}`));
+                    const schema = definition.events[name];
+                    return subscribe().pipe(Stream.filter((event) => event.type === type), Stream.mapEffect((event) => RpcRuntime.event(definition, name, schema, event)));
+                },
+            },
+        });
+    };
+}
+export function aborted(signal) {
+    return Effect.callback((resume) => {
+        if (signal.aborted)
+            return resume(Effect.void);
+        const abort = () => resume(Effect.void);
+        signal.addEventListener("abort", abort, { once: true });
+        return Effect.sync(() => signal.removeEventListener("abort", abort));
+    });
+}

package/dist/effect/service.d.ts

@@ -0,0 +1,78 @@
+import { Effect, FileSystem, Schema } from "effect";
+import type { DiscoverOptions, Endpoint, EnsureOptions, StopOptions } from "../service.js";
+export * from "../service.js";
+/** Contents of the local service registration file. */
+export type Info = import("../service.js").Info;
+/** Discover a healthy, compatible local service without starting one. */
+export declare const discover: (options?: DiscoverOptions | undefined) => Effect.Effect<{
+    url: string;
+    auth: {
+        type: "basic";
+        username: string;
+        password: string;
+    } | undefined;
+} | undefined, never, FileSystem.FileSystem>;
+/** Recognize an authenticated compatible service bound to an expected URL, including while it starts or fails. */
+export declare const incumbent: (options: DiscoverOptions & {
+    readonly url: string;
+}) => Effect.Effect<{
+    endpoint: {
+        url: string;
+        auth: {
+            type: "basic";
+            username: string;
+            password: string;
+        } | undefined;
+    };
+    state: "failed" | "ready" | "waiting";
+} | undefined, never, FileSystem.FileSystem>;
+/** Ensure a healthy, compatible local service is running. */
+export declare const ensure: (options?: EnsureOptions | undefined) => Effect.Effect<Endpoint, Error, FileSystem.FileSystem>;
+/** Stop the registered local service. */
+export declare const stop: (options?: StopOptions | undefined) => Effect.Effect<void, Error, FileSystem.FileSystem>;
+/** Create HTTP authentication headers for a service endpoint. */
+export declare function headers(endpoint: Endpoint): {
+    authorization: string;
+} | undefined;
+/** Schema for the local service registration file. */
+export declare const Info: Schema.Struct<{
+    readonly id: Schema.optional<Schema.String>;
+    readonly version: Schema.optional<Schema.String>;
+    readonly url: Schema.String;
+    readonly pid: Schema.Int;
+    readonly password: Schema.optional<Schema.String>;
+}>;
+/** Effect-based local service lifecycle operations. */
+export declare const Service: {
+    discover: (options?: DiscoverOptions | undefined) => Effect.Effect<{
+        url: string;
+        auth: {
+            type: "basic";
+            username: string;
+            password: string;
+        } | undefined;
+    } | undefined, never, FileSystem.FileSystem>;
+    incumbent: (options: DiscoverOptions & {
+        readonly url: string;
+    }) => Effect.Effect<{
+        endpoint: {
+            url: string;
+            auth: {
+                type: "basic";
+                username: string;
+                password: string;
+            } | undefined;
+        };
+        state: "failed" | "ready" | "waiting";
+    } | undefined, never, FileSystem.FileSystem>;
+    ensure: (options?: EnsureOptions | undefined) => Effect.Effect<Endpoint, Error, FileSystem.FileSystem>;
+    stop: (options?: StopOptions | undefined) => Effect.Effect<void, Error, FileSystem.FileSystem>;
+    headers: typeof headers;
+    Info: Schema.Struct<{
+        readonly id: Schema.optional<Schema.String>;
+        readonly version: Schema.optional<Schema.String>;
+        readonly url: Schema.String;
+        readonly pid: Schema.Int;
+        readonly password: Schema.optional<Schema.String>;
+    }>;
+};

package/dist/effect/service.js

@@ -0,0 +1,259 @@
+import { ServiceStatus } from "@opencode/protocol/groups/health";
+import { Effect, FileSystem, Option, Schedule, Schema } from "effect";
+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 service daemon advertises itself through a registration file in the
+// user's state directory: url, pid, version, and the private password, with
+// 0600 permissions. That file is the complete discovery contract — reading it
+// is all a client needs to connect. The daemon's own configuration (port,
+// persisted password) is CLI-owned and never read here.
+// Read-only lookup: registration file plus health check and version gate.
+// Never spawns; escalation to ensure() is the caller's policy.
+/** Discover a healthy, compatible local service without starting one. */
+export const discover = Effect.fn("service.discover")(function* (options = {}) {
+    const found = (yield* registered(options.file)).service;
+    if (found?.state !== "ready")
+        return undefined;
+    if (!matchesVersion(found.version, options))
+        return undefined;
+    return found.endpoint;
+});
+/** Recognize an authenticated compatible service bound to an expected URL, including while it starts or fails. */
+export const incumbent = Effect.fn("service.incumbent")(function* (options) {
+    const info = yield* read(options.file);
+    const found = info === undefined ? undefined : yield* probe({ ...info, url: options.url });
+    if (found === undefined || found.legacy)
+        return undefined;
+    if (!matchesVersion(found.version, options))
+        return undefined;
+    return { endpoint: found.endpoint, state: found.state };
+});
+// Idempotent ensure-running: reuses a healthy compatible server, replaces a
+// version-mismatched one, and otherwise spawns small contenders until a server
+// becomes discoverable. A contender is never killed merely for slow startup.
+/** Ensure a healthy, compatible local service is running. */
+export const ensure = Effect.fn("service.ensure")(function* (options = {}) {
+    const timing = ensureTiming(options);
+    const contenders = new Set();
+    let timeouts;
+    let announced = false;
+    let lastSpawn = 0;
+    let spawnDelay = timing.spawnDelay;
+    const announce = (reason, previousVersion) => Effect.sync(() => {
+        if (announced)
+            return;
+        announced = true;
+        options.onStart?.(reason, previousVersion);
+    });
+    const spawnContender = Effect.gen(function* () {
+        const [command, ...args] = options.command ?? ["opencode", "serve", "--service"];
+        if (command === undefined)
+            return yield* Effect.fail(new Error("Missing service command"));
+        const env = yield* Effect.tryPromise(() => PtyHandoff.environment(options.file ?? fallback(), options.env));
+        return yield* Effect.try({
+            try: () => {
+                return spawnServiceContender(command, args, env);
+            },
+            catch: (cause) => new Error("Failed to start server", { cause }),
+        });
+    });
+    const found = yield* Effect.gen(function* () {
+        const registration = yield* registered(options.file, true, timing.requestTimeout);
+        const info = registration.info;
+        const service = registration.service;
+        if (registration.timedOut && info !== undefined) {
+            timeouts = {
+                info,
+                count: timeouts !== undefined && same(timeouts.info, info) ? timeouts.count + 1 : 1,
+            };
+            if (timeouts.count >= 3) {
+                yield* announce("missing");
+                yield* Effect.logWarning("Background service is unresponsive; recovery cannot preserve persistent terminals");
+                yield* Effect.tryPromise(() => PtyHandoff.clear(options.file ?? fallback()));
+                yield* terminate(info, options, timing);
+                timeouts = undefined;
+                lastSpawn = Date.now() - spawnDelay;
+            }
+        }
+        else
+            timeouts = undefined;
+        if (service !== undefined) {
+            spawnDelay = timing.spawnDelay;
+            const compatible = !service.legacy && matchesVersion(service.version, options);
+            if (compatible && service.state === "ready") {
+                yield* Effect.tryPromise(() => PtyHandoff.complete(options.file ?? fallback(), service.info));
+                return Option.some(service);
+            }
+            if (compatible && service.state === "failed")
+                return yield* Effect.fail(new Error("Background service failed to start"));
+            if (compatible)
+                return Option.none();
+            yield* announce("version-mismatch", service.version);
+            if (!service.legacy && service.state !== "ready")
+                yield* Effect.logWarning("Background service is not ready; replacement cannot preserve persistent terminals");
+            yield* stop({
+                file: options.file,
+                pty: !service.legacy && service.state === "ready" ? "handoff" : "clear",
+            }).pipe(Effect.ignore);
+            lastSpawn = 0;
+            return Option.none();
+        }
+        else if (lastSpawn === 0 && 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)
+            return yield* Effect.fail(failure);
+        // Keep one candidate plus one lock probe so a pre-lock stall cannot block recovery.
+        if (contenders.size < 2 && Date.now() - lastSpawn >= spawnDelay) {
+            yield* announce("missing");
+            contenders.add(yield* spawnContender);
+            lastSpawn = Date.now();
+        }
+        return Option.none();
+    }).pipe(Effect.repeat({
+        until: Option.isSome,
+        schedule: Schedule.max([Schedule.spaced(timing.pollInterval), Schedule.recurs(timing.attempts)]),
+    }), Effect.ensuring(Effect.sync(() => contenders.forEach((contender) => contender.release()))));
+    if (Option.isNone(found))
+        return yield* Effect.fail(new Error("Timed out waiting for the background service to start"));
+    return found.value.endpoint;
+});
+/** Stop the registered local service. */
+export const stop = Effect.fn("service.stop")(function* (options = {}) {
+    const info = yield* read(options.file);
+    if (options.pty === "handoff" && info !== undefined)
+        yield* Effect.tryPromise(() => PtyHandoff.prepare(options.file ?? fallback(), info, defaultEnsureTiming.requestTimeout));
+    else
+        yield* Effect.tryPromise(() => PtyHandoff.clear(options.file ?? fallback()));
+    if (info !== undefined)
+        yield* terminate(info, options, defaultEnsureTiming);
+});
+function fallback() {
+    const state = process.env["XDG_STATE_HOME"] ?? join(homedir(), ".local", "state");
+    return join(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 " + btoa(endpoint.auth.username + ":" + endpoint.auth.password) };
+}
+/** Schema for the local service registration file. */
+export const Info = Schema.Struct({
+    id: Schema.optional(Schema.String),
+    version: Schema.optional(Schema.String),
+    url: Schema.String,
+    pid: Schema.Int.check(Schema.isGreaterThan(0)),
+    password: Schema.optional(Schema.String),
+});
+const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(Info));
+const decodeHealth = Schema.decodeUnknownOption(ServiceStatus.Health);
+const decodeLegacyHealth = Schema.decodeUnknownOption(Schema.Struct({ healthy: Schema.Literal(true) }));
+// A missing or corrupt file means no valid info; callers treat both
+// the same (the registering server self-evicts, clients rediscover).
+const read = Effect.fnUntraced(function* (file) {
+    const fs = yield* FileSystem.FileSystem;
+    const text = yield* fs.readFileString(file ?? fallback()).pipe(Effect.option);
+    if (Option.isNone(text))
+        return undefined;
+    return yield* decode(text.value).pipe(Effect.option, Effect.map(Option.getOrUndefined));
+});
+const probe = Effect.fnUntraced(function* (info, allowLegacy = false) {
+    return (yield* probeResult(info, allowLegacy)).service;
+});
+const probeResult = Effect.fnUntraced(function* (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 = yield* Effect.promise(() => 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;
+    const health = decodeHealth(body);
+    if (Option.isSome(health)) {
+        if (health.value.pid !== info.pid)
+            return { service: undefined, timedOut: false };
+        if (info.version !== undefined && health.value.version !== info.version)
+            return { service: undefined, timedOut: false };
+        return {
+            service: {
+                info,
+                endpoint,
+                version: health.value.version,
+                state: response.ok ? "ready" : response.status === 500 ? "failed" : "waiting",
+                legacy: false,
+            },
+            timedOut: false,
+        };
+    }
+    if (!allowLegacy ||
+        Option.isNone(decodeLegacyHealth(body)) ||
+        (typeof body === "object" && body !== null && ("version" in body || "pid" in body)))
+        return { service: undefined, timedOut: false };
+    return {
+        service: { info, endpoint, state: "ready", legacy: true },
+        timedOut: false,
+    };
+});
+const registered = Effect.fnUntraced(function* (file, allowLegacy = false, timeout) {
+    const info = yield* read(file);
+    if (info === undefined)
+        return { info: undefined, service: undefined, timedOut: false };
+    return { info, ...(yield* probeResult(info, allowLegacy, timeout)) };
+});
+// 50ms cadence bounded at ~5s, shared by stop escalation and each ensure
+// discovery window.
+const poll = (timing) => Schedule.max([Schedule.spaced(timing.stopPollInterval), Schedule.recurs(timing.stopPollAttempts)]);
+const signal = (pid, name) => Effect.try({ try: () => process.kill(pid, name), catch: (cause) => cause }).pipe(Effect.ignore);
+const stopped = Effect.fnUntraced(function* (pid) {
+    const running = yield* Effect.try({ try: () => process.kill(pid, 0), catch: () => false }).pipe(Effect.orElseSucceed(() => false));
+    if (!running)
+        return true;
+    return yield* Effect.fail(new Error(`Server process ${pid} is still running`));
+});
+function same(left, right) {
+    return left.id === right.id && left.version === right.version && left.url === right.url && left.pid === right.pid;
+}
+const terminate = Effect.fnUntraced(function* (info, options, timing) {
+    const current = yield* read(options.file);
+    if (current === undefined || !same(current, info))
+        return;
+    yield* signal(info.pid, "SIGTERM");
+    const done = yield* stopped(info.pid).pipe(Effect.retry(poll(timing)), Effect.option);
+    if (Option.isNone(done)) {
+        const latest = yield* read(options.file);
+        if (latest === undefined || !same(latest, info))
+            return;
+        yield* signal(info.pid, "SIGKILL");
+        yield* stopped(info.pid).pipe(Effect.retry(poll(timing)));
+    }
+    const latest = yield* read(options.file);
+    if (latest === undefined || !same(latest, info))
+        return;
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.remove(options.file ?? fallback()).pipe(Effect.ignore);
+});
+/** Effect-based local service lifecycle operations. */
+export const Service = { discover, incumbent, ensure, stop, headers, Info };

package/dist/promise/api.d.ts

@@ -0,0 +1,24 @@
+import type { OpenCode } from "./client.js";
+type Client = ReturnType<typeof OpenCode.make>;
+export type { RpcApi, RpcCallOptions, RpcClient, RpcEventPayload } from "./rpc.js";
+export type AgentApi = Client["agent"];
+export type CommandApi = Client["command"];
+export type ConfigApi = Client["config"];
+export type EventApi = Client["event"];
+export type GenerateApi = Client["generate"];
+export type IntegrationApi = Client["integration"];
+export type McpApi = Client["mcp"];
+export type ModelApi = Client["model"];
+export type PluginApi = Client["plugin"];
+export type PermissionApi = Client["permission"];
+export type ProviderApi = Client["provider"];
+export type ReferenceApi = Client["reference"];
+export type WebSearchApi = Client["websearch"];
+export type SessionApi = Client["session"];
+export type SkillApi = Client["skill"];
+export type VcsApi = Client["vcs"];
+export type WorktreeApi = Client["worktree"];
+export interface CatalogApi {
+    readonly provider: ProviderApi;
+    readonly model: ModelApi;
+}