fix(native): require publication for requested task documents

Co-Authored-By: Paperclip <noreply@paperclip.ing>

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);

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);
+  });
+});

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<boolean> {
+  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<void> {
   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:<attachmentId>. 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:<attachmentId> from the receipt, with /api/attachments/<attachmentId>/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),

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]));