@sema-agent/core 7.41.0 → 7.42.0

package/dist/tools/fs/dir-entries.js

@@ -0,0 +1,60 @@
+import { homeViewsOf } from "./read-deny-home.js";
+export const DIRECTORY_LISTING_MAX_ENTRIES = 1000;
+export function createEntryDenyJudge(env, deny, signal) {
+    const views = homeViewsOf(env, deny, signal);
+    return async (path, leaf) => {
+        const hit = deny.matchPath(path);
+        if (hit)
+            return hit;
+        const view = await views.of(path, leaf !== undefined ? { leaf } : undefined);
+        return view !== undefined ? deny.matchPath(view) : null;
+    };
+}
+export async function enumerateDirectory(env, dir, judge, signal) {
+    const listing = await env.listDir(dir, signal);
+    if (!listing.ok)
+        return listing;
+    const infos = [...listing.value].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const kept = [];
+    let omitted = 0;
+    const omittedPatterns = [];
+    let incomplete = false;
+    for (const info of infos) {
+        if (signal?.aborted) {
+            incomplete = true;
+            break;
+        }
+        const hit = judge === undefined ? null : await judge(info.path, info.kind === "directory" ? undefined : "file");
+        if (hit) {
+            omitted++;
+            if (!omittedPatterns.includes(hit.pattern))
+                omittedPatterns.push(hit.pattern);
+            continue;
+        }
+        kept.push({ name: info.name, kind: info.kind });
+    }
+    return {
+        ok: true,
+        value: {
+            entries: kept.slice(0, DIRECTORY_LISTING_MAX_ENTRIES),
+            more: Math.max(0, kept.length - DIRECTORY_LISTING_MAX_ENTRIES),
+            omitted,
+            omittedPatterns,
+            incomplete,
+        },
+    };
+}
+const LABEL_UNSAFE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+export function quoteDataLabel(label) {
+    let out = "";
+    for (const ch of JSON.stringify(label)) {
+        out += LABEL_UNSAFE.test(ch) ? `\\u${ch.codePointAt(0).toString(16).padStart(4, "0")}` : ch;
+    }
+    return out;
+}
+export function renderDirectoryListing(l) {
+    const lines = l.entries.map((e) => `${LABEL_UNSAFE.test(e.name) ? quoteDataLabel(e.name) : e.name}${e.kind === "directory" ? "/" : ""}`);
+    if (l.more > 0)
+        lines.push(`… and ${l.more} more entries`);
+    return lines.join("\n");
+}

package/dist/tools/fs/fs-pdf.d.ts

@@ -1,18 +1,18 @@
-import { errorResult } from "../../core/tools.js";
 import type { DocumentContent, ImageContent, TextContent } from "../../internal/llm.js";
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { type PdfModelCapabilities } from "./pdf.js";
 import { type ReadImageDownsamplerOption } from "./fs-shared.js";
-import { type ReminderDisclosureCounts } from "../../core/reminder-disclosure.js";
-/** The Read tool's disclosure state, threaded into the PDF TEXT legs (the
- *  two `pdftotext` extraction arms — the only PDF returns with a model-facing text projection of
- *  the document; the native document block and rendered page images have no text to scan). Shares
- *  the Read closure's throttle windows so a PDF and its text read dedup on the same file key. */
+import { type ReminderDisclosureEffects } from "../../core/reminder-disclosure.js";
+/** The reader's disclosure state, threaded into the PDF TEXT legs (the two `pdftotext` extraction arms —
+ *  the only PDF returns with a model-facing text projection of the document; the native document block and
+ *  rendered page images have no text to scan). Shares the reader's throttle windows so a PDF and its text
+ *  read dedup on the same file key. The windows are READ here and never advanced: each planned
+ *  disclosure's effects are pushed onto `effects`, and the reader commits them with the delivery. */
 export interface PdfReminderDisclosure {
     mark: string | undefined;
     windows: Map<string, number>;
     key: string;
-    counts?: ReminderDisclosureCounts;
+    effects: ReminderDisclosureEffects[];
 }
 export { pdfModelCapabilitiesOf, type PdfModelCapabilities } from "./pdf.js";
 /** What the Read tool's PDF pipeline returns (document block, or rendered page images, or an error string). */
@@ -45,7 +45,3 @@ type ReadPdfReturn = string | {
  * `caps` absent ⇒ fully capable (native document block; the brain placeholder still guards).
  */
 export declare function readPdfFile(env: ExecutionEnv, path: string, key: string, pages: string | undefined, signal: AbortSignal | undefined, downsamplerOpt: ReadImageDownsamplerOption, cwd: string, preRead?: Uint8Array, caps?: PdfModelCapabilities, readDeny?: import("./read-deny.js").ReadDenyMatcher, disclosure?: PdfReminderDisclosure): Promise<ReadPdfReturn>;
-/** readPdfFile's own return type stays `ReadPdfReturn` (its INTERNAL string-means-error dispatch
- *  contract, shared with pdfPagesToImageBlocks) — the isError flag is applied once, here, at the tool's
- *  actual execute() boundary, not inside the helper. */
-export declare function pdfResultToToolReturn(r: ReadPdfReturn): ReturnType<typeof errorResult> | Exclude<ReadPdfReturn, string>;

package/dist/tools/fs/fs-pdf.js

@@ -1,21 +1,15 @@
-import { errorResult } from "../../core/tools.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
 import { PDF_FALLBACK_RENDER_PAGES, PDF_INLINE_PAGE_THRESHOLD, PDF_MAX_EXTRACT_SIZE, PDF_MAX_PAGES_PER_READ, PDF_TARGET_RAW_SIZE, extractPdfPagesAsImages, extractPdfTextLayer, getPdfPageCount, parsePdfPageRange, pdfMagicMatches, } from "./pdf.js";
 import { resolveAutoDownsampler, enoentMessage, MAX_READ_BYTES } from "./fs-shared.js";
-import { discloseReminderShaped } from "../../core/reminder-disclosure.js";
+import { planReminderDisclosure, renderReminderDisclosureTrailer } from "../../core/reminder-disclosure.js";
 function pdfDisclosureTrailer(body, d) {
     if (d === undefined)
         return "";
-    const out = discloseReminderShaped({
-        segments: [body],
-        mark: d.mark,
-        outlet: "pdf",
-        defuseExactMark: false,
-        throttle: { key: d.key, windows: d.windows },
-        counts: d.counts,
-    });
-    return out.trailer !== undefined ? `\n${out.trailer}` : "";
+    const plan = planReminderDisclosure({ segments: [body], mark: d.mark, outlet: "pdf", defuseExactMark: false, throttle: { key: d.key, windows: d.windows } });
+    d.effects.push(plan.effects);
+    const trailer = renderReminderDisclosureTrailer(plan.verdict, d.mark);
+    return trailer !== undefined ? `\n${trailer}` : "";
 }
 export { pdfModelCapabilitiesOf } from "./pdf.js";
 async function pdfPagesToImageBlocks(pages, path, downsamplerOpt) {
@@ -245,6 +239,3 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
         },
     };
 }
-export function pdfResultToToolReturn(r) {
-    return typeof r === "string" ? errorResult(r) : r;
-}

package/dist/tools/fs/fs-read.d.ts

@@ -1,8 +1,179 @@
+import type { DocumentContent, ImageContent, TextContent } from "../../internal/llm.js";
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import { type ReadFileState, type RootsSeat } from "./safety.js";
+import { errorResult } from "../../core/tools.js";
+import type { ToolReturn } from "../../core/tool-spec.js";
+import { type ReadEntry, type ReadFileState, type RootsSeat } from "./safety.js";
+import { type ImageDimensions } from "../../core/mcp.js";
 import { type PdfModelCapabilities } from "./pdf.js";
 import { type ReadImageDownsamplerOption, type CwdRef } from "./fs-shared.js";
-import { type ReminderDisclosureCounts } from "../../core/reminder-disclosure.js";
+import { type ReminderDisclosureCounts, type ReminderDisclosureEffects, type ReminderDisclosureVerdict } from "../../core/reminder-disclosure.js";
+/**
+ * The Read tool, and the ONE read of a file for the model it is built on, split into three steps so every
+ * carrier shares it:
+ *
+ *   readForModel(args) → a value: the external data blocks, the engine's STRUCTURED notes about the read,
+ *                        the read-state observation, the deferred effects, an outcome word;
+ *   commit(result)     → the side effects, applied when the carrier actually delivers the result (the
+ *                        read-state entry, the disclosure throttle windows and counters);
+ *   render             → per carrier. {@link renderReadToolResult} is the Read tool's: it reproduces the
+ *                        tool result byte for byte (the Read pins are the proof); a carrier that delivers
+ *                        a file somewhere else renders the same notes in its own words.
+ *
+ * `readForModel` is side-effect free toward the run: it reads the filesystem (and, on the PDF lane, runs
+ * the poppler readers), it READS the read state and the throttle windows, and it writes neither.
+ *
+ * What is DATA and what is a NOTE. `data` holds what the file itself supplies, in order — the
+ * line-numbered body, the notebook cell blocks, the image block. Everything the engine says ABOUT the
+ * read (empty file, offset past the end, already in context, unchanged since the last read, the range
+ * header, the partial-view marker, the corrupt-notebook prefix, the 0-cell placeholder, the resize
+ * coordinates, the disclosure verdict) is a structured {@link ReadNote} — never a pre-rendered string, so
+ * no carrier inherits the tool carrier's wording (a name inside an engine sentence is the tool
+ * carrier's own byte, not a rule for other carriers). The PDF lane is the one exception: its blocks are
+ * the Read tool's PDF projection as-is (engine headers interleaved with the fenced text layer) — a
+ * carrier other than the Read tool does not present them as file data.
+ *
+ * A refusal is the Read tool's own error envelope (`refusal`), minted where it is decided, with
+ * `outcome: "not_attached"`.
+ */
+/** What happened to the file's contents. `partial` = a default read the token cap cut (the partial-view
+ *  marker); `unchanged` = the dedup answers (same window and hash, or a seeded file already in context);
+ *  `not_attached` = nothing of the contents was served (a refusal, an offset past the end, a PDF whose
+ *  degradation chain bottomed out). Exported to carriers by the seat that needs it, not from the package. */
+export declare const READ_OUTCOMES: readonly ["attached", "partial", "unchanged", "not_attached"];
+export type ReadOutcome = (typeof READ_OUTCOMES)[number];
+/** The lane the read took. Absent on a refusal raised before the lane was known. A corrupt notebook served
+ *  as raw text is `text` (with the `notebook_fallback` note). */
+export type ReadKind = "text" | "notebook" | "image" | "pdf";
+/** The engine's statements about one read, as data. The Read carrier's rendering is
+ *  {@link renderReadNoteForTool}; the frame carrier renders the same members its own way. */
+export type ReadNote = {
+    kind: "empty_file";
+} | {
+    kind: "past_eof";
+    offset: number;
+    totalLines: number;
+}
+/** A default read of a startup-seeded file that is unchanged on disk. `key` is the canonical path. */
+ | {
+    kind: "already_in_context";
+    key: string;
+}
+/** The same window of an unchanged file was already served. `path` is the caller's spelling. */
+ | {
+    kind: "unchanged";
+    path: string;
+    start: number;
+    end: number;
+    total: number;
+}
+/** A served window that is not the whole file (an explicit slice), no partial-view marker. */
+ | {
+    kind: "range";
+    path: string;
+    start: number;
+    end: number;
+    total: number;
+}
+/** A default read the token cap cut by lines. */
+ | {
+    kind: "partial_page";
+    end: number;
+    total: number;
+    approxTokens: number;
+}
+/** A default read whose first line alone overflows the cap, served as a character prefix. */
+ | {
+    kind: "partial_chars";
+    cut: number;
+    totalChars: number;
+    approxTokens: number;
+}
+/** A `.ipynb` that does not parse, served as raw text. */
+ | {
+    kind: "notebook_fallback";
+}
+/** A parsed notebook with no cells. */
+ | {
+    kind: "notebook_no_cells";
+}
+/** The image was downsampled; the coordinates map back to the original. */
+ | {
+    kind: "image_resized";
+    dimensions: ImageDimensions;
+}
+/** External bytes carried reminder- or envelope-shaped text. */
+ | {
+    kind: "disclosure";
+    verdict: ReminderDisclosureVerdict;
+};
+/** The read-state entry a delivery records, minus the delivery's own facts (when, which transmission). */
+export interface ReadObservation {
+    key: string;
+    entry: Pick<ReadEntry, "hash" | "totalLines" | "truncated" | "isPartialView" | "view">;
+}
+/** The Read tool's error envelope for a refusal. */
+export type ReadRefusal = ReturnType<typeof errorResult>;
+export interface ReadForModelResult {
+    outcome: ReadOutcome;
+    kind?: ReadKind;
+    data: Array<TextContent | ImageContent | DocumentContent>;
+    notes: ReadNote[];
+    /** The host face (the Read tool's `details`), shared by every carrier. */
+    details?: Record<string, unknown>;
+    /** The Read tool's refusal (its error envelope: the sentence and its structured details) — present exactly on a
+     *  refusal. */
+    refusal?: ReadRefusal;
+    /** Present when a delivery records read state. */
+    observation?: ReadObservation;
+    effects: {
+        disclosure: ReminderDisclosureEffects[];
+    };
+}
+/** The facts of the read the caller supplies (the tool context's subset). */
+export interface ReadForModelContext {
+    signal?: AbortSignal;
+    toolCallId?: string;
+    taskId?: string;
+    principal?: string;
+}
+export interface ModelFileReaderOptions {
+    env: ExecutionEnv;
+    state: ReadFileState;
+    rootCanonical: string;
+    cwdRef?: CwdRef;
+    additionalRoots?: RootsSeat;
+    imageDownsampler?: ReadImageDownsamplerOption;
+    pdfCapabilities?: PdfModelCapabilities;
+    /** See createReadFileTool's seat of the same name. */
+    bgOutputReadExemption?: (canonicalKey: string, ctx: {
+        taskId?: string;
+        principal?: string;
+        toolCallId?: string;
+    }) => boolean;
+    readDeny?: import("./read-deny.js").ReadDenyMatcher;
+    readFace?: import("./containment-face.js").ContainmentFace;
+    reminderMark?: string;
+    reminderDisclosureCounts?: ReminderDisclosureCounts;
+    /** The bare-form disclosure throttle windows, keyed by canonical file key. Owned by whoever builds the
+     *  reader; every carrier that reads through the same reader shares them. Absent ⇒ a fresh map. */
+    disclosureWindows?: Map<string, number>;
+}
+export interface ModelFileReader {
+    readForModel(args: unknown, ctx: ReadForModelContext): Promise<ReadForModelResult>;
+    /** Apply the result's effects: the read-state entry (stamped `lastReadAt` and the transmission that
+     *  carried it) and the disclosure windows / counters. Once per result: a second commit throws. */
+    commit(result: ReadForModelResult, at?: {
+        transmittedByToolCallId?: string;
+        now?: number;
+    }): void;
+}
+export declare function createModelFileReader(opts: ModelFileReaderOptions): ModelFileReader;
+/** The Read carrier's sentence for one note — the bytes the Read tool has always emitted for it. The
+ *  data-adjacent notes (range header, partial marker, fallback prefix, 0-cell placeholder, resize line,
+ *  disclosure trailer) render without their joining separators; {@link renderReadToolResult} places them. */
+export declare function renderReadNoteForTool(note: ReadNote, mark: string | undefined): string;
+/** The Read tool's result for one read — the composition each lane has always returned. */
+export declare function renderReadToolResult(r: ReadForModelResult, mark: string | undefined): ToolReturn;
 export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: RootsSeat, imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
     taskId?: string;
     principal?: string;