🩻 feat(insights): Scope Insights to Authorized Agents - #15549
Conversation
Call-flow diffAgent authorization: Repeated agent filter serialization: |
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7074c5fb90
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
🔵 Needs a closer look
It introduces new authorization paths, audit/rollback logic, and data-attribution changes across multiple layers that warrant careful human security review despite strong test coverage.
Pull request overview
Adds agent-scoped authorization and filtering for Insights across backend, data layer, and client UI, including immutable conversation agent attribution and per-agent ACL-based access while maintaining tenant isolation and DocumentDB constraints.
Changes:
- Introduces per-agent Insights access via
PermissionBits.VIEW_INSIGHTS(must pair withVIEWon the same ACL entry), with audit logging + fail-closed compensation. - Adds immutable conversation attribution (
initial_agent_id) for Insights and updates Insights aggregations + indexes to filter by selected/authorized agents. - Moves Insights endpoints to
/api/insights, adds an access resolver and lightweight access probe, and updates the client with an agent multi-select + new i18n strings.
File summaries
| File | Description |
|---|---|
| packages/data-schemas/src/types/convo.ts | Adds initial_agent_id typing for immutable agent attribution. |
| packages/data-schemas/src/types/admin.ts | Extends audit action enums for Insights permission transitions. |
| packages/data-schemas/src/schema/message.ts | Adds message index to support agent-attributed Insights queries. |
| packages/data-schemas/src/schema/insights.spec.ts | Asserts new Insights-related indexes exist. |
| packages/data-schemas/src/schema/convo.ts | Adds initial_agent_id field + indexes for Insights attribution/fallback. |
| packages/data-schemas/src/methods/insights.ts | Implements agent-scoped Insights pipelines and agent labeling. |
| packages/data-schemas/src/methods/insights.spec.ts | Adds coverage for agent scoping + attribution rules + pipeline constraints. |
| packages/data-schemas/src/methods/conversation.ts | Sets initial_agent_id only on insert from server metadata; strips client writes. |
| packages/data-schemas/src/methods/conversation.spec.ts | Tests immutability + explicit null attribution behavior (single + bulk). |
| packages/data-schemas/src/methods/agent.ts | Allows optional select projection in getAgents for access resolution. |
| packages/data-schemas/src/methods/aclEntry.ts | Adds optional session support when reading ACL entries. |
| packages/data-schemas/src/methods/aclEntry.spec.ts | Updates permission superset tests for 5-bit permission space. |
| packages/data-schemas/src/methods/aclEntry.parity.spec.ts | Extends parity/perf tests for the new permission bit. |
| packages/data-provider/src/types/insights.ts | Adds agent filter params/types and response agent metadata. |
| packages/data-provider/src/data-service.ts | Encodes array params (e.g., repeated agentIds) in Insights requests. |
| packages/data-provider/src/api-endpoints.ts | Moves Insights endpoint to /api/insights. |
| packages/data-provider/src/accessPermissions.ts | Adds VIEW_INSIGHTS permission bit and viewInsights principal field. |
| packages/client/src/components/MultiSelect.tsx | Adds disabled state + optional popover header slot for richer controls. |
| packages/api/src/insights/index.ts | Re-exports new access resolver module. |
| packages/api/src/insights/handlers.ts | Enforces agent authorization + validates requested agentIds; returns agent list. |
| packages/api/src/insights/handlers.spec.ts | Tests access gating + agent subset validation/dedup/sort behavior. |
| packages/api/src/insights/access.ts | Implements per-user accessible-agent resolution (admin/global/per-agent ACL). |
| packages/api/src/insights/access.spec.ts | Tests resolver behavior for admin, global, per-agent, and no-access cases. |
| packages/api/src/admin/index.ts | Exposes buildAuditContext for audit logging. |
| docs/agent-insights-access-design.md | Documents the design and constraints for agent-scoped Insights access. |
| client/src/locales/en/translation.json | Adds UI strings for Insights agent filter + permission text. |
| client/src/hooks/Nav/useUnifiedSidebarLinks.ts | Shows Insights link based on access probe; reserves slot while loading. |
| client/src/components/UnifiedSidebar/mobile/ShortcutTargets.tsx | Disables nav targets when link is in loading/disabled state. |
| client/src/components/UnifiedSidebar/ExpandedPanel.tsx | Disables nav icon button when link is disabled. |
| client/src/components/Sharing/shareChanges.ts | Adds tri-state diffing for viewInsights vs role-only updates. |
| client/src/components/Sharing/PeoplePicker/SelectedPrincipalsList.tsx | Adds admin-only “View insights” control per principal. |
| client/src/components/Sharing/GenericGrantAccessDialog.tsx | Wires Insights checkbox into share dialog state + save payloads. |
| client/src/components/Sharing/tests/shareChanges.spec.ts | Tests new Insights diffing behavior. |
| client/src/components/Sharing/tests/GenericGrantAccessDialog.spec.tsx | Mocks admin role so Insights controls render in tests. |
| client/src/components/Insights/InsightsView.tsx | Adds sticky agent multi-select + URL-driven filtering + 403 messaging. |
| client/src/common/types.ts | Extends NavLink type with disabled. |
| api/server/services/PermissionService.spec.js | Tests Insights bit add/preserve/remove + rollback helper behavior. |
| api/server/services/PermissionService.js | Implements Insights bit handling and rollback operations on audit failure. |
| api/server/routes/insights.js | Moves protected Insights API to /api/insights with resolver-based access. |
| api/server/routes/accessPermissions.js | Allows tenant-admins to manage agent permissions after tenant validation. |
| api/server/routes/tests/insights.spec.js | Updates route tests for new Insights mount + shared resolver usage. |
| api/server/index.js | Updates server mount path for Insights routes. |
| api/server/experimental.js | Updates experimental server mount path for Insights routes. |
| api/server/controllers/PermissionsController.js | Validates Insights mutations, audits transitions, masks bit for non-admins. |
| api/server/controllers/agents/responses.js | Stores agent_id and passes initialAgentId metadata on insert. |
| api/server/controllers/agents/request.js | Persists verified initialAgentId (non-ephemeral) for new conversations. |
| api/server/controllers/agents/tests/request.resumeMetadata.spec.js | Updates test expectations for initialAgentId metadata. |
| api/app/clients/BaseClient.js | Supplies initialAgentId when saving conversations for agent runs. |
Review details
- Files reviewed: 49/49 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
danny-avila
changed the title
|
@codex review |
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5bfea4e743
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4a1ec7e43f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…insights # Conflicts: # client/src/components/Insights/InsightsView.tsx # client/src/components/Sharing/GenericGrantAccessDialog.tsx
|
@codex review |
|
Codex Review: Didn't find any major issues. What shall we delve into next? Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d4e01e5e79
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e36b4104e4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
|
Codex Review: Didn't find any major issues. Delightful! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
`docs/agent-insights-access-design.md` was the pre-implementation spec for #15549, and it says so: "design reference for work based on upstream/dev after PR #14898". Everything it specifies shipped — PermissionBits.VIEW_INSIGHTS = 16, /api/insights, the server-owned initial_agent_id — so the code and its tests are the source of truth now and the note can only drift from them. Nothing in the repository links to it. docs/skills-management-api.md stays: it describes a machine API surface that has no equivalent on librechat.ai, and its details still match packages/api/src/skills/management.ts.
* 📐 docs: Ask Pull Requests to Show the Mechanism The template asked for a brief summary and a test process, so descriptions land as a list of changed behavior with no view of how the change works. Reviewers then rebuild the call order from the diff. Summary now asks for the trigger and the resulting behavior. A new optional How it works section offers four views — a focused diff, a call tree, a shallow file tree, and a Mermaid sequence — with the instruction to pick one or two and delete the section when the summary already covers it. All guidance rides in HTML comments, so an unfilled template renders exactly as it does today. CLAUDE.md and AGENTS.md carry the same rule for agent-authored descriptions. Adapted from HumanLayer's show-me skill and an internal ClickHouse PR-template proposal. * 🧭 docs: Add Review and Completion Standards Both files describe how to write a change and how to test it, but not how a pull request gets from opened to done. That gap is where review rounds stall: a finding gets patched, the next review runs against an older head, and a working code path ships without its empty, failure or restored-session behavior. The new Review and Completion section states the review-cycle invariants — inline threads are the source of truth, findings are judged against the code, a review counts only for the commit it ran on, and repeated findings mean the subsystem needs a sweep — followed by a definition of done covering the observable experience, compatibility, and honest reporting of what was actually run. The reviewer and its trigger phrase are named as the part expected to change, so that subsection can be rewritten without touching the invariants around it. Nothing here restates the existing Testing, Typechecking or Frontend rules; it points at them. * 🧹 docs: Drop the Shipped Insights Design Note `docs/agent-insights-access-design.md` was the pre-implementation spec for #15549, and it says so: "design reference for work based on upstream/dev after PR #14898". Everything it specifies shipped — PermissionBits.VIEW_INSIGHTS = 16, /api/insights, the server-owned initial_agent_id — so the code and its tests are the source of truth now and the note can only drift from them. Nothing in the repository links to it. docs/skills-management-api.md stays: it describes a machine API surface that has no equivalent on librechat.ai, and its details still match packages/api/src/skills/management.ts.
Summary
Adds agent-scoped access control and filtering to Insights while preserving tenant isolation and DocumentDB compatibility.
read:insights, or a per-agent ACL that contains bothVIEWandVIEW_INSIGHTS./api/insightsand keeps the sidebar access probe lightweight.Design decisions
ENABLE_INSIGHTSremains the only feature flag. Public ACL entries, ownership, and agent creation do not grant Insights access; no ACL backfill is performed.read:insightsholders see every current persisted tenant agent. Other users see only agents where one ACL entry grants both required bits.agentIdsselects all authorized agents. Repeated IDs select an exact subset, and any missing or unauthorized ID returns403.initial_agent_id, withagent_idfallback only when the new field is absent. User messages inherit that primary agent; assistant messages useMessage.model.$facet, correlated lookups,$expr, or$type.Change Type
Checklist
Local validation screenshots
Permission granting
Administrators are shown with automatic Insights access: checked, disabled, and not persisted as a redundant per-agent grant. A normal viewer grant remains editable.
A non-admin agent owner can manage normal sharing, but does not receive the Insights grant control.
Agent filtering
The viewer's selector contains only the two agents for which they have both agent view access and per-agent Insights access.
Selecting Alpha Support scopes every dashboard panel to that agent.
Mobile agent filtering
Mobile validation at 390px: the selected agent name and dropdown arrow remain visible. Selecting all agents also updates the summary correctly.