Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-01 06:42:06 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
b866fa4bdc940469eb668d3ea7938e7039b442ec
PaperClipAI/maps/agent-access-map/agent-chat.md
T
DottaandPaperclip 8ff812cdde feat(chat): deliver proactive task messages to agent chats (#18374) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agent Chat gives each person a persistent conversation with each
agent.
> - Tasks and routines produce results outside that conversation.
> - Those runs need a safe way to bring a requested result back to the
person.
> - The server must select the agent's own chat and check the source
task's access rules.
> - This pull request adds proactive chat messages and unread
indicators.
> - People can see the result, open its source task, and reply in the
same chat.

## Linked Issues or Issue Description

**Subsystem affected**

Server, native runner tools, shared contracts, database, and UI.

**Problem or motivation**

An agent can report progress on a task or comment on an authorized task.
It cannot send a routine result to its own standing chat with the
responsible person. A morning review routine therefore cannot leave a
visible digest in that person's chat.

**Proposed solution**

Add `send_chat_message({body, idempotencyKey})` and `POST
/api/agents/me/chat/messages`. The server selects the company, agent,
and responsible person from the active run. It saves an attributed
comment and audit record in one transaction. The chat shows a
source-task link and per-person unread state.

**Alternatives considered**

A destination parameter on a generic comment tool would expose
unnecessary routing authority. A new delivery worker would add another
durable delivery path. This change uses a dedicated tool and the
existing comment and live-event paths.

**Roadmap alignment**

This extends the experimental Agent Chat capability in `ROADMAP.md`. The
existing `enableAgentChat` setting controls it. Related public work:
Refs #13282, Refs #13283, and Refs #14408. Searches for proactive chat
and unread chat found no duplicate PR.

## What Changed

- Add a focused messaging service shared by the native tool and HTTP
route. It checks current run ownership, execution mode, recipient
membership, task access, and task privacy.
- Reuse the canonical company/agent/person conversation. Save the
comment and audit record together. Keep task completion and chat
execution separate from delivery.
- Add source-task provenance and source-scoped retry keys. Identical
retries return the saved receipt. Changed content returns a conflict.
- Enforce the conversation's fixed agent at the shared comment-write
boundary. Keep normal reply cancellation and session checks.
- Add chat unread state, accessible agent dots, aggregate Chat
indicators, and visible-message read cutoffs. Refresh through existing
live events.
- Add the request-key constraint, native tool contracts, documentation,
capability maps, stories, and regression coverage.

## Verification

- Local delivery/security proof: all 38 proactive-message cases pass.
Eight credential-scope regressions and four quota regressions fail
against the prior source. The repaired delivery and canonical
cross-issue cap suites pass all 49 cases; all 31 OpenAPI tests, server
typecheck, and capability-map checks pass. The shared per-run cap covers
native and HTTP sends, mixed ordinary mutations, concurrent last-slot
contention, and retry/recovery without double charging.
- Credential tests preserve the authenticated person and authorizer;
reject bridge/test credentials and persisted skill-test runs after
task-mode changes; and recheck API-key revocation, scope, and
responsible person after destination locking. The earlier
delivery/native-authority suites passed all 74 cases before the four
quota additions.
- Four PostgreSQL contention cases cover native and HTTP sends plus
retries during a native chat mutation. All four deadlock against the
earlier source and pass with destination-before-source/run locking.
Recovery and human-reply delivery enqueue only the human comment; a
proactive digest never wakes the chat agent.
- Passed 108 companion conversation, native-authority, and OpenAPI
tests; 112 runner catalog/workflow-report tests; 47 completion-delivery
tests; and 25 project-handoff tests. Focused runner tests cover native
tool availability without generic API tools.
- All 327 affected UI tests, UI typecheck, token gates, and catalog
checks pass. The read hook retries at most three times, respects server
retry delay, coalesces only seen cutoffs, recovers on reconnect, and
cancels on scope changes.
- Real browser journeys with a deterministic process agent verify
routine-to-chat delivery, first-chat creation, unread state across
reload, the source link, secondary chat navigation, and a follow-up
reply referring to the digest. This does not qualify live GitHub
retrieval or model output quality.
- The Storybook showcase uses production components with deterministic
network fixtures. Rendered interactions pass for the landing, ordinary
read success, transient read recovery, and persistent failure after
bounded retries. Both Chat navigation variants update from two unread
chats to one while only Kodi's dot clears. Mobile and light variants
were reviewed. The existing Coordinator Recents label contrast finding
is unchanged; no Linux visual baseline archive exists.
- Current master's independent sandbox migration retains 0418.
Regenerated the feature migration as 0419 from the combined schema and
retained exactly the newest five snapshots; numbering/safety, replay,
and schema-drift checks pass.
- Workspace typecheck and build passed before PR preparation; canonical
server/UI typechecks passed again on the combined tree. Migration
`0419_slippery_impossible_man.sql` passes safety and schema drift checks
on disposable PostgreSQL, including interrupted index repair, concurrent
migrators, one-time owner read-state backfill, preserved receipts, and
two SQL replays. A default five-second local snapshot comparison timed
out; a diagnostic 30-second run passed without drift.
- Earlier failures are retained in the record: full local `pnpm
test:run` and broad shards encountered embedded-PostgreSQL startup,
timing, and provider-recovery failures. Thirteen selected
external-channel cases pass in isolation on the original and changed
sources; an unordered comment-row assertion now explicitly orders both
reads. The earlier route registry, native tool count, runner catalog,
and accessible Chat badge-name failures were fixed and passed full
remote CI on `920b3bb7db`.
- Repeated managed-skill server8 failures came from CI's newer synthetic
merge: its Cloud guard correctly rejected the old local-disk fixture.
Master independently repaired the fixture in #18385; this branch keeps
that repair unchanged. All 57 managed-skill and Cloud prerequisite cases
pass on the combined tree, and that fixture has no remaining PR diff.
- Current reviewed head `dc16f314739a6d977bed21cb1446d0e80a541578`:
Greptile 5/5 with no findings, Superagent security assessment passed,
advisory Paperclip Review 5/5 with no findings, and zero open review
threads. All 55 current-head check runs pass, with five expected skips
and the advisory review neutral at 5/5; Snyk also passes. No checks are
pending or failing. Protected squash auto-merge is enabled and is
waiting for required code-owner approval. A normal exact-head merge was
refused by the base-branch policy; no admin bypass was used. The
previous head's Superagent quota finding is fixed and covered above.

## Risks

- Chat remains company-visible. Delivery rejects a source task with
private-task, project, or ancestor restrictions.
- Read state uses a comment timestamp cutoff. The server retains
database precision and never moves a read receipt backward.
- The new unique constraint changes comment query planning. An existing
regression now uses an explicit row order. The migration builds the
unique index concurrently, then takes a brief table lock to attach it.
It uses the existing top-level migration and interrupted-index recovery
path.
- The upgrade backfills missing chat-owner read-state rows at the latest
existing agent comment. Existing read receipts remain intact. New chats
can still be unread before the human participates.
- Quota observation commits atomically with delivery. A rejected send
rolls back its attempted denial audit row and any first-chat creation;
the canonical warning remains in server logs, and previously spent quota
remains enforced. Identical/conflicting retries and receipt recovery
spend no extra slot.
- This version delivers in-app only. It adds no external-channel, push,
or email delivery.
- Local full-suite acceptance remains limited by the failures recorded
above. The feature stays behind `enableAgentChat`.

## Model Used

OpenAI Codex. PR preparation and CI work used `gpt-6.1-sol` with tool
use and code execution. The earlier implementation also used Codex, but
its exact model ID was not recorded in the visible session. The
context-window size was not provided.

## 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 focused tests locally and they pass; the broad local
failures are recorded above
- [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-10-30 21:39:07 -05:00

187 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Agent conversations and project handoff — agent access
Product map: [Agent conversations and project handoff](../feature-map/agent-chat.md).
Feature ID: `agent-chat`.
Review date: 2026-10-12. Source commit: `f981fa3cc10cb8663a87dec60345fbff46d54d0a`.
This is a source-reviewed baseline of representative operations and known gaps.
Each capability needs operation-level review before its entire scope can be
qualified. No live agent execution is claimed. Follow the [map contract](../README.md)
for format, permission checks, evidence and maintenance.
## `discovery`
Capability ID: `agent-chat/discovery`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `GET /api/companies/{companyId}/chats`.
- `GET /api/companies/{companyId}/chats/{agentRef}`.
Agent access: `restricted` — Board-user REST; the responding agent gets its assigned
conversation context.
Policy: Conversation discovery/creation requires a board user and the Agent Chat gate;
task access follows task visibility.
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts#L18077) at
the reviewed commit above.
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Agents cannot enumerate or create another person's standing chats. Detail route is
missing from the generated API catalog.
## `history`
Proactive publication: native `send_chat_message` and
`POST /api/agents/me/chat/messages` accept only Markdown body and idempotency key.
The server derives company, sender and responsible human from the authenticated
run and atomically resolves the same per-agent/human conversation. This operation
is available independently of generic API tools, only to active standard task
runs with standard credentials. Skill-test and task-bridge credentials, persisted
skill-test runs, Ask/planning/review/watchdog, stale/stopped runs, revoked recipients and
restricted source tasks are denied. The shared comment boundary rejects other
agents and execution-task writes that bypass this path. Comment/audit persistence
retains real agent/run attribution and server-owned source provenance.
Credential scope, responsible human and external authorizer remain part of access
checks. API keys are rechecked under a row lock before the delivery commits.
New deliveries spend the existing shared per-run cross-issue influence budget;
receipt retries and recovery spend no extra slot. Exhaustion returns the standard 429
denial and rolls back the attempted delivery, including first-chat creation.
`GET /api/companies/{companyId}/chats` and its detail endpoint include the current
human's unread state. `POST /api/issues/{id}/read` accepts an optional
`throughCommentId` for the owning human's conversation. Concurrent unseen arrivals
remain unread. Source: [delivery owner](../../server/src/services/agent-chat-messages.ts),
[database tests](../../server/src/__tests__/agent-chat-messages.test.ts), and
[browser journey](../../tests/e2e/agent-chat-messages.spec.ts). Test definitions
are not evidence that a live provider or whole capability has been qualified.
Capability ID: `agent-chat/history`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `GET /api/issues/{id}/recent-comments` (20 contiguous comments for a standing chat).
- `GET /api/issues/{id}/comments` (cursor pages for older history).
- `GET /api/issues/{id}/runs?runIds=...` (at most 100 requested IDs, constrained to the accessible issue and company).
- `POST /api/issues/{id}/comments`.
- `GET /api/issues/{id}/decision-receipts` (own standing-chat board read).
- `GET /api/issues/{id}/chat-handoffs` (own standing-chat board read, paginated).
Agent access: `partial` — Assigned conversation task tools / REST for eligible task
history and replies.
Policy: Conversation discovery/creation requires a board user and the Agent Chat gate;
task access follows task visibility.
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts#L18077) at
the reviewed commit above.
Verification: `not-run` — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Agent responses are supported; creating the person's chat and impersonating their
messages are different actions.
Coordinator model/effort selection reuses `PATCH /api/issues/{id}` for the conversation's `assigneeAdapterOverrides`, followed by the existing idempotent board-user comments endpoint. It introduces no new route or actor authority and never changes the agent configuration. Settings and message admission are separate writes: a settings failure prevents submission; a later message failure may leave the selected conversation settings saved. Existing in-flight execution is not retroactively changed. UI tests cover ordering and first-message identity; provider/session behavior remains a separate live check.
Coordinator evidence: [canonical chat projections](../../server/src/services/conversation-decision-receipts.ts)
return stable references to recorded task/decision rows, not copied agent prose.
The caller must own and currently read the source conversation; source agent and
session generation must still match the handoff, and each target task must remain
readable. The projection does not give the coordinator new execution authority or
wake it merely to repeat a human decision. The normal local-implicit/admin access
exception remains unchanged.
`GET /api/issues/{id}/pending-questions` is a board-owned, read-authorized projection of canonical attention, limited to current chat handoffs plus ordinary tasks created by the caller and currently assigned to that chat’s agent. Direct tasks with any existing chat handoff are excluded from the direct-task branch. The same direct-task scope extends recorded-decision reads from the current chat boundary; pending direct-task questions remain actionable across resets. Question audience, dismissal, archive, snooze and task privacy come from the existing attention service. No copied interactions or new write authority are introduced. The read currently obtains one full authorized company attention snapshot when relevant tasks exist; no polling is added.
## `handoff`
Capability ID: `agent-chat/handoff`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `POST /api/companies/{companyId}/projects`.
- `POST /api/companies/{companyId}/issues`.
- `POST /api/issues/{id}/interactions` with `suggest_tasks`.
- `POST /api/issues/{id}/interactions/{interactionId}/accept`.
Agent access: `available` — Native list_projects/create_project/create_task; project MCP
tools; REST.
Policy: Conversation discovery/creation requires a board user and the Agent Chat gate;
task access follows task visibility.
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts#L18077) at
the reviewed commit above.
Verification: `not-run` — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Agent handoff is implemented; execution readiness, assignment permission, and
repository access still apply.
Coordinator evidence: [interaction service](../../server/src/services/issue-thread-interactions.ts)
accepts authorized chat proposals through the normal issue creation service,
with atomic initial-plan persistence and a durable originating-chat handoff.
New chat handoffs default to the conversation agent when no agent or person is supplied. The effective default is included in assignment authorization before creation; explicit assignments retain company, invokability and access checks. Raw REST derives the default only from a verified same-company, same-agent run-bound conversation. Native/MCP creation and accepted suggestions follow the same owner policy. Suggestions alone have no task-creation effect. Accepted chat roots are standalone
tasks; nested execution tasks retain normal parent/child rules. Source participant,
session generation, task assignment and private-source inheritance are checked;
quality confirmations remain separate from task completion and publication.
[Focused regression coverage](../../server/src/__tests__/coordinator-handoff.test.ts)
does not claim live model/tool selection or external delivery verification.
Additional coverage: the explicit [chat feature evals](../../tests/runner-e2e/CHAT-FEATURES.md)
exercise native task creation and completion delivery through the real chat UI.
The [chat directive](../../server/src/services/agent-conversations.ts) tells agents
to use company-prefixed relative task links or platform-supplied absolute origins.
This adds no permission and does not qualify the whole capability or its denied cases.
## `conference-room`
Capability ID: `agent-chat/conference-room`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `POST /api/board/chat/stream`.
Agent access: `partial` — Existing SSE client in local_trusted mode with the
experimental gate.
Policy: Conversation discovery/creation requires a board user and the Agent Chat gate;
task access follows task visibility.
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts#L18077) at
the reviewed commit above.
Verification: `not-run` — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Not callable through generic REST tooling: protocol and deployment constraints
apply. This route is not guarded by assertBoard, so its intended agent policy needs
clarification.
### Required quality-review handoff
`request_human_input` suggestions and native `create_task` accept the same optional `requiredQualityReview` contract; task creation persists it atomically. Execution uses existing confirmation/item-verdict interactions with explicit quality-review keys and exact document/attachment targets. The server stamps the current requirement fingerprint, forces human-only resolution, validates current targets, and independently prevents completion until every required output has human approval. Agents cannot remove or weaken an existing requirement. Existing task read/write company and actor checks remain authoritative. Publication/delivery authority is unchanged. Completion-only chat wakes receive bounded canonical decision references and guidance to reuse reviews, not start duplicate ones.
An attachment target is an exact immutable identity, not a mutable latest-output label. Registering another attachment does not automatically replace that required slot; the agent must request a fresh bound review for the replacement. Deduplicated task creation rejects a mismatched requested review contract, and an already-completed task must reopen before taking an unsatisfied requirement.
Reference in new issue View Git Blame Copy Permalink