mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 12:04:41 +01:00
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>
90 lines
5.2 KiB
Markdown
90 lines
5.2 KiB
Markdown
---
|
|
navigation: {"section":"Oversight and operation","sectionOrder":70,"order":20}
|
|
---
|
|
|
|
# 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](../../ui/src/pages/Dashboard.tsx), [live dashboard](../../ui/src/pages/DashboardLive.tsx), [audit hub](../../ui/src/pages/audit/AuditHub.tsx).
|
|
|
|
Agent access: [companion](../agent-access-map/activity.md).
|
|
|
|
## 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](./README.md#before-driving-a-journey). Prepare known task mutations and completed/failed runs in a disposable company, recording their IDs and actors.
|
|
|
|
### `dashboard`
|
|
|
|
Automated: [dashboard service](../../server/src/__tests__/dashboard-service.test.ts) covers server aggregation; [dashboard helpers](../../ui/src/pages/Dashboard.test.ts) 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](../../server/src/__tests__/activity-service.test.ts), [audit runs](../../ui/src/pages/audit/AuditRuns.test.tsx), and [routine audit](../../ui/src/pages/audit/RoutineAuditActivity.test.tsx) 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](../../server/src/__tests__/activity-routes.test.ts) and
|
|
[sandbox bridge](../../packages/adapter-utils/src/sandbox-callback-bridge.test.ts)
|
|
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](../../ui/storybook/stories/activity/agent-commentary.stories.tsx)
|
|
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](./budgets-costs.md).
|
|
|
|
### 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](../../ui/src/pages/audit/AuditRuns.tsx), [heartbeats.ts](../../ui/src/api/heartbeats.ts), [routines.ts](../../ui/src/api/routines.ts). Tests: [AuditRuns.test.tsx](../../ui/src/pages/audit/AuditRuns.test.tsx), [heartbeat-run-privacy-routes.test.ts](../../server/src/__tests__/heartbeat-run-privacy-routes.test.ts), [routines-service.test.ts](../../server/src/__tests__/routines-service.test.ts)
|