From bf870fa7d37f3ad2a3e19d2e82362abf4e77bbd1 Mon Sep 17 00:00:00 2001 From: Dotta Date: Wed, 7 Oct 2026 01:58:23 -0500 Subject: [PATCH] fix(native): require publication for requested task documents Co-Authored-By: Paperclip --- .../native-completion-feedback.test.ts | 27 ++++++++++- .../native-deliverable-feedback.test.ts | 26 ++++++++++- .../native-deliverable-feedback.ts | 45 +++++++++++++++++-- .../native-runner-file-handoff.test.ts | 9 ++++ 4 files changed, 102 insertions(+), 5 deletions(-) diff --git a/server/src/services/native-runtime/native-completion-feedback.test.ts b/server/src/services/native-runtime/native-completion-feedback.test.ts index 45a70a9b45..441e93f049 100644 --- a/server/src/services/native-runtime/native-completion-feedback.test.ts +++ b/server/src/services/native-runtime/native-completion-feedback.test.ts @@ -1,7 +1,7 @@ import { randomUUID } from "node:crypto"; import { eq } from "drizzle-orm"; import { afterAll, beforeAll, describe, expect, it } from "vitest"; -import { agents, companies, createDb, heartbeatRuns, issues, issueThreadInteractions } from "@paperclipai/db"; +import { agents, companies, createDb, heartbeatRuns, issues, issueThreadInteractions, issueDocuments } from "@paperclipai/db"; import { startEmbeddedPostgresTestDatabase } from "../../__tests__/helpers/embedded-postgres.js"; import type { PrpStructuredRunResult } from "../../vendor/paperclip-runner/index.js"; import { documentService } from "../documents.js"; @@ -74,6 +74,31 @@ describe("native final-response feedback", () => { await db.update(issueThreadInteractions).set({ status: "answered" }).where(eq(issueThreadInteractions.id, questionId)); await expect(nativeCompletionFeedback(db, value.runId, waiting)).rejects.toThrow("without a pending wait condition"); }); + it("rejects completing a requested task document with only a workspace file", async () => { + const value = await fixture(); + await db.delete(issueDocuments).where(eq(issueDocuments.issueId, value.issueId)); + await db.update(issues).set({ description: "Create a short Markdown briefing document on this task." }).where(eq(issues.id, value.issueId)); + await db.update(heartbeatRuns).set({ resultJson: {} }).where(eq(heartbeatRuns.id, value.runId)); + const report = { ...done, summary: "Created briefing.md", evidence: [{ ref: "briefing.md" }] }; + await expect(nativeCompletionFeedback(db, value.runId, report)).rejects.toThrow("write_document"); + await expect(nativeCompletionFeedback(db, value.runId, { ...report, evidence: [] })).rejects.toThrow("write_document"); + const authority = new PaperclipRunnerToolAuthority(db, { companyId: value.companyId, agentId: value.agentId, issueId: value.issueId, runId: value.runId }); + await authority.execute({ tool: "write_document", callId: "briefing", arguments: { + idempotencyKey: "briefing", key: "briefing", title: "Briefing", body: "The retrieved page titles and verification code.", baseRevisionId: null, + } }); + await expect(nativeCompletionFeedback(db, value.runId, done)).resolves.toContain("Saved document"); + }); + it("does not accept a stale task-document receipt or another task's document", async () => { + const value = await fixture(), foreign = await fixture(); + await db.update(issues).set({ description: "Save a document on this task." }).where(eq(issues.id, value.issueId)); + await documentService(db).upsertIssueDocument({ format: "markdown", issueId: value.issueId, key: "output", title: "Updated", body: "Replacement revision", + baseRevisionId: value.saved.document.latestRevisionId, createdByAgentId: value.agentId, createdByRunId: null }); + await expect(nativeCompletionFeedback(db, value.runId, done)).rejects.toThrow("write_document"); + await db.update(heartbeatRuns).set({ resultJson: { semanticToolReceipts: { fake: { operationId: "write_document", result: { + disposition: "applied", document: foreign.saved.document, + } } } } }).where(eq(heartbeatRuns.id, value.runId)); + await expect(nativeCompletionFeedback(db, value.runId, done)).rejects.toThrow("write_document"); + }); it("returns a concrete final-answer link without treating the document title as instructions", async () => { const value = await fixture(); const feedback = await nativeCompletionFeedback(db, value.runId, done); diff --git a/server/src/services/native-runtime/native-deliverable-feedback.test.ts b/server/src/services/native-runtime/native-deliverable-feedback.test.ts index 724a0e152f..1cf1f33fc5 100644 --- a/server/src/services/native-runtime/native-deliverable-feedback.test.ts +++ b/server/src/services/native-runtime/native-deliverable-feedback.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { explicitlyRequestsFileOutput } from "./native-deliverable-feedback.js"; +import { explicitlyRequestsFileOutput, explicitlyRequestsTaskDocumentOutput } from "./native-deliverable-feedback.js"; describe("explicit file output requirements", () => { it.each([ @@ -35,3 +35,27 @@ describe("explicit file output requirements", () => { expect(explicitlyRequestsFileOutput(objective)).toBe(false); }); }); + + +describe("explicit task-document output", () => { + it.each([ + "Use the connected page service to find recent pages and create a short Markdown briefing document on this task. Include the titles and verification code returned by the service.", + "Save a document on this task.", + "Write a report document attached to the issue.", + ])("requires a published task document: %s", objective => { + expect(explicitlyRequestsTaskDocumentOutput(objective)).toBe(true); + }); + it.each([ + "Explain the document on this task.", + "Write a summary of the document on this task in chat.", + "Do not create a document on this task; reply inline.", + "Create no document on this task.", + "Write a response without a document on this task.", + "Create a document about this task in the repository.", + "Explain how to create a document on this task.", + "Create briefing.md in the workspace.", + "Connect HubSpot so you can read my recent contacts. If the contacts are unavailable, a brief explanation is enough instead of the contact list.", + ])("preserves other output scopes: %s", objective => { + expect(explicitlyRequestsTaskDocumentOutput(objective)).toBe(false); + }); +}); diff --git a/server/src/services/native-runtime/native-deliverable-feedback.ts b/server/src/services/native-runtime/native-deliverable-feedback.ts index 48aae1ace3..07a2416dcf 100644 --- a/server/src/services/native-runtime/native-deliverable-feedback.ts +++ b/server/src/services/native-runtime/native-deliverable-feedback.ts @@ -1,5 +1,5 @@ import { and, eq } from "drizzle-orm"; -import { assets, issueAttachments, issueWorkProducts, type Db } from "@paperclipai/db"; +import { assets, documents, issueDocuments, issueAttachments, issueWorkProducts, type Db } from "@paperclipai/db"; import type { PrpStructuredRunResult } from "../../vendor/paperclip-runner/index.js"; function evidenceRefs(value: unknown): string[] { @@ -86,6 +86,37 @@ export function explicitlyRequestsFileOutput(objective: string): boolean { }); } +/** An explicitly requested document on the task must be published there. */ +export function explicitlyRequestsTaskDocumentOutput(objective: string): boolean { + return objective.split(/(?:[.!?](?:\s|$)|\n|[;,]|\bbut\b)/iu).some(clause => { + const create = /\b(?:create|make|write|save|publish|prepare|provide|attach)\b/iu.exec(clause); + if (!create || /\b(?:do not|don't|never|no need to)\s*$/iu.test(clause.slice(0, create.index))) return false; + if (/\b(?:explain|describe|discuss|review)\b/iu.test(clause.slice(0, create.index))) return false; + const output = clause.slice(create.index + create[0].length); + return [...output.matchAll(/\b(?:document|doc)\b/giu)].some(match => { + const prefix = output.slice(0, match.index); + if (/\b(?:of|about|from|using|for|with|without|no|zero)\b/iu.test(prefix)) return false; + return /^\s+(?:on|to|in|attached to)\s+(?:this|the|current)\s+(?:task|issue)\b/iu.test(output.slice(match.index + match[0].length)); + }); + }); +} + +async function hasPublishedTaskDocument(db: Db, binding: { + companyId: string; issueId: string; semanticToolReceipts: unknown; +}): Promise { + const revisions = new Set(Object.values(record(binding.semanticToolReceipts)).flatMap(value => { + const receipt = record(value), result = record(receipt.result), document = record(result.document); + return receipt.operationId === "write_document" && ["applied", "duplicate"].includes(String(result.disposition)) + && typeof document.id === "string" && typeof document.latestRevisionId === "string" + ? [`${document.id}/${document.latestRevisionId}`] : []; + })); + if (!revisions.size) return false; + const saved = await db.select({ id: documents.id, revisionId: documents.latestRevisionId }) + .from(issueDocuments).innerJoin(documents, and(eq(documents.id, issueDocuments.documentId), eq(documents.companyId, binding.companyId))) + .where(and(eq(issueDocuments.companyId, binding.companyId), eq(issueDocuments.issueId, binding.issueId))); + return saved.some(document => revisions.has(`${document.id}/${document.revisionId}`)); +} + /** Files cited as completed output must be reachable outside the agent workspace. */ export async function validateNativeDeliverableEvidence( db: Db, @@ -94,6 +125,8 @@ export async function validateNativeDeliverableEvidence( ): Promise { if (result.reportedWorkDisposition !== "done") return; const fileRequested = explicitlyRequestsFileOutput(binding.objective); + const taskDocumentRequested = explicitlyRequestsTaskDocumentOutput(binding.objective); + const publishedTaskDocument = taskDocumentRequested && await hasPublishedTaskDocument(db, binding); const artifactRefs = new Set(evidenceRefs(result.artifacts)); const refs = new Set([ ...evidenceRefs(result.evidence), @@ -122,8 +155,8 @@ export async function validateNativeDeliverableEvidence( // this run published the newly requested output. The receipt survives a // controller restart of this run; a replacement can re-register preserved // workspace bytes internally rather than asking the user to confirm them. - if (fileRequested && attachment.originatingRunId !== binding.runId) continue; - if (fileRequested && !await hasCurrentPublicationReceipt(db, binding.companyId, binding.semanticToolReceipts, attachment)) { + if ((fileRequested || taskDocumentRequested) && attachment.originatingRunId !== binding.runId) continue; + if ((fileRequested || taskDocumentRequested) && !await hasCurrentPublicationReceipt(db, binding.companyId, binding.semanticToolReceipts, attachment)) { throw new Error("This attachment has no matching verified publication receipt for this run's requested output. Inspect any preserved file and use register_deliverable to verify its current filename, size, and SHA-256, then cite the new receipt. No human completion approval was created."); } registeredAttachment = true; @@ -133,10 +166,16 @@ export async function validateNativeDeliverableEvidence( // belong in verification; do not scan prose or upload files named by a model. const localFile = /^(?:file:|\.{0,2}\/|[a-z]:[\\/])/iu.test(ref) || (!/^[a-z][a-z0-9+.-]*:/iu.test(ref) && /^[^\r\n]+\.[a-z0-9]{1,16}(?::\d+(?::\d+)?)?$/iu.test(ref)); + if (localFile && taskDocumentRequested && !publishedTaskDocument) { + throw new Error("The requested task document is only a workspace file. Publish it on this task with write_document, or attach the verified file with register_deliverable and cite deliverable:. Reuse completed work; do not request a new completion approval."); + } if (localFile && (fileRequested || artifactRefs.has(value))) { throw new Error("Completion cites a workspace-only file that the user cannot download. Before finishing, use register_deliverable for requested file outputs and cite deliverable: from the receipt, with /api/attachments//content as the download link. For repository changes, cite an accessible PR or registered work product instead. No human completion approval was created."); } } + if (taskDocumentRequested && !publishedTaskDocument && !registeredAttachment) { + throw new Error("The requested document has not been published on this task. Use write_document, or register_deliverable with its verified attachment receipt. A workspace path or final message alone is not the requested task document. Reuse completed work without requesting a new completion approval."); + } if (fileRequested && !registeredAttachment) { const products = refs.size ? await db.select().from(issueWorkProducts).where(and( eq(issueWorkProducts.companyId, binding.companyId), eq(issueWorkProducts.issueId, binding.issueId), diff --git a/server/src/services/native-runtime/native-runner-file-handoff.test.ts b/server/src/services/native-runtime/native-runner-file-handoff.test.ts index 367671dd2e..1fabdfc7dd 100644 --- a/server/src/services/native-runtime/native-runner-file-handoff.test.ts +++ b/server/src/services/native-runtime/native-runner-file-handoff.test.ts @@ -315,6 +315,15 @@ describe("native runner file handoff", () => { await expect(nativeCompletionFeedback(db, runId, doneReport([`deliverable:${first.entityRefs[0]}`]))) .resolves.toContain("Completion report accepted"); + await db.update(issues).set({ title: "Create a Markdown document on this task." }).where(eq(issues.id, issueId)); + try { + await expect(nativeCompletionFeedback(db, runId, doneReport([`deliverable:${first.entityRefs[0]}`]))) + .resolves.toContain("Completion report accepted"); + await expect(nativeCompletionFeedback(db, runId, doneReport(["out/answer.txt"]))) + .rejects.toThrow("write_document"); + } finally { + await db.update(issues).set({ title: "Prepare a requested file" }).where(eq(issues.id, issueId)); + } const otherIssueId = "00000000-0000-4000-8000-000000009111"; await db.insert(issues).values({ id: otherIssueId, companyId, title: "Unrelated file", status: "in_progress" }); await db.update(issueAttachments).set({ issueId: otherIssueId }).where(eq(issueAttachments.id, first.entityRefs[0]));