feat(intelligent-assistant): add inline rename for notebook resources

[its-mitesh-kumar]

Description

Adds inline rename capability for notebook documents (resources) in the DocumentSidebar with full backend support.

Fixed

• https://redhat.atlassian.net/browse/RHIDP-14854

Backend

• Consolidated renameDocument logic into upsertDocument using an options object ({ fileType?, fileId?, newTitle? }) to eliminate code duplication
• upsertDocument includes rollback protection: if the vector store re-creation fails after delete, the original entry is restored
• Added title length validation (max 255 characters) in the PATCH endpoint with a 400 response for violations
• Defensive fallback for resolvedFileType to prevent undefined values in attributes

Frontend

• Users can double-click a filename or select "Rename" from the kebab menu to edit inline
• File extension shown as a static suffix (cannot be accidentally modified)
• Client-side validation with real-time error feedback:
  • Duplicate name detection ("Name already exists.")
  • Title length enforcement ("Name too long (max 255).")
  • Legacy long titles (pre-existing > 255 chars) don't trigger error until the user changes the name
• Hover effects on document rows and file names for discoverability
• Save on blur (clicking away commits the rename; Escape cancels)
• Only error toast on failure (no success toast — the inline name change provides visual confirmation)
• Error icon vertically centered in the input field (PF6 padding override)

UI after fix

S_.2026-07-26.at.7.09.52.AM.mov

Translations

• Added notebook.document.rename.tooLong key across all 6 languages
• Shortened conflict message to "Name already exists."
• Removed orphaned notebook.document.rename.success key

Fixed

• RHIDP-14854
  

✔️ Checklist

• A changeset describing the change and affected packages. (more info)
• Tests for new functionality and regression tests for bug fixes
• Screenshots attached (for UI changes)

[rhdh-gh-app]

Important

This PR includes changes that affect public-facing API. Please ensure you are adding/updating documentation for new features or behavior.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@red-hat-developer-hub/backstage-plugin-intelligent-assistant-backend	workspaces/intelligent-assistant/plugins/intelligent-assistant-backend	minor	v3.2.0
@red-hat-developer-hub/backstage-plugin-intelligent-assistant	workspaces/intelligent-assistant/plugins/intelligent-assistant	minor	v3.2.0

[codecov]

Codecov Report

❌ Patch coverage is 78.66667% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 58.37%. Comparing base (e632466) to head (4152077).
⚠️ Report is 5 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3834      +/-   ##
==========================================
+ Coverage   58.33%   58.37%   +0.03%     
==========================================
  Files        2432     2433       +1     
  Lines       96775    96917     +142     
  Branches    26912    26953      +41     
==========================================
+ Hits        56455    56573     +118     
- Misses      40121    40145      +24     
  Partials      199      199              

Flag	Coverage Δ		*Carryforward flag
adoption-insights	84.55% <ø> (ø)		Carriedforward from c99c375
ai-integrations	69.76% <ø> (ø)		Carriedforward from c99c375
app-defaults	69.79% <ø> (ø)		Carriedforward from c99c375
augment	46.67% <ø> (ø)		Carriedforward from c99c375
boost	76.77% <ø> (ø)		Carriedforward from c99c375
bulk-import	72.79% <ø> (ø)		Carriedforward from c99c375
cost-management	13.55% <ø> (ø)		Carriedforward from c99c375
dcm	67.21% <ø> (ø)		Carriedforward from c99c375
extensions	56.59% <ø> (ø)		Carriedforward from c99c375
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from c99c375
global-header	66.50% <ø> (ø)		Carriedforward from c99c375
homepage	47.50% <ø> (ø)		Carriedforward from c99c375
install-dynamic-plugins	59.95% <ø> (ø)		Carriedforward from c99c375
intelligent-assistant	75.42% <78.66%> (+0.18%)	⬆️
konflux	91.98% <ø> (ø)		Carriedforward from c99c375
lightspeed	69.02% <ø> (ø)		Carriedforward from c99c375
mcp-integrations	83.40% <ø> (ø)		Carriedforward from c99c375
orchestrator	66.91% <ø> (ø)		Carriedforward from c99c375
quickstart	63.74% <ø> (ø)		Carriedforward from c99c375
sandbox	79.56% <ø> (ø)		Carriedforward from c99c375
scorecard	86.17% <ø> (ø)		Carriedforward from c99c375
theme	88.77% <ø> (ø)		Carriedforward from c99c375
translations	5.12% <ø> (ø)		Carriedforward from c99c375
x2a	79.20% <ø> (ø)		Carriedforward from c99c375

*This pull request uses carry forward flags. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e632466...4152077. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[its-mitesh-kumar]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:19 AM UTC · Completed 10:26 AM UTC
Commit: 8d3503a · View workflow run →

[fullsend-ai-review]

Review

Findings

High

• [missing-doc] workspaces/intelligent-assistant/plugins/intelligent-assistant-backend/README.md:445 — The new PATCH /v1/sessions/:sessionId/documents/:documentId endpoint for document rename is not documented in the API Endpoints section of the backend README, which lists PUT, GET, GET (status), and DELETE for the Documents group but omits PATCH.
  Remediation: Add the PATCH endpoint to the Documents bullet list in the API Endpoints section, e.g.: PATCH /intelligent-assistant/notebooks/v1/sessions/:sessionId/documents/:documentId — Rename a document (JSON body: { "title": "new name" }).

Medium

• [race-condition] workspaces/intelligent-assistant/plugins/intelligent-assistant/src/components/notebooks/DocumentSidebar.tsx:280 — The savingRef guard intended to prevent double-invocation of onRenameDocument when both Enter and blur fire is ineffective. saveRename sets savingRef.current = true, calls onRenameDocument, then calls cancelEditing() which immediately resets savingRef.current = false. When React removes the input from the DOM, the blur event fires and saveRename runs again with the ref already reset. The double-call is currently prevented by an accidental side-effect (editName is cleared by cancelEditing(), causing the !trimmedBase early return), but this relies on a fragile side-effect rather than the intended guard mechanism.
  Remediation: Move savingRef.current = false out of cancelEditing and reset it only in startEditing.

Low

• [input-validation] workspaces/intelligent-assistant/plugins/intelligent-assistant-backend/src/service/notebooks/notebooksRouters.ts:451 — The documentId path parameter in the PATCH handler has no length validation. The 255-char limit is only applied to the new title from the request body, not the documentId. A very long documentId would simply fail the lookup, but the asymmetry is a minor defense-in-depth gap. See also: [missing-guard] finding on the same endpoint.

• [missing-guard] workspaces/intelligent-assistant/plugins/intelligent-assistant-backend/src/service/notebooks/notebooksRouters.ts:469 — The PATCH endpoint does not guard against a no-op rename where title.trim() === documentId, causing an unnecessary delete-and-recreate cycle in the vector store. The frontend prevents this scenario, but the backend is unprotected from direct API calls. See also: [input-validation] finding on the same endpoint.

• [toctou-race-condition] workspaces/intelligent-assistant/plugins/intelligent-assistant-backend/src/service/notebooks/documents/documentService.ts:173 — The rename operation performs a non-atomic check-then-act sequence (conflict check → delete → create). Concurrent rename requests could theoretically bypass the duplicate-title check. Practical risk is very low given per-user session ownership enforced by requireSessionOwnership middleware. See also: [scope-coherence] finding on the same file.

• [scope-coherence] workspaces/intelligent-assistant/plugins/intelligent-assistant-backend/src/service/notebooks/documents/documentService.ts — The deleteDocument method behavior was silently changed to preserve Files API entries (JSDoc updated from "Delete a document from the vector store and Files API" to "Remove a document's vector store entry... intentionally preserved"). This affects all delete operations, not just rename — standalone deletions now leave files in the Files API without corresponding vector store entries, which could accumulate over time.

• [naming-consistency] workspaces/intelligent-assistant/plugins/intelligent-assistant/src/translations/ref.ts:112 — Translation key notebook.document.rename.tooLong is 'Name too long (max 255)' without a trailing period, while sibling key notebook.document.rename.conflict has 'Name already exists.' with a period. All non-English locales (de, es, fr, it, ja) include the period for tooLong.

• [code-organization] workspaces/intelligent-assistant/plugins/intelligent-assistant/src/components/notebooks/DocumentSidebar.tsx:371 — The inline rename rendering uses an IIFE (() => { ... })() inside JSX to scope the validation error computation. This pattern is not used elsewhere in the codebase, which favors ternary expressions or extracted sub-components.

Previous run

Review — approve

PR: #3834 — feat(intelligent-assistant): add inline rename for notebook resources
Scope: workspaces/intelligent-assistant (frontend plugin + backend plugin)

Summary

This PR adds inline rename functionality for notebook document resources. The implementation is well-structured, spanning backend (PATCH endpoint with conflict detection and rollback) and frontend (inline TextInput with extension separation, conflict validation, keyboard handling). Test coverage is thorough across all layers.

What looks good

• Backend endpoint design — The PATCH route at /v1/sessions/:sessionId/documents/:documentId correctly uses generalRateLimiter, requireNotebooksPermission, and requireSessionOwnership(), matching the security posture of adjacent endpoints (DELETE, GET status). Input validation catches empty/whitespace titles with a 400 response.
• Rollback logic — documentService.renameDocument handles the case where the vector store re-create fails after delete by attempting to restore the original entry. Error logging distinguishes between rollback success and orphaned-document failure, aiding debuggability.
• Frontend conflict validation — The getConflictError callback provides real-time client-side conflict detection against the current document list, preventing unnecessary round-trips. The backend also validates conflicts independently (defense in depth).
• Extension handling — splitFileName correctly handles dotfiles (lastDot <= 0 treats names like .env as extensionless), and the extension is rendered as a static suffix outside the input, preventing accidental modification.
• Test coverage — Backend tests cover happy path, 404, 409, and empty-title validation. Frontend tests cover double-click entry, Enter to save, Escape to cancel, unchanged-name skip, empty-name skip, kebab menu trigger, tooltip presence, conflict error display, and conflict-free state.
• i18n — All five translation files (de, es, fr, it, ja) updated alongside the reference strings, with proper interpolation templates.

Findings

1. Non-atomic rename relies on delete-then-create with a brief inconsistency window

Severity	low
Category	correctness
File	workspaces/intelligent-assistant/plugins/intelligent-assistant-backend/src/service/notebooks/documents/documentService.ts
Line	~290 (in diff: the renameDocument method)

renameDocument deletes the old vector store file entry and then re-creates it with the new title. Between these two operations there is a brief window where the document does not exist in the vector store. A concurrent /query request hitting this window would miss the document's content. The rollback handles the most likely failure mode (create throws), but a process crash between delete and create would leave the document absent with the underlying file orphaned. This is an inherent limitation of the vector store API (no in-place attribute update), and the developer has mitigated it as well as is practical. Worth noting for operational awareness; no code change needed.

2. No maximum length or character validation on new title

Severity	low
Category	correctness
File	workspaces/intelligent-assistant/plugins/intelligent-assistant-backend/src/service/notebooks/notebooksRouters.ts
Line	~453 (in diff: the PATCH handler)

The PATCH endpoint validates that title is a non-empty, non-whitespace string, but does not enforce a maximum length or restrict characters (e.g., path separators, control characters). Extremely long titles could cause truncation or display issues in the sidebar, and special characters might interact poorly with the vector store API's attribute storage. Consider adding a length cap consistent with other title fields in the codebase.

3. Rename tooltip and kebab item shown unconditionally

Severity	low
Category	style/conventions
File	workspaces/intelligent-assistant/plugins/intelligent-assistant/src/components/notebooks/DocumentSidebar.tsx
Line	~376 (in diff: Typography with tooltip)

The "Double-click to rename" tooltip and the "Rename" kebab dropdown item are always rendered, regardless of whether onRenameDocument is provided. If DocumentSidebar is ever used without the callback, users would see the rename UI but saves would silently no-op (via optional chaining onRenameDocument?.(...)). This mirrors the existing pattern for onDeleteDocument, so it's consistent. No change required unless the component is reused elsewhere without rename support.

Verdict

The implementation is solid, well-tested, and follows established patterns in the codebase. The non-atomic rename is an inherent API limitation handled with appropriate rollback protection. The PR is safe to merge.

---

Labels: PR adds a PATCH endpoint and inline rename UI within the intelligent-assistant workspace

[its-mitesh-kumar]

@JslYoon Please review the backend changes.

[HusneShabbir]

I noticed a slight delay in the file renaming process. It seems the non-atomic rename relies on a delete-then-create flow, which introduces a brief inconsistency window. I'd encourage @JslYoon to take a closer look and suggest any improvements if applicable.

Also, could you please address comments 1 and 2 from the Fullsend review? Specifically:

• 1: The non-atomic rename (delete → create) introduces a brief inconsistency window.
• 2: Very long title names don't add much value; it would be better to consider adding a length cap.

#3834 (comment)

Screen.Recording.2026-07-20.at.1.24.16.PM.mov

[JslYoon]

There already exists a function upsertDocument that handles document updates, which follows the same logic as this function, please use it instead.

[its-mitesh-kumar]

@JslYoon Done — removed renameDocument and consolidated into upsertDocument with an options object ({ fileType?, fileId?, newTitle? }). Added rollback protection, attribute preservation, defensive fileType fallback, and a 255-char title length cap at the router level.

One concern: rename latency on local itself is 1–2 min due to the delete → re-create flow on the vector store (no in-place attribute update API). Can we do something here ?

[its-mitesh-kumar]

I noticed a slight delay in the file renaming process. It seems the non-atomic rename relies on a delete-then-create flow, which introduces a brief inconsistency window. I'd encourage @JslYoon to take a closer look and suggest any improvements if applicable.

Also, could you please address comments 1 and 2 from the Fullsend review? Specifically:

• 1: The non-atomic rename (delete → create) introduces a brief inconsistency window.
• 2: Very long title names don't add much value; it would be better to consider adding a length cap.

#3834 (comment)

Screen.Recording.2026-07-20.at.1.24.16.PM.mov

@HusneShabbir

Addressed both points:

1. Non-atomic rename (delete → create): This is an inherent limitation of the vector store API — there's no in-place attribute update endpoint. The rollback protection in upsertDocument mitigates the most likely failure (create throws after delete), but a brief inconsistency window remains unavoidable with the current API surface. On latency @JslYoon will check if we can do something here ?

2. Title length cap: Added a 255-character limit enforced at both the backend (PATCH endpoint returns 400) and frontend (inline validation with error feedback: "Name too long (max 255)").

[its-mitesh-kumar]

@ShiranHi Handled all your below feedbacks and have updated the screen recording please have a look.

• Could we add a hover state to the field so users know it's editable, as in the prototype?
• We don't need the floating confirmation toast message on successful rename. Changes should auto-save as soon as the user clicks outside the field or presses Enter
• When selecting "Rename" from the 3-dots menu, the text field should immediately become active and focused.
• For the duplicate name error, let's center the error icon inside the field and shorten the copy to "Name already exists.

[its-mitesh-kumar]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 3:29 AM UTC · Completed 4:09 AM UTC
Commit: 3ea8060 · View workflow run →

[its-mitesh-kumar]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:19 AM UTC · Completed 4:37 AM UTC
Commit: 11b90d3 · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[ShiranHi]

@ShiranHi Handled all your below feedbacks and have updated the screen recording please have a look.

• Could we add a hover state to the field so users know it's editable, as in the prototype?
• We don't need the floating confirmation toast message on successful rename. Changes should auto-save as soon as the user clicks outside the field or presses Enter
• When selecting "Rename" from the 3-dots menu, the text field should immediately become active and focused.
• For the duplicate name error, let's center the error icon inside the field and shorten the copy to "Name already exists.

LGTM, thank you!

[JslYoon]

I noticed a slight delay in the file renaming process. It seems the non-atomic rename relies on a delete-then-create flow, which introduces a brief inconsistency window. I'd encourage @JslYoon to take a closer look and suggest any improvements if applicable.
Also, could you please address comments 1 and 2 from the Fullsend review? Specifically:

• 1: The non-atomic rename (delete → create) introduces a brief inconsistency window.
• 2: Very long title names don't add much value; it would be better to consider adding a length cap.

#3834 (comment)
Screen.Recording.2026-07-20.at.1.24.16.PM.mov

@HusneShabbir

Addressed both points:

1. Non-atomic rename (delete → create): This is an inherent limitation of the vector store API — there's no in-place attribute update endpoint. The rollback protection in upsertDocument mitigates the most likely failure (create throws after delete), but a brief inconsistency window remains unavoidable with the current API surface. On latency @JslYoon will check if we can do something here ?
2. Title length cap: Added a 255-character limit enforced at both the backend (PATCH endpoint returns 400) and frontend (inline validation with error feedback: "Name too long (max 255)").

Yes unfortunately this is a problem with the nature of how vector stores are configured in the upstream, and would require bigger code changes upstream for delete/insert to be faster. However, I'm addressing this issue right now through https://redhat.atlassian.net/browse/RHDHBUGS-3302

[JslYoon]

Backend changes look good

[its-mitesh-kumar]

@ShiranHi @HusneShabbir @tobiastal
I made the changes to align document rename UX with notebook title rename:

1. single-click to edit (was double-click),
2. optimistic cache update with rollback on API failure : Now user will see the updated name instantly, if API failures happen it will get roll-backed.

Happy flow

S_.2026-08-07.at.3.05.19.PM.mov

API failure

S_.2026-08-07.at.3.19.08.PM.mov

[its-mitesh-kumar]

The document rename file was jumping to the top of the list. I made changes to preserve positions of documents in the sidebar

@JslYoon : Added created_at ascending sort in listDocuments to stabilize document ordering after rename. The delete → re-create flow changes the vector store's internal ordering, but since upsertDocument preserves the original created_at attribute, sorting by it keeps documents in their original upload order. Hope you are good with this change.

UI before changes

S_.2026-08-07.at.5.18.34.PM.mov

UI after changes

S_.2026-08-07.at.5.17.34.PM.mov

Cc: @ShiranHi @HusneShabbir @tobiastal

[ciiay]

Thanks for the work on this — the rename flow looks solid overall (optimistic update, validation, rollback, and the created_at ordering fix are appreciated).

Please address #1 and #3 before merge. #2 is a nit only.

Requested changes

1. Document the new PATCH endpoint in the backend README Documents API list (implementation is already in place; docs are missing).
2. Keep the inline editor open when the name is invalid (too long / conflict) on Enter or blur, instead of calling cancelEditing().

Nit

2. Add a trailing period to the EN notebook.document.rename.tooLong string for consistency with the conflict message and other locales.

[ciiay]

Requested change: When the name is too long or conflicts, saveRename currently calls cancelEditing() and exits edit mode (on both Enter and blur).

Please keep the user in the inline editor when validation fails so the error helper text remains visible and they can correct the name. For example, early-return without cancelEditing() when getValidationError(docId, originalTitle) is non-null (empty / unchanged can still cancel as today).

[its-mitesh-kumar]

We intentionally cancel on blur/Enter when validation fails. The error is visible in real-time while the user types, giving them a chance to correct it before submitting. If they press Enter or click away with an invalid name, we treat it as an implicit cancel (same as Escape) and revert to the original name. This avoids trapping the user in the editor and matches common file-rename UX patterns (e.g. macOS Finder).
Cc: @ShiranHi @tobiastal

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud