@opencode-ai/client 0.0.0-next-15611 → 0.0.0-next-15614

package/dist/effect/api/api.d.ts

@@ -9,7 +9,6 @@ export type HealthGetOperation<E = never> = () => Effect.Effect<Endpoint0_0Outpu
 type Endpoint0_1Request = Parameters<RawClient["server.health"]["health.stop"]>[0];
 export type Endpoint0_1Input = {
     readonly instanceID: Endpoint0_1Request["payload"]["instanceID"];
-    readonly targetVersion?: Endpoint0_1Request["payload"]["targetVersion"];
 };
 export type Endpoint0_1Output = EffectValue<ReturnType<RawClient["server.health"]["health.stop"]>>;
 export type HealthStopOperation<E = never> = (input: Endpoint0_1Input) => Effect.Effect<Endpoint0_1Output, E>;

package/dist/effect/generated/client.d.ts

@@ -8,7 +8,6 @@ type RawClient = HttpApiClient.ForApi<typeof ClientApi>;
 type Endpoint0_1Request = Parameters<RawClient["server.health"]["health.stop"]>[0];
 type Endpoint0_1Input = {
     readonly instanceID: Endpoint0_1Request["payload"]["instanceID"];
-    readonly targetVersion?: Endpoint0_1Request["payload"]["targetVersion"];
 };
 type Endpoint2_0Request = Parameters<RawClient["server.location"]["location.get"]>[0];
 type Endpoint2_0Input = {
@@ -511,19 +510,6 @@ export declare const make: (options?: {
             readonly healthy: true;
             readonly version: string;
             readonly pid: number;
-            readonly status: {
-                readonly type: "starting";
-            } | {
-                readonly type: "ready";
-            } | {
-                readonly type: "stopping";
-                readonly targetVersion?: string | undefined;
-            } | {
-                readonly type: "failed";
-                readonly message: string;
-                readonly action: string;
-            };
-            readonly instanceID?: string | undefined;
         }, Schema.SchemaError | import("@opencode-ai/protocol/errors").InvalidRequestError | import("@opencode-ai/protocol/errors").UnauthorizedError | HttpClientError.HttpClientError | ClientError, never>;
         stop: (input: Endpoint0_1Input) => Effect.Effect<{
             readonly accepted: boolean;

package/dist/effect/generated/client.js

@@ -9,7 +9,7 @@ const mapClientError = (error) => HttpClientError.isHttpClientError(error) || Sc
     ? new ClientError({ cause: error })
     : error;
 const Endpoint0_0 = (raw) => () => raw["health.get"]({}).pipe(Effect.mapError(mapClientError));
-const Endpoint0_1 = (raw) => (input) => raw["health.stop"]({ payload: { instanceID: input["instanceID"], targetVersion: input["targetVersion"] } }).pipe(Effect.mapError(mapClientError));
+const Endpoint0_1 = (raw) => (input) => raw["health.stop"]({ payload: { instanceID: input["instanceID"] } }).pipe(Effect.mapError(mapClientError));
 const adaptGroup0 = (raw) => ({ get: Endpoint0_0(raw), stop: Endpoint0_1(raw) });
 const Endpoint1_0 = (raw) => () => raw["server.get"]({}).pipe(Effect.mapError(mapClientError));
 const adaptGroup1 = (raw) => ({ get: Endpoint1_0(raw) });

package/dist/effect/index.d.ts

@@ -1,7 +1,6 @@
 import type { Effect } from "effect";
 export * from "./generated/index";
 export type { AgentApi, AppApi, CatalogApi, CommandApi, EventApi, IntegrationApi, ModelApi, PluginApi, ProviderApi, ReferenceApi, SessionApi, SkillApi, } from "./api.js";
-export { Service } from "./service.js";
 export { Agent } from "@opencode-ai/schema/agent";
 export { Command } from "@opencode-ai/schema/command";
 export { Credential } from "@opencode-ai/schema/credential";

package/dist/effect/index.js

@@ -1,5 +1,4 @@
 export * from "./generated/index";
-export { Service } from "./service.js";
 export { Agent } from "@opencode-ai/schema/agent";
 export { Command } from "@opencode-ai/schema/command";
 export { Credential } from "@opencode-ai/schema/credential";

package/dist/effect/service.d.ts

@@ -1,39 +1,10 @@
-import { ServiceStatus } from "@opencode-ai/protocol/groups/health";
 import { Effect, FileSystem, Schema } from "effect";
-export type Endpoint = {
-    readonly url: string;
-    readonly auth?: {
-        readonly type: "basic";
-        readonly username: string;
-        readonly password: string;
-    };
-};
-export type Options = {
-    readonly file?: string;
-    readonly version?: string;
-    readonly command?: ReadonlyArray<string>;
-};
-export type StartReason = "missing" | "version-mismatch";
-export type StartOptions = Options & {
-    readonly onStart?: (reason: StartReason, existing?: Info) => void;
-    readonly onStatus?: (status: Status) => void;
-};
-export type Status = {
-    readonly type: "missing";
-} | {
-    readonly type: "unreachable";
-} | {
-    readonly type: "unresponsive";
-} | (ServiceStatus.State & {
-    readonly version?: string;
-});
-declare const FailedError_base: Schema.Class<FailedError, Schema.TaggedStruct<"ServiceFailedError", {
-    readonly message: Schema.String;
-    readonly action: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-export declare class FailedError extends FailedError_base {
-}
-export declare const discover: (options?: Options | undefined) => Effect.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";
@@ -41,15 +12,15 @@ export declare const discover: (options?: Options | undefined) => Effect.Effect<
         password: string;
     } | undefined;
 } | undefined, never, FileSystem.FileSystem>;
-export declare const status: (options?: Options | undefined) => Effect.Effect<Status, never, FileSystem.FileSystem>;
-export declare const start: (options?: StartOptions | undefined) => Effect.Effect<Endpoint, Error, FileSystem.FileSystem>;
-export type StopMetadata = {
-    readonly targetVersion?: string;
-};
-export declare const stop: (options?: Options | undefined, metadata?: StopMetadata | undefined) => Effect.Effect<void, Error, 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>;
@@ -57,5 +28,24 @@ export declare const Info: Schema.Struct<{
     readonly pid: Schema.Int;
     readonly password: Schema.optional<Schema.String>;
 }>;
-export type Info = typeof Info.Type;
-export * as Service from "./service.js";
+/** 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>;
+    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

@@ -3,30 +3,16 @@ import { Effect, FileSystem, Option, Schedule, Schema } from "effect";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
-export class FailedError extends Schema.TaggedErrorClass()("ServiceFailedError", {
-    message: Schema.String,
-    action: Schema.String,
-}) {
-}
+export * from "../service.js";
 // Read-only lookup: registration file plus health check and version gate.
-// Never spawns; escalation to start() is the caller's policy.
+// 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 = {}) {
     return (yield* discoverLocal(options))?.endpoint;
 });
-export const status = Effect.fn("service.status")(function* (options = {}) {
-    const result = yield* registered(options.file, true);
-    if (result.info === undefined)
-        return { type: "missing" };
-    if (result.service === undefined)
-        return { type: "unreachable" };
-    return publicStatus(result.service);
-});
-function publicStatus(service) {
-    return { ...service.status, version: service.version };
-}
 const discoverLocal = Effect.fnUntraced(function* (options) {
     const found = (yield* registered(options.file)).service;
-    if (found?.status.type !== "ready")
+    if (found?.state !== "ready")
         return undefined;
     if (options.version !== undefined && found.version !== options.version)
         return undefined;
@@ -35,18 +21,18 @@ const discoverLocal = Effect.fnUntraced(function* (options) {
 // 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.
-export const start = Effect.fn("service.start")(function* (options = {}) {
+/** Ensure a healthy, compatible local service is running. */
+export const ensure = Effect.fn("service.ensure")(function* (options = {}) {
     const contenders = new Set();
     let announced = false;
-    let reported;
     let lastSpawn = 0;
     let spawnDelay = 5_000;
     let ownerHeld = false;
-    const announce = (reason, existing) => Effect.sync(() => {
+    const announce = (reason, previousVersion) => Effect.sync(() => {
         if (announced)
             return;
         announced = true;
-        options.onStart?.(reason, existing);
+        options.onStart?.(reason, previousVersion);
     });
     const spawnContender = Effect.gen(function* () {
         const [command, ...args] = options.command ?? ["opencode", "serve", "--service"];
@@ -69,26 +55,18 @@ export const start = Effect.fn("service.start")(function* (options = {}) {
         const registration = yield* registered(options.file, true);
         const info = registration.info;
         const service = registration.service;
-        const current = service === undefined ? { type: info === undefined ? "missing" : "unreachable" } : publicStatus(service);
-        const next = ownerHeld && service === undefined ? { type: "unresponsive" } : current;
-        yield* Effect.sync(() => {
-            if (sameStatus(reported, next))
-                return;
-            reported = next;
-            options.onStatus?.(next);
-        });
         if (service !== undefined) {
             ownerHeld = false;
             spawnDelay = 5_000;
             const compatible = !service.legacy && (options.version === undefined || service.version === options.version);
-            if (compatible && service.status.type === "ready")
+            if (compatible && service.state === "ready")
                 return Option.some(service);
-            if (compatible && service.status.type === "failed")
-                return yield* new FailedError({ message: service.status.message, action: service.status.action });
-            if (compatible || service.status.type === "stopping")
+            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.info);
-            yield* kill(service, options, options.version).pipe(Effect.ignore);
+            yield* announce("version-mismatch", service.version);
+            yield* kill(service, options).pipe(Effect.ignore);
             lastSpawn = 0;
             return Option.none();
         }
@@ -113,20 +91,6 @@ export const start = Effect.fn("service.start")(function* (options = {}) {
     }).pipe(Effect.repeat({ until: Option.isSome, schedule: Schedule.spaced("1 second") }));
     return Option.getOrThrow(found).endpoint;
 });
-function sameStatus(left, right) {
-    if (left?.type !== right.type)
-        return false;
-    if (right.type === "failed")
-        return (left.type === "failed" &&
-            left.version === right.version &&
-            left.message === right.message &&
-            left.action === right.action);
-    if (right.type === "stopping")
-        return left.type === "stopping" && left.version === right.version && left.targetVersion === right.targetVersion;
-    if (right.type === "starting" || right.type === "ready")
-        return left.type === right.type && left.version === right.version;
-    return true;
-}
 function contenderFailure(contender) {
     const error = contender.error();
     if (error !== undefined)
@@ -140,20 +104,23 @@ function contenderFailure(contender) {
 function contenderFinished(contender) {
     return contender.error() !== undefined || contender.child.exitCode !== null || contender.child.signalCode !== null;
 }
-export const stop = Effect.fn("service.stop")(function* (options = {}, metadata = {}) {
+/** Stop the registered local service. */
+export const stop = Effect.fn("service.stop")(function* (options = {}) {
     const existing = yield* find(options);
     if (existing !== undefined)
-        yield* kill(existing, options, metadata.targetVersion);
+        yield* kill(existing, options);
 });
 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),
@@ -193,13 +160,11 @@ const probe = Effect.fnUntraced(function* (info, allowLegacy = false) {
             return undefined;
         if (info.version !== undefined && health.value.version !== info.version)
             return undefined;
-        if (info.id !== undefined && health.value.instanceID !== undefined && health.value.instanceID !== info.id)
-            return undefined;
         return {
             info,
             endpoint,
             version: health.value.version,
-            status: health.value.status,
+            state: response.ok ? "ready" : response.status === 500 ? "failed" : "waiting",
             legacy: false,
         };
     }
@@ -207,7 +172,7 @@ const probe = Effect.fnUntraced(function* (info, allowLegacy = false) {
         Option.isNone(decodeLegacyHealth(body)) ||
         (typeof body === "object" && body !== null && ("version" in body || "pid" in body)))
         return undefined;
-    return { info, endpoint, status: { type: "ready" }, legacy: true };
+    return { info, endpoint, state: "ready", legacy: true };
 });
 const registered = Effect.fnUntraced(function* (file, allowLegacy = false) {
     const info = yield* read(file);
@@ -215,12 +180,12 @@ const registered = Effect.fnUntraced(function* (file, allowLegacy = false) {
         return { info: undefined, service: undefined };
     return { info, service: yield* probe(info, allowLegacy) };
 });
-// Health-checked lookup without the version gate: status operations must be
+// Health-checked lookup without the version gate: lifecycle operations must be
 // able to see (and replace or stop) a server from a different version.
 const find = Effect.fnUntraced(function* (options) {
     return (yield* registered(options.file, true)).service;
 });
-// 50ms cadence bounded at ~5s, shared by stop escalation and each start
+// 50ms cadence bounded at ~5s, shared by stop escalation and each ensure
 // discovery window.
 const poll = Schedule.spaced("50 millis").pipe(Schedule.both(Schedule.recurs(100)));
 const signal = (pid, name) => Effect.try({ try: () => process.kill(pid, name), catch: (cause) => cause }).pipe(Effect.ignore);
@@ -233,8 +198,8 @@ const stopped = Effect.fnUntraced(function* (pid) {
 function same(left, right) {
     return left.id === right.id && left.version === right.version && left.url === right.url && left.pid === right.pid;
 }
-const kill = Effect.fnUntraced(function* (service, options, targetVersion) {
-    const requested = yield* requestStop(service, targetVersion);
+const kill = Effect.fnUntraced(function* (service, options) {
+    const requested = yield* requestStop(service);
     if (requested === "rejected")
         return;
     if (requested === "unsupported") {
@@ -255,13 +220,13 @@ const kill = Effect.fnUntraced(function* (service, options, targetVersion) {
     yield* stopped(service.info.pid).pipe(Effect.retry(poll));
 });
 const decodeStopResponse = Schema.decodeUnknownOption(ServiceStatus.StopResponse);
-const requestStop = Effect.fnUntraced(function* (service, targetVersion) {
+const requestStop = Effect.fnUntraced(function* (service) {
     if (service.info.id === undefined || service.legacy)
         return "unsupported";
     const response = yield* Effect.tryPromise(() => 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, targetVersion }),
+        body: JSON.stringify({ instanceID: service.info.id }),
         signal: AbortSignal.timeout(2_000),
     })).pipe(Effect.option, Effect.map(Option.getOrUndefined));
     if (response === undefined || response.status === 404 || response.status === 405)
@@ -272,4 +237,5 @@ const requestStop = Effect.fnUntraced(function* (service, targetVersion) {
         return "rejected";
     return "accepted";
 });
-export * as Service from "./service.js";
+/** Effect-based local service lifecycle operations. */
+export const Service = { discover, ensure, stop, headers, Info };

package/dist/promise/generated/client.js

@@ -132,7 +132,7 @@ export function make(options) {
             stop: (input, requestOptions) => request({
                 method: "POST",
                 path: `/api/service/stop`,
-                body: { instanceID: input["instanceID"], targetVersion: input["targetVersion"] },
+                body: { instanceID: input["instanceID"] },
                 successStatus: 200,
                 declaredStatuses: [401, 400],
                 empty: false,

package/dist/promise/generated/types.d.ts

@@ -1,17 +1,10 @@
 export type JsonValue = null | boolean | number | string | Array<JsonValue> | {
     [key: string]: JsonValue;
 };
-export type ServiceStatus = {
-    type: "starting";
-} | {
-    type: "ready";
-} | {
-    type: "stopping";
-    targetVersion?: string | null;
-} | {
-    type: "failed";
-    message: string;
-    action: string;
+export type ServiceHealth = {
+    healthy: true;
+    version: string;
+    pid: number;
 };
 export type ServiceStopResponse = {
     accepted: boolean;
@@ -752,13 +745,6 @@ export type VcsFileStatus = {
     deletions: number;
     status: "added" | "deleted" | "modified";
 };
-export type ServiceHealth = {
-    healthy: true;
-    version: string;
-    pid: number;
-    instanceID?: string | null;
-    status?: ServiceStatus;
-};
 export type SessionMessageModelSelected = {
     id: string;
     metadata?: {
@@ -3178,12 +3164,7 @@ export type HealthGetOutput = ServiceHealth;
 export type HealthStopInput = {
     readonly instanceID: {
         readonly instanceID: string;
-        readonly targetVersion?: string | undefined;
     }["instanceID"];
-    readonly targetVersion?: {
-        readonly instanceID: string;
-        readonly targetVersion?: string | undefined;
-    }["targetVersion"];
 };
 export type HealthStopOutput = ServiceStopResponse;
 export type ServerGetOutput = {

package/dist/promise/service.d.ts

@@ -0,0 +1,19 @@
+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<Endpoint | 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,230 @@
+import { readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export * from "../service.js";
+/** 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 (options.version !== undefined && found.version !== options.version)
+        return undefined;
+    return found;
+}
+/** Ensure a healthy, compatible local service is running. */
+export async function ensure(options = {}) {
+    const contenders = new Set();
+    let announced = false;
+    let lastSpawn = 0;
+    let spawnDelay = 5_000;
+    let ownerHeld = false;
+    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 {
+            const child = spawn(command, args, { detached: true, stdio: "ignore" });
+            let error;
+            child.once("error", (cause) => {
+                error = new Error("Failed to start server", { cause });
+            });
+            child.unref();
+            return { child, error: () => error };
+        }
+        catch (cause) {
+            throw new Error("Failed to start server", { cause });
+        }
+    };
+    while (true) {
+        const registration = await registered(options.file, true);
+        if (registration.service !== undefined) {
+            ownerHeld = false;
+            spawnDelay = 5_000;
+            const service = registration.service;
+            const compatible = !service.legacy && (options.version === undefined || service.version === options.version);
+            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).catch(() => undefined);
+                lastSpawn = 0;
+            }
+        }
+        else {
+            if (lastSpawn === 0 && registration.info !== undefined)
+                lastSpawn = Date.now();
+            const failure = [...contenders].map(contenderFailure).find((error) => error !== undefined);
+            if (failure !== undefined)
+                throw failure;
+            const finished = [...contenders].filter(contenderFinished);
+            if (finished.some((item) => item.child.exitCode === 0)) {
+                ownerHeld = true;
+                spawnDelay = Math.min(spawnDelay * 2, 30_000);
+            }
+            finished.forEach((item) => contenders.delete(item));
+            // 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(1_000);
+    }
+}
+function contenderFailure(contender) {
+    const error = contender.error();
+    if (error !== undefined)
+        return error;
+    if (contender.child.exitCode !== null && contender.child.exitCode !== 0)
+        return new Error(`Server process exited with code ${contender.child.exitCode}`);
+    if (contender.child.signalCode !== null)
+        return new Error(`Server process terminated by ${contender.child.signalCode}`);
+    return undefined;
+}
+function contenderFinished(contender) {
+    return contender.error() !== undefined || contender.child.exitCode !== null || contender.child.signalCode !== null;
+}
+/** Stop the registered local service. */
+export async function stop(options = {}) {
+    const existing = await find(options);
+    if (existing !== undefined)
+        await kill(existing, options);
+}
+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) {
+    const endpoint = {
+        url: info.url,
+        auth: info.password === undefined
+            ? undefined
+            : { type: "basic", username: "opencode", password: info.password },
+    };
+    const response = await fetch(new URL("/api/health", info.url), {
+        headers: headers(endpoint),
+        signal: AbortSignal.timeout(2_000),
+    }).catch(() => undefined);
+    const body = (await response?.json().catch(() => undefined));
+    if (body !== undefined && "version" in body && "pid" in body) {
+        if (body.pid !== info.pid)
+            return undefined;
+        if (info.version !== undefined && body.version !== info.version)
+            return undefined;
+        return {
+            info,
+            endpoint,
+            version: body.version,
+            state: response?.ok ? "ready" : response?.status === 500 ? "failed" : "waiting",
+            legacy: false,
+        };
+    }
+    if (!allowLegacy || body?.healthy !== true)
+        return undefined;
+    return { info, endpoint, state: "ready", legacy: true };
+}
+async function registered(file, allowLegacy = false) {
+    const info = await read(file);
+    if (info === undefined)
+        return { info: undefined, service: undefined };
+    return { info, service: await probe(info, allowLegacy) };
+}
+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) {
+    for (let attempt = 0; attempt <= 100; attempt++) {
+        if (stopped(pid))
+            return true;
+        if (attempt < 100)
+            await delay(50);
+    }
+    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 kill(service, options) {
+    const requested = await requestStop(service);
+    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))
+        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)))
+        throw new Error(`Server process ${service.info.pid} is still running`);
+}
+async function requestStop(service) {
+    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(2_000),
+    }).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.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 service version. */
+    readonly version?: string;
+};
+/** 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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@opencode-ai/client",
-  "version": "0.0.0-next-15611",
+  "version": "0.0.0-next-15614",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,10 @@
       "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"
@@ -35,6 +39,10 @@
     "./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": {
@@ -45,8 +53,8 @@
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/schema": "0.0.0-next-15611",
-    "@opencode-ai/protocol": "0.0.0-next-15611"
+    "@opencode-ai/schema": "0.0.0-next-15614",
+    "@opencode-ai/protocol": "0.0.0-next-15614"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.83"
@@ -58,7 +66,7 @@
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.0-beta.83",
-    "@opencode-ai/httpapi-codegen": "0.0.0-next-15611",
+    "@opencode-ai/httpapi-codegen": "0.0.0-next-15614",
     "@tsconfig/bun": "1.0.9",
     "@types/bun": "1.3.13",
     "@typescript/native-preview": "7.0.0-dev.20251207.1",