rea-agents 6.2.0 → 6.4.0

package/dist/reference/ReferenceSourceReaderEntries.js

@@ -1,7 +1,9 @@
-import { readdir, readlink, realpath } from "node:fs/promises";
+import { opendir, readlink, realpath } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
-import { cancelled, entryFailure, filesystemFailureDetail, safeSize, } from "./ReferenceSourceReaderErrors.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js";
+import { err, ok } from "../domain/result.js";
+import { cancelled, entryFailure, failure, filesystemFailureDetail, safeSize, } from "./ReferenceSourceReaderErrors.js";
 import { isPathWithinRoot } from "../domain/localPath.js";
 import { pathFromRoot } from "./ReferenceSourceReaderPaths.js";
 import { readStableFile } from "./ReferenceSourceReaderFile.js";
@@ -15,15 +17,76 @@ export const traverseDirectory = async (state, current) => {
         state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", before.code, before.message));
         return { ok: true, value: undefined };
     }
-    const names = await readDirectoryNames(current.path);
+    const directories = [];
+    let readFailure;
+    let handle;
+    try {
+        handle = await opendir(current.path);
+    }
+    catch (cause) {
+        readFailure = directoryReadFailure(cause);
+    }
+    if (handle !== undefined) {
+        const owner = new OwnedDirectoryHandle(handle);
+        let result = ok(undefined);
+        let cleanup;
+        try {
+            for (;;) {
+                let child;
+                try {
+                    child = await handle.read();
+                }
+                catch (cause) {
+                    readFailure = directoryReadFailure(cause);
+                    break;
+                }
+                if (child === null)
+                    break;
+                result = await processEntry(state, current, child.name, directories);
+                if (!result.ok)
+                    break;
+            }
+        }
+        finally {
+            cleanup = await state.resources.release({
+                kind: "directory-handle",
+                handle: owner,
+                resource: current.path,
+            });
+        }
+        if (cleanup.kind === "failed") {
+            if (result.ok && !isAborted(state.signal) && readFailure !== undefined)
+                state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "io", readFailure));
+            const observation = ArtifactReaderFailure.cleanupObservation(cleanup.cause, current.path);
+            const previous = result.ok ? undefined : result.error.cleanup;
+            const primary = result.ok
+                ? isAborted(state.signal)
+                    ? cancelled()
+                    : failure("io", readFailure ??
+                        `Reference directory cleanup failed: ${current.path}`)
+                : result.error;
+            return err({
+                ...primary,
+                cleanup: previous === undefined
+                    ? observation
+                    : {
+                        reason: `${previous.reason}; ${observation.reason}`,
+                        resources: [
+                            ...new Set([...previous.resources, ...observation.resources]),
+                        ],
+                    },
+                cause: primary.cause ?? cleanup.cause,
+            });
+        }
+        if (!result.ok)
+            return result;
+    }
     if (isAborted(state.signal))
         return { ok: false, error: cancelled() };
-    if (!names.ok) {
-        state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "io", names.message));
+    if (readFailure !== undefined) {
+        state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "io", readFailure));
         return { ok: true, value: undefined };
     }
-    if (isAborted(state.signal))
-        return { ok: false, error: cancelled() };
     const after = await validateDirectory(state.root, state.rootIdentity, current.path, state.signal);
     if (isAborted(state.signal))
         return { ok: false, error: cancelled() };
@@ -37,29 +100,15 @@ export const traverseDirectory = async (state, current) => {
             kind: "directory",
             path: pathFromRoot(state.root, current.path),
         });
-    const directories = [];
-    for (const name of names.value) {
-        const result = await processEntry(state, current, name, directories);
-        if (!result.ok)
-            return result;
-    }
     directories.reverse();
     state.pending.push(...directories);
     return { ok: true, value: undefined };
 };
-const readDirectoryNames = async (path) => {
-    try {
-        return {
-            ok: true,
-            value: (await readdir(path)).sort(compareUnicodeCodePoints),
-        };
-    }
-    catch (cause) {
-        const message = filesystemFailureDetail(cause, "Directory could not be read");
-        if (message === undefined)
-            throw cause;
-        return { ok: false, message };
-    }
+const directoryReadFailure = (cause) => {
+    const message = filesystemFailureDetail(cause, "Directory could not be read");
+    if (message === undefined)
+        throw cause;
+    return message;
 };
 const readMetadata = async (path) => {
     try {
@@ -77,18 +126,6 @@ const processEntry = async (state, current, name, directories) => {
         return { ok: false, error: cancelled() };
     const absolute = join(current.path, name);
     const path = pathFromRoot(state.root, absolute);
-    const excluded = applyExclusion(state.shouldExclude, path);
-    if (!excluded.ok)
-        return {
-            ok: false,
-            error: {
-                tag: "reference-source-reader",
-                code: "io",
-                message: "Reference source exclusion check failed",
-            },
-        };
-    if (excluded.value)
-        return { ok: true, value: undefined };
     const metadata = await readMetadata(absolute);
     if (isAborted(state.signal))
         return { ok: false, error: cancelled() };
@@ -96,28 +133,41 @@ const processEntry = async (state, current, name, directories) => {
         state.entries.push(entryFailure(path, "unknown", "io", metadata.message));
         return { ok: true, value: undefined };
     }
-    if (isAborted(state.signal))
+    const kind = metadata.value.isSymbolicLink()
+        ? "symlink"
+        : metadata.value.isDirectory()
+            ? "directory"
+            : metadata.value.isFile()
+                ? "file"
+                : "other";
+    const excluded = applyExclusion(state.shouldExclude, path, kind);
+    if (!excluded.ok)
         return {
             ok: false,
             error: {
                 tag: "reference-source-reader",
-                code: "cancelled",
-                message: "Reference source traversal cancelled",
+                code: "io",
+                message: "Reference source exclusion check failed",
             },
         };
-    if (metadata.value.isSymbolicLink())
+    if (excluded.value)
+        return { ok: true, value: undefined };
+    if (isAborted(state.signal))
+        return { ok: false, error: cancelled() };
+    if (kind === "symlink")
         state.entries.push(await describeSymlink(state.root, absolute, path, state.signal));
-    else if (metadata.value.isDirectory()) {
+    else if (kind === "directory") {
         directories.push({ path: absolute });
     }
-    else if (!metadata.value.isFile())
+    else if (kind !== "file")
         state.entries.push(entryFailure(path, "other", "unsupported", "Entry is not a regular file", safeSize(metadata.value.size)));
     else
-        await processFileEntry(state, absolute, path, metadata.value);
+        return processFileEntry(state, absolute, path, metadata.value);
     return { ok: true, value: undefined };
 };
 const processFileEntry = async (state, absolute, path, metadata) => {
     const result = await readStableFile({
+        resources: state.resources,
         root: state.root,
         rootIdentity: state.rootIdentity,
         absolute,
@@ -125,9 +175,22 @@ const processFileEntry = async (state, absolute, path, metadata) => {
         expected: metadata,
         ...(state.signal === undefined ? {} : { signal: state.signal }),
     });
-    if (result.status === "read" && result.kind === "file")
-        state.bytesRead += result.bytes.byteLength;
-    state.entries.push(result);
+    const { entry } = result;
+    if (entry.status === "read" && entry.kind === "file")
+        state.bytesRead += entry.bytes.byteLength;
+    state.entries.push(entry);
+    if (result.cleanup !== undefined)
+        return err({
+            tag: "reference-source-reader",
+            code: entry.status === "failed" && entry.code === "cancelled"
+                ? "cancelled"
+                : "io",
+            message: entry.status === "failed"
+                ? entry.message
+                : `Reference file cleanup failed: ${path}`,
+            cleanup: result.cleanup,
+        });
+    return ok(undefined);
 };
 const describeSymlink = async (root, absolute, path, signal) => {
     try {
@@ -190,9 +253,9 @@ const describeSymlink = async (root, absolute, path, signal) => {
         return entryFailure(path, "symlink", "io", message);
     }
 };
-const applyExclusion = (shouldExclude, path) => {
+const applyExclusion = (shouldExclude, path, kind) => {
     try {
-        return { ok: true, value: shouldExclude?.(path) === true };
+        return { ok: true, value: shouldExclude?.(path, kind) === true };
     }
     catch (cause) {
         // Exclusion predicates are caller-supplied; a throwing predicate fails

package/dist/reference/ReferenceSourceReaderErrors.js

@@ -33,6 +33,18 @@ export const filesystemFailureDetail = (cause, operation) => {
         ? `${operation}: ${cause.message}`
         : undefined;
 };
+/** Preserve root I/O detail while separating bad selections from access failures. */
+export const rootFilesystemFailure = (cause, operation) => {
+    if (!(cause instanceof Error))
+        return undefined;
+    const code = Reflect.get(cause, "code");
+    if (typeof code !== "string" || !FILESYSTEM_ERROR_CODES.has(code))
+        return undefined;
+    return {
+        code: code === "ENOENT" || code === "ENOTDIR" ? "invalid-root" : "io",
+        message: `${operation}: ${cause.message}`,
+    };
+};
 export const entryFailure = (...[path, kind, code, message, size]) => ({
     status: "failed",
     kind,

package/dist/reference/ReferenceSourceReaderFile.js

@@ -1,6 +1,7 @@
-import { constants } from "node:fs";
-import { open } from "node:fs/promises";
 import { dirname } from "node:path";
+import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { entryFailure, filesystemFailureDetail, safeSize, } from "./ReferenceSourceReaderErrors.js";
 import { isAborted, sameFile, validateDirectory, } from "./ReferenceSourceReaderValidate.js";
 import {} from "./ReferenceSourceReaderTypes.js";
@@ -22,7 +23,8 @@ const prepareFileRead = async (request, handle) => {
     }
     return { status: "ready", before };
 };
-const readFileContents = async (request) => {
+/** Read a stable-size file through its borrowed descriptor; growth is a change. */
+export const readFileContents = async (request) => {
     const { handle, path, signal } = request;
     const chunks = [];
     let total = 0;
@@ -32,7 +34,12 @@ const readFileContents = async (request) => {
                 status: "failed",
                 entry: entryFailure(path, "file", "cancelled", "File read cancelled", total),
             };
-        const chunk = Buffer.allocUnsafe(READ_CHUNK_BYTES);
+        // One extra byte detects growth without allocating a full chunk at EOF.
+        const remaining = request.expectedSize - BigInt(total);
+        const chunkBytes = remaining >= BigInt(READ_CHUNK_BYTES)
+            ? READ_CHUNK_BYTES
+            : Number(remaining) + 1;
+        const chunk = Buffer.allocUnsafe(chunkBytes);
         const read = await handle.read(chunk, 0, chunk.byteLength, null);
         if (isAborted(signal))
             return {
@@ -42,6 +49,11 @@ const readFileContents = async (request) => {
         if (read.bytesRead === 0)
             break;
         total += read.bytesRead;
+        if (BigInt(total) > request.expectedSize)
+            return {
+                status: "failed",
+                entry: entryFailure(path, "file", "changed", "File grew while it was read", total),
+            };
         chunks.push(chunk.subarray(0, read.bytesRead));
     }
     return { status: "ok", chunks, total };
@@ -63,19 +75,45 @@ const finalizeFileRead = async (request) => {
     };
 };
 export const readStableFile = async (request) => {
+    let owner;
+    let cleanup;
+    let entry;
+    try {
+        entry = await readStableFileEntry(request, (admitted) => {
+            owner = admitted;
+        });
+    }
+    finally {
+        if (owner !== undefined) {
+            const result = await request.resources.release({
+                kind: "file-handle",
+                handle: owner,
+                resource: request.absolute,
+            });
+            if (result.kind === "failed")
+                cleanup = ArtifactReaderFailure.cleanupObservation(result.cause, request.absolute);
+        }
+    }
+    return { entry, ...(cleanup === undefined ? {} : { cleanup }) };
+};
+const readStableFileEntry = async (request, retain) => {
     const { root, rootIdentity, absolute, path, expected, signal } = request;
-    let handle;
     try {
         const parentBefore = await validateDirectory(root, rootIdentity, dirname(absolute), signal);
         if (!parentBefore.ok)
             return entryFailure(path, "file", parentBefore.code, parentBefore.message, safeSize(expected.size));
-        handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const handle = await openRegularFile(absolute, {
+            symlinks: "reject",
+            signal,
+        });
+        retain(new OwnedFileHandle(handle));
         const prepared = await prepareFileRead(request, handle);
         if (prepared.status === "failed")
             return prepared.entry;
         const contents = await readFileContents({
             handle,
             path,
+            expectedSize: prepared.before.size,
             ...(signal === undefined ? {} : { signal }),
         });
         if (contents.status === "failed")
@@ -94,15 +132,17 @@ export const readStableFile = async (request) => {
         });
     }
     catch (cause) {
+        if (cause instanceof RegularFileAdmissionFailure) {
+            retain(cause.owner);
+            cause = cause.cause;
+        }
         if (isAborted(signal))
             return entryFailure(path, "file", "cancelled", "File read cancelled", safeSize(expected.size));
+        if (cause instanceof NonRegularFileReadError)
+            return entryFailure(path, "file", "changed", "File is no longer a regular file", safeSize(expected.size));
         const message = filesystemFailureDetail(cause, "File could not be read safely");
         if (message === undefined)
             throw cause;
         return entryFailure(path, "file", "io", message, safeSize(expected.size));
     }
-    finally {
-        // best-effort cleanup: file-handle close must not mask the read result.
-        await handle?.close().catch(() => undefined);
-    }
 };

package/dist/reference/ReferenceSourceReaderValidate.js

@@ -1,7 +1,7 @@
 import { constants } from "node:fs";
 import { lstat, realpath } from "node:fs/promises";
 import { err, ok } from "../domain/result.js";
-import { cancelled, failure, filesystemFailureDetail, } from "./ReferenceSourceReaderErrors.js";
+import { cancelled, failure, filesystemFailureDetail, rootFilesystemFailure, } from "./ReferenceSourceReaderErrors.js";
 import { isPathWithinRoot } from "../domain/localPath.js";
 import {} from "./ReferenceSourceReaderTypes.js";
 export const bigLstat = (path) => lstat(path, { bigint: true });
@@ -74,9 +74,9 @@ export const prepareRoot = async (root, signal) => {
     catch (cause) {
         if (isAborted(signal))
             return err(cancelled());
-        const message = filesystemFailureDetail(cause, "Reference source root could not be resolved");
-        if (message === undefined)
+        const rootFailure = rootFilesystemFailure(cause, "Reference source root could not be resolved");
+        if (rootFailure === undefined)
             throw cause;
-        return err(failure("invalid-root", `${message}: ${root}`));
+        return err(failure(rootFailure.code, `${rootFailure.message}: ${root}`));
     }
 };

package/dist/server/EvidenceMcpServer.js

@@ -1,18 +1,53 @@
 import { McpServer, isCallToolResult, isJSONRPCRequest, isJSONRPCNotification, isJSONRPCResultResponse, } from "@modelcontextprotocol/server";
 import { analysisErrorProjectionSchema } from "../contracts/errorSchemas.js";
+import { compactAdvertisedInputSchema } from "../contracts/compactInputSchema.js";
+import { transformAdvertisedInputJsonSchema } from "../contracts/toolSchemaMetadata.js";
 import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { encodeToolResult } from "./toolResultEncoding.js";
+/** A Zod schema whose standard interface exposes a JSON Schema projection. */
+const hasAdvertisedInputJsonSchema = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const standard = Reflect.get(value, "~standard");
+    if (typeof standard !== "object" || standard === null)
+        return false;
+    const jsonSchema = Reflect.get(standard, "jsonSchema");
+    return (typeof jsonSchema === "object" &&
+        jsonSchema !== null &&
+        Reflect.get(jsonSchema, "input") !== undefined);
+};
 /** Bind oversized MCP error recovery to this server's Evidence ledger. */
 export class EvidenceMcpServer extends McpServer {
     recordEvidence;
     delivery;
-    constructor(info, options, recordEvidence, delivery) {
+    compactPresentation;
+    constructor(info, options, recordEvidence, delivery, compactPresentation = undefined) {
         super(info, options);
         this.recordEvidence = recordEvidence;
         this.delivery = delivery;
+        this.compactPresentation = compactPresentation;
+    }
+    /**
+     * Compact the advertised input schema of every registered tool when the
+     * compact profile is active. The registered canonical schema, its parser,
+     * and output schemas are untouched; only the advertised JSON Schema
+     * projection is rendered within the provider's per-schema size budget.
+     * The signatures mirror the SDK's registrations so call sites keep their
+     * inferred handler argument types.
+     */
+    registerTool(name, config, callback) {
+        const budget = this.compactPresentation?.budgetBytes;
+        const inputSchema = budget !== undefined &&
+            config !== undefined &&
+            hasAdvertisedInputJsonSchema(config.inputSchema)
+            ? transformAdvertisedInputJsonSchema(config.inputSchema, (projected) => compactAdvertisedInputSchema(projected, budget).schema)
+            : undefined;
+        return super.registerTool(name, (inputSchema === undefined
+            ? config
+            : { ...config, inputSchema }), callback);
     }
     /** Preserve the SDK transport lifecycle while retaining oversized errors. */
     connect(transport) {

package/dist/server/admittedToolOperation.js

@@ -0,0 +1,9 @@
+/** Run one complete tool workflow inside session admission when supplied. */
+export const runAdmittedToolOperation = async (server, admission, operationName, signal, operation) => {
+    if (admission === undefined)
+        return operation();
+    const admitted = await admission(operationName, signal, operation);
+    return admitted.ok
+        ? admitted.value
+        : server.delivery.toErrorToolResult(admitted.error);
+};

package/dist/server/analysisAdmission.js

@@ -0,0 +1,8 @@
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+/** Run against the source's explicit owner, admitting session-scoped work. */
+export const withAdmittedAnalysis = (source) => source.kind === "session"
+    ? (operationName, signal, operation) => source.session.withAdmittedAnalysis(operationName, signal, operation)
+    : async (operationName, signal, operation) => signal?.aborted === true
+        ? err(new AnalysisCancelledError(operationName))
+        : ok(await operation(source.analysis));

package/dist/server/contractToolHandler.js

@@ -0,0 +1,21 @@
+import { logToolExecution } from "./toolLogging.js";
+import { runAdmittedToolOperation } from "./admittedToolOperation.js";
+/**
+ * Bind one service-backed handler to its exact named contract through the
+ * shared log/execute/record/deliver workflow.
+ */
+export const createContractToolHandler = (server, service, logger, recordEvidence, withAdmittedAnalysis) => (contract) => createEvidenceToolHandler(server, (input, options) => service.execute(contract.name, input, options), logger, recordEvidence, withAdmittedAnalysis)(contract);
+/** Bind a named Evidence-producing operation to shared logging and delivery. */
+export const createEvidenceToolHandler = (server, operation, logger, recordEvidence, withAdmittedAnalysis) => (contract) => {
+    const name = contract.name;
+    return async (input, context) => {
+        const executeAndRecord = async () => {
+            const result = await logToolExecution(logger, name, () => operation(input, { signal: context.mcpReq.signal }));
+            if (!result.ok)
+                return server.delivery.toCallToolResult(result, contract);
+            const recorded = recordEvidence?.(result.value);
+            return server.delivery.toEvidenceToolResult(result.value, contract, recorded);
+        };
+        return runAdmittedToolOperation(server, withAdmittedAnalysis, name, context.mcpReq.signal, executeAndRecord);
+    };
+};