Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(upload): resolve relative working dirs against /api/file/home (#1106)

chuckbutkus2ed2c571e6fd
diff --git a/AGENTS.md b/AGENTS.md
index d64107b476..d56aad4951 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -179,14 +179,16 @@ you are running inside of β€” NOT the automation backend.
- **State isolation**: `OH_CANVAS_SAFE_STATE_DIR=.tmp/mock-llm-state` isolates test state from the user's real `~/.openhands/agent-canvas/` directory. Both `STATE_DIR` (`.tmp/mock-llm-state`) and the automation DB dir (`.tmp/automation/`) are cleaned before each test run β€” the automation DB now lives outside STATE_DIR at `dirname(STATE_DIR)/automation/automations.db`, mirroring Docker's `~/.openhands/automation/automations.db`.
- **Session API key**: A random key is generated per test run and passed to the stack via `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0` / `VITE_SESSION_API_KEY`. The static server injects it into `index.html` at serve time so the frontend authenticates automatically.
- **Mock LLM server** (`tests/e2e/mock-llm/scripts/mock-llm-server.py`): Python HTTP server using openhands-sdk's `TestLLM` to return scripted tool-call + text trajectories. Supports admin API endpoints for dynamic trajectory management:
- - `POST /admin/reset` β€” reset to the default trajectory (terminal printf + text reply)
+ - `POST /admin/reset` β€” reset to the default trajectory (terminal printf + text reply); also clears the stored completion-request history
- `POST /admin/trajectory/register` β€” register a named trajectory (JSON body: `{name, turns}` where each turn is `{tool_call: {name, arguments}}` or `{text: "..."}`)
- `POST /admin/trajectory/activate` β€” activate a previously registered trajectory
+ - `GET /admin/requests` β€” return the list of all `/v1/chat/completions` request bodies captured since the last reset (used by the image-upload test to verify the image was forwarded to the LLM)
- **Real automation backend**: The automation test uses the production automation backend (started by `bin/agent-canvas.mjs`), NOT a mock server. Terminal `curl` commands from the agent hit the automation API through the ingress proxy at the test's `BACKEND_URL` (default `http://localhost:18300`). Auth uses the `X-Session-API-Key` header matching the stack's session key. The `mock-automation-server.py` file still exists as a reference but is not used by current tests.
-- **Test helpers** (`tests/e2e/mock-llm/utils/mock-llm-helpers.ts`): Exports `registerTrajectory()`, `activateTrajectory()`, `resetMockLLM()`, `ensureMockLLMProfile()`, etc.
+- **Test helpers** (`tests/e2e/mock-llm/utils/mock-llm-helpers.ts`): Exports `registerTrajectory()`, `activateTrajectory()`, `resetMockLLM()`, `ensureMockLLMProfile()`, `getMockLLMRequests()` (fetches captured completion bodies from `GET /admin/requests`), `IMAGE_REPLY_TOKEN` + `MINIMAL_PNG_BASE64` (constants for the image-upload spec), and more.
- **Padding response for internal LLM call**: The agent-server makes an internal LLM call (condenser/skill-analysis) before the agent's main loop starts when skills are activated. This consumes one trajectory response. Automation tests prepend a throwaway `{ text: "" }` response as padding. The conversation test does NOT need this because its user message doesn't trigger skill activation.
- **Test specs**:
- `mock-llm-conversation.spec.ts` β€” Creates LLM profile via UI, runs a conversation with a terminal tool call, verifies bash execution and agent reply.
+ - `mock-llm-image-upload.spec.ts` β€” Attaches a 1Γ—1 PNG via the hidden file input, sends "What is in this image?", verifies the agent replies, that the user message event stores image_urls, and that the mock LLM received an image_url content block with a base64 data: URL in at least one completion call.
- `mock-llm-automation.spec.ts` β€” Full automation lifecycle: registers a trajectory (7 responses total β€” 4 for the main conversation + 3 for the automation run's spawned conversation) where the LLM creates a cron automation and dispatches a run via terminal `curl` commands to the real automation backend. Verifies: automation created with correct schedule, run reaches COMPLETED status with a conversation_id, automation appears on the `/automations` list page, detail page shows COMPLETED badge (`data-testid="run-status-icon-completed"`), and clicking the run's conversation link navigates to the correct `/conversations/{id}` page.
- `mock-llm-partial-stack.spec.ts` β€” Partial stack mode tests. Unlike other specs, these spawn their own `bin/agent-canvas.mjs` child processes instead of relying on the config's webServer entries. Three describe blocks: (1) `--frontend-only` verifies static frontend is served (200 on `/`), backend routes return 503 (`/server_info`, `/api/settings`, `/api/automation/v1`), and the browser shows the manage-backends modal; (2) `--backend-only` verifies `/server_info` returns 200, `/api/settings` is reachable, automation endpoint works, and root/asset requests return 503; (3) port conflict verifies the process exits non-zero with a clear error message when the ingress port is occupied, then starts successfully on a free port. Each test uses isolated state dirs and high port numbers (18310+ range) to avoid collisions with the main full-stack instance.
- Tests run serially (`workers: 1`, `mode: "serial"` per describe block). Files are discovered alphabetically so automation tests run before conversation tests; each spec is self-contained (automation test configures its own LLM profile via the settings API). The `afterEach` hook resets the mock LLM to its default trajectory so subsequent specs start fresh even when a preceding test fails.
diff --git a/__tests__/api/agent-server-conversation-service.test.ts b/__tests__/api/agent-server-conversation-service.test.ts
index 854da8636a..6f72989b99 100644
--- a/__tests__/api/agent-server-conversation-service.test.ts
+++ b/__tests__/api/agent-server-conversation-service.test.ts
@@ -146,6 +146,9 @@ describe("AgentServerConversationService", () => {
);
return response.data;
},
+ // @spec WUP-001 β€” createConversation resolves relative working dirs
+ // via FileClient.getHome before sending the conversation-start payload.
+ getHome: async () => ({ home: "/Users/agent" }),
});
mockSettingsClient.mockReturnValue({
listSecrets: vi.fn().mockResolvedValue({ secrets: [] }),
@@ -284,6 +287,85 @@ describe("AgentServerConversationService", () => {
`/state/workspaces/${secondHex}`,
);
});
+
+ // @spec WUP-001 β€” When the default working_dir is relative, the
+ // conversation-start payload must be anchored against the agent-server
+ // home dir so the worktree and later file uploads agree on a writable
+ // absolute path.
+ it("resolves relative default working dirs against /api/file/home", async () => {
+ const { buildConversationWorkingDir: mockedBuilder } =
+ await import("#/api/agent-server-config");
+ vi.mocked(mockedBuilder).mockImplementationOnce(
+ (id: string) => `workspace/project/${id.replace(/-/g, "")}`,
+ );
+ const { clearAgentServerHomeDirCache } =
+ await import("#/api/agent-server-home");
+ clearAgentServerHomeDirCache();
+
+ mockGetSettings.mockResolvedValue({
+ agent_settings: { llm: { model: "gpt-4o" } },
+ conversation_settings: {},
+ });
+ mockGetSettingsForConversation.mockResolvedValue({
+ agentSettings: { llm: { model: "gpt-4o" } },
+ conversationSettings: {},
+ secretsEncrypted: true,
+ });
+ mockHttpPost.mockResolvedValue({
+ data: {
+ id: "ignored-server-id",
+ created_at: "2024-01-01",
+ updated_at: "2024-01-01",
+ },
+ });
+
+ await AgentServerConversationService.createConversation();
+
+ const [payloadCall] = mockHttpPost.mock.calls;
+ const payload = payloadCall[1] as {
+ conversation_id: string;
+ workspace: { working_dir: string };
+ };
+ const hex = payload.conversation_id.replace(/-/g, "");
+ expect(payload.workspace.working_dir).toBe(
+ `/Users/agent/workspace/project/${hex}`,
+ );
+ });
+
+ // @spec WUP-001 β€” User-supplied workspace overrides are already absolute
+ // (they come from `search_subdirs`), so they must pass through verbatim.
+ it("leaves an absolute workingDirOverride untouched", async () => {
+ mockGetSettings.mockResolvedValue({
+ agent_settings: { llm: { model: "gpt-4o" } },
+ conversation_settings: {},
+ });
+ mockGetSettingsForConversation.mockResolvedValue({
+ agentSettings: { llm: { model: "gpt-4o" } },
+ conversationSettings: {},
+ secretsEncrypted: true,
+ });
+ mockHttpPost.mockResolvedValue({
+ data: {
+ id: "ignored-server-id",
+ created_at: "2024-01-01",
+ updated_at: "2024-01-01",
+ },
+ });
+
+ await AgentServerConversationService.createConversation(
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ "/Users/jane/projects/foo",
+ );
+
+ const [payloadCall] = mockHttpPost.mock.calls;
+ const payload = payloadCall[1] as {
+ workspace: { working_dir: string };
+ };
+ expect(payload.workspace.working_dir).toBe("/Users/jane/projects/foo");
+ });
});
describe("downloadConversation local branch", () => {
diff --git a/__tests__/api/conversation-file-upload.test.ts b/__tests__/api/conversation-file-upload.test.ts
index 5ff8d08176..be83cd27c8 100644
--- a/__tests__/api/conversation-file-upload.test.ts
+++ b/__tests__/api/conversation-file-upload.test.ts
@@ -7,8 +7,10 @@ import {
} from "#/api/backend-registry/active-store";
import type { Backend } from "#/api/backend-registry/types";
import { uploadFilesToConversation } from "#/api/conversation-file-upload.api";
+import { clearAgentServerHomeDirCache } from "#/api/agent-server-home";
const fileUploadMock = vi.fn();
+const getHomeMock = vi.fn();
vi.mock("@openhands/typescript-client/workspace/remote-workspace", () => ({
RemoteWorkspace: vi.fn(function RemoteWorkspaceMock() {
@@ -16,6 +18,12 @@ vi.mock("@openhands/typescript-client/workspace/remote-workspace", () => ({
}),
}));
+vi.mock("@openhands/typescript-client/clients", () => ({
+ FileClient: vi.fn(function FileClientMock() {
+ return { getHome: getHomeMock };
+ }),
+}));
+
const batchGetCloudConversations = vi.fn();
vi.mock("#/api/cloud/conversation-service.api", () => ({
@@ -40,11 +48,16 @@ describe("uploadFilesToConversation", () => {
vi.clearAllMocks();
window.localStorage.clear();
__resetActiveStoreForTests();
+ clearAgentServerHomeDirCache();
fileUploadMock.mockResolvedValue(undefined);
batchGetCloudConversations.mockReset();
+ getHomeMock.mockReset();
+ getHomeMock.mockResolvedValue({ home: "/Users/test" });
});
- it("uploads local conversations through the bundled agent-server host", async () => {
+ // @spec WUP-001 β€” Default-fallback relative working dirs are resolved
+ // against /api/file/home, not the filesystem root.
+ it("uploads local conversations under the agent-server home dir when working dir is relative", async () => {
setRegisteredBackends([
{
id: "local-1",
@@ -62,10 +75,42 @@ describe("uploadFilesToConversation", () => {
expect(fileUploadMock).toHaveBeenCalledWith(
expect.objectContaining({ name: "a.txt" }),
- "/workspace/project/a.txt",
+ "/Users/test/workspace/project/a.txt",
);
expect(result.uploaded_files).toEqual(["a.txt"]);
expect(batchGetCloudConversations).not.toHaveBeenCalled();
+ expect(getHomeMock).toHaveBeenCalled();
+ });
+
+ // @spec WUP-001 β€” Absolute working dirs (e.g. the conversation's own
+ // `workspace.working_dir`) pass through without a /api/file/home round-trip.
+ it("respects an absolute conversation working_dir verbatim", async () => {
+ setRegisteredBackends([
+ {
+ id: "local-1",
+ name: "Local",
+ host: "http://127.0.0.1:18000",
+ apiKey: "local-key",
+ kind: "local",
+ },
+ ]);
+ setActiveSelection({ backendId: "local-1" });
+
+ const result = await uploadFilesToConversation(
+ "conv-1",
+ [makeFile("notes.md")],
+ {
+ id: "conv-1",
+ workspace: { working_dir: "/Users/test/projects/foo" },
+ } as never,
+ );
+
+ expect(fileUploadMock).toHaveBeenCalledWith(
+ expect.objectContaining({ name: "notes.md" }),
+ "/Users/test/projects/foo/notes.md",
+ );
+ expect(result.uploaded_files).toEqual(["notes.md"]);
+ expect(getHomeMock).not.toHaveBeenCalled();
});
it("uploads cloud conversations against the provisioned runtime URL", async () => {
diff --git a/__tests__/api/conversation-service.test.ts b/__tests__/api/conversation-service.test.ts
index 246325538a..30e99a1553 100644
--- a/__tests__/api/conversation-service.test.ts
+++ b/__tests__/api/conversation-service.test.ts
@@ -2,8 +2,10 @@ import { describe, expect, it, vi, beforeEach } from "vitest";
import { RemoteWorkspace } from "@openhands/typescript-client/workspace/remote-workspace";
import ConversationService from "#/api/conversation-service/conversation-service.api";
+import { clearAgentServerHomeDirCache } from "#/api/agent-server-home";
const fileUploadMock = vi.fn();
+const getHomeMock = vi.fn();
vi.mock("@openhands/typescript-client/workspace/remote-workspace", () => ({
RemoteWorkspace: vi.fn(function RemoteWorkspaceMock() {
@@ -11,6 +13,12 @@ vi.mock("@openhands/typescript-client/workspace/remote-workspace", () => ({
}),
}));
+vi.mock("@openhands/typescript-client/clients", () => ({
+ FileClient: vi.fn(function FileClientMock() {
+ return { getHome: getHomeMock };
+ }),
+}));
+
function makeFile(name: string) {
return new File(["content"], name, { type: "text/plain" });
}
@@ -19,9 +27,14 @@ describe("ConversationService", () => {
beforeEach(() => {
vi.clearAllMocks();
ConversationService.setCurrentConversation(null);
+ clearAgentServerHomeDirCache();
+ getHomeMock.mockResolvedValue({ home: "/Users/agent" });
});
describe("uploadFiles", () => {
+ // @spec WUP-001 β€” The default fallback working dir is relative
+ // (`workspace/project`); the upload path is resolved against the
+ // agent-server's home directory via /api/file/home.
it("uploads files through RemoteWorkspace and reports successes", async () => {
fileUploadMock.mockResolvedValue(undefined);
@@ -38,11 +51,11 @@ describe("ConversationService", () => {
);
expect(fileUploadMock).toHaveBeenCalledWith(
expect.objectContaining({ name: "a.txt" }),
- "/workspace/project/a.txt",
+ "/Users/agent/workspace/project/a.txt",
);
expect(fileUploadMock).toHaveBeenCalledWith(
expect.objectContaining({ name: "b.txt" }),
- "/workspace/project/b.txt",
+ "/Users/agent/workspace/project/b.txt",
);
expect(result).toEqual({
uploaded_files: ["a.txt", "b.txt"],
@@ -59,7 +72,7 @@ describe("ConversationService", () => {
expect(fileUploadMock).toHaveBeenCalledWith(
expect.objectContaining({ name: "../../evil.txt" }),
- "/workspace/project/evil.txt",
+ "/Users/agent/workspace/project/evil.txt",
);
expect(result).toEqual({
uploaded_files: ["evil.txt"],
diff --git a/__tests__/api/workspace-upload-path.test.ts b/__tests__/api/workspace-upload-path.test.ts
index 004af6556d..76cebd2d63 100644
--- a/__tests__/api/workspace-upload-path.test.ts
+++ b/__tests__/api/workspace-upload-path.test.ts
@@ -1,34 +1,131 @@
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
import {
buildWorkspaceUploadPath,
getSafeUploadFileName,
+ resolveAbsoluteWorkspacePath,
resolveConversationUploadWorkingDir,
toAbsoluteWorkspacePath,
} from "#/api/workspace-upload-path";
+import { clearAgentServerHomeDirCache } from "#/api/agent-server-home";
-vi.mock("#/api/conversation-service/agent-server-conversation-service.api", () => ({
- default: {
- resolveConversationWorkingDir: vi.fn(
- async (id: string) => `/workspace/project/${id.replace(/-/g, "")}`,
- ),
- },
+const mockGetHome = vi.fn();
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+ FileClient: vi.fn(function FileClientMock() {
+ return { getHome: mockGetHome };
+ }),
+}));
+
+vi.mock("#/api/agent-server-client-options", () => ({
+ getAgentServerClientOptions: vi.fn(() => ({
+ host: "http://localhost:8000",
+ apiKey: "test-key",
+ workingDir: "workspace/project",
+ })),
}));
+vi.mock(
+ "#/api/conversation-service/agent-server-conversation-service.api",
+ () => ({
+ default: {
+ resolveConversationWorkingDir: vi.fn(
+ async (id: string) => `/workspace/project/${id.replace(/-/g, "")}`,
+ ),
+ },
+ }),
+);
+
+beforeEach(() => {
+ clearAgentServerHomeDirCache();
+ mockGetHome.mockReset();
+ mockGetHome.mockResolvedValue({ home: "/Users/test" });
+});
+
describe("workspace-upload-path", () => {
- it("normalizes relative working dirs to absolute paths", () => {
+ // @spec WUP-001 β€” legacy helper kept for cosmetic uses only.
+ it("toAbsoluteWorkspacePath is a naive `/`-prefix and stays sync", () => {
expect(toAbsoluteWorkspacePath("workspace/project")).toBe(
"/workspace/project",
);
- expect(buildWorkspaceUploadPath("a.txt", "workspace/project")).toBe(
- "/workspace/project/a.txt",
+ expect(toAbsoluteWorkspacePath("/already/absolute")).toBe(
+ "/already/absolute",
);
});
+ // @spec WUP-001 β€” resolver anchors relative paths against /api/file/home.
+ it("resolveAbsoluteWorkspacePath joins relative dirs to the agent-server home", async () => {
+ const resolved = await resolveAbsoluteWorkspacePath("workspace/project");
+ expect(resolved).toBe("/Users/test/workspace/project");
+ expect(mockGetHome).toHaveBeenCalledTimes(1);
+ });
+
+ // @spec WUP-001 β€” absolute inputs pass through, no /file/home round-trip.
+ it("resolveAbsoluteWorkspacePath leaves absolute paths alone", async () => {
+ const resolved = await resolveAbsoluteWorkspacePath(
+ "/workspace/project/custom",
+ );
+ expect(resolved).toBe("/workspace/project/custom");
+ expect(mockGetHome).not.toHaveBeenCalled();
+ });
+
+ // @spec WUP-001 β€” Windows-style absolute paths are also pass-through.
+ it("resolveAbsoluteWorkspacePath treats Windows drive-letter paths as absolute", async () => {
+ const resolved = await resolveAbsoluteWorkspacePath("C:\\foo\\bar");
+ expect(resolved).toBe("C:\\foo\\bar");
+ expect(mockGetHome).not.toHaveBeenCalled();
+ });
+
+ // @spec WUP-001 β€” the home dir is cached so concurrent uploads share one round-trip.
+ it("caches the home directory across calls", async () => {
+ await resolveAbsoluteWorkspacePath("workspace/project");
+ await resolveAbsoluteWorkspacePath("other/relative");
+ expect(mockGetHome).toHaveBeenCalledTimes(1);
+ });
+
+ // @spec WUP-001 β€” failures are not cached so a later call retries fresh.
+ it("does not cache failed lookups", async () => {
+ mockGetHome.mockRejectedValueOnce(new Error("boom"));
+ await expect(
+ resolveAbsoluteWorkspacePath("workspace/project"),
+ ).rejects.toThrow("boom");
+
+ mockGetHome.mockResolvedValueOnce({ home: "/Users/test" });
+ const resolved = await resolveAbsoluteWorkspacePath("workspace/project");
+ expect(resolved).toBe("/Users/test/workspace/project");
+ expect(mockGetHome).toHaveBeenCalledTimes(2);
+ });
+
+ // @spec WUP-001 β€” empty or whitespace working dirs collapse to the home dir.
+ it("resolves an empty working dir to the home directory itself", async () => {
+ expect(await resolveAbsoluteWorkspacePath("")).toBe("/Users/test");
+ expect(await resolveAbsoluteWorkspacePath("/")).toBe("/Users/test");
+ });
+
+ // @spec WUP-001 β€” the safe-name helper still strips traversal segments.
it("strips path segments from file names", () => {
expect(getSafeUploadFileName("../../evil.txt")).toBe("evil.txt");
- expect(buildWorkspaceUploadPath("../../evil.txt", "/workspace/project")).toBe(
- "/workspace/project/evil.txt",
+ });
+
+ // @spec WUP-001 β€” buildWorkspaceUploadPath uses the resolver and a safe leaf.
+ it("builds an absolute upload path from a relative working dir", async () => {
+ const upload = await buildWorkspaceUploadPath("a.txt", "workspace/project");
+ expect(upload).toBe("/Users/test/workspace/project/a.txt");
+ });
+
+ it("rejects file names that escape the destination via path traversal", async () => {
+ const upload = await buildWorkspaceUploadPath(
+ "../../evil.txt",
+ "/workspace/project",
);
+ expect(upload).toBe("/workspace/project/evil.txt");
+ });
+
+ it("collapses trailing slashes on the working dir", async () => {
+ const upload = await buildWorkspaceUploadPath(
+ "doc.md",
+ "/workspace/project/",
+ );
+ expect(upload).toBe("/workspace/project/doc.md");
});
it("prefers the active conversation workspace when ids match", async () => {
@@ -46,8 +143,6 @@ describe("workspace-upload-path", () => {
null,
);
- expect(dir).toBe(
- "/workspace/project/550e8400e29b41d4a716446655440000",
- );
+ expect(dir).toBe("/workspace/project/550e8400e29b41d4a716446655440000");
});
});
diff --git a/specs/workspace-upload-path.md b/specs/workspace-upload-path.md
new file mode 100644
index 0000000000..37b46d7621
--- /dev/null
+++ b/specs/workspace-upload-path.md
@@ -0,0 +1,16 @@
+# Workspace Upload Path Specs
+
+---
+
+### WUP-001: Relative working dirs are resolved against `/api/file/home`, not the filesystem root
+- [x] When the frontend creates a conversation and the resolved working dir is **relative** (e.g. the `DEFAULT_WORKING_DIR = "workspace/project"` fallback), `AgentServerConversationService.createConversation` shall resolve it to an **absolute** path before sending `workspace.working_dir` to the agent-server, by prefixing the agent-server's home directory as returned by `GET /api/file/home`.
+- [x] When the frontend uploads a file, `buildWorkspaceUploadPath` shall resolve the conversation's working dir through the same home-directory anchor, so the upload destination always matches the conversation's worktree location.
+- [x] When the working dir is already absolute (e.g. POSIX `/foo`, Windows `C:\foo`, or the explicit selection from `search_subdirs`), the resolver shall pass it through unchanged.
+- [x] The home-directory lookup shall be cached per backend host so concurrent uploads share a single in-flight `/api/file/home` request, and a cached value is reused for subsequent uploads.
+- [x] A failed lookup shall not be cached so the next call retries fresh.
+- [x] The legacy `toAbsoluteWorkspacePath` helper that naively prepends `/` shall remain only for cosmetic/log use; it shall not be used to construct upload paths.
+
+### Why this exists
+- The agent-server's `/api/file/upload` endpoint requires an absolute path and `mkdir -p`s the parent of the destination. Naively prepending `/` to the default `workspace/project/<hex>` produces `/workspace/project/<hex>`. On macOS and on fresh Docker images that mount only `/home/<user>` as writable, the filesystem root is read-only, so the upload fails with `OSError: [Errno 30] Read-only file system: '/workspace'`.
+- The agent-server otherwise interprets a relative `workspace.working_dir` against its process CWD (which is whichever directory the launcher used), so absent this resolver, the conversation's worktree lands in one place and the upload tries to land in a totally different place.
+- `/api/file/home` is the most reliable absolute, writable anchor the agent-server API currently exposes; `/server_info` does not include the CWD.
diff --git a/src/api/agent-server-home.ts b/src/api/agent-server-home.ts
new file mode 100644
index 0000000000..5372cdc4e3
--- /dev/null
+++ b/src/api/agent-server-home.ts
@@ -0,0 +1,114 @@
+// @spec WUP-001 β€” Resolve relative working dirs against /api/file/home
+import { FileClient } from "@openhands/typescript-client/clients";
+import {
+ getAgentServerClientOptions,
+ type AgentServerClientOverrides,
+} from "./agent-server-client-options";
+
+/**
+ * Cache the agent-server's home directory per host so we only round-trip
+ * `/api/file/home` once per backend. The home dir is effectively static for
+ * the lifetime of a running agent-server (it's `Path.home()` on the host),
+ * so caching is safe and avoids hammering the endpoint on every upload.
+ *
+ * The cache holds `Promise<string>` rather than `string` so concurrent
+ * callers share a single in-flight request.
+ */
+const homeDirCache = new Map<string, Promise<string>>();
+
+function isAbsolutePath(path: string): boolean {
+ // Treat POSIX-style and Windows-style absolute paths as absolute.
+ // The agent-server itself is POSIX on Linux/macOS and uses `\\` style
+ // on Windows; we just need to know whether `Path(path).is_absolute()`
+ // would return true on the server.
+ //
+ // Patterns covered:
+ // POSIX absolute: /foo/bar
+ // Windows drive: C:\foo or C:/foo
+ // Windows UNC: \\server\share (starts with `\`, matches `[/\\]`)
+ return /^([/\\]|[a-zA-Z]:[/\\])/.test(path);
+}
+
+/**
+ * Join a parent directory and a relative child segment with a forward slash,
+ * collapsing any duplicate separators that result from the join.
+ */
+function joinPath(parent: string, child: string): string {
+ const left = parent.replace(/[/\\]+$/, "");
+ const right = child.replace(/^[/\\]+/, "");
+ return `${left}/${right}`;
+}
+
+/**
+ * Fetch and cache the agent-server's home directory via `GET /api/file/home`.
+ *
+ * The result is the absolute path returned by `Path.home()` on the
+ * agent-server host (e.g. `/Users/foo`, `/root`, or `C:\\Users\\Foo`). This
+ * is the most reliable absolute, writable anchor the agent-server API
+ * currently exposes β€” `/server_info` doesn't include the process CWD.
+ *
+ * @param overrides Same shape as `getAgentServerClientOptions` β€” lets cloud
+ * sandboxes pass a `conversationUrl` + `sessionApiKey` so the lookup goes
+ * to the per-conversation runtime rather than the bundled local backend.
+ */
+export async function getAgentServerHomeDir(
+ overrides: AgentServerClientOverrides = {},
+): Promise<string> {
+ const options = getAgentServerClientOptions(overrides);
+ const cacheKey = options.host;
+ const cached = homeDirCache.get(cacheKey);
+ if (cached) return cached;
+
+ const lookup = (async () => {
+ const { home } = await new FileClient(options).getHome();
+ if (!home || typeof home !== "string") {
+ throw new Error("Agent server returned an empty home directory");
+ }
+ return home.replace(/[/\\]+$/, "");
+ })();
+
+ homeDirCache.set(cacheKey, lookup);
+ try {
+ return await lookup;
+ } catch (error) {
+ // Don't cache failures β€” let the next call retry.
+ homeDirCache.delete(cacheKey);
+ throw error;
+ }
+}
+
+/** Test-only helper. */
+export function clearAgentServerHomeDirCache(): void {
+ homeDirCache.clear();
+}
+
+/**
+ * Resolve a (possibly relative) working dir to an absolute path the
+ * agent-server's file APIs will accept.
+ *
+ * - If `workingDir` is already absolute, returns it unchanged.
+ * - Otherwise prepends the agent-server's home dir (looked up via
+ * `/api/file/home` and cached). This matches how the published binary
+ * and Docker entrypoint expect to anchor relative working dirs: under
+ * `~/workspace/project` rather than the filesystem root.
+ *
+ * Why this matters: the agent-server's `/api/file/upload` endpoint requires
+ * an absolute path and `mkdir -p`s the parent. Naively prepending `/` to a
+ * relative dir like `workspace/project/<hex>` produces `/workspace/...`,
+ * which on macOS lives under the SIP-protected read-only root and fails
+ * with `Errno 30: Read-only file system: '/workspace'`. Resolving against
+ * `Path.home()` instead puts the path somewhere reliably writable.
+ */
+export async function resolveAbsoluteAgentServerPath(
+ workingDir: string,
+ overrides: AgentServerClientOverrides = {},
+): Promise<string> {
+ const trimmed = workingDir.replace(/[/\\]+$/, "");
+ if (!trimmed) {
+ return getAgentServerHomeDir(overrides);
+ }
+ if (isAbsolutePath(trimmed)) return trimmed;
+
+ const home = await getAgentServerHomeDir(overrides);
+ return joinPath(home, trimmed);
+}
diff --git a/src/api/conversation-file-upload.api.ts b/src/api/conversation-file-upload.api.ts
index b83f0ab15a..d07e54db9e 100644
--- a/src/api/conversation-file-upload.api.ts
+++ b/src/api/conversation-file-upload.api.ts
@@ -132,7 +132,16 @@ async function uploadFilesToRuntime(options: {
const uploadFile = async (file: File) => {
try {
const safeName = getSafeUploadFileName(file.name);
- const uploadPath = buildWorkspaceUploadPath(file.name, workingDir);
+ // @spec WUP-001 β€” Build an absolute upload path that's anchored against
+ // the agent-server's home dir (when `workingDir` is relative) instead
+ // of the filesystem root. Without this, default conversations whose
+ // working_dir is `workspace/project/<hex>` (relative) land at
+ // `/workspace/project/<hex>/...` on the agent-server, which on macOS
+ // and fresh containers is a read-only mount.
+ const uploadPath = await buildWorkspaceUploadPath(file.name, workingDir, {
+ conversationUrl,
+ sessionApiKey,
+ });
await workspace.fileUpload(file, uploadPath);
return { uploadedFile: safeName, skippedFile: null };
} catch (error) {
diff --git a/src/api/conversation-service/agent-server-conversation-service.api.ts b/src/api/conversation-service/agent-server-conversation-service.api.ts
index 09b217986a..bb2f57b1cc 100644
--- a/src/api/conversation-service/agent-server-conversation-service.api.ts
+++ b/src/api/conversation-service/agent-server-conversation-service.api.ts
@@ -16,6 +16,7 @@ import {
buildConversationWorkingDir,
getAgentServerWorkingDir,
} from "../agent-server-config";
+import { resolveAbsoluteAgentServerPath } from "../agent-server-home";
import {
getActiveBackend,
getEffectiveLocalBackend,
@@ -375,8 +376,15 @@ class AgentServerConversationService {
const settings = await SettingsService.getSettings();
const conversationId = uuidv4();
- const workingDir =
- workingDirOverride ?? buildConversationWorkingDir(conversationId);
+ // @spec WUP-001 β€” Send an absolute working_dir to the agent-server.
+ // The default is `workspace/project/<hex>` (relative); without
+ // resolving it here, `/api/file/upload` later prepends `/` and writes
+ // to `/workspace/...` (read-only on macOS and fresh containers). When
+ // the user picks an explicit workspace, `workingDirOverride` is
+ // already absolute (it comes from `search_subdirs`).
+ const workingDir = await resolveAbsoluteAgentServerPath(
+ workingDirOverride ?? buildConversationWorkingDir(conversationId),
+ );
// Use encrypted settings to avoid exposing secrets in the browser
const payload = await buildStartConversationRequestWithEncryptedSettings({
diff --git a/src/api/workspace-upload-path.ts b/src/api/workspace-upload-path.ts
index a8026890c3..4548b734db 100644
--- a/src/api/workspace-upload-path.ts
+++ b/src/api/workspace-upload-path.ts
@@ -1,5 +1,11 @@
+// @spec WUP-001 β€” Resolve relative working dirs against /api/file/home
import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
import { getAgentServerWorkingDir } from "#/api/agent-server-config";
+import {
+ type AgentServerClientOverrides,
+ getAgentServerClientOptions,
+} from "#/api/agent-server-client-options";
+import { resolveAbsoluteAgentServerPath } from "#/api/agent-server-home";
import { getStoredConversationMetadata } from "#/api/conversation-metadata-store";
import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
@@ -17,20 +23,66 @@ export function getSafeUploadFileName(fileName: string): string {
return safeName;
}
-/** Normalize agent-server working_dir values to absolute sandbox paths. */
+/**
+ * @deprecated The old `prepend `/` if not already absolute` behaviour is the
+ * root cause of #XXXX (relative `workspace/project` β†’ `/workspace/project`,
+ * which is on a read-only mount on macOS / fresh containers). Callers that
+ * need an actual absolute path must use {@link resolveAbsoluteWorkspacePath}
+ * so the relative leg is anchored against `/api/file/home` instead.
+ *
+ * Kept for the rare callers that genuinely just want a leading-slash
+ * normaliser on a value already known to be agent-server-rooted (e.g.
+ * cosmetic display, log strings).
+ */
export function toAbsoluteWorkspacePath(path: string): string {
return path.startsWith("/") ? path : `/${path}`;
}
-export function buildWorkspaceUploadPath(
+/**
+ * Resolve `workingDir` to an absolute path the agent-server's file APIs
+ * accept. Relative paths are joined against `/api/file/home` (cached per
+ * backend); absolute paths pass through.
+ */
+export async function resolveAbsoluteWorkspacePath(
+ workingDir: string,
+ overrides: AgentServerClientOverrides = {},
+): Promise<string> {
+ return resolveAbsoluteAgentServerPath(workingDir, overrides);
+}
+
+/**
+ * Build the absolute destination path for a file upload, resolving the
+ * working-dir leg via {@link resolveAbsoluteWorkspacePath}.
+ */
+export async function buildWorkspaceUploadPath(
fileName: string,
workingDir: string,
-): string {
+ overrides: AgentServerClientOverrides = {},
+): Promise<string> {
const safeName = getSafeUploadFileName(fileName);
- const base = toAbsoluteWorkspacePath(workingDir.replace(/\/+$/, ""));
- return `${base}/${safeName}`;
+ const absoluteDir = await resolveAbsoluteWorkspacePath(workingDir, overrides);
+ return `${absoluteDir.replace(/[/\\]+$/, "")}/${safeName}`;
}
+/**
+ * Resolve the working directory for a file upload into a conversation's
+ * workspace.
+ *
+ * **Returns the raw working dir string** β€” which may be relative (e.g.
+ * `workspace/project/<hex>`) when the default `DEFAULT_WORKING_DIR` is in
+ * use. Callers that need an actual filesystem-absolute path (e.g. to pass to
+ * the agent-server's `/api/file/upload` endpoint) **must** funnel this result
+ * through {@link buildWorkspaceUploadPath}, which calls
+ * {@link resolveAbsoluteWorkspacePath} to anchor any relative segment against
+ * the agent-server's home directory.
+ *
+ * Why not resolve here? Because this function is also called by cloud-runtime
+ * upload paths where the overrides (conversationUrl, sessionApiKey) aren't
+ * available until {@link uploadFilesToConversation} assembles them. Keeping
+ * the resolution step in {@link buildWorkspaceUploadPath} means both the
+ * local and cloud legs share a single resolution point with the correct
+ * override context.
+ */
export async function resolveConversationUploadWorkingDir(
conversationId: string,
currentConversation?: AppConversation | null,
@@ -55,3 +107,8 @@ export async function resolveConversationUploadWorkingDir(
return getAgentServerWorkingDir();
}
+
+// Re-export so callers can construct overrides matching what
+// {@link buildWorkspaceUploadPath} expects without importing two modules.
+export type { AgentServerClientOverrides };
+export { getAgentServerClientOptions };
diff --git a/src/hooks/mutation/use-conversation-upload-files.ts b/src/hooks/mutation/use-conversation-upload-files.ts
index 4e6cf669d7..59df9d0624 100644
--- a/src/hooks/mutation/use-conversation-upload-files.ts
+++ b/src/hooks/mutation/use-conversation-upload-files.ts
@@ -29,9 +29,25 @@ export const useConversationUploadFiles = () =>
const { conversationUrl, sessionApiKey, workingDir, files } = variables;
const uploadPromises = files.map(async (file) => {
+ // @spec WUP-001 β€” Resolve once so both the success and failure
+ // branches report the same absolute path.
+ let filePath: string;
+ try {
+ filePath = await buildWorkspaceUploadPath(file.name, workingDir, {
+ conversationUrl,
+ sessionApiKey,
+ });
+ } catch (error) {
+ return {
+ success: false as const,
+ fileName: file.name,
+ filePath: file.name,
+ error: error instanceof Error ? error.message : "Unknown error",
+ };
+ }
+
try {
const safeName = getSafeUploadFileName(file.name);
- const filePath = buildWorkspaceUploadPath(file.name, workingDir);
await new RemoteWorkspace(
getAgentServerClientOptions({
conversationUrl,
@@ -44,7 +60,7 @@ export const useConversationUploadFiles = () =>
return {
success: false as const,
fileName: file.name,
- filePath: buildWorkspaceUploadPath(file.name, workingDir),
+ filePath,
error: error instanceof Error ? error.message : "Unknown error",
};
}
diff --git a/tests/e2e/mock-llm/mock-llm-image-upload.spec.ts b/tests/e2e/mock-llm/mock-llm-image-upload.spec.ts
new file mode 100644
index 0000000000..a4b71f568c
--- /dev/null
+++ b/tests/e2e/mock-llm/mock-llm-image-upload.spec.ts
@@ -0,0 +1,279 @@
+/**
+ * Mock-LLM E2E: image attachment is embedded as base64 and forwarded to LLM.
+ *
+ * Covers the fix from PR #1106: relative working-dir paths no longer resolve
+ * to a read-only root, so file uploads (and image attachments processed via
+ * the same pipeline) land in the correct writable location.
+ *
+ * Flow:
+ * 1. Configure mock LLM profile via the settings API (skips UI setup).
+ * 2. Register a scripted trajectory: one text reply with IMAGE_REPLY_TOKEN.
+ * 3. Attach a minimal 1Γ—1 PNG to the home-page chat input via the hidden
+ * file input (`data-testid="upload-image-input"`).
+ * 4. Wait for the submit button to become enabled (image processed into
+ * the Zustand store β†’ canSubmit flips to true).
+ * 5. Type "What is in this image?" and submit.
+ * 6. After the conversation is created and the agent replies:
+ * a. Verify IMAGE_REPLY_TOKEN appears in the chat UI.
+ * b. Verify the user's conversation event has image_urls set.
+ * c. Verify at least one LLM completion call to the mock server
+ * included an image_url content block (base64 data: URL).
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+ IMAGE_REPLY_TOKEN,
+ MINIMAL_PNG_BASE64,
+ waitForAgentMessageContaining,
+ waitForNonUserMessageText,
+ getMockLLMRequests,
+ BACKEND_URL,
+ SESSION_API_KEY,
+ seedLocalStorage,
+ routeSessionApiKey,
+ dismissAnalyticsModal,
+ waitForTestId,
+ waitForPath,
+ getConversationIdFromURL,
+ deleteConversation,
+ resetMockLLM,
+ registerTrajectory,
+ activateTrajectory,
+ ensureMockLLMProfile,
+ setChatInput,
+} from "./utils/mock-llm-helpers";
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const USER_MESSAGE = "What is in this image?";
+const TRAJECTORY_NAME = "image-query";
+
+// ── Test suite ────────────────────────────────────────────────────────────────
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("mock-LLM image upload", () => {
+ let conversationId: string | null = null;
+
+ test.beforeEach(async ({ page }) => {
+ await seedLocalStorage(page);
+ });
+
+ test.afterEach(async ({ request }) => {
+ if (conversationId) {
+ try {
+ await deleteConversation(request, conversationId);
+ } catch {
+ // best-effort cleanup
+ }
+ conversationId = null;
+ }
+ await resetMockLLM(request);
+ });
+
+ // ── Main test ──────────────────────────────────────────────────────────────
+
+ test("attaching an image embeds it as base64 in the LLM completion call", async ({
+ page,
+ request,
+ }) => {
+ // ── 1. Configure mock LLM via API (avoids repeating the UI profile steps) ──
+ // Use a vision-capable model name so litellm does not strip image_url
+ // content blocks when constructing the completion request. The base_url
+ // still points at the local mock server; the model name is purely a hint
+ // to litellm about what content types the model accepts.
+
+ await ensureMockLLMProfile(request, "openai/gpt-4o");
+
+ // ── 2. Register and activate the trajectory ──
+ // The mock LLM ignores the request body, so we don't need the agent to
+ // "understand" the image β€” we just want a reply that proves the LLM was
+ // called and the conversation completed successfully.
+ //
+ // ⚠️ Padding note (mirrors the automation test's pattern):
+ // When public skills are loaded (VITE_LOAD_PUBLIC_SKILLS !== "false"),
+ // the agent-server may make one internal LLM call for skill-analysis
+ // before the agent loop starts, consuming one trajectory slot.
+ // Turn 0 is a throwaway empty response that absorbs this internal call.
+ // Turn 1 is the agent's actual reply (IMAGE_REPLY_TOKEN).
+ // Turn 2 is a safety buffer in case a follow-up internal call is made.
+
+ await resetMockLLM(request); // clears request history too
+ await registerTrajectory(request, TRAJECTORY_NAME, [
+ { text: "" }, // 0: padding β€” absorbs any internal skill-activation call
+ { text: IMAGE_REPLY_TOKEN }, // 1: agent's actual reply
+ { text: "" }, // 2: safety buffer for any follow-up internal call
+ ]);
+ await activateTrajectory(request, TRAJECTORY_NAME);
+
+ // ── 3. Navigate to the home page ──
+
+ await routeSessionApiKey(page);
+ await page.goto("/", { waitUntil: "domcontentloaded" });
+ await dismissAnalyticsModal(page);
+ await waitForTestId(page, "home-chat-launcher");
+
+ // ── 4. Attach the test image via the hidden file input ──
+ // Playwright's setInputFiles works on hidden inputs without needing a
+ // visible click target. The onChange handler (handleFileInputChange β†’
+ // handleUpload β†’ processImages β†’ addImages) runs asynchronously in
+ // React, so we wait for the submit button to become enabled afterwards.
+
+ await page.locator('[data-testid="upload-image-input"]').setInputFiles({
+ name: "test-image.png",
+ mimeType: "image/png",
+ buffer: Buffer.from(MINIMAL_PNG_BASE64, "base64"),
+ });
+
+ // Wait for the image to be processed (FileReader async + Zustand store
+ // update). Once images.length > 0 the submit button stops being disabled.
+ await expect(page.getByTestId("submit-button")).not.toBeDisabled({
+ timeout: 10_000,
+ });
+
+ // ── 5. Type the user message and submit ──
+ // setChatInput sets innerText directly so the chat doesn't need visible
+ // typing; the InputEvent dispatch keeps canSubmit in sync.
+
+ await setChatInput(page, USER_MESSAGE);
+
+ // Confirm submit button is still enabled after text is added
+ await expect(page.getByTestId("submit-button")).not.toBeDisabled({
+ timeout: 5_000,
+ });
+
+ await page.getByTestId("submit-button").click();
+
+ // ── 6a. Wait for the conversation page ──
+
+ await waitForPath(page, /\/conversations\/.+/, 30_000);
+ conversationId = getConversationIdFromURL(page);
+
+ // ── 6b. Verify agent reply appears in the chat UI ──
+
+ await test.step("agent reply token appears in chat UI", async () => {
+ await waitForNonUserMessageText(page, IMAGE_REPLY_TOKEN, 30_000);
+ });
+
+ // ── 6c. Verify agent reply captured in conversation events API ──
+
+ await test.step("agent reply captured in conversation events", async () => {
+ await waitForAgentMessageContaining(
+ request,
+ conversationId!,
+ IMAGE_REPLY_TOKEN,
+ 15_000,
+ );
+ });
+
+ // ── 6d. Verify user message includes image_urls in conversation events ──
+ // The agent-server stores the user's message as a MessageEvent whose
+ // content array contains an "image" block with base64 data URLs.
+
+ await test.step("user message event includes image_urls", async () => {
+ let lastDiag = "no polls yet";
+ await expect
+ .poll(
+ async () => {
+ const resp = await request.get(
+ `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId!)}/events/search`,
+ {
+ headers: { "X-Session-API-Key": SESSION_API_KEY },
+ params: { limit: "50", sort_order: "TIMESTAMP_DESC" },
+ },
+ );
+ if (!resp.ok()) {
+ lastDiag = `events API: ${resp.status()}`;
+ return false;
+ }
+ const body = (await resp.json()) as { items?: unknown[] };
+ const items = body.items ?? [];
+ lastDiag = `${items.length} events`;
+
+ return items.some((e: any) => {
+ if (e.source !== "user") return false;
+ // Check llm_message.content for image blocks (REST send path)
+ if (Array.isArray(e.llm_message?.content)) {
+ if (
+ e.llm_message.content.some(
+ (c: any) =>
+ c.type === "image" &&
+ Array.isArray(c.image_urls) &&
+ c.image_urls.length > 0,
+ )
+ )
+ return true;
+ }
+ // Fall back: args.image_urls (WebSocket send path)
+ const imageUrls = e.args?.image_urls;
+ return Array.isArray(imageUrls) && imageUrls.length > 0;
+ });
+ },
+ { timeout: 15_000 },
+ )
+ .toBe(true)
+ .catch((err) => {
+ throw new Error(
+ `User message event should have image_urls after 15s.\n${lastDiag}`,
+ { cause: err },
+ );
+ });
+ });
+
+ // ── 6e. Verify the LLM completion call included image content ──
+ // The mock server stores every /v1/chat/completions request body since
+ // the last reset. At least one should contain an image_url content
+ // block with a base64 data: URL, confirming the frontend embedded the
+ // image rather than dropping it.
+
+ await test.step("LLM completion call included image_url content", async () => {
+ const llmRequests = await getMockLLMRequests(request);
+
+ expect(
+ llmRequests.length,
+ "mock LLM should have received at least one completion request",
+ ).toBeGreaterThan(0);
+
+ // Helper: recursively walk any JSON value looking for a base64 image URL.
+ function containsImageUrl(value: unknown): boolean {
+ if (typeof value === "string") {
+ return value.startsWith("data:image/");
+ }
+ if (Array.isArray(value)) {
+ return value.some(containsImageUrl);
+ }
+ if (value !== null && typeof value === "object") {
+ return Object.values(value as Record<string, unknown>).some(
+ containsImageUrl,
+ );
+ }
+ return false;
+ }
+
+ const anyRequestHadImage = llmRequests.some(containsImageUrl);
+ expect(
+ anyRequestHadImage,
+ `At least one LLM completion call should include a base64 image data: URL.\n` +
+ `Received ${llmRequests.length} request(s).\n` +
+ llmRequests
+ .map(
+ (req, i) =>
+ `Request ${i} messages:\n` +
+ JSON.stringify((req as any)?.messages ?? [], null, 2).slice(
+ 0,
+ 800,
+ ),
+ )
+ .join("\n---\n"),
+ ).toBe(true);
+ });
+
+ // ── 6f. Verify no error banners appeared ──
+
+ await test.step("no error banners", async () => {
+ await expect(page.getByTestId("error-message-banner")).not.toBeVisible({
+ timeout: 2_000,
+ });
+ });
+ });
+});
diff --git a/tests/e2e/mock-llm/scripts/mock-llm-server.py b/tests/e2e/mock-llm/scripts/mock-llm-server.py
index c54917e835..f58c0141d2 100644
--- a/tests/e2e/mock-llm/scripts/mock-llm-server.py
+++ b/tests/e2e/mock-llm/scripts/mock-llm-server.py
@@ -77,10 +77,22 @@ class MockLLMHandler(BaseHTTPRequestHandler):
# Named trajectories that tests can register via the admin API and then
# activate with POST /admin/trajectory/activate.
_named_trajectories: dict[str, list[Message | Exception]] = {}
+ # All completion request bodies since the last /admin/reset.
+ # Tests read them via GET /admin/requests to verify image / content details.
+ # Stored as a list so assertions survive even when the agent-server makes
+ # multiple LLM calls (e.g., internal condenser calls after the main turn).
+ _completion_requests: list = []
_lock = threading.Lock()
def do_GET(self):
- """Health check β€” Playwright's webServer probes GET / to detect readiness."""
+ """Health check and admin read endpoints."""
+ path = self.path.rstrip("/").split("?")[0]
+ if path == "/admin/requests":
+ with self._lock:
+ payload = list(MockLLMHandler._completion_requests)
+ self._send_json(200, {"requests": payload})
+ return
+ # Default: health check β€” Playwright's webServer probes GET / to detect readiness.
self._send_json(200, {"status": "ok", "server": "mock-llm"})
def do_POST(self):
@@ -91,6 +103,7 @@ class MockLLMHandler(BaseHTTPRequestHandler):
with self._lock:
MockLLMHandler.test_llm = TestLLM.from_messages(build_trajectory())
MockLLMHandler._named_trajectories.clear()
+ MockLLMHandler._completion_requests.clear()
remaining = MockLLMHandler.test_llm.remaining_responses
self._send_json(200, {
"status": "reset",
@@ -149,6 +162,11 @@ class MockLLMHandler(BaseHTTPRequestHandler):
length = int(self.headers.get("Content-Length", 0))
body = json.loads(self.rfile.read(length)) if length else {}
+ # Append to request history for test verification.
+ # Tests can GET /admin/requests to confirm image content was included.
+ with self._lock:
+ MockLLMHandler._completion_requests.append(body)
+
try:
response = self.test_llm.completion([])
except TestLLMExhaustedError:
diff --git a/tests/e2e/mock-llm/utils/mock-llm-helpers.ts b/tests/e2e/mock-llm/utils/mock-llm-helpers.ts
index 28073137f6..b557a6affd 100644
--- a/tests/e2e/mock-llm/utils/mock-llm-helpers.ts
+++ b/tests/e2e/mock-llm/utils/mock-llm-helpers.ts
@@ -12,6 +12,18 @@ export const BASH_TOKEN = "MOCK_LLM_E2E_BASH_OK";
export const REPLY_TOKEN = "MOCK_LLM_E2E_REPLY_OK";
export const BASH_COMMAND = `printf '${BASH_TOKEN}\\n'`;
+/** Reply token used by the image-upload test trajectory. */
+export const IMAGE_REPLY_TOKEN = "MOCK_LLM_IMAGE_OK";
+
+/**
+ * A minimal valid 1Γ—1 white pixel PNG, base64-encoded.
+ * Used as a lightweight test fixture for image-upload E2E tests β€” small
+ * enough to keep request bodies manageable while still being a real PNG that
+ * the browser's FileReader can process.
+ */
+export const MINIMAL_PNG_BASE64 =
+ "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVQI12NgAAIABQAABjE+ibYAAAAASUVORK5CYII=";
+
// Ports / URLs β€” set via env or defaults matching playwright.mock-llm.config.ts.
// The agent-canvas binary exposes a single ingress port; API calls are proxied
// through it, so BACKEND_URL = ingress URL (no separate backend port).
@@ -403,12 +415,29 @@ export async function activateTrajectory(
/**
* Reset the mock LLM server to its default trajectory.
+ * Also clears the stored completion-request history.
*/
export async function resetMockLLM(request: APIRequestContext) {
const resp = await request.post(`${MOCK_LLM_BASE_URL}/admin/reset`);
expect(resp.ok(), `Reset mock LLM: ${resp.status()}`).toBe(true);
}
+/**
+ * Fetch all chat-completion request bodies captured by the mock LLM server
+ * since the last /admin/reset.
+ *
+ * The server stores every POST to /v1/chat/completions, so callers can assert
+ * that at least one request contained image content (or any other field).
+ */
+export async function getMockLLMRequests(
+ request: APIRequestContext,
+): Promise<Record<string, unknown>[]> {
+ const resp = await request.get(`${MOCK_LLM_BASE_URL}/admin/requests`);
+ expect(resp.ok(), `GET /admin/requests: ${resp.status()}`).toBe(true);
+ const body = await resp.json();
+ return (body.requests as Record<string, unknown>[]) ?? [];
+}
+
/**
* Set contentEditable chat input text and dispatch an input event.
*