@sema-agent/core 5.17.0 → 5.18.1

package/dist/stores/file/permission-rule-store.js

@@ -0,0 +1,213 @@
+import { closeSync, constants as FS, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { PERMISSION_RULE_WRITER, applyTombstones, assertDeleteDeltaCarriesNoAdd, foldDelta } from "../../core/permission-rule-store.js";
+import { canonicalize } from "../../core/canonical-json.js";
+import { BootLock } from "./fs-atomic.js";
+const EMPTY_READ = { rules: [], tombstones: [], rev: 0 };
+function checksumOf(body) {
+    return `sha256:${createHash("sha256").update(canonicalize(body), "utf8").digest("hex")}`;
+}
+function assertSafeDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) {
+        throw new Error(`permission-rule store directory ${dir} is a symlink or not a directory; refusing to use it`);
+    }
+    if (typeof process.getuid === "function" && st.uid !== process.getuid()) {
+        throw new Error(`permission-rule store directory ${dir} is owned by another user; refusing to use it`);
+    }
+    if ((st.mode & 0o022) !== 0) {
+        throw new Error(`permission-rule store directory ${dir} is writable by group or others (mode ${(st.mode & 0o777).toString(8)}); ` +
+            `refusing to use it — anyone who can write here can grant themselves permissions`);
+    }
+}
+class FilePermissionRuleStore {
+    dir;
+    file;
+    acquireWriteLock;
+    onError;
+    durability = "durable";
+    fidelity = "json";
+    constructor(dir, file, acquireWriteLock, onError) {
+        this.dir = dir;
+        this.file = file;
+        this.acquireWriteLock = acquireWriteLock;
+        this.onError = onError;
+    }
+    read() {
+        let raw;
+        try {
+            assertSafeDir(this.dir);
+            const st = lstatSync(this.file);
+            if (st.isSymbolicLink() || !st.isFile()) {
+                const why = `${this.file} is a symlink or not a regular file; refusing to load any rule from it`;
+                this.disclose(why);
+                return { unreadable: why };
+            }
+            raw = readFileSync(this.file, "utf8");
+        }
+        catch (err) {
+            const e = err;
+            if (e?.code === "ENOENT")
+                return { absent: true };
+            const why = `could not read ${this.file}: ${e?.message ?? String(err)}; loading zero rules`;
+            this.disclose(why);
+            return { unreadable: why };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            const why = `${this.file} is not valid JSON (${err.message}); refusing the whole file and loading zero rules`;
+            this.disclose(why);
+            return { unreadable: why };
+        }
+        if (parsed?.schemaVersion !== 1 || !Array.isArray(parsed.rules) || !Array.isArray(parsed.tombstones) || typeof parsed.rev !== "number") {
+            const why = `${this.file} does not carry a readable rule-file shape; refusing the whole file and loading zero rules`;
+            this.disclose(why);
+            return { unreadable: why };
+        }
+        const { checksum, ...body } = parsed;
+        if (checksum !== checksumOf(body)) {
+            const why = `${this.file} failed its integrity check; refusing the whole file and loading zero rules`;
+            this.disclose(why);
+            return { unreadable: why };
+        }
+        return { file: parsed };
+    }
+    disclose(message) {
+        try {
+            this.onError?.(message);
+        }
+        catch {
+        }
+    }
+    write(next) {
+        assertSafeDir(this.dir);
+        const payload = JSON.stringify({ ...next, checksum: checksumOf(next) }, null, 2);
+        const tmp = join(this.dir, `.${randomBytes(8).toString("hex")}.tmp`);
+        let fd;
+        try {
+            fd = openSync(tmp, FS.O_WRONLY | FS.O_CREAT | FS.O_EXCL | (FS.O_NOFOLLOW ?? 0), 0o600);
+            writeFileSync(fd, payload);
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            renameSync(tmp, this.file);
+            let dfd;
+            try {
+                dfd = openSync(this.dir, "r");
+                fsyncSync(dfd);
+            }
+            catch {
+            }
+            finally {
+                if (dfd !== undefined)
+                    closeSync(dfd);
+            }
+        }
+        catch (err) {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                }
+            }
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+            }
+            throw err;
+        }
+    }
+    async list() {
+        const r = this.read();
+        if (!("file" in r))
+            return { ...EMPTY_READ };
+        return {
+            rules: applyTombstones(r.file.rules, r.file.tombstones),
+            tombstones: r.file.tombstones,
+            rev: r.file.rev,
+            checksum: r.file.checksum,
+        };
+    }
+    current() {
+        const r = this.read();
+        if ("unreadable" in r) {
+            throw new Error(`refusing to write the permission-rule store while it cannot be read: ${r.unreadable}`);
+        }
+        return "absent" in r
+            ? { schemaVersion: 1, actor: `file-${randomBytes(6).toString("hex")}`, counter: 0, rev: 0, rules: [], tombstones: [] }
+            : { schemaVersion: 1, actor: r.file.actor, counter: r.file.counter, rev: r.file.rev, rules: r.file.rules, tombstones: r.file.tombstones };
+    }
+    writeAndVerify(next) {
+        const expected = checksumOf(next);
+        this.write(next);
+        const after = this.read();
+        return "file" in after && after.file.checksum === expected;
+    }
+    writeChain = Promise.resolve();
+    serialize(fn) {
+        const run = this.writeChain.then(fn, fn);
+        this.writeChain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    get [PERMISSION_RULE_WRITER]() {
+        this.acquireWriteLock();
+        return this.writer;
+    }
+    writer = {
+        nextDot: async () => this.serialize(() => {
+            const cur = this.current();
+            const dot = { actor: cur.actor, counter: cur.counter + 1 };
+            if (!this.writeAndVerify({ ...cur, counter: dot.counter })) {
+                throw new Error("the permission-rule store did not survive its own write; refusing to hand out an identity");
+            }
+            return dot;
+        }),
+        apply: async (delta, opts) => this.serialize(() => {
+            const cur = this.current();
+            if (cur.rev !== opts.expectedRev)
+                return { conflict: true, rev: cur.rev };
+            const next = delta.kind === "redemption-add"
+                ? { ...cur, rev: cur.rev + 1, rules: foldDelta(cur.rules, delta) }
+                : (assertDeleteDeltaCarriesNoAdd(delta), { ...cur, rev: cur.rev + 1, tombstones: [...cur.tombstones, delta.tombstone] });
+            if (!this.writeAndVerify(next)) {
+                throw new Error("the permission-rule store did not survive its own write; the change was not committed");
+            }
+            return { rev: cur.rev + 1 };
+        }),
+    };
+}
+export class FilePermissionRuleStoreProvider {
+    dir;
+    onError;
+    lock;
+    constructor(dir, onError) {
+        this.dir = dir;
+        this.onError = onError;
+    }
+    acquireWriteLock = () => {
+        if (this.lock !== undefined)
+            return;
+        assertSafeDir(this.dir);
+        const lock = new BootLock(join(this.dir, "PERMISSION-RULES-WRITER-LOCK"));
+        lock.acquire();
+        this.lock = lock;
+    };
+    forPrincipal(principal) {
+        if (typeof principal !== "string" || principal === "") {
+            return { list: async () => ({ ...EMPTY_READ }), durability: "process-local" };
+        }
+        const name = `${createHash("sha256").update(principal, "utf8").digest("hex")}.json`;
+        return new FilePermissionRuleStore(this.dir, join(this.dir, name), this.acquireWriteLock, this.onError);
+    }
+    dispose() {
+        this.lock?.release();
+        this.lock = undefined;
+    }
+}

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

@@ -9,7 +9,7 @@ import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
 import { imageMagicMatches, withinAnyRoot } from "./safety.js";
 import { isRemoteExecutionEnv, hasDestroy, isIsolated } from "../../core/remote-env.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
-import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
+import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
 import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonly, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
@@ -498,7 +498,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
         description: bashDescription(coAuthor, timeoutCaps, bgNotifies, bgRetained, bgSessionScoped, bgEnvIsolatedOwned),
         parameters: Type.Object({
             command: Type.String({ description: "The command to execute" }),
-            timeout: Type.Optional(Type.Number({ description: `Optional timeout in milliseconds (max ${timeoutCaps.maxMs}; requests above the max are capped to it)` })),
+            timeout: Type.Optional(Type.Number({ description: bashTimeoutParamDescription(timeoutCaps, false) })),
             description: Type.Optional(Type.String({
                 description: 'Clear, concise description of what this command does in active voice. Never use words like "complex" or "risk" in the description - just describe what it does.\n' +
                     "\n" +
@@ -517,6 +517,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
             })),
         }),
         effect: "write",
+        contentOrigin: "execution",
         isConcurrencySafe: (args) => {
             const cmd = args?.command;
             if (typeof cmd !== "string")
@@ -528,6 +529,9 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
         },
         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" });
             if (run_in_background) {
                 if (!hasBackgroundShell(env)) {
                     return errorResult("Error (Bash): this environment does not support background processes (run_in_background).");
@@ -543,7 +547,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                     ...(requestedTimeoutSec !== undefined ? { timeout: requestedTimeoutSec } : {}),
                 });
                 if (!r.ok)
-                    return errorResult(`Error (Bash): ${r.error.message}`);
+                    return errorResult(`Error (Bash): the background process could not be started (${r.error.code}): ${envErrorDetail(r.error.message)}`);
                 const bgCaps = env.backgroundCapabilities;
                 const appliedTimeoutSec = typeof bgCaps.defaultBgTimeoutSec === "number" && typeof bgCaps.maxBgTimeoutSec === "number"
                     ? Math.min(requestedTimeoutSec ?? bgCaps.defaultBgTimeoutSec, bgCaps.maxBgTimeoutSec)
@@ -953,11 +957,14 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
             "Still subject to the deployment's approval policy.",
         parameters: Type.Object({
             command: Type.String({ description: "A single allowlisted read-only command (no shell operators)." }),
-            timeout: Type.Optional(Type.Number({ description: `Timeout in milliseconds (default ${timeoutCaps.defaultMs}, max ${timeoutCaps.maxMs}; requests above the max are capped to it).` })),
+            timeout: Type.Optional(Type.Number({ description: bashTimeoutParamDescription(timeoutCaps, true) })),
         }),
         effect: "read",
         execute: async (args, ctx) => {
             const { command, timeout } = args;
+            const timeoutRefusal = bashTimeoutArgRefusal(timeout, timeoutCaps);
+            if (timeoutRefusal !== undefined)
+                return errorResult(timeoutRefusal, { type: "bash_invalid_timeout", code: "bash_invalid_timeout" });
             const reason = coarseReadonlyCheck(command, allow);
             if (reason)
                 return errorResult(`Error (Bash): ${reason}`);
@@ -1008,7 +1015,7 @@ export function createEnvTaskOutputTool(env) {
             }
             const r = await env.pollBackground(id);
             if (!r.ok)
-                return errorResult(`Error (TaskOutput): ${r.error.message}`);
+                return errorResult(`Error (TaskOutput): could not read ${id} (${r.error.code}): ${envErrorDetail(r.error.message)}`);
             const shape = (text) => clipShellOutput(rx ? text.split(/\r?\n/).filter((l) => rx.test(l)).join("\n") : text);
             const status = r.value.status === "exited" ? `exited(code ${r.value.exitCode})` : r.value.status;
             const dropAcct = {};

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

@@ -30,6 +30,17 @@ export declare const BASH_DEFAULT_TIMEOUT_SEC = 120;
 export declare const BASH_MAX_TIMEOUT_SEC = 600;
 export declare const BASH_DEFAULT_TIMEOUT_MS: number;
 export declare const BASH_MAX_TIMEOUT_MS: number;
+export declare const MIN_BASH_TIMEOUT_MS = 1000;
+export declare const BASH_TIMEOUT_PLATEAU_END_MS = 1500;
+export declare function envErrorDetail(message: string | undefined): string;
+export declare function bashTimeoutParamDescription(caps: {
+    defaultMs: number;
+    maxMs: number;
+}, withDefault: boolean): string;
+export declare function bashTimeoutArgRefusal(timeoutMs: number | undefined, caps: {
+    defaultMs: number;
+    maxMs: number;
+}): string | undefined;
 export declare function resolveBashTimeoutCaps(opts?: {
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
@@ -37,6 +48,7 @@ export declare function resolveBashTimeoutCaps(opts?: {
     defaultMs: number;
     maxMs: number;
 };
+export declare function __resetBashTimeoutAnnouncements(): void;
 export declare function bashTimeoutCapsSec(caps: {
     defaultMs: number;
     maxMs: number;

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

@@ -59,19 +59,83 @@ export const BASH_DEFAULT_TIMEOUT_SEC = 120;
 export const BASH_MAX_TIMEOUT_SEC = 600;
 export const BASH_DEFAULT_TIMEOUT_MS = BASH_DEFAULT_TIMEOUT_SEC * 1000;
 export const BASH_MAX_TIMEOUT_MS = BASH_MAX_TIMEOUT_SEC * 1000;
+export const MIN_BASH_TIMEOUT_MS = 1000;
+export const BASH_TIMEOUT_PLATEAU_END_MS = 1500;
+function bashTimeoutDefect(ms) {
+    if (!Number.isFinite(ms))
+        return "must be a finite number of milliseconds";
+    if (ms <= 0)
+        return `must be a positive number of milliseconds (received ${ms})`;
+    if (ms < MIN_BASH_TIMEOUT_MS) {
+        return (`is in MILLISECONDS and ${ms} is under one second — if ${ms} seconds was meant, the value is ` +
+            `${ms * 1000}. Values below ${MIN_BASH_TIMEOUT_MS}ms all collapse to the same one-second budget`);
+    }
+    if (ms > MIN_BASH_TIMEOUT_MS && ms < BASH_TIMEOUT_PLATEAU_END_MS) {
+        return (`is ${ms}ms, which rounds down to the same one-second budget as ${MIN_BASH_TIMEOUT_MS}ms — the ` +
+            `shell's granularity is whole seconds, so write ${MIN_BASH_TIMEOUT_MS} for one second or at least ` +
+            `${BASH_TIMEOUT_PLATEAU_END_MS} for two`);
+    }
+    return undefined;
+}
 function validTimeoutMs(n) {
     if (n === undefined || !Number.isFinite(n))
         return undefined;
     const floored = Math.floor(n);
-    return floored >= 1 ? floored : undefined;
+    return bashTimeoutDefect(floored) === undefined ? floored : undefined;
+}
+export function envErrorDetail(message) {
+    const trimmed = (message ?? "").trim();
+    return trimmed === "" ? "the execution environment reported no reason" : trimmed;
+}
+const announcedTimeoutConfig = new Set();
+function announceDiscardedTimeout(knob, raw, usedMs) {
+    if (!Number.isFinite(raw) || raw <= 0)
+        return;
+    const defect = bashTimeoutDefect(Math.floor(raw));
+    if (defect === undefined)
+        return;
+    const line = `${knob}=${raw} was ignored — it ${defect}. Using ${usedMs}ms instead.`;
+    if (announcedTimeoutConfig.has(line))
+        return;
+    announcedTimeoutConfig.add(line);
+    console.warn(line);
+}
+export function bashTimeoutParamDescription(caps, withDefault) {
+    const bounds = `${withDefault ? `default ${caps.defaultMs}, ` : ""}min ${MIN_BASH_TIMEOUT_MS}, max ${caps.maxMs}`;
+    const escape = caps.maxMs >= BASH_TIMEOUT_PLATEAU_END_MS
+        ? ` — pass exactly ${MIN_BASH_TIMEOUT_MS} for one second, or ${BASH_TIMEOUT_PLATEAU_END_MS}+ for longer`
+        : ` — ${MIN_BASH_TIMEOUT_MS} is the only value this deployment accepts below its ${caps.maxMs}ms ceiling`;
+    return (`Timeout in milliseconds (${bounds}). The shell's granularity is whole seconds, so ${MIN_BASH_TIMEOUT_MS} is the ` +
+        `smallest accepted value and anything between ${MIN_BASH_TIMEOUT_MS} and ${BASH_TIMEOUT_PLATEAU_END_MS} is REJECTED ` +
+        `(it would round back down to ${MIN_BASH_TIMEOUT_MS})${escape}. Requests above the max are capped to it.`);
+}
+export function bashTimeoutArgRefusal(timeoutMs, caps) {
+    if (timeoutMs === undefined)
+        return undefined;
+    const defect = bashTimeoutDefect(timeoutMs);
+    if (defect === undefined)
+        return undefined;
+    return (`Error (Bash): \`timeout\` ${defect}. The command was NOT run. Omit \`timeout\` to use the default ` +
+        `budget of ${caps.defaultMs}ms (maximum ${caps.maxMs}ms).`);
 }
 export function resolveBashTimeoutCaps(opts) {
     const defaultMs = validTimeoutMs(opts?.bashDefaultTimeoutMs) ??
         validTimeoutMs(Number(process.env.BASH_DEFAULT_TIMEOUT_MS)) ??
         BASH_DEFAULT_TIMEOUT_MS;
     const maxMs = Math.max(validTimeoutMs(opts?.bashMaxTimeoutMs) ?? validTimeoutMs(Number(process.env.BASH_MAX_TIMEOUT_MS)) ?? BASH_MAX_TIMEOUT_MS, defaultMs);
+    if (opts?.bashDefaultTimeoutMs !== undefined)
+        announceDiscardedTimeout("bashDefaultTimeoutMs", opts.bashDefaultTimeoutMs, defaultMs);
+    else if (process.env.BASH_DEFAULT_TIMEOUT_MS !== undefined)
+        announceDiscardedTimeout("BASH_DEFAULT_TIMEOUT_MS", Number(process.env.BASH_DEFAULT_TIMEOUT_MS), defaultMs);
+    if (opts?.bashMaxTimeoutMs !== undefined)
+        announceDiscardedTimeout("bashMaxTimeoutMs", opts.bashMaxTimeoutMs, maxMs);
+    else if (process.env.BASH_MAX_TIMEOUT_MS !== undefined)
+        announceDiscardedTimeout("BASH_MAX_TIMEOUT_MS", Number(process.env.BASH_MAX_TIMEOUT_MS), maxMs);
     return { defaultMs, maxMs };
 }
+export function __resetBashTimeoutAnnouncements() {
+    announcedTimeoutConfig.clear();
+}
 export function bashTimeoutCapsSec(caps) {
     return { defaultSec: Math.max(1, Math.round(caps.defaultMs / 1000)), maxSec: Math.max(1, Math.round(caps.maxMs / 1000)) };
 }

package/dist/tools/web.js

@@ -251,6 +251,7 @@ export function webFetchToolSpec(config = {}) {
                 : {}),
         }),
         effect: "read",
+        contentOrigin: "external",
         execute: async (args, ctx) => {
             const { url, prompt } = args;
             const startedAt = Date.now();
@@ -811,6 +812,7 @@ export function createWebSearchTool(config) {
             blocked_domains: Type.Optional(Type.Array(Type.String(), { description: "Never include search results from these domains" })),
         }),
         effect: "read",
+        contentOrigin: "external",
         execute: async (args, ctx) => {
             const { query, allowed_domains, blocked_domains } = args;
             const startedAt = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.17.0",
+  "version": "5.18.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",