@sema-agent/core 7.51.1 → 7.52.0

package/dist/tools/fs/dir-entries.d.ts

@@ -22,7 +22,7 @@
  * judging was cut short by an abort — the listing is a prefix, not the directory).
  */
 import type { ExecutionEnv } from "../../internal/harness-types.js";
-import type { FileError, FileInfo, FileKind, Result } from "../../internal/harness.js";
+import { FileError, type FileInfo, type FileKind, type Result } from "../../internal/harness.js";
 import { type HomeViewEnv, type HomeViewsCarrier } from "./read-deny-home.js";
 /** The upstream at-mention's cap on listed entries. */
 export declare const DIRECTORY_LISTING_MAX_ENTRIES = 1000;
@@ -37,7 +37,9 @@ export type EntryDenyTable = {
 export type EntryDenyJudge = (path: string, leaf?: "file") => Promise<{
     pattern: string;
 } | null>;
-/** The per-entry judge over `deny` (literal spelling, then the home view). */
+/** The per-entry judge over `deny` (literal spelling, then the home view). An entry whose home view nobody could read is not
+ *  an entry with no view: the judgment of the traversal did not finish, and the call is refused whole
+ *  ({@link HomeViewUnreadError}, thrown) — what the walk would serve was not judged, so neither it nor a partial result is. */
 export declare function createEntryDenyJudge(env: HomeViewEnv, deny: EntryDenyTable, signal?: AbortSignal): EntryDenyJudge;
 export interface DirectoryEntry {
     name: string;

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

@@ -1,4 +1,5 @@
-import { homeViewsOf } from "./read-deny-home.js";
+import { FileError } from "../../internal/harness.js";
+import { HomeViewUnreadError, homeViewsOf } from "./read-deny-home.js";
 import { DATA_LABEL_UNSAFE, quoteDataLabel } from "../../internal/llm.js";
 export const DIRECTORY_LISTING_MAX_ENTRIES = 1000;
 export function createEntryDenyJudge(env, deny, signal) {
@@ -7,8 +8,11 @@ export function createEntryDenyJudge(env, deny, signal) {
         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;
+        const home = await views.of(path, leaf !== undefined ? { leaf } : undefined);
+        const viewHit = home.view !== undefined ? deny.matchPath(home.view) : null;
+        if (viewHit === null && home.unread !== undefined)
+            throw new HomeViewUnreadError(path, home.unread);
+        return viewHit;
     };
 }
 export async function enumerateDirectory(env, dir, judge, signal, list = (d) => env.listDir(d, signal)) {
@@ -25,7 +29,15 @@ export async function enumerateDirectory(env, dir, judge, signal, list = (d) =>
             incomplete = true;
             break;
         }
-        const hit = judge === undefined ? null : await judge(info.path, info.kind === "directory" ? undefined : "file");
+        let hit;
+        try {
+            hit = judge === undefined ? null : await judge(info.path, info.kind === "directory" ? undefined : "file");
+        }
+        catch (e) {
+            if (e instanceof HomeViewUnreadError)
+                return { ok: false, error: new FileError("unknown", e.message, info.path) };
+            throw e;
+        }
         if (hit) {
             omitted++;
             if (!omittedPatterns.includes(hit.pattern))

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

@@ -1,4 +1,4 @@
-import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
+import { type AgentTool, type ExecutionEnv } from "../../internal/harness.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type CwdRef } from "./fs-shared.js";
 import type { ReversibilityVerdict } from "../../core/types.js";

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

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
+import { isTimeCutCode } from "../../internal/harness.js";
 import { defaultTaskRegistry } from "../../core/task-registry.js";
 import { accountDroppedBytes, spoolDropNote } from "../../core/task-registry-shared.js";
 import { RollingTailBuffer } from "../../core/exec-output-tail.js";
@@ -8,7 +9,8 @@ import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESS
 import { envDeclaresRetain, hasBackgroundShell, retainsBackgroundProcesses } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
-import { imageMagicMatches, withinAnyRoot } from "./safety.js";
+import { withinAnyRoot } from "./safety.js";
+import { imageMagicMatches } from "../../core/image-admission.js";
 import { isDeadCwd, diagnoseDeadCwd } from "./dead-cwd.js";
 import { boundaryIsTheSandbox, hasDestroy, isIsolated } from "../../core/remote-env.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
@@ -375,7 +377,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
                 isError: true,
             };
         }
-        if (res.error.code === "timeout" || res.error.code === "aborted" || res.error.code === "callback_error") {
+        if (isTimeCutCode(res.error.code) || res.error.code === "aborted" || res.error.code === "callback_error") {
             const rawStdout = res.error.partialStdout ?? "";
             const rawStderr = res.error.partialStderr ?? "";
             const cutOverflowFile = rawStdout.length > bashMaxOutputChars() || rawStderr.length > bashMaxOutputChars()
@@ -383,19 +385,26 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
                 : undefined;
             const pStdout = clipShellOutput(rawStdout);
             const pStderr = clipShellOutput(rawStderr);
+            const noOutputSec = res.error.code === "liveness_no_output" && typeof res.error.noOutputSec === "number" && Number.isFinite(res.error.noOutputSec) && Math.floor(res.error.noOutputSec) >= 1
+                ? Math.floor(res.error.noOutputSec)
+                : undefined;
             const headline = res.error.code === "timeout"
                 ? cappedByMaxTimeout
                     ? `Command timed out after ${timeout}s — requested ${requestedSec}s, capped at ${caps.maxSec}s (engine ceiling: requests above ${caps.maxSec}s are reduced to it). The process was killed; output produced before the cutoff is shown below. Re-running with a larger timeout gets the same ${caps.maxSec}s ceiling — use run_in_background for work that needs longer, a narrower command, or resume from the partial progress below.`
                     : `Command timed out after ${timeout}s (timeout limit: ${timeout}s). The process was killed; output produced before the cutoff is shown below. Re-running the same command will likely time out again — consider run_in_background for long commands, a narrower command, or resuming from the partial progress below.`
-                : res.error.code === "aborted"
-                    ? `Command was interrupted (aborted) before completion. Output produced before the interrupt is shown below.`
-                    : `Command started but its completion could not be observed — a host-side output-stream callback failed mid-run and the process was terminated (${res.error.message}). Output captured before the cut is shown below; its effects up to that point may have landed. Verify before assuming it needs a full re-run.`;
+                : res.error.code === "liveness_no_output"
+                    ? `Command was killed after producing no output for ${noOutputSec !== undefined ? `${noOutputSec}s` : "the environment's no-output window"} (a command that writes nothing to stdout or stderr that long is treated as hung; this is not the timeout you requested). Output produced before the cutoff is shown below. Re-running the same command will likely stall the same way — make it print progress as it works, use run_in_background for long quiet commands, or split it into smaller steps.`
+                    : res.error.code === "aborted"
+                        ? `Command was interrupted (aborted) before completion. Output produced before the interrupt is shown below.`
+                        : `Command started but its completion could not be observed — a host-side output-stream callback failed mid-run and the process was terminated (${res.error.message}). Output captured before the cut is shown below; its effects up to that point may have landed. Verify before assuming it needs a full re-run.`;
             const captured = (pStdout ? `--- partial stdout ---\n${pStdout}` : "") +
                 (pStderr ? `${pStdout ? "\n" : ""}--- partial stderr ---\n${pStderr}` : "");
             const zeroOutput = captured.length === 0;
-            const zeroOutputHint = res.error.code === "timeout" && timeout >= 60
-                ? ` — the process ran the full ${timeout}s without writing to its stdio; it may have been stalled before producing output, or holding it in a block buffer`
-                : "";
+            const zeroOutputHint = res.error.code === "liveness_no_output"
+                ? ` — the process wrote nothing to its stdio for ${noOutputSec !== undefined ? `the whole ${noOutputSec}s window` : "the whole window"}; it may have been stalled before producing output, or holding it in a block buffer`
+                : res.error.code === "timeout" && timeout >= 60
+                    ? ` — the process ran the full ${timeout}s without writing to its stdio; it may have been stalled before producing output, or holding it in a block buffer`
+                    : "";
             const body = !zeroOutput
                 ? `\n${delimitUntrusted("partial command output", captured)}`
                 : `\n(no output was produced before the cutoff${zeroOutputHint})`;
@@ -414,9 +423,11 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
                             timeoutSec: timeout,
                             ...(cappedByMaxTimeout ? { requestedTimeoutSec: requestedSec, cappedToMaxTimeoutSec: caps.maxSec } : {}),
                         }
-                        : res.error.code === "aborted"
-                            ? { aborted: true }
-                            : { callbackError: true }),
+                        : res.error.code === "liveness_no_output"
+                            ? { livenessNoOutput: true, ...(noOutputSec !== undefined ? { noOutputSec } : {}) }
+                            : res.error.code === "aborted"
+                                ? { aborted: true }
+                                : { callbackError: true }),
                 },
                 ...(zeroOutput ? { isError: true } : {}),
             };

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

@@ -1,6 +1,7 @@
 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 { PDF_FALLBACK_RENDER_PAGES, PDF_INLINE_PAGE_THRESHOLD, PDF_MAX_EXTRACT_SIZE, PDF_MAX_PAGES_PER_READ, extractPdfPagesAsImages, extractPdfTextLayer, getPdfPageCount, parsePdfPageRange, pdfCutWords, } from "./pdf.js";
+import { PDF_TARGET_RAW_SIZE, pdfMagicMatches } from "../../core/image-admission.js";
 import { resolveAutoDownsampler, enoentMessage, MAX_READ_BYTES } from "./fs-shared.js";
 import { planReminderDisclosure, renderReminderDisclosureTrailer } from "../../core/reminder-disclosure.js";
 import { MARKED_BLOCK_AFTER_DATA } from "../../core/reminder-mint.js";
@@ -81,8 +82,9 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
             const t = await extractPdfTextLayer(env, key, { first: range.first, last }, signal);
             if (t.ok) {
                 const { body, truncated } = boundPdfExtractedText(t.text);
-                const timeoutNote = t.timedOutAfterSec !== undefined
-                    ? `; PARTIAL — pdftotext timed out after ${t.timedOutAfterSec}s, so the text below covers only what was extracted before the timeout; use a narrower pages range for the rest`
+                const words = t.cut !== undefined ? pdfCutWords(t.cut) : undefined;
+                const timeoutNote = words !== undefined
+                    ? `; PARTIAL — pdftotext ${words.clause}, so the text below covers only what was extracted before the ${words.noun}; use a narrower pages range for the rest`
                     : "";
                 return {
                     content: [
@@ -94,7 +96,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
                     ],
                     details: {
                         type: "document",
-                        file: { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}), pages: `${range.first}-${last}`, ...(t.timedOutAfterSec !== undefined ? { timedOut: true } : {}) },
+                        file: { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}), pages: `${range.first}-${last}`, ...(t.cut !== undefined ? { timedOut: true } : {}) },
                         fallback: { level: 1, reason: "model lacks document input; text layer extracted via pdftotext" },
                     },
                 };
@@ -128,10 +130,11 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
             return blocks;
         const requestedPages = last - range.first + 1;
         const renderedAll = extract.pages.length >= requestedPages;
-        const header = extract.timedOutAfterSec !== undefined
+        const words = extract.cut !== undefined ? pdfCutWords(extract.cut) : undefined;
+        const header = words !== undefined
             ? renderedAll
-                ? `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""}: pdftoppm timed out after ${extract.timedOutAfterSec}s, but all ${requestedPages} requested page${requestedPages === 1 ? "" : "s"} were rendered before the timeout hit at teardown (100 dpi); nothing is missing.]`
-                : `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""}: pdftoppm timed out after ${extract.timedOutAfterSec}s; rendered ${extract.pages.length} of ${requestedPages} requested page${requestedPages === 1 ? "" : "s"} before the timeout (100 dpi). Read the remaining pages with a narrower range (e.g. pages: "${range.first + extract.pages.length}-${last}").]`
+                ? `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""}: pdftoppm ${words.clause}, but all ${requestedPages} requested page${requestedPages === 1 ? "" : "s"} were rendered before the ${words.noun} hit at teardown (100 dpi); nothing is missing.]`
+                : `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""}: pdftoppm ${words.clause}; rendered ${extract.pages.length} of ${requestedPages} requested page${requestedPages === 1 ? "" : "s"} before the ${words.noun} (100 dpi). Read the remaining pages with a narrower range (e.g. pages: "${range.first + extract.pages.length}-${last}").]`
             : `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""} rendered as ${extract.pages.length} image${extract.pages.length === 1 ? "" : "s"} (100 dpi)]`;
         const content = [
             { type: "text", text: header },
@@ -147,7 +150,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
                     ...(pageCount !== undefined ? { pageCount } : {}),
                     pages: `${range.first}-${last}`,
                     renderedPages: extract.pages.length,
-                    ...(extract.timedOutAfterSec !== undefined ? { requestedPages, timedOut: true } : {}),
+                    ...(extract.cut !== undefined ? { requestedPages, timedOut: true } : {}),
                 },
             },
         };
@@ -164,8 +167,9 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
         const t = await extractPdfTextLayer(env, key, undefined, signal);
         if (t.ok) {
             const { body, truncated } = boundPdfExtractedText(t.text);
-            const timeoutNote = t.timedOutAfterSec !== undefined
-                ? `; PARTIAL — pdftotext timed out after ${t.timedOutAfterSec}s, so the text below covers only what was extracted before the timeout; use the pages parameter for the rest`
+            const words = t.cut !== undefined ? pdfCutWords(t.cut) : undefined;
+            const timeoutNote = words !== undefined
+                ? `; PARTIAL — pdftotext ${words.clause}, so the text below covers only what was extracted before the ${words.noun}; use the pages parameter for the rest`
                 : "";
             return {
                 content: [
@@ -177,7 +181,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
                 ],
                 details: {
                     type: "document",
-                    file: { ...fileCard, ...(t.timedOutAfterSec !== undefined ? { timedOut: true } : {}) },
+                    file: { ...fileCard, ...(t.cut !== undefined ? { timedOut: true } : {}) },
                     fallback: { level: 1, reason: "model lacks document input; text layer extracted via pdftotext" },
                 },
             };
@@ -190,7 +194,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
             if (extract.ok) {
                 const blocks = await pdfPagesToImageBlocks(extract.pages, path, downsamplerOpt);
                 if (typeof blocks !== "string") {
-                    const renderTimeoutNote = extract.timedOutAfterSec !== undefined ? ` pdftoppm timed out after ${extract.timedOutAfterSec}s — only the pages that finished rendering are included.` : "";
+                    const renderTimeoutNote = extract.cut !== undefined ? ` pdftoppm ${pdfCutWords(extract.cut).clause} — only the pages that finished rendering are included.` : "";
                     return {
                         content: [
                             {
@@ -202,7 +206,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
                         ],
                         details: {
                             type: "document",
-                            file: { ...fileCard, pages: `1-${extract.pages.length}`, renderedPages: extract.pages.length, ...(extract.timedOutAfterSec !== undefined ? { timedOut: true } : {}) },
+                            file: { ...fileCard, pages: `1-${extract.pages.length}`, renderedPages: extract.pages.length, ...(extract.cut !== undefined ? { timedOut: true } : {}) },
                             fallback: { level: 2, reason: `model lacks document input; ${textWhy}; rendered first ${extract.pages.length} page(s) via pdftoppm` },
                         },
                     };

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

@@ -1,10 +1,10 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, violationDetails, binaryMagicFormat, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, } from "./safety.js";
+import { sha256, resolveKey, violationText, violationDetails, binaryMagicFormat, hasBinaryExtension, isBinaryContent, imageMimeForRead, } from "./safety.js";
 import { decodeTextBytes } from "./encoding.js";
 import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
 import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE } from "../../core/mcp.js";
-import { countPdfPagesFromBytes, PDF_MAX_PAGES_PER_READ, PDF_TARGET_RAW_SIZE, pdfMagicMatches } from "./pdf.js";
+import { countPdfPagesFromBytes, PDF_MAX_PAGES_PER_READ } from "./pdf.js";
 import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, NO_DOWNSAMPLER_IMAGE_CAP_HINT, resolveAutoDownsampler, MAX_READ_OUTPUT_CHARS, FILE_PATH_PARAMS, countLines, seededFileUnchangedReminder, enoentMessage, } from "./fs-shared.js";
 import { readPdfFile } from "./fs-pdf.js";
 import { seatForCall, seatReady } from "./read-deny.js";
@@ -12,7 +12,8 @@ import { thrownText } from "../../core/thrown-value.js";
 import { MARKED_BLOCK_AFTER_DATA, openSystemReminder } from "../../core/reminder-mint.js";
 import { planReminderDisclosure, commitReminderDisclosureEffects, renderReminderDisclosureTrailer, } from "../../core/reminder-disclosure.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
-import { admitImageBytes, imageReadCap } from "./image-admission.js";
+import { fileArgPath } from "../../core/tool-registry.js";
+import { admitImageBytes, imageReadCap, PDF_TARGET_RAW_SIZE, pdfMagicMatches } from "../../core/image-admission.js";
 import { createEntryDenyJudge, enumerateDirectory } from "./dir-entries.js";
 import { FileError } from "../../internal/harness.js";
 export const READ_OUTCOMES = Object.freeze(["attached", "partial", "unchanged", "not_attached"]);

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

@@ -111,16 +111,7 @@ export declare function applyRecordedEdit(text: string, edit: RecordedEdit): str
  *  both sharper shapes describe files Read handled successfully, so the encoding-deadlock sentence
  *  would be false there — and stacking two escape routes on one refusal buries the one that applies. */
 export declare function notReadRefusalText(env: ExecutionEnv, toolName: string, key: string, v: Pick<FsViolation, "code" | "message" | "partialView">, signal?: AbortSignal, fallbackHint?: string): Promise<string>;
-/** Byte cap on a Read-image WITHOUT a downsampler: an image file is returned AS a visual
- *  `ImageContent` block (base64) rather than refused. Bounded so a huge image cannot blow the request.
- *  This stat-time cap only bounds the READ; the accept/refuse decision is the base64 gate below (the
- *  provider limit is on base64 LENGTH, so the effective no-sharp accept bound is raw ≤ 3.75MB). */
-export declare const MAX_IMAGE_READ_BYTES: number;
-/** Byte cap on a Read-image WITH a downsampler: sharp can shrink a big photo to CC's 2000×2000/3.75MB
- *  target, so the smaller hard refusal does not apply (CC readImageWithTokenBudget reads the file
- *  unbounded; we keep an OOM sanity bound — deliberate delta, camera photos fit comfortably). */
-export declare const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES: number;
-/** The no-downsampler cap above is a DELIBERATE bound and does not move — but its refusal must not
+/** The no-downsampler cap (`MAX_IMAGE_READ_BYTES`, core/image-admission.ts) is a DELIBERATE bound and does not move — but its refusal must not
  *  read like a hard ceiling. Whether the higher cap is reachable depends on an OPTIONAL dependency the
  *  caller can install, and only this package knows that, so the refusal names the move instead of
  *  leaving the caller to guess that the limit is negotiable. Appended ONLY on the no-downsampler

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

@@ -6,6 +6,7 @@ import { shellQuote } from "./search.js";
 import { isNotebookPath } from "./notebook.js";
 import { homeViewsOf } from "./read-deny-home.js";
 import { sharpImageDownsampler } from "../../core/mcp.js";
+import { MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES } from "../../core/image-admission.js";
 import { deliverEngineNotice } from "../../core/types.js";
 import { resolveEnvBudget } from "../../core/env-budget.js";
 import { openSystemReminder } from "../../core/reminder-mint.js";
@@ -55,8 +56,6 @@ export async function notReadRefusalText(env, toolName, key, v, signal, fallback
         return `${base} ${OVERSIZE_READ_ESCAPE_HINT}`;
     return fallbackHint === undefined ? base : `${base} ${fallbackHint}`;
 }
-export const MAX_IMAGE_READ_BYTES = 5 * 1024 * 1024;
-export const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES = 64 * 1024 * 1024;
 export const NO_DOWNSAMPLER_IMAGE_CAP_HINT = `Install the optional "sharp" dependency (declared in this package's optionalDependencies) to read images up to ${MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES} bytes — it downsamples them to fit the API image limit.`;
 let autoDownsampler;
 export function resolveAutoDownsampler() {
@@ -366,8 +365,8 @@ export async function enoentMessage(env, key, cwd, signal, readDeny) {
             return false;
         if (readDeny.matchPath(path) != null)
             return true;
-        const view = await views.of(path, leaf !== undefined ? { leaf } : undefined);
-        return view !== undefined && readDeny.matchPath(view) != null;
+        const home = await views.of(path, leaf !== undefined ? { leaf } : undefined);
+        return home.unread !== undefined || (home.view !== undefined && readDeny.matchPath(home.view) != null);
     };
     if (sep > 0) {
         const parent = key.slice(0, sep);

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

@@ -1,11 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
+import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { seatForCall } from "./read-deny.js";
 import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, coerceWriteArguments, ipynbRedirect, countLines, applyRecordedEdit, } from "./fs-shared.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
+import { fileArgPath } from "../../core/tool-registry.js";
 import { thrownText } from "../../core/thrown-value.js";
 async function envFinalWrite(env, key, content, signal, opts) {
     const fireEdited = () => {

package/dist/tools/fs/notebook.js

@@ -1,4 +1,4 @@
-import { imageMagicMatches } from "./safety.js";
+import { imageMagicMatches } from "../../core/image-admission.js";
 export function isNotebookPath(p) {
     return p.toLowerCase().endsWith(".ipynb");
 }

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

@@ -20,13 +20,10 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
 export declare const PDF_MAX_PAGES_PER_READ = 20;
 /** Above this page count a whole-PDF read is refused and `pages` is required (CC `PDF_AT_MENTION_INLINE_THRESHOLD`). */
 export declare const PDF_INLINE_PAGE_THRESHOLD = 10;
-/** Max raw size sent whole as a document block (CC `PDF_TARGET_RAW_SIZE`). */
-export declare const PDF_TARGET_RAW_SIZE: number;
-/** Max raw size the page-extraction (pdftoppm) path accepts (CC `PDF_MAX_EXTRACT_SIZE`). */
+/** Max raw size the page-extraction (pdftoppm) path accepts (CC `PDF_MAX_EXTRACT_SIZE`). The whole-send target
+ *  (`PDF_TARGET_RAW_SIZE`) and the `%PDF-` signature test (`pdfMagicMatches`) are the document admission's own
+ *  (core/image-admission.ts). */
 export declare const PDF_MAX_EXTRACT_SIZE: number;
-/** True when the bytes start with the `%PDF-` magic. Magic outranks extension both ways: a mis-named
- *  `.pdf` without it is refused, and a non-`.pdf` file carrying it is read AS a PDF. */
-export declare function pdfMagicMatches(bytes: Uint8Array): boolean;
 /** A parsed 1-indexed inclusive page range. `last === Infinity` for an open range ("10-"). */
 export interface PdfPageRange {
     first: number;
@@ -75,12 +72,25 @@ export declare function pdfModelCapabilitiesOf(model?: {
 }): PdfModelCapabilities;
 /** Timeout for the poppler extraction commands (pdftotext / pdftoppm), in seconds. */
 export declare const PDF_EXEC_TIMEOUT_SEC = 120;
+/** What cut a run short: the wall-clock budget (always a number), or the env's silence window (a number only when the env states it — otherwise the budget did not elapse and no number is honest). */
+export type PdfCut = {
+    readonly kind: "budget";
+    readonly sec: number;
+} | {
+    readonly kind: "silence";
+    readonly sec?: number;
+};
+/** A cut in words: the clause that says it (`timed out after 120s` / `was cut after producing no output for 30s` / `was cut for producing no output`) and the noun a later clause calls it. */
+export declare function pdfCutWords(cut: PdfCut): {
+    clause: string;
+    noun: string;
+};
 export type PdfTextResult = {
     ok: true;
     text: string;
-    /** Set when pdftotext hit its exec timeout but had already written partial text: the extraction is
+    /** Set when pdftotext was cut by a time bound but had already written partial text: the extraction is
      *  INCOMPLETE (covers only the leading part of the requested range) and the caller must say so. */
-    timedOutAfterSec?: number;
+    cut?: PdfCut;
 } | {
     ok: false;
     toolMissing: boolean;
@@ -104,9 +114,9 @@ export type PdfExtractResult = {
         pageNumber: number;
         jpeg: Uint8Array;
     }>;
-    /** Set when pdftoppm hit its exec timeout but had already rendered complete leading pages: `pages`
+    /** Set when pdftoppm was cut by a time bound but had already rendered complete leading pages: `pages`
      *  covers only a PREFIX of the requested range and the caller must label the delivery as partial. */
-    timedOutAfterSec?: number;
+    cut?: PdfCut;
 } | {
     ok: false;
     toolMissing: boolean;

package/dist/tools/fs/pdf.js

@@ -1,10 +1,7 @@
+import { isTimeCutCode } from "../../internal/harness.js";
 export const PDF_MAX_PAGES_PER_READ = 20;
 export const PDF_INLINE_PAGE_THRESHOLD = 10;
-export const PDF_TARGET_RAW_SIZE = 20 * 1024 * 1024;
 export const PDF_MAX_EXTRACT_SIZE = 100 * 1024 * 1024;
-export function pdfMagicMatches(bytes) {
-    return bytes.length >= 5 && bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46 && bytes[4] === 0x2d;
-}
 export function parsePdfPageRange(pages) {
     const s = pages.trim();
     const single = /^(\d+)$/.exec(s);
@@ -60,6 +57,16 @@ export function pdfModelCapabilitiesOf(model) {
     return { document, vision };
 }
 export const PDF_EXEC_TIMEOUT_SEC = 120;
+function cutOf(e) {
+    if (e.code !== "liveness_no_output")
+        return { kind: "budget", sec: PDF_EXEC_TIMEOUT_SEC };
+    return e.noOutputSec !== undefined ? { kind: "silence", sec: e.noOutputSec } : { kind: "silence" };
+}
+export function pdfCutWords(cut) {
+    if (cut.kind === "budget")
+        return { clause: `timed out after ${cut.sec}s`, noun: "timeout" };
+    return { clause: cut.sec !== undefined ? `was cut after producing no output for ${cut.sec}s` : "was cut for producing no output", noun: "cut" };
+}
 export async function extractPdfTextLayer(env, absPath, range, signal) {
     const tmp = await env.createTempDir("sema-pdf-text-", signal);
     if (!tmp.ok)
@@ -73,16 +80,17 @@ export async function extractPdfTextLayer(env, absPath, range, signal) {
         const cmd = `pdftotext -layout ${rangeArgs}${shellQuote(absPath)} ${shellQuote(outR.value)}`;
         const r = await env.exec(cmd, { timeout: PDF_EXEC_TIMEOUT_SEC, abortSignal: signal });
         if (!r.ok) {
-            if (r.error.code === "timeout") {
+            if (isTimeCutCode(r.error.code)) {
+                const cut = cutOf(r.error);
                 const partial = await env.readBinaryFile(outR.value, signal);
                 const text = partial.ok ? Buffer.from(partial.value).toString("utf8") : "";
                 if (text.trim())
-                    return { ok: true, text, timedOutAfterSec: PDF_EXEC_TIMEOUT_SEC };
+                    return { ok: true, text, cut };
                 return {
                     ok: false,
                     toolMissing: false,
                     timedOut: true,
-                    error: `pdftotext timed out after ${PDF_EXEC_TIMEOUT_SEC}s before writing any text. Use the pages parameter to extract a narrower range (e.g. pages: "1-5").`,
+                    error: `pdftotext ${pdfCutWords(cut).clause} before writing any text. Use the pages parameter to extract a narrower range (e.g. pages: "1-5").`,
                 };
             }
             return { ok: false, toolMissing: false, error: r.error.message };
@@ -129,7 +137,8 @@ export async function extractPdfPagesAsImages(env, absPath, first, last, signal)
         const cmd = `pdftoppm -jpeg -r 100 -f ${first} -l ${last} ${shellQuote(absPath)} ${shellQuote(prefixR.value)}`;
         const r = await env.exec(cmd, { timeout: PDF_EXEC_TIMEOUT_SEC, abortSignal: signal });
         if (!r.ok) {
-            if (r.error.code === "timeout") {
+            if (isTimeCutCode(r.error.code)) {
+                const cut = cutOf(r.error);
                 const listed = await listRenderedJpegs(env, dir, signal);
                 const jpgs = listed.ok ? listed.jpgs : [];
                 const pages = [];
@@ -140,12 +149,12 @@ export async function extractPdfPagesAsImages(env, absPath, first, last, signal)
                     pages.push({ pageNumber: first + i, jpeg: bin.value });
                 }
                 if (pages.length > 0)
-                    return { ok: true, pages, timedOutAfterSec: PDF_EXEC_TIMEOUT_SEC };
+                    return { ok: true, pages, cut };
                 return {
                     ok: false,
                     toolMissing: false,
                     timedOut: true,
-                    error: `pdftoppm timed out after ${PDF_EXEC_TIMEOUT_SEC}s before finishing any page. Request a narrower pages range (e.g. a single page like pages: "${first}").`,
+                    error: `pdftoppm ${pdfCutWords(cut).clause} before finishing any page. Request a narrower pages range (e.g. a single page like pages: "${first}").`,
                 };
             }
             return { ok: false, toolMissing: false, error: r.error.message };

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

@@ -172,9 +172,18 @@ export interface OptionSpec {
      *  `date -s`), `executes` a command (`find -exec`), or `none` — neither, which the binary gate witnesses for every
      *  option that states it (the read-only form of a program admits only such options). Absent: not stated. */
     readonly effect?: "writes" | "executes" | "none";
-    /** The option's value names a FILE the program reads its OPERANDS from (`find -files0-from`, `tar -T`): what it walks
-     *  or opens is not in the command line. */
+    /** The option's value names a FILE the program reads its OPERANDS from (`find -files0-from`, `tar -T`) — or, a switch, says they
+     *  arrive on its standard input (`ack -x`): what it walks or opens is not in the command line, so a segment that selects it has
+     *  reads the station cannot establish ({@link deliversOperands}); the list file itself is a read like any other and meets the deny
+     *  rows as itself. */
     readonly delivers?: "operands";
+    /** The option's value is a PLACE the program's walk works in or compares (`tar -C DIR`, `diff --from-file=DIR`): a root of a
+     *  recursive form, whichever way the value is spelled. Absent: a path value is a file the program READS (a config, ignore or
+     *  exclusion file, an archive, a pattern file) or an entry it examines — judged as itself, never a root, so it does not count
+     *  as the root the walk was given (`rg --ignore-file ig pat` walks `.`). A list the operands come from ({@link delivers}) is a
+     *  root of a recursive form too, in either spelling: the program works on what the list names, not on the working directory
+     *  (and, the names not being in the text, the segment is not vouched: {@link deliversOperands}). */
+    readonly walks?: true;
     /** The option's value bounds the program's output, in bytes or in lines (`head -c` / `head -n`). */
     readonly bounds?: "bytes" | "lines";
     /** The option's value is what the row's LAST operand would otherwise be (`cp -t <dir>`), so every operand is an
@@ -236,6 +245,12 @@ export interface Grammar {
     /** With no operand, this implementation walks the working directory (`grep -r pat`); absent, it walks nothing (it
      *  reads its standard input, or refuses to run). */
     readonly walksCwdWithoutOperand?: true;
+    /** Whether this implementation reads an unambiguous PREFIX of a long option's name as that option (`getopt_long`, Perl's
+     *  Getopt::Long: `grep --max 1`, `tar --dir d`). Absent = it does; `false` = only the exact name is an option and a prefix
+     *  is an unrecognised flag that runs nothing (ripgrep's parser: `rg --ignore-f x` is an error while `rg --ignore` is the
+     *  switch). Every reader that matches a long name against the table asks this one fact, so a name a row leaves undeclared is
+     *  never read as the abbreviation of a declared one in a program that does not take abbreviations. */
+    readonly acceptsAbbreviations?: boolean;
     /** The traditional FIRST-argument form `<sign><number><letters>` (`tail +0f`, `tail -1f`): the signs this
      *  implementation reads it with, and the option each letter names. */
     readonly obsoleteFirst?: {
@@ -412,9 +427,11 @@ export declare function movesBaseByStack(name: string): boolean;
 /** The LONG-OPTION name carried by a token (`--file=p` → `file`, `--reg` → `reg`); `undefined` for anything that is
  *  not a long option with a non-empty name (`--`, `--=x`, a short option). */
 export declare function longOptionNameOf(tok: string): string | undefined;
-/** Is `name` a spelling (possibly ABBREVIATED) of the long option `full`? Every prefix counts — `getopt_long`'s
- *  ambiguity is not modelled, and each caller makes that over-approximation land on its own safe side. */
-export declare function isLongOptionAbbrevOf(name: string, full: string): boolean;
+/** Is `name` a spelling of the long option `full`? The exact name always; a proper prefix — an abbreviation — only where the
+ *  program takes them (`accepts`: {@link Grammar.acceptsAbbreviations}, or {@link Merged.abbreviable} of a merged name). Every
+ *  prefix counts there — `getopt_long`'s ambiguity is not modelled, and each caller makes that over-approximation land on its
+ *  own safe side. This is the one place a long name is matched against another. */
+export declare function isLongOptionSpellingOf(name: string, full: string, accepts: boolean): boolean;
 /** The languages whose program text the read station parses (the rest is program text it does not read). */
 export declare const READ_LANGUAGES: ReadonlySet<string>;
 /**
@@ -472,6 +489,8 @@ export interface FirstOperandSlot {
     readonly role: ArgRole;
     readonly suppliedByLetters: string;
     readonly suppliedByLongNames: readonly string[];
+    /** The long names of {@link suppliedByLongNames} a prefix of which supplies it too ({@link Grammar.acceptsAbbreviations}). */
+    readonly abbreviableLongNames: readonly string[];
     /** The other letters that take a value in every implementation: in a cluster, the rest of the token is theirs. */
     readonly valueLetters: string;
 }
@@ -480,7 +499,7 @@ export declare function firstOperandSlot(row: ProgramRow | undefined, view?: Vie
  *  a letter that delivers the slot supplies it, and the first OTHER letter that takes a value owns the rest of the
  *  token (`grep -Dread x f`: `read` is `-D`'s value, its `e` delivers nothing); a letter the row does not declare is
  *  stepped over (it may be a switch), as digits are (grep's obsolete numeric context spec: `-2ebeta`). A long option
- *  supplies it by abbreviation. Over-triggering makes the first operand a CHECKED path candidate, the safe side. */
+ *  supplies it by its name, or by a prefix of it where the program takes abbreviations. Over-triggering makes the first operand a CHECKED path candidate, the safe side. */
 export declare function suppliesFirstOperandSlot(slot: FirstOperandSlot, tok: string): boolean;
 /** The row's options stand anywhere in its argv in every implementation (`find`'s predicates past its paths), so the
  *  "is a dash-word past the first operand still an option" ambiguity does not exist for it. */
@@ -544,6 +563,7 @@ type Event<R> =
     readonly role: R;
     readonly consumed: boolean;
     readonly spec?: OptionSpec;
+    readonly unsettled?: true;
 }
 /** An operand, the `ordinal`-th. `slot` = the first-operand slot's role when the slot applies; `role` = the role the
  *  row declares for an operand at this position past the slot (a URL, a name it only examines); `dash` = the word is
@@ -559,13 +579,25 @@ type Event<R> =
 export type ArgEvent = Event<ArgRole>;
 export type ArgRoleEvent = Event<ArgRole | undefined>;
 /** The candidate extraction's walk (the program word excluded). `firstOperandSlot: false` reads every operand as an
- *  ordinary one. */
+ *  ordinary one. `ownedValues`: a bare option of a traversing program that may take the NEXT word as its value
+ *  ({@link bareOptionValueOf}) hands that word over as a value read both ways (`consumed: false`) — what the roots of a
+ *  recursive form are read from. */
 export declare function readArgs(row: ProgramRow | undefined, words: readonly ArgWord[], opts: {
     readonly firstOperandSlot: boolean | "program-text";
+    readonly ownedValues?: true;
 }): ArgEvent[];
 /** The role walk: the SAME walk, every declared option read by its declared arity and role. What the binary gate
  *  predicts a binary opens is read off these events. */
 export declare function readArgRoles(row: ProgramRow, args: readonly string[]): ArgRoleEvent[];
+/**
+ * Does this invocation take the program's OPERANDS from a list file ({@link OptionSpec.delivers}: `ack --files-from LIST`,
+ * `tar -T LIST`, `find -files0-from LIST`)? What the program then walks or opens is written in a file this reading does not
+ * open — no root of it is in the command. The reading of a check that only ever refuses or asks ({@link selectedOptions} over the
+ * merged row: a word spelled as the option counts, an abbreviation that reaches it counts, a value spelled like it counts). The
+ * traditional key word is every letter of it an option — each value-taking letter takes one of the arguments that follow, in
+ * order, so none owns the rest of the word (`tar cfT out.tar list` takes `list` for `T`).
+ */
+export declare function deliversOperands(row: ProgramRow | undefined, args: readonly string[]): boolean;
 /**
  * Does this invocation walk its operands' subtrees AND hand back their CONTENTS? Detection over-approximates: a flag
  * misread as recursive costs one ask, an under-read hides a traversal. A value-taking letter owns its value only where
@@ -596,6 +628,33 @@ export declare function declaresOption(row: ProgramRow, pred: (spec: OptionSpec)
  * count must still see. getopt's cluster rule: the FIRST value-taking letter owns the rest of the token.
  */
 export declare function takesSeparatedDatum(row: ProgramRow | undefined, tok: string): boolean;
+/**
+ * The value the NEXT word may be, for an option token written BARE (no value attached) — the one place the "which word does this
+ * option own" question of a cluster or an optional count is answered. Each grammar of the row reads the token as getopt does (a
+ * cluster: a letter the row does not declare is a switch, the first value-taking letter owns the rest of the token, so the next
+ * word only when it ends the token; a long name: the name or, where the grammar takes abbreviations, any name it abbreviates,
+ * `--name=` carries its own value):
+ *  · a REQUIRED value is the next word wherever the option is read — the extraction's slot reading fails to see it where the token
+ *    is a cluster with a letter the row leaves undeclared (`rg -nA 2 pat`: rg / ag / ack declare no switches), and `tok` is then
+ *    read the speculative way;
+ *  · an OPTIONAL count (the value only attached) is the next word to a parser that reads an optional integer (Getopt::Long's `:i`:
+ *    ack's `-A` / `-B` / `-C`) or a required one (GNU grep's `--context`) when that word is spelled like a count, and an operand to
+ *    a parser that reads it attached-only (getopt_long's optional argument: ag's long names, BSD grep) — the row files it
+ *    attached-only, the reading that consumes nothing.
+ *  · a long name the row declares NOWHERE (not as a name, nor — in a grammar that takes abbreviations — as the abbreviation of one)
+ *    may take the next word: the row cannot say it does not (`rg --hostname-bin x pat`, whose option runs a program, is left
+ *    undeclared on purpose; `rg --ignore pat sub`, a switch of rg that is no abbreviation of `--ignore-file` there) — the word's value role is
+ *    {@link UNDECLARED_VALUE}, no more than "names no file", as it is also read as whatever it is on its own. A long name with its
+ *    value attached owns nothing, and one the row declares as a switch owns nothing.
+ * A SHORT letter the row leaves undeclared owns no word: the rows of rg / ag / ack declare no switches, so every word behind `-i`
+ * would otherwise be one — the letter is read as the switch it is in rg (whose table of value letters is complete). The extraction
+ * reads the word both ways (`consumed: false` — as the value, and as whatever it is on its own). Served to the contents walkers
+ * (`readArgs` `ownedValues`), whose rows carry no single-dash WORD options (`find -name`): a cluster here is always letters.
+ */
+export declare function bareOptionValueOf(row: ProgramRow, tok: string, next: string | undefined): {
+    readonly role: ArgRole;
+    readonly spec?: OptionSpec;
+} | undefined;
 /**
  * Does this option word carry, ATTACHED, the value `-` for an option whose value is a file the program opens or names
  * (`grep -f-`, `diff --from-file=-`, `diff -X-`) — or for a spelling the row does not account for? Such a word makes the
@@ -623,7 +682,8 @@ interface OptionScan {
  * Every option spec an argv selects. A short cluster is read as getopt reads it, scanning left to right: a declared
  * letter is selected; a value-taking letter owns the rest of the token (and the next word, when it ends the token); a
  * letter the row does not declare is read as a switch and the scan goes on. A long option is every name its spelling
- * can abbreviate (the exact name alone where there is one); a dash word its exact name. Two readings:
+ * can abbreviate where the grammar takes abbreviations (the exact name alone where there is one, and always in a grammar
+ * that takes none); a dash word its exact name. Two readings:
  *  · over ONE implementation's view ({@link implementationsOf}): what that program selects — a separated value is
  *    stepped over, `--` ends the options, and so does the first operand where the grammar stops there;
  *  · over the row (every implementation merged): every word is read as the option it SPELLS — a value spelled like an