mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-16 15:15:35 +02:00
DottaandPaperclip
7d9b93aee2
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Contributors use the feature map to understand and verify product capabilities. > - Agents need APIs and usable entry points within their permission boundaries. > - Product recipes and agent access need separate records with shared capability IDs. > - This pull request establishes that contract and gives maintenance ownership of both maps. > - The benefit is repeatable access review without changing product behavior or permissions. ## Linked Issues or Issue Description Refs: #15983, which added the portable verification skills and updated the feature map. This is its contract-only follow-up. Related: #15288 added the original feature map. **Issue type** Missing documentation and maintenance contract. **Where is the issue?** The product map, its missing agent access companions, and the verification skills. **What's wrong?** There is no shared convention for API presence, agent entry points, permission boundaries, access gaps, or evidence. An API declaration does not prove that a permitted native or remote agent can use it. **Suggested fix** Keep the product and agent access maps as siblings under `maps/`. Reuse capability IDs. Record representative source inventory separately from operation review and live proof. Keep both maps aligned through the maintenance skill. ## What Changed - Move the existing product map to `maps/feature-map/`. Preserve its recipes and Poteto format. Update relative links and add companion links. - Add `maps/agent-access-map/` with 35 area files and 171 matching capability IDs. Seed representative API operations, agent paths, policies and known gaps from the reviewed source inventory. Mark entries as `baseline`, `source-only`, and live verification `not-run`. - Define the shared contract in `maps/README.md`. Track API presence, agent availability, policy, evidence and review depth separately. Require operation enumeration before marking a broad capability operation-reviewed. - Extend `maintain-verification-skill` to reconcile both maps and inspect actual route policy and production tool admission. Update creation, verification, notices and contributor references to use the shared contract. - Add `scripts/check-maps.mjs` and ten regression tests. Check matching areas/IDs, indexes, references, contract fields, API method/path examples, justified exceptions and evidence-state consistency. - Keep the coverage inventory unchanged. Preserve skill invocation policies and both MIT license blocks. No product API, permission, UI, runtime helper, migration, dependency or workflow changes. ## Verification - Passed: `node scripts/check-maps.mjs` reports 35 paired areas and 171 matching capability IDs. All local map references resolve. - Passed: `node --test scripts/check-maps.test.mjs` runs ten tests. Fixtures cover missing companions, renamed/orphan/duplicate IDs, broken references, missing operation fields, empty exceptions, missing API examples, empty policy fields, and verified evidence without passed verification. - Passed: metadata validation for all three verification skills. Skill and contributor links resolve. Invocation policies and both license blocks are unchanged. - Compared relocated recipes with current master. Contents differ only in relative links and companion links. `coverage.json` is byte-for-byte unchanged. Master's updated read-only interaction test reference is retained. - Passed: `git diff --check`. The branch starts from current master and contains only this contract change. - Repository-wide typecheck, tests and build were not run locally for this documentation and Node structural-check scope. Live agent access was not exercised. Those gaps are explicit in the baseline entries; the structural check does not certify behavior. CI and automated review are pending. ## Risks - The companions are representative source baselines. They are not complete operation inventories or passed agent journeys. - The checker cannot establish actual permissions, native tool admission, operation completeness or truthful live evidence. Maintenance must inspect source and verify with the actual permitted agent context. - External links to the old product-map directory may need updates. Repository references have been updated. - Existing access gaps and board/user restrictions remain recorded. This contract does not change authority or implement missing paths. ## Model Used OpenAI GPT-6 through Codex assisted with this change. The session does not expose the exact serving model ID, configured context-window size, or reasoning setting. Capabilities used: source analysis, file edits, shell commands, and structural regression tests. ## 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 - [ ] All Paperclip CI gates are green - [ ] 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>
138 lines
7.0 KiB
Markdown
138 lines
7.0 KiB
Markdown
# Steering and queued messages
|
|
|
|
People can send follow-ups while an agent works, manage saved messages that have
|
|
not been consumed, and choose when to steer or interrupt. Stopping a run and
|
|
pausing a task are separate controls. The UI must preserve the message, explain
|
|
why it is waiting, and only claim delivery after an authoritative acknowledgement.
|
|
|
|
Agent access: [companion](../agent-access-map/steering.md).
|
|
|
|
## Sub-features
|
|
|
|
- `queue`: a busy task saves follow-ups and shows their order and wait reason.
|
|
- `edit-order-discard`: edit full Markdown, reorder, and discard eligible saved
|
|
messages; ownership, revision conflicts, and already-dispatched states matter.
|
|
- `steer`: explicit user action sends a queued message into a compatible active
|
|
run; unavailable capabilities and provider rejection remain visible.
|
|
- `interrupt`: stop the current execution and carry accepted follow-ups into
|
|
the eligible continuation without delivering them twice.
|
|
- `stop-and-pause`: distinguish stop-in-flight, confirmed stop, task/ancestor
|
|
pause, agent pause, and budget hold. Resume must respect the actual gate.
|
|
- `drafts`: switching tasks, reloading, and uncertain submission retain the
|
|
correct task's draft and attachment receipts.
|
|
- `approval-queue`: answered questions and accepted approvals have durable
|
|
delivery distinct from editable ordinary comments.
|
|
|
|
## How to get to it (user POV)
|
|
|
|
### `task-composer`
|
|
|
|
Open an assigned task (`/issues/:issueId`). Start work, then send follow-ups while
|
|
the agent runs. Use the queued-message controls to edit, reorder, discard,
|
|
steer, or interrupt when offered. Use the composer stop/pause control separately.
|
|
Both task presentations need attention when changing their shared behavior.
|
|
|
|
### `agent-chat`
|
|
|
|
Enable Agent Chat and open an agent conversation. Send another message during
|
|
a reply and inspect the shared queue. `/new` starts fresh provider context in
|
|
the same conversation; it is an ordered boundary, not a normal model prompt.
|
|
|
|
### `request-response`
|
|
|
|
Answer an earlier question or accept a confirmation while successor work is
|
|
active on the task. Inspect the resulting queued response and its available
|
|
steer/interrupt control instead of assuming acceptance interrupted execution.
|
|
|
|
### `external-channel`
|
|
|
|
Send a follow-up from a linked external chat conversation while its task is
|
|
running. Use that provider's supported stop/control affordance where available;
|
|
inspect the resulting task and run in Paperclip.
|
|
|
|
## Driving it
|
|
|
|
Preconditions: follow the [baseline](./README.md#before-driving-a-journey).
|
|
Use an agent that stays busy long enough to inspect the queue. Record the adapter,
|
|
native/legacy mode, and advertised steering capability. Test supported and
|
|
unsupported steering without treating an absent capability as a product failure.
|
|
|
|
### `task-composer`
|
|
|
|
Automated: [queued-message UI](../../ui/src/components/task-chat/TaskChatQueuedMessages.test.tsx)
|
|
covers order, failure restoration, unavailable steering, stale revisions, and
|
|
discard acknowledgements. [Queue routes](../../server/src/__tests__/issue-queued-comments-routes.test.ts)
|
|
cover durable ordering, authorization, steering acknowledgements, interrupt
|
|
recovery, and concurrent dispatch. [Composer](../../ui/src/components/task-chat/TaskChatComposer.test.tsx)
|
|
covers drafts and uncertain saves.
|
|
|
|
```sh
|
|
pnpm exec vitest run ui/src/components/task-chat/TaskChatQueuedMessages.test.tsx server/src/__tests__/issue-queued-comments-routes.test.ts
|
|
```
|
|
|
|
Automated stop coverage is separate:
|
|
[composer stop](../../tests/e2e/composer-stop.spec.ts) with
|
|
[its configuration](../../tests/e2e/playwright-composer-stop.config.ts) and
|
|
[ACP stop/continuation](../../tests/e2e/acp-stop-continuation.spec.ts). Inspect their
|
|
fixture and opt-in prerequisites; skipped native cases are not native proof.
|
|
|
|
Manual: queue three distinguishable messages. Edit one, reorder them, reload,
|
|
and confirm the saved order. Discard one and confirm it never reaches execution.
|
|
Steer one while busy and verify the agent receives that exact message once.
|
|
Repeat with a rejected steer and a stale second-tab edit; the UI must preserve
|
|
retryable content and explain the conflict. On a fresh run, interrupt with a
|
|
queued follow-up and verify confirmed stop followed by one continuation. Pause
|
|
the task (and separately its ancestor), preserve a draft, then resume the actual
|
|
hold; no hidden send should occur while paused. Check both task presentations
|
|
when available; the named component tests do not prove every host integration.
|
|
|
|
### `agent-chat`
|
|
|
|
Automated: [agent chat sessions](../../tests/e2e/agent-chat-sessions.spec.ts) covers
|
|
persistent conversation/session behavior with deterministic harness fixtures;
|
|
shared composer tests cover the controls. These do not qualify live steering
|
|
for every harness.
|
|
|
|
Manual: queue two follow-ups while the conversation replies. Reload, edit or
|
|
discard one, then let the other run. Verify one reply and unchanged conversation
|
|
identity. Send `/new`, then a new prompt; old history remains visible, and the
|
|
new turn uses fresh provider context. Verify a useful answer rather than only
|
|
the session-divider UI. Repeat the queue operations with a live capable harness
|
|
when the change touches delivery.
|
|
|
|
### `request-response`
|
|
|
|
Automated: [response delivery](../../server/src/__tests__/question-response-delivery.test.ts)
|
|
proves queueing/coalescing and retry-safe receipts. The queue-route suite tests
|
|
separate comment and approval queues, explicit steering, and fresh-session
|
|
restrictions on plan approvals.
|
|
|
|
Manual: answer an old question during a new run, confirm that it is saved and
|
|
queued, and let the active run end. Verify exactly one continuation with the
|
|
answer. Repeat an eligible approval with explicit steer; another approval that
|
|
requires a fresh session must not offer same-turn delivery. Do not edit an
|
|
approval outcome through an ordinary queued-message editor.
|
|
|
|
### `external-channel`
|
|
|
|
Automated: [chat interaction arbitration](../../server/src/services/chat-interaction-arbitration.test.ts)
|
|
covers backend arbitration with simulated requests. It is not a provider UI test.
|
|
|
|
Manual: send two distinguishable messages through one disposable linked
|
|
conversation while busy. Inspect their saved task order, run delivery, and
|
|
external reply. Check a duplicate provider event and unauthorized sender.
|
|
Provider-specific control semantics and real transport timing remain a manual
|
|
gap; do not assume browser queue controls are available in every channel.
|
|
|
|
## Gotchas
|
|
|
|
- Paperclip's queue is server-owned once saved; it is not Omnigent's unsent
|
|
browser draft buffer. A stale edit must not overwrite a consumed message.
|
|
- Steer availability depends on the active runtime's capability, not its brand
|
|
name. A UI row disappearing optimistically does not prove provider receipt.
|
|
- Interrupt, stop, task pause, agent pause, and budget pause have different
|
|
effects. A running indicator disappearing does not prove remote work stopped.
|
|
- An interrupted run may need verified cleanup before a saved follow-up can
|
|
start. Preserve and inspect the wait reason; see [recovery](./recovery.md).
|
|
- A healthy idle Agent Chat is waiting for input, not stranded unfinished work.
|