mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-16 10:50:38 +09:00
[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>
This commit is contained in:
Dotta
GitHub
parent
f0ddd24d61
commit
b7545823be
55 changed files with 25070 additions and 31 deletions
|
|
@ -23,6 +23,8 @@ import {
|
|||
createIssueWorkProductSchema,
|
||||
createIssueLabelSchema,
|
||||
checkoutIssueSchema,
|
||||
createDocumentAnnotationCommentSchema,
|
||||
createDocumentAnnotationThreadSchema,
|
||||
createChildIssueSchema,
|
||||
createIssueSchema,
|
||||
resolveCreateIssueStatusDefault,
|
||||
|
|
@ -38,6 +40,7 @@ import {
|
|||
restoreIssueDocumentRevisionSchema,
|
||||
respondIssueThreadInteractionSchema,
|
||||
updateIssueWorkProductSchema,
|
||||
updateDocumentAnnotationThreadSchema,
|
||||
upsertIssueDocumentSchema,
|
||||
updateIssueSchema,
|
||||
getClosedIsolatedExecutionWorkspaceMessage,
|
||||
|
|
@ -71,6 +74,7 @@ import {
|
|||
issueService,
|
||||
clampIssueListLimit,
|
||||
documentService,
|
||||
documentAnnotationService,
|
||||
logActivity,
|
||||
projectService,
|
||||
routineService,
|
||||
|
|
@ -868,6 +872,7 @@ export function issueRoutes(
|
|||
const executionWorkspacesSvc = executionWorkspaceServiceDirect(db);
|
||||
const workProductsSvc = workProductService(db);
|
||||
const documentsSvc = documentService(db);
|
||||
const documentAnnotationsSvc = documentAnnotationService(db);
|
||||
const issueReferencesSvc = issueReferenceService(db);
|
||||
const issueThreadInteractionsSvc = issueThreadInteractionService(db);
|
||||
const routinesSvc = routineService(db, {
|
||||
|
|
@ -1106,6 +1111,69 @@ export function issueRoutes(
|
|||
return value === true || value === "true" || value === "1";
|
||||
}
|
||||
|
||||
function shouldIncludeDocumentAnnotations(req: Request) {
|
||||
if (req.query.includeAnnotations === "false" || req.query.includeAnnotations === "0") return false;
|
||||
return req.actor.type === "agent" || parseBooleanQuery(req.query.includeAnnotations);
|
||||
}
|
||||
|
||||
function shouldIncludeDocumentAnnotationComments(req: Request) {
|
||||
return parseBooleanQuery(req.query.includeAnnotationComments);
|
||||
}
|
||||
|
||||
function annotationActorInput(req: Request) {
|
||||
const actor = getActorInfo(req);
|
||||
return {
|
||||
actor,
|
||||
annotationActor: {
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
userId: actor.actorType === "user" ? actor.actorId : null,
|
||||
runId: actor.runId,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function queueAnnotationCommentWakeup(input: {
|
||||
issue: { id: string; assigneeAgentId: string | null; status: string };
|
||||
actor: { actorType: "user" | "agent"; actorId: string };
|
||||
threadId: string;
|
||||
commentId: string;
|
||||
documentKey: string;
|
||||
}) {
|
||||
const assigneeId = input.issue.assigneeAgentId;
|
||||
const selfComment = input.actor.actorType === "agent" && input.actor.actorId === assigneeId;
|
||||
if (!assigneeId || selfComment || isClosedIssueStatus(input.issue.status)) return;
|
||||
void heartbeat.wakeup(assigneeId, {
|
||||
source: "automation",
|
||||
triggerDetail: "system",
|
||||
reason: "issue_commented",
|
||||
payload: {
|
||||
issueId: input.issue.id,
|
||||
annotationThreadId: input.threadId,
|
||||
annotationCommentId: input.commentId,
|
||||
documentKey: input.documentKey,
|
||||
mutation: "document_annotation_comment",
|
||||
},
|
||||
requestedByActorType: input.actor.actorType,
|
||||
requestedByActorId: input.actor.actorId,
|
||||
contextSnapshot: {
|
||||
issueId: input.issue.id,
|
||||
taskId: input.issue.id,
|
||||
annotationThreadId: input.threadId,
|
||||
annotationCommentId: input.commentId,
|
||||
documentKey: input.documentKey,
|
||||
source: "issue.document.annotation",
|
||||
wakeReason: "issue_commented",
|
||||
},
|
||||
}).catch((err) => logger.warn({
|
||||
err,
|
||||
issueId: input.issue.id,
|
||||
annotationThreadId: input.threadId,
|
||||
annotationCommentId: input.commentId,
|
||||
}, "failed to wake assignee on document annotation comment"));
|
||||
}
|
||||
|
||||
async function assertIssueEnvironmentSelection(
|
||||
companyId: string,
|
||||
environmentId: string | null | undefined,
|
||||
|
|
@ -2448,9 +2516,239 @@ export function issueRoutes(
|
|||
res.status(404).json({ error: "Document not found" });
|
||||
return;
|
||||
}
|
||||
res.json(doc);
|
||||
if (!shouldIncludeDocumentAnnotations(req)) {
|
||||
res.json(doc);
|
||||
return;
|
||||
}
|
||||
const annotations = await documentAnnotationsSvc.listThreadsForIssueDocument(issue.id, keyParsed.data, {
|
||||
status: "open",
|
||||
includeComments: shouldIncludeDocumentAnnotationComments(req),
|
||||
});
|
||||
res.json({ ...doc, annotations });
|
||||
});
|
||||
|
||||
router.get("/issues/:id/documents/:key/annotations", async (req, res) => {
|
||||
const id = req.params.id as string;
|
||||
const issue = await svc.getById(id);
|
||||
if (!issue) {
|
||||
res.status(404).json({ error: "Issue not found" });
|
||||
return;
|
||||
}
|
||||
assertCompanyAccess(req, issue.companyId);
|
||||
const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
|
||||
if (!keyParsed.success) {
|
||||
res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
|
||||
return;
|
||||
}
|
||||
const status = req.query.status === "resolved" || req.query.status === "all" ? req.query.status : "open";
|
||||
const threads = await documentAnnotationsSvc.listThreadsForIssueDocument(issue.id, keyParsed.data, {
|
||||
status,
|
||||
includeComments: parseBooleanQuery(req.query.includeComments),
|
||||
});
|
||||
res.json(threads);
|
||||
});
|
||||
|
||||
router.post(
|
||||
"/issues/:id/documents/:key/annotations",
|
||||
validate(createDocumentAnnotationThreadSchema),
|
||||
async (req, res) => {
|
||||
const id = req.params.id as string;
|
||||
const issue = await svc.getById(id);
|
||||
if (!issue) {
|
||||
res.status(404).json({ error: "Issue not found" });
|
||||
return;
|
||||
}
|
||||
assertCompanyAccess(req, issue.companyId);
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
|
||||
if (!keyParsed.success) {
|
||||
res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
|
||||
return;
|
||||
}
|
||||
|
||||
const { actor, annotationActor } = annotationActorInput(req);
|
||||
const referenceSummaryBefore = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
|
||||
const thread = await documentAnnotationsSvc.createThread(issue.id, keyParsed.data, req.body, annotationActor);
|
||||
const firstComment = thread.comments[0];
|
||||
if (firstComment) await issueReferencesSvc.syncAnnotationComment(firstComment.id);
|
||||
const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
|
||||
const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);
|
||||
|
||||
await logActivity(db, {
|
||||
companyId: issue.companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: "issue.document_annotation_thread_created",
|
||||
entityType: "issue",
|
||||
entityId: issue.id,
|
||||
details: {
|
||||
documentKey: thread.documentKey,
|
||||
documentId: thread.documentId,
|
||||
threadId: thread.id,
|
||||
commentId: firstComment?.id ?? null,
|
||||
revisionNumber: thread.currentRevisionNumber,
|
||||
quote: thread.selectedText.slice(0, 240),
|
||||
...summarizeIssueReferenceActivityDetails({
|
||||
addedReferencedIssues: referenceDiff.addedReferencedIssues.map(summarizeIssueRelationForActivity),
|
||||
removedReferencedIssues: referenceDiff.removedReferencedIssues.map(summarizeIssueRelationForActivity),
|
||||
currentReferencedIssues: referenceDiff.currentReferencedIssues.map(summarizeIssueRelationForActivity),
|
||||
}),
|
||||
},
|
||||
});
|
||||
|
||||
if (firstComment) {
|
||||
queueAnnotationCommentWakeup({
|
||||
issue,
|
||||
actor,
|
||||
threadId: thread.id,
|
||||
commentId: firstComment.id,
|
||||
documentKey: thread.documentKey,
|
||||
});
|
||||
}
|
||||
|
||||
res.status(201).json(thread);
|
||||
},
|
||||
);
|
||||
|
||||
router.get("/issues/:id/documents/:key/annotations/:threadId", async (req, res) => {
|
||||
const id = req.params.id as string;
|
||||
const issue = await svc.getById(id);
|
||||
if (!issue) {
|
||||
res.status(404).json({ error: "Issue not found" });
|
||||
return;
|
||||
}
|
||||
assertCompanyAccess(req, issue.companyId);
|
||||
const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
|
||||
if (!keyParsed.success) {
|
||||
res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
|
||||
return;
|
||||
}
|
||||
const thread = await documentAnnotationsSvc.getThreadForIssueDocument(
|
||||
issue.id,
|
||||
keyParsed.data,
|
||||
req.params.threadId as string,
|
||||
);
|
||||
if (!thread) {
|
||||
res.status(404).json({ error: "Annotation thread not found" });
|
||||
return;
|
||||
}
|
||||
res.json(thread);
|
||||
});
|
||||
|
||||
router.post(
|
||||
"/issues/:id/documents/:key/annotations/:threadId/comments",
|
||||
validate(createDocumentAnnotationCommentSchema),
|
||||
async (req, res) => {
|
||||
const id = req.params.id as string;
|
||||
const issue = await svc.getById(id);
|
||||
if (!issue) {
|
||||
res.status(404).json({ error: "Issue not found" });
|
||||
return;
|
||||
}
|
||||
assertCompanyAccess(req, issue.companyId);
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
|
||||
if (!keyParsed.success) {
|
||||
res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
|
||||
return;
|
||||
}
|
||||
|
||||
const { actor, annotationActor } = annotationActorInput(req);
|
||||
const referenceSummaryBefore = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
|
||||
const comment = await documentAnnotationsSvc.addComment(
|
||||
issue.id,
|
||||
keyParsed.data,
|
||||
req.params.threadId as string,
|
||||
req.body,
|
||||
annotationActor,
|
||||
);
|
||||
await issueReferencesSvc.syncAnnotationComment(comment.id);
|
||||
const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
|
||||
const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);
|
||||
|
||||
await logActivity(db, {
|
||||
companyId: issue.companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: "issue.document_annotation_comment_added",
|
||||
entityType: "issue",
|
||||
entityId: issue.id,
|
||||
details: {
|
||||
documentKey: keyParsed.data,
|
||||
threadId: comment.threadId,
|
||||
commentId: comment.id,
|
||||
bodySnippet: comment.body.slice(0, 120),
|
||||
...summarizeIssueReferenceActivityDetails({
|
||||
addedReferencedIssues: referenceDiff.addedReferencedIssues.map(summarizeIssueRelationForActivity),
|
||||
removedReferencedIssues: referenceDiff.removedReferencedIssues.map(summarizeIssueRelationForActivity),
|
||||
currentReferencedIssues: referenceDiff.currentReferencedIssues.map(summarizeIssueRelationForActivity),
|
||||
}),
|
||||
},
|
||||
});
|
||||
|
||||
queueAnnotationCommentWakeup({
|
||||
issue,
|
||||
actor,
|
||||
threadId: comment.threadId,
|
||||
commentId: comment.id,
|
||||
documentKey: keyParsed.data,
|
||||
});
|
||||
|
||||
res.status(201).json(comment);
|
||||
},
|
||||
);
|
||||
|
||||
router.patch(
|
||||
"/issues/:id/documents/:key/annotations/:threadId",
|
||||
validate(updateDocumentAnnotationThreadSchema),
|
||||
async (req, res) => {
|
||||
const id = req.params.id as string;
|
||||
const issue = await svc.getById(id);
|
||||
if (!issue) {
|
||||
res.status(404).json({ error: "Issue not found" });
|
||||
return;
|
||||
}
|
||||
assertCompanyAccess(req, issue.companyId);
|
||||
if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
|
||||
const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
|
||||
if (!keyParsed.success) {
|
||||
res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
|
||||
return;
|
||||
}
|
||||
const { actor, annotationActor } = annotationActorInput(req);
|
||||
const thread = await documentAnnotationsSvc.updateThread(
|
||||
issue.id,
|
||||
keyParsed.data,
|
||||
req.params.threadId as string,
|
||||
req.body,
|
||||
annotationActor,
|
||||
);
|
||||
await logActivity(db, {
|
||||
companyId: issue.companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: thread.status === "resolved"
|
||||
? "issue.document_annotation_thread_resolved"
|
||||
: "issue.document_annotation_thread_reopened",
|
||||
entityType: "issue",
|
||||
entityId: issue.id,
|
||||
details: {
|
||||
documentKey: thread.documentKey,
|
||||
documentId: thread.documentId,
|
||||
threadId: thread.id,
|
||||
status: thread.status,
|
||||
},
|
||||
});
|
||||
res.json(thread);
|
||||
},
|
||||
);
|
||||
|
||||
router.put("/issues/:id/documents/:key", validate(upsertIssueDocumentSchema), async (req, res) => {
|
||||
const id = req.params.id as string;
|
||||
const issue = await svc.getById(id);
|
||||
|
|
@ -2488,6 +2786,16 @@ export function issueRoutes(
|
|||
await issueReferencesSvc.syncDocument(doc.id);
|
||||
const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
|
||||
const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);
|
||||
const remappedAnnotations = result.created
|
||||
? []
|
||||
: await documentAnnotationsSvc.remapOpenThreadsForDocument({
|
||||
issueId: issue.id,
|
||||
key: doc.key,
|
||||
documentId: doc.id,
|
||||
nextRevisionId: doc.latestRevisionId,
|
||||
nextRevisionNumber: doc.latestRevisionNumber,
|
||||
nextBody: doc.body,
|
||||
});
|
||||
|
||||
await logActivity(db, {
|
||||
companyId: issue.companyId,
|
||||
|
|
@ -2513,6 +2821,28 @@ export function issueRoutes(
|
|||
},
|
||||
});
|
||||
|
||||
for (const remap of remappedAnnotations) {
|
||||
await logActivity(db, {
|
||||
companyId: issue.companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: "issue.document_annotation_remapped",
|
||||
entityType: "issue",
|
||||
entityId: issue.id,
|
||||
details: {
|
||||
key: doc.key,
|
||||
documentId: doc.id,
|
||||
threadId: remap.thread.id,
|
||||
revisionNumber: doc.latestRevisionNumber,
|
||||
anchorState: remap.thread.anchorState,
|
||||
anchorConfidence: remap.thread.anchorConfidence,
|
||||
snapshotId: remap.snapshot.id,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
if (!result.created) {
|
||||
const expiredInteractions = await issueThreadInteractionService(db).expireStaleRequestConfirmationsForIssueDocument(
|
||||
issue,
|
||||
|
|
@ -2684,6 +3014,14 @@ export function issueRoutes(
|
|||
await issueReferencesSvc.syncDocument(result.document.id);
|
||||
const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
|
||||
const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);
|
||||
const remappedAnnotations = await documentAnnotationsSvc.remapOpenThreadsForDocument({
|
||||
issueId: issue.id,
|
||||
key: result.document.key,
|
||||
documentId: result.document.id,
|
||||
nextRevisionId: result.document.latestRevisionId,
|
||||
nextRevisionNumber: result.document.latestRevisionNumber,
|
||||
nextBody: result.document.body,
|
||||
});
|
||||
|
||||
await logActivity(db, {
|
||||
companyId: issue.companyId,
|
||||
|
|
@ -2710,6 +3048,28 @@ export function issueRoutes(
|
|||
},
|
||||
});
|
||||
|
||||
for (const remap of remappedAnnotations) {
|
||||
await logActivity(db, {
|
||||
companyId: issue.companyId,
|
||||
actorType: actor.actorType,
|
||||
actorId: actor.actorId,
|
||||
agentId: actor.agentId,
|
||||
runId: actor.runId,
|
||||
action: "issue.document_annotation_remapped",
|
||||
entityType: "issue",
|
||||
entityId: issue.id,
|
||||
details: {
|
||||
key: result.document.key,
|
||||
documentId: result.document.id,
|
||||
threadId: remap.thread.id,
|
||||
revisionNumber: result.document.latestRevisionNumber,
|
||||
anchorState: remap.thread.anchorState,
|
||||
anchorConfidence: remap.thread.anchorConfidence,
|
||||
snapshotId: remap.snapshot.id,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
const expiredInteractions = await issueThreadInteractionService(db).expireStaleRequestConfirmationsForIssueDocument(
|
||||
issue,
|
||||
{
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue