From 6d8f59d49430d389ed419212f923d0f6dc93bfc7 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Thu, 12 Nov 2026 05:46:26 -0600 Subject: [PATCH] fix(api): name the secret binding proposal as the way to give an agent a company secret (#21090) 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 > - Chat agents find product API routes through the runner API search, which ranks operations by their OpenAPI summary and description > - In the chat eval `secrets.configure-company-secret`, a person asked the CEO to let Morgan use an existing deployment API key > - The agent searched for agent configuration and environment variable routes, tried `PATCH /api/agents/{id}` (403) and spent 3.5 minutes before it used `POST /api/agents/me/secret-proposals` > - The summary "Propose a company secret or agent secret binding" did not match how agents describe the task > - This pull request rewrites the summary and adds a description that names the binding fields > - The benefit is that the first search finds the supported route, so the turn is short ## Linked Issues or Issue Description **What happened?** Runner API search did not rank `POST /api/agents/me/secret-proposals` for the queries an agent uses to give another agent a company secret ("agent configuration update env secret", "agent environment variables set secret ref"). The agent probed other routes for 3.5 minutes. **Expected behavior** Those searches return the secret binding proposal route in the first results, and the result explains `secretId`, `configPath` and `targetAgentId`. **Steps to reproduce** Call `searchRunnerApi({ query: "agent configuration update env secret", limit: 3 })` on master. The proposal route is not in the results. ## What Changed - `server/src/routes/openapi.ts`: new summary and description for `POST /api/agents/me/secret-proposals`. The description states the reporting-line target rule, the `env.` config path, and that a board member approves the binding. - `server/src/__tests__/secret-binding-discovery.test.ts`: the four queries return the route in their top three results. The test fails on master (red) and passes with this change (green). ## Verification - `npx vitest run` on 24 server guidance, discovery, OpenAPI and runner API test files: 2305 passed. - `node tests/runner-e2e/source-sdk-public-inputs.mjs --check`: `changed: false`. - Paid chat eval run: see the PR comment. ## Risks - Low. Only OpenAPI text changes. Other search results can move down by one place for queries that share these words. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with 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 --- .../__tests__/secret-binding-discovery.test.ts | 17 +++++++++++++++++ server/src/routes/openapi.ts | 4 +++- 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 server/src/__tests__/secret-binding-discovery.test.ts diff --git a/server/src/__tests__/secret-binding-discovery.test.ts b/server/src/__tests__/secret-binding-discovery.test.ts new file mode 100644 index 00000000000..fa33024268f --- /dev/null +++ b/server/src/__tests__/secret-binding-discovery.test.ts @@ -0,0 +1,17 @@ +import { expect, it } from "vitest"; +import { searchRunnerApi } from "../services/native-runtime/runner-api-catalog.js"; + +it("finds the secret binding proposal when an agent searches for how to give an agent a company secret", () => { + for (const query of [ + "agent configuration update env secret", + "agent environment variables set secret ref", + "agent configuration environment variables bind secret reference", + "give agent access to company secret", + ]) { + const { results } = searchRunnerApi({ query, limit: 3 }); + expect(results.map(operation => operation.operationId), query).toContain("POST /api/agents/me/secret-proposals"); + } + const operation = searchRunnerApi({ query: "POST /api/agents/me/secret-proposals" }).results[0]!; + expect(operation.description).toContain("configPath"); + expect(operation.description).toContain("targetAgentId"); +}); diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts index 843d85134c5..5a5a89497e6 100644 --- a/server/src/routes/openapi.ts +++ b/server/src/routes/openapi.ts @@ -3697,7 +3697,9 @@ registry.registerPath({ method: "post", path: "/api/agents/me/secret-proposals", tags: ["secrets"], - summary: "Propose a company secret or agent secret binding", + summary: "Bind an existing company secret to an agent's environment variable, or propose a new company secret, for board approval", + description: + "This is how an agent gives itself or an agent in its reporting line (targetAgentId) access to a company secret: send kind \"binding\" with the secret's id from the secrets catalog and the agent configuration path (configPath, e.g. env.DEPLOY_API_KEY). Agents cannot PATCH agent configuration with secret refs; a board member approves the proposal, which applies the binding. Send kind \"secret\" to propose storing a new value.", request: { body: jsonBody(createAgentSecretProposalSchema) }, responses: { 201: r.ok(),