@qilin-agent/workspace-changes 0.0.0-stage → 3.1.4

package/lib/types/index.js

@@ -0,0 +1,146 @@
+/**
+ * Summarizes the files each top-level turn changed from git working-tree
+ * snapshots taken at turn start and turn end, plus whole-file captures taken
+ * around each file-tool edit for paths git does not cover, and serves each
+ * listed file's before-and-after comparison on demand. Each summary is
+ * announced by a `workspace/changes` Session event that carries only the turn
+ * number; summaries and comparisons are served through the `workspaceChanges`
+ * service until the Session is disposed. Outside a git repository, or without
+ * git, the summary lists file-tool edits only.
+ */
+import { homedir, tmpdir } from 'node:os';
+import z from '@qilin-agent/schemastery';
+import { GitRunner } from "./git.js";
+import { TurnRecorder } from "./recorder.js";
+/** Stable Loader identity. */
+export const name = 'workspace-changes';
+/** Services used to run git and observe turns. */
+export const inject = ['subprocess'];
+/** Schemastery validation for {@link Config}. */
+export const Config = z.object({
+    timeoutMs: z.number().default(30_000),
+    outputMaxBytes: z.number().default(8 * 1024 * 1024),
+    maxFiles: z.number().default(500),
+    maxFileBytes: z.number().default(2 * 1024 * 1024),
+    diffTimeoutMs: z.number().default(100),
+});
+function eligible(session) {
+    const { cwd, origin, delegationDepth } = session.header;
+    return origin === 'subagent' || (delegationDepth ?? 0) > 0 ? undefined : cwd;
+}
+/**
+ * Resolve the git executable once. On macOS the Xcode stub at `/usr/bin/git`
+ * opens an installer dialog instead of running, so it counts as absent until
+ * developer tools are selected.
+ * @param ctx - subprocess capability.
+ * @param signal - plugin lifetime.
+ * @returns the executable path, or null when git is unavailable.
+ */
+async function resolveGit(ctx, signal) {
+    let executable;
+    try {
+        executable = await ctx.subprocess.resolveExecutable('git', undefined, signal);
+    }
+    catch {
+        return null;
+    }
+    if (process.platform !== 'darwin' || executable !== '/usr/bin/git')
+        return executable;
+    const probe = ctx.subprocess.spawn({
+        argv: ['/usr/bin/xcode-select', '-p'], cwd: homedir(),
+        stdio: { stdin: 'ignore', stdout: { maxBytes: 4096 }, stderr: { maxBytes: 4096 } }, graceMs: 1_000, signal,
+    });
+    const outcome = await probe.done.catch(() => ({ exitCode: null }));
+    return outcome.exitCode === 0 ? executable : null;
+}
+/**
+ * Observe top-level turns of every Session with a working directory, capture
+ * file-tool edits, announce change summaries, and serve them with their
+ * comparisons as `workspaceChanges`.
+ * @param ctx - host context with `subprocess`.
+ * @param config - validated bounds.
+ */
+export function apply(ctx, config) {
+    for (const [field, value] of [
+        ['timeoutMs', config.timeoutMs], ['outputMaxBytes', config.outputMaxBytes], ['maxFiles', config.maxFiles],
+        ['maxFileBytes', config.maxFileBytes], ['diffTimeoutMs', config.diffTimeoutMs],
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new Error(`workspace-changes requires a positive integer ${field}`);
+    }
+    const lifetime = new AbortController();
+    const recorders = new Map();
+    const byId = new Map();
+    const forget = (session) => {
+        const recorder = recorders.get(session);
+        recorders.delete(session);
+        byId.delete(session.id);
+        return recorder?.dispose() ?? Promise.resolve();
+    };
+    ctx.effect(() => async () => {
+        lifetime.abort();
+        await Promise.all([...recorders.keys()].map(forget));
+    });
+    const service = {
+        summary: (sessionId, seq) => byId.get(sessionId)?.summary(seq),
+        session: (sessionId) => {
+            const recorder = byId.get(sessionId);
+            if (recorder === undefined)
+                return undefined;
+            const folded = recorder.sessionChanges();
+            return folded.files.length === 0 ? undefined : folded;
+        },
+        diff: (sessionId, seq, index, signal) => byId.get(sessionId)?.diff(seq, index, signal) ?? Promise.resolve(undefined),
+    };
+    ctx.provide('workspaceChanges', service);
+    let runner;
+    const gitRunner = () => {
+        runner ??= resolveGit(ctx, lifetime.signal).then((executable) => {
+            if (executable === null) {
+                ctx.logger.info('workspace-changes: git is unavailable; only file-tool edits are summarized');
+                return null;
+            }
+            return new GitRunner(ctx.subprocess, executable, { timeoutMs: config.timeoutMs, outputMaxBytes: config.outputMaxBytes });
+        });
+        return runner;
+    };
+    const recorderFor = (session, cwd) => {
+        let recorder = recorders.get(session);
+        if (recorder === undefined) {
+            recorder = new TurnRecorder(session, cwd, {
+                git: gitRunner(), tempRoot: tmpdir(), maxFiles: config.maxFiles,
+                maxFileBytes: config.maxFileBytes, diffTimeoutMs: config.diffTimeoutMs,
+                warn: (message) => { ctx.logger.warn(message); },
+            });
+            recorders.set(session, recorder);
+            byId.set(session.id, recorder);
+        }
+        return recorder;
+    };
+    ctx.on('session/event', (session, event) => {
+        if (event.type === 'turn/start') {
+            const cwd = eligible(session);
+            if (cwd !== undefined)
+                recorderFor(session, cwd).start(event.data.turn);
+            return;
+        }
+        if (event.type === 'tool/result')
+            recorders.get(session)?.observe(event);
+        else if (event.type === 'turn/end')
+            recorders.get(session)?.end(event.data.turn);
+    });
+    ctx.on('session/disposed', (session) => { void forget(session); });
+    ctx.on('agent/turn-stopping', async ({ agent, turn }) => {
+        await recorders.get(agent.session)?.stopping(turn);
+    });
+    ctx.on('tools/pre-execute', async (exec, next) => {
+        const session = exec.agent?.session;
+        const recorder = session === undefined ? undefined : recorders.get(session);
+        if (recorder !== undefined) {
+            recorder.capture(exec.name, exec.arguments);
+            await recorder.settled();
+        }
+        return next();
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/types/numstat.d.ts

@@ -0,0 +1,19 @@
+/** Parsing of `git diff-tree --numstat -z` output. */
+/** One `--numstat` record; paths are slash-separated and relative to the repository root. */
+export interface NumstatEntry {
+    path: string;
+    /** The path before a detected rename; absent for a file that kept its path. */
+    oldPath?: string;
+    added: number;
+    deleted: number;
+    binary: boolean;
+}
+/**
+ * Parse NUL-terminated numstat records. A rename record carries an empty path
+ * followed by the old and new paths.
+ * @param output - complete stdout of `git diff-tree -r -M -z --numstat`.
+ * @returns records in git's output order.
+ * @throws when a record is malformed, which indicates truncated output.
+ */
+export declare function parseNumstat(output: string): NumstatEntry[];
+//# sourceMappingURL=numstat.d.ts.map

package/lib/types/numstat.js

@@ -0,0 +1,45 @@
+/** Parsing of `git diff-tree --numstat -z` output. */
+/**
+ * Parse NUL-terminated numstat records. A rename record carries an empty path
+ * followed by the old and new paths.
+ * @param output - complete stdout of `git diff-tree -r -M -z --numstat`.
+ * @returns records in git's output order.
+ * @throws when a record is malformed, which indicates truncated output.
+ */
+export function parseNumstat(output) {
+    const queue = output.split('\0');
+    if (queue.at(-1) !== '')
+        throw new Error('numstat output is not NUL-terminated');
+    queue.pop();
+    const entries = [];
+    while (queue.length > 0) {
+        const record = queue.shift();
+        // Only the first two tabs separate fields; a file name keeps its own tabs.
+        const first = record.indexOf('\t');
+        const second = first < 0 ? -1 : record.indexOf('\t', first + 1);
+        if (second < 0)
+            throw new Error(`malformed numstat record: ${record}`);
+        const added = record.slice(0, first);
+        const deleted = record.slice(first + 1, second);
+        const path = record.slice(second + 1);
+        let target = path;
+        let oldPath;
+        if (target === '') {
+            oldPath = queue.shift();
+            const renamed = queue.shift();
+            if (oldPath === undefined || renamed === undefined)
+                throw new Error('malformed numstat rename record');
+            target = renamed;
+        }
+        const binary = added === '-';
+        entries.push({
+            path: target,
+            ...oldPath === undefined ? {} : { oldPath },
+            added: binary ? 0 : Number(added),
+            deleted: binary ? 0 : Number(deleted),
+            binary,
+        });
+    }
+    return entries;
+}
+//# sourceMappingURL=numstat.js.map

package/lib/types/paths.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Slash-separated form of a native relative path.
+ * @param path - native path.
+ * @returns the same path with `/` separators.
+ */
+export declare function toPosix(path: string): string;
+/**
+ * Whether `path` is `root` or lies under it.
+ * @param root - absolute directory.
+ * @param path - absolute path to test.
+ * @returns true for the root itself and every descendant.
+ */
+export declare function isInside(root: string, path: string): boolean;
+/**
+ * Canonical spellings of the temporary directories a workspace-write sandbox
+ * grants: the host `/tmp` and the platform temp area, each also in its
+ * symlink-resolved form so `/tmp` and `/private/tmp` match alike.
+ * @param candidates - directories to canonicalize.
+ * @returns absolute directory paths.
+ */
+export declare function temporaryRoots(candidates?: readonly string[]): Promise<string[]>;
+/**
+ * Symlink-resolved path. A path that does not exist yet is resolved through
+ * its nearest existing ancestor, so a file created through a directory
+ * symlink has the same canonical spelling before and after it exists.
+ * @param path - absolute path.
+ * @returns the canonical spelling git reports for the path.
+ */
+export declare function canonicalPath(path: string): Promise<string>;
+/**
+ * Whether a file lives under a temporary root, where the model keeps scratch work.
+ * @param path - absolute file path.
+ * @param roots - {@link temporaryRoots}.
+ * @returns true for scratch paths that never enter the change summary.
+ */
+export declare function isTemporaryPath(path: string, roots: readonly string[]): boolean;
+/**
+ * Sort key and label of a changed file; see `WorkspaceChangedFile.display`.
+ * @param absolute - canonical absolute file path.
+ * @param cwd - canonical Session working directory.
+ * @param root - repository top-level directory.
+ * @param home - canonical home directory, or empty to skip the `~` form.
+ * @returns the slash-separated display path.
+ */
+export declare function displayPathOf(absolute: string, cwd: string, root: string, home: string): string;
+/**
+ * The durable `path` field: relative inside the working directory, absolute elsewhere.
+ * @param absolute - canonical absolute file path.
+ * @param cwd - canonical Session working directory.
+ * @returns the path the Web client opens the file through.
+ */
+export declare function durablePathOf(absolute: string, cwd: string): string;
+/**
+ * Code-unit order of display paths, which places `../` and absolute paths
+ * before letters and matches git's own listing order for relative paths.
+ * @param a - first file.
+ * @param b - second file.
+ * @returns negative, zero, or positive as `Array.prototype.sort` expects.
+ */
+export declare function compareDisplay(a: {
+    display: string;
+}, b: {
+    display: string;
+}): number;
+//# sourceMappingURL=paths.d.ts.map

package/lib/types/paths.js

@@ -0,0 +1,106 @@
+/** Path classification and display forms for changed files. */
+import { realpath } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+/**
+ * Slash-separated form of a native relative path.
+ * @param path - native path.
+ * @returns the same path with `/` separators.
+ */
+export function toPosix(path) {
+    return path.split(sep).join('/');
+}
+/**
+ * Whether `path` is `root` or lies under it.
+ * @param root - absolute directory.
+ * @param path - absolute path to test.
+ * @returns true for the root itself and every descendant.
+ */
+export function isInside(root, path) {
+    const rel = relative(root, path);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/**
+ * Canonical spellings of the temporary directories a workspace-write sandbox
+ * grants: the host `/tmp` and the platform temp area, each also in its
+ * symlink-resolved form so `/tmp` and `/private/tmp` match alike.
+ * @param candidates - directories to canonicalize.
+ * @returns absolute directory paths.
+ */
+export async function temporaryRoots(candidates = ['/tmp', tmpdir()]) {
+    const roots = new Set();
+    for (const root of candidates) {
+        roots.add(root);
+        roots.add(await canonicalPath(root));
+    }
+    return [...roots];
+}
+/**
+ * Symlink-resolved path. A path that does not exist yet is resolved through
+ * its nearest existing ancestor, so a file created through a directory
+ * symlink has the same canonical spelling before and after it exists.
+ * @param path - absolute path.
+ * @returns the canonical spelling git reports for the path.
+ */
+export async function canonicalPath(path) {
+    const missing = [];
+    let head = path;
+    while (true) {
+        try {
+            return join(await realpath(head), ...missing);
+        }
+        catch {
+            // A missing or unreadable component is kept lexically under its nearest resolvable ancestor;
+            // a path with no existing ancestor but the root keeps its spelling entirely.
+            const parent = dirname(head);
+            if (parent === head || dirname(parent) === parent)
+                return path;
+            missing.unshift(basename(head));
+            head = parent;
+        }
+    }
+}
+/**
+ * Whether a file lives under a temporary root, where the model keeps scratch work.
+ * @param path - absolute file path.
+ * @param roots - {@link temporaryRoots}.
+ * @returns true for scratch paths that never enter the change summary.
+ */
+export function isTemporaryPath(path, roots) {
+    return roots.some(root => isInside(root, path));
+}
+/**
+ * Sort key and label of a changed file; see `WorkspaceChangedFile.display`.
+ * @param absolute - canonical absolute file path.
+ * @param cwd - canonical Session working directory.
+ * @param root - repository top-level directory.
+ * @param home - canonical home directory, or empty to skip the `~` form.
+ * @returns the slash-separated display path.
+ */
+export function displayPathOf(absolute, cwd, root, home) {
+    if (isInside(cwd, absolute) || isInside(root, absolute))
+        return toPosix(relative(cwd, absolute));
+    if (home !== '' && isInside(home, absolute))
+        return `~/${toPosix(relative(home, absolute))}`;
+    return toPosix(absolute);
+}
+/**
+ * The durable `path` field: relative inside the working directory, absolute elsewhere.
+ * @param absolute - canonical absolute file path.
+ * @param cwd - canonical Session working directory.
+ * @returns the path the Web client opens the file through.
+ */
+export function durablePathOf(absolute, cwd) {
+    return isInside(cwd, absolute) ? toPosix(relative(cwd, absolute)) : absolute;
+}
+/**
+ * Code-unit order of display paths, which places `../` and absolute paths
+ * before letters and matches git's own listing order for relative paths.
+ * @param a - first file.
+ * @param b - second file.
+ * @returns negative, zero, or positive as `Array.prototype.sort` expects.
+ */
+export function compareDisplay(a, b) {
+    return a.display < b.display ? -1 : a.display > b.display ? 1 : 0;
+}
+//# sourceMappingURL=paths.js.map

package/lib/types/recorder.d.ts

@@ -0,0 +1,126 @@
+import type { Session, SessionEvent } from '@qilin-agent/session';
+import { type GitRunner } from './git.ts';
+import type { WorkspaceChangesSummary, WorkspaceFileDiff, WorkspaceSessionChanges } from './types.ts';
+/** Facts shared by every recorder of one plugin instance. */
+export interface RecorderEnvironment {
+    /** Resolves to the runner, or null when git is unavailable and no snapshot is taken. */
+    git: Promise<GitRunner | null>;
+    /** Directory that receives each Session's temporary directory. */
+    tempRoot: string;
+    /** Maximum files carried by one summary. */
+    maxFiles: number;
+    /** Inclusive byte cap on a captured copy and on a snapshot blob read for a comparison. */
+    maxFileBytes: number;
+    /** Milliseconds a line comparison may run before it degrades to whole-file replacement. */
+    diffTimeoutMs: number;
+    /** Failure reporter; a failed turn records nothing and the next turn retries. */
+    warn: (message: string) => void;
+}
+/**
+ * Serializes one Session's recording work: the turn-start snapshot, the
+ * whole-file capture before each file-tool mutation, the turn-end snapshot
+ * with its diff, and the appended `workspace/changes` event whose summary and
+ * comparisons this recorder keeps. Snapshot objects and captured copies live in
+ * a temporary directory owned by the recorder; disposal removes it together
+ * with the summaries. Tool execution waits for pending work so a snapshot or
+ * capture never races a mutation. A working directory outside any repository,
+ * or a Host without git, gets no snapshot; its summary lists the files the file
+ * tools changed.
+ */
+export declare class TurnRecorder {
+    private readonly session;
+    private readonly cwd;
+    private readonly env;
+    private chain;
+    /** The open turn; before the first `turn/start` it is an empty placeholder no event can match. */
+    private state;
+    /** Canonical paths, resolved by the first turn. */
+    private paths;
+    /** The located repository, reused across turns once found; null keeps retrying each turn. */
+    private repository;
+    /** Temporary directory holding this Session's snapshot objects, scratch indexes, and captured copies. */
+    private scratch;
+    /** Records by the sequence of the event that announced them. */
+    private readonly records;
+    private readonly lifetime;
+    constructor(session: Session, cwd: string, env: RecorderEnvironment);
+    /**
+     * Open a turn with fresh per-turn state and queue its baseline snapshot.
+     * @param turn - the turn number from `turn/start`.
+     */
+    start(turn: number): void;
+    /**
+     * Queue the capture of the path a file tool is about to mutate, before the
+     * tool runs; only the turn's first mutation of a path captures it. Await
+     * {@link settled} afterwards so the tool cannot overtake the capture.
+     * @param name - wire tool name.
+     * @param args - parsed call arguments.
+     */
+    capture(name: string, args: unknown): void;
+    /**
+     * Remember a settled tool result, so a record after `turn/end` covers it.
+     * @param event - the appended `tool/result` event.
+     */
+    observe(event: SessionEvent<'tool/result'>): void;
+    /**
+     * Record the turn's changes inside the turn, before `turn/end` commits.
+     * @param turn - the stopping turn.
+     * @returns after the event is appended or the attempt failed.
+     */
+    stopping(turn: number): Promise<void>;
+    /**
+     * Record after `turn/end` unless a record was already attempted after the turn's last tool result.
+     * @param turn - the turn number from `turn/end`.
+     */
+    end(turn: number): void;
+    /** Resolves once every queued snapshot, capture, and record has settled. */
+    settled(): Promise<void>;
+    /**
+     * The summary announced by one `workspace/changes` event of this Session.
+     * @param seq - the event's sequence number.
+     * @returns the summary, or undefined for a sequence this recorder did not announce.
+     */
+    summary(seq: number): WorkspaceChangesSummary | undefined;
+    /**
+     * Every file this Session's recorded turns changed, folded by path.
+     *
+     * The per-file counts and flags come from the LATEST turn that listed the
+     * file, so a rewrite reads as the delta it left rather than as the churn of
+     * every rewrite; `turns` carries that churn. The Session totals come from
+     * each turn's own complete counts, which include files that turn's list cap
+     * omitted.
+     * @returns the folded list in `display` order, empty before the first recorded turn.
+     */
+    sessionChanges(): WorkspaceSessionChanges;
+    /**
+     * Compare one listed file's contents at turn start and turn end.
+     * @param seq - the announcing event's sequence number.
+     * @param index - the file's index in the summary's `files`.
+     * @param signal - cancels the reads.
+     * @returns the comparison, or undefined for an unknown sequence or index, or once disposed.
+     * @throws when a read fails while the recorder lives.
+     */
+    diff(seq: number, index: number, signal: AbortSignal): Promise<WorkspaceFileDiff | undefined>;
+    /**
+     * Abort queued work, forget every record, and remove the temporary directory.
+     * @returns once the temporary directory is gone.
+     */
+    dispose(): Promise<void>;
+    private enqueue;
+    /** A failure after disposal is expected cancellation and stays silent. */
+    private warnUnlessDisposed;
+    /** This Session's temporary directory, created on first use. */
+    private scratchDir;
+    /** The repository enclosing the working directory, located once; null keeps retrying each turn. */
+    private locate;
+    /** One side's text, null for an absent file, or {@link OVERSIZED} for a snapshot side beyond the byte cap. */
+    private readSide;
+    private record;
+    /**
+     * The listing of a captured pair: an oversized side lists the file without
+     * counts and refuses its comparison, a binary side likewise, and two text
+     * sides carry the counts of their line comparison.
+     */
+    private compared;
+}
+//# sourceMappingURL=recorder.d.ts.map