fix: stage sandbox media for inbound attachments

CHANGELOG.md

@@ -10,6 +10,7 @@
 - macOS: local gateway now connects via tailnet IP when bind mode is `tailnet`/`auto`.
 - macOS: Settings now use a sidebar layout to avoid toolbar overflow in Connections.
 - macOS: drop deprecated `afterMs` from agent wait params to match gateway schema.
+- Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments.
 
 ### Maintenance
 - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome.

src/agents/clawdbot-tools.sessions.test.ts

@@ -5,16 +5,20 @@ vi.mock("../gateway/call.js", () => ({
   callGateway: (opts: unknown) => callGatewayMock(opts),
 }));
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => ({
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-    session: {
+  return {
-      mainKey: "main",
+    ...actual,
-      scope: "per-sender",
+    loadConfig: () => ({
-      agentToAgent: { maxPingPongTurns: 2 },
+      session: {
-    },
+        mainKey: "main",
-  }),
+        scope: "per-sender",
-  resolveGatewayPort: () => 18789,
+        agentToAgent: { maxPingPongTurns: 2 },
-}));
+      },
+    }),
+    resolveGatewayPort: () => 18789,
+  };
+});
 
 import { createClawdbotTools } from "./clawdbot-tools.js";
 

src/agents/sandbox.ts

@@ -99,6 +99,11 @@ export type SandboxContext = {
   browser?: SandboxBrowserContext;
 };
 
+export type SandboxWorkspaceInfo = {
+  workspaceDir: string;
+  containerWorkdir: string;
+};
+
 const DEFAULT_SANDBOX_WORKSPACE_ROOT = path.join(
   os.homedir(),
   ".clawdbot",
@@ -866,3 +871,28 @@ export async function resolveSandboxContext(params: {
     browser: browser ?? undefined,
   };
 }
+
+export async function ensureSandboxWorkspaceForSession(params: {
+  config?: ClawdbotConfig;
+  sessionKey?: string;
+  workspaceDir?: string;
+}): Promise<SandboxWorkspaceInfo | null> {
+  const rawSessionKey = params.sessionKey?.trim();
+  if (!rawSessionKey) return null;
+  const cfg = defaultSandboxConfig(params.config);
+  const mainKey = params.config?.session?.mainKey?.trim() || "main";
+  if (!shouldSandboxSession(cfg, rawSessionKey, mainKey)) return null;
+
+  const workspaceRoot = resolveUserPath(cfg.workspaceRoot);
+  const workspaceDir = cfg.perSession
+    ? resolveSandboxWorkspaceDir(workspaceRoot, rawSessionKey)
+    : workspaceRoot;
+  const seedWorkspace =
+    params.workspaceDir?.trim() || DEFAULT_AGENT_WORKSPACE_DIR;
+  await ensureSandboxWorkspace(workspaceDir, seedWorkspace);
+
+  return {
+    workspaceDir,
+    containerWorkdir: cfg.docker.workdir,
+  };
+}

src/auto-reply/reply.triggers.test.ts

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 vi.mock("../agents/pi-embedded.js", () => ({
@@ -14,6 +14,8 @@ vi.mock("../agents/pi-embedded.js", () => ({
 }));
 
 import { runEmbeddedPiAgent } from "../agents/pi-embedded.js";
+import { ensureSandboxWorkspaceForSession } from "../agents/sandbox.js";
+import { resolveSessionKey } from "../config/sessions.js";
 import { getReplyFromConfig } from "./reply.js";
 import { HEARTBEAT_TOKEN } from "./tokens.js";
 
@@ -712,6 +714,81 @@ describe("trigger handling", () => {
       expect(runEmbeddedPiAgent).toHaveBeenCalledOnce();
     });
   });
+
+  it("stages inbound media into the sandbox workspace", async () => {
+    await withTempHome(async (home) => {
+      const inboundDir = join(home, ".clawdbot", "media", "inbound");
+      await fs.mkdir(inboundDir, { recursive: true });
+      const mediaPath = join(inboundDir, "photo.jpg");
+      await fs.writeFile(mediaPath, "test");
+
+      vi.mocked(runEmbeddedPiAgent).mockResolvedValue({
+        payloads: [{ text: "ok" }],
+        meta: {
+          durationMs: 1,
+          agentMeta: { sessionId: "s", provider: "p", model: "m" },
+        },
+      });
+
+      const cfg = {
+        agent: {
+          model: "anthropic/claude-opus-4-5",
+          workspace: join(home, "clawd"),
+          sandbox: {
+            mode: "non-main" as const,
+            workspaceRoot: join(home, "sandboxes"),
+          },
+        },
+        whatsapp: {
+          allowFrom: ["*"],
+        },
+        session: {
+          store: join(home, "sessions.json"),
+        },
+      };
+
+      const ctx = {
+        Body: "hi",
+        From: "group:whatsapp:demo",
+        To: "+2000",
+        ChatType: "group" as const,
+        Surface: "whatsapp" as const,
+        MediaPath: mediaPath,
+        MediaType: "image/jpeg",
+        MediaUrl: mediaPath,
+      };
+
+      const res = await getReplyFromConfig(ctx, {}, cfg);
+      const text = Array.isArray(res) ? res[0]?.text : res?.text;
+      expect(text).toBe("ok");
+      expect(runEmbeddedPiAgent).toHaveBeenCalledOnce();
+
+      const prompt =
+        vi.mocked(runEmbeddedPiAgent).mock.calls[0]?.[0]?.prompt ?? "";
+      const stagedPath = `media/inbound/${basename(mediaPath)}`;
+      expect(prompt).toContain(stagedPath);
+      expect(prompt).not.toContain(mediaPath);
+
+      const sessionKey = resolveSessionKey(
+        cfg.session?.scope ?? "per-sender",
+        ctx,
+        cfg.session?.mainKey,
+      );
+      const sandbox = await ensureSandboxWorkspaceForSession({
+        config: cfg,
+        sessionKey,
+        workspaceDir: cfg.agent.workspace,
+      });
+      expect(sandbox).not.toBeNull();
+      const stagedFullPath = join(
+        sandbox!.workspaceDir,
+        "media",
+        "inbound",
+        basename(mediaPath),
+      );
+      await expect(fs.stat(stagedFullPath)).resolves.toBeTruthy();
+    });
+  });
 });
 
 describe("group intro prompts", () => {

src/auto-reply/reply.ts

@@ -1,4 +1,7 @@
 import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { resolveModelRefFromString } from "../agents/model-selection.js";
 import {
@@ -7,6 +10,7 @@ import {
   isEmbeddedPiRunStreaming,
   resolveEmbeddedSessionLane,
 } from "../agents/pi-embedded.js";
+import { ensureSandboxWorkspaceForSession } from "../agents/sandbox.js";
 import {
   DEFAULT_AGENT_WORKSPACE_DIR,
   ensureAgentWorkspace,
@@ -49,7 +53,7 @@ import {
   prependSystemEvents,
 } from "./reply/session-updates.js";
 import { createTypingController } from "./reply/typing.js";
-import type { MsgContext } from "./templating.js";
+import type { MsgContext, TemplateContext } from "./templating.js";
 import {
   type ElevatedLevel,
   normalizeThinkLevel,
@@ -478,6 +482,15 @@ export async function getReplyFromConfig(
     typing.cleanup();
     return commandResult.reply;
   }
+
+  await stageSandboxMedia({
+    ctx,
+    sessionCtx,
+    cfg,
+    sessionKey,
+    workspaceDir,
+  });
+
   const isFirstTurnInSession = isNewSession || !systemSent;
   const isGroupChat = sessionCtx.ChatType === "group";
   const wasMentioned = ctx.WasMentioned === true;
@@ -681,3 +694,65 @@ export async function getReplyFromConfig(
     shouldInjectGroupIntro,
   });
 }
+
+async function stageSandboxMedia(params: {
+  ctx: MsgContext;
+  sessionCtx: TemplateContext;
+  cfg: ClawdbotConfig;
+  sessionKey?: string;
+  workspaceDir: string;
+}) {
+  const { ctx, sessionCtx, cfg, sessionKey, workspaceDir } = params;
+  const rawPath = ctx.MediaPath?.trim();
+  if (!rawPath || !sessionKey) return;
+
+  const sandbox = await ensureSandboxWorkspaceForSession({
+    config: cfg,
+    sessionKey,
+    workspaceDir,
+  });
+  if (!sandbox) return;
+
+  let source = rawPath;
+  if (source.startsWith("file://")) {
+    try {
+      source = fileURLToPath(source);
+    } catch {
+      return;
+    }
+  }
+  if (!path.isAbsolute(source)) return;
+
+  const originalMediaPath = ctx.MediaPath;
+  const originalMediaUrl = ctx.MediaUrl;
+
+  try {
+    const fileName = path.basename(source);
+    if (!fileName) return;
+    const destDir = path.join(sandbox.workspaceDir, "media", "inbound");
+    await fs.mkdir(destDir, { recursive: true });
+    const dest = path.join(destDir, fileName);
+    await fs.copyFile(source, dest);
+
+    const relative = path.posix.join("media", "inbound", fileName);
+    ctx.MediaPath = relative;
+    sessionCtx.MediaPath = relative;
+
+    if (originalMediaUrl) {
+      let normalizedUrl = originalMediaUrl;
+      if (normalizedUrl.startsWith("file://")) {
+        try {
+          normalizedUrl = fileURLToPath(normalizedUrl);
+        } catch {
+          normalizedUrl = originalMediaUrl;
+        }
+      }
+      if (normalizedUrl === originalMediaPath || normalizedUrl === source) {
+        ctx.MediaUrl = relative;
+        sessionCtx.MediaUrl = relative;
+      }
+    }
+  } catch (err) {
+    logVerbose(`Failed to stage inbound media for sandbox: ${String(err)}`);
+  }
+}

src/browser/profiles-service.test.ts

@@ -10,10 +10,14 @@ import type {
   BrowserServerState,
 } from "./server-context.js";
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: vi.fn(),
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-  writeConfigFile: vi.fn(async () => {}),
+  return {
-}));
+    ...actual,
+    loadConfig: vi.fn(),
+    writeConfigFile: vi.fn(async () => {}),
+  };
+});
 
 vi.mock("./trash.js", () => ({
   movePathToTrash: vi.fn(async (targetPath: string) => targetPath),

src/browser/server.test.ts

@@ -64,22 +64,26 @@ function makeProc(pid = 123) {
 
 const proc = makeProc();
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => ({
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-    browser: {
+  return {
-      enabled: true,
+    ...actual,
-      controlUrl: `http://127.0.0.1:${testPort}`,
+    loadConfig: () => ({
-      color: "#FF4500",
+      browser: {
-      attachOnly: cfgAttachOnly,
+        enabled: true,
-      headless: true,
+        controlUrl: `http://127.0.0.1:${testPort}`,
-      defaultProfile: "clawd",
+        color: "#FF4500",
-      profiles: {
+        attachOnly: cfgAttachOnly,
-        clawd: { cdpPort: testPort + 1, color: "#FF4500" },
+        headless: true,
+        defaultProfile: "clawd",
+        profiles: {
+          clawd: { cdpPort: testPort + 1, color: "#FF4500" },
+        },
       },
-    },
+    }),
-  }),
+    writeConfigFile: vi.fn(async () => {}),
-  writeConfigFile: vi.fn(async () => {}),
+  };
-}));
+});
 
 const launchCalls = vi.hoisted(() => [] as Array<{ port: number }>);
 vi.mock("./chrome.js", () => ({

src/commands/health.snapshot.test.ts

@@ -10,9 +10,13 @@ import { getHealthSnapshot } from "./health.js";
 let testConfig: Record<string, unknown> = {};
 let testStore: Record<string, { updatedAt?: number }> = {};
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => testConfig,
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-}));
+  return {
+    ...actual,
+    loadConfig: () => testConfig,
+  };
+});
 
 vi.mock("../config/sessions.js", () => ({
   resolveStorePath: () => "/tmp/sessions.json",

src/commands/send.test.ts

@@ -5,9 +5,13 @@ import type { RuntimeEnv } from "../runtime.js";
 import { sendCommand } from "./send.js";
 
 let testConfig: Record<string, unknown> = {};
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => testConfig,
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-}));
+  return {
+    ...actual,
+    loadConfig: () => testConfig,
+  };
+});
 
 const callGatewayMock = vi.fn();
 vi.mock("../gateway/call.js", () => ({

src/commands/sessions.test.ts

@@ -7,11 +7,15 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 // Disable colors for deterministic snapshots.
 process.env.FORCE_COLOR = "0";
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => ({
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-    agent: { model: "pi:opus", contextTokens: 32000 },
+  return {
-  }),
+    ...actual,
-}));
+    loadConfig: () => ({
+      agent: { model: "pi:opus", contextTokens: 32000 },
+    }),
+  };
+});
 
 import { sessionsCommand } from "./sessions.js";
 

src/commands/status.test.ts

@@ -31,9 +31,13 @@ vi.mock("../web/session.js", () => ({
   readWebSelfId: mocks.readWebSelfId,
   logWebSelfId: mocks.logWebSelfId,
 }));
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => ({ session: {} }),
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-}));
+  return {
+    ...actual,
+    loadConfig: () => ({ session: {} }),
+  };
+});
 
 import { statusCommand } from "./status.js";
 

src/gateway/call.test.ts

@@ -9,10 +9,14 @@ let lastClientOptions: {
   onHelloOk?: () => void | Promise<void>;
 } | null = null;
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig,
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-  resolveGatewayPort,
+  return {
-}));
+    ...actual,
+    loadConfig,
+    resolveGatewayPort,
+  };
+});
 
 vi.mock("../infra/tailnet.js", () => ({
   pickPrimaryTailnetIPv4,

src/imessage/monitor.test.ts

@@ -14,9 +14,13 @@ let notificationHandler:
   | undefined;
 let closeResolve: (() => void) | undefined;
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => config,
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-}));
+  return {
+    ...actual,
+    loadConfig: () => config,
+  };
+});
 
 vi.mock("../auto-reply/reply.js", () => ({
   getReplyFromConfig: (...args: unknown[]) => replyMock(...args),

src/imessage/send.test.ts

@@ -5,9 +5,13 @@ import { sendMessageIMessage } from "./send.js";
 const requestMock = vi.fn();
 const stopMock = vi.fn();
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => ({}),
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-}));
+  return {
+    ...actual,
+    loadConfig: () => ({}),
+  };
+});
 
 vi.mock("./client.js", () => ({
   createIMessageRpcClient: vi.fn().mockResolvedValue({

src/telegram/bot.media.test.ts

@@ -31,9 +31,13 @@ vi.mock("@grammyjs/transformer-throttler", () => ({
   apiThrottler: () => throttlerSpy(),
 }));
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => ({}),
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-}));
+  return {
+    ...actual,
+    loadConfig: () => ({}),
+  };
+});
 
 vi.mock("../auto-reply/reply.js", () => {
   const replySpy = vi.fn(async (_ctx, opts) => {

src/telegram/bot.test.ts

@@ -5,9 +5,13 @@ import { createTelegramBot } from "./bot.js";
 const { loadConfig } = vi.hoisted(() => ({
   loadConfig: vi.fn(() => ({})),
 }));
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig,
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-}));
+  return {
+    ...actual,
+    loadConfig,
+  };
+});
 
 const useSpy = vi.fn();
 const onSpy = vi.fn();

src/web/inbound.media.test.ts

@@ -5,18 +5,22 @@ import path from "node:path";
 
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: vi.fn().mockReturnValue({
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-    whatsapp: {
+  return {
-      allowFrom: ["*"], // Allow all in tests
+    ...actual,
-    },
+    loadConfig: vi.fn().mockReturnValue({
-    messages: {
+      whatsapp: {
-      messagePrefix: undefined,
+        allowFrom: ["*"], // Allow all in tests
-      responsePrefix: undefined,
+      },
-      timestampPrefix: false,
+      messages: {
-    },
+        messagePrefix: undefined,
-  }),
+        responsePrefix: undefined,
-}));
+        timestampPrefix: false,
+      },
+    }),
+  };
+});
 
 const HOME = path.join(
   os.tmpdir(),

src/web/monitor-inbox.test.ts

@@ -20,9 +20,13 @@ const mockLoadConfig = vi.fn().mockReturnValue({
   },
 });
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => mockLoadConfig(),
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-}));
+  return {
+    ...actual,
+    loadConfig: () => mockLoadConfig(),
+  };
+});
 
 vi.mock("./session.js", () => {
   const { EventEmitter } = require("node:events");

src/web/test-helpers.ts

@@ -31,13 +31,17 @@ export function resetLoadConfigMock() {
   (globalThis as Record<symbol, unknown>)[CONFIG_KEY] = () => DEFAULT_CONFIG;
 }
 
-vi.mock("../config/config.js", () => ({
+vi.mock("../config/config.js", async (importOriginal) => {
-  loadConfig: () => {
+  const actual = await importOriginal<typeof import("../config/config.js")>();
-    const getter = (globalThis as Record<symbol, unknown>)[CONFIG_KEY];
+  return {
-    if (typeof getter === "function") return getter();
+    ...actual,
-    return DEFAULT_CONFIG;
+    loadConfig: () => {
-  },
+      const getter = (globalThis as Record<symbol, unknown>)[CONFIG_KEY];
-}));
+      if (typeof getter === "function") return getter();
+      return DEFAULT_CONFIG;
+    },
+  };
+});
 
 vi.mock("../media/store.js", () => ({
   saveMediaBuffer: vi