@tequila99/githuman 0.2.2 → 0.3.0

package/dist/server/services/agent/agent-session.js

@@ -0,0 +1,497 @@
+import { AgentSessionError, AgentSessionStateError, AgentConfigError } from "../../errors/agents.js";
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable, Writable } from 'node:stream';
+import { setTimeout as delay } from 'node:timers/promises';
+import { errorMessage } from "../../../shared/utils/error-message.js";
+import * as acp from '@agentclientprotocol/sdk';
+import { mapConfigOptions, mapPermissionRequest, mapSessionUpdate } from "../../adapters/agents/event-mapper.js";
+/** `npx` may have to download the adapter first. */
+const START_TIMEOUT_MS = 90_000;
+const MAX_BUFFERED_EVENTS = 5_000;
+const STDERR_TAIL_CHARS = 2_000;
+/** How long a closed connection waits for the `exit` event that carries the reason. */
+const EXIT_GRACE_MS = 500;
+/** The option the server picks for an auto-approved request; never a rejection. */
+function autoApproveChoice(options) {
+    return (options.find(o => o.kind === 'allow_once') ??
+        options.find(o => o.kind === 'allow_always'));
+}
+/**
+ * One ACP agent subprocess plus its single session. The server is the only
+ * ACP client (browsers can't speak stdio); everything the UI sees goes
+ * through `subscribe`, which replays the buffered history so a second tab or
+ * a reconnect catches up (ADR 0023). Not declaring the `fs`/`terminal` client
+ * capabilities means agents read, write and run things on their own.
+ */
+export class AgentSession {
+    id = randomUUID();
+    /** Binary attachments of this session's prompts (see context-builder); removed on close. */
+    attachmentDir = join(tmpdir(), 'githuman-agent', this.id);
+    presetId;
+    name;
+    reviewId;
+    #status = 'starting';
+    /** Set when the user (or the server) ends the session: its exit is no failure. */
+    #closing = false;
+    #error = null;
+    #autoApprove = false;
+    #child;
+    #connection;
+    #acpSessionId;
+    #embeddedContext = false;
+    #image = false;
+    #config = [];
+    #stderrTail = '';
+    /** Settles when the agent process has exited. */
+    #exited = Promise.resolve();
+    #ownEventId = 0;
+    #buffer = [];
+    /** Highest id dropped from the buffer; a client that last saw less has lost events. */
+    #evictedId = 0;
+    #listeners = new Set();
+    #pendingPermissions = new Map();
+    #options;
+    constructor(options) {
+        this.#options = options;
+        this.presetId = options.preset.id;
+        this.name = options.name;
+        this.reviewId = options.reviewId ?? null;
+    }
+    get status() {
+        return this.#status;
+    }
+    /** Whether the agent advertised `promptCapabilities.embeddedContext`. */
+    get supportsEmbeddedContext() {
+        return this.#embeddedContext;
+    }
+    /** Whether the agent advertised `promptCapabilities.image`. */
+    get supportsImages() {
+        return this.#image;
+    }
+    info() {
+        return {
+            id: this.id,
+            presetId: this.presetId,
+            name: this.name,
+            status: this.#status,
+            reviewId: this.reviewId,
+            autoApprove: this.#autoApprove,
+            error: this.#error
+        };
+    }
+    /** What the session is now; see `AgentSessionState`. */
+    state() {
+        return {
+            sessionId: this.id,
+            status: this.#status,
+            autoApprove: this.#autoApprove,
+            config: this.#config,
+            permissions: [...this.#pendingPermissions.values()].map(p => p.request)
+        };
+    }
+    /**
+     * Spawns the agent and runs the handshake. Never rejects: a session that
+     * cannot start ends up `closed` with the reason in `info().error` and an
+     * `error` event, so the UI can show it on the chat's tab.
+     */
+    async start() {
+        try {
+            await this.#start();
+        }
+        catch (error) {
+            // An exit during the start already reported itself (`#onExit`).
+            if (this.#error === null && !this.#closing) {
+                const message = errorMessage(error);
+                this.#error = message;
+                this.#emit({ type: 'error', message });
+            }
+            this.close();
+        }
+    }
+    async #start() {
+        const { preset, cwd } = this.#options;
+        const child = spawn(preset.command, preset.args, {
+            cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, ...preset.env }
+        });
+        this.#child = child;
+        this.#exited = new Promise(resolve => child.once('exit', resolve));
+        child.stderr.setEncoding('utf-8');
+        child.stderr.on('data', (chunk) => {
+            this.#stderrTail = (this.#stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
+        });
+        // Swallow stdin EPIPE after the agent died; the closed connection reports it.
+        child.stdin.on('error', () => { });
+        const died = new Promise((_, reject) => {
+            child.once('error', error => {
+                reject(new AgentSessionError(`Cannot start "${preset.command}": ${error.message}`));
+            });
+            child.once('exit', (code, signal) => {
+                reject(new AgentSessionError(this.#exitMessage(code, signal)));
+            });
+        });
+        died.catch(() => { });
+        child.once('exit', (code, signal) => {
+            this.#onExit(code, signal);
+        });
+        const timer = new AbortController();
+        const timedOut = delay(START_TIMEOUT_MS, undefined, {
+            signal: timer.signal
+        }).then(() => {
+            throw new AgentSessionError(`Agent did not become ready within ${START_TIMEOUT_MS / 1000}s`);
+        });
+        timedOut.catch(() => { });
+        try {
+            await Promise.race([this.#handshake(child), died, timedOut]);
+        }
+        finally {
+            timer.abort();
+        }
+        this.#setStatus('ready');
+    }
+    async #handshake(child) {
+        if (child.stdin === null || child.stdout === null) {
+            throw new AgentSessionError('Agent process has no stdio');
+        }
+        const stream = acp.ndJsonStream(Writable.toWeb(child.stdin), 
+        // Node's web-stream typing differs from the DOM one the SDK expects.
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- same stream, differing lib typings
+        Readable.toWeb(child.stdout));
+        const connection = acp
+            .client({ name: 'githuman' })
+            .onRequest(acp.methods.client.session.requestPermission, ctx => this.#requestPermission(ctx.params))
+            .onNotification(acp.methods.client.session.update, ctx => {
+            this.#onUpdate(ctx.params.update);
+        })
+            .connect(stream);
+        this.#connection = connection;
+        void connection.closed.finally(() => {
+            this.#onConnectionClosed();
+        });
+        const init = await connection.agent.request(acp.methods.agent.initialize, {
+            protocolVersion: acp.PROTOCOL_VERSION,
+            clientCapabilities: {}
+        });
+        const prompt = init.agentCapabilities?.promptCapabilities;
+        this.#embeddedContext = prompt?.embeddedContext === true;
+        this.#image = prompt?.image === true;
+        const created = await connection.agent.request(acp.methods.agent.session.new, {
+            cwd: this.#options.cwd,
+            mcpServers: []
+        });
+        this.#acpSessionId = created.sessionId;
+        this.#setConfig(mapConfigOptions(created.configOptions));
+    }
+    #setConfig(options) {
+        this.#config = options;
+        this.#emit({ type: 'config', options });
+    }
+    /**
+     * Changes a session setting (model, mode, …) and returns the agent's new
+     * full set of options. Validated against what the agent itself offered, so
+     * an unknown id or value is rejected here rather than sent on.
+     */
+    async setConfig(configId, value) {
+        const connection = this.#connection;
+        const sessionId = this.#acpSessionId;
+        if (this.#status !== 'ready' || !connection || !sessionId) {
+            throw new AgentSessionStateError(this.#status === 'busy'
+                ? 'Settings cannot be changed while the agent is answering'
+                : `The session is ${this.#status}`);
+        }
+        const option = this.#config.find(o => o.id === configId);
+        if (!option) {
+            throw new AgentConfigError(`Unknown setting "${configId}"`);
+        }
+        if (option.type === 'boolean'
+            ? typeof value !== 'boolean'
+            : !option.options?.some(c => c.value === value)) {
+            throw new AgentConfigError(`Invalid value for "${option.name}"`);
+        }
+        try {
+            const response = await connection.agent.request(acp.methods.agent.session.setConfigOption, typeof value === 'boolean'
+                ? { sessionId, configId, type: 'boolean', value }
+                : { sessionId, configId, value });
+            this.#setConfig(mapConfigOptions(response.configOptions));
+        }
+        catch (error) {
+            throw new AgentSessionError(errorMessage(error), { cause: error });
+        }
+    }
+    /** The agent process ended: report why, unless the session itself ended it. */
+    #onExit(code, signal) {
+        if (!this.#closing && this.#error === null && this.#status !== 'closed') {
+            this.#error = this.#exitMessage(code, signal);
+            this.#emit({ type: 'error', message: this.#error });
+        }
+        this.#markClosed();
+    }
+    /**
+     * The connection often closes before the `exit` event, and only that event
+     * has the exit code. Wait a short time for it before closing without a reason.
+     */
+    #onConnectionClosed() {
+        const child = this.#child;
+        if (this.#closing ||
+            !child ||
+            child.exitCode !== null ||
+            child.signalCode !== null) {
+            this.#markClosed();
+            return;
+        }
+        void this.#closeAfterGrace();
+    }
+    async #closeAfterGrace() {
+        await delay(EXIT_GRACE_MS, undefined, { ref: false });
+        if (!this.#isClosed() && this.#error === null) {
+            this.#error = 'Agent closed the connection';
+            this.#emit({ type: 'error', message: this.#error });
+        }
+        this.#markClosed();
+    }
+    #exitMessage(code, signal) {
+        const tail = this.#stderrTail.trim();
+        return (`Agent exited (${signal ?? `code ${code}`})` +
+            (tail === '' ? '' : `: ${tail.slice(-400)}`));
+    }
+    /**
+     * Sends a prompt and returns immediately; progress arrives as events and the
+     * turn ends with a `stop` event (or `error`). One prompt at a time.
+     */
+    prompt(blocks, display) {
+        const { connection, sessionId } = this.#readyChannel();
+        this.#setStatus('busy');
+        this.#emit({
+            type: 'user',
+            text: display.text,
+            context: display.context ?? []
+        });
+        void this.#runPrompt(connection, sessionId, blocks);
+    }
+    /**
+     * Throws when the session cannot take a prompt now. The route calls this
+     * before it builds the context, which can be slow and writes attachments.
+     */
+    assertCanPrompt() {
+        this.#readyChannel();
+    }
+    #readyChannel() {
+        const connection = this.#connection;
+        const sessionId = this.#acpSessionId;
+        if (this.#status !== 'ready' || !connection || !sessionId) {
+            throw new AgentSessionStateError(this.#status === 'busy'
+                ? 'The agent is still answering the previous prompt'
+                : `The session is ${this.#status}`);
+        }
+        return { connection, sessionId };
+    }
+    async #runPrompt(connection, sessionId, blocks) {
+        try {
+            const response = await connection.agent.request(acp.methods.agent.session.prompt, { sessionId, prompt: blocks });
+            this.#emit({ type: 'stop', stopReason: response.stopReason });
+        }
+        catch (error) {
+            // A failure of the transport comes before the `exit` event, and only
+            // that event can say why the agent died: let it report first.
+            if (!(error instanceof acp.RequestError)) {
+                await Promise.race([
+                    this.#exited,
+                    delay(EXIT_GRACE_MS, undefined, { ref: false })
+                ]);
+            }
+            if (!this.#isClosed() && this.#error === null) {
+                this.#emit({ type: 'error', message: errorMessage(error) });
+            }
+        }
+        finally {
+            // A request still open once the turn is over (it ended in an error, say)
+            // is dead: answering it later would still make the agent act on it.
+            this.#cancelPendingPermissions();
+            if (this.#status === 'busy') {
+                this.#setStatus('ready');
+            }
+        }
+    }
+    /** A method, so TypeScript does not keep a stale narrowing across an `await`. */
+    #isClosed() {
+        return this.#status === 'closed';
+    }
+    async cancel() {
+        if (this.#status !== 'busy' || !this.#connection || !this.#acpSessionId) {
+            return;
+        }
+        try {
+            await this.#connection.agent.notify(acp.methods.agent.session.cancel, {
+                sessionId: this.#acpSessionId
+            });
+        }
+        catch (error) {
+            // The connection closed since the check above: the turn is over anyway.
+            if (!this.#isClosed()) {
+                throw new AgentSessionError(errorMessage(error), { cause: error });
+            }
+        }
+    }
+    /**
+     * Returns false when no such request is pending (already answered or
+     * cancelled). Throws when `optionId` is not one the agent offered.
+     */
+    answerPermission(requestId, optionId) {
+        const pending = this.#pendingPermissions.get(requestId);
+        if (!pending) {
+            return false;
+        }
+        if (optionId !== undefined &&
+            !pending.request.options.some(option => option.optionId === optionId)) {
+            throw new AgentConfigError(`Unknown option "${optionId}"`);
+        }
+        pending.resolve(optionId === undefined
+            ? { outcome: { outcome: 'cancelled' } }
+            : { outcome: { outcome: 'selected', optionId } });
+        return true;
+    }
+    /**
+     * Switches the server answering the agent's permission requests itself (see
+     * `autoApproveChoice`), requests already waiting included. Off by default;
+     * the UI only turns it on after warning the user.
+     */
+    setAutoApprove(enabled) {
+        if (this.#status === 'closed') {
+            throw new AgentSessionStateError('The session is closed');
+        }
+        if (this.#autoApprove === enabled) {
+            return;
+        }
+        this.#autoApprove = enabled;
+        this.#emit({ type: 'auto-approve', enabled });
+        if (!enabled) {
+            return;
+        }
+        // Resolving removes the entry being visited, which Map iteration allows.
+        for (const pending of this.#pendingPermissions.values()) {
+            const response = this.#autoApprovePermission(pending.request);
+            if (response) {
+                pending.resolve(response);
+            }
+        }
+    }
+    #autoApprovePermission(request) {
+        const choice = autoApproveChoice(request.options);
+        if (!choice) {
+            return undefined;
+        }
+        this.#emit({ type: 'auto-approved', title: request.title });
+        return { outcome: { outcome: 'selected', optionId: choice.optionId } };
+    }
+    #requestPermission(params) {
+        // Requests belong to a turn; one arriving outside it has nobody to answer it.
+        if (this.#status !== 'busy') {
+            return Promise.resolve({ outcome: { outcome: 'cancelled' } });
+        }
+        const requestId = randomUUID();
+        const request = mapPermissionRequest(requestId, params);
+        if (this.#autoApprove) {
+            const response = this.#autoApprovePermission(request);
+            if (response) {
+                return Promise.resolve(response);
+            }
+        }
+        return new Promise(resolve => {
+            this.#pendingPermissions.set(requestId, {
+                request,
+                resolve: response => {
+                    this.#pendingPermissions.delete(requestId);
+                    this.#emit({ type: 'permission-resolved', requestId });
+                    resolve(response);
+                }
+            });
+            this.#emit(request);
+        });
+    }
+    #onUpdate(update) {
+        // Agents may speak outside a turn — pi greets with its version and skill
+        // list right after session/new. That is noise in a chat transcript.
+        if (this.#status !== 'busy' &&
+            update.sessionUpdate === 'agent_message_chunk') {
+            return;
+        }
+        const event = mapSessionUpdate(update);
+        if (event?.type === 'config') {
+            // Keep `#config` current: `setConfig` checks values against it.
+            this.#setConfig(event.options);
+        }
+        else if (event) {
+            this.#emit(event);
+        }
+    }
+    /**
+     * Buffered events newer than `afterId`. `gap` means the buffer no longer
+     * reaches back to `afterId`: the client missed events for good and should
+     * rebuild this chat from what is left.
+     */
+    replay(afterId) {
+        return {
+            envelopes: this.#buffer.filter(envelope => envelope.id > afterId),
+            gap: afterId > 0 && this.#evictedId > afterId
+        };
+    }
+    /** Delivers live events (no replay — see `replay`). Returns an unsubscribe function. */
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    #emit(event) {
+        const id = this.#options.nextEventId?.() ?? ++this.#ownEventId;
+        const envelope = { id, event };
+        this.#buffer.push(envelope);
+        const limit = this.#options.bufferLimit ?? MAX_BUFFERED_EVENTS;
+        if (this.#buffer.length > limit) {
+            const dropped = this.#buffer.splice(0, this.#buffer.length - limit);
+            this.#evictedId = dropped.at(-1)?.id ?? this.#evictedId;
+        }
+        for (const listener of this.#listeners) {
+            listener(envelope);
+        }
+    }
+    #setStatus(status, error) {
+        if (this.#status === status) {
+            return;
+        }
+        this.#status = status;
+        this.#emit({
+            type: 'status',
+            status,
+            ...(error === undefined ? {} : { error })
+        });
+    }
+    #markClosed() {
+        if (this.#status === 'closed') {
+            return;
+        }
+        this.#setStatus('closed', this.#error ?? undefined);
+        void rm(this.attachmentDir, { recursive: true, force: true }).catch(() => { });
+        // Unanswered permission requests must not leave the agent blocked forever.
+        this.#cancelPendingPermissions();
+    }
+    #cancelPendingPermissions() {
+        // Each resolver removes itself from the map, which Map iteration allows.
+        for (const pending of this.#pendingPermissions.values()) {
+            pending.resolve({ outcome: { outcome: 'cancelled' } });
+        }
+    }
+    close() {
+        this.#closing = true;
+        this.#markClosed();
+        this.#connection?.close();
+        if (this.#child &&
+            this.#child.exitCode === null &&
+            this.#child.signalCode === null) {
+            this.#child.kill();
+        }
+    }
+}

package/dist/server/services/agent/context-builder.js

@@ -0,0 +1,137 @@
+import { MAX_ATTACHMENT_BYTES } from "../../../shared/agents/constants.js";
+import { AgentContextError } from "../../errors/agents.js";
+import { errorMessage } from "../../../shared/utils/error-message.js";
+import { formatDiffFile } from "../../../shared/agents/context-format.js";
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getStagedDiff, getUnstagedDiff } from "../diff.service.js";
+import { exportAsMarkdown } from "../export.service.js";
+import { resolveWithinRepo } from "../git.service.js";
+import { safeFileName } from "../../utils/file-name.js";
+import { decodeText, truncateText } from "../../utils/text.js";
+/** Per attached item. Bigger contexts are cut with a visible marker, never silently. */
+export const MAX_EMBEDDED_CHARS = 200_000;
+/** What ACP agents (and the models behind them) accept as an image block. */
+const IMAGE_MIME_TYPES = new Set([
+    'image/png',
+    'image/jpeg',
+    'image/gif',
+    'image/webp'
+]);
+function diffFilePath(file) {
+    return file.newPath || file.oldPath;
+}
+function fenceFor(text) {
+    const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map(run => run.length));
+    return '`'.repeat(Math.max(3, longest + 1));
+}
+/**
+ * Text the agent cannot fetch on its own (a diff of staged content, a review)
+ * goes in as an embedded resource when the agent supports it, otherwise as a
+ * fenced block in a plain text part — same content either way.
+ */
+function embed(deps, uri, title, mimeType, text) {
+    const body = truncateText(text, MAX_EMBEDDED_CHARS, omitted => `\n… [truncated by githuman: ${omitted} more characters]`);
+    if (deps.embeddedContext) {
+        return { type: 'resource', resource: { uri, mimeType, text: body } };
+    }
+    const fence = fenceFor(body);
+    return { type: 'text', text: `${title}\n${fence}\n${body}\n${fence}` };
+}
+function asContextError(error) {
+    return new AgentContextError(errorMessage(error), { cause: error });
+}
+async function buildDiffItem(item, deps) {
+    const files = item.source === 'staged'
+        ? await getStagedDiff(deps.repositoryPath)
+        : await getUnstagedDiff(deps.repositoryPath);
+    const selected = item.path === undefined
+        ? files
+        : files.filter(file => diffFilePath(file) === item.path);
+    if (selected.length === 0) {
+        throw new AgentContextError(item.path === undefined
+            ? `No ${item.source} changes to attach`
+            : `No ${item.source} changes in "${item.path}"`);
+    }
+    return embed(deps, `githuman://diff/${item.source}/${item.path ?? ''}`, `Diff (${item.source}${item.path === undefined ? '' : `, ${item.path}`}):`, 'text/x-diff', selected.map(formatDiffFile).join('\n'));
+}
+async function buildFileItem(item, deps) {
+    let absolute;
+    try {
+        absolute = resolveWithinRepo(deps.repositoryPath, item.path);
+    }
+    catch (error) {
+        throw asContextError(error);
+    }
+    const info = await stat(absolute).catch(() => null);
+    if (!info?.isFile()) {
+        throw new AgentContextError(`"${item.path}" is not a file in the repository`);
+    }
+    return {
+        type: 'resource_link',
+        uri: pathToFileURL(absolute).href,
+        name: item.path
+    };
+}
+async function buildReviewItem(item, deps) {
+    let markdown;
+    try {
+        markdown = await exportAsMarkdown(deps.db, item.reviewId, deps.repositoryPath);
+    }
+    catch (error) {
+        throw asContextError(error);
+    }
+    return embed(deps, `githuman://review/${item.reviewId}`, 'Code review with comments:', 'text/markdown', markdown);
+}
+/**
+ * Images become image blocks, UTF-8 text is embedded. Anything else (PDF,
+ * archives, …) is written to disk and passed as a link the agent opens with
+ * its own tools: adapters don't hand ACP blob resources to the model as files
+ * — codex-acp turns them into a base64 text dump the model can't read.
+ */
+async function buildAttachmentItem(item, deps) {
+    const bytes = Buffer.from(item.data, 'base64');
+    if (bytes.length > MAX_ATTACHMENT_BYTES) {
+        throw new AgentContextError(`"${item.name}" is larger than ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB`);
+    }
+    if (IMAGE_MIME_TYPES.has(item.mimeType)) {
+        if (!deps.image) {
+            throw new AgentContextError('This agent does not accept images');
+        }
+        return { type: 'image', mimeType: item.mimeType, data: item.data };
+    }
+    const text = decodeText(bytes);
+    if (text !== null) {
+        return embed(deps, `githuman://attachment/${encodeURIComponent(item.name)}`, `Attached file ${item.name}:`, item.mimeType || 'text/plain', text);
+    }
+    // A directory per attachment keeps the user's file name without collisions.
+    const dir = join(deps.attachmentDir, randomUUID());
+    const path = join(dir, safeFileName(item.name));
+    await mkdir(dir, { recursive: true });
+    await writeFile(path, bytes);
+    return {
+        type: 'resource_link',
+        uri: pathToFileURL(path).href,
+        name: item.name,
+        ...(item.mimeType === '' ? {} : { mimeType: item.mimeType })
+    };
+}
+function buildItem(item, deps) {
+    if (item.kind === 'diff') {
+        return buildDiffItem(item, deps);
+    }
+    if (item.kind === 'file') {
+        return buildFileItem(item, deps);
+    }
+    if (item.kind === 'attachment') {
+        return buildAttachmentItem(item, deps);
+    }
+    return buildReviewItem(item, deps);
+}
+/** The user's text first, then each attached item as its own content block. */
+export async function buildPromptBlocks(request, deps) {
+    const items = await Promise.all((request.context ?? []).map(item => buildItem(item, deps)));
+    return [{ type: 'text', text: request.text }, ...items];
+}

package/dist/server/services/agent/file-index.js

@@ -0,0 +1,58 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getFilesAtRef } from "../git.service.js";
+import { DEFAULT_FILE_SEARCH_LIMIT } from "../../../shared/agents/constants.js";
+import { rankFiles } from "../../../shared/agents/file-search.js";
+/**
+ * The repository's file list for `@` mentions. Read once from `git ls-files`
+ * and filtered in memory — the query never reaches a git argument — and
+ * dropped whenever the working tree changes.
+ */
+export function createFileIndex(repositoryPath, eventBus) {
+    let cached = null;
+    let loading = null;
+    // A change during a load makes that load's result stale on arrival.
+    let generation = 0;
+    const unsubscribe = eventBus.subscribe(event => {
+        if (event.type === 'files:changed') {
+            generation++;
+            cached = null;
+        }
+    });
+    function files() {
+        if (cached) {
+            return Promise.resolve(cached);
+        }
+        if (!loading) {
+            const started = generation;
+            loading = getFilesAtRef(repositoryPath, 'WORKTREE')
+                .then(list => {
+                if (started === generation) {
+                    cached = list;
+                }
+                return list;
+            })
+                .finally(() => {
+                loading = null;
+            });
+        }
+        return loading;
+    }
+    return {
+        async search(query, limit = DEFAULT_FILE_SEARCH_LIMIT) {
+            const ranked = rankFiles(await files(), query);
+            const found = [];
+            for (const path of ranked) {
+                // `ls-files --cached` still lists files deleted from the working tree.
+                if (existsSync(join(repositoryPath, path))) {
+                    found.push(path);
+                    if (found.length >= limit) {
+                        break;
+                    }
+                }
+            }
+            return found;
+        },
+        close: unsubscribe
+    };
+}