@openclaw/codex 2026.5.2 → 2026.5.3-beta.2

package/src/conversation-control.ts

@@ -1,255 +0,0 @@
-import { CODEX_CONTROL_METHODS } from "./app-server/capabilities.js";
-import {
-  resolveCodexAppServerRuntimeOptions,
-  type CodexAppServerApprovalPolicy,
-  type CodexAppServerSandboxMode,
-} from "./app-server/config.js";
-import type { CodexServiceTier, CodexThreadResumeResponse } from "./app-server/protocol.js";
-import {
-  readCodexAppServerBinding,
-  writeCodexAppServerBinding,
-} from "./app-server/session-binding.js";
-import { getSharedCodexAppServerClient } from "./app-server/shared-client.js";
-
-type ActiveTurn = {
-  sessionFile: string;
-  threadId: string;
-  turnId: string;
-};
-
-type PermissionsMode = "default" | "yolo";
-
-const CODEX_CONVERSATION_CONTROL_STATE = Symbol.for("openclaw.codex.conversationControl");
-
-function getActiveTurns(): Map<string, ActiveTurn> {
-  const globalState = globalThis as typeof globalThis & {
-    [CODEX_CONVERSATION_CONTROL_STATE]?: Map<string, ActiveTurn>;
-  };
-  globalState[CODEX_CONVERSATION_CONTROL_STATE] ??= new Map();
-  return globalState[CODEX_CONVERSATION_CONTROL_STATE];
-}
-
-export function trackCodexConversationActiveTurn(active: ActiveTurn): () => void {
-  const activeTurns = getActiveTurns();
-  activeTurns.set(active.sessionFile, active);
-  return () => {
-    const current = activeTurns.get(active.sessionFile);
-    if (current?.turnId === active.turnId) {
-      activeTurns.delete(active.sessionFile);
-    }
-  };
-}
-
-export function readCodexConversationActiveTurn(sessionFile: string): ActiveTurn | undefined {
-  return getActiveTurns().get(sessionFile);
-}
-
-export async function stopCodexConversationTurn(params: {
-  sessionFile: string;
-  pluginConfig?: unknown;
-}): Promise<{ stopped: boolean; message: string }> {
-  const active = readCodexConversationActiveTurn(params.sessionFile);
-  if (!active) {
-    return { stopped: false, message: "No active Codex run to stop." };
-  }
-  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
-  const binding = await readCodexAppServerBinding(params.sessionFile);
-  const client = await getSharedCodexAppServerClient({
-    startOptions: runtime.start,
-    timeoutMs: runtime.requestTimeoutMs,
-    authProfileId: binding?.authProfileId,
-  });
-  await client.request(
-    "turn/interrupt",
-    {
-      threadId: active.threadId,
-      turnId: active.turnId,
-    },
-    { timeoutMs: runtime.requestTimeoutMs },
-  );
-  return { stopped: true, message: "Codex stop requested." };
-}
-
-export async function steerCodexConversationTurn(params: {
-  sessionFile: string;
-  message: string;
-  pluginConfig?: unknown;
-}): Promise<{ steered: boolean; message: string }> {
-  const active = readCodexConversationActiveTurn(params.sessionFile);
-  const text = params.message.trim();
-  if (!text) {
-    return { steered: false, message: "Usage: /codex steer <message>" };
-  }
-  if (!active) {
-    return { steered: false, message: "No active Codex run to steer." };
-  }
-  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
-  const binding = await readCodexAppServerBinding(params.sessionFile);
-  const client = await getSharedCodexAppServerClient({
-    startOptions: runtime.start,
-    timeoutMs: runtime.requestTimeoutMs,
-    authProfileId: binding?.authProfileId,
-  });
-  await client.request(
-    "turn/steer",
-    {
-      threadId: active.threadId,
-      expectedTurnId: active.turnId,
-      input: [{ type: "text", text, text_elements: [] }],
-    },
-    { timeoutMs: runtime.requestTimeoutMs },
-  );
-  return { steered: true, message: "Sent steer message to Codex." };
-}
-
-export async function setCodexConversationModel(params: {
-  sessionFile: string;
-  model: string;
-  pluginConfig?: unknown;
-}): Promise<string> {
-  const model = params.model.trim();
-  if (!model) {
-    return "Usage: /codex model <model>";
-  }
-  const binding = await requireThreadBinding(params.sessionFile);
-  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
-  const response = await resumeThreadWithOverrides({
-    pluginConfig: params.pluginConfig,
-    threadId: binding.threadId,
-    authProfileId: binding.authProfileId,
-    model,
-  });
-  await writeCodexAppServerBinding(params.sessionFile, {
-    ...binding,
-    cwd: response.thread.cwd ?? binding.cwd,
-    model: response.model ?? model,
-    modelProvider: response.modelProvider ?? binding.modelProvider,
-    approvalPolicy: binding.approvalPolicy,
-    sandbox: binding.sandbox,
-    serviceTier: binding.serviceTier ?? runtime.serviceTier,
-  });
-  return `Codex model set to ${response.model ?? model}.`;
-}
-
-export async function setCodexConversationFastMode(params: {
-  sessionFile: string;
-  enabled?: boolean;
-  pluginConfig?: unknown;
-}): Promise<string> {
-  const binding = await requireThreadBinding(params.sessionFile);
-  if (params.enabled == null) {
-    return `Codex fast mode: ${binding.serviceTier === "fast" ? "on" : "off"}.`;
-  }
-  const serviceTier: CodexServiceTier = params.enabled ? "fast" : "flex";
-  // Fast mode is sent on each later turn; do not require Codex to accept an
-  // immediate thread/resume control request just to persist the preference.
-  await writeCodexAppServerBinding(params.sessionFile, {
-    ...binding,
-    serviceTier,
-  });
-  return `Codex fast mode ${params.enabled ? "enabled" : "disabled"}.`;
-}
-
-export async function setCodexConversationPermissions(params: {
-  sessionFile: string;
-  mode?: PermissionsMode;
-  pluginConfig?: unknown;
-}): Promise<string> {
-  const binding = await requireThreadBinding(params.sessionFile);
-  if (!params.mode) {
-    return `Codex permissions: ${formatPermissionsMode(binding)}.`;
-  }
-  const policy = permissionsForMode(params.mode);
-  // Native bound turns pass these settings at turn/start time, so this command
-  // can update the local binding even when app-server resume overrides fail.
-  await writeCodexAppServerBinding(params.sessionFile, {
-    ...binding,
-    approvalPolicy: policy.approvalPolicy,
-    sandbox: policy.sandbox,
-  });
-  return `Codex permissions set to ${params.mode === "yolo" ? "full access" : "default"}.`;
-}
-
-export function parseCodexFastModeArg(arg: string | undefined): boolean | undefined {
-  const normalized = arg?.trim().toLowerCase();
-  if (!normalized || normalized === "status") {
-    return undefined;
-  }
-  if (normalized === "on" || normalized === "true" || normalized === "fast") {
-    return true;
-  }
-  if (normalized === "off" || normalized === "false" || normalized === "flex") {
-    return false;
-  }
-  return undefined;
-}
-
-export function parseCodexPermissionsModeArg(arg: string | undefined): PermissionsMode | undefined {
-  const normalized = arg?.trim().toLowerCase();
-  if (!normalized || normalized === "status") {
-    return undefined;
-  }
-  if (normalized === "yolo" || normalized === "full" || normalized === "full-access") {
-    return "yolo";
-  }
-  if (normalized === "default" || normalized === "guardian") {
-    return "default";
-  }
-  return undefined;
-}
-
-export function formatPermissionsMode(binding: {
-  approvalPolicy?: CodexAppServerApprovalPolicy;
-  sandbox?: CodexAppServerSandboxMode;
-}): string {
-  return binding.approvalPolicy === "never" && binding.sandbox === "danger-full-access"
-    ? "full access"
-    : "default";
-}
-
-async function requireThreadBinding(sessionFile: string) {
-  const binding = await readCodexAppServerBinding(sessionFile);
-  if (!binding?.threadId) {
-    throw new Error("No Codex thread is attached to this OpenClaw session yet.");
-  }
-  return binding;
-}
-
-async function resumeThreadWithOverrides(params: {
-  pluginConfig?: unknown;
-  threadId: string;
-  authProfileId?: string;
-  model?: string;
-  approvalPolicy?: CodexAppServerApprovalPolicy;
-  sandbox?: CodexAppServerSandboxMode;
-  serviceTier?: CodexServiceTier;
-}): Promise<CodexThreadResumeResponse> {
-  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
-  const client = await getSharedCodexAppServerClient({
-    startOptions: runtime.start,
-    timeoutMs: runtime.requestTimeoutMs,
-    authProfileId: params.authProfileId,
-  });
-  return await client.request(
-    CODEX_CONTROL_METHODS.resumeThread,
-    {
-      threadId: params.threadId,
-      ...(params.model ? { model: params.model } : {}),
-      approvalPolicy: params.approvalPolicy ?? runtime.approvalPolicy,
-      sandbox: params.sandbox ?? runtime.sandbox,
-      approvalsReviewer: runtime.approvalsReviewer,
-      ...(params.serviceTier ? { serviceTier: params.serviceTier } : {}),
-      persistExtendedHistory: true,
-    },
-    { timeoutMs: runtime.requestTimeoutMs },
-  );
-}
-
-function permissionsForMode(mode: PermissionsMode): {
-  approvalPolicy: CodexAppServerApprovalPolicy;
-  sandbox: CodexAppServerSandboxMode;
-} {
-  return mode === "yolo"
-    ? { approvalPolicy: "never", sandbox: "danger-full-access" }
-    : { approvalPolicy: "on-request", sandbox: "workspace-write" };
-}

package/src/conversation-turn-collector.test.ts

@@ -1,154 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { createCodexConversationTurnCollector } from "./conversation-turn-collector.js";
-
-describe("codex conversation turn collector", () => {
-  it("collects streamed assistant deltas for the active turn", async () => {
-    const collector = createCodexConversationTurnCollector("thread-1");
-    collector.setTurnId("turn-1");
-    const completion = collector.wait({ timeoutMs: 1_000 });
-
-    collector.handleNotification({
-      method: "item/agentMessage/delta",
-      params: { threadId: "thread-1", turnId: "turn-1", itemId: "item-1", delta: "hello " },
-    });
-    collector.handleNotification({
-      method: "item/agentMessage/delta",
-      params: { threadId: "thread-1", turnId: "turn-1", itemId: "item-1", delta: "world" },
-    });
-    collector.handleNotification({
-      method: "turn/completed",
-      params: { threadId: "thread-1", turn: { id: "turn-1", status: "completed", items: [] } },
-    });
-
-    await expect(completion).resolves.toEqual({ replyText: "hello world" });
-  });
-
-  it("uses completed agent message items when deltas are absent", async () => {
-    const collector = createCodexConversationTurnCollector("thread-1");
-    collector.setTurnId("turn-1");
-    const completion = collector.wait({ timeoutMs: 1_000 });
-
-    collector.handleNotification({
-      method: "item/completed",
-      params: {
-        threadId: "thread-1",
-        turnId: "turn-1",
-        item: { type: "agentMessage", id: "item-1", text: "final answer" },
-      },
-    });
-    collector.handleNotification({
-      method: "turn/completed",
-      params: { threadId: "thread-1", turn: { id: "turn-1", status: "completed", items: [] } },
-    });
-
-    await expect(completion).resolves.toEqual({ replyText: "final answer" });
-  });
-
-  it("ignores notifications for other threads or turns", async () => {
-    const collector = createCodexConversationTurnCollector("thread-1");
-    collector.setTurnId("turn-1");
-    const completion = collector.wait({ timeoutMs: 1_000 });
-
-    collector.handleNotification({
-      method: "item/agentMessage/delta",
-      params: { threadId: "thread-2", turnId: "turn-1", itemId: "wrong", delta: "wrong" },
-    });
-    collector.handleNotification({
-      method: "item/agentMessage/delta",
-      params: { threadId: "thread-1", turnId: "turn-2", itemId: "wrong", delta: "wrong" },
-    });
-    collector.handleNotification({
-      method: "turn/completed",
-      params: {
-        threadId: "thread-1",
-        turn: {
-          id: "turn-1",
-          status: "completed",
-          items: [{ type: "agentMessage", id: "item-1", text: "right" }],
-        },
-      },
-    });
-
-    await expect(completion).resolves.toEqual({ replyText: "right" });
-  });
-
-  it("ignores unscoped deltas once the active turn is known", async () => {
-    const collector = createCodexConversationTurnCollector("thread-1");
-    collector.setTurnId("turn-1");
-    const completion = collector.wait({ timeoutMs: 1_000 });
-
-    collector.handleNotification({
-      method: "item/agentMessage/delta",
-      params: { threadId: "thread-1", itemId: "wrong", delta: "wrong" },
-    });
-    collector.handleNotification({
-      method: "item/agentMessage/delta",
-      params: { threadId: "thread-1", turnId: "turn-1", itemId: "right", delta: "right" },
-    });
-    collector.handleNotification({
-      method: "turn/completed",
-      params: { threadId: "thread-1", turn: { id: "turn-1", status: "completed", items: [] } },
-    });
-
-    await expect(completion).resolves.toEqual({ replyText: "right" });
-  });
-
-  it("does not complete from unscoped turn completion once the active turn is known", async () => {
-    const collector = createCodexConversationTurnCollector("thread-1");
-    collector.setTurnId("turn-1");
-    const completion = collector.wait({ timeoutMs: 1_000 });
-
-    collector.handleNotification({
-      method: "turn/completed",
-      params: {
-        threadId: "thread-1",
-        turn: {
-          status: "completed",
-          items: [{ type: "agentMessage", id: "wrong", text: "wrong" }],
-        },
-      },
-    });
-    collector.handleNotification({
-      method: "turn/completed",
-      params: {
-        threadId: "thread-1",
-        turn: {
-          id: "turn-1",
-          status: "completed",
-          items: [{ type: "agentMessage", id: "right", text: "right" }],
-        },
-      },
-    });
-
-    await expect(completion).resolves.toEqual({ replyText: "right" });
-  });
-
-  it("rejects failed turns with the app-server error message", async () => {
-    const collector = createCodexConversationTurnCollector("thread-1");
-    collector.setTurnId("turn-1");
-    const completion = collector.wait({ timeoutMs: 1_000 });
-
-    collector.handleNotification({
-      method: "turn/completed",
-      params: {
-        threadId: "thread-1",
-        turn: { id: "turn-1", status: "failed", error: { message: "model exploded" }, items: [] },
-      },
-    });
-
-    await expect(completion).rejects.toThrow("model exploded");
-  });
-
-  it("times out when the app-server never completes the turn", async () => {
-    vi.useFakeTimers();
-    try {
-      const collector = createCodexConversationTurnCollector("thread-1");
-      const completion = collector.wait({ timeoutMs: 100 });
-      const assertion = expect(completion).rejects.toThrow("codex app-server bound turn timed out");
-      await vi.advanceTimersByTimeAsync(100);
-      await assertion;
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});

package/src/conversation-turn-collector.ts

@@ -1,158 +0,0 @@
-import {
-  isJsonObject,
-  type CodexServerNotification,
-  type JsonObject,
-} from "./app-server/protocol.js";
-
-export function createCodexConversationTurnCollector(threadId: string) {
-  let turnId: string | undefined;
-  let completed = false;
-  let failedError: string | undefined;
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  const assistantTextByItem = new Map<string, string>();
-  const assistantOrder: string[] = [];
-  let resolveCompletion: ((value: { replyText: string }) => void) | undefined;
-  let rejectCompletion: ((error: Error) => void) | undefined;
-
-  const rememberItem = (itemId: string) => {
-    if (!assistantOrder.includes(itemId)) {
-      assistantOrder.push(itemId);
-    }
-  };
-  const collectReplyText = (): string => {
-    const texts = assistantOrder
-      .map((itemId) => assistantTextByItem.get(itemId)?.trim())
-      .filter((text): text is string => Boolean(text));
-    return texts.at(-1) ?? "";
-  };
-  const clearWaitState = () => {
-    if (timeout) {
-      clearTimeout(timeout);
-      timeout = undefined;
-    }
-    resolveCompletion = undefined;
-    rejectCompletion = undefined;
-  };
-  const finish = () => {
-    if (completed) {
-      return;
-    }
-    completed = true;
-    if (failedError) {
-      rejectCompletion?.(new Error(failedError));
-    } else {
-      resolveCompletion?.({ replyText: collectReplyText() });
-    }
-    clearWaitState();
-  };
-
-  return {
-    setTurnId(nextTurnId: string) {
-      turnId = nextTurnId;
-    },
-    handleNotification(notification: CodexServerNotification) {
-      const params = isJsonObject(notification.params) ? notification.params : undefined;
-      if (!params || !isNotificationForTurn(params, threadId, turnId)) {
-        return;
-      }
-      if (notification.method === "item/agentMessage/delta") {
-        const itemId = readString(params, "itemId") ?? readString(params, "id") ?? "assistant";
-        const delta = readTextString(params, "delta");
-        if (!delta) {
-          return;
-        }
-        rememberItem(itemId);
-        assistantTextByItem.set(itemId, `${assistantTextByItem.get(itemId) ?? ""}${delta}`);
-        return;
-      }
-      if (notification.method === "item/completed") {
-        const item = isJsonObject(params.item) ? params.item : undefined;
-        if (item?.type === "agentMessage") {
-          const itemId = readString(item, "id") ?? readString(params, "itemId") ?? "assistant";
-          const text = readTextString(item, "text");
-          if (text) {
-            rememberItem(itemId);
-            assistantTextByItem.set(itemId, text);
-          }
-        }
-        return;
-      }
-      if (notification.method === "turn/completed") {
-        const turn = isJsonObject(params.turn) ? params.turn : undefined;
-        const status = readString(turn, "status");
-        if (status === "failed") {
-          failedError =
-            readString(readRecord(turn?.error), "message") ?? "codex app-server turn failed";
-        }
-        const items = Array.isArray(turn?.items) ? turn.items : [];
-        for (const item of items) {
-          if (!isJsonObject(item) || item.type !== "agentMessage") {
-            continue;
-          }
-          const itemId = readString(item, "id") ?? `assistant-${assistantOrder.length + 1}`;
-          const text = readTextString(item, "text");
-          if (text) {
-            rememberItem(itemId);
-            assistantTextByItem.set(itemId, text);
-          }
-        }
-        finish();
-      }
-    },
-    wait(params: { timeoutMs: number }): Promise<{ replyText: string }> {
-      if (completed) {
-        return failedError
-          ? Promise.reject(new Error(failedError))
-          : Promise.resolve({ replyText: collectReplyText() });
-      }
-      return new Promise<{ replyText: string }>((resolve, reject) => {
-        resolveCompletion = resolve;
-        rejectCompletion = reject;
-        timeout = setTimeout(
-          () => {
-            completed = true;
-            reject(new Error("codex app-server bound turn timed out"));
-            clearWaitState();
-          },
-          Math.max(100, params.timeoutMs),
-        );
-        timeout.unref?.();
-      });
-    },
-  };
-}
-
-function isNotificationForTurn(
-  params: JsonObject,
-  threadId: string,
-  turnId: string | undefined,
-): boolean {
-  if (readString(params, "threadId") !== threadId) {
-    return false;
-  }
-  if (!turnId) {
-    return true;
-  }
-  const directTurnId = readString(params, "turnId");
-  if (directTurnId) {
-    return directTurnId === turnId;
-  }
-  const turn = isJsonObject(params.turn) ? params.turn : undefined;
-  return readString(turn, "id") === turnId;
-}
-
-function readRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-}
-
-function readString(record: Record<string, unknown> | JsonObject | undefined, key: string) {
-  const value = record?.[key];
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
-function readTextString(record: Record<string, unknown> | JsonObject | undefined, key: string) {
-  const value = record?.[key];
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}

package/src/conversation-turn-input.test.ts

@@ -1,44 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { buildCodexConversationTurnInput } from "./conversation-turn-input.js";
-
-describe("codex conversation turn input", () => {
-  it("forwards inbound image attachments to Codex app-server", () => {
-    expect(
-      buildCodexConversationTurnInput({
-        prompt: "what is this?",
-        event: {
-          content: "what is this?",
-          channel: "telegram",
-          isGroup: false,
-          metadata: {
-            mediaPaths: ["/tmp/photo.png", "/tmp/readme.txt"],
-            mediaUrls: ["https://example.test/photo.png"],
-            mediaTypes: ["image/png", "text/plain"],
-          },
-        },
-      }),
-    ).toEqual([
-      { type: "text", text: "what is this?", text_elements: [] },
-      { type: "localImage", path: "/tmp/photo.png" },
-    ]);
-  });
-
-  it("uses remote image urls when no local path is available", () => {
-    expect(
-      buildCodexConversationTurnInput({
-        prompt: "look",
-        event: {
-          content: "look",
-          channel: "webchat",
-          isGroup: false,
-          metadata: {
-            mediaUrl: "https://example.test/photo.webp?sig=1",
-          },
-        },
-      }),
-    ).toEqual([
-      { type: "text", text: "look", text_elements: [] },
-      { type: "image", url: "https://example.test/photo.webp?sig=1" },
-    ]);
-  });
-});

package/src/conversation-turn-input.ts

@@ -1,80 +0,0 @@
-import path from "node:path";
-import type { PluginHookInboundClaimEvent } from "openclaw/plugin-sdk/plugin-entry";
-import type { CodexUserInput } from "./app-server/protocol.js";
-
-type InboundMedia = {
-  path?: string;
-  url?: string;
-  mimeType?: string;
-};
-
-const IMAGE_EXTENSIONS = new Set([".avif", ".gif", ".jpeg", ".jpg", ".png", ".webp"]);
-
-export function buildCodexConversationTurnInput(params: {
-  prompt: string;
-  event: PluginHookInboundClaimEvent;
-}): CodexUserInput[] {
-  return [
-    { type: "text", text: params.prompt, text_elements: [] },
-    ...extractInboundMedia(params.event)
-      .map(toCodexImageInput)
-      .filter((item): item is CodexUserInput => item !== undefined),
-  ];
-}
-
-function extractInboundMedia(event: PluginHookInboundClaimEvent): InboundMedia[] {
-  const metadata = event.metadata ?? {};
-  // OpenClaw channels expose either local staged files or remote URLs. Keep
-  // them separate so Codex can receive the cheaper localImage input when a file
-  // is already present, while still supporting remote-only transports.
-  const paths = readStringArray(metadata.mediaPaths).concat(readStringArray(metadata.mediaPath));
-  const urls = readStringArray(metadata.mediaUrls).concat(readStringArray(metadata.mediaUrl));
-  const mimeTypes = readStringArray(metadata.mediaTypes).concat(
-    readStringArray(metadata.mediaType),
-  );
-  const count = Math.max(paths.length, urls.length, mimeTypes.length);
-  const media: InboundMedia[] = [];
-  for (let index = 0; index < count; index += 1) {
-    media.push({
-      path: paths[index],
-      url: urls[index],
-      mimeType: mimeTypes[index] ?? mimeTypes[0],
-    });
-  }
-  return media;
-}
-
-function toCodexImageInput(media: InboundMedia): CodexUserInput | undefined {
-  if (!isImageMedia(media)) {
-    return undefined;
-  }
-  if (media.path) {
-    return { type: "localImage", path: normalizeFileUrl(media.path) };
-  }
-  return media.url ? { type: "image", url: media.url } : undefined;
-}
-
-function isImageMedia(media: InboundMedia): boolean {
-  if (media.mimeType?.toLowerCase().startsWith("image/")) {
-    return true;
-  }
-  const candidate = media.path ?? media.url;
-  if (!candidate) {
-    return false;
-  }
-  return IMAGE_EXTENSIONS.has(path.extname(candidate.split(/[?#]/, 1)[0] ?? "").toLowerCase());
-}
-
-function normalizeFileUrl(value: string): string {
-  return value.startsWith("file://") ? new URL(value).pathname : value;
-}
-
-function readStringArray(value: unknown): string[] {
-  if (typeof value === "string" && value.trim()) {
-    return [value.trim()];
-  }
-  if (!Array.isArray(value)) {
-    return [];
-  }
-  return value.map((entry) => (typeof entry === "string" ? entry.trim() : "")).filter(Boolean);
-}