mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-22 00:30:19 +02:00
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>
91 lines
5.3 KiB
Markdown
91 lines
5.3 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
|
|
`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](../../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)
|