@hachej/boring-files 0.2.0 → 0.2.2

package/dist/revision.js

@@ -1,5 +1,5 @@
 import { createResourceClient } from './remote.js';
-import { binding, bindingHeader, bindingValue, catalogHeader, filePage, record, savedRevisions } from './revision-protocol.js';
+import { binding, bindingHeader, bindingValue, catalogHeader, changeEvent, filePage, record, savedRevisions, serverEvents } from './revision-protocol.js';
 import { readJsonBody } from './request-guard.js';
 import { RevisionError } from './revision-contracts.js';
 import { observe } from './remote-protocol.js';
@@ -45,6 +45,93 @@ export async function connectRevisionProvider(options) {
             throw new RevisionError('denied', 'The response belongs to another workspace');
         return result.value;
     }
+    /** One feed across reconnections: each resumes after the last seq delivered; a refused binding ends it. */
+    async function* changes(request = {}) {
+        const signal = request.signal;
+        let cursor = request.since, incarnation = request.incarnation, staged, delay = 500;
+        const pause = () => new Promise(resolve => {
+            const timer = setTimeout(done, delay);
+            function done() { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); }
+            signal?.addEventListener('abort', done, { once: true });
+            delay = Math.min(delay * 2, 30_000);
+        });
+        while (!signal?.aborted) {
+            const url = new URL(endpoint);
+            url.searchParams.set('op', 'changes');
+            if (cursor !== undefined) {
+                url.searchParams.set('since', String(cursor));
+                if (incarnation !== undefined)
+                    url.searchParams.set('incarnation', incarnation);
+            }
+            const connection = new AbortController();
+            const stop = () => connection.abort();
+            signal?.addEventListener('abort', stop, { once: true });
+            try {
+                let response;
+                try {
+                    response = await fetch(new Request(url, { method: 'GET', redirect: 'error', headers: { accept: 'text/event-stream', [bindingHeader]: bound }, signal: connection.signal }));
+                }
+                catch {
+                    if (signal?.aborted)
+                        return;
+                    await pause();
+                    continue;
+                }
+                if (response.redirected || !response.ok || !response.body) {
+                    void response.body?.cancel().catch(() => { });
+                    if (response.status === 403 || response.status === 409)
+                        throw new RevisionError('denied', 'The selected workspace is unavailable or no longer authorized');
+                    if (response.status === 400)
+                        throw new RevisionError('invalid', 'The change feed request was refused');
+                    await pause();
+                    continue;
+                }
+                try {
+                    for await (const message of serverEvents(response.body)) {
+                        if (message.event === 'ready') {
+                            const ready = record(JSON.parse(message.data)), seq = ready.seq;
+                            // A new provider lifetime is adopted with its resnapshot, not with `ready`: a disconnect in between must reconnect with the
+                            // old cursor and incarnation, which the server answers with a resnapshot again.
+                            if (typeof ready.incarnation === 'string') {
+                                if (cursor === undefined || incarnation === undefined)
+                                    incarnation = ready.incarnation;
+                                else
+                                    staged = ready.incarnation;
+                            }
+                            if (cursor === undefined && typeof seq === 'number' && Number.isSafeInteger(seq))
+                                cursor = seq;
+                            delay = 500;
+                            continue;
+                        }
+                        if (message.event !== 'change' && message.event !== 'resnapshot')
+                            continue;
+                        const event = changeEvent(JSON.parse(message.data));
+                        if (event.kind === 'change' && cursor !== undefined && event.seq <= cursor)
+                            continue;
+                        if (event.kind === 'resnapshot' && staged !== undefined) {
+                            incarnation = staged;
+                            staged = undefined;
+                        }
+                        cursor = event.seq;
+                        yield event;
+                    }
+                }
+                catch (error) {
+                    if (signal?.aborted)
+                        return;
+                    if (error instanceof RevisionError && error.kind === 'invalid')
+                        throw error;
+                }
+            }
+            finally {
+                signal?.removeEventListener('abort', stop);
+                connection.abort();
+            }
+            if (signal?.aborted)
+                return;
+            await pause();
+        }
+    }
     if (!client.publish || !client.lookup)
         throw new Error('Publishing client lacks reconciliation');
     return {
@@ -53,5 +140,6 @@ export async function connectRevisionProvider(options) {
         list: async (request, signal) => filePage(await invoke('list', request, signal)),
         search: async (request, signal) => filePage(await invoke('search', request, signal)),
         history: async (path, signal) => savedRevisions(await invoke('history', path, signal)),
+        changes: request => changes(request),
     };
 }

package/dist/sqlite-batch.d.ts

@@ -10,6 +10,9 @@ export interface SqliteBatch {
     readonly bytes: (path: string) => Uint8Array | null | undefined;
     /** Write a regular file at an absolute path, creating its missing parent directories. Throws a Pi `FileError` on failure. */
     readonly write: (path: string, bytes: Uint8Array) => void;
+    /** The one byte limit of this file system: native writes and publications both enforce it. */
+    readonly maxFileBytes: () => number;
+    readonly setMaxFileBytes: (limit: number) => void;
 }
 export declare const registerSqliteBatch: (fs: object, batch: SqliteBatch) => void;
 export declare const sqliteBatchOf: (fs: object) => SqliteBatch | undefined;

package/dist/sqlite-filesystem.d.ts

@@ -7,6 +7,8 @@ export interface SqliteFileSystemOptions {
     readonly workspace: string;
     /** The absolute working directory, created when missing (for example `/workspace`). Relative paths resolve against `cwd`. */
     readonly cwd: string;
+    /** The largest file a write may store (default `SQLITE_MAX_FILE_BYTES`, the row limit of a Durable Object). A larger write fails with `EFBIG`. */
+    readonly maxFileBytes?: number;
 }
 /** A Pi `FileSystem` plus the incarnation of its rows: new when the workspace was first created in this database. */
 export interface SqliteFileSystem extends FileSystem {

package/dist/sqlite-filesystem.js

@@ -1,4 +1,5 @@
 import { FileError, LineScanner, err, ok } from '@earendil-works/pi-durable/env';
+import { SQLITE_MAX_FILE_BYTES, assertLimit, fileTooLarge } from './file-limits.js';
 import { randomUUID } from './platform.js';
 import { registerSqliteBatch } from './sqlite-batch.js';
 function normalize(path) {
@@ -20,7 +21,10 @@ const within = (base, path) => path === base || path.startsWith(base === '/' ? '
 // system answers exactly like Pi's environments.
 const fileError = (code, message, path) => new FileError(code, message, path);
 const isFileError = (error) => error instanceof FileError;
-/** How often a watcher compares snapshots: SQLite reports no changes, so the watcher polls (`mode: 'polling'`). */
+/**
+ * How often a watcher compares snapshots. A write through this file system (this connection) is compared at once, right after
+ * its transaction; polling remains for writes through another connection to the same database (`mode: 'polling'`).
+ */
 const WATCH_INTERVAL_MS = 1000;
 /** A FileError whose message starts with the POSIX code, as shells and Git read it. */
 const failure = (code, errno, path, what) => fileError(code, `${errno}: ${what}, '${path}'`, path);
@@ -32,6 +36,8 @@ export function openSqliteFileSystem(options) {
     if (typeof options.cwd !== 'string' || !options.cwd.startsWith('/'))
         throw new TypeError('An absolute working directory is required');
     const now = () => Date.now();
+    let maxFileBytes = options.maxFileBytes ?? SQLITE_MAX_FILE_BYTES;
+    assertLimit(maxFileBytes);
     function row(path) {
         if (path === '/')
             return { kind: 'directory', size: 0, mtime: 0 };
@@ -65,20 +71,29 @@ export function openSqliteFileSystem(options) {
         if (found.kind !== 'directory')
             throw failure('not_directory', 'ENOTDIR', path, 'not a directory');
     }
+    /** Paths written, renamed or removed by this file system since the last comparison: reported as changed even when size and time look alike. */
+    const touched = new Set();
     function bytes(path) {
-        if (existing(path).kind === 'directory')
+        const entry = existing(path);
+        if (entry.kind === 'directory')
             throw failure('is_directory', 'EISDIR', path, 'illegal operation on a directory');
         const found = db.get('SELECT bytes FROM boring_workspace_files WHERE workspace = ? AND path = ?', workspace, path);
+        // A zero-length BLOB can come back as no bytes (a NULL pointer through some engines): a file row with no bytes is an empty file.
+        if (found?.bytes === null && entry.kind === 'file')
+            return new Uint8Array();
         if (!(found?.bytes instanceof Uint8Array))
             throw fileError('unknown', 'Invalid stored bytes', path);
         return Uint8Array.from(found.bytes);
     }
     function put(path, kind, content) {
+        touched.add(path);
         db.run('INSERT INTO boring_workspace_files (workspace, path, parent, kind, bytes, mtime_ms) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(workspace, path) DO UPDATE SET kind = excluded.kind, bytes = excluded.bytes, mtime_ms = excluded.mtime_ms', workspace, path, dirname(path), kind, content, now());
     }
     function write(path, content) {
         if (path === '/')
             throw failure('is_directory', 'EISDIR', path, 'illegal operation on a directory');
+        if (content.length > maxFileBytes)
+            throw fileTooLarge(path, content.length, maxFileBytes);
         const found = row(path);
         if (found?.kind === 'directory')
             throw failure('is_directory', 'EISDIR', path, 'illegal operation on a directory');
@@ -125,13 +140,31 @@ export function openSqliteFileSystem(options) {
     const incarnation = db.get('SELECT incarnation FROM boring_workspaces WHERE workspace = ?', workspace)?.incarnation;
     if (typeof incarnation !== 'string')
         throw new Error('The workspace has no incarnation');
+    /** Each open watcher's comparison, run right after a write through this file system commits. */
+    const watchers = new Set();
+    let notifying = false;
+    function notify() {
+        if (watchers.size === 0) {
+            touched.clear();
+            return;
+        }
+        if (notifying)
+            return;
+        notifying = true;
+        // After the current synchronous work: a batch write inside a caller's transaction is compared once it has committed.
+        queueMicrotask(() => { notifying = false; const paths = [...touched]; touched.clear(); for (const check of [...watchers])
+            check(paths); });
+    }
     async function run(path, context, mode, work) {
         if (context.abortSignal?.aborted)
             return err(fileError('aborted', 'Operation aborted', path));
         if (typeof path !== 'string' || path.includes('\0'))
             return err(fileError('invalid', 'Invalid path', String(path)));
         try {
-            return ok(db.transaction(mode, () => work(normalize(path.startsWith('/') ? path : `${fs.cwd}/${path}`))));
+            const value = db.transaction(mode, () => work(normalize(path.startsWith('/') ? path : `${fs.cwd}/${path}`)));
+            if (mode === 'write')
+                notify();
+            return ok(value);
         }
         catch (error) {
             return err(isFileError(error) ? error : fileError('unknown', error instanceof Error ? error.message : String(error), path));
@@ -244,6 +277,9 @@ export function openSqliteFileSystem(options) {
             const added = encode(content);
             if (!row(absolute))
                 return write(absolute, added);
+            const grown = existing(absolute).size + added.length;
+            if (grown > maxFileBytes)
+                throw fileTooLarge(absolute, grown, maxFileBytes);
             const before = bytes(absolute), joined = new Uint8Array(before.length + added.length);
             joined.set(before);
             joined.set(added, before.length);
@@ -252,6 +288,9 @@ export function openSqliteFileSystem(options) {
         truncateFile: (path, size, context) => run(path, context, 'write', absolute => {
             if (!Number.isSafeInteger(size) || size < 0)
                 throw fileError('invalid', 'File size must be a non-negative safe integer', absolute);
+            // Checked before the buffer is allocated: a huge size is a size refusal, not an allocation failure.
+            if (size > maxFileBytes)
+                throw fileTooLarge(absolute, size, maxFileBytes);
             const before = bytes(absolute), after = new Uint8Array(size);
             after.set(before.subarray(0, size));
             write(absolute, after);
@@ -264,6 +303,12 @@ export function openSqliteFileSystem(options) {
             const moved = existing(from);
             if (from === to)
                 return;
+            // A moved file keeps its bytes, so a file (or a file below a moved directory) over the limit cannot replace another file by renaming.
+            const oversized = db.get(`SELECT path, length(bytes) AS size FROM boring_workspace_files WHERE ${subtree(from)} AND kind = 'file' AND length(bytes) > ? LIMIT 1`, ...subtreeArgs(from), maxFileBytes);
+            if (oversized)
+                throw fileTooLarge(oversized.path, Number(oversized.size), maxFileBytes);
+            touched.add(from);
+            touched.add(to);
             if (from === '/' || within(from, to))
                 throw failure('invalid', 'EINVAL', to, 'cannot move a directory into itself');
             const target = row(to);
@@ -306,8 +351,9 @@ export function openSqliteFileSystem(options) {
             };
             return reader;
         }),
-        // SQLite reports no changes, so the watcher compares snapshots of the watched rows. The first snapshot is taken before the
-        // watcher is returned, so a change made after `watch` resolves is always seen.
+        // SQLite reports no changes, so the watcher compares snapshots of the watched rows: at once after each write through this file
+        // system, and every second for other connections. The first snapshot is taken before the watcher is returned, so a change made
+        // after `watch` resolves is always seen.
         watch: async (targets, onChange, context) => {
             if (context.abortSignal?.aborted)
                 return err(fileError('aborted', 'Operation aborted'));
@@ -326,7 +372,18 @@ export function openSqliteFileSystem(options) {
                     onChange(change);
                 }
                 catch { /* the host's callback cannot stop the watcher */ } };
-            const timer = setInterval(() => {
+            const hidden = (name, target) => (target.exclude?.hidden && name.startsWith('.')) || target.exclude?.names?.includes(name);
+            /** Whether a path this file system just wrote lies under a watched target, as the snapshot would have listed it. */
+            const covered = (path) => targets.some(target => {
+                const root = normalize(target.path.startsWith('/') ? target.path : `${fs.cwd}/${target.path}`);
+                if (path === root)
+                    return true;
+                if (!within(root, path))
+                    return false;
+                const names = path.slice(root.length + (root === '/' ? 0 : 1)).split('/');
+                return (target.recursive || names.length === 1) && !names.some(name => hidden(name, target));
+            });
+            const check = (direct = []) => {
                 if (stopped)
                     return;
                 let next;
@@ -335,16 +392,19 @@ export function openSqliteFileSystem(options) {
                 }
                 catch (error) {
                     report({ error: isFileError(error) ? error : fileError('unknown', String(error)) });
-                    stopped = true;
-                    clearInterval(timer);
+                    stop();
                     return;
                 }
-                const changed = [...new Set([...previous.keys(), ...next.keys()])].filter(path => previous.get(path) !== next.get(path));
+                const written = new Set(direct.filter(covered));
+                const changed = [...new Set([...previous.keys(), ...next.keys(), ...written])].filter(path => written.has(path) || previous.get(path) !== next.get(path));
                 previous = next;
                 if (changed.length)
                     report({ paths: changed });
-            }, WATCH_INTERVAL_MS);
-            const watcher = { mode: 'polling', close: async () => { stopped = true; clearInterval(timer); } };
+            };
+            const timer = setInterval(() => check(), WATCH_INTERVAL_MS);
+            const stop = () => { stopped = true; clearInterval(timer); watchers.delete(check); };
+            watchers.add(check);
+            const watcher = { mode: 'polling', close: async () => { stop(); } };
             return ok(watcher);
         },
         canonicalPath: (path, context) => run(path, context, 'read', absolute => { existing(absolute); return absolute; }),
@@ -366,6 +426,7 @@ export function openSqliteFileSystem(options) {
                 throw failure('permission_denied', 'EPERM', absolute, 'the workspace root cannot be removed');
             if (found.kind === 'directory' && !options?.recursive && children(absolute).length)
                 throw failure('invalid', 'ENOTEMPTY', absolute, 'directory not empty');
+            touched.add(absolute);
             db.run(`DELETE FROM boring_workspace_files WHERE ${subtree(absolute)}`, ...subtreeArgs(absolute));
         }),
         createTempDir: (prefix, context) => temporary(prefix ?? 'tmp-', '', 'directory', context),
@@ -374,8 +435,10 @@ export function openSqliteFileSystem(options) {
     };
     registerSqliteBatch(fs, {
         connection: db,
+        maxFileBytes: () => maxFileBytes,
+        setMaxFileBytes: limit => { assertLimit(limit); maxFileBytes = limit; },
         bytes: path => { const found = row(normalize(path)); return !found ? null : found.kind === 'directory' ? undefined : bytes(normalize(path)); },
-        write: (path, content) => { const absolute = normalize(path); makeDirectory(dirname(absolute), true); write(absolute, content); },
+        write: (path, content) => { const absolute = normalize(path); makeDirectory(dirname(absolute), true); write(absolute, content); notify(); },
     });
     return fs;
 }

package/dist/workspace-catalog.js

@@ -1,9 +1,13 @@
 import ignore from 'ignore';
 import { identifier, locator } from './publication-input.js';
+import { HIDDEN_NAMES, isTemporary } from './file-types.js';
 import { RevisionError } from './revision-contracts.js';
-const hidden = new Set(['.git', '.boring', 'node_modules', 'dist', 'build', '.cache', '.next', 'coverage', '__pycache__']);
-const temporary = /^\.boring-[0-9a-f-]{36}\.tmp$/;
 const inside = (root, path) => path === root || path.startsWith(root === '/' ? '/' : `${root}/`);
+/** Basename first: a name that starts with the query, then one that contains it, then a match in the directories only. */
+const rank = (path, query) => {
+    const name = path.slice(path.lastIndexOf('/') + 1).toLowerCase();
+    return name.startsWith(query) ? '0' : name.includes(query) ? '1' : '2';
+};
 export function catalogPath(path, allowRoot = false) {
     if (allowRoot && path === '')
         return path;
@@ -47,10 +51,10 @@ export function createWorkspaceCatalog(options) {
     }
     function visible(entry, rules) {
         const name = entry.path.slice(entry.path.lastIndexOf('/') + 1);
-        if (temporary.test(name))
+        if (isTemporary(name))
             return false;
         if (config.defaults !== false) {
-            if (hidden.has(name))
+            if (HIDDEN_NAMES.has(name))
                 return false;
             let ignored = false;
             for (const rule of rules) {
@@ -111,7 +115,15 @@ export function createWorkspaceCatalog(options) {
             return entries;
         return entries.filter(entry => entry.path.slice(0, entry.path.lastIndexOf('/') + 1) === (directory ? `${directory}/` : ''));
     }
-    function page(entries, key, cursor, limit) {
+    // One traversal at a time, each started after its search was called: a search never reuses a walk that began before it, so its
+    // result reflects every change made before the call, and no two walks overlap.
+    let walking = Promise.resolve();
+    function files(access) {
+        const run = walking.then(() => collect('', true, access));
+        walking = run.then(() => undefined, () => undefined);
+        return run.then(entries => entries.filter(entry => entry.kind === 'file'));
+    }
+    function page(entries, key, cursor, limit, order) {
         const count = limit ?? 100;
         if (!Number.isSafeInteger(count) || count < 1 || count > 500)
             throw new RevisionError('invalid', 'Page limit must be between 1 and 500');
@@ -121,15 +133,15 @@ export function createWorkspaceCatalog(options) {
                 const value = JSON.parse(decodeURIComponent(cursor));
                 if (!Array.isArray(value) || value.length !== 2 || value[0] !== key || typeof value[1] !== 'string')
                     throw new Error();
-                after = catalogPath(value[1]);
+                after = order ? value[1] : catalogPath(value[1]);
             }
             catch {
                 throw new RevisionError('invalid', 'Invalid catalog cursor');
             }
         }
-        const sorted = entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0).filter(entry => entry.path > after);
+        const sorted = entries.map(entry => ({ entry, sort: order ? order(entry) : entry.path })).sort((a, b) => a.sort < b.sort ? -1 : a.sort > b.sort ? 1 : 0).filter(item => item.sort > after);
         const selected = sorted.slice(0, count), last = selected.at(-1);
-        return { entries: selected, ...(last && sorted.length > count ? { cursor: encodeURIComponent(JSON.stringify([key, last.path])) } : {}) };
+        return { entries: selected.map(item => item.entry), ...(last && sorted.length > count ? { cursor: encodeURIComponent(JSON.stringify([key, last.sort])) } : {}) };
     }
     return {
         list: async (request, access) => {
@@ -140,7 +152,8 @@ export function createWorkspaceCatalog(options) {
             if (typeof request.query !== 'string' || request.query.length > 1024)
                 throw new RevisionError('invalid', 'Invalid filename query');
             const query = request.query.toLowerCase();
-            return page((await collect('', true, access)).filter(entry => entry.kind === 'file' && entry.path.toLowerCase().includes(query)), `search:${query}`, request.cursor, request.limit);
+            const matches = (await files(access)).filter(entry => entry.path.toLowerCase().includes(query));
+            return page(matches, `search:${query}`, request.cursor, request.limit, entry => rank(entry.path, query) + entry.path);
         },
         history: async (path, access) => { check(access); identifier(access.scopeId); return options.saves(catalogPath(path)); },
     };

package/dist/workspace.d.ts

@@ -1,16 +1,33 @@
 import type { FileSystem } from '@earendil-works/pi-durable/env';
 import type { PublicationLookupResult, PublicationResult, ReadResult, ResourceAccess, ResourceProvider } from './contracts.js';
 import type { WorkspaceCatalogOptions } from './workspace-catalog.js';
-import type { WorkspaceCatalog } from './revision-contracts.js';
+import type { ChangeFeedRequest, WorkspaceCatalog, WorkspaceChangeEvent } from './revision-contracts.js';
+export type { ChangeFeedRequest, WorkspaceChangeEvent } from './revision-contracts.js';
 export type { WorkspaceCatalogOptions } from './workspace-catalog.js';
-import type { WorkspaceJournal } from './journal.js';
+import type { HistorySource, WorkspaceJournal } from './journal.js';
+export { isTemporary } from './file-types.js';
 import type { WorkspaceKey } from './workspace-identity.js';
 export type { WorkspaceKey } from './workspace-identity.js';
 export interface WorkspaceChange {
     readonly path: string;
-    /** `null` when the file is absent. */
+    /** `null` when the file is absent (or, from a watcher, when the path is a directory). */
     readonly revision: string | null;
-    readonly source: 'provider' | 'poll';
+    /** `publish`: a conditional write. `agent`: `record` (a Pi `write` or `edit`). `poll`: found by hashing. `watch`: the file system reported it. */
+    readonly source: 'publish' | 'agent' | 'poll' | 'watch';
+}
+/** What `record` is told about an agent write (ruling 2: observed, never receipted). */
+export interface AgentWrite {
+    readonly path: string;
+    /** The file before the write, when it existed: its revision and the bytes of that revision (kept in history as the replaced version). */
+    readonly before?: {
+        readonly revision: string;
+        readonly bytes: Uint8Array;
+    } | null | undefined;
+    /** The revision the write produced, as the caller observed it right after. */
+    readonly after: string;
+    readonly source: 'agent';
+    /** The Pi conversation that wrote it, carried on the change event. */
+    readonly conversationId?: string | undefined;
 }
 /** Runs one piece of work at a time, in order. A failed piece does not stop the ones behind it. */
 export interface WorkspaceQueue {
@@ -27,29 +44,70 @@ export interface WorkspaceResourceProvider extends ResourceProvider {
     };
     /** The workspace's mutation queue. Native tool calls that must not interleave with a conditional write run through it. */
     readonly queue: WorkspaceQueue;
+    /**
+     * Record a write the agent already made through the native tools (Pi `write`/`edit`, called by the file guard right after the
+     * tool succeeded): the file's history gains the written revision (source `agent`, and the replaced one when `before` carries its
+     * bytes) and the change feed an `agent` event. It writes history rows only: no publish, no receipt, no operation or intent rows,
+     * so agent writes are observed, not published. It does not enter `queue` (the guard already runs inside it), so it is safe to call from queued work.
+     * When the bytes there no longer have the `after` revision (a shell wrote in between), only the change event is recorded.
+     */
+    readonly record: (write: AgentWrite, access: ResourceAccess) => Promise<void>;
+    /**
+     * The change feed: every write this provider makes or records, every change `poll` finds and, while someone is listening, every
+     * change the file system's `watch` reports (the SQLite file system reports its own connection's writes at once). Ordered by
+     * `seq` and replayable from `since` within a bounded window; a gap yields a `resnapshot` event. The iterator ends when
+     * `request.signal` or `access.signal` aborts, or the provider closes. Events are invalidation hints: read the bytes again.
+     *
+     * After the last listener leaves, the watcher stays open for `watchLingerMs` and then closes. Changes made while no watcher was
+     * open are unknown, so the first listener afterwards makes the feed append a `resnapshot`: a client that reconnects after a
+     * longer absence reloads everything once, and one that stays connected is never affected.
+     */
+    readonly changes: (request: ChangeFeedRequest, access: ResourceAccess) => AsyncIterable<WorkspaceChangeEvent>;
+    /** The seq of the newest change event (the cursor of "now" for `changes({ since })`). */
+    readonly changeHead: () => number;
+    /** Names this provider's lifetime; a cursor from another one (`ChangeFeedRequest.incarnation`) is answered with a `resnapshot`. */
+    readonly changeIncarnation: string;
+    /** Ends every change stream, closes the file watcher and drops the change listeners. Idempotent; the provider still reads and publishes. */
+    readonly close: () => void;
+    /** Aborts when the provider closes, so a change stream nobody is reading still ends and releases its lease. */
+    readonly lifetime: AbortSignal;
     /** Revisions still retained for a file, newest first. */
     readonly history: (path: string) => string[];
     /** The same revisions with the time each was saved (milliseconds since the epoch; 0 when unknown), newest first. */
     readonly saves: (path: string) => {
         readonly revision: string;
         readonly savedAt: number;
+        readonly source: HistorySource;
     }[];
     /** Read the file as it is now and retain that revision in its history (what `present` shows). Serialised with writes. */
     readonly keep: (path: string, access: ResourceAccess) => Promise<ReadResult>;
     /** Provider writes and polled detections. The listener must not throw. */
     readonly onChange: (listener: (change: WorkspaceChange) => void) => () => void;
-    /** Hash each path now and report those that differ from the last revision this provider wrote or polled. Finds shell writes. */
-    readonly poll: (paths: readonly string[], signal?: AbortSignal) => Promise<WorkspaceChange[]>;
+    /**
+     * Hash each path now and report those that differ from the last revision this provider wrote or polled. Finds shell writes.
+     * Without `paths`, every file of the workspace (except `.git` and `node_modules`): the first such call takes the baseline and
+     * reports nothing; later calls also report new and removed files. A host whose file system cannot `watch` calls it at the end of
+     * each agent turn (after `bash`), so the change feed still sees shell writes.
+     */
+    readonly poll: (paths?: readonly string[], signal?: AbortSignal) => Promise<WorkspaceChange[]>;
 }
 export interface WorkspaceProviderOptions {
     readonly identity: WorkspaceKey;
     readonly fs: FileSystem;
     readonly journal: WorkspaceJournal;
     readonly catalog?: WorkspaceCatalogOptions;
+    /** How many change events the feed retains for replay (default 1024). An older cursor gets a `resnapshot`. */
+    readonly changeBuffer?: number;
+    /** How long the watcher stays open after the last change-feed listener leaves, in milliseconds (default 30 000). */
+    readonly watchLingerMs?: number;
+    /**
+     * The largest file this workspace may store, in bytes. Over a SQLite file system (the SQLite and Durable Object providers) it sets
+     * that file system's one limit, so native writes and publications agree; default: the file system's own limit (`SQLITE_MAX_FILE_BYTES`
+     * unless opened otherwise). Over other file systems it applies to publications only, with no default.
+     */
+    readonly maxFileBytes?: number;
 }
 /** The Git blob id of `bytes` (`sha1("blob <length>\0" + bytes)`), computed without Git. */
 export declare function blobRevision(bytes: Uint8Array): Promise<string>;
-/** Whether a path is one of the provider's temporary files (a lister hides them). */
-export declare const isTemporary: (path: string) => boolean;
 export declare function createWorkspaceProvider(options: WorkspaceProviderOptions): WorkspaceResourceProvider;
 //# sourceMappingURL=workspace.d.ts.map