DottaandPaperclip
e6dcd1e8e9
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents can submit suggestions and complaints while they work. > - Operators currently need database access to read those messages. > - That makes it hard to find feedback from one agent or share a specific message. > - This pull request adds a standard Commentary tab in Audit. > - Operators can filter messages, browse 50 at a time, and share links to full message dialogs. ## Linked Issues or Issue Description Refs #15367, which added feedback storage and agent submission. The duplicate search found no open PR for a commentary reader. **Subsystem affected** Server, shared API contracts, and the board UI. **Problem or motivation** Agent suggestions and complaints are stored but have no board reader. Operators must query the database to inspect feedback. **Proposed solution** Add Commentary to Audit without an experimental toggle. Show previews, agent and message-type filters, text search, and 50-message pages. Opening a row updates the URL. A copied URL opens the full message with its agent, task, and run context. **Alternatives considered** Direct database queries remain useful for operators, but do not provide a normal product workflow. An experimental setting would add setup to a read-only audit page. **Roadmap alignment** This completes the operator view for the existing feedback feature. It supports human oversight and does not change agent execution or task ownership. ## What Changed - Add company-scoped, board-only list and detail endpoints with audit permission and source-task privacy checks. - Return bounded previews and counts. Fetch full bodies only when a message opens. - Add the Commentary tab, search, filters, 50-row pagination, and URL-based selection. Audit tab destinations work in both layouts, with a classic sidebar entry for Commentary. - Add production Storybook examples for populated, filtered, linked, long, paginated, empty, loading, failed, denied, mobile, and light states. - Update API documentation and the feature and agent access maps. ## Verification - Final head `abc4a251c14cfbfec007542214beec528f2b18bf`: 55 checks pass; two conditional Storybook checks are skipped. The PR workflow is successful. Greptile is 5/5 with all findings resolved. - Focused database, HTTP, submission, OpenAPI, and UI regression tests cover company isolation, task privacy, filter bounds, 50-row pagination, and copied message links. - Browser Storybook journeys cover row opening, direct links, combined filters, search, and pagination. Storybook uses synthetic API fixtures; database authorization is tested separately. - Token gates, feature maps, and Storybook catalog validation pass. - `pnpm -r typecheck`, `pnpm build`, and `pnpm build-storybook` pass on the rebased branch. All 80 focused tests and all 37 Audit tests pass, including the real App route table in both layouts, task grant/revocation through HTTP, deleted-task privacy, and URL UI regressions. The full suite passes in the parallel PR CI matrix. The local serial full-suite run was stopped before completion after checking the recorded 94-minute serial duration. Local focused tests, workspace typecheck, production build, and final server/UI checks pass. - The linked-message Storybook test initially asserted against the loading dialog. It now waits for the message body; both direct-link and row-open journeys pass. - Native and legacy deleted-task privacy regressions failed before the fix and pass afterward. The reader checks the run task binding after the task foreign key clears. - A rapid search-then-agent-filter browser regression reproduced the search overwriting the selected agent. The pending search now restarts when URL filters change. The same browser test passes with both filters applied. - CI found two existing AuditHub assertions that still expected five tabs. They now assert the six-tab model and selected-company Commentary rendering. All 37 Audit tests pass. All other test and build jobs passed before this test-only correction. - The [agent-chat attachment browser test](https://github.com/paperclipai/paperclip/actions/runs/39307881171/job/118250189664) timed out waiting for an attachment preview. The [same shard passed on the prior head](https://github.com/paperclipai/paperclip/actions/runs/39306658703/job/118245498343) with identical application code; the intervening change only updates AuditHub unit tests. The single retry passed on the same head. The precise cause of the earlier failure remains unconfirmed. ## Risks - Commentary may contain sensitive task context. The reader requires board access and audit permission, and filters source-task visibility before returning previews, counts, or full bodies. - Text search scans stored message bodies. Pages are bounded and full bodies are fetched on demand. - Offset pagination can shift if new messages arrive while paging. Ordering uses timestamp and ID for stable ties. - No database migration or agent submission behavior changes are required. ## Model Used - OpenAI Codex, GPT-6 family, with reasoning, tool use, browser interaction, and code execution. The exact backend model ID and context-window size are 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 - [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>
5.2 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Dashboards and audit trails
People inspect company health, recent activity, run history, and routine activity, then follow evidence back to the task or agent responsible.
Implementation: dashboard, live dashboard, audit hub.
Agent access: companion.
Sub-features
overview: inspect the company dashboard and live-work summary.activity: filter and page through recorded actor/resource events.runs: find executions and follow their task/agent context.routine-audit: inspect routine execution activity separately from its definition.timeline: use the available timeline view to understand work over time.agent-commentary: browse attributed agent suggestions and complaints.
How to get to it (user POV)
dashboard
Open /dashboard or /dashboard/live.
activity-audit
Open /activity, /activity/runs, or /activity/timeline in the streamlined shell; legacy routes may redirect.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Prepare known task mutations and completed/failed runs in a disposable company, recording their IDs and actors.
dashboard
Automated: dashboard service covers server aggregation; dashboard helpers is narrower UI helper coverage.
Manual: Compare the dashboard with the known fixture tasks and runs. Start and finish a small task, refresh/reload, and verify the summary changes and links reach the right records. Exercise empty data and a failed fetch.
activity-audit
Automated: activity service, audit runs, and routine audit cover these separate data/host layers.
Manual: Find a known mutation by actor/resource and a known run by status. Change filters, load more, and follow the source links. Reload the chosen view and verify no company leakage or duplicate events. Inspect a routine run from its audit entry.
Issue activity is also available through GET /api/issues/{id}/activity.
Agent authorization and
sandbox bridge
regressions cover this route separately from company-wide audit. Live sandbox
agent access remains unverified; use the companion recipe.
Audit-event Load more and run listings differ: Runs currently loads at most 200 entries without pagination. The tested RoutineAuditActivity component has no registered activity-route host; inspect execution links actually offered by the routine rather than treating that component test as a reachable journey.
agent-commentary
Open Audit → Commentary (/activity/commentary). Search message text, filter by agent and suggestion/complaint,
page through 50-message previews, and open a row to read the full message with its task/run links.
Filters, page offsets and the selected entry are retained in the URL. Read access requires board company access and
audit:view_agent_actions; task privacy applies to previews, counts and full messages.
All Audit tab destinations resolve in both the classic and streamlined layouts.
Storybook: production page and message journeys covers populated, filtered, long-message, paginated, empty, loading, failed, denied, linked-message, mobile and light states using synthetic API fixtures. These examples do not prove live database filtering or authorization.
Gotchas
- Audit/activity events, run-log rows, first-party Telemetry, and operator OpenTelemetry traces are separate data paths.
- A healthy stream or dashboard counter alone does not prove task success.
- Cost and budget reports have their own recipe.
Storybook verification
runs
Scope: ui Storybook: Mount AuditRuns selected status/agent/routine, linked task/agent, empty/loading/error/retry and 200-entry limit. Do not invent pagination. Production: GET /companies/{id}/heartbeat-runs and /routines/{id}/runs require company/read/privacy checks; real browser follows context links and confirms the referenced execution. Company run history defaults to 200 rows and caps explicit limits at 1,000. Summary contexts omit stored prompts and expand JSON once per returned row. The array response and run visibility/redaction checks remain in place. Agent detail links resolve older runs by ID outside the recent history page. Sources: Source: AuditRuns.tsx, heartbeats.ts, routines.ts. Tests: AuditRuns.test.tsx, heartbeat-run-privacy-routes.test.ts, routines-service.test.ts