History

Dotta 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
..
fixtures	feat: add experimental persistent agent chat (#13284 )	2026-09-12 08:56:04 -05:00
provider-schemas	Add end-to-end session goals to Paperclip Runner	2026-09-08 16:18:47 -05:00
schemas	Add end-to-end session goals to Paperclip Runner	2026-09-08 16:18:47 -05:00
README.md	Add end-to-end session goals to Paperclip Runner	2026-09-08 16:18:47 -05:00
manifest.json	feat: add experimental persistent agent chat (#13284 )	2026-09-12 08:56:04 -05:00

README.md

PRP v1/v2 Contract

The JSON Schema files in schemas/ are the language-neutral source of truth for Paperclip Runner Protocol versions 1 and 2. The fixtures in fixtures/ define accepted and rejected compatibility cases.

Compatibility

protocolVersion, fixtureVersion, and event.schemaVersion are required.
A consumer fails closed when a required version or schema discriminator is not supported.
A v1 envelope can contain an unknown optional property when its schema marks that object as extensible.
A consumer ignores an unknown optional property until a later contract gives it meaning.
A required field, enum value, or typed structured-input field is not optional.
Question and answer identifiers are stable across the provider boundary.
Peers negotiate the highest mutually supported protocol version. Existing v1 runners remain compatible but cannot receive v2-only session-goal commands.

The unknown-optional-fields.json fixture must be accepted. The unsupported-required-version.json fixture must be rejected.

Session goals (v2)

PRP v2 adds a provider-neutral durable session-goal lifecycle. Every v2 capability snapshot includes sessionGoals, even when its availability is unsupported or policy_disabled. Paperclip sends controls only when the negotiated capability advertises the corresponding action.

Commands:

session.goal.get
session.goal.set for objective, status, and optional token budget changes
session.goal.clear

Events:

session.capabilities.updated
session.goal.snapshot
session.goal.updated
session.goal.cleared

Goal state is separate from Paperclip's company/business goal hierarchy. The snapshot distinguishes the durable status from workingNow, because an active goal can be idle between autonomous turns. A runner emits the full capability and authoritative snapshot after every session open or resume. Missing v1 capability is unsupported; clients do not infer support from an adapter name.

Scope

The first provider descriptor and adapter fixture cover Codex only. The schemas for provider-neutral events and semantic receipts do not enable those actions. Discovery and authorization are separate contracts.

The conformance manifest records every source file and its SHA-256 digest. Run pnpm generate:protocol-manifest from this package after a source change. CI runs the same generator with --check to reject drift. This check also compiles the JSON Schemas and validates every replay, question, and cross-language conformance fixture against its declared schema.

The files in fixtures/replay/golden/ are deterministic reducer oracles. Each accepted replay fixture has a complete session snapshot and a compact parity summary. pnpm generate:replay-goldens updates them after an intentional reducer change; package build and CI fail when they drift.

The files in fixtures/local-runner/scripts/ drive the package-local fake harness. They cover successful, failed, interrupted, interactive, duplicate terminal, process-cleanup, and oversized-frame behavior without starting a production adapter.