From f7ddab8e942a0e28ce48ed71b4fee5815c07e2d6 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 13 Nov 2026 08:16:44 -0600 Subject: [PATCH] fix(runner): give agent task and workspace reads the workspace page href (#21384) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - People ask a chat agent where the files of a task are. > - The answer must link the page of the workspace that holds the task's files, when that page exists. > - The agent reads the task with `get_task`. The task's `currentExecutionWorkspace` had no `href`. > - The chat directive tells the agent that a workspace without an `href` has no page. So the agent said the page did not exist, although isolated workspaces were on. > - This pull request adds the workspace page `href` to the agent's task and workspace reads, as `get_workspace` already does. > - The benefit is that the agent links the real workspace page and does not make a false claim. ## Linked Issues or Issue Description **What happened?** A person asked the CEO chat agent: "Where are the files for the website task actually being worked on?" The agent named the task workspace and linked the file. It did not link the workspace page. It also said "the workspace has no separate page on this instance". The instance had isolated workspaces on, so the page existed at `//execution-workspaces/`. The chat eval `chat-features.runner-opencode.local.workspaces.locate-files` (OpenCode, `openrouter/deepseek/deepseek-v4.1-flash-1017`) failed its `bound-workspace-page-link` check in four cohorts and in one more paid run for this reason. **Expected behavior** The agent reads the task, gets the workspace page link from the tool result, and links that page in its reply. **Steps to reproduce** 1. Turn on isolated workspaces (`enableIsolatedWorkspaces`). 2. Let an agent complete a projectless task, so the task has a bound execution workspace. 3. In a different chat, ask the CEO where the files of that task are. 4. The agent calls `get_task` for the task. `data.currentExecutionWorkspace` has no `href`. The agent reply names the workspace and says it has no page. **Additional context** `get_workspace` and `list_workspaces` add the page `href` only for the current task. The agent reads another task with `get_task` (`GET /api/issues/{id}`) or with `call_api`. Those results did not get the `href`. The run transcript shows the agent's reasoning: "The task API includes currentExecutionWorkspace with no href", followed by the directive rule "a workspace without an href has no page on this instance". ## What Changed - `server/src/services/task-workspace-tools.ts`: add `withWorkspacePageHref` and `apiResultMayHaveWorkspace`. They add the page `href` to the workspace in successful agent reads of `GET /api/issues/{id}` (`currentExecutionWorkspace`), `GET /api/issues/{id}/workspace` (`workspace`) and `GET /api/execution-workspaces/{id}`. The function uses the same `href` builder as `get_workspace`. It adds no `href` when the page is off, when the read failed, or when the workspace is in a different company. - `server/src/services/native-runtime/paperclip-runner-tool-authority.ts`: apply the function to the results of the task bridge tools (`get_task`) and `call_api`. The tool authority reads the page setting only for these three operations. - Tests: unit tests for the function, and an integration test through the real tool authority and API. The integration test checks `get_task` and `call_api` with workspace pages on (the `href` is present) and off (no `href`). ## Verification - Red/green: with the base tool authority, the new integration test fails (`undefined` instead of `//execution-workspaces/` for both reads). With the fix, it passes. The unit tests fail on the base (4 failures) and pass with the fix. - `cd server && npx vitest run src/__tests__/chat-project-tools.test.ts src/__tests__/task-workspace-tools.test.ts src/__tests__/agent-conversations.test.ts`: 110 passed. - `cd server && npx tsc --noEmit -p .`: passes. - Latency: the change runs only when the agent calls one of the three reads. It does not touch run boot or time to first token. Local `get_task` timing through the tool authority, 40 calls per sample, pages on: base p50 51 ms and 74 ms; fix p50 49 ms and 54 ms. The difference is in the noise. - Paid eval: one narrow run of `chat-features.runner-opencode.local.workspaces.locate-files` on this branch: https://github.com/paperclipai/paperclip/actions/runs/43436040405 (result in a comment below). ## Risks - Low risk. The change only adds an `href` field to three agent read results. It does not change REST responses for the board UI. - The `href` appears only while isolated workspaces are on, because the page route exists only then. This is the same rule `get_workspace` uses. - An agent can now link a workspace page that it read through `get_task`. The page itself still applies normal board access checks. ## Model Used - Claude, Anthropic, model ID `claude-opus-5-5`, used through Claude Code with tool use (shell, file edits, test execution). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- .../src/__tests__/chat-project-tools.test.ts | 26 ++++++++++++++ .../__tests__/task-workspace-tools.test.ts | 34 +++++++++++++++++- .../paperclip-runner-tool-authority.ts | 12 +++++-- server/src/services/task-workspace-tools.ts | 35 +++++++++++++++++++ 4 files changed, 103 insertions(+), 4 deletions(-) diff --git a/server/src/__tests__/chat-project-tools.test.ts b/server/src/__tests__/chat-project-tools.test.ts index 80a4ada56de..c759d2ea881 100644 --- a/server/src/__tests__/chat-project-tools.test.ts +++ b/server/src/__tests__/chat-project-tools.test.ts @@ -38,6 +38,32 @@ import { recoveryPostgresSupport as support } from "./helpers/recovery-postgres. } }); + it("links another task's bound workspace page from get_task and call_api reads only while the page exists", async () => { + const f = await server.fixture({ conversation: true, disableWakeOnDemand: true }); + const [{ issuePrefix }] = await server.db.select({ issuePrefix: companies.issuePrefix }).from(companies).where(eq(companies.id, f.companyId)); + const settings = instanceSettingsService(server.db); + const previous = await settings.getExperimental(); + const [workspace] = await server.db.insert(executionWorkspaces).values({ companyId: f.companyId, + mode: "shared_workspace", strategyType: "project_primary", name: "Website files" }).returning(); + const website = await issueService(server.db).create(f.companyId, { title: "Website task", status: "todo" }); + await server.db.update(issues).set({ executionWorkspaceId: workspace!.id }).where(eq(issues.id, website.id)); + const href = `/${issuePrefix}/execution-workspaces/${workspace!.id}`; + const read = async () => { + const task = await call(f, "get_task", { taskId: website.id }) as { data: { currentExecutionWorkspace: { id: string; href?: string } } }; + const view = await call(f, "call_api", { operationId: "GET /api/issues/{id}/workspace", pathParams: { id: website.id } }) as { data: { workspace: { href?: string } } }; + expect(task.data.currentExecutionWorkspace.id).toBe(workspace!.id); + return [task.data.currentExecutionWorkspace.href, view.data.workspace.href]; + }; + try { + await settings.updateExperimental({ enableIsolatedWorkspaces: true }); + expect(await read()).toEqual([href, href]); + await settings.updateExperimental({ enableIsolatedWorkspaces: false }); + expect(await read()).toEqual([undefined, undefined]); + } finally { + await settings.updateExperimental({ enableIsolatedWorkspaces: previous.enableIsolatedWorkspaces }); + } + }); + it("pages only visible projects and prefilters low-trust agent and run scopes", async () => { const f = await server.fixture({ disableWakeOnDemand: true }); const ids = Array.from({ length: 53 }, (_, i) => `abcdefab-0000-4000-8000-${String(i).padStart(12, "0")}`); diff --git a/server/src/__tests__/task-workspace-tools.test.ts b/server/src/__tests__/task-workspace-tools.test.ts index 2ca60b77574..1eba3f3b5c5 100644 --- a/server/src/__tests__/task-workspace-tools.test.ts +++ b/server/src/__tests__/task-workspace-tools.test.ts @@ -1,5 +1,5 @@ import { afterEach, describe, expect, it, vi } from "vitest"; -import { callTaskWorkspaceTool } from "../services/task-workspace-tools.js"; +import { apiResultMayHaveWorkspace, callTaskWorkspaceTool, withWorkspacePageHref } from "../services/task-workspace-tools.js"; afterEach(() => vi.unstubAllGlobals()); const base = { apiUrl: "https://paperclip.example/api", token: "run-token", companyId: "company", issueId: "task" }; @@ -61,3 +61,35 @@ describe("task workspace semantic transport", () => { expect(fetcher).toHaveBeenCalledTimes(1); }); }); + +describe("workspace page hrefs on agent API reads", () => { + // The chat agent read another task with get_task (GET /api/issues/{id}); its + // currentExecutionWorkspace had no href, so the agent told the person the + // workspace had no page even though the page was enabled. + const workspace = { id: "ws-1", companyId: "company", name: "COM-1", mode: "shared_workspace", cwd: "/srv/ws" }; + const taskRead = { operationId: "GET /api/issues/{id}", ok: true, status: 200, + data: { id: "task-1", identifier: "COM-1", companyId: "company", currentExecutionWorkspace: workspace } }; + it("links the task's bound workspace page when workspace pages are on", () => { + expect(apiResultMayHaveWorkspace(taskRead)).toBe(true); + expect(withWorkspacePageHref(taskRead, "COM", "company")).toEqual({ ...taskRead, + data: { ...taskRead.data, currentExecutionWorkspace: { ...workspace, href: "/COM/execution-workspaces/ws-1" } } }); + }); + it("links the workspace from the task workspace and workspace detail reads", () => { + expect(withWorkspacePageHref({ operationId: "GET /api/issues/{id}/workspace", ok: true, data: { issueId: "task-1", workspace } }, "COM", "company")) + .toMatchObject({ data: { workspace: { id: "ws-1", href: "/COM/execution-workspaces/ws-1" } } }); + expect(withWorkspacePageHref({ operationId: "GET /api/execution-workspaces/{id}", ok: true, data: workspace }, "COM", "company")) + .toMatchObject({ data: { id: "ws-1", href: "/COM/execution-workspaces/ws-1" } }); + }); + it("adds no href when the page is off, the read failed, or the workspace is not this company's", () => { + expect(withWorkspacePageHref(taskRead, null, "company")).toBe(taskRead); + expect(withWorkspacePageHref({ ...taskRead, ok: false }, "COM", "company")).toEqual({ ...taskRead, ok: false }); + expect(withWorkspacePageHref(taskRead, "COM", "other-company")).toBe(taskRead); + const unbound = { ...taskRead, data: { ...taskRead.data, currentExecutionWorkspace: null } }; + expect(withWorkspacePageHref(unbound, "COM", "company")).toBe(unbound); + }); + it("leaves unrelated reads untouched and skips the page setting for them", () => { + const other = { operationId: "GET /api/issues/{id}/runs", ok: true, data: [{ id: "ws-1", companyId: "company" }] }; + expect(apiResultMayHaveWorkspace(other)).toBe(false); + expect(withWorkspacePageHref(other, "COM", "company")).toBe(other); + }); +}); diff --git a/server/src/services/native-runtime/paperclip-runner-tool-authority.ts b/server/src/services/native-runtime/paperclip-runner-tool-authority.ts index ead8a3c426c..1d51e1f483f 100644 --- a/server/src/services/native-runtime/paperclip-runner-tool-authority.ts +++ b/server/src/services/native-runtime/paperclip-runner-tool-authority.ts @@ -22,7 +22,7 @@ import { handoffCaseSchema } from "@paperclipai/shared"; import { skillAccessService } from "../skill-access.js"; import { SKILL_LIBRARY_SCHEMAS, SKILL_LIBRARY_TOOL_DEFINITIONS, SkillLibraryReadCache, executeSkillLibraryTool } from "./native-skill-library-tools.js"; import { withExternalExecutionAdmission, type ExternalAdmissionTransaction } from "../../modules/external-agents/index.js"; -import { callTaskWorkspaceTool, pendingTaskRepositoryContinuation } from "../task-workspace-tools.js"; +import { apiResultMayHaveWorkspace, callTaskWorkspaceTool, pendingTaskRepositoryContinuation, withWorkspacePageHref } from "../task-workspace-tools.js"; import { TaskAttachmentReadCache, TASK_ATTACHMENT_DEFINITIONS, TASK_ATTACHMENT_SCHEMAS, listTaskAttachments, readTaskAttachment } from "./runner-task-attachments.js"; import { RUNNER_BRIDGE_READ_OPERATIONS, RUNNER_BRIDGE_SCHEMAS, runnerBridgeDefinitions, readAssignedSkill, executeWorkspaceTool, readWorkspaceUploadFile, settleRunnerBridgeRead, assertRunnerWorkspacePathAllowed } from "./runner-bridge-tools.js"; import type { NativeRuntimeContextSnapshot } from "../../vendor/paperclip-runner/index.js"; @@ -727,7 +727,7 @@ export class PaperclipRunnerToolAuthority { // read-only options; the shared client still enforces GET-only export. return apiToolResult(await this.#callApi(call.callId, { ...input, saveResponse: true } as RunnerApiCall)); } - return apiToolResult(await this.#callApi(call.callId, taskBridgeApiRequest(call.tool, input))); + return apiToolResult(await this.#withWorkspacePageHref(await this.#callApi(call.callId, taskBridgeApiRequest(call.tool, input)))); } if (this.binding.firstPartyOnly && (call.tool === READ_TOOL_RESULT || this.binding.assignedMcpTools?.has(call.tool) || isConnectorTool(call.tool) || RUNTIME_CONNECTION_TOOL_DEFINITIONS.some(tool => tool.name === call.tool))) throw forbidden("This Grok Bot connection exposes first-party Paperclip operations. Use your own provider apps under their existing permissions."); @@ -925,7 +925,7 @@ export class PaperclipRunnerToolAuthority { // PRP reserves operationId/callId for semantic result identity. The // HTTP operation is metadata, including in previously saved receipts; // exposing it as operationId makes the runner reject a valid response. - return apiToolResult(await this.#callApi(call.callId, call.arguments)); + return apiToolResult(await this.#withWorkspacePageHref(await this.#callApi(call.callId, call.arguments))); } case "get_task_context": { if (this.#apiScope(context).kind === "skill_test") return { @@ -1155,6 +1155,12 @@ export class PaperclipRunnerToolAuthority { ? this.#companyPagePrefix() : null; } + /** Gives workspace reads the same page href get_workspace returns, reading the setting only for those reads. */ + async #withWorkspacePageHref(result: unknown) { + return apiResultMayHaveWorkspace(result) + ? withWorkspacePageHref(result, await this.#workspacePagePrefix(), this.binding.companyId) : result; + } + #apiToken(context: { actor: { adapterType: string }; issue: { workMode: string }; diff --git a/server/src/services/task-workspace-tools.ts b/server/src/services/task-workspace-tools.ts index b06a7eb07eb..e280bfbdda4 100644 --- a/server/src/services/task-workspace-tools.ts +++ b/server/src/services/task-workspace-tools.ts @@ -37,6 +37,41 @@ function workspaceHref(prefix: string | null | undefined, id: unknown) { return prefix && typeof id === "string" ? { href: `/${encodeURIComponent(prefix)}/execution-workspaces/${encodeURIComponent(id)}` } : {}; } +function objectOrNull(value: unknown) { + return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record : null; +} + +/** The API reads that return a workspace, and the field that holds it ("" is the response itself). */ +const WORKSPACE_READ_FIELDS: Readonly> = { + "GET /api/issues/{id}": "currentExecutionWorkspace", + "GET /api/issues/{id}/workspace": "workspace", + "GET /api/execution-workspaces/{id}": "", +}; + +/** True when an agent API result may hold a workspace, so the page prefix is read only then. */ +export function apiResultMayHaveWorkspace(result: unknown) { + const operationId = objectOrNull(result)?.operationId; + return typeof operationId === "string" && Object.hasOwn(WORKSPACE_READ_FIELDS, operationId); +} + +/** + * Adds the workspace page href to an agent's API read of a task or workspace, + * as get_workspace does. Without it the agent reads the missing href as "this + * workspace has no page" and names the workspace instead of linking it. + */ +export function withWorkspacePageHref(result: T, prefix: string | null | undefined, companyId: string): T { + const response = objectOrNull(result); + const operationId = response?.operationId; + const data = objectOrNull(response?.data); + if (!prefix || !response || response.ok !== true || !data || typeof operationId !== "string" + || !Object.hasOwn(WORKSPACE_READ_FIELDS, operationId)) return result; + const field = WORKSPACE_READ_FIELDS[operationId]!; + const workspace = field ? objectOrNull(data[field]) : data; + if (!workspace || workspace.companyId !== companyId || typeof workspace.id !== "string") return result; + const linked = { ...workspace, ...workspaceHref(prefix, workspace.id) }; + return { ...response, data: field ? { ...data, [field]: linked } : linked } as T; +} + function workspacePage(rows: Array>, limit: number) { const workspaces: Array> = []; const result = () => ({ workspaces, limit, returnedCount: workspaces.length,