@sema-agent/core 7.55.0 → 7.57.0

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

@@ -16,15 +16,23 @@ import { boundaryIsTheSandbox, hasDestroy, isIsolated } from "../../core/remote-
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { backgroundLifetimeNote } from "./fs-bash-background-text.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, stripCwdSentinel, } from "./fs-shared.js";
-import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed } from "./bash-readonly-classifier.js";
+import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, parseLeadingCommandName } from "./bash-readonly-classifier.js";
+import { readOnlyShellVerdict } from "../../core/read-only-shell.js";
 import { mountRuleFace, toolFace } from "../../core/tool-catalog-entries.js";
 import { argvOf, compoundValueHidesRun, expansionHidesRun, expansionsInHeredocBody, lexShell } from "../../shell/lex.js";
 import { arithmeticAssignedNames } from "./shell-read-bindings.js";
 import { thrownText } from "../../core/thrown-value.js";
+import { patternKillRefusal } from "./pattern-kill-guard.js";
 function shellCommandOf(args) {
     const command = args?.command;
     return typeof command === "string" ? command : undefined;
 }
+const CONCURRENT_READERS = new Set(BASH_READONLY_DEFAULT_ALLOW);
+function readOnlyFaceRefusal(command, allow) {
+    const parsed = parseLeadingCommandName(command);
+    const verdict = "reject" in parsed ? { readOnly: false, reason: parsed.reject } : readOnlyShellVerdict(command, { readers: allow });
+    return verdict.readOnly ? undefined : verdict.reason;
+}
 function isBackgroundShellCall(args) {
     return args?.run_in_background === true;
 }
@@ -38,11 +46,10 @@ export function bashReversibilityProbe(allow, boundary) {
             return { reversible: false };
         const home = typeof boundary === "function" ? boundary() : boundary;
         const fold = home?.homeDir !== undefined ? { homeDir: home.homeDir } : undefined;
-        if (classifyCompoundReadonlyDetailed(command, allowSet, fold).reason === undefined)
-            return { reversible: true };
-        if (classifyBoundedReadonlyPollLoopDetailed(command, allowSet, fold).reason === undefined)
+        const reason = classifyCompoundReadonlyDetailed(command, allowSet, fold).reason;
+        if (reason === undefined)
             return { reversible: true };
-        return { reversible: false };
+        return classifyBoundedReadonlyPollLoopDetailed(command, allowSet, fold).reason === undefined ? { reversible: true } : { reversible: false, reason };
     };
 }
 export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
@@ -578,14 +585,14 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
             const command = shellCommandOf(args);
             if (command === undefined || isBackgroundShellCall(args))
                 return false;
-            return coarseReadonlyCheck(command, new Set(BASH_READONLY_DEFAULT_ALLOW)) === undefined;
+            return readOnlyShellVerdict(command, { readers: CONCURRENT_READERS }).readOnly;
         },
         execute: async (args, ctx) => {
             const { command, timeout, run_in_background, description } = args;
             const timeoutRefusal = bashTimeoutArgRefusal(timeout, timeoutCaps);
             if (timeoutRefusal !== undefined)
                 return errorResult(timeoutRefusal, { type: "bash_invalid_timeout", code: "bash_invalid_timeout" });
-            const refused = await taskOpts.shellReadAdmission?.("Bash", ctx.toolCallId, command, ctx.signal);
+            const refused = (await taskOpts.shellReadAdmission?.("Bash", ctx.toolCallId, command, ctx.signal)) ?? (await patternKillRefusal(command, env, cwdRef.current, ctx.signal));
             if (refused !== undefined)
                 return refused;
             if (run_in_background) {
@@ -797,7 +804,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
             const timeoutRefusal = bashTimeoutArgRefusal(timeout, timeoutCaps);
             if (timeoutRefusal !== undefined)
                 return errorResult(timeoutRefusal, { type: "bash_invalid_timeout", code: "bash_invalid_timeout" });
-            const reason = coarseReadonlyCheck(command, allow);
+            const reason = readOnlyFaceRefusal(command, allow);
             if (reason)
                 return errorResult(`Error (Bash): ${reason}`);
             const refused = await opts?.shellReadAdmission?.("Bash", ctx.toolCallId, command, ctx.signal);

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

@@ -0,0 +1,86 @@
+/**
+ * The matcher of the filesystem glob dialect: a token list is compiled to a small program, and a path is matched by walking
+ * it once, left to right, holding the SET of instructions that are live at the current position. An instruction is in the set
+ * at most once, so the cost of one test is at most the program's length times the path's length plus one, however many stars
+ * the pattern holds and however they are arranged — no expression is built from the pattern's text, so nothing backtracks and
+ * no pattern needs a cap. That product is a limit a pattern can reach on an ordinary path, when it keeps every instruction live at
+ * every place (a ring of empty alternatives does). The scratch it needs is two sets of the program's length, kept between tests for a
+ * program of up to 65 536 instructions (a longer program's is made for each test that gets past the two checks below and dropped: a
+ * cost of the program's length, whatever the path); a test whose threads all die at the first character costs what it touched, not
+ * the product of the two lengths. Two cheap checks come before the walk and only ever say "cannot match": a value that lacks a
+ * literal every match holds, or does not end with the literal the pattern ends on, is refused at once; inside the walk, a program
+ * that opens on a literal starts a thread only where that literal stands.
+ *
+ * It answers a different question from {@link wildcardMatch} (the permission-rule name glob), which is why the two are two
+ * engines and not one with a switch. The grammars differ:
+ *
+ *   | construct          | rule glob (`wildcardMatch`)   | filesystem glob (this module)                         |
+ *   | ------------------ | ----------------------------- | ----------------------------------------------------- |
+ *   | `*`                | any run, `/` included         | any run of characters but `/` (`star`)                |
+ *   | `**`               | the same as `*`               | any run, `/` included (`globstar`)                    |
+ *   | `?`                | a literal                     | one character but `/` (`one`)                         |
+ *   | `[abc]`, `[!a-c]`  | literals                      | one character of the class (`class`)                  |
+ *   | `{a,b}`            | literals                      | one alternative of several (`alt`)                    |
+ *   | where it may start | the whole value               | the whole path, or any path segment (`anchor`)        |
+ *
+ * Each site that reads such a glob (the search tools' `pattern` / `glob` arguments and `.gitignore` lines, the shell read
+ * station's expansion of a command word) parses its own spelling into tokens — what a spelling MEANS stays with the site — and
+ * this module is the one place that matches them.
+ *
+ * Lengths are counted in UTF-16 code units, the unit a RegExp without the `u` flag counts in: `?` and a class stand for one unit.
+ */
+/** One bracket-expression's test of a single code unit, already validated: build it with {@link fsGlobClass}. */
+export interface FsGlobClass {
+    /** Does this one code unit belong to the class? */
+    matches(unit: string): boolean;
+}
+/**
+ * A class from its character-class source (`[a-z]`, `[^/ab]`), or `undefined` when the source is not a class JavaScript accepts
+ * (a reversed range, say). A class is one character wide: its expression holds no repetition, so it cannot backtrack and the
+ * repetition structure of a glob stays in the program.
+ */
+export declare function fsGlobClass(source: string): FsGlobClass | undefined;
+/** A token that stands for a fixed or bounded part of the path. */
+export type FsGlobUnit = {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly kind: "one";
+} | {
+    readonly kind: "class";
+    readonly class: FsGlobClass;
+} | {
+    readonly kind: "star";
+};
+export type FsGlobToken = FsGlobUnit | {
+    readonly kind: "globstar";
+}
+/** One of several alternatives, each a run of units (no nesting). */
+ | {
+    readonly kind: "alt";
+    readonly alternatives: readonly (readonly FsGlobUnit[])[];
+};
+/** Where a match may begin: `start` only at the first character of the value; `segment` at the first character or right after any `/`. */
+export type FsGlobAnchor = "start" | "segment";
+/** A compiled glob: the whole of a value must match. */
+export interface FsGlob {
+    /** Does the whole of `value` match? */
+    test(value: string): boolean;
+}
+/**
+ * What the matcher has done in this process so far, for a pin to state a bound as a count instead of timing a call. `visits`: the
+ * (instruction, position) pairs entered — a test of a program `size` long against a path of `length` enters at most
+ * `size * (length + 1)`. `scratchBytes`: the bytes of the sets allocated — it moves when a program larger than any before needs
+ * scratch, and per test only for a program past the retained size.
+ */
+export declare function fsGlobWorkTotals(): {
+    readonly visits: number;
+    readonly scratchBytes: number;
+};
+/** A compiled program (see the module header). */
+export interface FsGlobProgram extends FsGlob {
+    /** The program's length in instructions: the factor of the visit bound that belongs to the pattern. */
+    readonly size: number;
+}
+/** Compile a token list. The match is always over the whole value; `anchor` says where it may begin. */
+export declare function compileFsGlob(tokens: readonly FsGlobToken[], anchor: FsGlobAnchor): FsGlobProgram;

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

@@ -0,0 +1,226 @@
+export function fsGlobClass(source) {
+    let re;
+    try {
+        re = new RegExp(source);
+    }
+    catch {
+        return undefined;
+    }
+    return { matches: (unit) => re.test(unit) };
+}
+const OP_TEXT = 0;
+const OP_ONE = 1;
+const OP_CLASS = 2;
+const OP_ANY = 3;
+const OP_SPLIT = 4;
+const OP_JUMP = 5;
+const OP_END = 6;
+const SLASH = 47;
+class LiveSet {
+    dense;
+    sparse;
+    count = 0;
+    constructor(capacity) {
+        this.dense = new Int32Array(capacity);
+        this.sparse = new Int32Array(capacity);
+    }
+    has(pc) {
+        const at = this.sparse[pc];
+        return at < this.count && this.dense[at] === pc;
+    }
+    add(pc) {
+        this.dense[this.count] = pc;
+        this.sparse[pc] = this.count++;
+    }
+}
+const MAX_RETAINED_SIZE = 1 << 16;
+let retained;
+let retainedCapacity = 0;
+const pending = [];
+let visitsTotal = 0;
+let scratchBytesTotal = 0;
+function scratchFor(size) {
+    const made = (capacity) => {
+        scratchBytesTotal += 16 * capacity;
+        return [new LiveSet(capacity), new LiveSet(capacity)];
+    };
+    if (size > MAX_RETAINED_SIZE)
+        return made(size);
+    if (retained === undefined || size > retainedCapacity) {
+        retainedCapacity = Math.max(size, retainedCapacity * 2, 1 << 8);
+        retained = made(retainedCapacity);
+    }
+    retained[0].count = 0;
+    retained[1].count = 0;
+    return retained;
+}
+export function fsGlobWorkTotals() {
+    return { visits: visitsTotal, scratchBytes: scratchBytesTotal };
+}
+const isStarRun = (token) => token.kind === "star" || token.kind === "globstar";
+export function compileFsGlob(tokens, anchor) {
+    const op = [];
+    const arg = [];
+    const arg2 = [];
+    const classes = [];
+    const emit = (o, a = 0, b = 0) => {
+        op.push(o);
+        arg.push(a);
+        arg2.push(b);
+        return op.length - 1;
+    };
+    const emitLoop = (unit) => {
+        const loop = emit(OP_SPLIT);
+        emit(unit);
+        emit(OP_JUMP, loop);
+        arg[loop] = loop + 1;
+        arg2[loop] = op.length;
+    };
+    const emitUnit = (unit) => {
+        if (unit.kind === "text")
+            for (let i = 0; i < unit.text.length; i++)
+                emit(OP_TEXT, unit.text.charCodeAt(i));
+        else if (unit.kind === "one")
+            emit(OP_ONE);
+        else if (unit.kind === "class")
+            emit(OP_CLASS, classes.push(unit.class) - 1);
+        else
+            emitLoop(OP_ONE);
+    };
+    const merged = [];
+    for (const token of tokens) {
+        const previous = merged[merged.length - 1];
+        if (previous !== undefined && isStarRun(previous) && isStarRun(token)) {
+            if (token.kind === "globstar")
+                merged[merged.length - 1] = token;
+        }
+        else
+            merged.push(token);
+    }
+    for (const token of merged) {
+        if (token.kind === "globstar")
+            emitLoop(OP_ANY);
+        else if (token.kind === "alt") {
+            const exits = [];
+            token.alternatives.forEach((alternative, k) => {
+                const last = k === token.alternatives.length - 1;
+                const choice = last ? -1 : emit(OP_SPLIT);
+                if (!last)
+                    arg[choice] = choice + 1;
+                for (const unit of alternative)
+                    emitUnit(unit);
+                if (!last) {
+                    exits.push(emit(OP_JUMP));
+                    arg2[choice] = op.length;
+                }
+            });
+            for (const exit of exits)
+                arg[exit] = op.length;
+        }
+        else
+            emitUnit(token);
+    }
+    emit(OP_END);
+    let required = "";
+    let run = "";
+    for (const token of merged) {
+        run = token.kind === "text" ? run + token.text : "";
+        if (run.length > required.length)
+            required = run;
+    }
+    return new Program(Int32Array.from(op), Int32Array.from(arg), Int32Array.from(arg2), classes, anchor === "segment", required, run);
+}
+class Program {
+    op;
+    arg;
+    arg2;
+    classes;
+    segmentAnchored;
+    required;
+    tail;
+    constructor(op, arg, arg2, classes, segmentAnchored, required, tail) {
+        this.op = op;
+        this.arg = arg;
+        this.arg2 = arg2;
+        this.classes = classes;
+        this.segmentAnchored = segmentAnchored;
+        this.required = required;
+        this.tail = tail;
+        this.first = op[0] === OP_TEXT ? arg[0] : -1;
+        this.beginsAfter = this.first >= 0 ? `/${String.fromCharCode(this.first)}` : "/";
+    }
+    first;
+    beginsAfter;
+    get size() {
+        return this.op.length;
+    }
+    follow(set, from) {
+        const { op, arg, arg2 } = this;
+        let added = 0;
+        let pc = from;
+        for (;;) {
+            if (!set.has(pc)) {
+                set.add(pc);
+                added++;
+                const o = op[pc];
+                if (o === OP_SPLIT) {
+                    pending.push(arg2[pc]);
+                    pc = arg[pc];
+                    continue;
+                }
+                if (o === OP_JUMP) {
+                    pc = arg[pc];
+                    continue;
+                }
+            }
+            if (pending.length === 0)
+                return added;
+            pc = pending.pop();
+        }
+    }
+    test(value) {
+        if (this.tail !== "" && !value.endsWith(this.tail))
+            return false;
+        if (this.required !== "" && !value.includes(this.required))
+            return false;
+        const { op, arg, classes } = this;
+        const length = value.length;
+        const [first, second] = scratchFor(op.length);
+        let live = first;
+        let ahead = second;
+        let entered = 0;
+        let found = false;
+        for (let pos = 0;;) {
+            if ((pos === 0 || (this.segmentAnchored && value.charCodeAt(pos - 1) === SLASH)) && (this.first < 0 || value.charCodeAt(pos) === this.first))
+                entered += this.follow(live, 0);
+            if (pos === length) {
+                found = live.has(op.length - 1);
+                break;
+            }
+            if (live.count === 0) {
+                if (!this.segmentAnchored)
+                    break;
+                const slash = value.indexOf(this.beginsAfter, pos);
+                if (slash < 0)
+                    break;
+                pos = slash + 1;
+                continue;
+            }
+            const unit = value.charCodeAt(pos);
+            ahead.count = 0;
+            for (let i = 0; i < live.count; i++) {
+                const pc = live.dense[i];
+                const o = op[pc];
+                const takes = o === OP_TEXT ? arg[pc] === unit : o === OP_ONE ? unit !== SLASH : o === OP_ANY ? true : o === OP_CLASS ? classes[arg[pc]].matches(value[pos]) : false;
+                if (takes)
+                    entered += this.follow(ahead, pc + 1);
+            }
+            const spent = live;
+            live = ahead;
+            ahead = spent;
+            pos++;
+        }
+        visitsTotal += entered;
+        return found;
+    }
+}

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

@@ -467,20 +467,20 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
             "- You must read a file before editing it.\n" +
             "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
-        descriptionClassic: "Reads a file from the local filesystem.\n" +
-            "\n" +
-            "Usage:\n" +
-            "- By default, it reads the whole file (from `offset`, 1-based); a very large file is served as a partial view with an explicit marker and the next-page call\n" +
-            "- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n" +
-            "- Results are returned using cat -n format, with each line prefixed by its line number and a tab\n" +
-            "- This tool allows the model to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually.\n" +
-            "- This tool can only read files, not directories. To read a directory, use Glob/Grep or an ls command via the Bash tool.\n" +
-            "- You must read a file before editing it.\n" +
-            "- Reads PDFs (.pdf): the document is provided to the model directly (text layer included). Use the `pages` parameter (e.g., \"1-5\") to read a page range; a PDF whose detected page count exceeds 10 requires `pages`. Maximum 20 pages per request.\n" +
-            "- Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
-            "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
-            "- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.\n" +
-            "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
+        descriptionVariants: [{ id: "classic", traits: { noneOf: ["lean_prompt"] }, text: "Reads a file from the local filesystem.\n" +
+                    "\n" +
+                    "Usage:\n" +
+                    "- By default, it reads the whole file (from `offset`, 1-based); a very large file is served as a partial view with an explicit marker and the next-page call\n" +
+                    "- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n" +
+                    "- Results are returned using cat -n format, with each line prefixed by its line number and a tab\n" +
+                    "- This tool allows the model to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually.\n" +
+                    "- This tool can only read files, not directories. To read a directory, use Glob/Grep or an ls command via the Bash tool.\n" +
+                    "- You must read a file before editing it.\n" +
+                    "- Reads PDFs (.pdf): the document is provided to the model directly (text layer included). Use the `pages` parameter (e.g., \"1-5\") to read a page range; a PDF whose detected page count exceeds 10 requires `pages`. Maximum 20 pages per request.\n" +
+                    "- Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
+                    "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
+                    "- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.\n" +
+                    "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you." }],
         parameters: Type.Object({
             ...FILE_PATH_PARAMS,
             offset: Type.Optional(Type.Integer({ minimum: 0, description: "The line number to start reading from. Only provide if the file is too large to read at once (1-based; default 1)." })),

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

@@ -189,13 +189,13 @@ export function createGlobTool(env, rootCanonical, rootsSeat, denySeat, readFace
             "\n" +
             "- On environments that do not report modification times, results fall back to alphabetical order\n" +
             "- Paths are RELATIVE to the root; ignored trees (node_modules/build/.gitignore) are skipped unless your pattern names them explicitly (e.g. `dist/**`)",
-        descriptionClassic: "- Fast file pattern matching tool that works with any codebase size\n" +
-            '- Supports glob patterns like "**/*.js" or "src/**/*.ts"\n' +
-            "- Returns matching file paths sorted by modification time\n" +
-            "- On environments that do not report modification times, results fall back to alphabetical order\n" +
-            "- Paths are RELATIVE to the root; ignored trees (node_modules/build/.gitignore) are skipped unless your pattern names them explicitly (e.g. `dist/**`)\n" +
-            "- Use this tool when you need to find files by name patterns; use `path` to scope to a sub-directory\n" +
-            "- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead (if available)",
+        descriptionVariants: [{ id: "classic", traits: { noneOf: ["lean_prompt"] }, text: "- Fast file pattern matching tool that works with any codebase size\n" +
+                    '- Supports glob patterns like "**/*.js" or "src/**/*.ts"\n' +
+                    "- Returns matching file paths sorted by modification time\n" +
+                    "- On environments that do not report modification times, results fall back to alphabetical order\n" +
+                    "- Paths are RELATIVE to the root; ignored trees (node_modules/build/.gitignore) are skipped unless your pattern names them explicitly (e.g. `dist/**`)\n" +
+                    "- Use this tool when you need to find files by name patterns; use `path` to scope to a sub-directory\n" +
+                    "- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead (if available)" }],
         parameters: Type.Object({
             pattern: Type.String({ description: "Glob pattern (`*`, `**`, `?`)." }),
             path: Type.Optional(Type.String({

package/dist/tools/fs/pattern-kill-guard.d.ts

@@ -0,0 +1,23 @@
+import type { ExecutionEnv } from "../../internal/harness.js";
+/** One killer the command spells and the questions to put to `pgrep` for it, or why the question cannot be put. */
+export interface PatternKillReading {
+    readonly text: string;
+    readonly probes: readonly (readonly string[])[];
+    /** Set when a word of the selector is decided only when the command runs. */
+    readonly computed?: string;
+    /** Set when the kill names every process the caller may signal — this agent's own among them — so there is nothing to ask. */
+    readonly everyProcess?: true;
+}
+/** The killers a command text spells, read off the plan the read station plans (nothing is read from disk or run). */
+export declare function patternKillReadings(command: string, cwd: string): PatternKillReading[];
+/**
+ * The refusal for a command whose pattern-kill would select this agent's own process or one above it — or undefined (run it).
+ * `cwd`: where the command stands, for the plan's read of its words (nothing is read from disk). Where the question is put is
+ * the env's own declaration ({@link processTableOf}): this process's table is asked, another table is not, and an env that does
+ * not say is refused. Windows is not asked: this process's table is not read there.
+ */
+export declare function patternKillRefusal(command: string, env: ExecutionEnv, cwd: string, signal?: AbortSignal): Promise<{
+    content: string;
+    isError: true;
+    details?: unknown;
+} | undefined>;