@syengup/friday-channel-next 0.1.14 → 0.1.15

package/dist/src/channel.js

@@ -138,6 +138,15 @@ export const fridayNextChannelPlugin = createChatChannelPlugin({
             },
             parseExplicitTarget: () => ({ to: "friday-next" }),
             formatTargetDisplay: ({ display }) => display || "Friday Next",
+            // friday-next is a transparent proxy: outbound text/media already reach the app live
+            // via SSE (sendText/sendMedia/handleSend). The OpenClaw core additionally mirrors
+            // message-tool sends into the recipient's session transcript (model:"delivery-mirror").
+            // For friday-next that recipient session falls back to
+            // `agent:<agentId>:friday-next:direct:<deviceId>` — an orphan session unrelated to the
+            // app's real conversation — spawning a phantom session + a stray delivery-mirror message.
+            // The core checks this hook first; returning null short-circuits route resolution so no
+            // orphan session entry and no delivery-mirror are written.
+            resolveOutboundSessionRoute: () => null,
         },
     },
     outbound: {

package/dist/src/http/handlers/messages.js

@@ -13,8 +13,7 @@ import crypto from "node:crypto";
 import { resolveFridayNextConfig } from "../../config.js";
 import { getHostOpenClawConfigSnapshot } from "../../host-config.js";
 import { getFridayNextRuntime } from "../../runtime.js";
-import { getFridayAgentForwardRuntime } from "../../agent-forward-runtime.js";
-import { agentIdFromSessionKey, setSessionSettings, splitModelRef, toSessionStoreKey, } from "../../session/session-manager.js";
+import { resolveAgentDefaults, setSessionSettings, splitModelRef, toSessionStoreKey, } from "../../session/session-manager.js";
 import { sseEmitter } from "../../sse/emitter.js";
 import { extractBearerToken } from "../middleware/auth.js";
 import { readJsonBody } from "../middleware/body.js";
@@ -314,41 +313,9 @@ export async function handleMessages(req, res) {
     res.end(JSON.stringify({ accepted: true, deviceId: normalizedDeviceId, runId }));
     log("MESSAGE_RECEIVED", normalizedDeviceId, runId, `textLen=${trimmedText.length} attachments=${attachments.length} sessionKey=${baseSessionKey}`);
     const cfg = resolveFridayNextConfig(getHostOpenClawConfigSnapshot(runtime.config));
-    // Resolve defaults from the OpenClaw agent config so settings are never left empty.
-    // The target agent comes from the app-supplied sessionKey (`agent:<id>:<rest>`); prefer that
-    // agent's own configured model/thinking over the global defaults so non-main agents are not
-    // silently forced onto the global default model.
-    const targetAgentId = agentIdFromSessionKey(baseSessionKey);
-    let defaultModel;
-    let defaultThinking;
-    try {
-        const forwardRt = getFridayAgentForwardRuntime();
-        if (forwardRt) {
-            const ocCfg = (forwardRt.getConfig() ?? {});
-            const agents = ocCfg.agents;
-            const agentEntry = agents?.list?.find((a) => agentIdFromSessionKey(`agent:${String(a?.id ?? "")}:x`) === targetAgentId);
-            const agentModel = agentEntry?.model;
-            const perAgentModel = typeof agentModel === "string"
-                ? agentModel
-                : typeof agentModel?.primary === "string"
-                    ? agentModel.primary
-                    : undefined;
-            const perAgentThinking = typeof agentEntry?.thinkingDefault === "string"
-                ? agentEntry.thinkingDefault
-                : undefined;
-            const agentDefaults = agents?.defaults;
-            const model = agentDefaults?.model;
-            const globalModel = typeof model?.primary === "string" ? model.primary : undefined;
-            const globalThinking = typeof agentDefaults?.thinkingDefault === "string"
-                ? agentDefaults.thinkingDefault
-                : undefined;
-            defaultModel = perAgentModel ?? globalModel;
-            defaultThinking = perAgentThinking ?? globalThinking;
-        }
-    }
-    catch {
-        // Config not available (tests) — leave defaults undefined.
-    }
+    // Resolve defaults from the OpenClaw agent config so settings are never left empty. Prefers the
+    // target agent's own model/thinking over the global defaults (see resolveAgentDefaults).
+    const { model: defaultModel, thinking: defaultThinking } = resolveAgentDefaults(baseSessionKey);
     const modelRef = payload.modelRef ?? defaultModel;
     const reasoningLevel = payload.reasoningLevel ?? "stream";
     const thinkingLevel = payload.thinkingLevel ?? defaultThinking;
@@ -356,7 +323,8 @@ export async function handleMessages(req, res) {
     if (modelRef) {
         settings.modelRef = modelRef;
         const split = splitModelRef(modelRef);
-        settings.providerOverride = split.provider;
+        // `?? null` clears a stale provider when the resolved ref is bare (no `provider/` prefix).
+        settings.providerOverride = split.provider ?? null;
         settings.modelOverride = split.modelId;
     }
     if (reasoningLevel)

package/dist/src/http/handlers/sessions-settings.js

@@ -1,4 +1,4 @@
-import { setSessionSettings, getSessionSettings, splitModelRef, } from "../../session/session-manager.js";
+import { setSessionSettings, getSessionSettings, splitModelRef, resolveAgentDefaults, } from "../../session/session-manager.js";
 import { readJsonBody } from "../middleware/body.js";
 import { extractBearerToken } from "../middleware/auth.js";
 const VALID_REASONING = new Set(["on", "off", "stream"]);
@@ -43,7 +43,7 @@ export async function handleSessionsSettings(req, res) {
     }
     const reasoningLevel = typeof body?.reasoningLevel === "string" ? body.reasoningLevel : undefined;
     const thinkingLevel = typeof body?.thinkingLevel === "string" ? body.thinkingLevel : undefined;
-    const modelRef = typeof body?.modelRef === "string" ? body.modelRef : undefined;
+    const modelRef = typeof body?.modelRef === "string" ? body.modelRef.trim() : undefined;
     const errors = [];
     if (reasoningLevel !== undefined && !VALID_REASONING.has(reasoningLevel)) {
         errors.push(`reasoningLevel must be one of: ${[...VALID_REASONING].join(", ")}`);
@@ -57,11 +57,26 @@ export async function handleSessionsSettings(req, res) {
         res.end(JSON.stringify({ error: errors.join("; ") }));
         return true;
     }
-    const settings = { reasoningLevel, thinkingLevel, modelRef };
-    if (modelRef) {
-        const split = splitModelRef(modelRef);
-        settings["providerOverride"] = split.provider;
-        settings["modelOverride"] = split.modelId;
+    // The app omits (or empties) modelRef to mean "use the agent's default model". Resolve that
+    // default and write it as an *explicit* override, identical in shape to any other selection — so
+    // the agent runs the default exactly the way it runs an explicitly-picked model. Do NOT just
+    // clear the override here: the session entry is shared with the OpenClaw core, which stamps it
+    // with provenance fields (`modelOverrideSource`, `model`, `modelProvider`); deleting only our
+    // three fields leaves those dangling and the core mis-resolves to a fallback model.
+    const effectiveModelRef = modelRef || resolveAgentDefaults(sessionKey).model;
+    const settings = { reasoningLevel, thinkingLevel };
+    if (effectiveModelRef) {
+        const split = splitModelRef(effectiveModelRef);
+        settings.modelRef = effectiveModelRef;
+        // `?? null` clears a stale provider when the ref is bare (no `provider/` prefix).
+        settings.providerOverride = split.provider ?? null;
+        settings.modelOverride = split.modelId;
+    }
+    else {
+        // No configured default to resolve (e.g. config unavailable) — clear rather than pin a stale model.
+        settings.modelRef = null;
+        settings.providerOverride = null;
+        settings.modelOverride = null;
     }
     const result = setSessionSettings(sessionKey, settings);
     res.statusCode = 200;

package/dist/src/session/session-manager.d.ts

@@ -17,5 +17,34 @@ export interface FridaySessionSettings {
     providerOverride?: string;
     modelOverride?: string;
 }
-export declare function setSessionSettings(sessionKey: string, settings: FridaySessionSettings, historyDir?: string): FridaySessionSettings;
+/**
+ * Update shape for {@link setSessionSettings}. A field set to a string writes that value, a field
+ * left `undefined` is untouched, and a field set to `null` **clears** the stored value. The `null`
+ * case is what lets the app reset a model override back to the agent default — without it the merge
+ * could only ever add/replace overrides, never remove them (the cause of "selecting the default
+ * model doesn't take effect": a prior `provider/model` override survived and was read back).
+ */
+export type FridaySessionSettingsUpdate = {
+    reasoningLevel?: string | null;
+    thinkingLevel?: string | null;
+    modelRef?: string | null;
+    providerOverride?: string | null;
+    modelOverride?: string | null;
+};
+export declare function setSessionSettings(sessionKey: string, settings: FridaySessionSettingsUpdate, historyDir?: string): FridaySessionSettings;
 export declare function getSessionSettings(sessionKey: string, historyDir?: string): FridaySessionSettings;
+/**
+ * Resolve the configured default model + thinking level for the agent that owns `sessionKey`,
+ * reading the live OpenClaw config. Prefers the target agent's own `model`/`thinkingDefault` over
+ * the global `agents.defaults`, so non-main agents aren't silently forced onto the global default.
+ *
+ * Used to write the default model as an **explicit** override when the app selects it (the app
+ * sends no modelRef for the default). Writing it explicitly — rather than clearing the stored
+ * override — keeps the shared session entry consistent with the core's provenance fields
+ * (`modelOverrideSource`, `model`, `modelProvider`); a bare clear leaves those dangling and the
+ * agent mis-resolves to a fallback model.
+ */
+export declare function resolveAgentDefaults(sessionKey: string): {
+    model?: string;
+    thinking?: string;
+};

package/dist/src/session/session-manager.js

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import os from "node:os";
 import { readFileSync, writeFileSync } from "node:fs";
+import { getFridayAgentForwardRuntime } from "../agent-forward-runtime.js";
 const FRIDAY_AGENT_ID = "main";
 const SESSION_ID_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/i;
 /** Path/shell-safe agent id (mirrors OpenClaw's `normalizeAgentId`). Anything else falls back to `main`. */
@@ -122,7 +123,17 @@ export function setSessionSettings(sessionKey, settings, historyDir) {
         let updated = false;
         for (const key of fieldKeys) {
             const value = settings[key];
-            if (value !== undefined && data[fileKey][key] !== value) {
+            if (value === undefined)
+                continue; // leave the stored value untouched
+            if (value === null) {
+                // Explicit clear — remove the override so the agent falls back to its default.
+                if (key in data[fileKey]) {
+                    delete data[fileKey][key];
+                    updated = true;
+                }
+                continue;
+            }
+            if (data[fileKey][key] !== value) {
                 data[fileKey][key] = value;
                 updated = true;
             }
@@ -163,3 +174,41 @@ export function getSessionSettings(sessionKey, historyDir) {
         return {};
     }
 }
+/**
+ * Resolve the configured default model + thinking level for the agent that owns `sessionKey`,
+ * reading the live OpenClaw config. Prefers the target agent's own `model`/`thinkingDefault` over
+ * the global `agents.defaults`, so non-main agents aren't silently forced onto the global default.
+ *
+ * Used to write the default model as an **explicit** override when the app selects it (the app
+ * sends no modelRef for the default). Writing it explicitly — rather than clearing the stored
+ * override — keeps the shared session entry consistent with the core's provenance fields
+ * (`modelOverrideSource`, `model`, `modelProvider`); a bare clear leaves those dangling and the
+ * agent mis-resolves to a fallback model.
+ */
+export function resolveAgentDefaults(sessionKey) {
+    try {
+        const forwardRt = getFridayAgentForwardRuntime();
+        if (!forwardRt)
+            return {};
+        const ocCfg = (forwardRt.getConfig() ?? {});
+        const agents = ocCfg.agents;
+        const targetAgentId = agentIdFromSessionKey(sessionKey);
+        const agentEntry = agents?.list?.find((a) => agentIdFromSessionKey(`agent:${String(a?.id ?? "")}:x`) === targetAgentId);
+        const agentModel = agentEntry?.model;
+        const perAgentModel = typeof agentModel === "string"
+            ? agentModel
+            : typeof agentModel?.primary === "string"
+                ? agentModel.primary
+                : undefined;
+        const perAgentThinking = typeof agentEntry?.thinkingDefault === "string" ? agentEntry.thinkingDefault : undefined;
+        const agentDefaults = agents?.defaults;
+        const model = agentDefaults?.model;
+        const globalModel = typeof model?.primary === "string" ? model.primary : undefined;
+        const globalThinking = typeof agentDefaults?.thinkingDefault === "string" ? agentDefaults.thinkingDefault : undefined;
+        return { model: perAgentModel ?? globalModel, thinking: perAgentThinking ?? globalThinking };
+    }
+    catch {
+        // Config not available (e.g. unit tests) — caller decides the fallback.
+        return {};
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syengup/friday-channel-next",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "OpenClaw Friday Next Apple channel plugin",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,15 @@
     "tsconfig.json",
     "openclaw.plugin.json"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "pnpm build && rm -rf dist/attachments",
+    "test": "npm run test:unit && npm run test:e2e",
+    "test:unit": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:smoke": "node scripts/e2e-smoke.mjs",
+    "test:msg-live": "node scripts/message-roundtrip-live.mjs"
+  },
   "bin": {
     "friday-channel-next": "install.js"
   },
@@ -57,13 +66,5 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
     "zod": "^4.3.6"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "npm run test:unit && npm run test:e2e",
-    "test:unit": "vitest run",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:smoke": "node scripts/e2e-smoke.mjs",
-    "test:msg-live": "node scripts/message-roundtrip-live.mjs"
   }
-}
+}

package/src/channel.outbound-mirror-suppression.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { fridayNextChannelPlugin } from "./channel.js";
+
+/**
+ * friday-next is a transparent proxy: outbound attachments/text already reach the app
+ * live via SSE (sendText/sendMedia/handleSend). OpenClaw core's generic outbound path
+ * additionally mirrors message-tool sends into the *recipient's* session transcript
+ * (model:"delivery-mirror"). For friday-next that recipient session falls back to
+ * `agent:<agentId>:friday-next:direct:<deviceId>` — an orphan session unrelated to the
+ * app's real conversation — producing a phantom session + a stray delivery-mirror message.
+ *
+ * The core consults `messaging.resolveOutboundSessionRoute` FIRST; returning `null`
+ * short-circuits route resolution so no orphan session entry and no delivery-mirror are
+ * created. This test pins that contract.
+ */
+describe("friday-next channel suppresses core delivery-mirror", () => {
+  const messaging = (fridayNextChannelPlugin as { messaging?: Record<string, unknown> }).messaging;
+
+  it("exposes resolveOutboundSessionRoute on the messaging adapter", () => {
+    expect(typeof messaging?.resolveOutboundSessionRoute).toBe("function");
+  });
+
+  it("returns null for any outbound target so no mirror session is routed", async () => {
+    const resolve = messaging?.resolveOutboundSessionRoute as (
+      params: Record<string, unknown>,
+    ) => unknown;
+    const route = await resolve({
+      cfg: {},
+      agentId: "operator",
+      channel: "friday-next",
+      target: "9cd3d546-b230-40ab-b931-bb2e8305e38c",
+      currentSessionKey: "agent:operator:friday-next:9cd3d546",
+    });
+    expect(route).toBeNull();
+  });
+});

package/src/channel.ts

@@ -160,6 +160,15 @@ export const fridayNextChannelPlugin = createChatChannelPlugin({
       },
       parseExplicitTarget: () => ({ to: "friday-next" }),
       formatTargetDisplay: ({ display }: any) => display || "Friday Next",
+      // friday-next is a transparent proxy: outbound text/media already reach the app live
+      // via SSE (sendText/sendMedia/handleSend). The OpenClaw core additionally mirrors
+      // message-tool sends into the recipient's session transcript (model:"delivery-mirror").
+      // For friday-next that recipient session falls back to
+      // `agent:<agentId>:friday-next:direct:<deviceId>` — an orphan session unrelated to the
+      // app's real conversation — spawning a phantom session + a stray delivery-mirror message.
+      // The core checks this hook first; returning null short-circuits route resolution so no
+      // orphan session entry and no delivery-mirror are written.
+      resolveOutboundSessionRoute: () => null,
     },
   },
   outbound: {

package/src/http/handlers/messages.ts

@@ -27,12 +27,12 @@ export type FridayReplyPayload = {
 import { resolveFridayNextConfig } from "../../config.js";
 import { getHostOpenClawConfigSnapshot } from "../../host-config.js";
 import { getFridayNextRuntime } from "../../runtime.js";
-import { getFridayAgentForwardRuntime } from "../../agent-forward-runtime.js";
 import {
-  agentIdFromSessionKey,
+  resolveAgentDefaults,
   setSessionSettings,
   splitModelRef,
   toSessionStoreKey,
+  type FridaySessionSettingsUpdate,
 } from "../../session/session-manager.js";
 import { sseEmitter } from "../../sse/emitter.js";
 import { extractBearerToken } from "../middleware/auth.js";
@@ -425,58 +425,20 @@ export async function handleMessages(req: IncomingMessage, res: ServerResponse):
 
   const cfg = resolveFridayNextConfig(getHostOpenClawConfigSnapshot(runtime.config));
 
-  // Resolve defaults from the OpenClaw agent config so settings are never left empty.
-  // The target agent comes from the app-supplied sessionKey (`agent:<id>:<rest>`); prefer that
-  // agent's own configured model/thinking over the global defaults so non-main agents are not
-  // silently forced onto the global default model.
-  const targetAgentId = agentIdFromSessionKey(baseSessionKey);
-  let defaultModel: string | undefined;
-  let defaultThinking: string | undefined;
-  try {
-    const forwardRt = getFridayAgentForwardRuntime();
-    if (forwardRt) {
-      const ocCfg = (forwardRt.getConfig() ?? {}) as Record<string, unknown>;
-      const agents = ocCfg.agents as Record<string, unknown> | undefined;
-
-      const agentEntry = (agents?.list as Array<Record<string, unknown>> | undefined)?.find(
-        (a) => agentIdFromSessionKey(`agent:${String(a?.id ?? "")}:x`) === targetAgentId,
-      );
-      const agentModel = agentEntry?.model;
-      const perAgentModel =
-        typeof agentModel === "string"
-          ? agentModel
-          : typeof (agentModel as Record<string, unknown> | undefined)?.primary === "string"
-            ? ((agentModel as Record<string, unknown>).primary as string)
-            : undefined;
-      const perAgentThinking =
-        typeof agentEntry?.thinkingDefault === "string"
-          ? (agentEntry.thinkingDefault as string)
-          : undefined;
-
-      const agentDefaults = agents?.defaults as Record<string, unknown> | undefined;
-      const model = agentDefaults?.model as Record<string, unknown> | undefined;
-      const globalModel = typeof model?.primary === "string" ? (model.primary as string) : undefined;
-      const globalThinking =
-        typeof agentDefaults?.thinkingDefault === "string"
-          ? (agentDefaults.thinkingDefault as string)
-          : undefined;
-
-      defaultModel = perAgentModel ?? globalModel;
-      defaultThinking = perAgentThinking ?? globalThinking;
-    }
-  } catch {
-    // Config not available (tests) — leave defaults undefined.
-  }
+  // Resolve defaults from the OpenClaw agent config so settings are never left empty. Prefers the
+  // target agent's own model/thinking over the global defaults (see resolveAgentDefaults).
+  const { model: defaultModel, thinking: defaultThinking } = resolveAgentDefaults(baseSessionKey);
 
   const modelRef = payload.modelRef ?? defaultModel;
   const reasoningLevel = payload.reasoningLevel ?? "stream";
   const thinkingLevel = payload.thinkingLevel ?? defaultThinking;
 
-  const settings: Record<string, string | undefined> = {};
+  const settings: FridaySessionSettingsUpdate = {};
   if (modelRef) {
     settings.modelRef = modelRef;
     const split = splitModelRef(modelRef);
-    settings.providerOverride = split.provider;
+    // `?? null` clears a stale provider when the resolved ref is bare (no `provider/` prefix).
+    settings.providerOverride = split.provider ?? null;
     settings.modelOverride = split.modelId;
   }
   if (reasoningLevel) settings.reasoningLevel = reasoningLevel;

package/src/http/handlers/sessions-settings.ts

@@ -3,6 +3,8 @@ import {
   setSessionSettings,
   getSessionSettings,
   splitModelRef,
+  resolveAgentDefaults,
+  type FridaySessionSettingsUpdate,
 } from "../../session/session-manager.js";
 import { readJsonBody } from "../middleware/body.js";
 import { extractBearerToken } from "../middleware/auth.js";
@@ -57,7 +59,7 @@ export async function handleSessionsSettings(
 
   const reasoningLevel = typeof body?.reasoningLevel === "string" ? body.reasoningLevel : undefined;
   const thinkingLevel = typeof body?.thinkingLevel === "string" ? body.thinkingLevel : undefined;
-  const modelRef = typeof body?.modelRef === "string" ? body.modelRef : undefined;
+  const modelRef = typeof body?.modelRef === "string" ? body.modelRef.trim() : undefined;
 
   const errors: string[] = [];
   if (reasoningLevel !== undefined && !VALID_REASONING.has(reasoningLevel)) {
@@ -74,11 +76,26 @@ export async function handleSessionsSettings(
     return true;
   }
 
-  const settings: Record<string, string | undefined> = { reasoningLevel, thinkingLevel, modelRef };
-  if (modelRef) {
-    const split = splitModelRef(modelRef);
-    settings["providerOverride"] = split.provider;
-    settings["modelOverride"] = split.modelId;
+  // The app omits (or empties) modelRef to mean "use the agent's default model". Resolve that
+  // default and write it as an *explicit* override, identical in shape to any other selection — so
+  // the agent runs the default exactly the way it runs an explicitly-picked model. Do NOT just
+  // clear the override here: the session entry is shared with the OpenClaw core, which stamps it
+  // with provenance fields (`modelOverrideSource`, `model`, `modelProvider`); deleting only our
+  // three fields leaves those dangling and the core mis-resolves to a fallback model.
+  const effectiveModelRef = modelRef || resolveAgentDefaults(sessionKey).model;
+
+  const settings: FridaySessionSettingsUpdate = { reasoningLevel, thinkingLevel };
+  if (effectiveModelRef) {
+    const split = splitModelRef(effectiveModelRef);
+    settings.modelRef = effectiveModelRef;
+    // `?? null` clears a stale provider when the ref is bare (no `provider/` prefix).
+    settings.providerOverride = split.provider ?? null;
+    settings.modelOverride = split.modelId;
+  } else {
+    // No configured default to resolve (e.g. config unavailable) — clear rather than pin a stale model.
+    settings.modelRef = null;
+    settings.providerOverride = null;
+    settings.modelOverride = null;
   }
 
   const result = setSessionSettings(sessionKey, settings);

package/src/session/session-manager.test.ts

@@ -87,4 +87,46 @@ describe("per-agent session settings file routing", () => {
 
     expect(readEntry("main", "agent:main:main")?.thinkingLevel).toBe("low");
   });
+
+  it("clears a stored model override when the trio is set to null (default re-selected)", () => {
+    seedSessionsFile("main");
+
+    // Prior non-default selection.
+    setSessionSettings(
+      "main",
+      { modelRef: "openai/gpt-x", providerOverride: "openai", modelOverride: "gpt-x" },
+      historyDir,
+    );
+    expect(getSessionSettings("main", historyDir).modelRef).toBe("openai/gpt-x");
+
+    // Switching back to the agent default sends nulls → override is removed, not merged.
+    setSessionSettings(
+      "main",
+      { modelRef: null, providerOverride: null, modelOverride: null },
+      historyDir,
+    );
+
+    const entry = readEntry("main", "agent:main:main")!;
+    expect(entry.modelRef).toBeUndefined();
+    expect(entry.providerOverride).toBeUndefined();
+    expect(entry.modelOverride).toBeUndefined();
+    expect(getSessionSettings("main", historyDir).modelRef).toBeUndefined();
+  });
+
+  it("leaves the stored model override untouched when fields are undefined", () => {
+    seedSessionsFile("main");
+
+    setSessionSettings(
+      "main",
+      { modelRef: "openai/gpt-x", providerOverride: "openai", modelOverride: "gpt-x" },
+      historyDir,
+    );
+    // A thinking-only update (model fields undefined) must not disturb the override.
+    setSessionSettings("main", { thinkingLevel: "high" }, historyDir);
+
+    const entry = readEntry("main", "agent:main:main")!;
+    expect(entry.thinkingLevel).toBe("high");
+    expect(entry.modelRef).toBe("openai/gpt-x");
+    expect(entry.providerOverride).toBe("openai");
+  });
 });

package/src/session/session-manager.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import os from "node:os";
 import { readFileSync, writeFileSync } from "node:fs";
+import { getFridayAgentForwardRuntime } from "../agent-forward-runtime.js";
 
 const FRIDAY_AGENT_ID = "main";
 const SESSION_ID_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/i;
@@ -132,9 +133,24 @@ export interface FridaySessionSettings {
   modelOverride?: string;
 }
 
+/**
+ * Update shape for {@link setSessionSettings}. A field set to a string writes that value, a field
+ * left `undefined` is untouched, and a field set to `null` **clears** the stored value. The `null`
+ * case is what lets the app reset a model override back to the agent default — without it the merge
+ * could only ever add/replace overrides, never remove them (the cause of "selecting the default
+ * model doesn't take effect": a prior `provider/model` override survived and was read back).
+ */
+export type FridaySessionSettingsUpdate = {
+  reasoningLevel?: string | null;
+  thinkingLevel?: string | null;
+  modelRef?: string | null;
+  providerOverride?: string | null;
+  modelOverride?: string | null;
+};
+
 export function setSessionSettings(
   sessionKey: string,
-  settings: FridaySessionSettings,
+  settings: FridaySessionSettingsUpdate,
   historyDir?: string,
 ): FridaySessionSettings {
   try {
@@ -145,13 +161,22 @@ export function setSessionSettings(
 
     upsertSessionEntry(data, fileKey, sessionKey);
 
-    const fieldKeys: (keyof FridaySessionSettings)[] = [
+    const fieldKeys: (keyof FridaySessionSettingsUpdate)[] = [
       "reasoningLevel", "thinkingLevel", "modelRef", "providerOverride", "modelOverride",
     ];
     let updated = false;
     for (const key of fieldKeys) {
       const value = settings[key];
-      if (value !== undefined && data[fileKey][key] !== value) {
+      if (value === undefined) continue; // leave the stored value untouched
+      if (value === null) {
+        // Explicit clear — remove the override so the agent falls back to its default.
+        if (key in data[fileKey]) {
+          delete data[fileKey][key];
+          updated = true;
+        }
+        continue;
+      }
+      if (data[fileKey][key] !== value) {
         data[fileKey][key] = value;
         updated = true;
       }
@@ -197,3 +222,48 @@ export function getSessionSettings(
     return {};
   }
 }
+
+/**
+ * Resolve the configured default model + thinking level for the agent that owns `sessionKey`,
+ * reading the live OpenClaw config. Prefers the target agent's own `model`/`thinkingDefault` over
+ * the global `agents.defaults`, so non-main agents aren't silently forced onto the global default.
+ *
+ * Used to write the default model as an **explicit** override when the app selects it (the app
+ * sends no modelRef for the default). Writing it explicitly — rather than clearing the stored
+ * override — keeps the shared session entry consistent with the core's provenance fields
+ * (`modelOverrideSource`, `model`, `modelProvider`); a bare clear leaves those dangling and the
+ * agent mis-resolves to a fallback model.
+ */
+export function resolveAgentDefaults(sessionKey: string): { model?: string; thinking?: string } {
+  try {
+    const forwardRt = getFridayAgentForwardRuntime();
+    if (!forwardRt) return {};
+    const ocCfg = (forwardRt.getConfig() ?? {}) as Record<string, unknown>;
+    const agents = ocCfg.agents as Record<string, unknown> | undefined;
+    const targetAgentId = agentIdFromSessionKey(sessionKey);
+
+    const agentEntry = (agents?.list as Array<Record<string, unknown>> | undefined)?.find(
+      (a) => agentIdFromSessionKey(`agent:${String(a?.id ?? "")}:x`) === targetAgentId,
+    );
+    const agentModel = agentEntry?.model;
+    const perAgentModel =
+      typeof agentModel === "string"
+        ? agentModel
+        : typeof (agentModel as Record<string, unknown> | undefined)?.primary === "string"
+          ? ((agentModel as Record<string, unknown>).primary as string)
+          : undefined;
+    const perAgentThinking =
+      typeof agentEntry?.thinkingDefault === "string" ? (agentEntry.thinkingDefault as string) : undefined;
+
+    const agentDefaults = agents?.defaults as Record<string, unknown> | undefined;
+    const model = agentDefaults?.model as Record<string, unknown> | undefined;
+    const globalModel = typeof model?.primary === "string" ? (model.primary as string) : undefined;
+    const globalThinking =
+      typeof agentDefaults?.thinkingDefault === "string" ? (agentDefaults.thinkingDefault as string) : undefined;
+
+    return { model: perAgentModel ?? globalModel, thinking: perAgentThinking ?? globalThinking };
+  } catch {
+    // Config not available (e.g. unit tests) — caller decides the fallback.
+    return {};
+  }
+}