@linzumi/cli 0.0.12-beta → 0.0.14-beta

package/src/channelSession.ts

@@ -90,6 +90,11 @@
   Relationship: Watches descendant listener ports, prompts the authorized
   Kandan listener user for approval, and resolves the approval into a dynamic
   runner forwarding capability before publishing the same-origin preview URL.
+
+- Date: 2026-05-02
+  Spec: plans/2026-05-02-agent-first-zero-to-codex-launch-plan.md
+  Relationship: Closes npm CLI runner parity gaps for attachment-backed
+  Kandan replies, runtime settings updates, and local TUI turn exclusivity.
 */
 import {
   availabilityMessage,
@@ -104,6 +109,8 @@ import {
   type RunnerPayloadContext,
 } from "./channelSessionSupport";
 import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import { type CodexAppServerClient } from "./codexAppServer";
 import {
   codexThreadRuntimeOverrides,
@@ -223,12 +230,14 @@ export type ChannelSessionRuntime = {
   ) => void;
   readonly handleControl: (control: KandanControl) => Promise<JsonObject | undefined>;
   readonly handleKandanReconnect: () => Promise<void>;
+  readonly currentRuntimeSettings: () => LocalCodexRuntimeSettings;
   readonly currentCodexThreadId: () => string | undefined;
   readonly currentKandanThreadId: () => string | undefined;
   readonly close: () => Promise<void>;
 };
 
 export type ChannelSessionRunnerOptions = {
+  readonly kandanUrl?: string | undefined;
   readonly token: string;
   readonly runnerId: string;
   readonly cwd: string;
@@ -294,12 +303,21 @@ type ChannelSessionState = {
   webSearchProgressForwardChain: Promise<void>;
   typingHeartbeat: ReturnType<typeof setInterval> | undefined;
   typingHeartbeatInFlight: boolean;
+  runtimeSettings: LocalCodexRuntimeSettings;
 };
 
 const codexTypingHeartbeatMs = 5_000;
 const defaultStreamFlushIntervalMs = 150;
 const maxForwardedTurnIds = 64;
 
+type LocalCodexRuntimeSettings = {
+  readonly model: string | undefined;
+  readonly reasoningEffort: string | undefined;
+  readonly approvalPolicy: string | undefined;
+  readonly sandbox: string | undefined;
+  readonly fast: boolean | undefined;
+};
+
 type StreamingAssistantOutput = {
   readonly itemKey: string;
   readonly turnId: string | undefined;
@@ -362,7 +380,11 @@ export async function attachChannelSession(
 ): Promise<ChannelSessionRuntime> {
   const session = args.options.channelSession;
   const chatTopic = `chat:${session.workspaceSlug}:${session.channelSlug}`;
-  const state = initialChannelSessionState(0, session.kandanThreadId);
+  const state = initialChannelSessionState(
+    0,
+    session.kandanThreadId,
+    args.options,
+  );
   const joined = await args.kandan.join(chatTopic, { last_seq: 0 }, {
     rejoinPayload: () => ({ last_seq: state.minSeq }),
   });
@@ -413,10 +435,7 @@ export async function attachChannelSession(
       const turnId = codexNotificationTurnId(params);
       const threadId = codexNotificationThreadId(params);
 
-      if (
-        threadId !== undefined &&
-        state.codexThreadId === threadId
-      ) {
+      if (codexNotificationBelongsToSession(state, threadId, turnId)) {
         const processingReason = processingReasonForCodexNotification(method, params);
         if (turnId !== undefined && processingReason !== undefined) {
           void refreshActiveProcessingState(args, state, turnId, processingReason).catch(error => {
@@ -504,6 +523,7 @@ export async function attachChannelSession(
       }
     },
     handleControl: control => handleChannelSessionControl(args, state, payloadContext, control),
+    currentRuntimeSettings: () => state.runtimeSettings,
     currentCodexThreadId: () => state.codexThreadId,
     currentKandanThreadId: () => state.kandanThreadId,
     handleKandanReconnect: async () => {
@@ -519,6 +539,7 @@ export async function attachChannelSession(
       await bindCurrentCodexThread(args, state);
       if (state.kandanThreadId !== undefined && state.turn.status !== "idle") {
         startCodexTypingHeartbeat(args, state, state.kandanThreadId);
+        await refreshActiveProcessingHeartbeat(args, state);
       }
       await drainKandanMessageQueue(args, state, payloadContext);
     },
@@ -554,6 +575,7 @@ async function bindCurrentCodexThread(
 function initialChannelSessionState(
   cursor: number,
   kandanThreadId: string | undefined,
+  options: ChannelSessionRunnerOptions,
 ): ChannelSessionState {
   return {
     rootSeq: undefined,
@@ -591,6 +613,7 @@ function initialChannelSessionState(
     webSearchProgressForwardChain: Promise.resolve(),
     typingHeartbeat: undefined,
     typingHeartbeatInFlight: false,
+    runtimeSettings: runtimeSettingsFromOptions(options),
   };
 }
 
@@ -679,6 +702,10 @@ async function handleChannelSessionControl(
   payloadContext: RunnerPayloadContext,
   control: KandanControl,
 ): Promise<JsonObject | undefined> {
+  if (control.type === "update_session_settings") {
+    return updateSessionSettings(args, state, control);
+  }
+
   if (control.type === "resolve_codex_approval_request") {
     return resolvePendingCodexApprovalRequest(args, state, control);
   }
@@ -753,6 +780,43 @@ async function handleChannelSessionControl(
   };
 }
 
+function updateSessionSettings(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  control: Extract<KandanControl, { readonly type: "update_session_settings" }>,
+): JsonObject {
+  if (
+    state.codexThreadId === undefined ||
+    control.threadId !== state.codexThreadId
+  ) {
+    return { instanceId: args.instanceId, ok: false, error: "thread_not_bound" };
+  }
+
+  state.runtimeSettings = mergeRuntimeSettings(state.runtimeSettings, control);
+  void publishRuntimeSettings(args, state).catch(error => {
+    args.log("kandan.session_settings_publish_failed", {
+      message: error instanceof Error ? error.message : String(error),
+    });
+  });
+  args.log("codex.session_settings_updated", {
+    model: state.runtimeSettings.model ?? null,
+    reasoning_effort: state.runtimeSettings.reasoningEffort ?? null,
+    approval_policy: state.runtimeSettings.approvalPolicy ?? null,
+    sandbox: state.runtimeSettings.sandbox ?? null,
+    fast: state.runtimeSettings.fast ?? null,
+  });
+
+  return {
+    instanceId: args.instanceId,
+    ok: true,
+    model: state.runtimeSettings.model ?? null,
+    reasoningEffort: state.runtimeSettings.reasoningEffort ?? null,
+    approvalPolicy: state.runtimeSettings.approvalPolicy ?? null,
+    sandbox: state.runtimeSettings.sandbox ?? null,
+    fast: state.runtimeSettings.fast ?? null,
+  };
+}
+
 async function resolvePendingCodexApprovalRequest(
   args: ChannelSessionContext,
   state: ChannelSessionState,
@@ -1136,7 +1200,7 @@ async function handleKandanChatEvent(
   if (
     event.type !== "thread.message" ||
     event.threadId === undefined ||
-    event.body.trim() === ""
+    (event.body.trim() === "" && event.attachments.length === 0)
   ) {
     args.log("kandan.message_ignored", {
       seq: event.seq,
@@ -1248,6 +1312,7 @@ async function handleKandanChatEvent(
     actorSlug: event.actorSlug,
     actorUserId: event.actorUserId,
     body: event.body,
+    attachments: event.attachments,
   });
   args.log("kandan.message_queued", {
     seq: event.seq,
@@ -1357,7 +1422,11 @@ async function drainKandanMessageQueue(
   state: ChannelSessionState,
   payloadContext: RunnerPayloadContext,
 ): Promise<void> {
-  if (state.closed || state.turn.status !== "idle") {
+  if (
+    state.closed ||
+    state.turn.status !== "idle" ||
+    localTuiTurnIsActive(state)
+  ) {
     return;
   }
 
@@ -1394,8 +1463,8 @@ async function drainKandanMessageQueue(
 
     const started = await args.codex.request("turn/start", {
       threadId: codexThreadId,
-      input: [{ type: "text", text: codexInputForQueuedKandanMessage(next) }],
-      ...codexTurnRuntimeOverrides(args.options),
+      input: await codexInputItemsForQueuedKandanMessage(args, next),
+      ...codexTurnRuntimeOverrides(runtimeOptionsForSettings(args.options, state.runtimeSettings)),
     });
     const turnId = extractTurnIdFromResponse(started);
     const interruptAfterStart =
@@ -1478,7 +1547,7 @@ async function handleCodexServerRequest(
   const params = objectValue(request.params) ?? {};
   const turnId = stringValue(params.turnId);
 
-  if (codexApprovalRequestCanAutoAccept(args.options, request.method)) {
+  if (codexApprovalRequestCanAutoAccept(state.runtimeSettings, request.method)) {
     args.log("codex.server_request_auto_accepted", {
       method: request.method,
       turn_id: turnId ?? null,
@@ -1509,11 +1578,11 @@ async function handleCodexServerRequest(
 }
 
 function codexApprovalRequestCanAutoAccept(
-  options: ChannelSessionRunnerOptions,
+  settings: LocalCodexRuntimeSettings,
   method: string,
 ): boolean {
   return (
-    options.channelSession.approvalPolicy === "never" &&
+    settings.approvalPolicy === "never" &&
     (
       method === "item/commandExecution/requestApproval" ||
       method === "item/fileChange/requestApproval"
@@ -1624,7 +1693,6 @@ async function forwardCompletedCodexTurn(
   forgetRetryableTurnId(state, turnId);
 
   try {
-    const session = args.options.channelSession;
     const read = await args.codex.request("thread/read", {
       threadId: state.codexThreadId,
       includeTurns: true,
@@ -1702,24 +1770,11 @@ async function forwardCompletedCodexTurn(
 
       switch (streamed.status) {
         case "none":
-          await pushOk(args.kandan, args.topic, "session:post_thread_message", {
-            workspace: session.workspaceSlug,
-            channel: session.channelSlug,
-            thread_id: state.kandanThreadId,
-            body: message.body,
-            payload: {
-              ...localRunnerPayload(
-                args.options,
-                args.instanceId,
-                "codex_output",
-                state.codexThreadId,
-                payloadContext,
-                sourceMessageSeq,
-              ),
-              ...(rootSeq === undefined ? {} : { reply_to_seq: rootSeq }),
-              structured: message.structured,
-            },
-            client_message_id: `local-codex-${args.instanceId}-${turnId}-${message.itemKey}`,
+          await streamCompletedCodexOutput(args, state, payloadContext, {
+            turnId,
+            sourceMessageSeq,
+            rootSeq,
+            message,
           });
           break;
         case "matched":
@@ -1788,6 +1843,7 @@ async function forwardCompletedCodexTurn(
     }
     if (completingLocalTuiTurn && !completingActiveTurn) {
       await stopCodexTyping(args, state);
+      await drainKandanMessageQueue(args, state, payloadContext);
     }
   }
 }
@@ -2675,6 +2731,80 @@ function commandOutputBody(command: string, output: string): string {
   return [`$ ${command}`, output].filter(part => part.trim() !== "").join("\n\n");
 }
 
+async function streamCompletedCodexOutput(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  payloadContext: RunnerPayloadContext,
+  params: {
+    readonly turnId: string;
+    readonly sourceMessageSeq: number | undefined;
+    readonly rootSeq: number | undefined;
+    readonly message: {
+      readonly itemKey: string;
+      readonly body: string;
+      readonly structured: JsonObject;
+    };
+  },
+): Promise<void> {
+  if (state.kandanThreadId === undefined || state.codexThreadId === undefined) {
+    return;
+  }
+
+  const session = args.options.channelSession;
+  const streamKey = streamingClientMessageId(args.instanceId, {
+    itemKey: params.message.itemKey,
+    turnId: params.turnId,
+  });
+  const streamMetadata: JsonObject = {
+    turn_id: params.turnId,
+    stream_key: streamKey,
+  };
+  const structured = structuredWithStreamKey(params.message.structured, streamKey);
+  const uploadedFileIds = await uploadedFileIdsForCodexOutput(
+    args,
+    params.message.body,
+    structured,
+  );
+
+  await pushOk(args.kandan, args.topic, "session:stream_thread_message", {
+    workspace: session.workspaceSlug,
+    channel: session.channelSlug,
+    thread_id: state.kandanThreadId,
+    stream_key: streamKey,
+    body: params.message.body,
+    payload: {
+      ...localRunnerPayload(
+        args.options,
+        args.instanceId,
+        "codex_output",
+        state.codexThreadId,
+        payloadContext,
+        params.sourceMessageSeq,
+        streamMetadata,
+      ),
+      ...(params.rootSeq === undefined ? {} : { reply_to_seq: params.rootSeq }),
+      ...(params.sourceMessageSeq === undefined
+        ? {}
+        : { source_message_seq: params.sourceMessageSeq }),
+      ...streamMetadata,
+      structured,
+    },
+    ...(uploadedFileIds.length === 0
+      ? {}
+      : { uploaded_file_ids: uploadedFileIds }),
+    client_message_id: streamKey,
+  });
+}
+
+function structuredWithStreamKey(
+  structured: JsonObject,
+  streamKey: string | undefined,
+): JsonObject {
+  return streamKey === undefined
+    ? structured
+    : { ...structured, stream_key: streamKey };
+}
+
 async function editStreamedCodexOutput(
   args: ChannelSessionContext,
   state: ChannelSessionState,
@@ -3120,6 +3250,22 @@ function codexNotificationThreadId(params: JsonObject): string | undefined {
   );
 }
 
+function codexNotificationBelongsToSession(
+  state: ChannelSessionState,
+  threadId: string | undefined,
+  turnId: string | undefined,
+): boolean {
+  if (threadId !== undefined) {
+    return state.codexThreadId === threadId;
+  }
+
+  if (turnId === undefined) {
+    return false;
+  }
+
+  return activeTurnId(state.turn) === turnId || isLocalTuiTurn(state, turnId);
+}
+
 function rememberLocalTuiTurnIfNeeded(
   args: ChannelSessionContext,
   state: ChannelSessionState,
@@ -3145,6 +3291,10 @@ function isLocalTuiTurn(state: ChannelSessionState, turnId: string): boolean {
   return state.localTuiTurnIds.has(turnId);
 }
 
+function localTuiTurnIsActive(state: ChannelSessionState): boolean {
+  return state.localTuiTurnIds.size > 0;
+}
+
 function ensureKandanThreadForLocalTuiTurn(
   state: ChannelSessionState,
 ): void {
@@ -3630,6 +3780,441 @@ function clearActiveProcessingState(state: ChannelSessionState, seq: number): vo
   }
 }
 
+type DownloadedKandanAttachment = {
+  readonly fileName: string;
+  readonly contentType: string | undefined;
+  readonly sizeBytes: number | undefined;
+  readonly path: string;
+  readonly isImage: boolean;
+};
+
+async function codexInputItemsForQueuedKandanMessage(
+  args: ChannelSessionContext,
+  message: QueuedKandanMessage,
+): Promise<JsonObject[]> {
+  const attachments = await downloadQueuedKandanAttachments(args, message);
+  const text = appendDownloadedAttachmentContext(
+    codexInputForQueuedKandanMessage(message),
+    attachments,
+  );
+  const imageItems = attachments.flatMap(attachment =>
+    attachment.isImage ? [{ type: "localImage", path: attachment.path }] : [],
+  );
+
+  return [{ type: "text", text }, ...imageItems];
+}
+
+async function downloadQueuedKandanAttachments(
+  args: ChannelSessionContext,
+  message: QueuedKandanMessage,
+): Promise<DownloadedKandanAttachment[]> {
+  if (message.attachments.length === 0) {
+    return [];
+  }
+
+  const directory = join(
+    args.options.cwd,
+    ".kandan",
+    "local-codex-attachments",
+    `message-${message.seq}`,
+  );
+  await mkdir(directory, { recursive: true });
+
+  const downloaded: DownloadedKandanAttachment[] = [];
+
+  for (const [index, attachment] of message.attachments.entries()) {
+    const url = attachment.url;
+
+    if (url === undefined) {
+      throw new Error(
+        `attachment ${index + 1} for message ${message.seq} is missing a URL`,
+      );
+    }
+
+    const fileName = safeAttachmentFileName(
+      attachment.fileName ?? attachment.id ?? `attachment-${index + 1}`,
+      index,
+    );
+    const localPath = join(directory, fileName);
+    const response = await fetch(resolveKandanAttachmentUrl(args.options.kandanUrl, url), {
+      headers: {
+        authorization: `Bearer ${args.options.token}`,
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `attachment ${fileName} download failed: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    const bytes = Buffer.from(await response.arrayBuffer());
+    await writeFile(localPath, bytes);
+
+    downloaded.push({
+      fileName,
+      contentType: attachment.contentType,
+      sizeBytes: attachment.sizeBytes ?? bytes.byteLength,
+      path: localPath,
+      isImage: isImageAttachment(attachment.contentType, attachment.kind),
+    });
+  }
+
+  return downloaded;
+}
+
+function appendDownloadedAttachmentContext(
+  input: string,
+  attachments: readonly DownloadedKandanAttachment[],
+): string {
+  if (input.trimStart().startsWith("!")) {
+    return input;
+  }
+
+  const attachmentContext =
+    attachments.length === 0
+      ? []
+      : [
+          "",
+          "Kandan attachments downloaded for this message:",
+          ...attachments.map(attachment => {
+            const details = [
+              attachment.contentType,
+              attachment.sizeBytes === undefined
+                ? undefined
+                : `${attachment.sizeBytes} bytes`,
+            ].flatMap(value => (value === undefined ? [] : [value]));
+            const suffix = details.length === 0 ? "" : ` (${details.join(", ")})`;
+
+            return `- ${attachment.fileName}${suffix}: ${attachment.path}`;
+          }),
+        ];
+
+  return [
+    input,
+    ...attachmentContext,
+    "",
+    "If you create files that should be attached back to Kandan, end your assistant response with:",
+    "Kandan attachments:",
+    "- relative/or/absolute/path/to/file",
+  ].join("\n");
+}
+
+function resolveKandanAttachmentUrl(
+  kandanUrl: string | undefined,
+  url: string,
+): string {
+  const absolute = tryAbsoluteUrl(url);
+
+  if (absolute !== undefined) {
+    return absolute;
+  }
+
+  if (kandanUrl === undefined) {
+    throw new Error(
+      `relative attachment URL cannot be resolved without Kandan URL: ${url}`,
+    );
+  }
+
+  const httpBase = kandanUrl
+    .replace(/^wss:\/\//, "https://")
+    .replace(/^ws:\/\//, "http://");
+
+  return new URL(url, httpBase).toString();
+}
+
+function tryAbsoluteUrl(url: string): string | undefined {
+  try {
+    return new URL(url).toString();
+  } catch (_error) {
+    return undefined;
+  }
+}
+
+function safeAttachmentFileName(fileName: string, index: number): string {
+  const normalized = basename(fileName)
+    .replaceAll(/[^\w.\- ]/g, "_")
+    .trim();
+  const safeName =
+    normalized === "" || normalized === "." || normalized === ".."
+      ? `attachment-${index + 1}`
+      : normalized;
+
+  return `${index + 1}-${safeName}`;
+}
+
+function isImageAttachment(
+  contentType: string | undefined,
+  kind: string | undefined,
+): boolean {
+  if (
+    contentType !== undefined &&
+    contentType.toLowerCase().startsWith("image/")
+  ) {
+    return true;
+  }
+
+  return kind?.toLowerCase() === "image";
+}
+
+async function uploadedFileIdsForCodexOutput(
+  args: ChannelSessionContext,
+  body: string,
+  structured: JsonObject,
+): Promise<string[]> {
+  if (stringValue(structured.kind) !== "codex_assistant_message") {
+    return [];
+  }
+
+  const paths = extractKandanAttachmentPaths(body, args.options.cwd);
+
+  if (paths.length === 0) {
+    return [];
+  }
+
+  const files = await Promise.all(
+    paths.map(async path => {
+      const info = await stat(path);
+
+      if (!info.isFile()) {
+        throw new Error(`Kandan attachment path is not a file: ${path}`);
+      }
+
+      return {
+        path,
+        fileName: basename(path),
+        contentType: contentTypeForFileName(path),
+        sizeBytes: info.size,
+      };
+    }),
+  );
+  const session = args.options.channelSession;
+  const prepare = await pushOk(args.kandan, args.topic, "session:prepare_message_uploads", {
+    workspace: session.workspaceSlug,
+    channel: session.channelSlug,
+    files: files.map(file => ({
+      file_name: file.fileName,
+      content_type: file.contentType,
+      size_bytes: file.sizeBytes,
+    })),
+  });
+  const uploads = arrayValue(prepare.uploads) ?? [];
+
+  if (uploads.length !== files.length) {
+    throw new Error("Kandan attachment prepare response count mismatch");
+  }
+
+  await Promise.all(
+    files.map(async (file, index) => {
+      const upload = objectValue(uploads[index]);
+      const uploadUrl = stringValue(upload?.upload_url);
+      const uploadMethod = stringValue(upload?.upload_method) ?? "PUT";
+
+      if (uploadUrl === undefined) {
+        throw new Error("Kandan attachment prepare response missing upload_url");
+      }
+
+      const bytes = await readFile(file.path);
+      const response = await fetch(
+        resolveKandanAttachmentUrl(args.options.kandanUrl, uploadUrl),
+        {
+          method: uploadMethod,
+          headers: { "content-type": file.contentType },
+          body: bytes,
+        },
+      );
+
+      if (!response.ok) {
+        throw new Error(
+          `Kandan attachment upload failed for ${file.fileName}: ${response.status} ${response.statusText}`,
+        );
+      }
+    }),
+  );
+
+  return uploads.map(upload => {
+    const fileId = stringValue(objectValue(upload)?.file_id);
+
+    if (fileId === undefined) {
+      throw new Error("Kandan attachment prepare response missing file_id");
+    }
+
+    return fileId;
+  });
+}
+
+function extractKandanAttachmentPaths(body: string, cwd: string): string[] {
+  const lines = body.split(/\r?\n/);
+  const headingIndex = lines.findIndex(
+    line => line.trim().toLowerCase() === "kandan attachments:",
+  );
+
+  if (headingIndex === -1) {
+    return [];
+  }
+
+  const seen = new Set<string>();
+  return lines.slice(headingIndex + 1).flatMap(line => {
+    const trimmed = line.trim();
+
+    if (!trimmed.startsWith("- ")) {
+      return [];
+    }
+
+    const rawPath = trimmed.slice(2).trim().replace(/^`|`$/g, "");
+    const resolvedPath = resolveCodexAttachmentPath(cwd, rawPath);
+
+    if (seen.has(resolvedPath)) {
+      return [];
+    }
+
+    seen.add(resolvedPath);
+    return [resolvedPath];
+  });
+}
+
+function resolveCodexAttachmentPath(cwd: string, rawPath: string): string {
+  if (rawPath === "") {
+    throw new Error("Kandan attachment path must not be empty");
+  }
+
+  const cwdPath = resolve(cwd);
+  const path = isAbsolute(rawPath) ? resolve(rawPath) : resolve(cwdPath, rawPath);
+  const relativePath = relative(cwdPath, path);
+
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(
+      `Kandan attachment path must be inside the runner cwd: ${rawPath}`,
+    );
+  }
+
+  return path;
+}
+
+function contentTypeForFileName(fileName: string): string {
+  const lower = fileName.toLowerCase();
+
+  if (lower.endsWith(".png")) {
+    return "image/png";
+  }
+
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) {
+    return "image/jpeg";
+  }
+
+  if (lower.endsWith(".gif")) {
+    return "image/gif";
+  }
+
+  if (lower.endsWith(".webp")) {
+    return "image/webp";
+  }
+
+  if (lower.endsWith(".csv")) {
+    return "text/csv";
+  }
+
+  if (lower.endsWith(".json")) {
+    return "application/json";
+  }
+
+  if (
+    lower.endsWith(".md") ||
+    lower.endsWith(".txt") ||
+    lower.endsWith(".log")
+  ) {
+    return "text/plain";
+  }
+
+  return "application/octet-stream";
+}
+
+function runtimeSettingsFromOptions(
+  options: ChannelSessionRunnerOptions,
+): LocalCodexRuntimeSettings {
+  return {
+    model: options.channelSession.model,
+    reasoningEffort: options.channelSession.reasoningEffort,
+    approvalPolicy: options.channelSession.approvalPolicy,
+    sandbox: options.channelSession.sandbox,
+    fast: options.fast,
+  };
+}
+
+function mergeRuntimeSettings(
+  current: LocalCodexRuntimeSettings,
+  update: Extract<KandanControl, { readonly type: "update_session_settings" }>,
+): LocalCodexRuntimeSettings {
+  return {
+    model: mergeOptionalStringRuntimeSetting(current.model, update, "model"),
+    reasoningEffort: mergeOptionalStringRuntimeSetting(
+      current.reasoningEffort,
+      update,
+      "reasoningEffort",
+    ),
+    approvalPolicy: mergeOptionalStringRuntimeSetting(
+      current.approvalPolicy,
+      update,
+      "approvalPolicy",
+    ),
+    sandbox: mergeOptionalStringRuntimeSetting(current.sandbox, update, "sandbox"),
+    fast: update.fast ?? current.fast,
+  };
+}
+
+function mergeOptionalStringRuntimeSetting(
+  current: string | undefined,
+  update: Extract<KandanControl, { readonly type: "update_session_settings" }>,
+  key: "model" | "reasoningEffort" | "approvalPolicy" | "sandbox",
+): string | undefined {
+  if (Object.prototype.hasOwnProperty.call(update, key)) {
+    return update[key] ?? undefined;
+  }
+
+  return current;
+}
+
+function runtimeOptionsForSettings(
+  options: ChannelSessionRunnerOptions,
+  settings: LocalCodexRuntimeSettings,
+): ChannelSessionRunnerOptions {
+  return {
+    ...options,
+    fast: settings.fast,
+    channelSession: {
+      ...options.channelSession,
+      model: settings.model,
+      reasoningEffort: settings.reasoningEffort,
+      approvalPolicy: settings.approvalPolicy,
+      sandbox: settings.sandbox,
+    },
+  };
+}
+
+async function publishRuntimeSettings(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+): Promise<void> {
+  const session = args.options.channelSession;
+
+  if (state.kandanThreadId === undefined || state.codexThreadId === undefined) {
+    throw new Error("cannot publish local Codex settings before thread binding");
+  }
+
+  await pushOk(args.kandan, args.topic, "session:settings", {
+    workspace: session.workspaceSlug,
+    channel: session.channelSlug,
+    thread_id: state.kandanThreadId,
+    codex_thread_id: state.codexThreadId,
+    model: state.runtimeSettings.model ?? null,
+    reasoningEffort: state.runtimeSettings.reasoningEffort ?? null,
+    approvalPolicy: state.runtimeSettings.approvalPolicy ?? null,
+    sandbox: state.runtimeSettings.sandbox ?? null,
+    fast: state.runtimeSettings.fast ?? null,
+    updated_at: new Date().toISOString(),
+  });
+}
+
 
 function extractThreadIdFromResponse(response: JsonRpcResponse): string {
   if ("error" in response) {