@jskit-ai/assistant-core 0.2.6 → 0.2.8

package/src/server/conversation/openCodeNativeHistory.js

@@ -0,0 +1,141 @@
+// Stopped native storage inspection, and retirement of a native family after the host's durable preservation.
+import { Buffer } from "node:buffer";
+import path from "node:path";
+import { createNativeHistoryExport, readStoppedNativeDatabase, retireNativeConversation } from "./nativeHistoryExport.js";
+import { normalizedMessageRows, openCodeAssistantMessageText } from "./openCodeClient.js";
+
+/** Inspect stopped native storage without starting OpenCode or changing its files. */
+async function readOpenCodeConversationDatabase({ databasePath, conversationId, onMessage, signal } = {}) {
+  if (!path.isAbsolute(databasePath || "") || !/^ses_[a-zA-Z0-9_]{1,256}$/u.test(conversationId || "") ||
+      typeof onMessage !== "function") throw new TypeError("OpenCode inspection requires its exact database, conversation and message reader.");
+  const unavailable = () => new Error("OpenCode native storage could not be inspected completely. Keep its writers stopped and inspect its original database before retrying.");
+  try {
+    return await readStoppedNativeDatabase(databasePath, async database => {
+      const session = database.prepare("SELECT * FROM session WHERE id = ?").get(conversationId);
+      if (!session || session.id !== conversationId || !path.isAbsolute(session.directory || "")) throw unavailable();
+      if (database.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'session_input'").get() &&
+          database.prepare("SELECT 1 FROM session_input WHERE session_id = ? AND promoted_seq IS NULL LIMIT 1").get(conversationId)) {
+        throw new Error("OpenCode has an unpromoted native request. Inspect it before restoring continuity; no request was repeated.");
+      }
+      const output = createNativeHistoryExport(async ({ message }) => onMessage(normalizedMessageRows([message])[0]), { signal });
+      const parts = database.prepare("SELECT id, message_id, session_id, data FROM part WHERE message_id = ? ORDER BY id");
+      for (const row of database.prepare("SELECT id, session_id, data FROM message WHERE session_id = ? ORDER BY time_created, id").iterate(conversationId)) {
+        signal?.throwIfAborted();
+        if (!/^msg_[a-zA-Z0-9_]{1,256}$/u.test(row.id)) throw unavailable();
+        let bytes = Buffer.byteLength(row.data);
+        if (bytes > 64 * 1024 * 1024) throw unavailable();
+        const data = JSON.parse(row.data);
+        if (!data || typeof data !== "object" || Array.isArray(data) || !["user", "assistant"].includes(data.role)) throw unavailable();
+        const content = [];
+        for (const part of parts.iterate(row.id)) {
+          signal?.throwIfAborted();
+          bytes += Buffer.byteLength(part.data);
+          if (bytes > 64 * 1024 * 1024 || part.session_id !== conversationId || part.message_id !== row.id ||
+              !/^prt_[a-zA-Z0-9_]{1,256}$/u.test(part.id)) throw unavailable();
+          const value = JSON.parse(part.data);
+          if (!value || typeof value !== "object" || Array.isArray(value)) throw unavailable();
+          content.push({ ...value, id: part.id, sessionID: part.session_id, messageID: part.message_id });
+        }
+        // OpenCode's MessageV2 storage projection: native columns own IDs.
+        await output.emit({ type: "message", message: { info: { ...data, id: row.id, sessionID: row.session_id }, parts: content }, text: [] });
+      }
+      return { session, ...output.complete() };
+    }, { signal });
+  } catch (error) {
+    if (signal?.aborted) throw signal.reason;
+    if (String(error?.message || "").startsWith("OpenCode ") ||
+        String(error?.message || "").startsWith("Native storage ")) throw error;
+    throw unavailable();
+  }
+}
+
+// Native preservation uses the storage API independently of the saved worktree.
+// Status still comes from the exact directory-scoped control client.
+async function inspectOpenCodeConversationFamily(storageClient, controlClient, binding, { signal } = {}) {
+  const queue = [binding.conversationId];
+  const seen = new Set();
+  const records = [];
+  for (let index = 0; index < queue.length; index += 1) {
+    signal?.throwIfAborted();
+    const conversationId = queue[index];
+    if (seen.has(conversationId) || queue.length > 1000) throw new Error("OpenCode native family is cyclic or exceeds its inventory limit.");
+    seen.add(conversationId);
+    let native;
+    try { native = await storageClient.readConversationStorage(conversationId, { signal }); }
+    catch (error) { if (error.statusCode === 404 && index === 0) return []; throw error; }
+    if (native?.id !== conversationId || native?.directory !== binding.workdir ||
+        (await controlClient.sessionStatus(conversationId, { signal })).type !== "idle") {
+      throw new Error("OpenCode retirement requires an idle native family in the exact saved directory.");
+    }
+    records.push({ conversationId, workdir: native.directory,
+      ...(Number.isFinite(native.time?.created) ? { createdAt: new Date(native.time.created).toISOString() } : {}),
+      ...(Number.isFinite(native.time?.updated) ? { updatedAt: new Date(native.time.updated).toISOString() } : {}) });
+    const children = await storageClient.listConversationChildren(conversationId, { signal });
+    for (const child of children) {
+      if (child.directory !== binding.workdir) throw new Error("OpenCode child directory differs from its saved owner.");
+      queue.push(child.id);
+    }
+  }
+  return records.sort((left, right) => left.conversationId.localeCompare(right.conversationId));
+}
+
+async function exportOpenCodeNativeHistory(storageClient, controlClient, id, onRecord, { signal: inputSignal } = {}) {
+  const deadline = AbortSignal.timeout(300_000);
+  const signal = inputSignal ? AbortSignal.any([inputSignal, deadline]) : deadline;
+  const output = createNativeHistoryExport(onRecord, { signal });
+  const info = await storageClient.readConversationStorage(id, { signal });
+  if (info?.id !== id || (await controlClient.sessionStatus(id, { signal })).type !== "idle") {
+    throw new Error("OpenCode native export requires the exact idle conversation.");
+  }
+  await output.emit({ type: "thread", thread: info, text: [] });
+  const messageIds = new Set();
+  const cursors = new Set();
+  let before = "";
+  let pages = 0;
+  while (true) {
+    signal.throwIfAborted();
+    if (++pages > 20_000) throw new Error("OpenCode native export exceeded its page limit; history was not retired.");
+    const response = await storageClient.readConversationStoragePage(id, { before, signal });
+    if (!Array.isArray(response?.data) || response.data.length > 1 ||
+        (response.nextCursor !== null && (typeof response.nextCursor !== "string" || !response.nextCursor || response.nextCursor.length > 8192)) ||
+        (response.data.length === 0 && response.nextCursor !== null)) {
+      throw new Error("OpenCode returned an incomplete or invalid native message page.");
+    }
+    for (const message of response.data) {
+      const info = message?.info;
+      if (!/^msg_[a-zA-Z0-9_]{1,256}$/u.test(info?.id) || info.sessionID !== id ||
+          !["user", "assistant"].includes(info.role) || !Array.isArray(message.parts) || messageIds.has(info.id)) {
+        throw new Error("OpenCode returned an invalid or duplicate native message.");
+      }
+      messageIds.add(info.id);
+      const content = openCodeAssistantMessageText({ content: message.parts });
+      await output.emit({ type: "message", message, text: content ? [{ role: info.role, text: content,
+        branchId: id, messageId: info.id,
+        ...(info.parentID ? { parentMessageId: info.parentID } : {}),
+        ...(Number.isFinite(info.time?.created) ? { createdAt: new Date(info.time.created).toISOString() } : {}),
+        ...(Number.isFinite(info.time?.completed) ? { completedAt: new Date(info.time.completed).toISOString() } : {}),
+        ...(info.modelID || info.model?.modelID ? { modelId: info.modelID || info.model.modelID } : {}),
+        ...(info.providerID || info.model?.providerID ? { modelProviderId: info.providerID || info.model.providerID } : {}),
+        ...(info.agent ? { agent: info.agent } : {}) }] : [] });
+    }
+    if (response.nextCursor === null) break;
+    if (cursors.has(response.nextCursor)) throw new Error("OpenCode repeated a native history cursor.");
+    cursors.add(response.nextCursor);
+    before = response.nextCursor;
+  }
+  return output.complete();
+}
+
+/** Retire the exact native family after the host's durable preservation. */
+async function retireOpenCodeConversationHistory(storageClient, controlClient, binding, options = {}) {
+  const inspect = () => inspectOpenCodeConversationFamily(storageClient, controlClient, binding, { signal: options.signal });
+  return retireNativeConversation({ binding, inspect, beforeDelete: options.beforeDelete,
+    readConversation: async (id) => ({ info: await storageClient.readConversationStorage(id), messages: (await controlClient.messages(id)).data }),
+    exportConversation: (id, onRecord) => exportOpenCodeNativeHistory(storageClient, controlClient, id, onRecord, { signal: options.signal }),
+    remove: () => controlClient.deleteSession(binding.conversationId) });
+}
+
+export {
+  readOpenCodeConversationDatabase,
+  retireOpenCodeConversationHistory
+};

package/src/server/conversation/openCodeNativeSession.js

@@ -0,0 +1,79 @@
+// One native OpenCode session: its model, its selection, the shared server
+// bound to its directory, and the start that creates or resumes it.
+import { normalizeNullableText } from "./normalize.js";
+
+/** The shared server with its client bound to one native directory. */
+export function openCodeServerForDirectory(server, workdir) {
+  return Object.freeze({
+    ...server,
+    client: server.client.forDirectory(workdir)
+  });
+}
+
+/** The native model a selection names, or the one an execution profile overrides it with. */
+export function openCodeModel(selection = {}, executionProfile = null) {
+  const modelId = normalizeNullableText(executionProfile?.model) || normalizeNullableText(selection.modelId);
+  const variantId = executionProfile
+    ? normalizeNullableText(executionProfile.thinking)
+    : normalizeNullableText(selection.variantId);
+  return {
+    id: modelId,
+    providerID: normalizeNullableText(selection.modelProviderId),
+    ...(variantId ? { variant: variantId } : {})
+  };
+}
+
+/** Whether two selections name the same agent, model, provider and variant. */
+export function sameOpenCodeSelection(left, right) {
+  return ["agentId", "modelId", "modelProviderId", "variantId"]
+    .every((name) => normalizeNullableText(left?.[name]) === normalizeNullableText(right?.[name]));
+}
+
+/**
+ * Native selection and identity publication share the same pending operation.
+ * @param {object} target
+ * @param {{ selection: object, model: object, workdir?: string, signal?: AbortSignal, invalidIdentity?: () => Error,
+ *   identity: { write(nativeId: string): unknown, publish(nativeId: string): unknown } }} session
+ */
+export async function ensureOpenCodeSession(target, { selection, model, workdir = target.workdir, identity, signal,
+  invalidIdentity = () => new Error("OpenCode did not return a native conversation ID.") }) {
+  if (target.upstreamStart) {
+    return target.upstreamStart;
+  }
+  const start = Promise.resolve().then(async () => {
+    await target.server.client.prepareDirectory({ signal });
+    let upstream = (
+      target.upstream &&
+      sameOpenCodeSelection(target.upstreamSelection, selection)
+    ) ? target.upstream : null;
+    if (!upstream && target.upstreamSessionId) {
+      upstream = await target.server.client.readSession(target.upstreamSessionId, { signal });
+      await target.server.client.switchModel(target.upstreamSessionId, model, { signal });
+      await target.server.client.switchAgent(target.upstreamSessionId, selection.agentId, { signal });
+    } else if (!upstream) {
+      upstream = await target.server.client.createSession({
+        agent: selection.agentId,
+        location: { directory: workdir },
+        model
+      }, { signal });
+    }
+    const nativeId = normalizeNullableText(upstream?.id);
+    if (!nativeId) {
+      throw invalidIdentity();
+    }
+    await identity.write(nativeId);
+    target.upstreamSessionId = nativeId;
+    target.upstream = upstream;
+    target.upstreamSelection = { ...selection };
+    await identity.publish(nativeId);
+    return target;
+  });
+  target.upstreamStart = start;
+  try {
+    return await start;
+  } finally {
+    if (target.upstreamStart === start) {
+      delete target.upstreamStart;
+    }
+  }
+}

package/src/server/conversation/openCodeProcess.js

@@ -1,3 +1,4 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import { randomBytes } from "node:crypto";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import net from "node:net";
@@ -7,9 +8,9 @@ import { createOpenCodeServerClient, readBoundedResponse } from "./openCodeClien
 import { createLocalConversationExecution } from "./localExecution.js";
 import { normalizeNullableText } from "./normalize.js";
 import { DISCOVERY_TOOL_DESCRIPTORS } from "../lib/serviceToolCatalog.js";
-export { createOpenCodeSharedRuntime, openCodeServerForDirectory, readOpenCodeEnvironments, openCodeEnvironmentForDirectory,
-  openCodeEnvironmentForSession, assertOpenCodeModelProvider, limitOpenCodeModelOutput,
-  ensureOpenCodeSession, openCodeModel, sameOpenCodeSelection } from "./openCodeRuntime.js";
+export { createOpenCodeSharedRuntime, readOpenCodeEnvironments, openCodeEnvironmentForDirectory,
+  openCodeEnvironmentForSession, assertOpenCodeModelProvider, limitOpenCodeModelOutput } from "./openCodeRuntime.js";
+export { openCodeServerForDirectory, ensureOpenCodeSession, openCodeModel, sameOpenCodeSelection } from "./openCodeNativeSession.js";
 export { default as createOpenCodeConversationPlugin } from "./openCodePlugin.js";
 
 export const OPENCODE_EXPECTED_VERSION = "1.18.31";
@@ -26,7 +27,11 @@ const OPENCODE_ZEN_MODELS_URL = "https://opencode.ai/zen/v1/models";
 const OPENCODE_ZEN_PROVIDER_ID = "opencode";
 const OPENCODE_ZEN_PUBLIC_API_KEY = "public";
 
-const text = normalizeNullableText;
+/** A server start whose caller records no execution identity. */
+function ignoreServerStart() {}
+
+/** A server whose caller keeps no state after an unexpected exit. */
+function ignoreServerFailure() {}
 
 export function openCodeProcessEnvironment(baseEnv = {}, {
   cacheRoot = "", dbPath = "", inlineConfig = "", outputTokenMax = 0, packageInstalls = true, password = ""
@@ -44,7 +49,7 @@ export function openCodeProcessEnvironment(baseEnv = {}, {
       npm_config_cache: path.join(cacheRoot, "npm-offline"),
       npm_config_offline: "true"
     }),
-    NO_PROXY: [text(baseEnv.NO_PROXY), OPENCODE_HOST, "localhost", "::1"]
+    NO_PROXY: [normalizeNullableText(baseEnv.NO_PROXY), OPENCODE_HOST, "localhost", "::1"]
       .filter(Boolean)
       .join(","),
     OPENCODE_DB: dbPath,
@@ -124,9 +129,9 @@ async function waitForOpenCodeReady({
       });
       signal?.throwIfAborted();
       if (health?.healthy === true) {
-        if (expectedVersion && text(health.version) !== expectedVersion) {
+        if (expectedVersion && normalizeNullableText(health.version) !== expectedVersion) {
           const error = new Error(
-            `OpenCode ${text(health.version) || "(unknown)"} is installed; this host requires ${expectedVersion}.`
+            `OpenCode ${normalizeNullableText(health.version) || "(unknown)"} is installed; this host requires ${expectedVersion}.`
           );
           error.code = "assistant_opencode_version_mismatch";
           throw error;
@@ -161,11 +166,11 @@ export function openCodeConversationAgent({ nativeTools = false, tools = false }
 }
 
 export function openCodeConversationAgents({ sessionEnvironmentRegistry = "" } = {}) {
-  const guarded = Boolean(text(sessionEnvironmentRegistry));
+  const guarded = Boolean(normalizeNullableText(sessionEnvironmentRegistry));
   return Object.fromEntries([false, true].flatMap(nativeTools => [false, true].map(tools => [
     openCodeConversationAgent({ nativeTools, tools }), {
       hidden: true, mode: "primary",
-      // Keep native definitions behind approval, as in the original host agents.
+      // Keep native definitions behind approval.
       // The registered plugin rejects every ungranted native call before execution.
       permission: nativeTools || tools || guarded ? agentPermission(!nativeTools && guarded, nativeTools, tools) : "deny"
     }
@@ -181,12 +186,32 @@ function agentPermission(ask, nativeTools, tools) {
     ...(tools ? actionPermission("allow") : ask ? actionPermission("deny") : {}), ...(ask ? { doom_loop: "deny" } : {}) };
 }
 
-/** Shared conversation configuration around the extracted server lifecycle. */
+/** @typedef {import("./localExecution.js").ConversationExecution} ConversationExecution */
+
+/**
+ * Starts the OpenCode server of one conversation runtime: its private credential home, its configuration for the selected
+ * connection, and the environment it passes on from the application's.
+ * @param {object} options
+ * @param {string} [options.command]
+ * @param {ConversationExecution} [options.execution]
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.env
+ * @param {string} options.workdir
+ * @param {string} options.stateDirectory
+ * @param {string} options.databasePath
+ * @param {string} options.sessionEnvironmentRegistry
+ * @param {Record<string, any>} options.connection
+ * @param {number} [options.maxOutputTokens]
+ * @param {(executionId: string, processDirectory: string) => unknown} [options.onStarted]
+ * @param {(error: Error) => unknown} [options.onFailure]
+ * @param {object} [options.executionLimits]
+ * @param {AbortSignal} [options.signal]
+ */
 export async function createOpenCodeConversationServer({
-  command = "opencode", execution = createLocalConversationExecution(), env = process.env,
+  command = "opencode", execution = createLocalConversationExecution(), env,
   workdir, stateDirectory, databasePath, sessionEnvironmentRegistry, connection, maxOutputTokens,
-  onStarted, onFailure, executionLimits, signal
-} = {}) {
+  onStarted = ignoreServerStart, onFailure = ignoreServerFailure, executionLimits, signal
+}) {
+  if (!env) throw new TypeError("An OpenCode conversation's host requires the application's environment, such as process.env, to start OpenCode.");
   await mkdir(stateDirectory, { recursive: true, mode: 0o700 });
   const directory = await mkdtemp(path.join(stateDirectory, "process-"));
   const model = `${connection.providerId}/${connection.model}`;
@@ -221,17 +246,39 @@ export async function createOpenCodeConversationServer({
     JSKIT_OPENCODE_TOOL_SCHEMAS: JSON.stringify(openCodeApplicationToolSchemas)
   });
   return createOpenCodeServerProcess({ command, execution, env: environment, workdir, privateRoot: directory,
-    directory: workdir, connections: [connection], onStarted: id => onStarted?.(id, directory),
+    directory: workdir, connections: [connection], onStarted: id => onStarted(id, directory),
     onFailure, executionLimits, signal });
 }
 
-/** Shared server lifecycle for standalone and managed hosts. */
+/**
+ * Shared server lifecycle for standalone and managed hosts.
+ * @param {object} options
+ * @param {string} [options.command]
+ * @param {ConversationExecution} [options.execution]
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.env
+ * @param {string} options.workdir
+ * @param {string} options.privateRoot
+ * @param {string} [options.directory]
+ * @param {Record<string, any>[]} [options.connections]
+ * @param {number} [options.port]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @param {boolean} [options.allowAttachmentDirectories]
+ * @param {string} [options.expectedVersion]
+ * @param {number} [options.readinessTimeoutMs]
+ * @param {(executionId: string) => unknown} [options.onStarted]
+ * @param {(error: Error) => unknown} [options.onFailure]
+ * @param {object} [options.executionLimits]
+ * @param {AbortSignal} [options.signal]
+ */
 export async function createOpenCodeServerProcess({
-  command = "opencode", execution = createLocalConversationExecution(), env = process.env,
+  command = "opencode", execution = createLocalConversationExecution(), env,
   workdir, privateRoot, directory = "", connections = [], port = 0, fetchImpl = globalThis.fetch,
   allowAttachmentDirectories = false, expectedVersion = OPENCODE_EXPECTED_VERSION, readinessTimeoutMs = OPENCODE_READY_TIMEOUT_MS,
-  onStarted, onFailure, executionLimits, signal
-} = {}) {
+  onStarted = ignoreServerStart, onFailure = ignoreServerFailure, executionLimits, signal
+}) {
+  if (!env) {
+    throw new TypeError("createOpenCodeServerProcess requires the application's environment, such as process.env.");
+  }
   if (!path.isAbsolute(workdir || "") || !path.isAbsolute(privateRoot || "")) {
     throw new TypeError("OpenCode server processes require absolute working and private roots.");
   }
@@ -250,6 +297,7 @@ export async function createOpenCodeServerProcess({
   const logPath = path.join(privateRoot, "opencode-server.log");
   const processHandle = {
     get exited() { return stopped || native?.running === false; },
+    // readable-check: allow optional-call - optional operation: an execution host's started process may not keep its logs
     readLogs: () => native?.readLogs?.() || { stderr: "", stdout: "" },
     async stop() {
       const proof = await execution.stop(executionId, {
@@ -293,17 +341,17 @@ export async function createOpenCodeServerProcess({
     native = await execution.start({ command, cwd: workdir, env: environment, limits: executionLimits,
       logPath, args: ["serve", "--hostname", OPENCODE_HOST, "--port", String(selectedPort), "--mdns=false"] });
     executionId = native.id;
-    await onStarted?.(native.id);
+    await onStarted(native.id);
     const fail = error => {
       if (closing) return;
       unexpectedExit.resolve(error);
-      Promise.resolve().then(() => onFailure?.(error)).catch(() => {});
+      Promise.resolve().then(() => onFailure(error)).catch(() => {});
     };
     native.exited.then(() => fail(new Error("The owned OpenCode process exited."))).catch(fail);
     const health = await waitForOpenCodeReady({ client, expectedVersion, processHandle, timeoutMs: readinessTimeoutMs, signal });
     const authenticated = new Set();
     for (const connection of connections) {
-      const providerId = text(connection?.providerId);
+      const providerId = normalizeNullableText(connection?.providerId);
       const key = String(connection?.apiKey || "");
       if (!providerId || !key || authenticated.has(providerId)) {
         continue;
@@ -311,22 +359,32 @@ export async function createOpenCodeServerProcess({
       await client.authenticateApiKey(providerId, key, { signal });
       authenticated.add(providerId);
     }
-    return Object.freeze({ client, executionId: native.id, privateRoot, pid: native.pid, port: selectedPort,
-      environment, health: Object.freeze({ ...health }), modelProviderIds: Object.freeze([...authenticated]),
-      readLogs: processHandle.readLogs, stop,
+    /** The native terminal's arguments for one conversation in an absolute directory. */
+    function attachArguments({ conversationId, directory }) {
+      if (!conversationId || !path.isAbsolute(directory || "")) throw new TypeError("An OpenCode terminal requires a conversation and absolute directory.");
+      return ["attach", baseUrl, "--dir", directory, "--session", conversationId, "--pure"];
+    }
+    return Object.freeze({
+      client,
+      executionId: native.id,
+      privateRoot,
+      pid: native.pid,
+      port: selectedPort,
+      environment,
+      health: Object.freeze({ ...health }),
+      modelProviderIds: Object.freeze([...authenticated]),
+      readLogs: processHandle.readLogs,
+      stop,
       // Resolves when the process exits without being stopped.
       unexpectedExit: unexpectedExit.promise,
-      attachArguments({ conversationId, directory }) {
-        if (!conversationId || !path.isAbsolute(directory || "")) throw new TypeError("An OpenCode terminal requires a conversation and absolute directory.");
-        return ["attach", baseUrl, "--dir", directory, "--session", conversationId, "--pure"];
-      }
+      attachArguments
     });
   } catch (error) {
     error.code ||= "assistant_opencode_start_failed";
     executionId ||= error.executionId;
     error.executionId = executionId;
     if (!native && executionId) {
-      try { await onStarted?.(executionId); }
+      try { await onStarted(executionId); }
       catch (bindingError) { error.bindingError = bindingError; }
     }
     try { error.details = processHandle.readLogs(); }
@@ -342,12 +400,10 @@ export async function createOpenCodeServerProcess({
 }
 
 function openCodeZenCatalogError(cause = null) {
-  const error = new Error("OpenCode Zen's current model list could not be read. Try again.", {
-    cause
+  const error = new AppError(503, "OpenCode Zen's current model list could not be read. Try again.", {
+    cause, code: "assistant_opencode_zen_catalog_unavailable"
   });
-  error.code = "assistant_opencode_zen_catalog_unavailable";
   error.retryable = true;
-  error.statusCode = 503;
   return error;
 }
 
@@ -374,7 +430,7 @@ export async function readOpenCodeZenModelIds({
     if (!Array.isArray(payload?.data) || payload.data.length === 0) {
       throw new Error("OpenCode Zen returned an empty model list.");
     }
-    const ids = payload.data.map((model) => text(model?.id));
+    const ids = payload.data.map((model) => normalizeNullableText(model?.id));
     const uniqueIds = new Set(ids);
     if (ids.some((id) => !id) || uniqueIds.size !== ids.length) {
       throw new Error("OpenCode Zen returned an invalid model list.");
@@ -398,9 +454,9 @@ export async function readOpenCodeCatalog({
   privateRoot = "",
   workdir = ""
 } = {}) {
-  const normalizedPrivateRoot = path.resolve(text(privateRoot));
-  const normalizedWorkdir = path.resolve(text(workdir));
-  if (!text(privateRoot) || !text(workdir)) {
+  const normalizedPrivateRoot = path.resolve(normalizeNullableText(privateRoot));
+  const normalizedWorkdir = path.resolve(normalizeNullableText(workdir));
+  if (!normalizeNullableText(privateRoot) || !normalizeNullableText(workdir)) {
     throw new TypeError("OpenCode catalogue reads require private and working roots.");
   }
   const authRoot = path.join(normalizedPrivateRoot, "data", "opencode");
@@ -454,11 +510,11 @@ export async function verifyOpenCodeApiKey({
   workdir = ""
 } = {}) {
   const key = String(apiKey || "");
-  const providerId = text(modelProviderId);
-  const selectedModelId = text(modelId);
-  const normalizedPrivateRoot = path.resolve(text(privateRoot));
-  const normalizedWorkdir = path.resolve(text(workdir));
-  if (!key || !providerId || !selectedModelId || !text(privateRoot) || !text(workdir)) {
+  const providerId = normalizeNullableText(modelProviderId);
+  const selectedModelId = normalizeNullableText(modelId);
+  const normalizedPrivateRoot = path.resolve(normalizeNullableText(privateRoot));
+  const normalizedWorkdir = path.resolve(normalizeNullableText(workdir));
+  if (!key || !providerId || !selectedModelId || !normalizeNullableText(privateRoot) || !normalizeNullableText(workdir)) {
     throw new TypeError("OpenCode API-key verification requires a key, provider, model, and isolated roots.");
   }
   try {
@@ -500,26 +556,26 @@ export async function verifyOpenCodeApiKey({
         timeout: OPENCODE_VERIFY_TIMEOUT_MS
       });
     } catch {
-      const error = new Error("OpenCode API-key verification could not run.");
-      error.code = "assistant_opencode_key_verification_unavailable";
+      const error = new AppError(503, "OpenCode API-key verification could not run.", {
+        code: "assistant_opencode_key_verification_unavailable"
+      });
       error.retryable = true;
-      error.statusCode = 503;
       throw error;
     }
     if (result?.ok !== true) {
       const exitCode = Number(result?.exitCode);
       const unavailable = result?.timedOut === true ||
         result?.retryable === true ||
-        Boolean(text(result?.code)) ||
+        Boolean(normalizeNullableText(result?.code)) ||
         (Number.isSafeInteger(exitCode) && exitCode !== 1);
-      const error = new Error(unavailable
-        ? "OpenCode API-key verification could not run."
-        : "OpenCode rejected the API-key verification request.");
-      error.code = unavailable
-        ? "assistant_opencode_key_verification_unavailable"
-        : "assistant_opencode_key_verification_failed";
+      const error = unavailable
+        ? new AppError(503, "OpenCode API-key verification could not run.", {
+          code: "assistant_opencode_key_verification_unavailable"
+        })
+        : new AppError(422, "OpenCode rejected the API-key verification request.", {
+          code: "assistant_opencode_key_verification_failed"
+        });
       error.retryable = unavailable;
-      error.statusCode = unavailable ? 503 : 422;
       throw error;
     }
     return Object.freeze({ ok: true });