Repository navigation
[RFC] Material library (tracking) #1736
Description
Tracking issue for RFC Discussion #1716. The initial material-library integration is merged and included in the first 1.3.0 release candidate.
Status — checked 2026-10-26: #1896 merged into main as c4a24031. v1.3.0-rc.1 was published on 2026-10-22 from c119eefc83fc555d1e1cf73bdff612605e908775. #1898 is completed and closed: every successful upload is retained; only unfinished reservations have a 24-hour sweep; material and file-storage allowances remain separate with separate display.
#1923 merged on 2026-10-26 as 84a88bc4. It completes #1892 items 1, 2, 4, 5 and 6. The 2026-10-23 thinking decision keeps the current raw preview intentionally; item 3 needs no implementation. #1892 has been updated and closed as completed, citing the maintainer's decision and merged #1923.
Latest scope decisions override the earlier “next phase” plan: #1875 is parked until real usage demonstrates demand for batch operations. #1932 is also parked so navigation can be designed together with the composer/tool-row changes in #1957. Both stay open and Draft; neither is a current 1.3.0 requirement. The former conversation-side pane and other-folder notice remain superseded.
Scope
- An owner-scoped material library (Knowledge base / 知识库 in the UI): folders and top-level files (
folderId = null, without an "Unfiled" UI label), a library page opened from the left rail, and@selection of library materials in the composer. - Materials and their extraction outputs in the asset pool, kept alive by generic
asset_root_refs, with extraction reused across conversations. - One set of library operations shared by the page and the agent, with a one-line summary of each agent change in its tool-call row. No undo or result cards in the first batch.
Phases
Checked implementation items reached main through merged #1896. A checkmark does not mean an RC or deployment has shipped.
- 1a. Manifest, folders and
asset_root_refs; lifecycle checks against both reference tables; claims; reference-rule version; remove theDROP COLUMN asset_idbootstrap statement (feat(storage): add asset reference roots and the material library schema (1a) #1745) - 1b. Owner-level extraction state and the per-owner extraction cache (feat(persistence): owner-level material extraction state and per-owner cache (1b) #1753)
- 1c. New uploads into the pool, pool-first reads, and opt-in backfill / migration; real database verification with old sessions and new uploads side by side (feat(materials): store uploads in the asset pool, read pool-first, and backfill (1c) #1763)
- Required 1c follow-up: release losing backfill allocations, fall back to retained old objects when pool reads fail, and verify old-object digests (fix(materials): release losing backfill allocations and harden the pool-first reader (1c follow-up) #1791)
- 2a. Runtime/readers: attach-by-id, library scopes, source-id and revision-aware reads, consumer compatibility, document-image ingestion/reference rewriting, course copy-on-use, the prompt and owner extraction activation (feat(materials): material library runtime and readers (Phase 2a) #1801)
- 2b. Shared organizing operations/routes/tools, invalidation, limits, tool-row summaries, composer pickers and
@, empty-folder deletion (feat(materials): organizing, invalidation, tool rows and the @ pickers (Phase 2b) #1802) - Source deletion after Phase 2: shared source/derivative deletion and the page-only HTTP route; confirmation UI stays in Phase 3; no agent deletion tool (feat(materials): delete a source with its derivatives #1805)
- Required deletion follow-up: cleanup-only scan for deleted originals independent of the backfill flag, and removal of the move/delete lock cycle (fix(materials): retry deleted originals without the backfill and drop the move/delete lock cycle #1806)
- Required 2a hardening: bounded parser workers/queue and input admission, parsing outside the owner fence, position-validation fallback, cancellation, and text preservation when structural image parsing exceeds its input budget (fix(materials): harden document image parsing #1808)
- 2b nit follow-up (fix(materials): address Phase 2b follow-up nits #1818, merged): legacy-copy notice after successful rename/move, correct existing-folder counts, same-turn picker deduplication, skipping unused
@usage/count calculations, and NULL extraction settlement. Includes the two N3 regression-test coverage additions. - 3. Library page: left-rail entry, one folder-and-file list with flat search, usage and limits, processing status and automatic parsing after uploads from both the page and composer (ready publication and pending extraction are atomic; Parse / Parse again remain for idle sources and failures), refresh (polling and focus), empty state/onboarding, in-place folder creation and renaming, Open / Download original labels matching the response, source-delete confirmation and empty-folder controls (feat(workspace): knowledge base page (material library Phase 3) #1835, merged as
11857e87; a card view with thumbnails comes later). Its description records automated checks, browser validation, a walkthrough recording and the remaining validation limits.
The original combined Phase 2 PR #1792 was closed after splitting into #1801 and #1802. All phase items above and the required follow-ups below are merged into the integration branch; the integration-to-main PR #1896 is now merged.
Required follow-up before main — #1865
The Phase 3 review assigned these two items to one follow-up PR, #1865, separate from #1835. They are now merged into the integration branch:
- Non-empty folder deletion: always offer Delete on folders. For a non-empty folder, confirmation states that its N files move to the top level; no files are deleted. Moving the files and deleting the folder happen in one transaction.
- Searchable toolbar picker: the composer toolbar button opens the same searchable picker as inline
@, with a visible sort order.
Implementation status: Both items above are merged in #1865 into integration/material-library as 510973bd. The PR also implements the subsequent review requirements:
| Requirement | Status in #1865 |
|---|---|
| Drag-to-move, shared with the course rail; remove the Move dialog and move menu entries | Implemented, including hover expansion, target highlights and edge auto-scroll. |
| Explicit top-level tool argument and terminology | folderId: "top-level" maps to persistence null; real pi-ai argument validation is tested. Tool descriptions and the material prompt no longer use “Unfiled”. |
| Shared page/picker status wording and failed-file selection | Implemented; failed materials are disabled in both inline @ and toolbar pickers. |
| Unconfigured parsing-service guidance | Updated across 12 locales for all file types; Parse again appears immediately before Delete. |
| Preserve a new-folder draft after duplicate-name refusal and search | Implemented. |
| Upload-row continuity and status-column layout | Implemented. |
Validation on 05430148: Six CI checks pass. A real browser + PostgreSQL + worker + project MaaS run passed simultaneous uploads, drag moves, agent move/list with "top-level", both pickers, non-empty-folder deletion and touch scrolling at 375 px. Recordings and detailed results are in #1865. Edge auto-scroll was tested with controlled browser responses, not in the live three-file run; physical Safari/iOS was not tested.
Disclosed input limitation: Drag-to-move supports mouse/trackpad input. Native touch scrolling is preserved, but there is no dedicated touch or keyboard move entry point; the agent can move materials. #1865 asks the reviewer to confirm this limitation.
Duplicate file display names are intentional and remain allowed; #1835 records this in its description. Folder names remain unique.
Completed final integration follow-up — #1880
- Material library: follow-ups before the integration branch merges to main #1880: course-rail drag/drop styling, successful tool-call status, safe model-facing failure reasons and status wording, and picker details. Merged through fix(materials): final follow-ups before integration merges to main #1888 into
integration/material-libraryas742e94c6and included in feat: integrate material library into main #1896.
Current release and follow-ups
| Item | Current status | Next action |
|---|---|---|
| #1896 / rc.1 | Merged; rc.1 published on 2026-10-22 | Preserve the published baseline; deployment acceptance is recorded separately. |
| #1898 | Completed and closed by the maintainer on 2026-10-22 | No additional upstream retention/quota implementation is pending under this issue; verify actual host integration when deploying. |
| #1892 → #1923 | #1923 merged as 84a88bc4; thinking intentionally unchanged, no implementation needed |
#1892 is closed as completed; no issue closeout remains. Confirm which later release/tag contains the merged fix; merge alone does not publish it. |
| #1875 | Parked; keep Draft and open | Wait for actual usage to justify batch operations. No automatic Ready transition after rebase or green CI. |
| #1924 → #1932 | Parked; keep Draft and open | Revisit navigation with #1957. Do not independently advance its old rebase/browser/RFC implementation checklist as a release gate. |
| Former standalone classic-generation library-picker candidate | No current independent implementation commitment is established by the latest decisions | Coordinate any new entry point with the current home/workbench design. Durable classic uploads are already implemented; they do not imply that a new standalone picker has shipped. |
Parked batch implementation — #1875
The 2026-10-22 decision supersedes the earlier post-integration Ready instruction. The reason is product demand: the knowledge base is newly on main and has not seen enough real use to justify batch management yet. It is not waiting on another technical prerequisite.
The implementation is preserved at 4aadfe06, now targeting main after a rebase onto 84a88bc4. Eight focused files / 337 tests, full TypeScript/static checks, Chromium component walkthroughs at 1280/375 px and all seven new-head CI checks passed. Those results preserve a usable draft; they do not authorize resuming delivery. Details and historical real-PostgreSQL recordings remain in #1875. No merge, Ready transition or scheduled 1.3.0 delivery is implied.
Parked page links and the separate workbench line
The 2026-10-22 decision parks #1932 because its composer, tool rows and originating panel are being reworked in #1957. The page-link draft at 70f678e0 remains unmerged on its existing base. The no-pane design still applies; do not publish the old local RFC amendment as an agreed implementation while navigation is parked.
The latest #1957 decision, 2026-10-23 says materials reuse ordinary session references in a candidate after rc.1, with actual gaps verified; oversized-document splitting is after 1.3.0. That separate line ships in whichever release candidate is current once accepted and must not hold up 1.3.0. It does not reinstate #1875 or require a separate classic executor/library-picker project here.
Remaining closeout — checked 2026-10-26
- Record the actual later release/tag containing fix(materials): clarify picker guidance, tool errors and move feedback #1923. Latest publication checked here remains v1.3.0-rc.1; neither rc.2 nor 1.3.0 stable is recorded as published.
- Validate and record the deployed host's actual version, identity/ownership mapping, byte store/parser/worker wiring, old-result compatibility, durable-upload cleanup, separate usage/enforcement and supported generation consumers. Upstream CI and QA are not host deployment acceptance.
- At formal release closeout, record the chosen 1.3.0 tag/commit and resolved release findings. No parked feature is required merely because it appeared in an earlier plan.
The final upstream QA and earlier nine-scenario smoke remain evidence for their stated heads. They do not assert deployment completion. No new code, migration, backfill, deployment, issue closure or PR review-state change is performed by this status update.
Release conditions
v1.3.0-rc.1 is published. #1923 landed later for the subsequent release line; publication of a later RC/stable remains separate. The integration's upgrade conditions still apply:
- Stop every old instance before this version accepts material-pool writes; do not run a mixed-version rollout.
- Finish the rollout well within
ASSET_COLLECTION_GRACE_MS. - Do not run an older version against the upgraded database or roll back below this material-pool boundary.
- Optional backfill is not a prerequisite for library membership; enable it only after old instances have stopped and follow the documented ordering.
Activity
fix(persistence): key the owner extraction cache on endpoints and reu…
feat(persistence): owner-level material extraction state and per-owne…
fix(persistence): key the owner extraction cache on endpoints and reu…
test(persistence): make the publication rollback case fail after the …
feat(storage): refuse generic remove and replace of rooted entries (0…
feat(materials): store uploads in the asset pool and read pool-first
feat(materials): backfill pre-pool uploads into the asset pool, opt-in
docs(materials): state how long the pool reader's fallback holds the …
feat(persistence): owner-level material extraction state and per-owne…
fix(persistence): key the owner extraction cache on endpoints and reu…
test(persistence): make the publication rollback case fail after the …
feat(persistence): owner-level material extraction state and per-owne…
feat(storage): refuse generic remove and replace of rooted entries (0…
13 remaining items
wyuc commentedon Oct 12, 2026
#1888 is merged into
integration/material-library(742e94c), which completes #1880. The integration branch is ready to merge intomain. Small follow-ups that don't block it are in #1892, and multi-select (#1875) waits for the next phase.LING-6150 commentedon Oct 12, 2026
@wyuc Thanks, noted. I'm working on the integration →
mainmerge PR now and will link it here once it's open. #1875 stays a draft until then; afterwards I'll rebase it ontomain, retarget it and mark it ready. I'll take #1892 in 1.2.x.LING-6150 commentedon Oct 13, 2026
Current status — checked 2026-10-26: #1896 is merged; v1.3.0-rc.1 is published. #1923 is now merged and thinking needs no change. #1892 has been updated and closed as completed. #1875 is parked pending usage, and #1932 is parked for navigation coordination with #1957; both remain Draft. These later decisions supersede earlier delivery instructions. See the tracking body and updated plan. Deployment acceptance remains separate.
Earlier integration announcement (historical)
updated： The material-library integration PR is now ready for review: #1896 (integration/material-library → main).
It includes this phase’s implementation and review follow-ups through #1888. The PR description documents the required rollout conditions.
Bulk operations (#1875) and the small follow-ups in #1892 remain separate from this release. Pending review and merge into main.
LING-6150 commentedon Oct 13, 2026
1.3.0 knowledge-base plan — checked 2026-10-26
This replaces the outdated delivery statuses in this plan. The 2026-10-22/23 maintainer decisions take precedence over the earlier post-integration “next phase” instructions.
Published and merged
c119eefc83fc555d1e1cf73bdff612605e908775. The base material library from merged #1896 is included. There is no remaining “publish the first RC” task.84a88bc4, 2026-10-26. Thinking item 3 needs no change; #1892 has been updated and closed as completed, citing that decision and merged fix(materials): clarify picker guidance, tool errors and move feedback #1923. No administrative closeout remains. A later published tag containing fix(materials): clarify picker guidance, tool errors and move feedback #1923 is not yet recorded.Parked — retain Drafts, no current release commitment
4aadfe06, with seven green CI checks; these technical results do not change the hold. Keep open and Draft.Separate workbench/material-entry coordination
The latest #1957 decisions reuse ordinary session references for materials in a candidate after rc.1, verify gaps, and defer oversized-document splitting until after 1.3.0. That work ships when its own integrated branch is accepted and must not hold up 1.3.0.
The former standalone classic “choose from library” proposal is not a newly confirmed independent task under this plan. Coordinate entry-point needs with the current workbench scope rather than automatically implementing the old candidate. Existing classic uploads are already durable; that is distinct from a new selection UI.
Actual remaining closeout
This status update records #1892's completed closure. It does not change any PR review state, merge, publish or deploy.
feat: integrate material library into main (#1896)
feat(storage): refuse generic remove and replace of rooted entries (0…
feat(materials): store uploads in the asset pool and read pool-first
feat(materials): backfill pre-pool uploads into the asset pool, opt-in
docs(materials): state how long the pool reader's fallback holds the …
feat(persistence): owner-level material extraction state and per-owne…
fix(persistence): key the owner extraction cache on endpoints and reu…
test(persistence): make the publication rollback case fail after the …
feat(materials): select several files, batch move and batch delete
wyuc commentedon Oct 29, 2026
@LING-6150 Release closeout facts for the remaining items:
c0f296aa36, release PR release: v1.3.0 #2088).v1.3.0→c0f296aa36. Knowledge-base findings resolved between rc.1 and GA:too_many_pageswith the counts; not retried.mainat or after856f473cpassed full QA, including the knowledge base, with no new regressions. Host-specific acceptance (identity mapping, byte store and parser wiring, old-result compatibility, cleanup, usage enforcement) is for the host owner to record here.Parked items are unchanged: #1875 batch operations and #1932 page links stay Draft per the 2026-10-22 decisions; long-document splitting is now tracked in #2084. Closing this tracking issue is your call once the host acceptance line is recorded.
LING-6150 commentedon Oct 30, 2026
@wyuc Thanks for the release facts. Recording host-owner validation for a downstream host with host-specific adaptations.
Selected upstream release: v1.3.0 (
c0f296aa36), based on the maintainer's release confirmation. The results below combine initial rollout checks and subsequent follow-up checks; they are not a full rerun of every check on the GA build.@, or through the toolbar picker. Direct cross-owner API access was not tested.read_materialtool output matched the registered image derivatives, with no external image URLs. This was checked for both an existing extraction and a newly uploaded sample; it is not a general PDF layout-fidelity claim.Coverage limits: No natural recoverable failure was available to test a successful Parse again and subsequent cross-entry consumption. Agent-initiated retry, retention after cancelled generation, old-session copy compatibility and non-restoration of previously deleted legacy materials were not independently tested. Total count/size limits were not filled. Migration/backfill execution was not repeated as part of these checks; deployment records remain the basis for those operations.
This records the verified host acceptance coverage and its limits. The previous follow-up gaps for over-24-hour retention, PDF figure verification and a pre-upgrade extraction sample are now covered. #1875 and #1932 remain parked as agreed.