mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents reach external apps through MCP connections. Paperclip
records each call and shows it as a tool row in the task chat.
> - MCP Apps (SEP-1865, extension `io.modelcontextprotocol/ui`, spec
2026-01-26) lets an MCP server attach an interactive `ui://` view to a
tool. Claude, Claude Code and VS Code render these views in chat.
Circleback uses them to show meeting cards.
> - Paperclip dropped the tool's `_meta.ui` at discovery and the
result's `_meta` at call time. Its gateway reported MCP App UI as
"unsupported". Circleback was reachable only through Composio, whose
toolkit has no `Display*` tools.
> - This pull request makes Paperclip an MCP Apps host. It also adds
Circleback as a native catalog connection.
> - The benefit is that a Circleback recap in a task shows the same
meeting cards as in Claude, and any other MCP server with views works
the same way.
## Linked Issues or Issue Description
**Subsystem affected**
Connections and apps (remote MCP gateway) and the task chat.
**Problem or motivation**
An agent that uses Circleback in Paperclip can only return text. The
same tools in Claude Code show interactive meeting cards
(`DisplayMeetings`). Paperclip discards the MCP Apps metadata, so it
cannot show them.
**Proposed solution**
Paperclip implements the host side of MCP Apps end to end. It keeps the
tool's view declaration and records each call that has a view. It
renders the view under the tool row in a sandboxed iframe that uses the
MCP Apps postMessage protocol. Circleback becomes a native catalog
connection, so its `Display*` tools are available.
**Alternatives considered**
Composio's `circleback_mcp` toolkit has 11 read tools and no `Display*`
tools, and its meta-tools return plain JSON, so it cannot carry views.
The spec's double-iframe sandbox proxy on a separate origin needs a
second origin that Paperclip does not have. A single opaque-origin
`srcdoc` frame with an injected CSP gives the same isolation.
**Roadmap alignment**
This extends the existing Apps catalog and MCP gateway. It adds no new
integration substrate (decision D4 in doc/connections/README.md).
**Additional context**
The standard, the design and the testing plan are in
`doc/connections/MCP-APPS.md`.
## What Changed
- **Shared:** `packages/shared/src/mcp-apps.ts` adds MCP Apps types,
`_meta.ui` and resource parsing (current and legacy keys), and a CSP
builder that keeps only well-formed `https` origins.
- **DB:** migration `0471` (`online_compatible`) adds
`tool_catalog_entries.ui_meta` and a new `tool_mcp_app_views` table.
- **Server, catalog:** discovery keeps each tool's `_meta.ui`. It is not
part of the version hash, so a view never quarantines a reviewed tool.
- **Server, gateway:**
- Paperclip advertises the MCP Apps client capability when it
initializes a session.
- App-only tools (`visibility: ["app"]`) are hidden from agents.
- The result `_meta` is kept for the view and is not sent to the agent.
- Each successful call to a tool with a view records a view row.
Recording is best effort.
- The gateway's `initialize` now reports `paperclip/mcp-app-ui:
host_rendered`.
- The context protocol (`resources/read`) now uses the injected test
transport, like the other remote calls.
- **Server, routes:** `server/src/routes/mcp-apps.ts`
- `GET /api/issues/:issueId/mcp-app-views` lists a task's views. It
needs task read access.
- `GET /api/issues/:issueId/mcp-app-views/:viewId` returns the view
document, read live through the agent's connection.
- `POST /api/issues/:issueId/mcp-app-views/:viewId/tool-calls` runs the
view's `tools/call`. It needs `tools:use` and reaches only tools of the
same connection that allow `app`. It uses the connection test-call path,
so policy, Ask first and audit apply.
- **UI:** `ui/src/components/mcp-app/`
- The host protocol: `ui/initialize` with theme, style variables and
size limits; tool-input; tool-result; size-changed; `tools/call`;
`ui/open-link` (http and https only); teardown.
- An opaque-origin iframe (`allow-scripts`, never `allow-same-origin`)
with the CSP placed before the view's markup.
- The views of a run render with that run's reply, in the live turn and
in settled history. They are keyed by the reply's run, so history needs
no transcript.
- **Circleback:** a native catalog app (`mcp-oauth`, DCR, `user
user:write`) with:
- the official logo;
- a reviewed risk classifier (Share* tools are writes, Delete* tools are
destructive, Display* tools are reads);
- warnings in the sign-in step;
- `doc/connections/CIRCLEBACK.md`.
Search now prefers a native app over an aggregator listing named "X
MCP".
- **Storybook:** `Tasks/MCP App views` shows the tool row with its view,
the ready state (Refresh calls a tool), loading, view unavailable, and a
tool call that needs approval.
## Verification
- `pnpm exec vitest run packages/shared/src/mcp-apps.test.ts
ui/src/components/mcp-app/`: 19 passed.
- `pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts`: 3
passed, on embedded Postgres. The test connects Circleback through the
catalog with DCR OAuth against a fake Circleback MCP server. It checks:
- `ui_meta` is stored;
- an app-only tool is hidden from the agent;
- an agent call records one view with arguments, structured content and
`_meta`;
- a call without a view records nothing;
- the routes serve the view's HTML and CSP;
- the view's tool call works and a model-only tool is refused;
- another task, another company and an agent actor are refused.
- Circleback connector: 13 focused files, 645 tests passed. These are
the app definitions, search, aggregator fallback, connection intents,
tool policy, `AppsConnect` and `Browse`.
- Typecheck passed for `@paperclipai/shared`, `@paperclipai/server` and
`@paperclipai/ui`. `node scripts/storybook-catalog.mjs` and the
migration compatibility check also passed.
- Storybook check in the browser:
- In both themes, the view runs the handshake, renders the meeting cards
from `structuredContent`, picks up the theme variables, and resizes to
its content.
- Refresh sends `tools/call` and re-renders the cards.
- **Live Circleback end to end** on a local instance, with a real
Circleback account:
- Connected through the catalog entry with Circleback's dynamic client
registration and OAuth.
- Discovery stored the real view declarations:
- `DisplayMeetings` uses `ui://circleback/meetings.v2.html`.
- `DisplayActionItems` and `DisplayCalendarEvents` also have views.
- `ListAssigneeOptions` and `SetCalendarEventRecording` are app-only
helpers with no view. They are hidden from agents.
- A `claude_local` agent called `DisplayMeetings` on two tasks.
- The real 3.5 MB Circleback view rendered the meeting cards with the
agent's reply.
- Clicking a card opened that meeting in Circleback through
`ui/open-link`.
- The live run found two bugs, both fixed in this PR, each with a
regression test:
- The 1 MB tool-result limit blocked the view document.
- Views were hidden inside the folded tool history.
## Risks
- **New migration:** a new table and a nullable column. It is
`online_compatible`.
- **Existing connections:** tools get `ui_meta` on the next catalog
refresh. Until then, no view shows and the tool row is unchanged.
- **Untrusted provider HTML:** the view runs as provider HTML in an
opaque-origin sandbox. It cannot reach Paperclip's session, DOM or API.
Its network access is limited to the origins its server declared. A
view's tool calls use the viewer's permissions and the normal policy and
Ask-first path.
- **Agent tool lists:** app-only tools are removed from them. No current
provider marks tools app-only, so no listed tool disappears.
- **Search:** the change that prefers a native app over an "X MCP"
aggregator listing affects every app.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
subagents (one subagent authored the Circleback catalog connector).
## 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
- [ ] 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 <noreply@anthropic.com>
754 lines
33 KiB
TypeScript
754 lines
33 KiB
TypeScript
export const queryKeys = {
|
|
linkPreview: (companyId: string, userId: string | null, url: string) =>
|
|
["link-preview", companyId, userId, url] as const,
|
|
workspacePreferences: {
|
|
mine: (userId: string | null) => ["workspace-preferences", userId] as const,
|
|
},
|
|
agentCommentary: {
|
|
list: (companyId: string, filters: object) => ["agent-commentary", companyId, "list", filters] as const,
|
|
detail: (companyId: string, id: string | null) => ["agent-commentary", companyId, "detail", id] as const,
|
|
},
|
|
skillSources: {
|
|
projects: (companyId: string) => ['project-skill-repositories', companyId] as const,
|
|
preview: (companyId: string, repositoryUrl: string, connectionId: string | null, commitSha: string | null, skillPath: string, filePath: string) => ['skill-sources', companyId, 'preview', repositoryUrl, connectionId, commitSha, skillPath, filePath] as const,
|
|
all: (companyId: string) => ["skill-sources", companyId] as const,
|
|
repositories: (companyId: string) => ["skill-source-repositories", companyId] as const,
|
|
},
|
|
agentChats: {
|
|
list: (companyId: string | null, userId?: string | null) =>
|
|
["agent-chats", companyId, userId] as const,
|
|
detail: (companyId: string | null, userId: string | null, agentId: string | undefined) =>
|
|
["agent-chat", companyId, userId, agentId] as const,
|
|
},
|
|
companies: {
|
|
/**
|
|
* Prefix for everything company-shaped. Matches the list, details and stats
|
|
* below, so an `invalidateQueries` against it still reaches all of them.
|
|
* Not a cache entry of its own — the list lives under `list()`.
|
|
*/
|
|
all: ["companies"] as const,
|
|
/**
|
|
* The company list, scoped to the account it was fetched for. Which
|
|
* companies you belong to is an answer about *you*, and a single shared
|
|
* entry made it look like an answer about the app: for 30 seconds after an
|
|
* account change the previous account's list was served to anyone who
|
|
* asked. A different account is a different entry, so there is nothing to
|
|
* mistake. `null` is the signed-out/local_trusted key.
|
|
*/
|
|
list: (userId: string | null) =>
|
|
["companies", "list", userId ?? "anonymous"] as const,
|
|
directory: (userId: string | null) =>
|
|
["companies", "directory", userId ?? "anonymous"] as const,
|
|
detail: (id: string) => ["companies", id] as const,
|
|
stats: ["companies", "stats"] as const,
|
|
exportFidelity: (companyId: string) =>
|
|
["companies", companyId, "export-fidelity"] as const,
|
|
},
|
|
apps: {
|
|
gallery: (companyId: string) => ["apps", companyId, "gallery"] as const,
|
|
attention: (companyId: string) => ["apps", companyId, "attention"] as const,
|
|
connectionReviewCounts: (companyId: string, connectionId: string) =>
|
|
["apps", companyId, "attention", "connection", connectionId, "review-counts"] as const,
|
|
},
|
|
chatEndpoints: {
|
|
list: (companyId: string) => ["chat-endpoints", companyId] as const,
|
|
detail: (endpointId: string) => ["chat-endpoints", "detail", endpointId] as const,
|
|
resources: (endpointId: string) => ["chat-endpoints", endpointId, "resources"] as const,
|
|
principals: (endpointId: string) => ["chat-endpoints", endpointId, "principals"] as const,
|
|
conversations: (endpointId: string) => ["chat-endpoints", endpointId, "conversations"] as const,
|
|
activity: (endpointId: string) => ["chat-endpoints", endpointId, "activity"] as const,
|
|
},
|
|
tools: {
|
|
aggregatorApps: (connectionId: string, userId: string | null) => ["tools", "aggregator-apps", connectionId, userId] as const,
|
|
composioApps: (connectionId: string) => ["tools", "composio-apps", connectionId] as const,
|
|
applications: (companyId: string) =>
|
|
["tools", companyId, "applications"] as const,
|
|
connections: (companyId: string) =>
|
|
["tools", companyId, "connections"] as const,
|
|
connection: (connectionId: string) =>
|
|
["tools", "connection", connectionId] as const,
|
|
connectionInstalls: (connectionId: string) =>
|
|
["tools", "connection", connectionId, "installs"] as const,
|
|
connectionGrants: (connectionId: string) =>
|
|
["tools", "connection", connectionId, "grants"] as const,
|
|
catalog: (connectionId: string) => ["tools", "connection", connectionId, "catalog"] as const,
|
|
connectionActivity: (connectionId: string) =>
|
|
["tools", "connection", connectionId, "activity"] as const,
|
|
testAgents: (connectionId: string) =>
|
|
["tools", "connection", connectionId, "test-agents"] as const,
|
|
testAgentAccesses: () => ["tools", "test-agent-access"] as const,
|
|
testAgentAccessesForConnection: (connectionId: string) =>
|
|
["tools", "test-agent-access", connectionId] as const,
|
|
testAgentAccess: (connectionId: string, agentId: string) =>
|
|
["tools", "test-agent-access", connectionId, agentId] as const,
|
|
testCallStatus: (connectionId: string, actionRequestId: string) =>
|
|
[
|
|
"tools",
|
|
"connection",
|
|
connectionId,
|
|
"test-calls",
|
|
actionRequestId,
|
|
] as const,
|
|
actionRequests: (companyId: string, status: string) =>
|
|
["tools", companyId, "action-requests", status] as const,
|
|
gateways: (companyId: string) => ["tools", "gateways", companyId] as const,
|
|
connectionProfileConfiguration: (companyId: string, connectionId: string) =>
|
|
["tools", companyId, "profiles", "connection-configuration", connectionId] as const,
|
|
profiles: (companyId: string) => ["tools", companyId, "profiles"] as const,
|
|
profileNewTools: (profileId: string) =>
|
|
["tools", "profiles", profileId, "new-tools"] as const,
|
|
effectiveProfilesForAgent: (companyId: string, agentId: string) =>
|
|
["tools", companyId, "profiles", "effective", "agent", agentId] as const,
|
|
stdioTemplates: (companyId: string) =>
|
|
["tools", companyId, "stdio-templates"] as const,
|
|
runtimeSlots: (companyId: string) =>
|
|
["tools", companyId, "runtime-slots"] as const,
|
|
runtimeHealth: (companyId: string) =>
|
|
["tools", companyId, "runtime-health"] as const,
|
|
runDecisions: (companyId: string, runId: string) =>
|
|
["tools", companyId, "runs", runId, "decisions"] as const,
|
|
liveRuntimeSlots: (companyId: string) =>
|
|
["tools", companyId, "runtime-slots", "live"] as const,
|
|
policies: (companyId: string) => ["tools", companyId, "policies"] as const,
|
|
trustRules: (companyId: string) =>
|
|
["tools", companyId, "trust-rules"] as const,
|
|
audit: (companyId: string, limit: number) =>
|
|
["tools", companyId, "audit", limit] as const,
|
|
activity: (
|
|
companyId: string,
|
|
filters: { gateway?: string; app?: string; agent?: string; outcome?: string; window?: string; search?: string },
|
|
) =>
|
|
[
|
|
"tools",
|
|
companyId,
|
|
"activity",
|
|
filters.gateway ?? "__all",
|
|
filters.app ?? "__all",
|
|
filters.agent ?? "__all",
|
|
filters.outcome ?? "__all",
|
|
filters.window ?? "24h",
|
|
filters.search ?? "",
|
|
] as const,
|
|
},
|
|
audit: {
|
|
runs: (companyId: string, agentId?: string | null) =>
|
|
["audit", companyId, "runs", agentId ?? "__all"] as const,
|
|
agentActions: (
|
|
companyId: string,
|
|
filters: {
|
|
actorScope?: "agents" | "all" | null;
|
|
agentId?: string | null;
|
|
responsibleUserId?: string | null;
|
|
runId?: string | null;
|
|
entityType?: string | null;
|
|
entityId?: string | null;
|
|
action?: string | null;
|
|
from?: string | null;
|
|
to?: string | null;
|
|
actorType?: string | null;
|
|
},
|
|
) =>
|
|
[
|
|
"audit",
|
|
companyId,
|
|
"agent-actions",
|
|
filters.actorScope ?? "agents",
|
|
filters.agentId ?? "__all",
|
|
filters.responsibleUserId ?? "__all",
|
|
filters.runId ?? "__all",
|
|
filters.entityType ?? "__all",
|
|
filters.entityId ?? "__all",
|
|
filters.action ?? "__all",
|
|
filters.actorType ?? "__all",
|
|
filters.from ?? "",
|
|
filters.to ?? "",
|
|
] as const,
|
|
},
|
|
smokeLab: {
|
|
services: (companyId: string) =>
|
|
["smoke-lab", companyId, "services"] as const,
|
|
runs: (companyId: string) => ["smoke-lab", companyId, "runs"] as const,
|
|
run: (companyId: string, runId: string) =>
|
|
["smoke-lab", companyId, "runs", runId] as const,
|
|
},
|
|
companySkills: {
|
|
list: (companyId: string) => ["company-skills", companyId] as const,
|
|
listRecent: (companyId: string) =>
|
|
["company-skills", companyId, "recent-updated"] as const,
|
|
detail: (companyId: string, skillId: string) =>
|
|
["company-skills", companyId, skillId] as const,
|
|
versions: (companyId: string, skillId: string) =>
|
|
["company-skills", companyId, skillId, "versions"] as const,
|
|
comments: (companyId: string, skillId: string) =>
|
|
["company-skills", companyId, skillId, "comments"] as const,
|
|
updateStatus: (companyId: string, skillId: string) =>
|
|
["company-skills", companyId, skillId, "update-status"] as const,
|
|
forkPrecheck: (companyId: string, skillId: string) =>
|
|
["company-skills", companyId, skillId, "fork-precheck"] as const,
|
|
file: (companyId: string, skillId: string, relativePath: string) =>
|
|
["company-skills", companyId, skillId, "file", relativePath] as const,
|
|
catalog: (filters: { kind?: string; category?: string; q?: string } = {}) =>
|
|
[
|
|
"company-skills",
|
|
"catalog",
|
|
filters.kind ?? "__all-kinds__",
|
|
filters.category ?? "__all-categories__",
|
|
filters.q ?? "",
|
|
] as const,
|
|
catalogDetail: (catalogRef: string) =>
|
|
["company-skills", "catalog", "detail", catalogRef] as const,
|
|
catalogFile: (catalogRef: string, relativePath: string) =>
|
|
["company-skills", "catalog", "file", catalogRef, relativePath] as const,
|
|
testInputs: (companyId: string, skillId: string) =>
|
|
["company-skills", companyId, skillId, "test-inputs"] as const,
|
|
testRunTemplates: (companyId: string) =>
|
|
["company-skills", companyId, "test-run-templates"] as const,
|
|
testRuns: (companyId: string, skillId: string, inputId?: string | null) =>
|
|
[
|
|
"company-skills",
|
|
companyId,
|
|
skillId,
|
|
"test-runs",
|
|
inputId ?? "__all-inputs__",
|
|
] as const,
|
|
testRunDetail: (companyId: string, skillId: string, runId: string) =>
|
|
["company-skills", companyId, skillId, "test-run", runId] as const,
|
|
},
|
|
teamCatalog: {
|
|
catalog: (filters: { kind?: string; category?: string; q?: string } = {}) =>
|
|
[
|
|
"team-catalog",
|
|
"catalog",
|
|
filters.kind ?? "__all-kinds__",
|
|
filters.category ?? "__all-categories__",
|
|
filters.q ?? "",
|
|
] as const,
|
|
catalogDetail: (catalogRef: string) =>
|
|
["team-catalog", "catalog", "detail", catalogRef] as const,
|
|
catalogFile: (catalogRef: string, relativePath: string) =>
|
|
["team-catalog", "catalog", "file", catalogRef, relativePath] as const,
|
|
installed: (companyId: string) =>
|
|
["team-catalog", "installed", companyId] as const,
|
|
},
|
|
agents: {
|
|
projectAccess: (id: string) => ["agents", "detail", id, "project-access"] as const,
|
|
identity: (id: string) => ["agents", "identity", id] as const,
|
|
list: (companyId: string) => ["agents", companyId] as const,
|
|
detail: (id: string) => ["agents", "detail", id] as const,
|
|
runtimeState: (id: string) => ["agents", "runtime-state", id] as const,
|
|
taskSessions: (id: string) => ["agents", "task-sessions", id] as const,
|
|
skills: (id: string) => ["agents", "skills", id] as const,
|
|
instructionsBundle: (id: string) =>
|
|
["agents", "instructions-bundle", id] as const,
|
|
instructionCandidates: (id: string) =>
|
|
["agents", "instruction-candidates", id] as const,
|
|
instructionsFile: (id: string, relativePath: string) =>
|
|
["agents", "instructions-bundle", id, "file", relativePath] as const,
|
|
keys: (agentId: string) => ["agents", "keys", agentId] as const,
|
|
configRevisions: (agentId: string) =>
|
|
["agents", "config-revisions", agentId] as const,
|
|
adapterModels: (
|
|
companyId: string,
|
|
adapterType: string,
|
|
environmentId?: string | null,
|
|
provider?: string,
|
|
) =>
|
|
[
|
|
"agents",
|
|
companyId,
|
|
"adapter-models",
|
|
adapterType,
|
|
environmentId ?? null,
|
|
provider ?? null,
|
|
] as const,
|
|
detectModel: (companyId: string, adapterType: string) =>
|
|
["agents", companyId, "detect-model", adapterType] as const,
|
|
authSignal: (companyId: string, adapterType: string, environmentId?: string | null) =>
|
|
["agents", companyId, "auth-signal", adapterType, environmentId ?? null] as const,
|
|
activeLoginSession: (companyId: string, adapterType: string) =>
|
|
["agents", companyId, "active-login-session", adapterType] as const,
|
|
},
|
|
builtInAgents: {
|
|
list: (companyId: string) => ["built-in-agents", companyId] as const,
|
|
},
|
|
summarySlots: {
|
|
detail: (
|
|
companyId: string,
|
|
scopeKind: string,
|
|
slotKey: string,
|
|
scopeId?: string | null,
|
|
) =>
|
|
[
|
|
"summary-slots",
|
|
companyId,
|
|
scopeKind,
|
|
slotKey,
|
|
scopeId ?? null,
|
|
] as const,
|
|
revisions: (
|
|
companyId: string,
|
|
scopeKind: string,
|
|
slotKey: string,
|
|
scopeId?: string | null,
|
|
) =>
|
|
[
|
|
"summary-slots",
|
|
companyId,
|
|
scopeKind,
|
|
slotKey,
|
|
scopeId ?? null,
|
|
"revisions",
|
|
] as const,
|
|
},
|
|
statusCards: {
|
|
list: (companyId: string, archived: boolean) =>
|
|
["status-cards", companyId, archived ? "archived" : "active"] as const,
|
|
detail: (id: string) => ["status-cards", "detail", id] as const,
|
|
updates: (id: string) => ["status-cards", "detail", id, "updates"] as const,
|
|
summaryRevisions: (id: string) =>
|
|
["status-cards", "detail", id, "summary-revisions"] as const,
|
|
dryRun: (id: string) => ["status-cards", "detail", id, "dry-run"] as const,
|
|
},
|
|
mcpApps: {
|
|
views: (issueId: string) => ["mcp-app-views", issueId] as const,
|
|
detail: (issueId: string, viewId: string) => ["mcp-app-views", issueId, "detail", viewId] as const,
|
|
},
|
|
issues: {
|
|
recoveryActions: (id: string, actionId: string | null, runId: string | null) =>
|
|
["issues", id, "recovery-actions", actionId, runId] as const,
|
|
allRecoveryActions: (id: string) => ["issues", id, "recovery-actions"] as const,
|
|
list: (companyId: string) => ["issues", companyId] as const,
|
|
onboardingFirstTask: (companyId: string) =>
|
|
["issues", companyId, "onboarding-first-task"] as const,
|
|
starPromptDone: (companyId: string) =>
|
|
["issues", companyId, "star-prompt-done"] as const,
|
|
mentionPool: (companyId: string) =>
|
|
["issues", companyId, "mention-pool"] as const,
|
|
search: (
|
|
companyId: string,
|
|
q: string,
|
|
projectId?: string,
|
|
limit?: number,
|
|
) =>
|
|
[
|
|
"issues",
|
|
companyId,
|
|
"search",
|
|
q,
|
|
projectId ?? "__all-projects__",
|
|
limit ?? "__no-limit__",
|
|
] as const,
|
|
listAssignedToMe: (companyId: string) =>
|
|
["issues", companyId, "assigned-to-me"] as const,
|
|
listMineByMe: (companyId: string) =>
|
|
["issues", companyId, "mine-by-me"] as const,
|
|
listTouchedByMe: (companyId: string) =>
|
|
["issues", companyId, "touched-by-me"] as const,
|
|
listUnreadTouchedByMe: (companyId: string) =>
|
|
["issues", companyId, "unread-touched-by-me"] as const,
|
|
listBlockedAttention: (companyId: string) =>
|
|
["issues", companyId, "blocked-attention"] as const,
|
|
countBlockedAttention: (companyId: string) =>
|
|
["issues", companyId, "blocked-attention", "count"] as const,
|
|
labels: (companyId: string) => ["issues", companyId, "labels"] as const,
|
|
listByProject: (companyId: string, projectId: string) =>
|
|
["issues", companyId, "project", projectId] as const,
|
|
listPluginOperationsByProject: (
|
|
companyId: string,
|
|
projectId: string,
|
|
originKindPrefix: string,
|
|
) =>
|
|
[
|
|
"issues",
|
|
companyId,
|
|
"project",
|
|
projectId,
|
|
"plugin-operations",
|
|
originKindPrefix,
|
|
] as const,
|
|
listParticipatedByAgent: (companyId: string, agentId: string) =>
|
|
["issues", companyId, "participated-by-agent", agentId] as const,
|
|
listByParent: (companyId: string, parentId: string) =>
|
|
["issues", companyId, "parent", parentId] as const,
|
|
listCreatedFromIssue: (companyId: string, issueId: string) =>
|
|
["issues", companyId, "created-from", issueId] as const,
|
|
listByDescendantRoot: (companyId: string, rootIssueId: string) =>
|
|
["issues", companyId, "descendants", rootIssueId] as const,
|
|
listByExecutionWorkspace: (
|
|
companyId: string,
|
|
executionWorkspaceId: string,
|
|
) =>
|
|
[
|
|
"issues",
|
|
companyId,
|
|
"execution-workspace",
|
|
executionWorkspaceId,
|
|
] as const,
|
|
summaries: (companyId: string) => ["issues", companyId, "summaries"] as const,
|
|
summaryBatch: (companyId: string, userId: string | null | undefined, sortedIds: readonly string[]) =>
|
|
["issues", companyId, "summaries", userId ?? "__local_board__", sortedIds] as const,
|
|
detail: (id: string) => ["issues", "detail", id] as const,
|
|
comments: (issueId: string) => ["issues", "comments", issueId] as const,
|
|
acknowledgedComments: (issueId: string) => ["issues", "comments", issueId, "acknowledged"] as const,
|
|
earlierComments: (issueId: string) => ["issues", "comments", issueId, "earlier"] as const,
|
|
commentsList: (issueId: string) =>
|
|
["issues", "comments", issueId, "list"] as const,
|
|
queuedComments: (issueId: string) =>
|
|
["issues", "queued-comments", issueId] as const,
|
|
interactions: (issueId: string) =>
|
|
["issues", "interactions", issueId] as const,
|
|
acceptedPlanDecompositions: (issueId: string) =>
|
|
["issues", "accepted-plan-decompositions", issueId] as const,
|
|
feedbackVotes: (issueId: string) =>
|
|
["issues", "feedback-votes", issueId] as const,
|
|
costSummary: (issueId: string, options: { excludeRoot?: boolean } = {}) =>
|
|
options.excludeRoot
|
|
? (["issues", "cost-summary", issueId, "exclude-root"] as const)
|
|
: (["issues", "cost-summary", issueId] as const),
|
|
privacyConstraints: (issueId: string) => ["issues", "privacy-constraints", issueId] as const,
|
|
accessGrants: (issueId: string) => ["issues", "access-grants", issueId] as const,
|
|
attachments: (issueId: string) => ["issues", "attachments", issueId] as const,
|
|
attachmentPreview: (attachmentId: string) => ["issues", "attachment-preview", attachmentId] as const,
|
|
documents: (issueId: string) => ["issues", "documents", issueId] as const,
|
|
document: (issueId: string, key: string) =>
|
|
["issues", "document", issueId, key] as const,
|
|
documentRevisions: (issueId: string, key: string) =>
|
|
["issues", "document-revisions", issueId, key] as const,
|
|
documentAnnotations: (
|
|
issueId: string,
|
|
key: string,
|
|
status: "open" | "resolved" | "all" = "all",
|
|
) => ["issues", "document-annotations", issueId, key, status] as const,
|
|
activity: (issueId: string) => ["issues", "activity", issueId] as const,
|
|
runs: (issueId: string) => ["issues", "runs", issueId] as const,
|
|
approvals: (issueId: string) => ["issues", "approvals", issueId] as const,
|
|
liveRuns: (issueId: string) => ["issues", "live-runs", issueId] as const,
|
|
activeRun: (issueId: string) => ["issues", "active-run", issueId] as const,
|
|
contextUsage: (issueId: string, assigneeAgentId: string | null) =>
|
|
["issues", "context-usage", issueId, assigneeAgentId] as const,
|
|
runnerGoal: (issueId: string, agentId?: string | null) =>
|
|
["issues", "runner-goal", issueId, agentId ?? "__effective__"] as const,
|
|
workProducts: (issueId: string) =>
|
|
["issues", "work-products", issueId] as const,
|
|
workProductPullRequestRefresh: (issueId: string) =>
|
|
["issues", "work-product-pr-refresh", issueId] as const,
|
|
fileResources: (
|
|
issueId: string,
|
|
options: {
|
|
workspace?: string;
|
|
projectId?: string | null;
|
|
workspaceId?: string | null;
|
|
path?: string | null;
|
|
mode?: string;
|
|
q?: string | null;
|
|
limit?: number;
|
|
offset?: number;
|
|
} = {},
|
|
) => ["issues", "file-resources", issueId, "list", options] as const,
|
|
fileResource: (
|
|
issueId: string,
|
|
query: {
|
|
path: string;
|
|
workspace?: string;
|
|
projectId?: string | null;
|
|
workspaceId?: string | null;
|
|
},
|
|
) => ["issues", "file-resources", issueId, "resolve", query] as const,
|
|
fileResourceContent: (
|
|
issueId: string,
|
|
query: {
|
|
path: string;
|
|
workspace?: string;
|
|
projectId?: string | null;
|
|
workspaceId?: string | null;
|
|
},
|
|
) => ["issues", "file-resources", issueId, "content", query] as const,
|
|
/**
|
|
* Batched availability preflight. `refKeys` are the deduplicated,
|
|
* lexicographically sorted reference keys in the request so identical
|
|
* batches share one cache entry.
|
|
*/
|
|
fileResourceAvailability: (issueId: string, refKeys: readonly string[]) =>
|
|
["issues", "file-resources", issueId, "availability", refKeys] as const,
|
|
},
|
|
routines: {
|
|
list: (companyId: string, filters?: { projectId?: string | null }) =>
|
|
[
|
|
"routines",
|
|
companyId,
|
|
filters?.projectId ?? "__all-projects__",
|
|
] as const,
|
|
detail: (id: string) => ["routines", "detail", id] as const,
|
|
runs: (id: string) => ["routines", "runs", id] as const,
|
|
revisions: (id: string) => ["routines", "revisions", id] as const,
|
|
activity: (companyId: string, id: string) =>
|
|
["routines", "activity", companyId, id] as const,
|
|
documentAnnotations: (
|
|
routineId: string,
|
|
key: "description",
|
|
status: "open" | "resolved" | "all" = "all",
|
|
) => ["routines", "document-annotations", routineId, key, status] as const,
|
|
},
|
|
folders: {
|
|
list: (companyId: string, kind: string) =>
|
|
["folders", companyId, kind] as const,
|
|
},
|
|
executionWorkspaces: {
|
|
list: (
|
|
companyId: string,
|
|
filters?: Record<string, string | boolean | undefined>,
|
|
) => ["execution-workspaces", companyId, filters ?? {}] as const,
|
|
summaryList: (
|
|
companyId: string,
|
|
filters?: Record<string, string | boolean | undefined>,
|
|
) => ["execution-workspaces", companyId, "summary", filters ?? {}] as const,
|
|
overview: (
|
|
companyId: string,
|
|
filters?: Record<string, string | number | boolean | undefined>,
|
|
) =>
|
|
["execution-workspaces", companyId, "overview", filters ?? {}] as const,
|
|
detail: (id: string) => ["execution-workspaces", "detail", id] as const,
|
|
closeReadiness: (id: string) =>
|
|
["execution-workspaces", "close-readiness", id] as const,
|
|
workspaceOperations: (id: string) =>
|
|
["execution-workspaces", "workspace-operations", id] as const,
|
|
},
|
|
environments: {
|
|
list: (companyId: string) => ["environments", companyId] as const,
|
|
capabilities: (companyId: string) =>
|
|
["environment-capabilities", companyId] as const,
|
|
customImageTemplate: (environmentId: string) =>
|
|
["environments", environmentId, "custom-image-template"] as const,
|
|
customImageSetupSession: (sessionId: string) =>
|
|
["environment-custom-image-setup-sessions", sessionId] as const,
|
|
},
|
|
projects: {
|
|
environments: (companyId: string) => ["project-environments", companyId] as const,
|
|
all: (companyId: string) => ["projects", companyId] as const,
|
|
list: (companyId: string, opts: { includeArchived?: boolean } = {}) =>
|
|
[
|
|
"projects",
|
|
companyId,
|
|
{ includeArchived: opts.includeArchived === true },
|
|
] as const,
|
|
detail: (id: string) => ["projects", "detail", id] as const,
|
|
accessMembers: (id: string) => ["projects", "access-members", id] as const,
|
|
},
|
|
cases: {
|
|
handoffs: (id: string) => ["cases", "handoffs", id] as const,
|
|
list: (companyId: string) => ["cases", companyId] as const,
|
|
detail: (id: string) => ["cases", "detail", id] as const,
|
|
documents: (id: string) => ["cases", "documents", id] as const,
|
|
documentAnnotations: (
|
|
caseId: string,
|
|
key: string,
|
|
status: "open" | "resolved" | "all" = "all",
|
|
) => ["cases", "document-annotations", caseId, key, status] as const,
|
|
events: (id: string) => ["cases", "events", id] as const,
|
|
children: (parentId: string) => ["cases", "children", parentId] as const,
|
|
revisions: (id: string, key: string) =>
|
|
["cases", "revisions", id, key] as const,
|
|
forIssue: (issueId: string) => ["cases", "for-issue", issueId] as const,
|
|
},
|
|
externalObjects: {
|
|
byIssue: (issueId: string) =>
|
|
["external-objects", "by-issue", issueId] as const,
|
|
issueSummary: (issueId: string) =>
|
|
["external-objects", "issue-summary", issueId] as const,
|
|
issueSummaries: (companyId: string, issueIds: readonly string[]) =>
|
|
["external-objects", "issue-summaries", companyId, issueIds] as const,
|
|
projectSummary: (projectId: string) =>
|
|
["external-objects", "project-summary", projectId] as const,
|
|
},
|
|
goals: {
|
|
list: (companyId: string) => ["goals", companyId] as const,
|
|
detail: (id: string) => ["goals", "detail", id] as const,
|
|
},
|
|
artifacts: {
|
|
list: (
|
|
companyId: string,
|
|
kind?: string,
|
|
q?: string,
|
|
groupBy?: string,
|
|
groupIssueId?: string,
|
|
) =>
|
|
[
|
|
"artifacts",
|
|
companyId,
|
|
kind ?? "all",
|
|
q ?? "",
|
|
groupBy ?? "none",
|
|
groupIssueId ?? "",
|
|
] as const,
|
|
byAgent: (companyId: string, agentId: string) =>
|
|
["artifacts", companyId, "by-agent", agentId] as const,
|
|
},
|
|
budgets: {
|
|
overview: (companyId: string) =>
|
|
["budgets", "overview", companyId] as const,
|
|
},
|
|
approvals: {
|
|
list: (companyId: string, status?: string) =>
|
|
["approvals", companyId, status] as const,
|
|
detail: (approvalId: string) =>
|
|
["approvals", "detail", approvalId] as const,
|
|
comments: (approvalId: string) =>
|
|
["approvals", "comments", approvalId] as const,
|
|
issues: (approvalId: string) =>
|
|
["approvals", "issues", approvalId] as const,
|
|
},
|
|
access: {
|
|
invites: (companyId: string, state: string = "all", limit: number = 20) =>
|
|
["access", "invites", "paginated-v1", companyId, state, limit] as const,
|
|
joinRequests: (companyId: string, status: string = "pending_approval") =>
|
|
["access", "join-requests", companyId, status] as const,
|
|
companyMembers: (companyId: string) =>
|
|
["access", "company-members", companyId] as const,
|
|
companyUserDirectory: (companyId: string) =>
|
|
["access", "company-user-directory", companyId] as const,
|
|
adminUsers: (query: string) => ["access", "admin-users", query] as const,
|
|
userCompanyAccess: (userId: string) =>
|
|
["access", "user-company-access", userId] as const,
|
|
invite: (token: string) => ["access", "invite", token] as const,
|
|
currentBoardAccess: ["access", "current-board-access"] as const,
|
|
},
|
|
auth: {
|
|
session: ["auth", "session"] as const,
|
|
},
|
|
inboxAgentPolicy: {
|
|
mine: (companyId: string) =>
|
|
["inbox-agent-policy", companyId, "me"] as const,
|
|
},
|
|
sidebarPreferences: {
|
|
companyOrder: (userId: string) =>
|
|
["sidebar-preferences", "company-order", userId] as const,
|
|
projectOrder: (companyId: string, userId: string) =>
|
|
["sidebar-preferences", "project-order", companyId, userId] as const,
|
|
},
|
|
primaryAgent: {
|
|
mine: (companyId: string, userId: string) => ["primary-agent", companyId, userId] as const,
|
|
},
|
|
resourceMemberships: {
|
|
mine: (companyId: string) =>
|
|
["resource-memberships", companyId, "me"] as const,
|
|
},
|
|
instance: {
|
|
settings: ["instance", "settings"] as const,
|
|
generalSettings: ["instance", "general-settings"] as const,
|
|
experimentalSettings: ["instance", "experimental-settings"] as const,
|
|
},
|
|
health: ["health"] as const,
|
|
stagingCommit: ["staging-commit"] as const,
|
|
cloud: {
|
|
stacks: ["cloud", "stacks"] as const,
|
|
},
|
|
secrets: {
|
|
list: (companyId: string) => ["secrets", companyId] as const,
|
|
providers: (companyId: string) => ["secret-providers", companyId] as const,
|
|
providerConfigs: (companyId: string) =>
|
|
["secret-provider-configs", companyId] as const,
|
|
usage: (secretId: string) => ["secrets", "usage", secretId] as const,
|
|
accessEvents: (secretId: string) =>
|
|
["secrets", "access-events", secretId] as const,
|
|
userDefinitions: (companyId: string) =>
|
|
["user-secret-definitions", companyId] as const,
|
|
userDefinitionCoverage: (companyId: string, definitionId: string) =>
|
|
["user-secret-definitions", companyId, definitionId, "coverage"] as const,
|
|
myUserSecrets: (companyId: string) =>
|
|
["my-user-secrets", companyId] as const,
|
|
proposals: (companyId: string, status: string = "pending") =>
|
|
["secret-proposals", companyId, status] as const,
|
|
},
|
|
companySearch: {
|
|
search: (
|
|
companyId: string,
|
|
q: string,
|
|
scope: string,
|
|
limit: number,
|
|
offset: number,
|
|
) => ["company-search", companyId, q, scope, limit, offset] as const,
|
|
},
|
|
dashboard: (companyId: string) => ["dashboard", companyId] as const,
|
|
attention: (companyId: string) => ["attention", companyId] as const,
|
|
decisions: {
|
|
list: (companyId: string, status?: string) =>
|
|
["decisions", companyId, status ?? "__all-statuses__"] as const,
|
|
detail: (id: string) => ["decisions", "detail", id] as const,
|
|
forTargetIssue: (companyId: string, issueId: string) =>
|
|
["decisions", companyId, "target", issueId] as const,
|
|
taskRecord: (companyId: string, issueId: string, viewerId: string | null, decisionId: string | null) =>
|
|
["decisions", companyId, "task-record", issueId, viewerId, decisionId] as const,
|
|
},
|
|
decisionQueues: {
|
|
list: (companyId: string) => ["decision-queues", companyId] as const,
|
|
items: (companyId: string, key: string) =>
|
|
["decision-queues", companyId, "items", key] as const,
|
|
seedRules: (companyId: string) =>
|
|
["decision-queues", companyId, "seed-rules"] as const,
|
|
triage: (companyId: string, sourceKind: string, sourceId: string) =>
|
|
["decision-triage", companyId, sourceKind, sourceId] as const,
|
|
},
|
|
workTimeline: (companyId: string, lens?: string) =>
|
|
["work-timeline", companyId, lens ?? "all"] as const,
|
|
userProfile: (companyId: string, userSlug: string) =>
|
|
["user-profile", companyId, userSlug] as const,
|
|
sidebarBadges: (companyId: string) => ["sidebar-badges", companyId] as const,
|
|
inboxDismissals: (companyId: string) =>
|
|
["inbox-dismissals", companyId] as const,
|
|
activity: (companyId: string) => ["activity", companyId] as const,
|
|
costs: (companyId: string, from?: string, to?: string) =>
|
|
["costs", companyId, from, to] as const,
|
|
usageByProvider: (companyId: string, from?: string, to?: string) =>
|
|
["usage-by-provider", companyId, from, to] as const,
|
|
usageByBiller: (companyId: string, from?: string, to?: string) =>
|
|
["usage-by-biller", companyId, from, to] as const,
|
|
financeSummary: (companyId: string, from?: string, to?: string) =>
|
|
["finance-summary", companyId, from, to] as const,
|
|
financeByBiller: (companyId: string, from?: string, to?: string) =>
|
|
["finance-by-biller", companyId, from, to] as const,
|
|
financeByKind: (companyId: string, from?: string, to?: string) =>
|
|
["finance-by-kind", companyId, from, to] as const,
|
|
financeEvents: (
|
|
companyId: string,
|
|
from?: string,
|
|
to?: string,
|
|
limit: number = 100,
|
|
) => ["finance-events", companyId, from, to, limit] as const,
|
|
usageWindowSpend: (companyId: string) =>
|
|
["usage-window-spend", companyId] as const,
|
|
usageQuotaWindows: (companyId: string) =>
|
|
["usage-quota-windows", companyId] as const,
|
|
heartbeats: (companyId: string, agentId?: string) =>
|
|
["heartbeats", companyId, agentId] as const,
|
|
runDetail: (runId: string) => ["heartbeat-run", runId] as const,
|
|
providerTraceMetadata: (companyId: string, runIds: readonly string[]) =>
|
|
["provider-trace-metadata", companyId, [...runIds].sort()] as const,
|
|
runWorkspaceOperations: (runId: string) =>
|
|
["heartbeat-run", runId, "workspace-operations"] as const,
|
|
liveRuns: (companyId: string) => ["live-runs", companyId] as const,
|
|
runIssues: (runId: string) => ["run-issues", runId] as const,
|
|
org: (companyId: string) => ["org", companyId] as const,
|
|
skills: {
|
|
available: ["skills", "available"] as const,
|
|
},
|
|
plugins: {
|
|
all: ["plugins"] as const,
|
|
examples: ["plugins", "examples"] as const,
|
|
detail: (pluginId: string) => ["plugins", pluginId] as const,
|
|
health: (pluginId: string) => ["plugins", pluginId, "health"] as const,
|
|
uiContributions: ["plugins", "ui-contributions"] as const,
|
|
config: (pluginId: string, companyId: string) =>
|
|
["plugins", pluginId, "companies", companyId, "config"] as const,
|
|
localFolders: (pluginId: string, companyId: string) =>
|
|
["plugins", pluginId, "companies", companyId, "local-folders"] as const,
|
|
dashboard: (pluginId: string) =>
|
|
["plugins", pluginId, "dashboard"] as const,
|
|
logs: (pluginId: string) => ["plugins", pluginId, "logs"] as const,
|
|
},
|
|
adapters: {
|
|
all: ["adapters"] as const,
|
|
availability: (companyId: string | null, environmentId?: string | null) =>
|
|
["adapters", "availability", companyId, environmentId ?? null] as const,
|
|
},
|
|
};
|