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.