Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(desktop): stop control and budget discipline for folder-zip walks (review)

Mf77e2ba65f6b
diff --git a/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts b/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts
index 02277cb53..a48f0cd4f 100644
--- a/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts
+++ b/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts
@@ -139,6 +139,10 @@ describe('createGfsFolderZip', () => {
expect(names.sort()).toEqual(['Docs/a.txt', 'Docs/b.png', 'Docs/sub/c.md'].sort())
expect(progress.map(value => value.phase)).toContain('downloading')
expect(progress.at(-1)?.phase).toBe('assembling')
+ // The "downloading N of M" copy is 1-based: file 1 reports filesAdded 1.
+ expect(
+ progress.filter(value => value.phase === 'downloading').map(value => value.filesAdded)
+ ).toEqual([1, 2, 3])
})
it('skips unreadable rows and 403 downloads with visible reasons', async () => {
@@ -303,6 +307,48 @@ describe('createGfsFolderZip', () => {
expect(attempts).toBe(2)
})
+ it('stops before the first request when the signal is aborted mid-wait (M3)', async () => {
+ const listChildren = vi.fn(async () => ({ items: [], nextCursor: null }))
+ const controller = new AbortController()
+ const deps: GfsFolderZipDeps = {
+ listChildren,
+ download: async () => ({ bytes: new ArrayBuffer(0) }),
+ // The first slot never frees: the walk parks here until the stop lands.
+ throttle: { acquire: () => new Promise<void>(() => undefined) },
+ sleep: async () => undefined,
+ }
+
+ const walk = createGfsFolderZip(
+ { resourceId: 'root', drive: 'main', name: 'Stopped' },
+ { deps, signal: controller.signal }
+ )
+ const expectation = expect(walk).rejects.toMatchObject({ name: 'AbortError' })
+ controller.abort()
+ await expectation
+ expect(listChildren).not.toHaveBeenCalled()
+ })
+
+ it('stops during a hung download instead of waiting out the request (M3)', async () => {
+ const controller = new AbortController()
+ const deps: GfsFolderZipDeps = {
+ listChildren: vi.fn(async () => ({
+ items: [folder({ resourceId: 'hung', name: 'hung.txt' })],
+ nextCursor: null,
+ })),
+ download: () => new Promise<{ bytes: ArrayBuffer }>(() => undefined),
+ throttle: { acquire: async () => undefined },
+ sleep: async () => undefined,
+ }
+
+ const walk = createGfsFolderZip(
+ { resourceId: 'root', drive: 'main', name: 'Stopped' },
+ { deps, signal: controller.signal }
+ )
+ const expectation = expect(walk).rejects.toMatchObject({ name: 'AbortError' })
+ controller.abort()
+ await expectation
+ })
+
it('aborts on a non-permission download failure instead of a holey archive', async () => {
const deps: GfsFolderZipDeps = {
listChildren: vi.fn(async () => ({
diff --git a/desktop-app/ui/src/lib/gfsFolderZip.ts b/desktop-app/ui/src/lib/gfsFolderZip.ts
index 393ffbeb1..66d428d67 100644
--- a/desktop-app/ui/src/lib/gfsFolderZip.ts
+++ b/desktop-app/ui/src/lib/gfsFolderZip.ts
@@ -115,6 +115,13 @@ export interface CreateGfsFolderZipOptions {
onProgress?: (progress: GfsFolderZipProgress) => void
limits?: { maxTotalBytes?: number; maxEntries?: number }
deps?: Partial<GfsFolderZipDeps>
+ /**
+ * Cooperative stop for a walk that can legally run for many minutes: every
+ * wait (throttle slot, 429 backoff, in-flight request) races the signal, and
+ * each loop turn re-checks it. Aborting rejects with a DOMException named
+ * `AbortError` (`isFolderZipAbortError`).
+ */
+ signal?: AbortSignal
}
export interface GfsZipFolderSource {
@@ -127,6 +134,15 @@ function toMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error)
}
+/** The user stopped the walk — not a failure, and never a save. */
+export function isFolderZipAbortError(error: unknown): boolean {
+ return error instanceof DOMException && error.name === 'AbortError'
+}
+
+function folderZipAbortedError(): DOMException {
+ return new DOMException('Folder-zip walk was stopped.', 'AbortError')
+}
+
/** A per-resource denial for THIS entry (403/forbidden), not a session failure. */
function isAccessDenied(message: string): boolean {
return parseHttpStatus(message) === 403 || message.toLowerCase().includes('forbidden')
@@ -173,6 +189,29 @@ export async function createGfsFolderZip(
const report = (progress: GfsFolderZipProgress) => options.onProgress?.(progress)
+ const signal = options.signal
+ const throwIfAborted = () => {
+ if (signal?.aborted) throw folderZipAbortedError()
+ }
+ // Rejects when the caller aborts; raced against every wait so a stop lands
+ // immediately instead of after the current throttle slot or backoff. The
+ // no-op catch keeps a late abort from becoming an unhandled rejection after
+ // the walk already finished.
+ const abortRejection = signal
+ ? new Promise<never>((_, reject) => {
+ signal.addEventListener(
+ 'abort',
+ () => {
+ reject(folderZipAbortedError())
+ },
+ { once: true }
+ )
+ })
+ : null
+ if (abortRejection) abortRejection.catch(() => undefined)
+ const withAbort = <T>(promise: Promise<T>): Promise<T> =>
+ abortRejection ? Promise.race([promise, abortRejection]) : promise
+
/**
* One 429 backs off by the server-provided hint and retries exactly once.
* The backoff window is NOT a throttle slot: after it elapses the retry
@@ -182,12 +221,13 @@ export async function createGfsFolderZip(
*/
const withRateLimitRetry = async <T>(operation: () => Promise<T>): Promise<T> => {
try {
- return await operation()
+ return await withAbort(operation())
} catch (error) {
+ if (isFolderZipAbortError(error)) throw error
const message = toMessage(error)
if (!isRateLimited(message)) throw error
- await sleep(Math.min((parseRetryAfterSeconds(message) ?? 15) * 1000, 120_000))
- await throttle.acquire()
+ await withAbort(sleep(Math.min((parseRetryAfterSeconds(message) ?? 15) * 1000, 120_000)))
+ await withAbort(throttle.acquire())
return operation()
}
}
@@ -203,12 +243,14 @@ export async function createGfsFolderZip(
// ── Phase 1: recursive listing (breadth-first, cursor-paginated). ──
report({ phase: 'listing', filesFound: 0, filesAdded: 0, currentPath: rootName })
while (queue.length) {
+ throwIfAborted()
const next = queue.shift()!
if (visitedFolders.has(next.resourceId)) continue
visitedFolders.add(next.resourceId)
let cursor: string | undefined
do {
- await throttle.acquire()
+ throwIfAborted()
+ await withAbort(throttle.acquire())
let page: GfsZipChildrenPage
try {
page = await withRateLimitRetry(() => listChildren(next.resourceId, folder.drive, cursor))
@@ -280,17 +322,20 @@ export async function createGfsFolderZip(
// ── Phase 2: throttled downloads, skipping per-resource denials. ──
let addedBytes = 0
for (const [index, file] of files.entries()) {
+ throwIfAborted()
+ // 1-based: the copy says "downloading N of M" while file N is fetched.
report({
phase: 'downloading',
filesFound: files.length,
- filesAdded: index,
+ filesAdded: index + 1,
currentPath: file.path,
})
- await throttle.acquire()
+ await withAbort(throttle.acquire())
let bytes: ArrayBuffer
try {
- bytes = (await withRateLimitRetry(() => download(file.uri))).bytes
+ bytes = (await withRateLimitRetry(() => withAbort(download(file.uri)))).bytes
} catch (error) {
+ if (isFolderZipAbortError(error)) throw error
const message = toMessage(error)
if (isAccessDenied(message)) {
skipped.push({ path: file.path, reason: 'Permission denied' })
diff --git a/desktop-app/ui/src/pages/FilesPage.tsx b/desktop-app/ui/src/pages/FilesPage.tsx
index 088b3e273..e4fe544ec 100644
--- a/desktop-app/ui/src/pages/FilesPage.tsx
+++ b/desktop-app/ui/src/pages/FilesPage.tsx
@@ -48,6 +48,7 @@ import {
type GfsFolderZipProgress,
createGfsFolderZip,
describeZipSkips,
+ isFolderZipAbortError,
} from '@lib/gfsFolderZip'
import {
describeGfsGrantError,
@@ -287,7 +288,10 @@ export function FilesPage({
folderName: string
progress: GfsFolderZipProgress
} | null>(null)
- const zipJobRef = useRef(false)
+ // Active job identity (folder name) + its stop handle. A ref, not state, so
+ // the prefetch effect can consult it without re-arming when a job starts.
+ const zipJobRef = useRef<string | null>(null)
+ const zipAbortRef = useRef<AbortController | null>(null)
const [draggingResourceId, setDraggingResourceId] = useState<string | null>(null)
const [dragOverFolderId, setDragOverFolderId] = useState<string | null>(null)
const [movingResourceId, setMovingResourceId] = useState<string | null>(null)
@@ -339,6 +343,10 @@ export function FilesPage({
// forever and never reach the rest.
useEffect(() => {
if (!sessionScope) return
+ // A running folder-zip walk holds the same per-actor read budget this
+ // prefetch spends; a burst here is one more 429 away from killing the
+ // job, so the warmer stays idle until the walk finishes (L9).
+ if (zipJobRef.current) return
const folders = items
.filter(item => item.kind === 'directory')
.map(folder => ({
@@ -812,13 +820,19 @@ export function FilesPage({
/**
* BUG-175 — recursive folder export as one zip archive, assembled in the
* renderer. The walk is throttled to the shared GFS read budget, refuses
- * over the size/entry ceilings with a clear message, and reports entries it
- * had to skip (no access / permission denied) in a visible notice after the
- * save so the archive's holes are never silent.
+ * over the size/entry ceilings with a clear message, can be stopped from the
+ * progress strip, and reports entries it had to skip (no access / permission
+ * denied) in a visible notice after the save so the archive's holes are
+ * never silent.
*/
const handleFolderZipDownload = async (folder: GfsDriveResource) => {
- if (zipJobRef.current) return
- zipJobRef.current = true
+ if (zipJobRef.current) {
+ pushToast?.(`Already preparing ${zipJobRef.current}.zip`, 'info')
+ return
+ }
+ zipJobRef.current = folder.name
+ const abortController = new AbortController()
+ zipAbortRef.current = abortController
const initialProgress: GfsFolderZipProgress = {
phase: 'listing',
filesFound: 0,
@@ -831,6 +845,7 @@ export function FilesPage({
{ resourceId: folder.resourceId, drive: folder.drive || GFS_DRIVE_MAIN, name: folder.name },
{
onProgress: progress => setZipJob({ folderName: folder.name, progress }),
+ signal: abortController.signal,
}
)
saveBytesToDisk(result.bytes, result.fileName)
@@ -842,7 +857,9 @@ export function FilesPage({
pushToast?.(describeZipSkips(result.skipped), 'warn', { durationMs: 10_000 })
}
} catch (zipError) {
- if (zipError instanceof GfsFolderZipEmptyError) {
+ if (isFolderZipAbortError(zipError)) {
+ pushToast?.(`Stopped preparing ${folder.name}.zip.`, 'info')
+ } else if (zipError instanceof GfsFolderZipEmptyError) {
pushToast?.(zipError.message, 'info')
if (zipError.skipped.length) {
pushToast?.(describeZipSkips(zipError.skipped), 'warn', { durationMs: 10_000 })
@@ -855,7 +872,8 @@ export function FilesPage({
pushToast?.(message, 'error')
}
} finally {
- zipJobRef.current = false
+ zipJobRef.current = null
+ zipAbortRef.current = null
setZipJob(null)
}
}
@@ -1626,6 +1644,14 @@ export function FilesPage({
? `Preparing ${zipJob.folderName}.zip — downloading ${zipJob.progress.filesAdded} of ${zipJob.progress.filesFound} ${zipJob.progress.filesFound === 1 ? 'file' : 'files'}…`
: `Preparing ${zipJob.folderName}.zip — assembling archive…`}
</span>
+ <button
+ type="button"
+ className="da-gfs-zip-progress__stop"
+ aria-label="Stop preparing zip"
+ onClick={() => zipAbortRef.current?.abort()}
+ >
+ Stop
+ </button>
</div>
) : null}
diff --git a/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx b/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
index d06966f51..806c41118 100644
--- a/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
+++ b/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
@@ -3496,6 +3496,193 @@ describe('FilesPage', () => {
expect(pushToast).toHaveBeenCalledWith('"Empty" has no downloadable files.', 'info')
})
+ it('stops a running folder zip from the progress strip without saving (M3)', async () => {
+ vi.useFakeTimers()
+ const listChildren = vi.fn(async () => ({
+ items: [
+ {
+ resourceId: 'doc-1',
+ rid: 'doc-1',
+ gfsUri: 'gfs://main/doc-1',
+ drive: 'main',
+ parentResourceId: 'folder-1',
+ name: 'plan.md',
+ kind: 'file' as const,
+ path: '/Assets/plan.md',
+ version: 0,
+ bytes: 4,
+ },
+ ],
+ nextCursor: null,
+ }))
+ const download = vi.fn(async () => ({ bytes: new Uint8Array([1, 2, 3, 4]).buffer }))
+ const pushToast = vi.fn()
+ const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: { gfs: { listChildren, download } },
+ })
+ const folderRow = {
+ resourceId: 'folder-1',
+ rid: 'folder-1',
+ gfsUri: 'gfs://main/folder-1',
+ drive: 'main',
+ parentResourceId: null,
+ name: 'Assets',
+ kind: 'directory' as const,
+ path: '/Assets',
+ version: 0,
+ bytes: 0,
+ sources: ['grant'],
+ permissions: ['read'],
+ coversDescendants: false,
+ }
+ hookMock.useGfsBrowserController.mockReturnValue({
+ ...baseController(),
+ accessibleResources: [folderRow],
+ })
+
+ renderFilesPage(pushToast)
+ await act(async () => {
+ fireEvent.click(screen.getByRole('button', { name: 'Options for Assets' }))
+ })
+ await act(async () => {
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Download as zip' }))
+ })
+
+ // The job is live with a visible stop affordance; use it before the
+ // throttled download slot frees, so nothing reaches the save path.
+ expect(screen.getByTestId('gfs-zip-progress')).toBeTruthy()
+ await act(async () => {
+ fireEvent.click(screen.getByRole('button', { name: 'Stop preparing zip' }))
+ await Promise.resolve()
+ })
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(5_000)
+ })
+ await act(async () => {
+ await Promise.resolve()
+ })
+
+ expect(screen.queryByTestId('gfs-zip-progress')).toBeNull()
+ expect(pushToast).toHaveBeenCalledWith('Stopped preparing Assets.zip.', 'info')
+ expect(pushToast).not.toHaveBeenCalledWith(expect.stringContaining('Downloaded'), 'success')
+ expect(click).not.toHaveBeenCalled()
+ })
+
+ it('tells the user a zip is already being prepared instead of ignoring the click (L7)', async () => {
+ vi.useFakeTimers()
+ // The listing never settles, so the first job stays in flight.
+ const listChildren = vi.fn(() => new Promise(() => undefined))
+ const pushToast = vi.fn()
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: { gfs: { listChildren, download: vi.fn() } },
+ })
+ hookMock.useGfsBrowserController.mockReturnValue({
+ ...baseController(),
+ accessibleResources: [
+ {
+ resourceId: 'folder-1',
+ rid: 'folder-1',
+ gfsUri: 'gfs://main/folder-1',
+ drive: 'main',
+ parentResourceId: null,
+ name: 'Assets',
+ kind: 'directory',
+ path: '/Assets',
+ version: 0,
+ bytes: 0,
+ sources: ['grant'],
+ permissions: ['read'],
+ coversDescendants: false,
+ },
+ ],
+ })
+
+ renderFilesPage(pushToast)
+ await act(async () => {
+ fireEvent.click(screen.getByRole('button', { name: 'Options for Assets' }))
+ })
+ await act(async () => {
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Download as zip' }))
+ })
+ await act(async () => {
+ fireEvent.click(screen.getByRole('button', { name: 'Options for Assets' }))
+ })
+ await act(async () => {
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Download as zip' }))
+ })
+
+ expect(pushToast).toHaveBeenCalledWith('Already preparing Assets.zip', 'info')
+ // One walk, not two: the second click never reached the listing plane.
+ expect(listChildren).toHaveBeenCalledTimes(1)
+ })
+
+ it('holds the folder prefetch while a folder zip is walking (L9)', async () => {
+ vi.useFakeTimers()
+ const listChildren = vi.fn((resourceId: string) => {
+ if (resourceId === 'folder-1') return new Promise(() => undefined) // walk parks in listing
+ throw new Error(`unexpected prefetch listing for ${resourceId}`)
+ })
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: { gfs: { listChildren } },
+ })
+ const row = (id: string, name: string) => ({
+ resourceId: id,
+ rid: id,
+ gfsUri: `gfs://main/${id}`,
+ drive: 'main',
+ parentResourceId: null,
+ name,
+ kind: 'directory' as const,
+ path: `/${name}`,
+ version: 0,
+ bytes: 0,
+ sources: ['grant'],
+ permissions: ['read'],
+ coversDescendants: false,
+ })
+ const controllerState = {
+ ...baseController(),
+ // Root view with a fresh (empty) folder listing: nothing to warm yet.
+ accessibleResources: [row('folder-1', 'Assets'), row('folder-p', 'PrefetchMe')],
+ }
+ hookMock.useGfsBrowserController.mockReturnValue(controllerState)
+
+ const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+ const makeElement = () => (
+ <QueryClientProvider client={queryClient}>
+ <FilesPage />
+ </QueryClientProvider>
+ )
+ const { rerender } = render(makeElement())
+
+ await act(async () => {
+ fireEvent.click(screen.getByRole('button', { name: 'Options for Assets' }))
+ })
+ await act(async () => {
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Download as zip' }))
+ await Promise.resolve()
+ })
+ expect(screen.getByTestId('gfs-zip-progress')).toBeTruthy()
+
+ // A folder's children land while the walk is still running: the prefetch
+ // effect re-runs, but must not spend the shared budget the walk holds.
+ hookMock.useGfsBrowserController.mockReturnValue({
+ ...controllerState,
+ items: [row('folder-p', 'PrefetchMe')],
+ })
+ await act(async () => {
+ rerender(makeElement())
+ })
+
+ expect(listChildren).toHaveBeenCalledTimes(1)
+ expect(listChildren).toHaveBeenCalledWith('folder-1', 'main', undefined)
+ expect(listChildren).not.toHaveBeenCalledWith('folder-p', 'main', undefined)
+ })
+
it('omits Download as zip for a folder the session cannot read', async () => {
hookMock.useGfsBrowserController.mockReturnValue({
...baseController(),
diff --git a/desktop-app/ui/src/styles.css b/desktop-app/ui/src/styles.css
index 390c3348e..32fbadc3d 100644
--- a/desktop-app/ui/src/styles.css
+++ b/desktop-app/ui/src/styles.css
@@ -15289,12 +15289,39 @@ pre {
}
.da-gfs-zip-progress__label {
+ flex: 1 1 auto;
min-width: 0;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
+.da-gfs-zip-progress__stop {
+ appearance: none;
+ flex: 0 0 auto;
+ align-self: center;
+ border: 1px solid rgba(var(--edge-rgb), 0.3);
+ border-radius: var(--radius-control);
+ background: transparent;
+ color: var(--text-dim);
+ font: inherit;
+ font-size: var(--font-size-xs);
+ line-height: 1;
+ padding: var(--space-1) var(--space-1-5);
+ cursor: pointer;
+ white-space: nowrap;
+}
+
+.da-gfs-zip-progress__stop:hover {
+ border-color: rgba(var(--danger-rgb), 0.5);
+ color: var(--danger);
+}
+
+.da-gfs-zip-progress__stop:focus-visible {
+ outline: 2px solid rgba(var(--focus-rgb), 0.56);
+ outline-offset: 1px;
+}
+
.da-gfs-zip-progress__label::before {
content: '';
flex: 0 0 auto;