DottaandPaperclip
e5927e1db9
## Thinking Path > - Paperclip lets people manage AI agents and inspect their work. > - Commentary collects agent suggestions and complaints for company members. > - Commentary used the permission for detailed agent-action audits. > - Owners, admins and viewers could therefore receive a permission error when they opened Commentary. > - This pull request gives commentary its own permission and enables it for all human company roles. > - Members can read feedback while task privacy and detailed audit access keep their own checks. ## Linked Issues or Issue Description Refs #16884, which added the Commentary browser. A search found no open PR for this permission fix. **What happened?** Commentary returned `Missing permission: audit:view_agent_actions` for company members without the detailed audit grant. Default owners, admins and viewers did not receive that grant. **Expected behavior** All human company roles can read commentary by default. A separate `commentary:view` permission controls this access. Private source tasks remain private. Commentary access does not grant detailed agent-action audits or CSV exports. **Steps to reproduce** 1. Sign in as an active company owner, admin or viewer without `audit:view_agent_actions`. 2. Open Audit, then Commentary. 3. Observe the permission error before this change. **Paperclip version or commit** Base commit: `7c58ea07b2`. **Deployment mode** Authenticated server or Cloud tenant. ## What Changed - Add `commentary:view` to the shared permission contract and all human role defaults. - Require that permission for commentary list and detail reads. - Add an idempotent upgrade migration for existing active human members. Preserve existing grants and scopes. - Add the commentary default when approving saved human invitation grants that omit it, including pre-upgrade invitations. Preserve explicit commentary scopes. - Add regression coverage for role defaults, permission removal, audit separation, private tasks and migration replay. - Update the API description, specifications, database notes and access maps. ## Verification - Passed 68 tests across commentary reads, role grants, old-invitation HTTP acceptance, migration replay, agent audit routes, access services and migration snapshot drift under the repository's locked dependencies. - Confirmed the new role and read tests failed before the implementation. - `node scripts/check-maps.mjs` passed. - Migration numbering and safety checks passed during the build. - Full `pnpm -r typecheck` and `pnpm build` passed locally after the invitation fix. - The final-commit CI matrix passed, including all test shards, typecheck, build, public-install checks and canary smoke. The redundant local `pnpm test:run` was stopped after the full CI matrix completed; the 68 focused local regressions passed separately. - The first install bypassed the stale lockfile and selected a newer diff-viewer API. The initial typecheck and build failed in that unrelated plugin. Installing the locked versions cleared both failures; the tracked lockfile is unchanged. - The first locked-dependency regression run hit the 15-second limit while importing the audit route graph in its first test. Moving that import into suite setup fixed the timeout; all 58 regressions then passed. - Greptile found that pre-upgrade invitations retain old grant lists. New helper and HTTP regressions reproduced this gap before the fix, then passed after approval added the missing commentary default. - Greptile reviewed the final commit at 5/5 with no remaining actionable findings. Its earlier thread is resolved. - No UI code changed. The permission tests use real disposable PostgreSQL databases and HTTP routes. ## Risks - The upgrade deliberately enables commentary for every existing active human company member, including viewers. Existing commentary grants retain their saved scopes. - Source-task privacy still filters previews, counts, searches and full messages. Agent-authenticated browsing remains denied. - Agent-action audit grants, detailed filters and CSV export permissions keep their current behavior. ## Model Used OpenAI Codex, based on GPT-6, with reasoning, repository editing and command execution. The exact runtime model ID and context window are not exposed to 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.3 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
commentary:view, granted by default to all human company roles and backfilled for existing active
human members. Task privacy applies to previews, counts and full messages; agent-action audit access is separate.
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