From 653ab8b18f76287800af85ab60b117f2eee8f8e2 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:54:24 -0600 Subject: [PATCH] fix(chat): answer "my inbox" from the person's Mine list (#20334) 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 > - Agent Chat lets a person ask an agent about their own work, such as "what in my inbox needs my attention?" > - Agents find API routes through the agent API catalog, which is built from the OpenAPI registry > - The catalog described `GET /api/agents/me/inbox/mine` as the current agent's assigned items and listed no `userId` parameter. The skill reference for the route is keyed with `?userId={}`, so it never attached to the catalog entry > - A chat agent called the route without `userId`, got 400, and then answered from an unscoped company task search. It named company work that is not in the person's inbox and did not link the person's Mine list > - This pull request documents the route as the person's Mine list with a required `userId`, and adds one chat guidance paragraph for inbox questions > - The benefit is that inbox answers use the person's own task scope and link their Mine list ## Linked Issues or Issue Description **What happened** A person asked a CEO chat agent: "What in my inbox needs my attention today?" The agent called `GET /api/agents/me/inbox/mine` without `userId` and got 400. Then it listed every company task, including an unrelated agent-created maintenance task. It said the person's inbox was board-only and did not link the Mine list. **Expected behavior** The agent reads the person's Mine list with `GET /api/agents/me/inbox/mine?userId=`. It answers from those tasks only, links each task it cites, and links the Mine list at `//inbox/mine`. If the read fails, it says so and links Mine. **Steps to reproduce** 1. As a board user, participate in some tasks. Let an agent create an unrelated task in the same company. 2. In Agent Chat with the CEO, ask "What in my inbox needs my attention today?" 3. The agent calls the Mine route without `userId` (400) and lists all company tasks. ## What Changed - `server/src/routes/openapi.ts`: `GET /api/agents/me/inbox/mine` now has a summary and description that say it is a person's Mine list, not the agent's own queue. It documents the required `userId` query parameter and the optional `status` parameter, and the 400 response. - `server/src/services/agent-conversations.ts`: one chat guidance paragraph. For inbox questions, read the Mine route with the `authorUserId` of the person's message, answer from those tasks only, and link `[Mine](//inbox/mine)` (it opens the Mine view in every layout). If the read fails, say so and link Mine. - Regression tests in `openapi-routes.test.ts` and `agent-conversations.test.ts`. ## Verification - `npx vitest run src/__tests__/openapi-routes.test.ts src/__tests__/agent-conversations.test.ts src/__tests__/heartbeat-list.test.ts` (in `server/`): 107 passed. The two new tests fail without the source change. - `npx vitest run src/services/native-runtime/runner-api.test.ts`: 2075 passed. - Live chat eval `inbox-search.show-my-work` on the eval candidate with this commit: see the comment below for the run result. ## Risks - Low risk. The change is catalog text, one query schema in the OpenAPI document, and one chat guidance paragraph. The route behavior does not change. - The chat prompt grows by about 500 characters. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), tool use and code execution in Claude Code. ## 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 --- server/src/__tests__/agent-conversations.test.ts | 6 ++++++ server/src/__tests__/openapi-routes.test.ts | 9 +++++++++ server/src/routes/openapi.ts | 11 +++++++++-- server/src/services/agent-conversations.ts | 2 ++ 4 files changed, 26 insertions(+), 2 deletions(-) diff --git a/server/src/__tests__/agent-conversations.test.ts b/server/src/__tests__/agent-conversations.test.ts index 6b9eb5dce3a..36044477657 100644 --- a/server/src/__tests__/agent-conversations.test.ts +++ b/server/src/__tests__/agent-conversations.test.ts @@ -1023,6 +1023,12 @@ describe("chat prompt policy", () => { expect(prompt).toContain("npx paperclipai issue document:get --json | jq -r .body > "); }); + it("answers a person's inbox question from their Mine list and links Mine", () => { + expect(AGENT_CHAT_DIRECTIVE).toContain("GET /api/agents/me/inbox/mine?userId=, using the authorUserId of their message"); + expect(AGENT_CHAT_DIRECTIVE).toContain("your own queue and a company-wide task search are not their inbox"); + expect(AGENT_CHAT_DIRECTIVE).toContain("[Mine](//inbox/mine)"); + }); + it("tells chat where a person can hire when the agent cannot", () => { expect(AGENT_CHAT_DIRECTIVE).toContain("send the person to the hire form at //agents/new"); expect(AGENT_CHAT_DIRECTIVE).toContain("to your own /permissions page, where they can turn on hiring for you"); diff --git a/server/src/__tests__/openapi-routes.test.ts b/server/src/__tests__/openapi-routes.test.ts index 5ab9bd45bfd..3bb221462f6 100644 --- a/server/src/__tests__/openapi-routes.test.ts +++ b/server/src/__tests__/openapi-routes.test.ts @@ -342,6 +342,15 @@ describe("openapi routes", () => { expect(route.post.description).toContain("--acknowledge-retention"); }); + it("documents the agent Mine inbox read as a person's inbox that requires their user id", () => { + const operation = buildOpenApiSpec().paths["/api/agents/me/inbox/mine"].get; + expect(operation.summary).not.toMatch(/current agent/i); + expect(operation.description).toContain("//inbox/mine"); + expect(operation.description).toContain("not your own work queue"); + const userId = operation.parameters.find((parameter: { name: string; in: string }) => parameter.name === "userId" && parameter.in === "query"); + expect(userId).toMatchObject({ required: true }); + }); + it("documents the export include body so agents can request projects and skills", () => { const spec = buildOpenApiSpec(); for (const path of ["/api/companies/{companyId}/exports", "/api/companies/{companyId}/exports/preview"]) { diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts index 6beaf9a6171..9494cf8a321 100644 --- a/server/src/routes/openapi.ts +++ b/server/src/routes/openapi.ts @@ -3761,8 +3761,15 @@ registry.registerPath({ method: "get", path: "/api/agents/me/inbox/mine", tags: ["agents"], - summary: "Get current agent assigned inbox items", - responses: { 200: r.ok(), 401: r.unauthorized }, + summary: "List a person's Mine inbox tasks", + description: "Agent read of one board user's personal inbox: the tasks that person participated in and has not archived, the same set as their Mine list, which they open at //inbox/mine. Use it when a person asks what is in their inbox or needs their attention; it is not your own work queue (GET /api/agents/me/inbox-lite) and a company-wide task search is not a substitute. userId is required: use the person's user id, such as the authorUserId of their message.", + request: { + query: z.object({ + userId: z.string().min(1).describe("The person's user id, such as the authorUserId of their message. Required."), + status: z.string().optional().describe("Comma-separated task statuses; defaults to the Mine list statuses (cancelled excluded)."), + }), + }, + responses: { 200: r.ok(), 400: r.badRequest, 401: r.unauthorized }, }); registry.registerPath({ diff --git a/server/src/services/agent-conversations.ts b/server/src/services/agent-conversations.ts index 30e9a252f0c..ab05abed70e 100644 --- a/server/src/services/agent-conversations.ts +++ b/server/src/services/agent-conversations.ts @@ -124,6 +124,8 @@ When a reply concerns a specific agent, such as one you paused, resumed, configu When a reply lists many tasks, write each task identifier in full, such as RUN-12, RUN-13, RUN-14. This conversation links each full identifier to its task, but a range such as RUN-12–14 links only its first task and leaves the others without a source link. When a complete list is too long to read in the reply, save it as a document on this conversation's task and link it, such as [Open work by owner](//issues/#document-), keeping a short summary with the counts in the reply. +When the person asks what is in their inbox or what needs their attention, read their own list with GET /api/agents/me/inbox/mine?userId=, using the authorUserId of their message. Answer from those tasks only: your own queue and a company-wide task search are not their inbox, so do not name or link tasks outside it. Link each task you cite and their list as [Mine](//inbox/mine), which opens their personal Mine view in every layout; do not send them to look through an inbox page for it. If that read fails, say so and link Mine instead of answering from other tasks. + A person's own display name and avatar belong to their account, and only they can change them in their profile settings at //company/settings/instance/profile. Agent credentials cannot edit a person's profile, and renaming an agent, a member record or the company does not change it. When the person asks to change their own name or avatar, link that page instead of attempting the change. Some developer labs, including the task-chat interaction lab at //dev/task-chat-lab, are registered only in a development build of the UI. A production or hosted instance has no task-chat lab page and no setting turns one on, so do not probe its bundle or try to open the lab with a browser. Tell the person the task-chat lab is development-only and that they can open it by running pnpm dev in their own Paperclip checkout and visiting //dev/task-chat-lab on that dev server. Other lab pages, such as the design guide and the ux-lab pages, are registered in every build, so open those normally.