@opencode-ai/client 0.0.0-dev-17471

package/dist/promise/generated/types.js

@@ -0,0 +1,26 @@
+export const isUnauthorizedError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "UnauthorizedError";
+export const isInvalidRequestError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "InvalidRequestError";
+export const isAgentNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "AgentNotFoundError";
+export const isInvalidCursorError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "InvalidCursorError";
+export const isConflictError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ConflictError";
+export const isSessionNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "SessionNotFoundError";
+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 isCommandEvaluationError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "CommandEvaluationError";
+export const isSkillNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "SkillNotFoundError";
+export const isServiceUnavailableError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ServiceUnavailableError";
+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 isFormNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "FormNotFoundError";
+export const isFormAlreadySettledError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "FormAlreadySettledError";
+export const isFormInvalidAnswerError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "FormInvalidAnswerError";
+export const isPermissionNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "PermissionNotFoundError";
+export const isPtyNotFoundError = (value) => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "PtyNotFoundError";
+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,4 @@
+export * from "./generated/index.js";
+export type { AgentApi, CatalogApi, CommandApi, ConfigApi, EventApi, IntegrationApi, ModelApi, PluginApi, ProviderApi, ReferenceApi, WebSearchApi, SessionApi, SkillApi, } from "./api.js";
+export type { EventSubscribeOutput as OpenCodeEvent } from "./generated/types.js";
+export type OpenCodeClient = ReturnType<typeof import("./generated/client.js").make>;

package/dist/promise/index.js

@@ -0,0 +1 @@
+export * from "./generated/index.js";

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,273 @@
+import { readFile } 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";
+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 = {}) {
+    return (await discoverLocal(options))?.endpoint;
+}
+async function discoverLocal(options) {
+    const found = (await registered(options.file)).service;
+    if (found?.state !== "ready")
+        return undefined;
+    if (!matchesVersion(found.version, options))
+        return undefined;
+    return found;
+}
+/** 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 = () => {
+        const [command, ...args] = options.command ?? ["opencode", "serve", "--service"];
+        if (command === undefined)
+            throw new Error("Missing service command");
+        try {
+            return spawnServiceContender(command, args);
+        }
+        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");
+                    await evict(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")
+                    return service.endpoint;
+                if (compatible && service.state === "failed")
+                    throw new Error("Background service failed to start");
+                if (!compatible) {
+                    announce("version-mismatch", service.version);
+                    await kill(service, options, timing).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(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 existing = await find(options);
+    if (existing !== undefined)
+        await kill(existing, 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 probe(info, allowLegacy = false) {
+    return (await probeResult(info, allowLegacy)).service;
+}
+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)) };
+}
+async function find(options) {
+    return (await registered(options.file, true)).service;
+}
+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 evict(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))
+        return;
+    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`);
+}
+async function kill(service, options, timing) {
+    const requested = await requestStop(service, timing.requestTimeout);
+    if (requested === "rejected")
+        return;
+    if (requested === "unsupported") {
+        const current = await find(options);
+        if (current === undefined || !same(current.info, service.info))
+            return;
+        signal(service.info.pid, "SIGTERM");
+    }
+    if (await waitUntilStopped(service.info.pid, timing))
+        return;
+    const latest = await find(options);
+    if (latest === undefined || !same(latest.info, service.info))
+        return;
+    signal(service.info.pid, "SIGKILL");
+    if (!(await waitUntilStopped(service.info.pid, timing)))
+        throw new Error(`Server process ${service.info.pid} is still running`);
+}
+async function requestStop(service, timeout = defaultEnsureTiming.requestTimeout) {
+    if (service.info.id === undefined || service.legacy)
+        return "unsupported";
+    const response = await fetch(new URL("/api/service/stop", service.info.url), {
+        method: "POST",
+        headers: { ...headers(service.endpoint), "content-type": "application/json" },
+        body: JSON.stringify({ instanceID: service.info.id }),
+        signal: AbortSignal.timeout(timeout),
+    }).catch(() => undefined);
+    if (response === undefined || response.status === 404 || response.status === 405)
+        return "unsupported";
+    const body = (await response.json().catch(() => undefined));
+    if (!response.ok || body?.accepted !== true)
+        return "rejected";
+    return "accepted";
+}
+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/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>): ServiceContender;
+export declare function contenderFailure(contender: ServiceContender): Error | undefined;
+export declare function contenderFinished(contender: ServiceContender): boolean;

package/dist/service-contender.js

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+const stderrLimit = 8 * 1024;
+export function spawnServiceContender(command, args) {
+    const child = spawn(command, args, { detached: true, stdio: ["ignore", "ignore", "pipe"] });
+    let error;
+    let closed = false;
+    let stderr = Buffer.alloc(0);
+    const onStderr = (chunk) => {
+        const tail = chunk.subarray(-stderrLimit);
+        stderr =
+            tail.length === stderrLimit
+                ? Buffer.from(tail)
+                : Buffer.concat([stderr.subarray(-(stderrLimit - tail.length)), tail]);
+    };
+    child.stderr?.on("data", onStderr);
+    if (child.stderr !== null && "unref" in child.stderr && typeof child.stderr.unref === "function")
+        child.stderr.unref();
+    child.once("error", (cause) => {
+        error = new Error("Failed to start server", { cause });
+    });
+    child.once("close", () => {
+        closed = true;
+    });
+    child.unref();
+    return {
+        child,
+        error: () => error,
+        closed: () => closed,
+        stderr: () => stderr.toString("utf8").trim(),
+        release: () => {
+            child.stderr?.off("data", onStderr);
+            child.stderr?.resume();
+            stderr = Buffer.alloc(0);
+        },
+    };
+}
+export function contenderFailure(contender) {
+    const error = contender.error();
+    if (error !== undefined)
+        return error;
+    if (contender.child.exitCode !== null && contender.child.exitCode !== 0)
+        return startupError(`Server process exited with code ${contender.child.exitCode}`, contender.stderr());
+    if (contender.child.signalCode !== null)
+        return startupError(`Server process terminated by ${contender.child.signalCode}`, contender.stderr());
+    return undefined;
+}
+export function contenderFinished(contender) {
+    return contender.error() !== undefined || contender.closed();
+}
+function startupError(message, stderr) {
+    return new Error(stderr ? `${message}\n${stderr}` : message);
+}

package/dist/service-timing.d.ts

@@ -0,0 +1,13 @@
+export type EnsureTiming = {
+    readonly pollInterval: number;
+    readonly attempts: number;
+    readonly requestTimeout: number;
+    readonly spawnDelay: number;
+    readonly maxSpawnDelay: number;
+    readonly promiseTimeout: number;
+    readonly stopPollInterval: number;
+    readonly stopPollAttempts: number;
+};
+export declare const defaultEnsureTiming: EnsureTiming;
+export declare function ensureTiming(options: object): EnsureTiming;
+export declare function withEnsureTiming<A extends object>(options: A, overrides: Partial<EnsureTiming>): A;

package/dist/service-timing.js

@@ -0,0 +1,19 @@
+const timings = new WeakMap();
+export const defaultEnsureTiming = {
+    pollInterval: 1_000,
+    attempts: 120,
+    requestTimeout: 2_000,
+    spawnDelay: 5_000,
+    maxSpawnDelay: 30_000,
+    promiseTimeout: 120_000,
+    stopPollInterval: 50,
+    stopPollAttempts: 100,
+};
+export function ensureTiming(options) {
+    return timings.get(options) ?? defaultEnsureTiming;
+}
+// Keep test timing out of the public lifecycle option types.
+export function withEnsureTiming(options, overrides) {
+    timings.set(options, { ...defaultEnsureTiming, ...overrides });
+    return options;
+}

package/dist/service-version.d.ts

@@ -0,0 +1,2 @@
+import type { DiscoverOptions } from "./service.js";
+export declare function matchesVersion(version: string | undefined, options: DiscoverOptions): boolean;

package/dist/service-version.js

@@ -0,0 +1,9 @@
+export function matchesVersion(version, options) {
+    if (options.version === undefined)
+        return true;
+    if (version === undefined)
+        return false;
+    if (typeof options.version === "function")
+        return options.version(version);
+    return version === options.version;
+}

package/dist/service.d.ts

@@ -0,0 +1,48 @@
+/** Connection details for a local OpenCode service. */
+export type Endpoint = {
+    /** Base URL of the service. */
+    readonly url: string;
+    /** Authentication required by the service, when configured. */
+    readonly auth?: {
+        /** HTTP authentication scheme. */
+        readonly type: "basic";
+        /** Basic authentication username. */
+        readonly username: string;
+        /** Basic authentication password. */
+        readonly password: string;
+    };
+};
+/** Options used to discover the local OpenCode service. */
+export type DiscoverOptions = {
+    /** Absolute registration file path. Defaults to the XDG state directory. */
+    readonly file?: string;
+    /** Required exact service version or compatibility predicate. */
+    readonly version?: string | ((version: string) => boolean);
+};
+/** Reason ensuring the service requires a new process. */
+export type EnsureReason = "missing" | "version-mismatch";
+/** Options used to ensure the local OpenCode service is running. */
+export type EnsureOptions = DiscoverOptions & {
+    /** Service command and arguments. Defaults to `opencode serve --service`. */
+    readonly command?: ReadonlyArray<string>;
+    /** Called once before spawning a new service process. */
+    readonly onStart?: (reason: EnsureReason, previousVersion?: string) => void;
+};
+/** Options used to stop the local OpenCode service. */
+export type StopOptions = {
+    /** Absolute registration file path. Defaults to the XDG state directory. */
+    readonly file?: string;
+};
+/** Contents of the local service registration file. */
+export type Info = {
+    /** Unique service instance identifier. */
+    readonly id?: string;
+    /** OpenCode version served by the process. */
+    readonly version?: string;
+    /** Base URL advertised by the service. */
+    readonly url: string;
+    /** Operating system process identifier. */
+    readonly pid: number;
+    /** Private service password, when authentication is enabled. */
+    readonly password?: string;
+};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@opencode-ai/client",
+  "version": "0.0.0-dev-17471",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anomalyco/opencode.git",
+    "directory": "packages/client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/promise/index.js",
+      "types": "./dist/promise/index.d.ts"
+    },
+    "./promise": {
+      "import": "./dist/promise/index.js",
+      "types": "./dist/promise/index.d.ts"
+    },
+    "./promise/api": {
+      "import": "./dist/promise/api.js",
+      "types": "./dist/promise/api.d.ts"
+    },
+    "./service": {
+      "import": "./dist/promise/service.js",
+      "types": "./dist/promise/service.d.ts"
+    },
+    "./effect": {
+      "import": "./dist/effect/index.js",
+      "types": "./dist/effect/index.d.ts"
+    },
+    "./effect/api": {
+      "import": "./dist/effect/api.js",
+      "types": "./dist/effect/api.d.ts"
+    },
+    "./effect/service": {
+      "import": "./dist/effect/service.js",
+      "types": "./dist/effect/service.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun run script/build-package.ts",
+    "generate": "bun run script/build.ts",
+    "check:generated": "bun run generate && git diff --exit-code -- src/promise/generated src/effect/generated src/effect/api",
+    "test": "bun test --timeout 5000",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@opencode-ai/schema": "0.0.0-dev-17471",
+    "@opencode-ai/protocol": "0.0.0-dev-17471"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-beta.101"
+  },
+  "peerDependenciesMeta": {
+    "effect": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-beta.101",
+    "@opencode-ai/httpapi-codegen": "0.0.0-dev-17471",
+    "@tsconfig/bun": "1.0.9",
+    "@types/bun": "1.3.13",
+    "@typescript/native-preview": "7.0.0-dev.20251207.1",
+    "effect": "4.0.0-beta.101"
+  }
+}