mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-15 20:53:23 +02:00
DottaandPaperclip
433d94ee0b
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Feature recipes and Storybook help contributors find behavior, examples, and verification steps. > - Independent feature changes currently update shared catalogs, indexes, and review hashes. > - Those shared files cause merge conflicts and repeated bookkeeping during parallel work. > - This pull request stores metadata in each feature recipe and story, then generates the combined views. > - Contributors can merge independent work without editing a common index. Git and PR evidence retain change and review history. ## Linked Issues or Issue Description **What existing behavior does this improve?** Maintaining the product, agent-access, and Storybook maps while multiple agents change different features. **Current behavior** A story or recipe change can update `catalog.json`, `INDEX.md`, review hashes, verification tables, and tracked generated navigation. Two unrelated changes then conflict in the same files. **Proposed behavior** Each story declares capability links and classification in `parameters.paperclip`. Each feature recipe declares its navigation and optional verification guidance. Startup, build, and UI typechecking discover these sources and generate ignored indexes and Storybook pages. **Reason and benefit** A routine change edits its own source files. Aggregate metadata is rebuilt from the merged checkout. There is no sidecar registry, shared review journal, or hash acknowledgment to maintain. **Breaking changes** The tracked Storybook catalog and index paths are retired. Consumers use `ui/storybook/generated/` or `maps/generated/` after generation. Contributor instructions and the existing feature-gap browser suite use the new paths. Story and overview IDs remain stable. ## What Changed - Move the existing annotations into 262 story files. Preserve classifications, capability associations, exports, and explicit IDs. - Discover all 35 feature recipes. Store section/order beside each recipe and move durable verification routes out of the shared table. - Remove tracked catalogs, inventories, overview pages, and inline preview ordering. Keep authored preview behavior in `preview-base.tsx`. - Generate the Storybook guide, feature/access Markdown indexes, gap report, page-reference inventory, and preview wrapper automatically. - Update the map contracts and maintenance skills to use Git history and revision-specific PR/CI evidence. - Add schema, identity, regeneration, and actual Git merge tests. Run these through the existing UI Vitest suite. Add focused browser navigation checks. This is one coordinated migration. Most of the 367 changed files contain only moved metadata or deleted generated content. Review the generator scripts, map contracts, Storybook configuration, and tests first. No product API or authorization behavior changes. ## Verification Passed: - `node scripts/check-maps.mjs`: 35 paired areas and 175 capabilities. - `node scripts/storybook-catalog.mjs --check`: 262 suites and 2,485 authored stories after incorporating current master. - `node --test scripts/check-maps.test.mjs scripts/storybook-catalog.test.mjs scripts/storybook-feature-index.test.mjs`: 28 tests, including independent branches merged in both orders with identical generated output and no tracked changes. - `pnpm --filter @paperclipai/ui exec vitest run storybook/map-tooling.test.ts`: the CI entrypoint runs those map tests. - `pnpm check:token-gates`. - `pnpm -r typecheck` and `pnpm build` before the final master rebase. - `pnpm build-storybook`: all 2,517 original story/docs URLs retained. Current master contributes exactly four additional recovery stories. - Focused Playwright navigation checks: search and open a feature without examples; expand verification guidance and check source links; retain capability order and follow a related Foundations suite. The final clean Storybook build passed after deleting every ignored map output. Post-rebase UI typechecking and both browser tests passed. The working tree stays clean after generation. The concurrent-cleanup regression fails with `ENOENT` without the fix and passes with it. All GitHub CI gates passed on `00fc7ec18e`, which also received Greptile 5/5 with no unresolved findings. The final merge commit `1c3c5143a6` incorporates master and resolves only the two modify/delete conflicts by retaining removal of the aggregate index and catalog. Master’s new workspace feature and access guidance is preserved. Map validation, catalog generation, overview generation, all 28 map tests, and diff checks pass after conflict resolution. The maintainer explicitly requested merging without another Greptile review. CI has not been rerun to completion on this merge commit. The local repository-wide `pnpm test:run` was stopped before completion after the earlier CI matrix passed; it is not reported as a local pass. No screenshot baselines or production acceptance are claimed. To repeat the browser check against an owned Storybook server: ```sh PAPERCLIP_GAP_STORYBOOK_URL=http://127.0.0.1:6136 pnpm exec playwright test --config tests/storybook-visual/feature-gap-stories.config.ts map-navigation.spec.ts ``` ## Risks - Existing branches need a one-time rebase to move their catalog changes into local annotations. The PR incorporates the recovery changes from current master. - Changing the same story or capability can still produce a meaningful conflict. This removes the shared aggregate bottleneck. - The generator uses Storybook's existing CSF parser. Literal-only annotations and parser regression tests protect the current contract. - Generated Markdown is available after running the generator; the published Storybook provides a browsable guide. - Shared source changes still require review. Removing hashes removes mechanical acknowledgments; it does not establish runtime parity. ## Model Used OpenAI Codex, based on GPT-6, with repository inspection, code execution, and browser-test tools. The exact deployment model ID and context window were not exposed in this session. ## 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 on the previously reviewed head `00fc7ec18e`; final conflict-resolution checks are documented above - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups on `00fc7ec18e`; another review was waived by the maintainer - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
158 lines
8.7 KiB
Markdown
158 lines
8.7 KiB
Markdown
---
|
|
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":60}
|
|
---
|
|
|
|
# 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.
|
|
|
|
### Storybook verification
|
|
|
|
#### `drafts`
|
|
|
|
Scope: ui
|
|
Storybook: Task-keyed restored draft and attachment receipts; task switch/reload, failed send and uncertain-save recovery.
|
|
Production: Retain correct task draft across navigation and reload; inspect authoritative saved receipt before claiming delivery; do not clear storage on every harness mount.
|
|
Sources: Source: [TaskChatComposer.tsx](../../ui/src/components/task-chat/TaskChatComposer.tsx), [composer-draft.ts](../../ui/src/lib/composer-draft.ts). Tests: [TaskChatComposer.test.tsx](../../ui/src/components/task-chat/TaskChatComposer.test.tsx), [issue-queued-comments-routes.test.ts](../../server/src/__tests__/issue-queued-comments-routes.test.ts)
|
|
|
|
#### `approval-queue`
|
|
|
|
Scope: ui
|
|
Storybook: Answered question/accepted approval delivery waiting, eligible steer/interrupt, failed delivery and fresh-session-only approval.
|
|
Production: Keep response delivery durable and distinct from editable comments; coalesce once, enforce fresh-session restrictions and deduplicate concurrent/retried continuation.
|
|
Sources: Source: [TaskChatQueuedMessages.tsx](../../ui/src/components/task-chat/TaskChatQueuedMessages.tsx), [question-response-delivery.ts](../../server/src/services/question-response-delivery.ts). Tests: [TaskChatQueuedMessages.test.tsx](../../ui/src/components/task-chat/TaskChatQueuedMessages.test.tsx), [question-response-delivery.test.ts](../../server/src/__tests__/question-response-delivery.test.ts), [issue-queued-comments-routes.test.ts](../../server/src/__tests__/issue-queued-comments-routes.test.ts)
|