Files
PaperClipAI/tests/e2e/fixtures/agent-chat.mjs
T
DottaandPaperclip ab15aff390 feat: add experimental persistent agent chat (#13284)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Conversations must use the same tasks, controls, and execution
history.
> - Users need an ongoing chat with an agent without managing task
properties.
> - Agents should clarify and plan work, then hand execution to assigned
project tasks.
> - This pull request combines the reviewed Agent Chat stack for one
squash merge.
> - The benefit is persistent conversation with normal task governance
and shared UI.

## Linked Issues or Issue Description

**Subsystem affected**

Task lifecycle, agent runtime tools, shared task UI, and browser/paid
runner tests.

**Problem or motivation**

Users need one persistent conversation with each agent. A separate chat
store or renderer would duplicate task behavior and bypass existing
controls.

**Proposed solution**

Use a task-backed chat per company, user, and agent. Reuse the task
composer and transcript. Clarify and plan in chat, then create assigned
project tasks with the relevant plan. Keep Agent Chat behind its own
disabled-by-default experimental setting.

**Roadmap alignment**

This implements the task-backed direction in [CEO
Chat](https://github.com/paperclipai/paperclip/blob/master/ROADMAP.md#-ceo-chat).
Related proposals: #2504 and #9693. Related request: #7981. The
maintainer requested one squash merge of the complete stack.

Consolidates the reviewed runtime
[#13281](https://github.com/paperclipai/paperclip/pull/13281), backend
[#13282](https://github.com/paperclipai/paperclip/pull/13282), and UI
[#13283](https://github.com/paperclipai/paperclip/pull/13283) layers
with this PR's E2E coverage. All four layers passed CI and received
Greptile 5/5 before consolidation. This PR targets master and includes
the complete feature.

## What Changed

- Add personal canonical chat tasks with ordinary company visibility,
immutable identity, idempotent first sends, and an idle waiting state.
- Process `/new` in queue order. Preserve history, release a chat pause,
and fence old provider context and delayed writes.
- Keep chat lifecycle rules across recovery, finalization, assignment,
task lists, and rollups.
- Support research and plan revision in chat. Hand plans to ordinary
assigned project tasks before execution starts. Reject new chat
subtasks.
- Add repository-aware project creation and discovery tools, including
multiple repository IDs and GitHub URLs, authorization, idempotency, and
durable project-created cards.
- Reuse task UI components for chat, with starred/recent agent
navigation and a separate `enableAgentChat` experimental flag.
- Add deterministic browser tests and 24 paid chat cells across four
Codex/Claude profiles, with validated reports and screenshots.
- Integrate current master recovery, controller lease, queued-message,
and task UI changes. Gate chat interruption and deferred promotion on
ownership/feature policy. Guarantee lease renewal and active controls
are stopped even if teardown fails.
- Preserve master's migration 0273 and generate chat migration 0274 with
idempotent replay for development databases.

## Verification

- Prior exact heads of all four PRs passed Linux CI, including build,
typecheck, general/serialized tests, and browser E2E. Each had Greptile
5/5 and no unresolved findings.
- Integrated local verification passed: full repository typecheck and
production build, Storybook build, token gates, 340 focused UI tests,
all 20 deterministic chat browser tests, two migration replay tests, 88
focused chat/queue/native/controller tests, and provider/session
regressions including real lease expiry. These include the three
lifecycle regressions for the final admission/teardown fixes; server
typecheck also passes. Current head
`1268eda16cc2af892055917e7292f068820be135` has Greptile 5/5 with no
unresolved findings and passing security scans. All final-head CI gates
passed: build, full Runner verification, typecheck/release registry,
canary, all general/serialized test shards, and all browser E2E shards
([CI
run](https://github.com/paperclipai/paperclip/actions/runs/34696739927)).
Local PostgreSQL startup contention required serialized retries; skipped
fixtures do not count as passing coverage.
- The earlier paid campaign passed all 24 chat cells and retained 32
screenshots:
[report](https://d1p6rlowie26tp.cloudfront.net/runner-e2e/campaigns/gha-34648511170-1/index.html?report=agent-chat#suite-agent-chat).
It tested `abacbdfd2f660709ec37312cdb758284c8399d04`; it is prior
evidence, not a paid run of this integrated head.
- Manual check: enable Agent Chat in Experimental settings, open an
agent, clarify and revise a plan, then hand off to an assigned project
task. Stop a reply, send `/new`, and verify fresh context with retained
history. Disable the setting and verify agent shortcuts/new chat turns
are blocked.

## Risks

- Queue/session integration can affect retries and delayed writes. Tests
cover ownership, cancellation, reset boundaries, idle recovery, and
ordinary task behavior.
- Migration 0274 adds conversation fields and constraints. Replay is
idempotent and preserves existing development chat history.
- This combines the previously reviewed stack at the maintainer's
request. Agent Chat remains off by default and is separate from
Conference Room.

## Model Used

OpenAI Codex, GPT-6 Astra (`gpt-6-astra`), with reasoning, code
execution, browser tools, and parallel review. The exact context-window
size is not exposed in this session. Codex and Claude also ran as test
subjects in the linked paid campaign.

## 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 searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-09-12 08:56:04 -05:00

189 lines
6.5 KiB
JavaScript

// Deterministic provider: all effects use the real run-authenticated APIs/MCP transport.
// No DB writes, mocked Paperclip responses, provider calls, or outside workspaces.
const base = process.env.PAPERCLIP_API_URL;
const headers = {
Authorization: `Bearer ${process.env.PAPERCLIP_API_KEY}`,
"Content-Type": "application/json",
};
async function api(path, method = "GET", body) {
const response = await fetch(`${base}/api${path}`, {
method,
headers,
...(body ? { body: JSON.stringify(body) } : {}),
});
const data = await response.json();
if (!response.ok)
throw new Error(
`${method} ${path}: ${response.status} ${JSON.stringify(data)}`,
);
return data;
}
const run = await api(`/heartbeat-runs/${process.env.PAPERCLIP_RUN_ID}`);
const ctx = run.contextSnapshot;
const task = await api(`/issues/${ctx.issueId}`);
const comment = async (body) =>
api(`/issues/${task.id}/comments`, "POST", { body });
if (!task.conversationAgentId) {
const plan = await api(`/issues/${task.id}/documents/plan`);
await api(`/issues/${task.id}/documents/output`, "PUT", {
title: "Output",
format: "markdown",
body: `Execution received plan: ${plan.body}`,
});
await api(`/issues/${task.id}`, "PATCH", {
status: "done",
comment: "Execution finished with its initial plan.",
});
process.exit(0);
}
const comments = await api(`/issues/${task.id}/comments?order=asc`);
const current =
comments.find((c) => c.id === ctx.wakeCommentId) ??
comments.filter((c) => c.authorUserId).at(-1);
let command;
try {
command = JSON.parse(
current.body.startsWith("fixture:")
? Buffer.from(current.body.slice(8), "base64url").toString()
: current.body,
);
} catch {
command = { action: "reply", text: current.body };
}
if (
ctx.interactionKind === "request_confirmation" &&
ctx.interactionStatus === "accepted"
) {
const plan = await api(`/issues/${task.id}/documents/plan`);
command = {
action: "handoff",
plan: plan.body,
name: "Approved plan project",
key: ctx.interactionId,
};
}
if (ctx.interactionKind === "ask_user_questions")
command = { action: "reply", text: "Clarification received." };
const writePlan = async (body) => {
const documents = await api(`/issues/${task.id}/documents`);
const previous = documents.find((doc) => doc.key === "plan");
return api(`/issues/${task.id}/documents/plan`, "PUT", {
title: "Plan",
format: "markdown",
body,
baseRevisionId: previous?.latestRevisionId,
});
};
const mcp = async (name, args) => {
const result = await api("/mcp/project-tools", "POST", {
jsonrpc: "2.0",
id: 1,
method: "tools/call",
params: { name, arguments: args },
});
if (result.result?.isError || result.error)
throw new Error(JSON.stringify(result));
return result.result.structuredContent;
};
console.log("Deterministic chat provider received a turn");
if (command.action === "hold") {
await comment("Provider is streaming and ready to stop.");
// Keep a real provider process alive so Stop exercises cancellation and tree holds.
setInterval(() => console.log("Streaming discussion"), 250);
} else if (command.action === "delayed") {
await comment("Turn started before feature disable.");
await new Promise((resolve) => setTimeout(resolve, 3000));
await comment("Active turn settled after feature disable.");
} else if (command.action === "project" || command.action === "handoff") {
try {
const args = {
name: command.name ?? "Fixture project",
repositoryUrls: command.urls,
repositoryIds: command.ids,
workspace: command.workspace,
idempotencyKey: command.key ?? current.id,
};
const project = command.projectId
? await api(`/projects/${command.projectId}`)
: command.direct
? await api(`/companies/${task.companyId}/projects`, "POST", args)
: await mcp("create_project", args);
const retry = command.projectId
? project
: await mcp("create_project", args);
if (retry.id !== project.id)
throw new Error("Project retry created a duplicate");
if (command.action === "handoff") {
const plan = command.plan ?? "# Plan\n\nWrite the welcome note.";
if (!ctx.interactionId) await writePlan(plan);
const tasks = [];
for (let index = 0; index < (command.split ? 2 : 1); index++) {
const input = {
title: `Execution ${index + 1}`,
projectId: project.id,
initialPlan: `${plan}\nPart ${index + 1}`,
idempotencyKey: `${current.id}-${index}`,
};
const child = await mcp("create_task", input);
const again = await mcp("create_task", input);
if (again.id !== child.id)
throw new Error("Task retry created a duplicate");
tasks.push(`[${child.identifier}](/issues/${child.id})`);
}
await comment(`Handed off: ${tasks.join(", ")}`);
} else await comment(`Project registered: ${project.name}`);
} catch (error) {
await comment(`Expected tool result: ${error.message}`);
}
} else if (command.action === "plan") {
const plan = await writePlan(command.text);
if (command.approval)
await api(`/issues/${task.id}/interactions`, "POST", {
kind: "request_confirmation",
continuationPolicy: "wake_assignee",
payload: {
version: 1,
prompt: "Hand this plan off to an assigned project task?",
acceptLabel: "Approve handoff",
rejectLabel: "Revise",
rejectRequiresReason: true,
target: {
type: "issue_document",
key: "plan",
revisionId: plan.latestRevisionId,
revisionNumber: plan.latestRevisionNumber,
},
},
});
await comment("The draft plan is ready for discussion.");
} else if (command.action === "question") {
await api(`/issues/${task.id}/interactions`, "POST", {
kind: "ask_user_questions",
idempotencyKey: current.id,
continuationPolicy: "wake_assignee",
payload: {
version: 1,
questions: [
{
id: "audience",
prompt: "Who is the welcome note for?",
selectionMode: "single",
required: true,
options: [
{ id: "garden", label: "Garden club" },
{ id: "book", label: "Book club" },
],
},
],
},
});
await comment("Please choose an audience.");
} else if (command.action === "history") {
for (let index = 0; index < 65; index++)
await comment(`History message ${String(index).padStart(2, "0")}`);
} else {
await comment(
`Reply generation ${ctx.conversationSessionGeneration}: ${command.text}`,
);
}