mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-17 05:20:55 +00:00
📐 docs: Set PR Description, Review and Completion Standards (#15753)
* 📐 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.
This commit is contained in:
parent
639d606c53
commit
2dd7ca478a
4 changed files with 192 additions and 131 deletions
153
.github/pull_request_template.md
vendored
153
.github/pull_request_template.md
vendored
|
|
@ -1,41 +1,112 @@
|
|||
# Pull Request Template
|
||||
|
||||
⚠️ Before Submitting a PR, Please Review:
|
||||
- Please ensure that you have thoroughly read and understood the [Contributing Docs](https://github.com/danny-avila/LibreChat/blob/main/.github/CONTRIBUTING.md) before submitting your Pull Request.
|
||||
|
||||
⚠️ Documentation Updates Notice:
|
||||
- Kindly note that documentation updates are managed in this repository: [librechat.ai](https://github.com/LibreChat-AI/librechat.ai)
|
||||
|
||||
## Summary
|
||||
|
||||
Please provide a brief summary of your changes and the related issue. Include any motivation and context that is relevant to your changes. If there are any dependencies necessary for your changes, please list them here.
|
||||
|
||||
## Change Type
|
||||
|
||||
Please delete any irrelevant options.
|
||||
|
||||
- [ ] Bug fix (non-breaking change which fixes an issue)
|
||||
- [ ] New feature (non-breaking change which adds functionality)
|
||||
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
|
||||
- [ ] This change requires a documentation update
|
||||
- [ ] Translation update
|
||||
|
||||
## Testing
|
||||
|
||||
Please describe your test process and include instructions so that we can reproduce your test. If there are any important variables for your testing configuration, list them here.
|
||||
|
||||
### **Test Configuration**:
|
||||
|
||||
## Checklist
|
||||
|
||||
Please delete any irrelevant options.
|
||||
|
||||
- [ ] My code adheres to this project's style guidelines
|
||||
- [ ] I have performed a self-review of my own code
|
||||
- [ ] I have commented in any complex areas of my code
|
||||
- [ ] I have made pertinent documentation changes
|
||||
- [ ] My changes do not introduce new warnings
|
||||
- [ ] I have written tests demonstrating that my changes are effective or that my feature works
|
||||
- [ ] Local unit tests pass with my changes
|
||||
- [ ] Any changes dependent on mine have been merged and published in downstream modules.
|
||||
- [ ] A pull request for updating the documentation has been submitted.
|
||||
# Pull Request Template
|
||||
|
||||
⚠️ Before Submitting a PR, Please Review:
|
||||
- Please ensure that you have thoroughly read and understood the [Contributing Docs](https://github.com/danny-avila/LibreChat/blob/main/.github/CONTRIBUTING.md) before submitting your Pull Request.
|
||||
|
||||
⚠️ Documentation Updates Notice:
|
||||
- Kindly note that documentation updates are managed in this repository: [librechat.ai](https://github.com/LibreChat-AI/librechat.ai)
|
||||
|
||||
## Summary
|
||||
|
||||
<!--
|
||||
Say what breaks or is missing today, what triggers it, and how it behaves after this
|
||||
change. Link the issue with `Fixes #N`, and list any dependency your change needs.
|
||||
Two or three sentences is usually enough:
|
||||
|
||||
"Pasting an image while the composer had focus left Send disabled until the user
|
||||
clicked back into the textarea: the upload dialog took focus and never returned it.
|
||||
Focus now returns to the composer as soon as the attachment mounts."
|
||||
|
||||
Describe the code as it stands. A reader who has not followed the branch has no
|
||||
context for what earlier commits tried or what a review round changed. Naming the
|
||||
merged pull request that caused the bug is different — that is history the reader
|
||||
needs.
|
||||
-->
|
||||
|
||||
## How it works
|
||||
|
||||
<!--
|
||||
Optional. Delete this section when the summary already explains the change.
|
||||
|
||||
Pick one or two views that make the change reviewable, and put a sentence beside
|
||||
each. These show the format, not a required implementation pattern — replace them
|
||||
with real names from your change. Do not paste the whole diff or list every file
|
||||
you touched.
|
||||
|
||||
The mechanism, as a focused diff, when the surrounding shape already exists:
|
||||
|
||||
```diff
|
||||
-const parts = content.filter(isText);
|
||||
-const files = content.filter(isFile);
|
||||
+const { parts, files } = splitContent(content);
|
||||
```
|
||||
|
||||
Runtime order, as a call tree, keeping only the calls that carry the change:
|
||||
|
||||
```text
|
||||
submitMessage
|
||||
ask
|
||||
setMessages
|
||||
setSubmission # opens the SSE stream
|
||||
```
|
||||
|
||||
Ownership, as a shallow file tree, for a new module or a broad refactor:
|
||||
|
||||
```text
|
||||
packages/api/src/agents/
|
||||
├── run.ts # builds the run and its callbacks
|
||||
├── tools.ts # resolves tools for the request
|
||||
└── client.ts # streams provider output back to the route
|
||||
```
|
||||
|
||||
Client/server or cross-service flow, as Mermaid:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant API
|
||||
participant Provider
|
||||
Client->>API: POST /api/agents/chat
|
||||
API->>Provider: stream request
|
||||
Provider->>API: content parts
|
||||
API->>Client: SSE events
|
||||
```
|
||||
|
||||
Editing this file: keep the arrows in the example above solid (`->>`). A dashed
|
||||
Mermaid arrow spells the comment terminator, so it would close this comment early
|
||||
and spill the rest of the guidance into every description. Your own diagram sits
|
||||
outside the comment, where dashed arrows are fine.
|
||||
|
||||
Show a whole block instead of a diff when most of it is new, or when the omitted
|
||||
context would hide execution order or ownership.
|
||||
-->
|
||||
|
||||
## Change Type
|
||||
|
||||
Please delete any irrelevant options.
|
||||
|
||||
- [ ] Bug fix (non-breaking change which fixes an issue)
|
||||
- [ ] New feature (non-breaking change which adds functionality)
|
||||
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
|
||||
- [ ] This change requires a documentation update
|
||||
- [ ] Translation update
|
||||
|
||||
## Testing
|
||||
|
||||
Please describe your test process and include instructions so that we can reproduce your test. If there are any important variables for your testing configuration, list them here.
|
||||
|
||||
### **Test Configuration**:
|
||||
|
||||
## Checklist
|
||||
|
||||
Please delete any irrelevant options.
|
||||
|
||||
- [ ] My code adheres to this project's style guidelines
|
||||
- [ ] I have performed a self-review of my own code
|
||||
- [ ] I have commented in any complex areas of my code
|
||||
- [ ] I have made pertinent documentation changes
|
||||
- [ ] My changes do not introduce new warnings
|
||||
- [ ] I have written tests demonstrating that my changes are effective or that my feature works
|
||||
- [ ] Local unit tests pass with my changes
|
||||
- [ ] Any changes dependent on mine have been merged and published in downstream modules.
|
||||
- [ ] A pull request for updating the documentation has been submitted.
|
||||
|
|
|
|||
24
AGENTS.md
24
AGENTS.md
|
|
@ -10,6 +10,30 @@ reaches it at the next sync. Pull requests opened against `main` are retargeted
|
|||
default branch, so close linked issues by hand. Worktrees share one stash stack, so never use a bare
|
||||
`git stash pop`. See the detailed policy in `CLAUDE.md` under "Branching and Pull Requests".
|
||||
|
||||
Write the description for a reader who has not followed the branch: what breaks, what triggers it,
|
||||
how it behaves after the change, then one or two views of the mechanism — a focused diff, a call
|
||||
tree, a shallow file tree, or a Mermaid sequence. Keep only what the change carries, and describe
|
||||
the code as it stands rather than narrating earlier commits or review rounds. The formats and
|
||||
examples live in `.github/pull_request_template.md`.
|
||||
|
||||
## Review and completion
|
||||
|
||||
Read the inline review threads themselves — a summary comment or notification list omits findings.
|
||||
Audit each one against the current code, fix what is valid, and reject what is obsolete in a reply
|
||||
that says why. After each round: focused tests, `npx tsc --noEmit` in every workspace you changed,
|
||||
push, then request the next review naming the pull request's exact remote head — a clean review of
|
||||
an earlier head says nothing about what you just pushed, and CI runs on its own clock. After two
|
||||
actionable rounds, stop patching thread by thread and read the subsystem by invariant instead.
|
||||
Which reviewer and what phrase triggers it will change; that the review must cover the exact pushed
|
||||
head will not.
|
||||
|
||||
A clean review is one completion signal, not the definition of done. Ship the observable experience
|
||||
— loading, empty, success, failure, cancellation, retry, restored session — with strings localized,
|
||||
accessibility intact, defaults and stored data preserved, and no backend capability left without a
|
||||
frontend entry point. Report the pushed head, what you ran locally, CI state, the review result at
|
||||
that head, and any finding you rejected with the reasoning. See `CLAUDE.md` under "Review and
|
||||
Completion".
|
||||
|
||||
## Verification
|
||||
|
||||
For startup, auth, config, file, or message-loading changes, avoid serial database
|
||||
|
|
|
|||
56
CLAUDE.md
56
CLAUDE.md
|
|
@ -48,6 +48,62 @@ The source code for `@librechat/agents` (major backend dependency, same team) li
|
|||
- **Git worktrees share one stash stack.** `refs/stash` lives in the common `.git` directory, so a
|
||||
bare `git stash pop` in one worktree can take work stashed in another. Prefer a throwaway WIP
|
||||
commit; if you must stash, `git stash push -m <tag>` and `apply` that specific entry.
|
||||
- **Write the description for a reader who has not followed the branch.** Say what breaks, what
|
||||
triggers it, and how it behaves after the change, then show the mechanism with whichever one or
|
||||
two views make it reviewable — a focused diff, a call tree, a shallow file tree, or a Mermaid
|
||||
sequence — keeping only the calls, files and state the change actually carries. Describe the code
|
||||
as it stands: do not narrate what earlier commits tried or what a review round changed. Naming the
|
||||
merged pull request that caused the bug is different — that is history the reader needs.
|
||||
`.github/pull_request_template.md` carries the formats and examples.
|
||||
|
||||
---
|
||||
|
||||
## Review and Completion
|
||||
|
||||
### AI review cycles
|
||||
|
||||
The reviewer, its trigger phrase and its cadence all change; this subsection is the fluid one, so
|
||||
rewrite it when they do. What survives a change of tool: a review counts only for the exact commit
|
||||
it ran on, its findings are judged against the code rather than accepted or dismissed wholesale, and
|
||||
findings that keep arriving mean the subsystem needs a sweep, not another patch.
|
||||
|
||||
- **Inline review threads are the source of truth.** A summary comment, a check name or a
|
||||
notification list omits findings — read the threads on the pull request itself.
|
||||
- Audit every finding against the current code. Fix the valid ones; reject the obsolete or wrong
|
||||
ones in a reply that says why.
|
||||
- After each round of fixes, run the focused tests and `npx tsc --noEmit` for every workspace you
|
||||
changed, push, read the pull request's remote head (`gh pr view <n> --json headRefOid`), and
|
||||
request the next review naming that exact SHA. **A clean review of an earlier head says nothing
|
||||
about what you just pushed.** Do not wait for CI before asking — review and CI run on their own
|
||||
clocks.
|
||||
- Reply on each thread you resolved with the commit that resolved it and the coverage that proves
|
||||
it.
|
||||
- **After two actionable rounds** — or sooner, when each fix uncovers an adjacent defect — stop
|
||||
answering threads one at a time and read the subsystem by invariant: identity, ownership,
|
||||
authorization, persistence, retry, replay, abort, cleanup, expiry, rollout. Follow producers,
|
||||
consumers, adapters, alternate write paths, and the final consumer of every limit; check
|
||||
mixed-version behavior in both directions; read the whole base-to-head diff with the callers and
|
||||
tests around it; then add transition or failure-injection coverage at the deepest boundary that
|
||||
owns the behavior.
|
||||
- The cycle ends when the exact pushed head draws no major findings, or only repeats ones already
|
||||
resolved. A clean review is one completion signal, not the definition of done.
|
||||
|
||||
### Definition of done
|
||||
|
||||
- **Ship the observable experience, not the reported path.** Where they apply, cover loading, empty,
|
||||
success, failure, cancellation, retry and restored-session behavior.
|
||||
- **A backend capability with no frontend entry point is unfinished**, and so is a control with no
|
||||
validation, persistence, error handling or authorization behind it.
|
||||
- Localize every visible string through `useLocalize()`, keep semantic HTML, keyboard behavior and
|
||||
ARIA intact, and compose shared primitives and semantic theme roles before adding local styling
|
||||
(see "Frontend Rules"). Custom styling that proves unavoidable still supports light/dark and
|
||||
reduced motion.
|
||||
- Preserve existing defaults, configuration compatibility, stored data, and mixed-version behavior.
|
||||
- Make the fix the smallest one consistent with the patterns already in the file, and test the
|
||||
behavior that was missed rather than the line a reviewer pointed at.
|
||||
- **Report what you actually ran**: the pushed head, the local checks from "Testing" and
|
||||
"Typechecking", CI state, the review result at that head, and any finding you rejected with the
|
||||
reasoning. Name the checks you could not run instead of implying coverage.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,90 +0,0 @@
|
|||
# Agent-Scoped Insights Design
|
||||
|
||||
Status: design reference for work based on `upstream/dev` after PR #14898.
|
||||
|
||||
## Access Model
|
||||
|
||||
- `ENABLE_INSIGHTS` remains the only feature flag.
|
||||
- Literal tenant admins can view insights for every current persisted agent.
|
||||
- A global `read:insights` grant permits viewing every current persisted agent.
|
||||
- Otherwise, a user needs at least one effective per-agent insights grant to open Insights.
|
||||
- Add `PermissionBits.VIEW_INSIGHTS = 16` to the existing agent ACL entry.
|
||||
- One ACL entry must contain both `VIEW` and `VIEW_INSIGHTS`; bits from separate entries do not combine.
|
||||
- Users, groups, and roles can receive the bit. Public principals cannot.
|
||||
- Agent creators and owners do not receive it automatically. Do not backfill existing ACL entries.
|
||||
- Only literal admins can change the bit, for any agent in their tenant.
|
||||
- Ordinary dashboard reads are not written to the audit log.
|
||||
|
||||
## Permission Updates
|
||||
|
||||
- Extend the existing agent sharing dialog and permission update API.
|
||||
- Show an admin-only **View insights** checkbox on each principal row.
|
||||
- Explain: "Allows this principal to view usage and conversation content for this agent."
|
||||
- Treat `viewInsights` as tri-state: omitted preserves the bit, `true` adds it, and `false` removes it.
|
||||
- Removing ordinary `VIEW` also removes the dependent insights bit.
|
||||
- Save role and insights changes through the existing bulk transaction boundary. Each ACL document is updated atomically.
|
||||
- Audit each actual insights grant or revoke separately. Follow `AUDIT_LOG_FAIL_CLOSED`; compensate any transition that cannot be audited, and do not audit no-op saves.
|
||||
|
||||
## API And Authorization
|
||||
|
||||
- Replace `/api/admin/insights` with `/api/insights`; no compatibility alias is required.
|
||||
- Keep `/api/insights/access` as a lightweight sidebar authorization check.
|
||||
- Outside Insights, the sidebar calls `/access`. On Insights itself, skip `/access` and call `/api/insights` immediately.
|
||||
- `/api/insights` independently resolves authorization and validates the requested agent IDs before starting its data aggregations in parallel.
|
||||
- The main response includes the authorized alphabetized `{ id, name }` agent list and dashboard data.
|
||||
- Omitted `agentIds` means all currently authorized agents. Repeated `agentIds` request an exact subset.
|
||||
- Sort and deduplicate IDs. Return `403` if any requested ID is missing or unauthorized.
|
||||
- Return `404` when the feature flag is off. Return `403` when the feature is on but the user has no accessible agents.
|
||||
- Resolve access on every protected request; do not add an authorization cache.
|
||||
- Every Agent, ACL, Conversation, Message, and User query must be tenant-scoped.
|
||||
- Transcript and attachment viewing are out of scope.
|
||||
|
||||
## Agent Filter
|
||||
|
||||
- Put a simple multi-select in the sticky header before the date controls.
|
||||
- Show current persisted agents only, in alphabetical order. Include agents with no activity.
|
||||
- Do not show deleted agents or their historical data.
|
||||
- Select all accessible agents by default, without a synthetic "All" row.
|
||||
- Provide a **Select all** command and prevent an empty selection.
|
||||
- Keep a one-agent selector visible but disabled.
|
||||
- Show one agent name, `N agents`, or `All N agents` in the trigger.
|
||||
- For duplicate names only, append a short stable agent ID.
|
||||
- Preserve the date range and conversation search when the filter changes; reset conversation pagination.
|
||||
- Omit `agentIds` from the URL for the default all-agent view; use repeated values for a subset.
|
||||
- Reserve the Insights icon slot while access loads so the icon rail does not move.
|
||||
|
||||
## Metric Attribution
|
||||
|
||||
- Add an immutable, server-owned `initial_agent_id` to conversations.
|
||||
- On insert, set it to the verified same-tenant persisted agent ID, or explicitly to `null` when the conversation did not start with one.
|
||||
- Never accept client writes to `initial_agent_id` and never change it after insertion.
|
||||
- Do not migrate existing conversations. For legacy rows where the field is absent, fall back to `agent_id`.
|
||||
- Conversation metrics and the conversations table use `initial_agent_id`, or the legacy fallback, as the primary agent.
|
||||
- Show only that primary agent in each conversations-table row.
|
||||
- Assistant messages use the persisted top-level `Message.model` agent ID.
|
||||
- User messages, which do not consistently store an agent ID, inherit the conversation's primary agent.
|
||||
- Ignore nested agent IDs in message content; subagent activity does not grant access to the parent conversation.
|
||||
- Exclude persisted `subagentThread` conversations and messages as standalone Insights data.
|
||||
- In a mixed-agent conversation, conversation metrics remain with the primary agent while assistant messages and output tokens can count for the agent in `Message.model`.
|
||||
- Unique users include users with any attributed message.
|
||||
- Top users counts attributed messages and distinct conversations containing them.
|
||||
- Churn uses user-authored messages only, across all selected agents, with the existing 28-day threshold.
|
||||
- Keep the Conversations label and add a tooltip stating that it counts conversations created during the selected period.
|
||||
- Text search affects only the conversations table. Agent and date filters affect every panel.
|
||||
- Archived and automated top-level persisted-agent conversations remain included.
|
||||
- Temporary, unattributed, deleted-agent, remote-agent, ephemeral-agent, and newly created normal chats later converted to agents are excluded.
|
||||
- Empty periods keep the dashboard visible, show zero summaries, and show localized empty states.
|
||||
|
||||
## DocumentDB Constraints
|
||||
|
||||
- Do not use `$facet` or correlated `$lookup` pipelines.
|
||||
- Bound conversation agent filters by indexed persisted fields before projection. Bound message queries by tenant and date before joining.
|
||||
- Use equality `$lookup` only where user messages must inherit conversation attribution, then validate tenant and owner after the join.
|
||||
- Add the required conversation agent/date index and message attribution index.
|
||||
- Cover the final pipelines in the DocumentDB compatibility tests.
|
||||
|
||||
## Delivery
|
||||
|
||||
- Implement the complete change in one PR.
|
||||
- Add the required indexes with the code; no separate index rollout is needed at current query volume.
|
||||
- Preserve the existing date, search, pagination, churn, and empty-state behavior except where this document explicitly changes it.
|
||||
Loading…
Add table
Add a link
Reference in a new issue