Files
paperclip/ui/src/lib/queryKeys.ts
T
Dotta b7545823be [codex] Add document annotations and comments (#6733)
## Thinking Path

> - Paperclip orchestrates AI-agent companies through issues, documents,
runs, and durable company-scoped state.
> - Issue documents are where agents and operators capture plans,
handoffs, and work products.
> - Before this change, document collaboration could only happen through
whole-document edits and detached issue comments.
> - Inline document annotations need stable anchors, revision-aware
persistence, and UI affordances that do not break existing document
editing.
> - This pull request adds company-scoped document annotation threads,
comments, anchor snapshots, API routes, and board UI.
> - The benefit is that operators and agents can discuss specific
document passages without losing context as documents evolve.

## What Changed

- Added document annotation tables, schema exports, shared types,
validators, anchor hashing, and text-anchor helpers.
- Added server-side document annotation services and issue routes for
listing, creating, commenting, resolving, and reopening annotation
threads.
- Included annotation summaries in relevant issue document reads and
backup/recovery document workspace behavior.
- Added React UI for inline document highlights, comment panels, mobile
sheet behavior, deep-link focus, and resolved/open filtering.
- Added annotation design artifacts, Storybook coverage, screenshots,
and a screenshot helper script.
- Rebased the branch onto current `paperclipai/paperclip` `master` and
renumbered the annotation migration from `0085_old_swarm` to
`0091_old_swarm`; the SQL uses `IF NOT EXISTS` guards so environments
that previously applied the old migration number can safely apply the
new one.
- Adjusted the new annotation UI tests to use a local async flush helper
because this workspace's React 19.2.4 export does not expose
`React.act`.

## Verification

- `pnpm run preflight:workspace-links && pnpm exec vitest run
packages/shared/src/document-anchors.test.ts
server/src/__tests__/document-annotation-routes.test.ts
server/src/__tests__/document-annotations-service.test.ts
ui/src/components/DocumentAnnotationLayer.test.tsx
ui/src/components/IssueDocumentAnnotations.test.tsx
ui/src/lib/document-annotation-hash.test.ts
ui/src/lib/document-annotation-selection.test.ts`
- Confirmed `git diff --check` passes.
- Confirmed no `pnpm-lock.yaml` or `.github/workflows/*` files are
included in the PR diff.

## Risks

- Medium risk: this adds new persisted annotation tables and routes
across db/shared/server/ui.
- Migration risk is reduced by moving the branch migration to
`0091_old_swarm` after upstream `0090_resource_memberships` and keeping
the SQL idempotent for old `0085_old_swarm` adopters.
- UI risk is mostly around text range anchoring and panel positioning
across long documents, folded content, and mobile layouts; the PR
includes focused unit coverage and design screenshots.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5 coding agent, tool-using software engineering
mode. Context window size is not exposed in this Paperclip runtime.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-05-26 06:41:23 -07:00

204 lines
12 KiB
TypeScript

export const queryKeys = {
companies: {
all: ["companies"] as const,
detail: (id: string) => ["companies", id] as const,
stats: ["companies", "stats"] as const,
},
companySkills: {
list: (companyId: string) => ["company-skills", companyId] as const,
detail: (companyId: string, skillId: string) => ["company-skills", companyId, skillId] as const,
updateStatus: (companyId: string, skillId: string) =>
["company-skills", companyId, skillId, "update-status"] as const,
file: (companyId: string, skillId: string, relativePath: string) =>
["company-skills", companyId, skillId, "file", relativePath] as const,
},
agents: {
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,
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) =>
["agents", companyId, "adapter-models", adapterType, environmentId ?? null] as const,
adapterModelProfiles: (companyId: string, adapterType: string) =>
["agents", companyId, "adapter-model-profiles", adapterType] as const,
detectModel: (companyId: string, adapterType: string) =>
["agents", companyId, "detect-model", adapterType] as const,
},
issues: {
list: (companyId: string) => ["issues", companyId] 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,
listByParent: (companyId: string, parentId: string) =>
["issues", companyId, "parent", parentId] 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,
detail: (id: string) => ["issues", "detail", id] as const,
comments: (issueId: string) => ["issues", "comments", issueId] as const,
interactions: (issueId: string) => ["issues", "interactions", 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),
attachments: (issueId: string) => ["issues", "attachments", issueId] 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,
workProducts: (issueId: string) => ["issues", "work-products", issueId] 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,
},
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,
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,
},
projects: {
list: (companyId: string) => ["projects", companyId] as const,
detail: (id: string) => ["projects", "detail", id] as const,
},
goals: {
list: (companyId: string) => ["goals", companyId] as const,
detail: (id: string) => ["goals", "detail", id] 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,
},
sidebarPreferences: {
companyOrder: (userId: string) => ["sidebar-preferences", "company-order", userId] as const,
projectOrder: (companyId: string, userId: string) =>
["sidebar-preferences", "project-order", companyId, userId] as const,
},
resourceMemberships: {
mine: (companyId: string) => ["resource-memberships", companyId, "me"] as const,
},
instance: {
generalSettings: ["instance", "general-settings"] as const,
schedulerHeartbeats: ["instance", "scheduler-heartbeats"] as const,
experimentalSettings: ["instance", "experimental-settings"] as const,
},
cloudUpstreams: (companyId: string) => ["cloud-upstreams", companyId] as const,
health: ["health"] 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,
},
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,
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,
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) => ["plugins", pluginId, "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,
},
};