@sema-agent/core 7.14.0 → 7.15.0

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

@@ -25,40 +25,100 @@ function operandFamily(paths) {
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_CLASSIFY_DEFAULT_ALLOW);
     return (args) => {
-        const a = args;
-        const command = a?.command;
-        if (typeof command !== "string")
+        const command = shellCommandOf(args);
+        if (command === undefined)
             return { reversible: false };
         const resolved = typeof boundary === "function" ? boundary() : boundary;
-        const outOfRootGate = () => resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
-        const boundaryGate = (verdict) => verdict.readDenied === true || (verdict.recursiveReadPaths !== undefined && verdict.recursiveReadPaths.length > 0) ? { mandated: true } : outOfRootGate();
-        const backgrounded = a?.run_in_background === true;
+        const boundaryGate = (verdict) => readBoundaryMandate(command, allowSet, resolved, verdict);
+        const outOfRootGate = () => readBoundaryMandate(command, allowSet, resolved, {});
+        const backgrounded = isBackgroundShellCall(args);
         const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
         if (backgrounded)
             return { reversible: false, ...boundaryGate(detailed) };
         if (detailed.reason === undefined) {
             if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0) {
-                const recursive = detailed.recursiveReadPaths;
-                if (recursive !== undefined && recursive.length > 0) {
-                    const recursiveSet = new Set(recursive);
-                    const others = detailed.undecidedPaths.filter((p) => !recursiveSet.has(p));
-                    return {
-                        reversible: false,
-                        ...boundaryGate(detailed),
-                        cause: {
-                            code: RECURSIVE_READ_CAUSE_CODE,
-                            roots: operandFamily(recursive),
-                            ...(others.length > 0 ? { further: operandFamily(others) } : {}),
-                        },
-                    };
-                }
+                const cause = recursiveReadCause(detailed);
+                if (cause !== undefined)
+                    return { reversible: false, ...boundaryGate(detailed), cause };
                 return { reversible: false, ...outOfRootGate() };
             }
             return { reversible: true };
         }
-        return classifyBoundedReadonlyPollLoop(command, allowSet, resolved) === undefined
-            ? { reversible: true }
-            : { reversible: false, ...boundaryGate(detailed) };
+        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
+        if (loopRefusal === undefined)
+            return { reversible: true };
+        return { reversible: false, ...(pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal) === "declared" ? { mandated: true } : boundaryGate(detailed)) };
+    };
+}
+function attributeRefusal(face, resolved, fullRefusal) {
+    if (resolved === undefined)
+        return "shape";
+    const { denyMatch: _deny, ...withoutDenyJudge } = resolved;
+    const opened = face({ ...withoutDenyJudge, face: "open" });
+    if (opened === undefined || opened !== fullRefusal)
+        return "declared";
+    return face(undefined) === opened ? "shape" : "unread";
+}
+function pollLoopBoundaryVerdict(command, allowSet, resolved, fullRefusal) {
+    return attributeRefusal((b) => classifyBoundedReadonlyPollLoop(command, allowSet, b), resolved, fullRefusal);
+}
+function boundaryDeclared(verdict) {
+    return denyJudgeSpoke(verdict) || verdict.outOfRootRead === true;
+}
+function denyJudgeSpoke(verdict) {
+    return verdict.readDenied === true || (verdict.recursiveReadPaths !== undefined && verdict.recursiveReadPaths.length > 0);
+}
+function shellCommandOf(args) {
+    const command = args?.command;
+    return typeof command === "string" ? command : undefined;
+}
+function isBackgroundShellCall(args) {
+    return args?.run_in_background === true;
+}
+function readBoundaryMandate(command, allowSet, resolved, verdict) {
+    if (denyJudgeSpoke(verdict))
+        return { mandated: true };
+    return resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
+}
+function recursiveReadCause(detailed) {
+    const recursive = detailed.recursiveReadPaths;
+    if (recursive === undefined || recursive.length === 0)
+        return undefined;
+    const recursiveSet = new Set(recursive);
+    const others = (detailed.undecidedPaths ?? []).filter((p) => !recursiveSet.has(p));
+    return {
+        code: RECURSIVE_READ_CAUSE_CODE,
+        roots: operandFamily(recursive),
+        ...(others.length > 0 ? { further: operandFamily(others) } : {}),
+    };
+}
+export function bashReadBoundaryProbe(boundary) {
+    const allowSet = new Set(BASH_CLASSIFY_DEFAULT_ALLOW);
+    return (args) => {
+        const command = shellCommandOf(args);
+        if (command === undefined)
+            return { reversible: false };
+        const resolved = typeof boundary === "function" ? boundary() : boundary;
+        if (resolved === undefined)
+            return { reversible: true };
+        const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
+        if (boundaryDeclared(detailed)) {
+            const cause = recursiveReadCause(detailed);
+            return { reversible: false, mandated: true, ...(cause !== undefined ? { cause } : {}) };
+        }
+        if (detailed.reason === undefined) {
+            return detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0 ? { reversible: false } : { reversible: true };
+        }
+        const compound = attributeRefusal((b) => classifyCompoundReadonlyDetailed(command, allowSet, b).reason, resolved, detailed.reason);
+        if (compound === "declared")
+            return { reversible: false, mandated: true };
+        if (compound === "unread")
+            return { reversible: false };
+        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
+        if (loopRefusal === undefined)
+            return { reversible: true };
+        const loop = pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal);
+        return loop === "shape" ? { reversible: true } : loop === "declared" ? { reversible: false, mandated: true } : { reversible: false };
     };
 }
 export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
@@ -563,13 +623,10 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
             })),
         }),
         isConcurrencySafe: (args) => {
-            const cmd = args?.command;
-            if (typeof cmd !== "string")
-                return false;
-            const bg = args.run_in_background;
-            if (bg === true)
+            const command = shellCommandOf(args);
+            if (command === undefined || isBackgroundShellCall(args))
                 return false;
-            return coarseReadonlyCheck(cmd, new Set(BASH_READONLY_DEFAULT_ALLOW)) === undefined;
+            return coarseReadonlyCheck(command, new Set(BASH_READONLY_DEFAULT_ALLOW)) === undefined;
         },
         execute: async (args, ctx) => {
             const { command, timeout, run_in_background, description } = args;

package/package.json

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

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 2291,
+  "count": 2293,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -1256,6 +1256,7 @@
     "SharedMemoryStoreProvider": "interface",
     "SharedMemoryStoreReader": "interface",
     "ShellCommandShape": "interface",
+    "ShellGateDoctrine": "type",
     "ShellRedirection": "interface",
     "ShellSegment": "interface",
     "ShellWord": "interface",
@@ -1578,6 +1579,7 @@
     "autoModeArmingRecipeOf": "function",
     "backgroundAgentStoreContract": "function",
     "backgroundAgentStoreScopesContract": "function",
+    "bashReadBoundaryProbe": "function",
     "bashReversibilityProbe": "function",
     "boundaryPublishVerdict": "function",
     "boundedRedactedSummary": "function",
@@ -3549,6 +3551,7 @@
     "SharedMemoryStoreProvider": "advanced",
     "SharedMemoryStoreReader": "advanced",
     "ShellCommandShape": "advanced",
+    "ShellGateDoctrine": "advanced",
     "ShellRedirection": "advanced",
     "ShellSegment": "advanced",
     "ShellWord": "advanced",
@@ -3871,6 +3874,7 @@
     "autoModeArmingRecipeOf": "advanced",
     "backgroundAgentStoreContract": "advanced",
     "backgroundAgentStoreScopesContract": "advanced",
+    "bashReadBoundaryProbe": "advanced",
     "bashReversibilityProbe": "advanced",
     "boundaryPublishVerdict": "advanced",
     "boundedRedactedSummary": "advanced",