The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(annotations): include issue document annotations in agent review context (#11332)
scotttongeabecc6f77e7
diff --git a/packages/adapter-utils/src/server-utils.test.ts b/packages/adapter-utils/src/server-utils.test.tsindex 1bfea41d35..526fe36789 100644--- a/packages/adapter-utils/src/server-utils.test.ts+++ b/packages/adapter-utils/src/server-utils.test.ts@@ -1740,6 +1740,52 @@ describe("renderPaperclipWakePrompt", () => {expect(prompt.indexOf("Open plan comments to incorporate:")).toBeLessThan(prompt.indexOf("New comments in order:"));});+ it("renders grouped non-plan document annotations with editing scope", () => {+ const prompt = renderPaperclipWakePrompt({+ reason: "issue_commented",+ issue: { id: "issue-1", identifier: "PAP-522", title: "Document annotations", status: "in_progress" },+ documentReviewContext: {+ issueId: "issue-1",+ documents: [{+ documentKey: "qa-evidence",+ documentId: "document-2",+ title: "QA evidence",+ latestRevisionId: "revision-3",+ latestRevisionNumber: 3,+ threads: [{+ id: "thread-2",+ documentKey: "qa-evidence",+ documentId: "document-2",+ status: "open",+ revisionNumber: 3,+ anchorState: "active",+ anchorConfidence: "exact",+ selectedText: "Passed in Chrome",+ prefixText: "Evidence: ",+ suffixText: ".",+ comments: [{ id: "comment-2", threadId: "thread-2", body: "Attach the run id.", author: { type: "user", id: "board-user" } }],+ commentCount: 1,+ }],+ totals: { openThreadCount: 1, includedThreadCount: 1, omittedThreadCount: 0, commentCount: 1, includedCommentCount: 1, omittedCommentCount: 0 },+ truncated: true,+ }],+ totals: { openThreadCount: 1, includedThreadCount: 1, omittedThreadCount: 0, commentCount: 1, includedCommentCount: 1, omittedCommentCount: 0 },+ truncated: true,+ },+ comments: [],+ commentWindow: { requestedCount: 0, includedCount: 0, missingCount: 0 },+ fallbackFetchNeeded: true,+ });++ expect(prompt).toContain("## Open document annotations");+ expect(prompt).toContain("### QA evidence");+ expect(prompt).toContain("selected text: Passed in Chrome");+ expect(prompt).toContain("Attach the run id.");+ expect(prompt).toContain("propose a child issue before making code changes");+ expect(prompt).toContain("prefer replying and resolving the thread over rewriting the snapshot");+ expect(prompt).toContain("[document review context truncated]");+ });+it("renders dependency-blocked interaction guidance", () => {const prompt = renderPaperclipWakePrompt({reason: "issue_commented",diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.tsindex 80b9909b23..23a73e09b9 100644--- a/packages/adapter-utils/src/server-utils.ts+++ b/packages/adapter-utils/src/server-utils.ts@@ -590,6 +590,14 @@ type PaperclipWakePlanReviewContext = {truncated: boolean;};+type PaperclipWakeDocumentReviewContext = {+ issueId: string | null;+ documents: Array<PaperclipWakePlanReviewContext & { title: string | null }>;+ totals: PaperclipWakePlanReviewContext["totals"];+ limits: PaperclipWakePlanReviewContext["limits"];+ truncated: boolean;+};+type PaperclipWakeContinuationSummary = {key: string | null;title: string | null;@@ -678,6 +686,7 @@ type PaperclipWakePayload = {executionStage: PaperclipWakeExecutionStage | null;continuationSummary: PaperclipWakeContinuationSummary | null;planReviewContext: PaperclipWakePlanReviewContext | null;+ documentReviewContext: PaperclipWakeDocumentReviewContext | null;livenessContinuation: PaperclipWakeLivenessContinuation | null;taskWatchdog: PaperclipWakeTaskWatchdogContext | null;interactionKind: string | null;@@ -993,6 +1002,41 @@ function normalizePaperclipWakePlanReviewContext(value: unknown): PaperclipWakeP};}+function normalizePaperclipWakeDocumentReviewContext(value: unknown): PaperclipWakeDocumentReviewContext | null {+ const context = parseObject(value);+ const issueId = asString(context.issueId, "").trim() || null;+ const documents = Array.isArray(context.documents)+ ? context.documents.flatMap((value) => {+ const document = parseObject(value);+ const normalized = normalizePaperclipWakePlanReviewContext({ ...document, issueId });+ return normalized+ ? [{ ...normalized, title: asString(document.title, "").trim() || null }]+ : [];+ })+ : [];+ if (!issueId && documents.length === 0) return null;+ const totalsRaw = parseObject(context.totals);+ const openThreadCount = asNumber(totalsRaw.openThreadCount, documents.reduce((sum, doc) => sum + doc.totals.openThreadCount, 0));+ const includedThreadCount = asNumber(totalsRaw.includedThreadCount, documents.reduce((sum, doc) => sum + doc.totals.includedThreadCount, 0));+ const commentCount = asNumber(totalsRaw.commentCount, documents.reduce((sum, doc) => sum + doc.totals.commentCount, 0));+ const includedCommentCount = asNumber(totalsRaw.includedCommentCount, documents.reduce((sum, doc) => sum + doc.totals.includedCommentCount, 0));+ const limits = documents[0]?.limits ?? null;+ return {+ issueId,+ documents,+ totals: {+ openThreadCount,+ includedThreadCount,+ omittedThreadCount: asNumber(totalsRaw.omittedThreadCount, Math.max(0, openThreadCount - includedThreadCount)),+ commentCount,+ includedCommentCount,+ omittedCommentCount: asNumber(totalsRaw.omittedCommentCount, Math.max(0, commentCount - includedCommentCount)),+ },+ limits,+ truncated: asBoolean(context.truncated, false),+ };+}+function normalizePaperclipWakeContinuationSummary(value: unknown): PaperclipWakeContinuationSummary | null {const summary = parseObject(value);const body = asString(summary.body, "").trim();@@ -1284,6 +1328,7 @@ export function normalizePaperclipWakePayload(value: unknown): PaperclipWakePaylconst executionStage = normalizePaperclipWakeExecutionStage(payload.executionStage);const continuationSummary = normalizePaperclipWakeContinuationSummary(payload.continuationSummary);const planReviewContext = normalizePaperclipWakePlanReviewContext(payload.planReviewContext);+ const documentReviewContext = normalizePaperclipWakeDocumentReviewContext(payload.documentReviewContext);const annotationDeltas = Array.isArray(payload.annotationDeltas)? payload.annotationDeltas.map((entry) => normalizePaperclipWakeAnnotationDelta(entry))@@ -1312,7 +1357,7 @@ export function normalizePaperclipWakePayload(value: unknown): PaperclipWakePaylconst checkboxSelection = normalizePaperclipWakeCheckboxSelection(payload.checkboxSelection);const executionWorkspace = normalizePaperclipWakeExecutionWorkspace(payload.executionWorkspace);const agentMessage = normalizePaperclipWakeAgentMessage(payload.agentMessage);- if (comments.length === 0 && commentIds.length === 0 && annotationDeltas.length === 0 && childIssueSummaries.length === 0 && unresolvedBlockerIssueIds.length === 0 && unresolvedBlockerSummaries.length === 0 && !activeTreeHold && !executionStage && !continuationSummary && !planReviewContext && !livenessContinuation && !taskWatchdog && !checkboxSelection && !executionWorkspace && !agentMessage && !recovery && !normalizePaperclipWakeIssue(payload.issue)) {+ if (comments.length === 0 && commentIds.length === 0 && annotationDeltas.length === 0 && childIssueSummaries.length === 0 && unresolvedBlockerIssueIds.length === 0 && unresolvedBlockerSummaries.length === 0 && !activeTreeHold && !executionStage && !continuationSummary && !planReviewContext && !documentReviewContext && !livenessContinuation && !taskWatchdog && !checkboxSelection && !executionWorkspace && !agentMessage && !recovery && !normalizePaperclipWakeIssue(payload.issue)) {return null;}@@ -1330,6 +1375,7 @@ export function normalizePaperclipWakePayload(value: unknown): PaperclipWakePaylexecutionStage,continuationSummary,planReviewContext,+ documentReviewContext,annotationDeltas,livenessContinuation,taskWatchdog,@@ -1760,6 +1806,50 @@ export function renderPaperclipWakePrompt(}}+ if (normalized.documentReviewContext) {+ const context = normalized.documentReviewContext;+ lines.push(+ "",+ "## Open document annotations",+ "",+ "These open annotations are grouped by issue document. Resolved annotations were intentionally omitted.",+ "Scope: a document annotation authorizes document edits and thread replies only; propose a child issue before making code changes.",+ "For snapshot documents such as QA evidence and run summaries, prefer replying and resolving the thread over rewriting the snapshot.",+ `- open annotation threads included: ${context.totals.includedThreadCount}/${context.totals.openThreadCount}`,+ `- annotation comments included: ${context.totals.includedCommentCount}/${context.totals.commentCount}`,+ );+ for (const document of context.documents) {+ lines.push(+ "",+ `### ${document.title ?? document.documentKey ?? "Document"}`,+ `- document key: ${document.documentKey ?? "unknown"}`,+ `- latest revision: ${document.latestRevisionNumber ?? "unknown"}${document.latestRevisionId ? ` (${document.latestRevisionId})` : ""}`,+ );+ for (const thread of document.threads) {+ const state = [+ thread.status,+ thread.revisionNumber ? `revision #${thread.revisionNumber}` : null,+ thread.anchorState,+ thread.anchorConfidence,+ ].filter(Boolean).join(", ");+ lines.push(`- thread ${thread.id ?? "unknown"}${state ? ` (${state})` : ""}`);+ renderPlanReviewText(" selected text", thread.selectedText, thread.selectedTextTruncated);+ renderPlanReviewText(" context before", thread.prefixText, thread.prefixTextTruncated);+ renderPlanReviewText(" context after", thread.suffixText, thread.suffixTextTruncated);+ for (const comment of thread.comments) {+ lines.push(+ ` comment ${comment.id ?? "unknown"} by ${planReviewAuthorLabel(comment.author)}${comment.createdAt ? ` at ${comment.createdAt}` : ""}:`,+ comment.body,+ );+ if (comment.bodyTruncated) lines.push("[document annotation comment body truncated]");+ }+ if (thread.commentsTruncated) lines.push("[document annotation thread comments truncated]");+ }+ if (document.truncated) lines.push("[document annotation context truncated]");+ }+ if (context.truncated) lines.push("[document review context truncated]");+ }+if (executionStage) {lines.push(`- execution wake role: ${executionStage.wakeRole ?? "unknown"}`,diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex ad7b5e8d6f..eb81657f74 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -914,6 +914,8 @@ export type {DocumentAnnotationThread,DocumentAnnotationThreadWithComments,PlanReviewContext,+ DocumentReviewContext,+ DocumentReviewContextDocument,PlanReviewContextAuthor,PlanReviewContextComment,PlanReviewContextThread,diff --git a/packages/shared/src/types/document-annotation.ts b/packages/shared/src/types/document-annotation.tsindex 43a193cd75..7769a42f1c 100644--- a/packages/shared/src/types/document-annotation.ts+++ b/packages/shared/src/types/document-annotation.ts@@ -232,3 +232,22 @@ export interface PlanReviewContext {};truncated: boolean;}++export interface DocumentReviewContextDocument {+ documentKey: string;+ documentId: string;+ title: string | null;+ latestRevisionId: string | null;+ latestRevisionNumber: number | null;+ threads: PlanReviewContextThread[];+ totals: PlanReviewContext["totals"];+ truncated: boolean;+}++export interface DocumentReviewContext {+ issueId: string;+ documents: DocumentReviewContextDocument[];+ totals: PlanReviewContext["totals"];+ limits: PlanReviewContext["limits"];+ truncated: boolean;+}diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.tsindex 787f06bc9a..52ff2ed3a6 100644--- a/packages/shared/src/types/index.ts+++ b/packages/shared/src/types/index.ts@@ -311,6 +311,8 @@ export type {DocumentAnnotationThread,DocumentAnnotationThreadWithComments,PlanReviewContext,+ DocumentReviewContext,+ DocumentReviewContextDocument,PlanReviewContextAuthor,PlanReviewContextComment,PlanReviewContextThread,diff --git a/server/src/__tests__/document-annotations-service.test.ts b/server/src/__tests__/document-annotations-service.test.tsindex d27fd40822..bb2dbf006b 100644--- a/server/src/__tests__/document-annotations-service.test.ts+++ b/server/src/__tests__/document-annotations-service.test.ts@@ -21,7 +21,7 @@ import {import { documentAnnotationService } from "../services/document-annotations.js";import { documentService } from "../services/documents.js";import { buildPaperclipWakePayload } from "../services/heartbeat.js";-import { buildPlanReviewContext, PLAN_REVIEW_CONTEXT_LIMITS } from "../services/plan-review-context.js";+import { buildDocumentReviewContext, buildPlanReviewContext, PLAN_REVIEW_CONTEXT_LIMITS } from "../services/plan-review-context.js";const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;@@ -800,4 +800,61 @@ describeEmbeddedPostgres("documentAnnotationService", () => {],});});++ it("groups non-plan annotations by most recently updated document and applies global caps", async () => {+ const { companyId, issueId } = await createIssueWithDocument("standard");+ const older = (await docs.upsertIssueDocument({+ issueId,+ key: "qa-evidence",+ title: "QA evidence",+ format: "markdown",+ body: "Alpha selected text omega",+ })).document;+ const newer = (await docs.upsertIssueDocument({+ issueId,+ key: "run-summary",+ title: "Run summary",+ format: "markdown",+ body: "Alpha selected text omega",+ })).document;+ await db.update(issueDocuments)+ .set({ updatedAt: new Date("2026-06-01T00:00:00.000Z") })+ .where(eq(issueDocuments.documentId, older.id));+ await db.update(issueDocuments)+ .set({ updatedAt: new Date("2026-06-02T00:00:00.000Z") })+ .where(eq(issueDocuments.documentId, newer.id));++ for (let index = 0; index < PLAN_REVIEW_CONTEXT_LIMITS.maxThreads + 1; index += 1) {+ await annotations.createThread(+ issueId,+ index === 0 ? "run-summary" : "qa-evidence",+ {+ baseRevisionId: index === 0 ? newer.latestRevisionId! : older.latestRevisionId!,+ baseRevisionNumber: index === 0 ? newer.latestRevisionNumber : older.latestRevisionNumber,+ selector: {+ quote: { exact: "selected text", prefix: "Alpha ", suffix: " omega" },+ position: { normalizedStart: 6, normalizedEnd: 19, markdownStart: 6, markdownEnd: 19 },+ },+ body: `Annotation ${index}`,+ },+ { actorType: "user", actorId: "board-user", userId: "board-user" },+ );+ }++ const context = await buildDocumentReviewContext({+ db,+ companyId,+ issueId,+ includeForIssueComment: true,+ });++ expect(context?.documents.map((document) => document.documentKey)).toEqual(["run-summary", "qa-evidence"]);+ expect(context?.totals).toMatchObject({+ openThreadCount: PLAN_REVIEW_CONTEXT_LIMITS.maxThreads + 1,+ includedThreadCount: PLAN_REVIEW_CONTEXT_LIMITS.maxThreads,+ omittedThreadCount: 1,+ });+ expect(context?.documents[1]).toMatchObject({ truncated: true });+ expect(context?.truncated).toBe(true);+ });});diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.tsindex 694e70490d..50ae72bda7 100644--- a/server/src/routes/issues.ts+++ b/server/src/routes/issues.ts@@ -135,7 +135,7 @@ import {routineService,workProductService,} from "../services/index.js";-import { buildPlanReviewContext } from "../services/plan-review-context.js";+import { buildDocumentReviewContext, buildPlanReviewContext } from "../services/plan-review-context.js";import {decideIssueReviewPathRecovery,ISSUE_REVIEW_PATH_LOST_WAKE_REASON,@@ -5982,6 +5982,12 @@ export function issueRoutes(issueWorkMode: issue.workMode,includeForIssueComment: wakeCommentId !== null,});+ const documentReviewContext = await buildDocumentReviewContext({+ db,+ companyId: issue.companyId,+ issueId: issue.id,+ includeForIssueComment: wakeCommentId !== null,+ });const response = {issue: {@@ -6054,6 +6060,7 @@ export function issueRoutes(}: null,planReviewContext,+ documentReviewContext,currentExecutionWorkspace: compactIssueExecutionWorkspace(currentExecutionWorkspace),};res.json(await runRedactions.redactForIssue(issue.companyId, issue.id, response));diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.tsindex 2500ac42b6..a63d435601 100644--- a/server/src/services/heartbeat.ts+++ b/server/src/services/heartbeat.ts@@ -172,7 +172,7 @@ import {getIssueContinuationSummaryDocument,refreshIssueContinuationSummary,} from "./issue-continuation-summary.js";-import { buildPlanReviewContext } from "./plan-review-context.js";+import { buildDocumentReviewContext, buildPlanReviewContext } from "./plan-review-context.js";import { executionWorkspaceService, mergeExecutionWorkspaceConfig } from "./execution-workspaces.js";import { workspaceOperationService, type WorkspaceOperationRecorder } from "./workspace-operations.js";import { isProcessGroupAlive, terminateLocalService } from "./local-service-supervisor.js";@@ -5687,7 +5687,16 @@ export async function buildPaperclipWakePayload(input: {interactionId,}): null;- const payloadTruncated = truncated || issueDescriptionTruncated || planReviewContext?.truncated === true;+ const documentReviewContext = issueId+ ? await buildDocumentReviewContext({+ db: input.db,+ companyId: input.companyId,+ issueId,+ includeForIssueComment: commentIds.length > 0,+ includeForAnnotationDelta: annotationDeltas.length > 0,+ })+ : null;+ const payloadTruncated = truncated || issueDescriptionTruncated || planReviewContext?.truncated === true || documentReviewContext?.truncated === true;const recoveryActionId = readNonEmptyString(input.contextSnapshot.recoveryActionId);const recoveryCause = readNonEmptyString(input.contextSnapshot.recoveryCause);const recoveryAction = recoveryActionId@@ -5799,6 +5808,7 @@ export async function buildPaperclipWakePayload(input: {comments,annotationDeltas,planReviewContext,+ documentReviewContext,commentWindow: {requestedCount: commentIds.length,includedCount: comments.length,diff --git a/server/src/services/plan-review-context.ts b/server/src/services/plan-review-context.tsindex e95e76704e..7a9f370105 100644--- a/server/src/services/plan-review-context.ts+++ b/server/src/services/plan-review-context.ts@@ -8,6 +8,8 @@ import {issueThreadInteractions,} from "@paperclipai/db";import type {+ DocumentReviewContext,+ DocumentReviewContextDocument,PlanReviewContext,PlanReviewContextAuthor,PlanReviewInteractionContext,@@ -34,6 +36,8 @@ type BuildPlanReviewContextInput = {interactionId?: string | null;};+type BuildDocumentReviewContextInput = Omit<BuildPlanReviewContextInput, "issueWorkMode" | "interactionId">;+function nonEmptyString(value: unknown) {return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;}@@ -328,3 +332,233 @@ export async function buildPlanReviewContext(input: BuildPlanReviewContextInput)truncated,};}++/**+ * Builds the non-plan half of issue-document review context. Plan context stays+ * on its legacy builder and payload field so plan-only wakes remain byte-for-byte+ * compatible. Budgets are shared across documents, while each document also+ * observes the legacy per-document limits.+ */+export async function buildDocumentReviewContext(+ input: BuildDocumentReviewContextInput,+): Promise<DocumentReviewContext | null> {+ if (input.includeForIssueComment !== true && input.includeForAnnotationDelta !== true) return null;++ const documentRows = await input.db+ .select({+ documentId: documents.id,+ documentKey: issueDocuments.key,+ title: documents.title,+ latestRevisionId: documents.latestRevisionId,+ latestRevisionNumber: documents.latestRevisionNumber,+ updatedAt: issueDocuments.updatedAt,+ })+ .from(issueDocuments)+ .innerJoin(documents, eq(issueDocuments.documentId, documents.id))+ .where(and(+ eq(issueDocuments.companyId, input.companyId),+ eq(issueDocuments.issueId, input.issueId),+ eq(documents.companyId, input.companyId),+ sql`${issueDocuments.key} <> 'plan'`,+ ))+ .orderBy(desc(issueDocuments.updatedAt), desc(issueDocuments.id));+ if (documentRows.length === 0) return null;++ let remainingThreads = PLAN_REVIEW_CONTEXT_LIMITS.maxThreads;+ let remainingComments = PLAN_REVIEW_CONTEXT_LIMITS.maxComments;+ let remainingBodyChars = PLAN_REVIEW_CONTEXT_LIMITS.maxTotalBodyChars;+ let totalOpenThreads = 0;+ let totalComments = 0;+ let includedThreads = 0;+ let includedComments = 0;+ let truncated = false;+ const groupedDocuments: DocumentReviewContextDocument[] = [];++ for (const document of documentRows) {+ const [{ count: openThreadCount }] = await input.db+ .select({ count: sql<number>`count(*)::int` })+ .from(documentAnnotationThreads)+ .where(and(+ eq(documentAnnotationThreads.companyId, input.companyId),+ eq(documentAnnotationThreads.issueId, input.issueId),+ eq(documentAnnotationThreads.documentId, document.documentId),+ eq(documentAnnotationThreads.documentKey, document.documentKey),+ eq(documentAnnotationThreads.status, "open"),+ ));+ if (openThreadCount === 0) continue;++ const perDocumentThreadLimit = Math.min(PLAN_REVIEW_CONTEXT_LIMITS.maxThreads, remainingThreads);+ const threadRows = perDocumentThreadLimit === 0 ? [] : await input.db+ .select({+ id: documentAnnotationThreads.id,+ documentId: documentAnnotationThreads.documentId,+ documentKey: documentAnnotationThreads.documentKey,+ status: documentAnnotationThreads.status,+ revisionId: documentAnnotationThreads.currentRevisionId,+ revisionNumber: documentAnnotationThreads.currentRevisionNumber,+ anchorState: documentAnnotationThreads.anchorState,+ anchorConfidence: documentAnnotationThreads.anchorConfidence,+ selectedText: documentAnnotationThreads.selectedText,+ prefixText: documentAnnotationThreads.prefixText,+ suffixText: documentAnnotationThreads.suffixText,+ createdByAgentId: documentAnnotationThreads.createdByAgentId,+ createdByUserId: documentAnnotationThreads.createdByUserId,+ createdAt: documentAnnotationThreads.createdAt,+ updatedAt: documentAnnotationThreads.updatedAt,+ })+ .from(documentAnnotationThreads)+ .where(and(+ eq(documentAnnotationThreads.companyId, input.companyId),+ eq(documentAnnotationThreads.issueId, input.issueId),+ eq(documentAnnotationThreads.documentId, document.documentId),+ eq(documentAnnotationThreads.documentKey, document.documentKey),+ eq(documentAnnotationThreads.status, "open"),+ ))+ .orderBy(desc(documentAnnotationThreads.updatedAt), desc(documentAnnotationThreads.id))+ .limit(perDocumentThreadLimit);++ const threadIds = threadRows.map((thread) => thread.id);+ const perDocumentCommentLimit = Math.min(PLAN_REVIEW_CONTEXT_LIMITS.maxComments, remainingComments);+ const commentRows = threadIds.length === 0 || perDocumentCommentLimit === 0 ? [] : await input.db+ .select({+ id: documentAnnotationComments.id,+ threadId: documentAnnotationComments.threadId,+ body: documentAnnotationComments.body,+ authorType: documentAnnotationComments.authorType,+ authorAgentId: documentAnnotationComments.authorAgentId,+ authorUserId: documentAnnotationComments.authorUserId,+ createdAt: documentAnnotationComments.createdAt,+ updatedAt: documentAnnotationComments.updatedAt,+ })+ .from(documentAnnotationComments)+ .where(and(+ eq(documentAnnotationComments.companyId, input.companyId),+ eq(documentAnnotationComments.issueId, input.issueId),+ eq(documentAnnotationComments.documentId, document.documentId),+ inArray(documentAnnotationComments.threadId, threadIds),+ ))+ .orderBy(asc(documentAnnotationComments.createdAt), asc(documentAnnotationComments.id))+ .limit(perDocumentCommentLimit);++ const [{ count: commentCount }] = await input.db+ .select({ count: sql<number>`count(*)::int` })+ .from(documentAnnotationComments)+ .innerJoin(documentAnnotationThreads, eq(documentAnnotationComments.threadId, documentAnnotationThreads.id))+ .where(and(+ eq(documentAnnotationComments.companyId, input.companyId),+ eq(documentAnnotationComments.issueId, input.issueId),+ eq(documentAnnotationComments.documentId, document.documentId),+ eq(documentAnnotationThreads.companyId, input.companyId),+ eq(documentAnnotationThreads.issueId, input.issueId),+ eq(documentAnnotationThreads.documentId, document.documentId),+ eq(documentAnnotationThreads.documentKey, document.documentKey),+ eq(documentAnnotationThreads.status, "open"),+ ));++ const commentsByThread = new Map<string, typeof commentRows>();+ for (const comment of commentRows) {+ const current = commentsByThread.get(comment.threadId) ?? [];+ current.push(comment);+ commentsByThread.set(comment.threadId, current);+ }++ let documentIncludedComments = 0;+ let documentTruncated = openThreadCount > threadRows.length;+ const threads = threadRows.map((thread) => {+ const selectedText = truncateText(thread.selectedText, PLAN_REVIEW_CONTEXT_LIMITS.maxAnchorTextChars);+ const prefixText = truncateText(thread.prefixText, PLAN_REVIEW_CONTEXT_LIMITS.maxAnchorTextChars);+ const suffixText = truncateText(thread.suffixText, PLAN_REVIEW_CONTEXT_LIMITS.maxAnchorTextChars);+ if (selectedText.truncated || prefixText.truncated || suffixText.truncated) documentTruncated = true;+ const sourceComments = commentsByThread.get(thread.id) ?? [];+ const comments = [];+ for (const comment of sourceComments) {+ if (remainingComments <= 0 || remainingBodyChars <= 0) {+ documentTruncated = true;+ break;+ }+ const body = truncateText(+ comment.body,+ Math.min(PLAN_REVIEW_CONTEXT_LIMITS.maxBodyChars, remainingBodyChars),+ );+ if (body.truncated) documentTruncated = true;+ remainingBodyChars -= body.text.length;+ remainingComments -= 1;+ documentIncludedComments += 1;+ includedComments += 1;+ comments.push({+ id: comment.id,+ threadId: comment.threadId,+ body: body.text,+ bodyTruncated: body.truncated,+ author: authorFrom(comment),+ createdAt: comment.createdAt.toISOString(),+ updatedAt: comment.updatedAt.toISOString(),+ });+ }+ const commentsTruncated = comments.length < sourceComments.length;+ if (commentsTruncated) documentTruncated = true;+ return {+ id: thread.id,+ documentKey: thread.documentKey,+ documentId: thread.documentId,+ status: thread.status,+ revisionId: thread.revisionId,+ revisionNumber: thread.revisionNumber,+ anchorState: thread.anchorState,+ anchorConfidence: thread.anchorConfidence,+ selectedText: selectedText.text,+ selectedTextTruncated: selectedText.truncated,+ prefixText: prefixText.text,+ prefixTextTruncated: prefixText.truncated,+ suffixText: suffixText.text,+ suffixTextTruncated: suffixText.truncated,+ author: authorFrom({ authorAgentId: thread.createdByAgentId, authorUserId: thread.createdByUserId }),+ commentCount: sourceComments.length,+ comments,+ commentsTruncated,+ createdAt: thread.createdAt.toISOString(),+ updatedAt: thread.updatedAt.toISOString(),+ };+ });++ remainingThreads -= threads.length;+ totalOpenThreads += openThreadCount;+ totalComments += commentCount;+ includedThreads += threads.length;+ if (commentCount > documentIncludedComments) documentTruncated = true;+ if (documentTruncated) truncated = true;+ groupedDocuments.push({+ documentKey: document.documentKey,+ documentId: document.documentId,+ title: document.title,+ latestRevisionId: document.latestRevisionId,+ latestRevisionNumber: document.latestRevisionNumber,+ threads,+ totals: {+ openThreadCount,+ includedThreadCount: threads.length,+ omittedThreadCount: Math.max(0, openThreadCount - threads.length),+ commentCount,+ includedCommentCount: documentIncludedComments,+ omittedCommentCount: Math.max(0, commentCount - documentIncludedComments),+ },+ truncated: documentTruncated,+ });+ }++ if (groupedDocuments.length === 0) return null;+ return {+ issueId: input.issueId,+ documents: groupedDocuments,+ totals: {+ openThreadCount: totalOpenThreads,+ includedThreadCount: includedThreads,+ omittedThreadCount: Math.max(0, totalOpenThreads - includedThreads),+ commentCount: totalComments,+ includedCommentCount: includedComments,+ omittedCommentCount: Math.max(0, totalComments - includedComments),+ },+ limits: { ...PLAN_REVIEW_CONTEXT_LIMITS },+ truncated,+ };+}diff --git a/ui/src/components/issue-properties/IssuePropertiesArtifactsTab.tsx b/ui/src/components/issue-properties/IssuePropertiesArtifactsTab.tsxindex 2612d3080a..4b9b2f67ed 100644--- a/ui/src/components/issue-properties/IssuePropertiesArtifactsTab.tsx+++ b/ui/src/components/issue-properties/IssuePropertiesArtifactsTab.tsx@@ -25,7 +25,9 @@ import {} from "@/lib/issue-artifacts";import { attachmentOpenPath } from "@/lib/issue-attachments";import { MarkdownBody } from "@/components/MarkdownBody";+import { DocumentAnnotationsCountChip, IssueDocumentAnnotations } from "@/components/IssueDocumentAnnotations";import { cn } from "@/lib/utils";+import { useLocation } from "@/lib/router";interface IssuePropertiesArtifactsTabProps {issue: Issue;@@ -116,28 +118,51 @@ function WorkProductRow({ workProduct }: { workProduct: IssueWorkProduct }) {return <div className={ROW_CLASS}>{body}</div>;}-function DocumentRow({ doc }: { doc: IssueDocument }) {+function DocumentRow({ issueId, doc }: { issueId: string; doc: IssueDocument }) {const [expanded, setExpanded] = useState(false);+ const [annotationPanelOpen, setAnnotationPanelOpen] = useState(false);+ const location = useLocation();const Chevron = expanded ? ChevronDown : ChevronRight;return (<div className="rounded-md border border-border bg-card/50">- <button- type="button"- onClick={() => setExpanded((open) => !open)}- className="flex w-full items-center gap-2 px-2.5 py-1.5 text-left text-sm hover:bg-accent/50"- aria-expanded={expanded}- >- <FileText className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />- <span className="min-w-0 flex-1 truncate">{documentDisplayTitle(doc)}</span>- <span className="shrink-0 text-(length:--text-micro) text-muted-foreground">- {`Rev ${doc.latestRevisionNumber ?? 1}`}- </span>- <Chevron className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />- </button>+ <div className="flex items-center hover:bg-accent/50">+ <button+ type="button"+ onClick={() => setExpanded((open) => !open)}+ className="flex min-w-0 flex-1 items-center gap-2 px-2.5 py-1.5 text-left text-sm"+ aria-expanded={expanded}+ >+ <FileText className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />+ <span className="min-w-0 flex-1 truncate">{documentDisplayTitle(doc)}</span>+ <span className="shrink-0 text-(length:--text-micro) text-muted-foreground">+ {`Rev ${doc.latestRevisionNumber ?? 1}`}+ </span>+ <Chevron className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />+ </button>+ <DocumentAnnotationsCountChip+ issueId={issueId}+ docKey={doc.key}+ panelOpen={annotationPanelOpen}+ onToggle={() => setAnnotationPanelOpen((open) => !open)}+ />+ </div>{expanded ? (<div className="border-t border-border px-2.5 py-2">{doc.body.trim().length > 0 ? (- <MarkdownBody>{doc.body}</MarkdownBody>+ <IssueDocumentAnnotations+ issueId={issueId}+ doc={doc}+ bodyMarkdown={doc.body}+ draftDirty={false}+ draftConflicted={false}+ historicalPreview={false}+ locationHash={location.hash}+ panelOpen={annotationPanelOpen}+ onPanelOpenChange={setAnnotationPanelOpen}+ panelPlacement="popover"+ >+ <MarkdownBody>{doc.body}</MarkdownBody>+ </IssueDocumentAnnotations>) : (<p className="text-sm text-muted-foreground">Document is empty.</p>)}@@ -200,7 +225,7 @@ export function IssuePropertiesArtifactsTab({ issue }: IssuePropertiesArtifactsT<ul className="flex flex-col gap-1">{documentRows.map((doc) => (<li key={doc.key}>- <DocumentRow doc={doc} />+ <DocumentRow issueId={issue.id} doc={doc} /></li>))}</ul>diff --git a/ui/src/components/issue-properties/IssuePropertiesDocumentAnnotations.test.tsx b/ui/src/components/issue-properties/IssuePropertiesDocumentAnnotations.test.tsxnew file mode 100644index 0000000000..6d6f4a0f4c--- /dev/null+++ b/ui/src/components/issue-properties/IssuePropertiesDocumentAnnotations.test.tsx@@ -0,0 +1,77 @@+// @vitest-environment jsdom++import { act } from "react";+import { createRoot } from "react-dom/client";+import type { Issue, IssueDocument } from "@paperclipai/shared";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { IssuePropertiesArtifactsTab } from "./IssuePropertiesArtifactsTab";+import { IssuePropertiesPlansTab } from "./IssuePropertiesPlansTab";++const issueDocument: IssueDocument = {+ id: "document-1",+ companyId: "company-1",+ issueId: "issue-1",+ key: "qa-evidence",+ title: "QA evidence",+ format: "markdown",+ body: "Shared annotation target",+ latestRevisionId: "revision-1",+ latestRevisionNumber: 1,+ createdByAgentId: null,+ createdByUserId: null,+ updatedByAgentId: null,+ updatedByUserId: null,+ lockedAt: null,+ lockedByAgentId: null,+ lockedByUserId: null,+ createdAt: new Date("2026-06-01T00:00:00.000Z"),+ updatedAt: new Date("2026-06-01T00:00:00.000Z"),+};++const issue = { id: "issue-1", identifier: "PAP-522", workMode: "standard" } as Issue;++vi.mock("@tanstack/react-query", () => ({ useQuery: () => ({ data: [] }) }));+vi.mock("@/hooks/useIssuePlanDocument", () => ({ useIssuePlanDocument: () => ({ data: null, isLoading: false }) }));+vi.mock("@/hooks/useIssueDocuments", () => ({ useIssueDocuments: () => ({ data: [issueDocument] }) }));+vi.mock("@/lib/router", () => ({ useLocation: () => ({ hash: "" }) }));+vi.mock("@/components/IssuePlanDecompositionsSection", () => ({ IssuePlanDecompositionsSection: () => null }));+vi.mock("@/components/MarkdownBody", () => ({ MarkdownBody: ({ children }: { children: string }) => <div>{children}</div> }));+vi.mock("@/components/IssueDocumentAnnotations", () => ({+ DocumentAnnotationsCountChip: ({ docKey }: { docKey: string }) => <span data-testid={`annotation-count-${docKey}`} />,+ IssueDocumentAnnotations: ({ doc, children }: { doc: IssueDocument; children: React.ReactNode }) => (+ <div data-testid={`annotation-surface-${doc.key}`} data-document-id={doc.id}>{children}</div>+ ),+}));++describe("issue properties document annotation mounting", () => {+ let container: HTMLDivElement;++ beforeEach(() => {+ container = document.createElement("div");+ document.body.appendChild(container);+ });++ afterEach(() => {+ container.remove();+ });++ it("uses the issue document key on the Plan tab", async () => {+ const root = createRoot(container);+ await act(async () => root.render(<IssuePropertiesPlansTab issue={issue} />));+ expect(container.querySelector('[data-testid="annotation-surface-qa-evidence"]')?.getAttribute("data-document-id"))+ .toBe("document-1");+ await act(async () => root.unmount());+ });++ it("shows the count while collapsed and mounts the same target when expanded on Artifacts", async () => {+ const root = createRoot(container);+ await act(async () => root.render(<IssuePropertiesArtifactsTab issue={issue} />));+ expect(container.querySelector('[data-testid="annotation-count-qa-evidence"]')).not.toBeNull();+ expect(container.querySelector('[data-testid="annotation-surface-qa-evidence"]')).toBeNull();+ const expand = container.querySelector('button[aria-expanded="false"]') as HTMLButtonElement;+ await act(async () => expand.click());+ expect(container.querySelector('[data-testid="annotation-surface-qa-evidence"]')?.getAttribute("data-document-id"))+ .toBe("document-1");+ await act(async () => root.unmount());+ });+});diff --git a/ui/src/components/issue-properties/IssuePropertiesPlansTab.tsx b/ui/src/components/issue-properties/IssuePropertiesPlansTab.tsxindex 904e49b628..1a5f90ea4c 100644--- a/ui/src/components/issue-properties/IssuePropertiesPlansTab.tsx+++ b/ui/src/components/issue-properties/IssuePropertiesPlansTab.tsx@@ -1,6 +1,6 @@import { useState } from "react";import { useQuery } from "@tanstack/react-query";-import type { Issue, IssueThreadInteraction } from "@paperclipai/shared";+import type { Issue, IssueDocument, IssueThreadInteraction } from "@paperclipai/shared";import { issuesApi } from "@/api/issues";import { queryKeys } from "@/lib/queryKeys";import { IssuePlanDecompositionsSection } from "@/components/IssuePlanDecompositionsSection";@@ -28,6 +28,45 @@ function hasPendingPlanConfirmation(interactions: IssueThreadInteraction[] | und);}+function OtherDocumentSection({ issueId, doc, locationHash }: { issueId: string; doc: IssueDocument; locationHash: string }) {+ const [annotationPanelOpen, setAnnotationPanelOpen] = useState(false);+ return (+ <section data-testid="issue-other-document" className="space-y-2 border-t border-border pt-4 first:border-t-0 first:pt-0">+ <div className="flex items-baseline justify-between gap-2">+ <h3 className="text-sm font-semibold">{documentDisplayTitle(doc)}</h3>+ <div className="flex shrink-0 items-center gap-1 text-xs text-muted-foreground">+ {`Revision ${doc.latestRevisionNumber ?? 1} · updated ${new Date(doc.updatedAt).toLocaleString([], {+ month: "short",+ day: "numeric",+ hour: "numeric",+ minute: "2-digit",+ })}`}+ <DocumentAnnotationsCountChip+ issueId={issueId}+ docKey={doc.key}+ panelOpen={annotationPanelOpen}+ onToggle={() => setAnnotationPanelOpen((open) => !open)}+ />+ </div>+ </div>+ <IssueDocumentAnnotations+ issueId={issueId}+ doc={doc}+ bodyMarkdown={doc.body}+ draftDirty={false}+ draftConflicted={false}+ historicalPreview={false}+ locationHash={locationHash}+ panelOpen={annotationPanelOpen}+ onPanelOpenChange={setAnnotationPanelOpen}+ panelPlacement="popover"+ >+ <MarkdownBody>{doc.body}</MarkdownBody>+ </IssueDocumentAnnotations>+ </section>+ );+}+/*** Plans tab of the properties pane.*@@ -120,20 +159,7 @@ export function IssuePropertiesPlansTab({ issue }: IssuePropertiesPlansTabProps)</section>) : null}{otherDocuments.map((doc) => (- <section key={doc.key} data-testid="issue-other-document" className="space-y-2 border-t border-border pt-4 first:border-t-0 first:pt-0">- <div className="flex items-baseline justify-between gap-2">- <h3 className="text-sm font-semibold">{documentDisplayTitle(doc)}</h3>- <span className="shrink-0 text-xs text-muted-foreground">- {`Revision ${doc.latestRevisionNumber ?? 1} · updated ${new Date(doc.updatedAt).toLocaleString([], {- month: "short",- day: "numeric",- hour: "numeric",- minute: "2-digit",- })}`}- </span>- </div>- <MarkdownBody>{doc.body}</MarkdownBody>- </section>+ <OtherDocumentSection key={doc.key} issueId={issue.id} doc={doc} locationHash={location.hash} />))}{hasPlans ? (<IssuePlanDecompositionsSection issueId={issue.id} issueIdentifier={issue.identifier} />