@opencode-ai/client 0.0.0-dev-18400 → 0.0.0-dev-18407

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

@@ -2115,6 +2115,15 @@ export type ExperimentalPersistentPtyCreateOutput = {
 export type ExperimentalPersistentPtyCreateOperation<E = never> = (input: ExperimentalPersistentPtyCreateInput) => Effect.Effect<ExperimentalPersistentPtyCreateOutput, E>;
 export type ExperimentalPersistentPtyShutdownOutput = void;
 export type ExperimentalPersistentPtyShutdownOperation<E = never> = () => Effect.Effect<ExperimentalPersistentPtyShutdownOutput, E>;
+export type ExperimentalPersistentPtyHandoffOutput = {
+    readonly handoff: {
+        readonly directory: string;
+        readonly instanceID: string;
+        readonly ticket: string;
+        readonly expiresAt: number;
+    } | null;
+};
+export type ExperimentalPersistentPtyHandoffOperation<E = never> = () => Effect.Effect<ExperimentalPersistentPtyHandoffOutput, E>;
 export type ExperimentalPersistentPtyGetInput = {
     readonly ptyID: Pty.ID;
 };
@@ -2216,6 +2225,7 @@ export interface ExperimentalApi<E = never> {
         readonly list: ExperimentalPersistentPtyListOperation<E>;
         readonly create: ExperimentalPersistentPtyCreateOperation<E>;
         readonly shutdown: ExperimentalPersistentPtyShutdownOperation<E>;
+        readonly handoff: ExperimentalPersistentPtyHandoffOperation<E>;
         readonly get: ExperimentalPersistentPtyGetOperation<E>;
         readonly update: ExperimentalPersistentPtyUpdateOperation<E>;
         readonly snapshot: ExperimentalPersistentPtySnapshotOperation<E>;

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

@@ -1,7 +1,7 @@
 import { Effect, Stream, Schema } from "effect";
 import { Sse } from "effect/unstable/encoding";
 import { HttpClientError } from "effect/unstable/http";
-import type { HealthGetOutput, ServerGetOutput, LocationGetInput, AgentListInput, AgentListOutput, AgentGetInput, AgentGetOutput, PluginListInput, PluginListOutput, SessionListInput, SessionListOutput, SessionStatsInput, SessionStatsOutput, SessionCreateInput, SessionImportInput, SessionExportInput, SessionExportOutput, SessionActiveOutput, SessionGetInput, SessionRemoveInput, SessionForkInput, SessionSwitchAgentInput, SessionSwitchModelInput, SessionRenameInput, SessionMoveInput, SessionPromptInput, SessionCommandInput, SessionSkillInput, SessionSyntheticInput, SessionShellInput, SessionCompactInput, SessionWaitInput, SessionRevertStageInput, SessionRevertClearInput, SessionRevertCommitInput, SessionContextInput, SessionContextOutput, SessionInboxListInput, SessionInboxListOutput, SessionInboxCancelInput, SessionInboxSteerInput, SessionInboxQueueInput, SessionInstructionsEntryListInput, SessionInstructionsEntryListOutput, SessionInstructionsEntryPutInput, SessionInstructionsEntryRemoveInput, SessionGenerateInput, SessionGenerateOutput, SessionLogInput, SessionLogOutput, SessionInterruptInput, SessionInterruptOutput, SessionBackgroundInput, SessionMessageInput, SessionMessageUpdateInput, SessionEnvironmentInput, SessionViewInput, MessageListInput, MessageListOutput, ModelListInput, ModelListOutput, ModelDefaultInput, ModelDefaultOutput, GenerateTextInput, GenerateTextOutput, ProviderListInput, ProviderListOutput, ProviderGetInput, ProviderGetOutput, IntegrationListInput, IntegrationListOutput, IntegrationGetInput, IntegrationGetOutput, IntegrationWellknownAddInput, IntegrationConnectKeyInput, IntegrationOauthConnectInput, IntegrationOauthConnectOutput, IntegrationOauthStatusInput, IntegrationOauthStatusOutput, IntegrationOauthCompleteInput, IntegrationOauthCancelInput, IntegrationCommandConnectInput, IntegrationCommandConnectOutput, IntegrationCommandStatusInput, IntegrationCommandStatusOutput, IntegrationCommandCancelInput, McpListInput, McpListOutput, McpAddInput, McpRemoveInput, McpConnectInput, McpDisconnectInput, McpResourceCatalogInput, McpResourceCatalogOutput, CredentialUpdateInput, CredentialActivateInput, CredentialRemoveInput, ProjectListOutput, ProjectUpdateInput, ProjectCurrentInput, FormRequestListInput, FormRequestListOutput, FormListInput, FormListOutput, FormCreateInput, FormGetInput, FormStateInput, FormReplyInput, FormCancelInput, PermissionRequestListInput, PermissionRequestListOutput, PermissionSavedListInput, PermissionSavedListOutput, PermissionSavedRemoveInput, PermissionCreateInput, PermissionCreateOutput, PermissionListInput, PermissionListOutput, PermissionGetInput, PermissionReplyInput, FileListInput, FileListOutput, FileFindInput, FileFindOutput, CommandListInput, CommandListOutput, SkillListInput, SkillListOutput, PtyListInput, PtyListOutput, PtyCreateInput, PtyCreateOutput, PtyGetInput, PtyGetOutput, PtyUpdateInput, PtyUpdateOutput, PtyRemoveInput, PtyConnectTokenInput, PtyConnectTokenOutput, ExperimentalPersistentPtyListInput, ExperimentalPersistentPtyListOutput, ExperimentalPersistentPtyCreateInput, ExperimentalPersistentPtyCreateOutput, ExperimentalPersistentPtyGetInput, ExperimentalPersistentPtyGetOutput, ExperimentalPersistentPtyUpdateInput, ExperimentalPersistentPtyUpdateOutput, ExperimentalPersistentPtySnapshotInput, ExperimentalPersistentPtySnapshotOutput, ExperimentalPersistentPtyRemoveInput, ExperimentalPersistentPtyConnectTokenInput, ShellListInput, ShellListOutput, ShellCreateInput, ShellCreateOutput, ShellGetInput, ShellGetOutput, ShellTimeoutInput, ShellTimeoutOutput, ShellOutputInput, ShellOutputOutput, ShellRemoveInput, ReferenceListInput, ReferenceListOutput, WorktreeListInput, WorktreeCreateInput, WorktreeRemoveInput, WorktreeRefreshInput, WorkspaceCreateInput, WorkspaceDestroyInput, VcsGetInput, VcsGetOutput, VcsStatusInput, VcsStatusOutput, VcsBranchesInput, VcsBranchesOutput, VcsDiffInput, VcsDiffOutput, DebugLocationListOutput, DebugLocationEvictInput, MigrationV1StatusOutput, WebsearchProvidersInput, WebsearchProvidersOutput, WebsearchQueryInput, WebsearchQueryOutput, ConfigGetInput, ConfigGetOutput } from "../api/api.js";
+import type { HealthGetOutput, ServerGetOutput, LocationGetInput, AgentListInput, AgentListOutput, AgentGetInput, AgentGetOutput, PluginListInput, PluginListOutput, SessionListInput, SessionListOutput, SessionStatsInput, SessionStatsOutput, SessionCreateInput, SessionImportInput, SessionExportInput, SessionExportOutput, SessionActiveOutput, SessionGetInput, SessionRemoveInput, SessionForkInput, SessionSwitchAgentInput, SessionSwitchModelInput, SessionRenameInput, SessionMoveInput, SessionPromptInput, SessionCommandInput, SessionSkillInput, SessionSyntheticInput, SessionShellInput, SessionCompactInput, SessionWaitInput, SessionRevertStageInput, SessionRevertClearInput, SessionRevertCommitInput, SessionContextInput, SessionContextOutput, SessionInboxListInput, SessionInboxListOutput, SessionInboxCancelInput, SessionInboxSteerInput, SessionInboxQueueInput, SessionInstructionsEntryListInput, SessionInstructionsEntryListOutput, SessionInstructionsEntryPutInput, SessionInstructionsEntryRemoveInput, SessionGenerateInput, SessionGenerateOutput, SessionLogInput, SessionLogOutput, SessionInterruptInput, SessionInterruptOutput, SessionBackgroundInput, SessionMessageInput, SessionMessageUpdateInput, SessionEnvironmentInput, SessionViewInput, MessageListInput, MessageListOutput, ModelListInput, ModelListOutput, ModelDefaultInput, ModelDefaultOutput, GenerateTextInput, GenerateTextOutput, ProviderListInput, ProviderListOutput, ProviderGetInput, ProviderGetOutput, IntegrationListInput, IntegrationListOutput, IntegrationGetInput, IntegrationGetOutput, IntegrationWellknownAddInput, IntegrationConnectKeyInput, IntegrationOauthConnectInput, IntegrationOauthConnectOutput, IntegrationOauthStatusInput, IntegrationOauthStatusOutput, IntegrationOauthCompleteInput, IntegrationOauthCancelInput, IntegrationCommandConnectInput, IntegrationCommandConnectOutput, IntegrationCommandStatusInput, IntegrationCommandStatusOutput, IntegrationCommandCancelInput, McpListInput, McpListOutput, McpAddInput, McpRemoveInput, McpConnectInput, McpDisconnectInput, McpResourceCatalogInput, McpResourceCatalogOutput, CredentialUpdateInput, CredentialActivateInput, CredentialRemoveInput, ProjectListOutput, ProjectUpdateInput, ProjectCurrentInput, FormRequestListInput, FormRequestListOutput, FormListInput, FormListOutput, FormCreateInput, FormGetInput, FormStateInput, FormReplyInput, FormCancelInput, PermissionRequestListInput, PermissionRequestListOutput, PermissionSavedListInput, PermissionSavedListOutput, PermissionSavedRemoveInput, PermissionCreateInput, PermissionCreateOutput, PermissionListInput, PermissionListOutput, PermissionGetInput, PermissionReplyInput, FileListInput, FileListOutput, FileFindInput, FileFindOutput, CommandListInput, CommandListOutput, SkillListInput, SkillListOutput, PtyListInput, PtyListOutput, PtyCreateInput, PtyCreateOutput, PtyGetInput, PtyGetOutput, PtyUpdateInput, PtyUpdateOutput, PtyRemoveInput, PtyConnectTokenInput, PtyConnectTokenOutput, ExperimentalPersistentPtyListInput, ExperimentalPersistentPtyListOutput, ExperimentalPersistentPtyCreateInput, ExperimentalPersistentPtyCreateOutput, ExperimentalPersistentPtyHandoffOutput, ExperimentalPersistentPtyGetInput, ExperimentalPersistentPtyGetOutput, ExperimentalPersistentPtyUpdateInput, ExperimentalPersistentPtyUpdateOutput, ExperimentalPersistentPtySnapshotInput, ExperimentalPersistentPtySnapshotOutput, ExperimentalPersistentPtyRemoveInput, ExperimentalPersistentPtyConnectTokenInput, ShellListInput, ShellListOutput, ShellCreateInput, ShellCreateOutput, ShellGetInput, ShellGetOutput, ShellTimeoutInput, ShellTimeoutOutput, ShellOutputInput, ShellOutputOutput, ShellRemoveInput, ReferenceListInput, ReferenceListOutput, WorktreeListInput, WorktreeCreateInput, WorktreeRemoveInput, WorktreeRefreshInput, WorkspaceCreateInput, WorkspaceDestroyInput, VcsGetInput, VcsGetOutput, VcsStatusInput, VcsStatusOutput, VcsBranchesInput, VcsBranchesOutput, VcsDiffInput, VcsDiffOutput, DebugLocationListOutput, DebugLocationEvictInput, MigrationV1StatusOutput, WebsearchProvidersInput, WebsearchProvidersOutput, WebsearchQueryInput, WebsearchQueryOutput, ConfigGetInput, ConfigGetOutput } from "../api/api.js";
 import { ClientError } from "./client-error.js";
 export declare const make: (options?: {
     readonly baseUrl?: URL | string;
@@ -2444,6 +2444,7 @@ export declare const make: (options?: {
             list: (input: ExperimentalPersistentPtyListInput) => Effect.Effect<ExperimentalPersistentPtyListOutput, import("@opencode-ai/protocol/errors").InvalidRequestError | import("@opencode-ai/protocol/errors").UnauthorizedError | import("@opencode-ai/protocol/errors").ServiceUnavailableError | Schema.SchemaError | ClientError | HttpClientError.HttpClientError, never>;
             create: (input: ExperimentalPersistentPtyCreateInput) => Effect.Effect<ExperimentalPersistentPtyCreateOutput, import("@opencode-ai/protocol/errors").InvalidRequestError | import("@opencode-ai/protocol/errors").UnauthorizedError | import("@opencode-ai/protocol/errors").ServiceUnavailableError | Schema.SchemaError | ClientError | HttpClientError.HttpClientError, never>;
             shutdown: () => Effect.Effect<void, import("@opencode-ai/protocol/errors").InvalidRequestError | import("@opencode-ai/protocol/errors").UnauthorizedError | import("@opencode-ai/protocol/errors").ServiceUnavailableError | Schema.SchemaError | ClientError | HttpClientError.HttpClientError, never>;
+            handoff: () => Effect.Effect<ExperimentalPersistentPtyHandoffOutput, import("@opencode-ai/protocol/errors").InvalidRequestError | import("@opencode-ai/protocol/errors").UnauthorizedError | import("@opencode-ai/protocol/errors").ServiceUnavailableError | Schema.SchemaError | ClientError | HttpClientError.HttpClientError, never>;
             get: (input: ExperimentalPersistentPtyGetInput) => Effect.Effect<ExperimentalPersistentPtyGetOutput, import("@opencode-ai/protocol/errors").InvalidRequestError | import("@opencode-ai/protocol/errors").UnauthorizedError | import("@opencode-ai/protocol/errors").ServiceUnavailableError | import("@opencode-ai/protocol/errors").PtyNotFoundError | Schema.SchemaError | ClientError | HttpClientError.HttpClientError, never>;
             update: (input: ExperimentalPersistentPtyUpdateInput) => Effect.Effect<ExperimentalPersistentPtyUpdateOutput, import("@opencode-ai/protocol/errors").InvalidRequestError | import("@opencode-ai/protocol/errors").UnauthorizedError | import("@opencode-ai/protocol/errors").ServiceUnavailableError | import("@opencode-ai/protocol/errors").PtyNotFoundError | Schema.SchemaError | ClientError | HttpClientError.HttpClientError, never>;
             snapshot: (input: ExperimentalPersistentPtySnapshotInput) => Effect.Effect<ExperimentalPersistentPtySnapshotOutput, import("@opencode-ai/protocol/errors").InvalidRequestError | import("@opencode-ai/protocol/errors").UnauthorizedError | import("@opencode-ai/protocol/errors").ServiceUnavailableError | import("@opencode-ai/protocol/errors").PtyNotFoundError | Schema.SchemaError | ClientError | HttpClientError.HttpClientError, never>;

package/dist/effect/generated/client.js

@@ -435,6 +435,7 @@ const EndpointExperimentalPersistentPtyCreate = (raw) => (input) => preserveEffe
     },
 }).pipe(Effect.mapError(mapClientError), Effect.map((value) => value.data)));
 const EndpointExperimentalPersistentPtyShutdown = (raw) => () => preserveEffect()(raw["persistentPty.shutdown"]({}).pipe(Effect.mapError(mapClientError)));
+const EndpointExperimentalPersistentPtyHandoff = (raw) => () => preserveEffect()(raw["persistentPty.handoff"]({}).pipe(Effect.mapError(mapClientError)));
 const EndpointExperimentalPersistentPtyGet = (raw) => (input) => preserveEffect()(raw["persistentPty.get"]({ params: { ptyID: input["ptyID"] } }).pipe(Effect.mapError(mapClientError), Effect.map((value) => value.data)));
 const EndpointExperimentalPersistentPtyUpdate = (raw) => (input) => preserveEffect()(raw["persistentPty.update"]({
     params: { ptyID: input["ptyID"] },
@@ -451,6 +452,7 @@ const adaptGroupExperimental = (raw) => ({
         list: EndpointExperimentalPersistentPtyList(raw),
         create: EndpointExperimentalPersistentPtyCreate(raw),
         shutdown: EndpointExperimentalPersistentPtyShutdown(raw),
+        handoff: EndpointExperimentalPersistentPtyHandoff(raw),
         get: EndpointExperimentalPersistentPtyGet(raw),
         update: EndpointExperimentalPersistentPtyUpdate(raw),
         snapshot: EndpointExperimentalPersistentPtySnapshot(raw),

package/dist/effect/service.js

@@ -5,6 +5,7 @@ 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.
 //
@@ -55,9 +56,10 @@ export const ensure = Effect.fn("service.ensure")(function* (options = {}) {
         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, options.env);
+                return spawnServiceContender(command, args, env);
             },
             catch: (cause) => new Error("Failed to start server", { cause }),
         });
@@ -73,6 +75,8 @@ export const ensure = Effect.fn("service.ensure")(function* (options = {}) {
             };
             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;
@@ -83,13 +87,22 @@ export const ensure = Effect.fn("service.ensure")(function* (options = {}) {
         if (service !== undefined) {
             spawnDelay = timing.spawnDelay;
             const compatible = !service.legacy && matchesVersion(service.version, options);
-            if (compatible && service.state === "ready")
+            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.tryPromise(() => PtyHandoff.prepare(options.file ?? fallback(), service.info, timing.requestTimeout));
+            else {
+                if (!service.legacy)
+                    yield* Effect.logWarning("Background service is not ready; replacement cannot preserve persistent terminals");
+                yield* Effect.tryPromise(() => PtyHandoff.clear(options.file ?? fallback()));
+            }
             yield* terminate(service.info, options, timing).pipe(Effect.ignore);
             lastSpawn = 0;
             return Option.none();
@@ -121,6 +134,7 @@ export const ensure = Effect.fn("service.ensure")(function* (options = {}) {
 });
 /** Stop the registered local service. */
 export const stop = Effect.fn("service.stop")(function* (options = {}) {
+    yield* Effect.tryPromise(() => PtyHandoff.clear(options.file ?? fallback()));
     const info = yield* read(options.file);
     if (info !== undefined)
         yield* terminate(info, options, defaultEnsureTiming);

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

@@ -1,4 +1,4 @@
-import type { ServerGetOutput, LocationGetInput, LocationGetOutput, AgentListInput, AgentListOutput, AgentGetInput, AgentGetOutput, PluginListInput, PluginListOutput, SessionListInput, SessionStatsInput, SessionCreateInput, SessionImportInput, SessionExportInput, SessionGetInput, SessionRemoveInput, SessionForkInput, SessionSwitchAgentInput, SessionSwitchModelInput, SessionRenameInput, SessionMoveInput, SessionPromptInput, SessionCommandInput, SessionSkillInput, SessionSyntheticInput, SessionShellInput, SessionCompactInput, SessionWaitInput, SessionRevertStageInput, SessionRevertClearInput, SessionRevertCommitInput, SessionContextInput, SessionInboxListInput, SessionInboxCancelInput, SessionInboxSteerInput, SessionInboxQueueInput, SessionInstructionsEntryListInput, SessionInstructionsEntryPutInput, SessionInstructionsEntryRemoveInput, SessionGenerateInput, SessionLogInput, SessionLogOutput, SessionInterruptInput, SessionBackgroundInput, SessionMessageInput, SessionMessageUpdateInput, SessionEnvironmentInput, SessionViewInput, MessageListInput, ModelListInput, ModelListOutput, ModelDefaultInput, ModelDefaultOutput, GenerateTextInput, ProviderListInput, ProviderListOutput, ProviderGetInput, ProviderGetOutput, IntegrationListInput, IntegrationListOutput, IntegrationGetInput, IntegrationGetOutput, IntegrationWellknownAddInput, IntegrationConnectKeyInput, IntegrationOauthConnectInput, IntegrationOauthConnectOutput, IntegrationOauthStatusInput, IntegrationOauthStatusOutput, IntegrationOauthCompleteInput, IntegrationOauthCancelInput, IntegrationCommandConnectInput, IntegrationCommandConnectOutput, IntegrationCommandStatusInput, IntegrationCommandStatusOutput, IntegrationCommandCancelInput, McpListInput, McpListOutput, McpAddInput, McpRemoveInput, McpConnectInput, McpDisconnectInput, McpResourceCatalogInput, McpResourceCatalogOutput, CredentialUpdateInput, CredentialActivateInput, CredentialRemoveInput, ProjectListOutput, ProjectUpdateInput, ProjectCurrentInput, FormRequestListInput, FormRequestListOutput, FormListInput, FormCreateInput, FormGetInput, FormStateInput, FormReplyInput, FormCancelInput, PermissionRequestListInput, PermissionRequestListOutput, PermissionSavedListInput, PermissionSavedRemoveInput, PermissionCreateInput, PermissionListInput, PermissionGetInput, PermissionReplyInput, FileReadInput, FileReadOutput, FileListInput, FileListOutput, FileFindInput, FileFindOutput, CommandListInput, CommandListOutput, SkillListInput, SkillListOutput, EventSubscribeOutput, PtyListInput, PtyListOutput, PtyCreateInput, PtyCreateOutput, PtyGetInput, PtyGetOutput, PtyUpdateInput, PtyUpdateOutput, PtyRemoveInput, PtyConnectTokenInput, PtyConnectTokenOutput, ExperimentalPersistentPtyListInput, ExperimentalPersistentPtyCreateInput, ExperimentalPersistentPtyGetInput, ExperimentalPersistentPtyUpdateInput, ExperimentalPersistentPtySnapshotInput, ExperimentalPersistentPtyRemoveInput, ExperimentalPersistentPtyConnectTokenInput, ShellListInput, ShellListOutput, ShellCreateInput, ShellCreateOutput, ShellGetInput, ShellGetOutput, ShellTimeoutInput, ShellTimeoutOutput, ShellOutputInput, ShellOutputOutput, ShellRemoveInput, ReferenceListInput, ReferenceListOutput, WorktreeListInput, WorktreeCreateInput, WorktreeRemoveInput, WorktreeRefreshInput, WorkspaceCreateInput, WorkspaceDestroyInput, VcsGetInput, VcsGetOutput, VcsStatusInput, VcsStatusOutput, VcsBranchesInput, VcsBranchesOutput, VcsDiffInput, VcsDiffOutput, DebugLocationListOutput, DebugLocationEvictInput, MigrationV1StatusOutput, WebsearchProvidersInput, WebsearchProvidersOutput, WebsearchQueryInput, WebsearchQueryOutput, ConfigGetInput, ConfigGetOutput } from "./types.js";
+import type { ServerGetOutput, LocationGetInput, LocationGetOutput, AgentListInput, AgentListOutput, AgentGetInput, AgentGetOutput, PluginListInput, PluginListOutput, SessionListInput, SessionStatsInput, SessionCreateInput, SessionImportInput, SessionExportInput, SessionGetInput, SessionRemoveInput, SessionForkInput, SessionSwitchAgentInput, SessionSwitchModelInput, SessionRenameInput, SessionMoveInput, SessionPromptInput, SessionCommandInput, SessionSkillInput, SessionSyntheticInput, SessionShellInput, SessionCompactInput, SessionWaitInput, SessionRevertStageInput, SessionRevertClearInput, SessionRevertCommitInput, SessionContextInput, SessionInboxListInput, SessionInboxCancelInput, SessionInboxSteerInput, SessionInboxQueueInput, SessionInstructionsEntryListInput, SessionInstructionsEntryPutInput, SessionInstructionsEntryRemoveInput, SessionGenerateInput, SessionLogInput, SessionLogOutput, SessionInterruptInput, SessionBackgroundInput, SessionMessageInput, SessionMessageUpdateInput, SessionEnvironmentInput, SessionViewInput, MessageListInput, ModelListInput, ModelListOutput, ModelDefaultInput, ModelDefaultOutput, GenerateTextInput, ProviderListInput, ProviderListOutput, ProviderGetInput, ProviderGetOutput, IntegrationListInput, IntegrationListOutput, IntegrationGetInput, IntegrationGetOutput, IntegrationWellknownAddInput, IntegrationConnectKeyInput, IntegrationOauthConnectInput, IntegrationOauthConnectOutput, IntegrationOauthStatusInput, IntegrationOauthStatusOutput, IntegrationOauthCompleteInput, IntegrationOauthCancelInput, IntegrationCommandConnectInput, IntegrationCommandConnectOutput, IntegrationCommandStatusInput, IntegrationCommandStatusOutput, IntegrationCommandCancelInput, McpListInput, McpListOutput, McpAddInput, McpRemoveInput, McpConnectInput, McpDisconnectInput, McpResourceCatalogInput, McpResourceCatalogOutput, CredentialUpdateInput, CredentialActivateInput, CredentialRemoveInput, ProjectListOutput, ProjectUpdateInput, ProjectCurrentInput, FormRequestListInput, FormRequestListOutput, FormListInput, FormCreateInput, FormGetInput, FormStateInput, FormReplyInput, FormCancelInput, PermissionRequestListInput, PermissionRequestListOutput, PermissionSavedListInput, PermissionSavedRemoveInput, PermissionCreateInput, PermissionListInput, PermissionGetInput, PermissionReplyInput, FileReadInput, FileReadOutput, FileListInput, FileListOutput, FileFindInput, FileFindOutput, CommandListInput, CommandListOutput, SkillListInput, SkillListOutput, EventSubscribeOutput, PtyListInput, PtyListOutput, PtyCreateInput, PtyCreateOutput, PtyGetInput, PtyGetOutput, PtyUpdateInput, PtyUpdateOutput, PtyRemoveInput, PtyConnectTokenInput, PtyConnectTokenOutput, ExperimentalPersistentPtyListInput, ExperimentalPersistentPtyCreateInput, ExperimentalPersistentPtyHandoffOutput, ExperimentalPersistentPtyGetInput, ExperimentalPersistentPtyUpdateInput, ExperimentalPersistentPtySnapshotInput, ExperimentalPersistentPtyRemoveInput, ExperimentalPersistentPtyConnectTokenInput, ShellListInput, ShellListOutput, ShellCreateInput, ShellCreateOutput, ShellGetInput, ShellGetOutput, ShellTimeoutInput, ShellTimeoutOutput, ShellOutputInput, ShellOutputOutput, ShellRemoveInput, ReferenceListInput, ReferenceListOutput, WorktreeListInput, WorktreeCreateInput, WorktreeRemoveInput, WorktreeRefreshInput, WorkspaceCreateInput, WorkspaceDestroyInput, VcsGetInput, VcsGetOutput, VcsStatusInput, VcsStatusOutput, VcsBranchesInput, VcsBranchesOutput, VcsDiffInput, VcsDiffOutput, DebugLocationListOutput, DebugLocationEvictInput, MigrationV1StatusOutput, WebsearchProvidersInput, WebsearchProvidersOutput, WebsearchQueryInput, WebsearchQueryOutput, ConfigGetInput, ConfigGetOutput } from "./types.js";
 export interface ClientOptions {
     readonly baseUrl: string;
     readonly fetch?: typeof globalThis.fetch;
@@ -198,6 +198,7 @@ export declare function make(options: ClientOptions): {
             list: (input: ExperimentalPersistentPtyListInput, requestOptions?: RequestOptions) => Promise<import("./types.js").PersistentPtyInfo[]>;
             create: (input: ExperimentalPersistentPtyCreateInput, requestOptions?: RequestOptions) => Promise<import("./types.js").PersistentPtyInfo>;
             shutdown: (requestOptions?: RequestOptions) => Promise<void>;
+            handoff: (requestOptions?: RequestOptions) => Promise<ExperimentalPersistentPtyHandoffOutput>;
             get: (input: ExperimentalPersistentPtyGetInput, requestOptions?: RequestOptions) => Promise<import("./types.js").PersistentPtyInfo>;
             update: (input: ExperimentalPersistentPtyUpdateInput, requestOptions?: RequestOptions) => Promise<import("./types.js").PersistentPtyInfo>;
             snapshot: (input: ExperimentalPersistentPtySnapshotInput, requestOptions?: RequestOptions) => Promise<import("./types.js").PersistentPtySnapshot>;

package/dist/promise/generated/client.js

@@ -1046,6 +1046,13 @@ export function make(options) {
                     declaredStatuses: [503, 401, 400],
                     empty: true,
                 }, requestOptions),
+                handoff: (requestOptions) => request({
+                    method: "POST",
+                    path: `/api/experimental/persistent-pty/handoff`,
+                    successStatus: 200,
+                    declaredStatuses: [503, 401, 400],
+                    empty: false,
+                }, requestOptions),
                 get: (input, requestOptions) => request({
                     method: "GET",
                     path: `/api/experimental/persistent-pty/${encodeURIComponent(input.ptyID)}`,

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

@@ -562,6 +562,12 @@ export type PtyTicketConnectToken = {
     ticket: string;
     expires_in: number;
 };
+export type PersistentPtyHandoff = {
+    directory: string;
+    instanceID: string;
+    ticket: string;
+    expiresAt: number;
+};
 export type ShellInfo1 = {
     id: string;
     status: "running" | "exited" | "timeout" | "killed";
@@ -7844,6 +7850,9 @@ export type ExperimentalPersistentPtyCreateOutput = {
     data: PersistentPtyInfo;
 }["data"];
 export type ExperimentalPersistentPtyShutdownOutput = void;
+export type ExperimentalPersistentPtyHandoffOutput = {
+    handoff: PersistentPtyHandoff | null;
+};
 export type ExperimentalPersistentPtyGetInput = {
     readonly ptyID: {
         readonly ptyID: string;

package/dist/promise/service.js

@@ -4,6 +4,7 @@ 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.
 //
@@ -34,12 +35,12 @@ export async function ensure(options = {}) {
         announced = true;
         options.onStart?.(reason, previousVersion);
     };
-    const spawnContender = () => {
+    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, options.env);
+            return spawnServiceContender(command, args, await PtyHandoff.environment(options.file ?? fallback(), options.env));
         }
         catch (cause) {
             throw new Error("Failed to start server", { cause });
@@ -57,6 +58,8 @@ export async function ensure(options = {}) {
                 };
                 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;
@@ -68,12 +71,21 @@ export async function ensure(options = {}) {
                 spawnDelay = timing.spawnDelay;
                 const service = registration.service;
                 const compatible = !service.legacy && matchesVersion(service.version, options);
-                if (compatible && service.state === "ready")
+                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")
+                        await PtyHandoff.prepare(options.file ?? fallback(), service.info, timing.requestTimeout);
+                    else {
+                        if (!service.legacy)
+                            console.warn("Background service is not ready; replacement cannot preserve persistent terminals");
+                        await PtyHandoff.clear(options.file ?? fallback());
+                    }
                     await terminate(service.info, options, timing).catch(() => undefined);
                     lastSpawn = 0;
                 }
@@ -92,7 +104,7 @@ export async function ensure(options = {}) {
                 // 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());
+                    contenders.add(await spawnContender());
                     lastSpawn = Date.now();
                 }
             }
@@ -105,6 +117,7 @@ export async function ensure(options = {}) {
 }
 /** Stop the registered local service. */
 export async function stop(options = {}) {
+    await PtyHandoff.clear(options.file ?? fallback());
     const info = await read(options.file);
     if (info !== undefined)
         await terminate(info, options, defaultEnsureTiming);

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/service-contender.d.ts

@@ -6,6 +6,6 @@ export type ServiceContender = {
     readonly stderr: () => string;
     readonly release: () => void;
 };
-export declare function spawnServiceContender(command: string, args: ReadonlyArray<string>, env?: Readonly<Record<string, string>>): ServiceContender;
+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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@opencode-ai/client",
-  "version": "0.0.0-dev-18400",
+  "version": "0.0.0-dev-18407",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -57,8 +57,8 @@
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/schema": "0.0.0-dev-18400",
-    "@opencode-ai/protocol": "0.0.0-dev-18400"
+    "@opencode-ai/schema": "0.0.0-dev-18407",
+    "@opencode-ai/protocol": "0.0.0-dev-18407"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.111",
@@ -74,7 +74,7 @@
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.0-rc.111",
-    "@opencode-ai/httpapi-codegen": "0.0.0-dev-18400",
+    "@opencode-ai/httpapi-codegen": "0.0.0-dev-18407",
     "@tsconfig/bun": "1.0.9",
     "@types/bun": "1.3.13",
     "@typescript/native-preview": "7.0.0-dev.20251207.1",