feat(frontend): @agenta/entities/drive — the drive's headless layer leaves the app

web/packages/agenta-entities/package.json

@@ -65,18 +65,21 @@
         "./shared/openapi": "./src/shared/openapi/index.ts",
         "./shared/execution": "./src/shared/execution/index.ts",
         "./shared/execution/invocationErrors": "./src/shared/execution/invocationErrors.ts",
-        "./shared/invalidation": "./src/shared/invalidation/index.ts"
+        "./shared/invalidation": "./src/shared/invalidation/index.ts",
+        "./drive": "./src/drive/index.ts"
     },
     "dependencies": {
-        "@agentaai/api-client": "workspace:../agenta-api-client",
         "@agenta/sdk": "workspace:../agenta-sdk",
         "@agenta/shared": "workspace:../agenta-shared",
         "@agenta/ui": "workspace:../agenta-ui",
+        "@agentaai/api-client": "workspace:../agenta-api-client",
         "@tanstack/query-persist-client-core": "5.100.9",
         "fast-deep-equal": "^3.1.3",
         "jotai-scheduler": "^0.0.5",
         "lodash": "^4.17.23",
+        "motion": "^12.0.0",
         "openapi-json-schema": "^2.0.0",
+        "pdfjs-dist": "^4.10.38",
         "stable-hash": "^0.0.6",
         "uuid": "^11.1.1",
         "zod": "^4.3.6"

web/oss/src/components/Drives/agentDrive.ts → web/packages/agenta-entities/src/drive/agentDrive.ts

@@ -4,11 +4,11 @@
  * runner, so `null` covers both "backend not deployed yet" and "agent never ran": the App drive
  * row simply stays gated until a mount appears, and lights up by itself once one does.
  */
-import {queryAgentMounts, type Mount} from "@agenta/entities/session"
+import {projectIdAtom} from "@agenta/shared/state"
 import {atomFamily} from "jotai/utils"
 import {atomWithQuery} from "jotai-tanstack-query"
 
-import {projectIdAtom} from "@/oss/state/project"
+import {queryAgentMounts, type Mount} from "@agenta/entities/session"
 
 export const agentMountQueryFamily = atomFamily((artifactId: string) =>
     atomWithQuery<Mount | null>((get) => {

web/oss/src/components/Drives/configDrive.ts → web/packages/agenta-entities/src/drive/configDrive.ts

@@ -5,16 +5,10 @@
  * resolve the same session/artifact drive via {@link useConfigDrive} and share one drawer request
  * via {@link configFilesDrawerAtomFamily}, keyed by the edited revision.
  */
-import {isSessionFresh} from "@agenta/chat/state"
-import {workflowMolecule} from "@agenta/entities/workflow"
 import {atom, useAtomValue} from "jotai"
 import {atomFamily} from "jotai/utils"
 
-import {useChatScopeKey} from "@/oss/components/AgentChatSlice/state/scope"
-import {
-    activeSessionIdAtomFamily,
-    sessionsListAtomFamily,
-} from "@/oss/components/AgentChatSlice/state/sessions"
+import {workflowMolecule} from "@agenta/entities/workflow"
 
 import {type DroppedFile} from "./dropEntries"
 import {useSessionDriveSummary, type SessionDriveData} from "./useSessionDrive"
@@ -33,28 +27,28 @@ export const configFilesDrawerAtomFamily = atomFamily((_revisionId: string) =>
 )
 
 /**
- * The drive backing the config panel's Files region: the active conversation's cwd mount plus the
- * agent's durable folder (resolved from the edited revision's artifact). Resolves the session id
- * the same way the chat does — a stale active id (closed tab) falls back to the first open tab,
- * and a brand-new never-run tab holds the queries off until its first run.
+ * The drive backing the config panel's Files region: the conversation's cwd mount plus the
+ * agent's durable folder (resolved from the edited revision's artifact).
+ *
+ * The SESSION is the host's to resolve and is passed in — the desktop derives it from its open
+ * chat tabs (a stale active id falls back to the first open tab, a never-run tab resolves to
+ * none), a session-scoped surface already knows it. An empty id holds the queries off, which is
+ * the "open a conversation to browse them here" state.
  */
-export function useConfigDrive(revisionId?: string | null): {
+export function useConfigDrive(
+    revisionId?: string | null,
+    sessionId?: string | null,
+): {
     drive: SessionDriveData
     sessionId: string
     artifactId?: string
 } {
-    const scope = useChatScopeKey()
     const artifactId = useAtomValue(workflowMolecule.selectors.workflowId(revisionId ?? ""))
-    const sessions = useAtomValue(sessionsListAtomFamily(scope))
-    const rawActiveId = useAtomValue(activeSessionIdAtomFamily(scope))
-    const resolvedId = sessions.some((s) => s.id === rawActiveId)
-        ? rawActiveId
-        : (sessions[0]?.id ?? "")
-    const sessionId = resolvedId && !isSessionFresh(resolvedId) ? resolvedId : ""
+    const resolvedSessionId = sessionId ?? ""
 
     // Summary only: the config header/body show a count + the latest handful. The browse drawer
     // gets its own full drive, gated on open (see StorageSection), so the whole tree is never
     // fetched just to render this always-mounted section.
-    const drive = useSessionDriveSummary(sessionId, artifactId ?? undefined)
-    return {drive, sessionId, artifactId: artifactId ?? undefined}
+    const drive = useSessionDriveSummary(resolvedSessionId, artifactId ?? undefined)
+    return {drive, sessionId: resolvedSessionId, artifactId: artifactId ?? undefined}
 }

web/packages/agenta-entities/src/drive/driveFlags.ts

@@ -0,0 +1,8 @@
+import {getEnv} from "@agenta/shared"
+
+/**
+ * Agent file uploads. Default ON; only an explicit "false" disables it.
+ * Lives here rather than in the chat slice so the drive code carries no app-layer import.
+ */
+export const isAgentFileUploadsEnabled = (): boolean =>
+    (getEnv("NEXT_PUBLIC_AGENT_FILE_UPLOADS") || "").toLowerCase() !== "false"

web/packages/agenta-entities/src/drive/driveLabels.ts

@@ -0,0 +1,6 @@
+import {type Mount} from "@agenta/entities/session"
+
+/** Breadcrumb root label. Mount slugs are the RESERVED form (`__ag__<uuid5>__cwd`) — surface
+ * only the human tail ("cwd"), never the uuid (spec: raw ids stay out of labels). */
+export const driveRootLabel = (mount: Mount | null): string =>
+    mount?.slug?.split("__").filter(Boolean).pop() ?? "cwd"

web/oss/src/components/Drives/driveMedia.ts → web/packages/agenta-entities/src/drive/driveMedia.ts

@@ -6,18 +6,15 @@
  * through the authenticated client once (cached blob → object URL). BACKEND ASK: an inline
  * disposition (or real signed URLs) to let media stream natively.
  */
-import {useCallback, useEffect, useMemo, useState} from "react"
+import {useEffect, useMemo, useState} from "react"
 
-import {type Mount} from "@agenta/entities/session"
-import {App} from "antd"
+import {axios, getAgentaApiUrl, getAuthToken} from "@agenta/shared/api"
+import {projectIdAtom} from "@agenta/shared/state"
 import {useAtomValue} from "jotai"
 import {atomFamily} from "jotai/utils"
 import {atomWithQuery} from "jotai-tanstack-query"
 
-import axios from "@/oss/lib/api/assets/axiosConfig"
-import {getAgentaApiUrl} from "@/oss/lib/helpers/api"
-import {getJWT} from "@/oss/services/api"
-import {projectIdAtom} from "@/oss/state/project"
+import {type Mount} from "@agenta/entities/session"
 
 import {renderPdfFirstPage} from "./pdfThumb"
 
@@ -202,7 +199,7 @@ export async function uploadMountFile({
 
 /** Raw-bytes save of one file. Module-private on purpose: it reports failure as `false`, which every
  * call site used to drop on the floor — go through {@link useDriveFileDownload}, which reports it. */
-async function downloadMountFile({
+export async function downloadMountFile({
     mount,
     path,
     projectId,
@@ -225,31 +222,6 @@ async function downloadMountFile({
     return true
 }
 
-/** `download(mount, path)` for ONE drive file, reporting the outcome through the themed toast
- * (App.useApp, so it renders correctly in dark mode). THE way to trigger a single-file download:
- * {@link downloadMountFile} resolves `false` on failure, so a bare fire-and-forget call left a failed
- * click looking exactly like a successful one. Stable — safe to pass down to list items. */
-export function useDriveFileDownload(): (mount: Mount | null, path: string) => Promise<boolean> {
-    const {message} = App.useApp()
-    const projectId = useAtomValue(projectIdAtom)
-    return useCallback(
-        async (mount: Mount | null, path: string) => {
-            // `path` is mount-RELATIVE, so it alone doesn't identify a file: `agent-files/notes.md`
-            // and a cwd `notes.md` both arrive here as "notes.md" and would share a toast.
-            const key = `drive-download:${mount?.id ?? "none"}:${path}`
-            message.open({type: "loading", key, content: "Downloading…", duration: 0})
-            const ok = await downloadMountFile({mount, path, projectId})
-            message.open(
-                ok
-                    ? {type: "success", key, content: "Downloaded"}
-                    : {type: "error", key, content: "Download failed"},
-            )
-            return ok
-        },
-        [message, projectId],
-    )
-}
-
 /** Download the WHOLE drive as ONE zip ("download all") — spanning every mount the drive folds in
  * (cwd at the root, the agent's durable folder under `agent-files/`). The backend STREAMS the zip
  * (never buffered whole) and reads file bodies with bounded concurrency.
@@ -300,7 +272,7 @@ export async function downloadMountArchive({
             let writable: WritableFileStreamLike | null = null
             try {
                 writable = await handle.createWritable()
-                const jwt = await getJWT()
+                const jwt = await getAuthToken()
                 const url = `${getAgentaApiUrl()}/mounts/files/export?project_id=${encodeURIComponent(projectId)}`
                 const response = await fetch(url, {
                     method: "POST",

web/oss/src/components/Drives/driveRepo.ts → web/packages/agenta-entities/src/drive/driveRepo.ts

@@ -7,9 +7,10 @@
  * clone keeps objects in a packfile (zlib + deltas), impractical to unpack in the browser — so we
  * surface branch, remote and the HEAD short SHA, which are all plain text.
  */
-import {mountFileContentQueryFamily, type Mount} from "@agenta/entities/session"
 import {useAtomValue} from "jotai"
 
+import {mountFileContentQueryFamily, type Mount} from "@agenta/entities/session"
+
 const SHA_RE = /^[0-9a-f]{40}$/i
 
 export interface RepoHead {

web/oss/src/components/Drives/driveTypes.ts → web/packages/agenta-entities/src/drive/driveTypes.ts

@@ -10,3 +10,12 @@ export interface DriveId {
     label: string
     value: string
 }
+
+/** A file staged for upload but not yet committed to the drive. */
+export interface StagedTileItem {
+    id: string
+    name: string
+    file: File
+    /** Object URL for an image preview, else null (icon fallback). Owned by DriveExplorer. */
+    previewUrl: string | null
+}

web/packages/agenta-entities/src/drive/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Drive (agent files) — HEADLESS. Queries, tree building, uploads/downloads, drop parsing and the
+ * session/artifact resolution behind the config panel's Files region. Zero JSX and zero UI imports:
+ * rendering lives in `@agenta/entity-ui/drive`, and anything app-specific (which conversation,
+ * which markdown renderer, the bearer token) arrives as a parameter or a registration.
+ */
+export * from "./agentDrive"
+export * from "./configDrive"
+export * from "./driveFlags"
+export * from "./driveKeyboard"
+export * from "./driveKinds"
+export * from "./driveLabels"
+export * from "./driveMedia"
+export * from "./driveMotion"
+export * from "./driveRepo"
+export * from "./driveTree"
+export * from "./driveTreeView"
+export * from "./driveTypes"
+export * from "./dropEntries"
+export * from "./pdfThumb"
+export * from "./recentChange"
+export * from "./useDelayedTrue"
+export * from "./useDriveDrop"
+export * from "./useDriveFilters"
+export * from "./useDriveSelection"
+export * from "./useDriveTreeKeyboard"
+export * from "./useDriveTreePane"
+export * from "./useDriveTreeReveal"
+export * from "./useDriveTreeViewport"
+export * from "./useDriveUploads"
+export * from "./useImagePreviews"
+export * from "./useMountUpload"
+export * from "./useSessionDrive"
+export * from "./useTreeGroupScroll"

web/oss/src/components/Drives/useDriveUploads.ts → web/packages/agenta-entities/src/drive/useDriveUploads.ts

@@ -13,9 +13,8 @@ import {useCallback, useEffect, useMemo, useRef} from "react"
 
 import {type MountFile} from "@agenta/entities/session"
 
-import {isAgentFileUploadsEnabled} from "@/oss/components/AgentChatSlice/assets/constants"
-
-import {type StagedTileItem} from "./DrivePendingTiles"
+import {isAgentFileUploadsEnabled} from "./driveFlags"
+import {type StagedTileItem} from "./driveTypes"
 import {type DroppedFile} from "./dropEntries"
 import {useDriveDrop} from "./useDriveDrop"
 import {useImagePreviews} from "./useImagePreviews"

web/oss/src/components/Drives/useMountUpload.ts → web/packages/agenta-entities/src/drive/useMountUpload.ts

@@ -1,10 +1,10 @@
 import {useCallback, useEffect, useMemo, useRef, useState} from "react"
 
-import {type Mount} from "@agenta/entities/session"
+import {projectIdAtom} from "@agenta/shared/state"
 import {useAtomValue} from "jotai"
 import {queryClientAtom} from "jotai-tanstack-query"
 
-import {projectIdAtom} from "@/oss/state/project"
+import {type Mount} from "@agenta/entities/session"
 
 import {uploadMountFile} from "./driveMedia"
 import {type DroppedFile} from "./dropEntries"

web/oss/src/components/Drives/useSessionDrive.ts → web/packages/agenta-entities/src/drive/useSessionDrive.ts

@@ -1,5 +1,7 @@
 import {useCallback, useMemo} from "react"
 
+import {useAtomValue} from "jotai"
+
 import {
     latestMountFilesQueryFamily,
     mountFilesQueryFamily,
@@ -11,7 +13,6 @@ import {
     type Mount,
     type MountFile,
 } from "@agenta/entities/session"
-import {useAtomValue} from "jotai"
 
 import {agentMountQueryFamily} from "./agentDrive"
 import {cleanPath, driveFileStats, isInternalDrivePath, relativeTime} from "./driveTree"

web/oss/src/components/Drives/dropEntries.test.ts → web/packages/agenta-entities/tests/unit/dropEntries.test.ts

@@ -1,21 +1,19 @@
 import {beforeEach, describe, expect, it, vi} from "vitest"
 
-import axios from "@/oss/lib/api/assets/axiosConfig"
+import {axios} from "@agenta/shared/api"
 
-import {uploadMountFile} from "./driveMedia"
+import {uploadMountFile} from "../../src/drive/driveMedia"
 import {
     collectDropEntry,
     type DropEntry,
     type DropEntryReader,
     readDroppedFiles,
-} from "./dropEntries"
+} from "../../src/drive/dropEntries"
 
-vi.mock("@/oss/lib/api/assets/axiosConfig", () => ({
-    default: {post: vi.fn(), get: vi.fn()},
-}))
-
-vi.mock("@/oss/lib/helpers/api", () => ({
+vi.mock("@agenta/shared/api", () => ({
+    axios: {post: vi.fn(), get: vi.fn()},
     getAgentaApiUrl: vi.fn(() => "https://api.example.test"),
+    getAuthToken: vi.fn(async () => undefined),
 }))
 
 const file = (name: string) => new File([name], name, {type: "text/plain"})