@neuralis/brain-core 0.2.0 → 0.2.1

package/app/README.md

@@ -19,7 +19,7 @@ React surface contributed by `@neuralis/brain-core`: the Files widget, the `file
 
 - `installFilesystemHostComponents({ registry, port })` registers the lazy `FilesystemWidget` in the host `PackageHostRegistry` under `componentImport: '@neuralis/brain-core/app/filesystem'` and registers `FilesystemChangeCard` for the `filesystem.change` card type via `agent-core`'s chat card registry — WITH the card's height model (`estimateFilesystemChangeCardHeight`) AND its composer-aggregation contract (`FILESYSTEM_COMPOSER_CONTRACT` from `app/cards/diffUtils.ts`): brain-core OWNS how its card's activity reaches the composer's Changes tab and the post-stream summary (`tab: 'changes'` + the `extractFilesystemComposerChanges` paths/`version.diff` extractor); agent-core's aggregation surfaces iterate the card registry and carry zero filesystem literals. Both are module-level stable references (the registry's idempotency check compares identity). The widget is wrapped in `<PackageApiProvider slug="brain-core" projectId agentId userId>` so all internal API calls resolve through the kernel client.
 - The same install entry fills the host slot `workspace.provider:@neuralis/brain-core` with `<FilesystemPackageHost port={port}>`, which the host's provider root wraps around the workspace (registration order — after agent-core's fill, so inside it). It consumes the `WorkspaceHostPort` (active project/agent ids, agent map, file marks, event-stream URL builder) and exposes a `FilesystemHostValue` to every component below it. The `useBuildFilesystemHostValue` hook is the single adapter — the Files UI reads agents and file marks through that contract, never through host-specific imports.
-- `app/filesystem/api/` calls the brain-core package routes via `tryGetPackageApiImperativeAsync('brain-core')` (the `PackageApi` returned by the kernel client) — no direct `fetch` against `/api/packages/brain-core/*` from components.
+- `app/filesystem/api/` calls the brain-core package routes through a kernel `PackageApi` client each Files window passes (built over the window's project and bound agent) — no direct `fetch` against `/api/packages/brain-core/*` from components.
 
 ## Security & scope
 

package/app/filesystem/README.md

@@ -11,13 +11,13 @@ Files widget package — the React surface mounted by the host as the brain-core
 
 - `FilesystemWidget` — top-level component; takes `{ agentId, widgetId, state? }`. Mounted lazily by the host via `installFilesystemHostComponents`.
 - `FilesystemHostProvider`, `useFilesystemHost`, `getFilesystemHostImperative`, `FilesystemHostValue` — the host-injection contract.
-- `useFilesystemStore` and the `FileSystemState` shape — the Zustand store consumed by every component.
+- `useFilesystemStore` and the `FileSystemState` shape — the Files window's Zustand store, read through `FilesystemStoreProvider` (one store per window; see `store/README.md`).
 - `AgentInfo`, the `domain/types` re-export, the `lib/projectFiles` and `lib/agentUtils` helpers.
 - The `ui/` re-export bundle (14 symbols from `ui/index.ts`): `FilesystemWidget`, `FileTree`, `FileEditor`, `FileTab`, `FileMetaBar`, `CodeEditor` (CodeMirror 6 + Shiki editor), `ReviewDiffView` (`@codemirror/merge` review diff), `GitDiffView`, `GitFileDiff`, `GitCommitChangesView` (the Git Control diff surface — single-file and the multi-file stacked commit tab), `Toolbar`, `SourceTypeIcon`, `InlineUploader`, `PolicyEditor`. (`DiffView` — the old Myers review diff — was removed; the never-mounted `EditFileModal` / `UploadFileModal` were deleted 2026-09-04; the internal `EditorTabBar` / `DiffModeToggle` back `FileEditor`, and `PendingChangesPanel` is rendered by `FileEditor` rather than re-exported.)
 
 ## How it plugs into the package-system kernel
 
-- The widget runs inside `<PackageApiProvider slug="brain-core" projectId agentId userId>` (wired by `installFilesystemHostComponents`); every API call flows through the kernel `PackageApi` client, which translates calls into `/api/packages/brain-core/<route>` requests scoped to the active session.
+- Each window runs inside its own store (`FilesystemStoreProvider`, wired by `installFilesystemHostComponents`); every API call flows through that store's kernel `PackageApi` client — built over the window's project and bound agent — which translates calls into `/api/packages/brain-core/<route>` requests the route layer resolves to the real session.
 - `FilesystemHostProvider` is built on top of `WorkspaceHostPort`. The adapter (`host/buildFilesystemHostValue.ts`) is the single bridge between the kernel port and the brain-core view; the widget never imports host-specific symbols.
 - The SSE hook (`hooks/useFilesystemSSE.ts`) subscribes through `host.subscribeFilesystemEvents(agentId, projectId, …)`, which delegates to `WorkspaceHostPort.subscribeRealtime({ channel: 'filesystem', … })` — the ONE multiplexed `/api/events` hub, never a per-widget connection.
 
@@ -25,7 +25,7 @@ Files widget package — the React surface mounted by the host as the brain-core
 
 - API calls are scoped by the kernel session (`projectId`, `agentId`, `userId`) — the UI cannot forge a request for another project. The brain-core route layer enforces feature grants and source scope.
 - File marks (`useFileMarks(agentId)`) and the SSE event stream are per-agent. Cross-agent visibility requires the same feature grants enforced server-side.
-- The store evicts COLD rows above `FILES_LRU_HARD_CAP` (never a source root, an expanded folder, its ancestors, its direct children, or an open file) so the UI cannot accumulate unbounded data even when many sources stream events — and the dock broom empties it outright through the kernel port's `onClientStateReset`.
+- The store evicts COLD rows above `FILES_LRU_HARD_CAP` (never a source root, an expanded folder, its ancestors, its direct children, or an open file) so the UI cannot accumulate unbounded data even when many sources stream events — the cap is PER window store, so N mounted windows hold up to N × the cap — and the dock broom empties the windows it scopes through the kernel port's `onClientStateReset`.
 
 ## Add Source — key suggestion
 

package/app/filesystem/api/README.md

@@ -4,7 +4,7 @@ Typed client for brain-core package routes plus a small set of host-side helpers
 
 ## Responsibility
 
-- Wrap the kernel `PackageApi` (`tryGetPackageApiImperativeAsync('brain-core')`) into typed functions that mirror every brain-core route.
+- Wrap a kernel `PackageApi` into typed functions that mirror every brain-core route; each takes that client as its LAST argument.
 - Build raw-file URLs (`getRawFileUrl`) for the `<img>` / `<video>` preview elements. **Not for an iframe or any other document embed** — the byte lane serves the executable document class (SVG, HTML, XML) as `content-disposition: attachment`, so a document embed against it renders nothing, and making it render again would re-open a stored-XSS path. There is exactly one call site today (`FileEditor`).
 - Provide the host-side helpers (`projectPackages.ts`) used by the Packages tab — these talk to the host's `/api/packages/runtime` and `/api/projects/:id/packages/:slug/{build,trust}` routes, NOT to brain-core.
 
@@ -18,7 +18,7 @@ Typed client for brain-core package routes plus a small set of host-side helpers
 
 ## How it plugs into the package-system kernel
 
-- All filesystem calls go through `tryGetPackageApiImperativeAsync('brain-core')` — the kernel resolves the `PackageApi` lazily so callers invoked at mount time don't race the `PackageApiProvider` registration.
+- A Files window passes the client its store was created with — `createPackageApi` over the window's project and BOUND agent — so the X-Project-Id / X-Agent-Id headers are the window's own, fixed before any await, whatever other window is mounted beside it; a body may still name another agent (a file read through its writing agent). `readFiles` alone also runs without a client, for the chat change card, which is not a Files window and resolves the first registered `brain-core` provider.
 - The `PackageApi` provided by `@neuralis/package-system/client` translates `.get(path, qs)`, `.post(path, body)`, `.patch`, `.del`, `.upload` into authenticated requests against `/api/packages/brain-core/<path>` with the active session attached by the host.
 - Project-package helpers go directly to host routes (`/api/packages/runtime`, `/api/projects/:id/packages/:slug/build`, `/.../trust`) — these are NOT package routes and are not part of the brain-core surface; the helpers live here only because the Files widget's Packages tab consumes them.
 
@@ -34,4 +34,4 @@ Typed client for brain-core package routes plus a small set of host-side helpers
 
 ## Tests
 
-Indirect coverage through the route tests under `test/routes/`. UI-side store interactions exercise these clients via mocked `PackageApi`.
+Indirect coverage through the route tests under `test/routes/`. `test/ui/gitApi.repo.test.ts` and `test/ui/searchApi.wire.test.ts` pass a mocked `PackageApi` as the client and pin the wire shape; `test/store/filesWindows.test.ts` pins that each window's requests carry its own client and headers.