@xenosystem/agent-interface-host 0.1.3

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}

package/dist/observation/DirectoryBaselineScanner.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What was already on disk when a run started, in CONTAINER terms.
+ *
+ * ## Why the namespace matters more than the walk
+ *
+ * The filesystem sensor reports paths as the sandbox sees them
+ * (`/mnt/xeno/work/src/app.ts`), because that is the only namespace both sides
+ * agree on. A baseline collected in host terms (`D:\work\repo\src\app.ts`) would
+ * therefore match nothing, and `RunDiff` would classify every touched file as
+ * `added` — a diff that reads as "the agent created your whole repository".
+ *
+ * It would also be silently wrong. Nothing errors; the numbers are simply
+ * inflated. So the mapping is the point of this class and the walk is incidental.
+ *
+ * ## Bounds are not an optimisation
+ *
+ * A run's directory can be a monorepo with `node_modules`. Walking it without a
+ * bound would stall the turn that triggered it, so there are two: entries and
+ * elapsed time. Hitting either yields `complete: false`, which the observer
+ * carries into the snapshot as a degradation rather than discarding — an
+ * incomplete baseline over-reports, and a reviewer cannot tell an inflated diff
+ * from an accurate one by looking at it.
+ */
+import type { RunBaselineScanner } from './XenoUseRunObserver.js';
+export interface DirectoryBaselineScannerOptions {
+    /** Largest number of files to record before giving up and saying so. */
+    maxEntries?: number;
+    /** Wall-clock budget for the whole walk. */
+    budgetMs?: number;
+    now?: () => number;
+}
+export declare class DirectoryBaselineScanner implements RunBaselineScanner {
+    #private;
+    constructor(options?: DirectoryBaselineScannerOptions);
+    scan(request: {
+        hostDirectory: string;
+        containerDirectory: string;
+    }): Promise<{
+        paths: string[];
+        complete: boolean;
+        problem?: string;
+    }>;
+}
+//# sourceMappingURL=DirectoryBaselineScanner.d.ts.map

package/dist/observation/DirectoryBaselineScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DirectoryBaselineScanner.d.ts","sourceRoot":"","sources":["../../src/observation/DirectoryBaselineScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,MAAM,WAAW,+BAA+B;IAC9C,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAKD,qBAAa,wBAAyB,YAAW,kBAAkB;;gBAKrD,OAAO,GAAE,+BAAoC;IAMnD,IAAI,CAAC,OAAO,EAAE;QAClB,aAAa,EAAE,MAAM,CAAA;QACrB,kBAAkB,EAAE,MAAM,CAAA;KAC3B,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAwEtE"}

package/dist/observation/DirectoryBaselineScanner.js

@@ -0,0 +1,112 @@
+/**
+ * What was already on disk when a run started, in CONTAINER terms.
+ *
+ * ## Why the namespace matters more than the walk
+ *
+ * The filesystem sensor reports paths as the sandbox sees them
+ * (`/mnt/xeno/work/src/app.ts`), because that is the only namespace both sides
+ * agree on. A baseline collected in host terms (`D:\work\repo\src\app.ts`) would
+ * therefore match nothing, and `RunDiff` would classify every touched file as
+ * `added` — a diff that reads as "the agent created your whole repository".
+ *
+ * It would also be silently wrong. Nothing errors; the numbers are simply
+ * inflated. So the mapping is the point of this class and the walk is incidental.
+ *
+ * ## Bounds are not an optimisation
+ *
+ * A run's directory can be a monorepo with `node_modules`. Walking it without a
+ * bound would stall the turn that triggered it, so there are two: entries and
+ * elapsed time. Hitting either yields `complete: false`, which the observer
+ * carries into the snapshot as a degradation rather than discarding — an
+ * incomplete baseline over-reports, and a reviewer cannot tell an inflated diff
+ * from an accurate one by looking at it.
+ */
+import { opendir } from 'node:fs/promises';
+import { join } from 'node:path';
+const DEFAULT_MAX_ENTRIES = 200_000;
+const DEFAULT_BUDGET_MS = 15_000;
+export class DirectoryBaselineScanner {
+    #maxEntries;
+    #budgetMs;
+    #now;
+    constructor(options = {}) {
+        this.#maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.#budgetMs = options.budgetMs ?? DEFAULT_BUDGET_MS;
+        this.#now = options.now ?? (() => Date.now());
+    }
+    async scan(request) {
+        const deadline = this.#now() + this.#budgetMs;
+        const paths = [];
+        // Iterative rather than recursive: a deep tree should bound the walk, not
+        // the call stack.
+        const queue = [
+            {
+                hostDirectory: request.hostDirectory,
+                // Trailing slashes are stripped HERE as well as by the observer that
+                // normally calls this. `/mnt/xeno/work//a.ts` matches no event, which is
+                // the same silent miss as a host-shaped path from a subtler cause — and
+                // this class is exported, so it cannot assume its caller normalised.
+                containerPrefix: request.containerDirectory.replace(/\/+$/, ''),
+            },
+        ];
+        const tooManyFiles = () => ({
+            paths,
+            complete: false,
+            problem: `the run's starting state was larger than ${this.#maxEntries} files, so files that already existed may report as added`,
+        });
+        while (queue.length > 0) {
+            if (paths.length >= this.#maxEntries)
+                return tooManyFiles();
+            if (this.#now() >= deadline) {
+                return {
+                    paths,
+                    complete: false,
+                    problem: `reading the run's starting state took longer than ${this.#budgetMs}ms, so files that already existed may report as added`,
+                };
+            }
+            const next = queue.pop();
+            if (!next)
+                break;
+            let dir;
+            try {
+                dir = await opendir(next.hostDirectory);
+            }
+            catch (error) {
+                // A directory that cannot be read is a genuine hole in the baseline —
+                // its files WILL report as added — so it degrades rather than being
+                // skipped quietly. The root failing is the common case (the run's
+                // directory does not exist yet) and it is the same answer.
+                return {
+                    paths,
+                    complete: false,
+                    problem: `part of the run's starting state could not be read (${reason(error)}), so files that already existed may report as added`,
+                };
+            }
+            for await (const entry of dir) {
+                // Symlinks are recorded as leaves and never followed. Following them
+                // could walk out of the mount entirely, and a link's TARGET is not part
+                // of this run's starting state even when it resolves inside.
+                if (entry.isDirectory()) {
+                    queue.push({
+                        hostDirectory: join(next.hostDirectory, entry.name),
+                        containerPrefix: `${next.containerPrefix}/${entry.name}`,
+                    });
+                    continue;
+                }
+                paths.push(`${next.containerPrefix}/${entry.name}`);
+                // Returned from HERE, not deferred to the top of the outer loop. The
+                // bound can be reached while draining the last directory in the queue,
+                // and a deferred check never runs in that case — the walk simply ends
+                // and reports `complete: true` for a baseline it knows is truncated.
+                // Found by the test, which is the only reason it is not still true.
+                if (paths.length >= this.#maxEntries)
+                    return tooManyFiles();
+            }
+        }
+        return { paths, complete: true };
+    }
+}
+function reason(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=DirectoryBaselineScanner.js.map

package/dist/observation/DirectoryBaselineScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DirectoryBaselineScanner.js","sourceRoot":"","sources":["../../src/observation/DirectoryBaselineScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAYhC,MAAM,mBAAmB,GAAG,OAAO,CAAA;AACnC,MAAM,iBAAiB,GAAG,MAAM,CAAA;AAEhC,MAAM,OAAO,wBAAwB;IAC1B,WAAW,CAAQ;IACnB,SAAS,CAAQ;IACjB,IAAI,CAAc;IAE3B,YAAY,UAA2C,EAAE;QACvD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAA;QAC5D,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAA;QACtD,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IAC/C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAGV;QACC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAA;QAC7C,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,0EAA0E;QAC1E,kBAAkB;QAClB,MAAM,KAAK,GAA8D;YACvE;gBACE,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,qEAAqE;gBACrE,yEAAyE;gBACzE,wEAAwE;gBACxE,qEAAqE;gBACrE,eAAe,EAAE,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;aAChE;SACF,CAAA;QAED,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,CAAC;YAC1B,KAAK;YACL,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,4CAA4C,IAAI,CAAC,WAAW,2DAA2D;SACjI,CAAC,CAAA;QAEF,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,WAAW;gBAAE,OAAO,YAAY,EAAE,CAAA;YAC3D,IAAI,IAAI,CAAC,IAAI,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC5B,OAAO;oBACL,KAAK;oBACL,QAAQ,EAAE,KAAK;oBACf,OAAO,EAAE,qDAAqD,IAAI,CAAC,SAAS,uDAAuD;iBACpI,CAAA;YACH,CAAC;YAED,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,CAAA;YACxB,IAAI,CAAC,IAAI;gBAAE,MAAK;YAChB,IAAI,GAAG,CAAA;YACP,IAAI,CAAC;gBACH,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;YACzC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,sEAAsE;gBACtE,oEAAoE;gBACpE,kEAAkE;gBAClE,2DAA2D;gBAC3D,OAAO;oBACL,KAAK;oBACL,QAAQ,EAAE,KAAK;oBACf,OAAO,EAAE,uDAAuD,MAAM,CAAC,KAAK,CAAC,sDAAsD;iBACpI,CAAA;YACH,CAAC;YAED,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;gBAC9B,qEAAqE;gBACrE,wEAAwE;gBACxE,6DAA6D;gBAC7D,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;oBACxB,KAAK,CAAC,IAAI,CAAC;wBACT,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,IAAI,CAAC;wBACnD,eAAe,EAAE,GAAG,IAAI,CAAC,eAAe,IAAI,KAAK,CAAC,IAAI,EAAE;qBACzD,CAAC,CAAA;oBACF,SAAQ;gBACV,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,eAAe,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;gBACnD,qEAAqE;gBACrE,uEAAuE;gBACvE,sEAAsE;gBACtE,qEAAqE;gBACrE,oEAAoE;gBACpE,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,WAAW;oBAAE,OAAO,YAAY,EAAE,CAAA;YAC7D,CAAC;QACH,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;IAClC,CAAC;CACF;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC/D,CAAC"}

package/dist/observation/MountContentReader.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Reads review content off a run's mounts — the "after" half of §2.9 hunks.
+ *
+ * Lives in the `node` entry, not `index`, because it touches the filesystem and
+ * `index` is renderer-safe by convention in this package.
+ *
+ * ## Why this needs no sandbox call, and no `xeno-use` dependency
+ *
+ * A bind mount **is** the host directory. That is the same property the
+ * filesystem sensor already relies on to observe container writes from outside,
+ * so current content is an ordinary host-side read. No verb, no exec, no
+ * licensing entanglement (see the AGPL boundary noted on `RunObservationService`).
+ *
+ * ## Containment is the whole job
+ *
+ * This maps an agent-supplied container path onto a host path and then reads it.
+ * That is precisely the shape of a path-traversal vulnerability, so the rule is:
+ * **resolve first, then verify the RESOLVED REAL path is still inside the mount.**
+ * Checking the string before resolving is the classic mistake — `..` segments,
+ * mixed separators and, most importantly, **symlinks** all defeat it. A symlink
+ * inside a mount pointing at `C:\Users\...\.ssh` is a file the container can
+ * create and this reader would happily follow.
+ *
+ * A review pane is not an exemption from containment.
+ */
+import type { RunChangeContent, RunContentReader } from './RunObservationService.js';
+/** One mount, as the run was granted it. */
+export interface MountBinding {
+    /** Host directory, e.g. `D:\work\repo`. */
+    source: string;
+    /** Container path it appears at, e.g. `/mnt/xeno/work`. */
+    target: string;
+}
+/**
+ * Supplies the pre-run bytes for a path.
+ *
+ * Separate from this reader because it CANNOT be a filesystem read of the same
+ * location: by the time a change is observed, the previous content is gone. It
+ * comes from something captured before the run — normally git's pre-run commit.
+ * Absent, review shows an "after" side only, which is honest and still useful.
+ */
+export interface RunBaselineContentSource {
+    read(containerPath: string): Promise<string | undefined> | string | undefined;
+}
+export interface MountContentReaderOptions {
+    mounts: MountBinding[];
+    baseline?: RunBaselineContentSource;
+    /**
+     * Largest file this will decode, in bytes.
+     *
+     * A cap rather than a preference: a review pane that reads a 2 GB artifact
+     * into the host's heap to render a hunk nobody asked for is a denial of
+     * service the agent can trigger by writing one file. Truncation is reported,
+     * never silent — a hunk cut off without saying so is a diff that lies.
+     */
+    maxBytes?: number;
+}
+export declare class MountContentReader implements RunContentReader {
+    #private;
+    constructor(options: MountContentReaderOptions);
+    read(path: string): Promise<RunChangeContent>;
+}
+//# sourceMappingURL=MountContentReader.d.ts.map

package/dist/observation/MountContentReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MountContentReader.d.ts","sourceRoot":"","sources":["../../src/observation/MountContentReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAEpF,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS,CAAA;CAC9E;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,YAAY,EAAE,CAAA;IACtB,QAAQ,CAAC,EAAE,wBAAwB,CAAA;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAMD,qBAAa,kBAAmB,YAAW,gBAAgB;;gBAK7C,OAAO,EAAE,yBAAyB;IASxC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CA4FpD"}

package/dist/observation/MountContentReader.js

@@ -0,0 +1,158 @@
+/**
+ * Reads review content off a run's mounts — the "after" half of §2.9 hunks.
+ *
+ * Lives in the `node` entry, not `index`, because it touches the filesystem and
+ * `index` is renderer-safe by convention in this package.
+ *
+ * ## Why this needs no sandbox call, and no `xeno-use` dependency
+ *
+ * A bind mount **is** the host directory. That is the same property the
+ * filesystem sensor already relies on to observe container writes from outside,
+ * so current content is an ordinary host-side read. No verb, no exec, no
+ * licensing entanglement (see the AGPL boundary noted on `RunObservationService`).
+ *
+ * ## Containment is the whole job
+ *
+ * This maps an agent-supplied container path onto a host path and then reads it.
+ * That is precisely the shape of a path-traversal vulnerability, so the rule is:
+ * **resolve first, then verify the RESOLVED REAL path is still inside the mount.**
+ * Checking the string before resolving is the classic mistake — `..` segments,
+ * mixed separators and, most importantly, **symlinks** all defeat it. A symlink
+ * inside a mount pointing at `C:\Users\...\.ssh` is a file the container can
+ * create and this reader would happily follow.
+ *
+ * A review pane is not an exemption from containment.
+ */
+import { readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+/** Git's own heuristic window for binary detection. */
+const BINARY_SNIFF_BYTES = 8_000;
+export class MountContentReader {
+    #mounts;
+    #baseline;
+    #maxBytes;
+    constructor(options) {
+        this.#mounts = options.mounts.map((mount) => ({
+            source: resolve(mount.source),
+            target: normaliseTarget(mount.target),
+        }));
+        this.#baseline = options.baseline;
+        this.#maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    }
+    async read(path) {
+        const hostPath = this.#toHostPath(path);
+        if (!hostPath) {
+            return {
+                path,
+                binary: false,
+                truncated: false,
+                refusal: 'path is not inside any mount granted to this run',
+            };
+        }
+        const before = await this.#readBaseline(path);
+        let after;
+        try {
+            after = await this.#readContained(hostPath);
+        }
+        catch (error) {
+            // A deleted file is the ORDINARY case here — the diff said `deleted`, so
+            // its absence is the expected finding rather than a failure. Anything
+            // else is reported as a refusal rather than swallowed into "no content",
+            // which would make a permissions problem look like an empty file.
+            const code = error.code;
+            if (code !== 'ENOENT') {
+                return {
+                    path,
+                    ...(before === undefined ? {} : { before }),
+                    binary: false,
+                    truncated: false,
+                    refusal: `could not read current content: ${code ?? 'unknown error'}`,
+                };
+            }
+        }
+        if (after === undefined) {
+            return { path, ...(before === undefined ? {} : { before }), binary: false, truncated: false };
+        }
+        if (isBinary(after)) {
+            // Deliberately no `after` string. Decoding binary to UTF-8 yields
+            // replacement characters that render as a plausible-looking text diff of
+            // something that was never text.
+            return { path, ...(before === undefined ? {} : { before }), binary: true, truncated: false };
+        }
+        const truncated = after.byteLength > this.#maxBytes;
+        return {
+            path,
+            ...(before === undefined ? {} : { before }),
+            after: after.subarray(0, this.#maxBytes).toString('utf8'),
+            binary: false,
+            truncated,
+        };
+    }
+    async #readBaseline(containerPath) {
+        if (!this.#baseline)
+            return undefined;
+        return (await this.#baseline.read(containerPath)) ?? undefined;
+    }
+    /**
+     * Reads a host path, re-verifying containment AFTER symlink resolution.
+     *
+     * The mapping in `#toHostPath` already rejects `..` escapes textually. This is
+     * the second check, and it is the one that catches a symlink the container
+     * planted inside its own mount — which the string check cannot see, because
+     * the string is entirely well-formed.
+     */
+    async #readContained(hostPath) {
+        const real = await realpath(hostPath);
+        if (!this.#mounts.some((mount) => isInside(mount.source, real))) {
+            const error = new Error('resolved path escapes its mount');
+            error.code = 'EACCES';
+            throw error;
+        }
+        return readFile(real);
+    }
+    /** Container path → host path, or `undefined` when it belongs to no mount. */
+    #toHostPath(containerPath) {
+        const normalised = containerPath.replace(/\\/g, '/');
+        for (const mount of this.#mounts) {
+            if (normalised === mount.target)
+                return mount.source;
+            if (!normalised.startsWith(`${mount.target}/`))
+                continue;
+            const relativePart = normalised.slice(mount.target.length + 1);
+            // Rejected BEFORE resolution rather than resolved and checked: a path
+            // containing `..` has no legitimate reason to reach a review pane, and
+            // refusing the input is clearer than proving the output happened to land
+            // somewhere acceptable.
+            if (relativePart.split('/').includes('..'))
+                return undefined;
+            const candidate = resolve(mount.source, relativePart);
+            if (!isInside(mount.source, candidate))
+                return undefined;
+            return candidate;
+        }
+        return undefined;
+    }
+}
+function normaliseTarget(target) {
+    const unified = target.replace(/\\/g, '/').replace(/\/+$/, '');
+    return unified === '' ? '/' : unified;
+}
+/**
+ * True when `candidate` is `root` or lies beneath it.
+ *
+ * Uses `relative` rather than `startsWith`, because `startsWith` reports
+ * `D:\work\repo-other` as inside `D:\work\repo` — the prefix bug that turns a
+ * scoped grant into a wider one.
+ */
+function isInside(root, candidate) {
+    if (root === candidate)
+        return true;
+    const rel = relative(root, candidate);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel) && !rel.startsWith(`..${sep}`);
+}
+/** A NUL byte in the first window means binary — git's heuristic. */
+function isBinary(content) {
+    return content.subarray(0, BINARY_SNIFF_BYTES).includes(0);
+}
+//# sourceMappingURL=MountContentReader.js.map

package/dist/observation/MountContentReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MountContentReader.js","sourceRoot":"","sources":["../../src/observation/MountContentReader.ts"],"names":[],"mappings":"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"}

package/dist/observation/RunObservationService.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Tier-1 run observation — the live producer behind §2.9's review capability.
+ *
+ * `RunDiff` (in `core`) folds a filesystem event stream into a net change set,
+ * `capabilityTier` says review is deliverable at tier 1 for ANY agent, and
+ * `xeno-use` emits the stream. All three existed and **nothing connected them**,
+ * which is the same "built, tested, unreachable" shape as xeno-workflow's 76
+ * node types and xeno-tools' never-called `install`. This is the connection.
+ *
+ * ## The source is a PORT, and that is a licensing boundary before it is a
+ * design preference
+ *
+ * 🔴 **`xeno-use` is AGPL-3.0** — it ships the AGPL text and its Cargo workspace
+ * declares `license = "AGPL-3.0-only"`. XENO Agent is proprietary. So this
+ * package must not import `@xeno-use/core`, link its N-API binding, or take it
+ * as a dependency in any direction, and neither may any composition that ships
+ * inside a proprietary installer.
+ *
+ * `RunObservationSource` is therefore declared HERE, provider-neutral, and an
+ * adapter is supplied from outside. That is the right design under either
+ * outcome of the open licence question: if `xeno-use` stays AGPL the adapter
+ * talks to it out of process over its own `/v1/use/*` surface — the consumption
+ * model it was built for — and if it is ever relicensed, an in-process adapter
+ * plugs into the identical port. The port is not a workaround for the licence;
+ * it is what makes the licence answer swappable.
+ *
+ * ## Completeness travels with the diff, never beside it
+ *
+ * A `RunChange[]` cannot say whether it is the whole story. A stream that
+ * dropped events yields a *shorter* diff, not an error — and a shorter diff is
+ * the most dangerous possible output here, because a reviewer reads "3 files
+ * changed" and approves. This is the same rule `SandboxObservation` applies one
+ * layer down, and it has to be re-applied here rather than assumed: the
+ * completeness signal does not survive a fold unless the fold carries it.
+ */
+import { type CapabilityResolution, type CapabilitySources, type KnownCapability, type LandingOverlapReport, type RunChange, type RunFileEvent } from '@xenosystem/agent-interface-core';
+/**
+ * One bounded drain from a run's sandbox.
+ *
+ * Mirrors what `xeno-use`'s observation surface returns, as a SHAPE rather than
+ * an import — three event kinds and four completeness facts. Redeclaring it is
+ * what keeps the AGPL boundary intact; there is nothing here that could be
+ * imported instead without creating the linkage this port exists to avoid.
+ */
+export interface RunObservationBatch {
+    events: RunFileEvent[];
+    /** The per-call bound was hit; drain again. Not a loss. */
+    morePending?: boolean;
+    /** Observation is known to be incomplete. */
+    degraded?: boolean;
+    /** Events the sandbox's backlog refused. These will never arrive. */
+    droppedEvents?: number;
+    /** Why, in prose, for a human. */
+    problems?: string[];
+}
+export interface RunObservationSource {
+    /** Drains at most `maxEvents`. May be async: a real source crosses a process
+     *  or network boundary, and a synchronous port would force every adapter to
+     *  block on it. */
+    drain(maxEvents: number): RunObservationBatch | Promise<RunObservationBatch>;
+}
+/**
+ * Content for one changed path — §2.9 hunk-level review.
+ *
+ * `before` and `after` are independently optional because they fail for
+ * different reasons: `after` is absent for a deleted file, `before` for an added
+ * one, and either can be refused. `refusal` says WHICH, because a reviewer
+ * shown an empty pane must be able to tell "this file is empty" from "we would
+ * not read this".
+ */
+export interface RunChangeContent {
+    path: string;
+    before?: string;
+    after?: string;
+    /** Content was not decoded as text. Never partially rendered as a hunk. */
+    binary: boolean;
+    /** Content exceeded the read cap and is cut short. */
+    truncated: boolean;
+    /** Present when a side could not be produced, in terms a human can act on. */
+    refusal?: string;
+}
+/**
+ * Resolves file content for review.
+ *
+ * A PORT, like `RunObservationSource`, and for the same licensing reason — but
+ * note the asymmetry the spec records: the **after** side needs no sandbox call
+ * at all, because a bind mount IS the host directory. The **before** side
+ * cannot come from the sandbox even in principle: by the time the watcher
+ * reports a write, the previous bytes are gone. It has to come from something
+ * captured before the run — git, normally.
+ */
+export interface RunContentReader {
+    read(path: string): RunChangeContent | Promise<RunChangeContent>;
+}
+/** A run's net changes, WITH whether they are the whole story. */
+export interface RunObservationSnapshot {
+    runId: string;
+    changes: RunChange[];
+    /**
+     * False when anything is known to have been missed. A surface must not
+     * present an incomplete diff as a review — §2.9's whole claim is that tier 1
+     * yields "a real diff", and a diff that quietly omits changes is worse than
+     * no diff, because a reviewer acts on it.
+     */
+    complete: boolean;
+    droppedEvents: number;
+    problems: string[];
+}
+/** What goes on the host event feed. Counts, never contents. */
+export interface RunObservationSummary {
+    runId: string;
+    added: number;
+    modified: number;
+    deleted: number;
+    complete: boolean;
+    droppedEvents: number;
+}
+export interface RunObservationServiceOptions {
+    /**
+     * Events per drain, and drains per poll. Both bounded, for the reason the
+     * sandbox's own drain is bounded: a poll that loops until a busy run stops
+     * producing does not return, and "wait for the filesystem to go quiet" is not
+     * a termination condition.
+     */
+    maxEventsPerDrain?: number;
+    maxDrainsPerPoll?: number;
+    emit?: (summary: RunObservationSummary) => void;
+}
+export declare class RunObservationService {
+    #private;
+    constructor(options?: RunObservationServiceOptions);
+    /** Mirrors `CoordinationService.setEventSink` — the host is constructed with
+     *  its services, so a sink fixed at construction could not be the host. */
+    setEventSink(emit: (summary: RunObservationSummary) => void): void;
+    /**
+     * Begins observing a run.
+     *
+     * `baseline` is the set of paths that existed when the run started. Its
+     * ABSENCE is meaningful and not a default: with no baseline every modified
+     * file reports as `added`, because nothing says it was there before. Callers
+     * that cannot supply one get a diff that is still useful and still honest —
+     * `added` really does mean "this run touched a path we have no prior record
+     * of" — but they should know that is what they are reading.
+     */
+    observe(runId: string, source: RunObservationSource, options?: {
+        baseline?: Iterable<string>;
+        content?: RunContentReader;
+        /**
+         * Observation began already knowing it is imperfect.
+         *
+         * The case this exists for is a baseline that could not be established:
+         * without one, files that existed before the run report as `added`, so the
+         * diff is not merely shorter — it attributes existing work to the agent.
+         * That is a completeness fact known at registration, and the only
+         * alternative to carrying it is discovering it during review.
+         */
+        degraded?: boolean;
+        /** Why, in prose, for the human who will read the snapshot. */
+        problems?: Iterable<string>;
+    }): void;
+    /**
+     * Content for one changed path, for hunk-level review.
+     *
+     * ⚠️ **A SNAPSHOT, not the state at the event.** The agent may have written
+     * again between the change being observed and this read, so a hunk view can
+     * disagree with the change list that prompted it. That is inherent to sampling
+     * a live filesystem rather than a defect to engineer away — but it means a
+     * surface must never label this "what the agent did at 10:04:03".
+     *
+     * Refuses a path the run has not actually changed. Reading arbitrary paths
+     * through a review API would turn a review pane into a file browser scoped to
+     * the sandbox, which is a different capability with a different consent story.
+     */
+    readChange(runId: string, path: string): Promise<RunChangeContent | undefined>;
+    stopObserving(runId: string): void;
+    observedRuns(): string[];
+    /**
+     * Drains what the sandbox has produced and folds it in.
+     *
+     * Returns the snapshot rather than only emitting it, so a caller that wants
+     * the answer does not have to subscribe to learn the result of its own call.
+     */
+    poll(runId: string): Promise<RunObservationSnapshot | undefined>;
+    /**
+     * What a run can deliver for a capability, and from which tier.
+     *
+     * §8: *"Reporting them unavailable for a third-party agent is a defect, not
+     * honest degradation — the data is in the sandbox."* This is the only place
+     * that can answer honestly, because it is the only place that knows whether a
+     * sandbox is actually being observed for this run — so the answer is DERIVED
+     * from that fact rather than configured.
+     *
+     * `acp` and `vendorSideChannel` are passed in by the caller, which knows what
+     * the run's provider supports. Absent, the answer is the tier-1 one: correct
+     * for a third-party agent in `native-tui`, which is the case §2.9 exists for.
+     */
+    capabilityFor(runId: string, capability: KnownCapability, sources?: Partial<Omit<CapabilitySources, 'sandboxObservation'>>): CapabilityResolution;
+    /**
+     * Where the observed runs collide — §5.7 conflict-aware landing.
+     *
+     * Computed from OBSERVED diffs rather than from claims, because nothing forces
+     * an agent to claim a path before writing it, and the agent that surprises us
+     * is exactly the one whose overlap matters. Claims remain complementary: pass
+     * them in and the report says whether a collision was invisible to the
+     * registry or whether a claim was released.
+     *
+     * Available *while the runs are alive*, which is the point — after the merge
+     * it is archaeology. Completeness rides along: a run with a hole in its diff
+     * cannot rule out an overlap, and `mayLand` refuses on that rather than
+     * reporting a clean landing it did not measure.
+     */
+    landingOverlaps(claimedPathsByRun?: Record<string, string[]>, 
+    /**
+     * 🔴 Runs the CALLER knows exist. Any of them this service never observed
+     * makes the report incomplete, so `mayLand` refuses.
+     *
+     * This rule lives HERE, not in the caller, because it was in the caller
+     * once and the shipping landing gate bypassed it: `apps/desktop` calls this
+     * method directly while the host's RPC reader had its own copy of the check.
+     * The surface told the truth and the gate that actually merges did not —
+     * so the rule belongs where every caller passes through.
+     *
+     * A caller that knows of no other runs passes nothing and loses nothing.
+     */
+    knownRunIds?: readonly string[]): LandingOverlapReport;
+    /** The current diff without draining. */
+    snapshot(runId: string): RunObservationSnapshot | undefined;
+}
+//# sourceMappingURL=RunObservationService.d.ts.map

package/dist/observation/RunObservationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunObservationService.d.ts","sourceRoot":"","sources":["../../src/observation/RunObservationService.ts"],"names":[],"mappings":"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"}