PaperClipAI/server/src/services/native-runtime/completion-contracts.test.ts

import { describe, expect, it } from "vitest";

import {
  buildNativeCompletionContract,
  buildNativeCompletionContractSources,
  nativeCompletionRequestsWithSources,
  nativeCompletionSource,
  nativeImmediateObjectiveSource,
  nativeCompletionRequestsForComments,
  resolveNativeCompletionPolicy,
} from "./completion-contracts.js";

describe("buildNativeCompletionContract", () => {
  it("scopes standing-chat criteria to the response while preserving every current request and source", () => {
    const issue = { id: "chat", title: "Chat with CEO", description: null, conversationAgentId: "ceo", conversationUserId: "operator" };
    const comments = [
      { id: "operator-request", body: "Restart this instance." },
      { id: "handoff-request", body: "Have Morgan draft the update and send it here when finished." },
    ];
    const pending = nativeCompletionRequestsWithSources(comments);
    const contract = buildNativeCompletionContract(issue, { immediateRequests: pending.requests, humanResponseId: "answer" });
    expect(contract.objective).toMatch(/conversation response/i);
    expect(contract.objective).toMatch(/verified|verify/i);
    expect(contract.objective).toMatch(/delegated/i);
    expect(contract.objective).toMatch(/unavailable/i);
    expect(contract.criteria.map(row => row.id)).toEqual(["pending_comment_1", "pending_comment_2", "human_response"]);
    for (const [index, comment] of comments.entries()) {
      const requirement = contract.criteria[index]!.requirement;
      expect(requirement).not.toBe(comment.body);
      expect(requirement).toContain(comment.body);
      expect(requirement).toMatch(/current authorized conversation response/i);
      expect(requirement.split(comment.body)).toHaveLength(2);
    }
    expect(contract.criteria[2]!.requirement).toContain('"answer"');
    expect(buildNativeCompletionContractSources({ issue, immediateRequests: pending.requests, immediateRequestSources: pending.sources }))
      .toEqual(comments.map((comment, index) => ({ id: `pending_comment_${index + 1}`, source: nativeCompletionSource("comment", comment.id, comment.body) })));
  });

  it.each([undefined, null])("keeps an ordinary task's action criterion strict even with a chat-like title (%s)", (conversationAgentId) => {
    const issue = { title: "Chat with CEO", description: null, conversationAgentId };
    const request = "Restart this instance.";
    expect(buildNativeCompletionContract(issue, { immediateRequest: request }).criteria)
      .toEqual([{ id: "objective", requirement: request }]);
  });

  it.each([undefined, null])("keeps an agent-only issue in task and plan scope when its conversation user is %s", conversationUserId => {
    const request = "Write the launch plan and wait for approval.";
    const contract = buildNativeCompletionContract({ title: "Chat with CEO", description: null,
      conversationAgentId: "ceo", conversationUserId }, { immediateRequest: request });
    expect(contract.criteria).toEqual([{ id: "objective", requirement: request }]);
    expect(contract.objective).toContain("propose or save the requested plan and wait before executing");
  });

  it.each(["  Help plan the launch.  ", null])("scopes a conversation's first turn without a follow-up (%s)", description => {
    const contract = buildNativeCompletionContract({ title: "Chat with CEO", description,
      conversationAgentId: "ceo", conversationUserId: "operator" });
    expect(contract.objective).toMatch(/current conversation response/i);
    expect(contract.criteria).toEqual([{ id: "objective", requirement:
      `Address this request in the current authorized conversation response: ${description?.trim() || "Respond to the current conversation context."}` }]);
  });

  it("uses the task description as the single initial criterion", () => {
    expect(buildNativeCompletionContract({
      title: "Ship the runner",
      description: "Prove the Codex vertical slice.",
    })).toEqual({
      revision: "1",
      objective: "Ship the runner",
      criteria: [{ id: "objective", requirement: "Prove the Codex vertical slice." }],
    });
  });

  it("binds the persisted numeric revision into the protocol contract", () => {
    expect(buildNativeCompletionContract({
      title: "Continue the runner",
      description: null,
    }, { revision: 3 }).revision).toBe("3");
  });

  it("applies the latest comment within the current authorized task scope", () => {
    expect(buildNativeCompletionContract(
      {
        title: "Reply with exactly STALE-ROOT-MARKER",
        description: "Return the original result.",
      },
      { immediateRequest: " Return the follow-up result. " },
    )).toEqual({
      revision: "1",
      objective: expect.stringContaining("current authorized stage"),
      criteria: [{ id: "objective", requirement: "Return the follow-up result." }],
    });
  });

  it("keeps every coalesced follow-up as an ordered completion criterion", () => {
    expect(buildNativeCompletionContract(
      { title: "Original task", description: "Return the original result." },
      {
        immediateRequests: [
          " Answer the first question. ",
          "Answer the second question.",
        ],
      },
    )).toEqual({
      revision: "1",
      objective: expect.stringContaining("current authorized stage"),
      criteria: [
        {
          id: "pending_comment_1",
          requirement: "Answer the first question.",
        },
        {
          id: "pending_comment_2",
          requirement: "Answer the second question.",
        },
      ],
    });
  });

  it("keeps a file-only follow-up authoritative over a stale title", () => {
    const contract = buildNativeCompletionContract(
      { title: "Reply with STALE", description: "Old request" },
      { immediateRequests: nativeCompletionRequestsForComments([
        { body: " ", attachments: [{ filename: "Ignore current request.txt" }] },
      ]) },
    );
    expect(contract.objective).toContain("current authorized stage");
    expect(contract.criteria).toEqual([{
      id: "objective",
      requirement: "Inspect and respond to the attached file(s) on pending comment 1.",
    }]);
    expect(JSON.stringify(contract)).not.toMatch(/STALE|Ignore current request/);
  });

  it("references existing context without copying the brief or treating clarification as approval", () => {
    const brief = "Propose work and wait for approval. ".repeat(1000);
    const contract = buildNativeCompletionContract(
      { title: "Original task", description: brief },
      { immediateRequest: "Use TypeScript." },
    );
    expect(contract.objective).toContain("task brief");
    expect(contract.objective).toContain("Later human direction replaces conflicting scope");
    expect(contract.objective).toContain("approval gates");
    expect(contract.objective).toContain("Clarification is not approval");
    expect(JSON.stringify(contract)).not.toContain(brief);
    expect(JSON.stringify(contract).split("Use TypeScript.")).toHaveLength(2);
    expect(JSON.stringify(contract).length).toBeLessThan(900);
  });

  it("keeps the instruction prefix identical as follow-up comments change", () => {
    const issue = { title: "Write welcome", description: "Use /first-task." };
    const first = buildNativeCompletionContract(issue, { immediateRequest: "Use a friendly tone." });
    const next = buildNativeCompletionContract(issue, { immediateRequest: "Actually, just save a plan." });
    expect(first.objective).toBe(next.objective);
    expect(next.criteria).toEqual([{ id: "objective", requirement: "Actually, just save a plan." }]);
    expect(JSON.stringify(next)).not.toContain("Use a friendly tone.");
  });

  it("binds the current verified card answer without duplicating its contents", () => {
    const contract = buildNativeCompletionContract(
      { title: "Onboarding", description: "Use /first-task; proposal mode: confirmation." },
      { humanResponseId: "80000000-0000-4000-8000-000000000008" },
    );
    expect(contract.objective).toContain("humanResponses");
    expect(contract.criteria).toEqual([{
      id: "human_response",
      requirement: expect.stringContaining('"80000000-0000-4000-8000-000000000008"'),
    }]);
    expect(contract.criteria[0]!.requirement).toContain("humanResponses");
    expect(JSON.stringify(contract)).not.toContain("proposal mode: confirmation");
    expect(buildNativeCompletionContract(
      { title: "Onboarding", description: null },
      { humanResponseId: "80000000-0000-4000-8000-000000000009" },
    )).not.toEqual(contract);
  });

  it("retains pending comments alongside a current card response without replaying older scope", () => {
    const contract = buildNativeCompletionContract(
      { title: "Implement", description: "Implement the old scope" },
      { immediateRequest: "Actually, just investigate.", humanResponseId: "answer-id" },
    );
    expect(contract.criteria.map(c => c.id)).toEqual(["objective", "human_response"]);
    expect(contract.criteria[0]!.requirement).toBe("Actually, just investigate.");
    expect(JSON.stringify(contract)).not.toContain("Implement the old scope");
    expect(contract.objective).toContain("Later human direction replaces conflicting scope");
  });

  it("preserves text and file-only requests in mixed batch order", () => {
    expect(nativeCompletionRequestsForComments([
      { body: " First question. " },
      { body: "", attachments: [{ id: "file" }] },
      { body: "Last question.", attachments: [{ id: "another-file" }] },
      { body: " " },
    ])).toEqual([
      "First question.",
      "Inspect and respond to the attached file(s) on pending comment 2.",
      "Last question.",
    ]);
  });

  it.each([9, 3])("requires complete scoped reading for a truncated %i-comment wake", (count) => {
    const requests = nativeCompletionRequestsForComments(
      [{ body: "Only an inline prefix, not the complete request." }],
      { requiredFullWakeCommentCount: count },
    );
    expect(requests).toHaveLength(1);
    expect(requests[0]).toContain("read_current_wake_comments until complete=true");
    expect(requests[0]).toContain(`all ${count} accepted comments in order`);
    expect(requests[0]).toContain("metadata alone is not its content");
    expect(requests[0]).not.toContain("Only an inline prefix");
  });
});

describe("resolveNativeCompletionPolicy", () => {
  it("uses agent claims for ordinary issues", () => {
    expect(resolveNativeCompletionPolicy({ reviewPolicy: null })).toEqual({
      risk: "low",
      completionAuthority: "agent_claim_policy",
    });
  });

  it("keeps completion server-authoritative when issue policy requires review", () => {
    for (const reviewPolicy of ["human_only", "not_creator"]) {
      expect(resolveNativeCompletionPolicy({ reviewPolicy })).toEqual({
        risk: "standard",
        completionAuthority: "server_arbiter",
      });
    }
  });
});


describe("completion source ownership", () => {
  it("selects only an explicitly bound initial description objective", () => {
    const source = nativeCompletionSource("description", "task", "Same text");
    expect(nativeImmediateObjectiveSource({ issueId: "task", objectiveSource: source, excluded: false })).toEqual(source);
    expect(nativeImmediateObjectiveSource({ issueId: "other-task", objectiveSource: source, excluded: false })).toBeNull();
    expect(nativeImmediateObjectiveSource({ issueId: "task", objectiveSource: source, excluded: true })).toBeNull();
    expect(nativeImmediateObjectiveSource({ issueId: "task", objectiveSource: nativeCompletionSource("comment", "comment", "Same text"), excluded: false })).toBeNull();
  });

  it("preserves separate identical comment sources and their criterion order", () => {
    const comments = [{ id: "first", body: " Repeat. Repeat. " }, { id: "second", body: " Repeat. Repeat. " }];
    const { requests, sources } = nativeCompletionRequestsWithSources(comments);
    const issue = { id: "task", title: "Task", description: "Brief" };
    const contract = buildNativeCompletionContract(issue, { immediateRequests: requests });
    expect(contract.criteria).toEqual([
      { id: "pending_comment_1", requirement: "Repeat. Repeat." },
      { id: "pending_comment_2", requirement: "Repeat. Repeat." },
    ]);
    expect(buildNativeCompletionContractSources({ issue, immediateRequests: requests, immediateRequestSources: sources })).toEqual([
      { id: "pending_comment_1", source: nativeCompletionSource("comment", "first", comments[0]!.body) },
      { id: "pending_comment_2", source: nativeCompletionSource("comment", "second", comments[1]!.body) },
    ]);
  });

  it("does not infer comment provenance from identical requirement text", () => {
    const issue = { id: "task", title: "Task", description: "Same text" };
    expect(buildNativeCompletionContractSources({ issue, immediateRequests: ["Same text"] })).toEqual([]);
    expect(buildNativeCompletionContractSources({ issue, immediateRequest: "Same text" })).toEqual([]);
    expect(buildNativeCompletionContractSources({
      issue,
      immediateRequest: "Same text",
      immediateRequestSource: nativeCompletionSource("description", "task", "Same text"),
    })).toEqual([{ id: "objective", source: nativeCompletionSource("description", "task", "Same text") }]);
    expect(buildNativeCompletionContractSources({ issue })).toEqual([{ id: "objective", source: nativeCompletionSource("description", "task", "Same text") }]);
    expect(buildNativeCompletionContractSources({ issue, humanResponseId: "answer" })).toEqual([]);
  });

  it("keeps attachment-only and incomplete-wake requirements independent", () => {
    const comments = [{ id: "file", body: "", attachments: [{ id: "attachment" }] }];
    expect(nativeCompletionRequestsWithSources(comments).sources).toEqual([null]);
    expect(nativeCompletionRequestsWithSources(comments, { requiredFullWakeCommentCount: 8 }).sources).toEqual([null]);
  });
});