@syengup/friday-channel-next 0.1.14 → 0.1.16

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.d.ts

@@ -22,6 +22,22 @@ export type FridayReplyPayload = {
     interactive?: unknown;
     channelData?: unknown;
 };
+/** Map local / gateway paths to public `/friday-next/files/...` URLs where possible. */
+/**
+ * Canvas snapshots are captured so the *agent* can "see" the rendered canvas. OpenClaw core surfaces
+ * any image tool result as deliverable media on the assistant reply block, which for Friday Next would
+ * make the snapshot auto-appear as an attachment mid-stream — not what we want. Snapshot temp files are
+ * named `openclaw-canvas-snapshot-<uuid>.<ext>`, so we detect them by basename and drop them from the
+ * delivered payload (the assistant text is preserved). Agent-initiated media sends are unaffected —
+ * those flow through the `outbound` channel action, not the deliver block path.
+ */
+export declare function isCanvasSnapshotMediaPath(url: unknown): boolean;
+export declare function translateDeliverPayload(pl: FridayReplyPayload, kind: string, meta?: {
+    modelName?: string;
+    totalTokens?: number;
+    contextTokensUsed?: number;
+    contextWindowMax?: number;
+}): Record<string, unknown>;
 export interface FridayMessagePayload {
     deviceId: string;
     text: string;

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";
@@ -85,7 +84,28 @@ function inferFridayNextMediaKind(params) {
     return "file";
 }
 /** Map local / gateway paths to public `/friday-next/files/...` URLs where possible. */
-function translateDeliverPayload(pl, kind, meta) {
+/**
+ * Canvas snapshots are captured so the *agent* can "see" the rendered canvas. OpenClaw core surfaces
+ * any image tool result as deliverable media on the assistant reply block, which for Friday Next would
+ * make the snapshot auto-appear as an attachment mid-stream — not what we want. Snapshot temp files are
+ * named `openclaw-canvas-snapshot-<uuid>.<ext>`, so we detect them by basename and drop them from the
+ * delivered payload (the assistant text is preserved). Agent-initiated media sends are unaffected —
+ * those flow through the `outbound` channel action, not the deliver block path.
+ */
+export function isCanvasSnapshotMediaPath(url) {
+    if (typeof url !== "string")
+        return false;
+    const base = url.split(/[/\\]/).pop() ?? url;
+    return /canvas-snapshot-/i.test(base);
+}
+export function translateDeliverPayload(pl, kind, meta) {
+    // Strip canvas-snapshot tool-result images before any media resolution (paths here are still the
+    // original `/tmp/openclaw/openclaw-canvas-snapshot-*.jpg` temp paths, not yet copied to friday files).
+    const filteredSingle = typeof pl.mediaUrl === "string" && !isCanvasSnapshotMediaPath(pl.mediaUrl) ? pl.mediaUrl : null;
+    const filteredArr = Array.isArray(pl.mediaUrls)
+        ? pl.mediaUrls.filter((u) => !isCanvasSnapshotMediaPath(u))
+        : pl.mediaUrls;
+    pl = { ...pl, mediaUrl: filteredSingle, mediaUrls: filteredArr };
     const raw = { ...pl };
     const originalUrls = collectReplyPayloadMediaUrls(pl);
     if (typeof pl.mediaUrl === "string" && pl.mediaUrl.trim()) {
@@ -314,41 +334,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 +344,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/install.js

@@ -238,14 +238,22 @@ if (configChanged) {
 
 // --------------- restart gateway ---------------
 
-log("Restarting OpenClaw gateway...");
+log("Restarting OpenClaw gateway... (this can take 20-30s)");
 try {
-  const out = execSync(`${openclawCmd} gateway restart`, { encoding: "utf8", stdio: "pipe", timeout: 15000 });
+  // A full gateway restart commonly takes 20s+ on a fresh boot; give it plenty of room
+  // so we don't kill it mid-restart and report a false failure.
+  const out = execSync(`${openclawCmd} gateway restart`, { encoding: "utf8", stdio: "pipe", timeout: 90000 });
   if (out.trim()) console.log(out.trim());
 } catch (e) {
   if (e.stdout?.trim()) console.log(e.stdout.trim());
   if (e.stderr?.trim()) console.error(e.stderr.trim());
-  warn("Gateway restart failed. Restart manually: openclaw gateway restart");
+  // ETIMEDOUT/SIGTERM here usually means the restart is simply slow, not broken —
+  // the verify step below will confirm whether the gateway actually came up.
+  if (e.code === "ETIMEDOUT" || e.signal === "SIGTERM") {
+    warn("Gateway restart is taking a while — will verify below.");
+  } else {
+    warn("Gateway restart failed. Restart manually: openclaw gateway restart");
+  }
 }
 
 // --------------- verify ---------------
@@ -270,7 +278,11 @@ const gatewayUrl = bindMode === "lan"
   ? `http://${getLanIp()}:${gatewayPort}`
   : `http://127.0.0.1:${gatewayPort}`;
 
-async function verifyGateway(url, token, retries = 6) {
+// Always verify against loopback: the gateway binds 0.0.0.0 so it's reachable here,
+// and this avoids false negatives from LAN/NAT routing of the advertised IP.
+const verifyUrl = `http://127.0.0.1:${gatewayPort}`;
+
+async function verifyGateway(url, token, retries = 30) {
   const http = await import("node:http");
   const { hostname, port } = new URL(url);
   for (let i = 1; i <= retries; i++) {
@@ -312,7 +324,7 @@ async function verifyGateway(url, token, retries = 6) {
 }
 
 log("Verifying gateway...");
-const verified = await verifyGateway(gatewayUrl, gatewayToken);
+const verified = await verifyGateway(verifyUrl, gatewayToken);
 
 // --------------- show connection info ---------------
 
@@ -372,4 +384,39 @@ if (ipType === "tailscale") {
 } else {
   log("This URL appears to be publicly accessible (" + ip + ").");
 }
+
+// On a cloud server the advertised IP is the internal/NAT address, which a phone
+// over the internet can't reach. Best-effort: detect the public IP so the user
+// has the address to actually connect with (and a reminder to open the port).
+if (ipType === "private" || ipType === "loopback") {
+  const publicIp = await detectPublicIp();
+  if (publicIp && publicIp !== ip) {
+    log("");
+    log(BOLD_YELLOW("Looks like a cloud server. For remote access use the PUBLIC address:"));
+    log(BOLD_YELLOW("检测到云服务器，远程连接请改用公网地址："));
+    log("Public URL:   " + BOLD_YELLOW(`http://${publicIp}:${gatewayPort}`));
+    log("(Open inbound TCP port " + gatewayPort + " in your firewall / security group first.)");
+    log("(需先在防火墙/安全组放行入站 TCP 端口 " + gatewayPort + "。)");
+  }
+}
 log("--------------------------------------------------");
+
+async function detectPublicIp() {
+  const endpoints = ["http://api.ipify.org", "http://ifconfig.me/ip", "http://icanhazip.com"];
+  const http = await import("node:http");
+  for (const url of endpoints) {
+    try {
+      const ipStr = await new Promise((resolve, reject) => {
+        const req = http.get(url, { timeout: 3000 }, (res) => {
+          let body = "";
+          res.on("data", (c) => body += c);
+          res.on("end", () => resolve(body.trim()));
+        });
+        req.on("error", reject);
+        req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
+      });
+      if (/^\d{1,3}(\.\d{1,3}){3}$/.test(ipStr)) return ipStr;
+    } catch { /* try next */ }
+  }
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syengup/friday-channel-next",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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.canvas-snapshot.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { isCanvasSnapshotMediaPath, translateDeliverPayload } from "./messages.js";
+
+/**
+ * canvas.snapshot tool results are an agent-facing capture. OpenClaw core surfaces image tool
+ * results as deliverable media on the assistant reply block, which would otherwise auto-attach the
+ * snapshot to the user's stream. translateDeliverPayload must drop snapshot temp files (by basename)
+ * while preserving the assistant text and any non-snapshot media.
+ */
+describe("canvas snapshot media suppression", () => {
+  it("detects canvas snapshot temp paths by basename", () => {
+    expect(
+      isCanvasSnapshotMediaPath("/tmp/openclaw/openclaw-canvas-snapshot-d2e6aef2-0441.jpg"),
+    ).toBe(true);
+    expect(isCanvasSnapshotMediaPath("C:\\tmp\\openclaw-canvas-snapshot-abc.png")).toBe(true);
+    expect(isCanvasSnapshotMediaPath("/Users/me/Pictures/screenshot_latest.jpg")).toBe(false);
+    expect(isCanvasSnapshotMediaPath("/friday-next/files/uuid.jpg")).toBe(false);
+    expect(isCanvasSnapshotMediaPath(undefined)).toBe(false);
+  });
+
+  it("strips a snapshot mediaUrl from a block deliver payload, keeping the text", () => {
+    const out = translateDeliverPayload(
+      {
+        text: "🎉 通了!",
+        mediaUrl: "/tmp/openclaw/openclaw-canvas-snapshot-d2e6aef2-0441.jpg",
+      },
+      "block",
+    );
+    expect(out.text).toBe("🎉 通了!");
+    expect(out.mediaUrl).toBeNull();
+    // No media survived → no image mediaKind tagged onto the payload.
+    const channelData = out.channelData as { fridayNext?: { mediaKind?: string } } | undefined;
+    expect(channelData?.fridayNext?.mediaKind).toBeUndefined();
+  });
+
+  it("strips snapshot entries from mediaUrls but preserves non-snapshot media", () => {
+    const out = translateDeliverPayload(
+      {
+        text: "page rendered",
+        mediaUrls: [
+          "/tmp/openclaw/openclaw-canvas-snapshot-aaa.jpg",
+          "/Users/me/Pictures/real-image.png",
+        ],
+      },
+      "block",
+    );
+    const urls = out.mediaUrls as string[];
+    expect(urls).toHaveLength(1);
+    expect(urls.some((u) => u.includes("canvas-snapshot-"))).toBe(false);
+  });
+});

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";
@@ -132,11 +132,34 @@ function inferFridayNextMediaKind(params: {
 }
 
 /** Map local / gateway paths to public `/friday-next/files/...` URLs where possible. */
-function translateDeliverPayload(
+/**
+ * Canvas snapshots are captured so the *agent* can "see" the rendered canvas. OpenClaw core surfaces
+ * any image tool result as deliverable media on the assistant reply block, which for Friday Next would
+ * make the snapshot auto-appear as an attachment mid-stream — not what we want. Snapshot temp files are
+ * named `openclaw-canvas-snapshot-<uuid>.<ext>`, so we detect them by basename and drop them from the
+ * delivered payload (the assistant text is preserved). Agent-initiated media sends are unaffected —
+ * those flow through the `outbound` channel action, not the deliver block path.
+ */
+export function isCanvasSnapshotMediaPath(url: unknown): boolean {
+  if (typeof url !== "string") return false;
+  const base = url.split(/[/\\]/).pop() ?? url;
+  return /canvas-snapshot-/i.test(base);
+}
+
+export function translateDeliverPayload(
   pl: FridayReplyPayload,
   kind: string,
   meta?: { modelName?: string; totalTokens?: number; contextTokensUsed?: number; contextWindowMax?: number },
 ): Record<string, unknown> {
+  // Strip canvas-snapshot tool-result images before any media resolution (paths here are still the
+  // original `/tmp/openclaw/openclaw-canvas-snapshot-*.jpg` temp paths, not yet copied to friday files).
+  const filteredSingle =
+    typeof pl.mediaUrl === "string" && !isCanvasSnapshotMediaPath(pl.mediaUrl) ? pl.mediaUrl : null;
+  const filteredArr = Array.isArray(pl.mediaUrls)
+    ? pl.mediaUrls.filter((u) => !isCanvasSnapshotMediaPath(u))
+    : pl.mediaUrls;
+  pl = { ...pl, mediaUrl: filteredSingle, mediaUrls: filteredArr };
+
   const raw = { ...pl } as Record<string, unknown>;
   const originalUrls = collectReplyPayloadMediaUrls(pl);
   if (typeof pl.mediaUrl === "string" && pl.mediaUrl.trim()) {
@@ -425,58 +448,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 {};
+  }
+}