@sema-agent/core 2.6.0 → 2.7.0

package/dist/core/background-agent-store.d.ts

@@ -37,6 +37,9 @@ export interface BackgroundAgentRecord {
     finalOutput?: string;
     finalOutputFull?: string;
     error?: string;
+    errorCode?: string;
+    errorRetryable?: boolean;
+    errorKind?: string;
     resultIsPartial?: boolean;
     recentSteps?: SubagentStep[];
     editedFiles?: SubagentEditedFile[];

package/dist/core/runner/prepare-task.js

@@ -1225,14 +1225,18 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 shellGatedBash = !egressTools.has("Bash") && !irreversibilityTier.has("Bash");
                 irreversibilityTier.set("Bash", shellGate === "always" ? "always" : "maybe");
                 irreversibleTools.add("Bash");
+                const shellReadBoundary = () => ({
+                    roots: [rootCanonical, ...additionalRootsCanonical],
+                    ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
+                });
                 if (shellGate === "classify")
-                    reversibilityProbes.set("Bash", bashReversibilityProbe());
+                    reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
                 if (backgroundTaskToolsActive) {
                     shellGatedMonitor = !egressTools.has("Monitor") && !irreversibilityTier.has("Monitor");
                     irreversibilityTier.set("Monitor", shellGate === "always" ? "always" : "maybe");
                     irreversibleTools.add("Monitor");
                     if (shellGate === "classify")
-                        reversibilityProbes.set("Monitor", bashReversibilityProbe());
+                        reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
                 }
             }
         }

package/dist/core/task-registry-agent.js

@@ -723,6 +723,9 @@ export function settleBackgroundAgentLane(core, id, outcome) {
         ...(handle.resultFull !== undefined ? { finalOutputFull: handle.resultFull } : {}),
         ...(handle.resultIsPartial ? { resultIsPartial: true } : {}),
         ...(handle.error !== undefined ? { error: handle.error } : {}),
+        ...(handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
+        ...(handle.errorRetryable !== undefined ? { errorRetryable: handle.errorRetryable } : {}),
+        ...(handle.errorKind !== undefined ? { errorKind: handle.errorKind } : {}),
     }, ["parkedCheckpointToken", "parkClaimId", "parkedAt"]);
     return outcome.status;
 }
@@ -856,7 +859,22 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
     handle.cycleSeq = (handle.cycleSeq ?? 1) + 1;
     handle.updatedAt = Date.now();
-    durableAgentWriteLane(handle, { status: "running" }, ["settledAt", "stoppedBy", "finalOutput", "finalOutputFull", "error", "resultIsPartial", "completionId", "summary", "recentSteps", "editedFiles", "usage"]);
+    durableAgentWriteLane(handle, { status: "running" }, [
+        "settledAt",
+        "stoppedBy",
+        "finalOutput",
+        "finalOutputFull",
+        "error",
+        "errorCode",
+        "errorRetryable",
+        "errorKind",
+        "resultIsPartial",
+        "completionId",
+        "summary",
+        "recentSteps",
+        "editedFiles",
+        "usage",
+    ]);
     return { ok: true, cycle: handle.reviveCycle };
 }
 export function settleRevivedAgentLane(core, id, cycle, outcome) {
@@ -1019,8 +1037,11 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
             },
         };
     }
+    const kindClause = row.status === "failed" && row.errorKind !== undefined && row.errorRetryable !== undefined
+        ? ` (error_kind: ${row.errorKind}, retryable: ${row.errorRetryable})`
+        : "";
     const body = `status: ${row.status}
-${row.error ? `error: ${row.error}
+${row.error ? `error: ${row.error}${kindClause}
 ` : ""}${row.finalOutput ? `--- result${row.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
 ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}`;
     return {
@@ -1034,6 +1055,8 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
             ...(row.seq !== undefined ? { seq: row.seq } : {}),
             ...(row.resultIsPartial ? { partial_result: true } : {}),
             ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
+            ...(row.status === "failed" && row.errorCode !== undefined ? { errorCode: row.errorCode } : {}),
+            ...(row.status === "failed" && row.errorRetryable !== undefined ? { retryable: row.errorRetryable } : {}),
         },
         ...(row.status === "failed" ? { isError: true } : {}),
     };

package/dist/index.d.ts

@@ -67,6 +67,7 @@ export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, CheckResult, } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, type ToolResultStore, type ToolResultSlice, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type ResourceLedger, type ResourceLimitReason, } from "./core/checkpoint-store.js";

package/dist/index.js

@@ -58,6 +58,7 @@ export { runExecGate } from "./core/exec-gate.js";
 export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core/untrusted-text.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";

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

@@ -5,4 +5,16 @@ export declare function parseLeadingCommandName(command: string): {
     reject: string;
 };
 export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>): string | undefined;
-export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>): string | undefined;
+export interface BashReadonlyRootBoundary {
+    roots: readonly string[];
+    cwd?: string;
+    homeDir?: string;
+}
+export interface CompoundReadonlyVerdict {
+    reason?: string;
+    outOfRootRead?: true;
+    outOfRootPaths?: readonly string[];
+}
+export declare function formatOutOfRootReadApprovalOption(directory: string): string;
+export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;

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

@@ -1,4 +1,4 @@
-import { isBlockedDevicePath, normalizeAbsPathLexically } from "./safety.js";
+import { isBlockedDevicePath, normalizeAbsPathLexically, withinAnyRoot } from "./safety.js";
 export const BASH_READONLY_DEFAULT_ALLOW = [
     "ls", "cat", "head", "tail", "wc", "pwd", "echo", "whoami", "uname",
     "grep", "cut", "tr", "basename", "dirname", "stat", "du", "df", "which",
@@ -49,12 +49,102 @@ function foldQuoteRemovalToken(tok) {
     }
     return out;
 }
-export function classifyCompoundReadonly(command, allow) {
+export function formatOutOfRootReadApprovalOption(directory) {
+    const trimmed = directory.replace(/[/\\]+$/, "");
+    const cut = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+    const leaf = cut >= 0 ? trimmed.slice(cut + 1) : trimmed;
+    return `Yes, allow reading from ${leaf || directory}/ from this project`;
+}
+const NO_PATH_OPERAND_COMMANDS = new Set(["pwd", "echo", "whoami", "uname", "which", "tr", "basename", "dirname"]);
+function isAbsolutePathToken(p) {
+    return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p);
+}
+function isPathShapedToken(tok) {
+    return tok.includes("/") || tok.startsWith("~") || tok === "." || tok === "..";
+}
+function normalizeAbsPathLexicalEitherFamily(p) {
+    const s = p.replace(/\\/g, "/");
+    return /^[A-Za-z]:\//.test(s) ? s.slice(0, 2) + normalizeAbsPathLexically(s.slice(2)) : normalizeAbsPathLexically(s);
+}
+function resolveOperandLexically(base, operand, homeDir) {
+    let raw = operand;
+    if (raw === "~" || raw.startsWith("~/")) {
+        if (homeDir === undefined || !isAbsolutePathToken(homeDir))
+            return undefined;
+        raw = raw === "~" ? homeDir : `${homeDir.replace(/[/\\]+$/, "")}/${raw.slice(2)}`;
+    }
+    else if (raw.startsWith("~")) {
+        return undefined;
+    }
+    if (isAbsolutePathToken(raw))
+        return normalizeAbsPathLexicalEitherFamily(raw);
+    if (base === undefined || !isAbsolutePathToken(base))
+        return undefined;
+    return normalizeAbsPathLexicalEitherFamily(`${base.replace(/[/\\]+$/, "")}/${raw}`);
+}
+function collectSegmentBoundaryFindings(toks, boundary) {
+    const name = toks[0];
+    if (NO_PATH_OPERAND_COMMANDS.has(name))
+        return [];
+    const args = toks.slice(1);
+    const findings = [];
+    const candidates = [];
+    if (name === "cd") {
+        const target = args.find((t) => !t.startsWith("-") || t === "-");
+        if (target === undefined) {
+            return [{ kind: "unresolvable", reason: '`cd` with no argument targets the home directory, which cannot be checked against the allowed directories — not auto-allowed' }];
+        }
+        if (target === "-") {
+            return [{ kind: "unresolvable", reason: '`cd -` targets the previous working directory, which cannot be resolved statically — not auto-allowed' }];
+        }
+        candidates.push(target);
+    }
+    else {
+        const patternSuppliedByFlag = name === "grep" && args.some((t) => t === "-e" || t.startsWith("-e") || t === "-f" || t.startsWith("-f") || t.startsWith("--regexp") || t.startsWith("--file"));
+        let sawOperand = false;
+        for (let k = 0; k < args.length; k++) {
+            const t = args[k];
+            if (name === "cut" && (t === "-d" || t === "--delimiter" || t === "--output-delimiter")) {
+                k++;
+                continue;
+            }
+            if (t.startsWith("-") && t !== "-") {
+                const eq = t.indexOf("=");
+                const value = eq > 0 ? t.slice(eq + 1) : "";
+                if (value.length > 0 && isAbsolutePathToken(value))
+                    candidates.push(value);
+                continue;
+            }
+            if (t === "-")
+                continue;
+            const isGrepPatternSlot = name === "grep" && !patternSuppliedByFlag && !sawOperand;
+            sawOperand = true;
+            if (isGrepPatternSlot)
+                continue;
+            if (isPathShapedToken(t))
+                candidates.push(t);
+        }
+    }
+    for (const candidate of candidates) {
+        const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], candidate, boundary.homeDir);
+        if (resolved === undefined) {
+            findings.push({
+                kind: "unresolvable",
+                reason: `"${name}" names the path "${candidate}", which cannot be resolved statically — not auto-allowed`,
+            });
+            continue;
+        }
+        if (!withinAnyRoot(boundary.roots, resolved))
+            findings.push({ kind: "outside", command: name, path: resolved });
+    }
+    return findings;
+}
+export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
     const trimmed = command.trim();
     if (!trimmed)
-        return "empty command";
+        return { reason: "empty command" };
     if (SHELL_SEGMENT_HARD_REJECT.test(trimmed)) {
-        return "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed";
+        return { reason: "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed" };
     }
     const source = trimmed.endsWith(";") ? trimmed.slice(0, -1) : trimmed;
     const segments = [];
@@ -70,7 +160,7 @@ export function classifyCompoundReadonly(command, allow) {
                 i++;
             }
             else
-                return "`&` backgrounding is not allowed — a backgrounded process outlives the command";
+                return { reason: "`&` backgrounding is not allowed — a backgrounded process outlives the command" };
         }
         else if (c === "|") {
             if (source[i + 1] === "|") {
@@ -97,7 +187,7 @@ export function classifyCompoundReadonly(command, allow) {
     for (const segment of segments) {
         const reason = coarseReadonlyCheck(segment, allow);
         if (reason !== undefined)
-            return reason;
+            return { reason };
     }
     const HEAD_AUTO_ALLOW_MAX = 1_000_000;
     const headBoundIsSmall = (name, toks) => {
@@ -128,11 +218,13 @@ export function classifyCompoundReadonly(command, allow) {
         return byteBound;
     };
     const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity };
+    const foldedSegments = [];
     for (let si = 0; si < segments.length; si++) {
         const toks = segments[si].trim().split(/\s+/).filter((t) => t.length > 0)
             .map(foldQuoteRemovalToken);
         if (toks.length === 0)
             continue;
+        foldedSegments.push(toks);
         const name = toks[0];
         const nonOption = toks.slice(1).filter((t) => !t.startsWith("-"));
         if (!(pipeFed[si] ?? false)) {
@@ -165,21 +257,44 @@ export function classifyCompoundReadonly(command, allow) {
                 }
             }
             if (floor !== undefined && hasStdinDash) {
-                return `"${name}" reads stdin via an explicit "-" argument and would block until the tool timeout — not auto-allowed`;
+                return { reason: `"${name}" reads stdin via an explicit "-" argument and would block until the tool timeout — not auto-allowed` };
             }
             if (floor !== undefined && nonOption.length < floor) {
-                return `"${name}" with no file argument reads stdin and would block until the tool timeout — not auto-allowed`;
+                return { reason: `"${name}" with no file argument reads stdin and would block until the tool timeout — not auto-allowed` };
             }
         }
         if (name === "tail" && toks.slice(1).some((t) => t === "--follow" || t.startsWith("--follow=") || /^[-+][^\s]*[fF]/.test(t))) {
-            return "`tail` in follow mode never terminates — not auto-allowed";
+            return { reason: "`tail` in follow mode never terminates — not auto-allowed" };
         }
         const GENERATOR_DEVICES = new Set(["/dev/zero", "/dev/random", "/dev/urandom", "/dev/full"]);
         const deviceArgs = toks.slice(1).filter((t) => !t.startsWith("-")).map(normalizeAbsPathLexically).filter(isBlockedDevicePath);
         const rescuedByHead = headBoundIsSmall(name, toks) && deviceArgs.every((d) => GENERATOR_DEVICES.has(d));
         if (!rescuedByHead && deviceArgs.length > 0) {
-            return "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) — not auto-allowed";
+            return { reason: "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) — not auto-allowed" };
         }
     }
-    return undefined;
+    if (boundary !== undefined) {
+        const outside = [];
+        for (const toks of foldedSegments) {
+            for (const finding of collectSegmentBoundaryFindings(toks, boundary)) {
+                if (finding.kind === "unresolvable")
+                    return { reason: finding.reason };
+                if (!outside.some((o) => o.path === finding.path))
+                    outside.push(finding);
+            }
+        }
+        if (outside.length > 0) {
+            const paths = outside.map((o) => `"${o.path}"`).join(", ");
+            const allowed = boundary.roots.length > 0 ? boundary.roots.join(", ") : "(none)";
+            return {
+                reason: `"${outside[0].command}" reads ${paths}, outside the allowed directories for this session: ${allowed} — not auto-allowed`,
+                outOfRootRead: true,
+                outOfRootPaths: outside.map((o) => o.path),
+            };
+        }
+    }
+    return {};
+}
+export function classifyCompoundReadonly(command, allow, boundary) {
+    return classifyCompoundReadonlyDetailed(command, allow, boundary).reason;
 }

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

@@ -1,7 +1,8 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type CwdRef } from "./fs-shared.js";
-export declare function bashReversibilityProbe(allow?: readonly string[]): (args: unknown) => {
+import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
+export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => {
     reversible: boolean;
 };
 export interface ExecClampOption {

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

@@ -9,13 +9,14 @@ import { imageMagicMatches, withinAnyRoot } from "./safety.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, } from "./fs-shared.js";
 import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyCompoundReadonly } from "./bash-readonly-classifier.js";
-export function bashReversibilityProbe(allow) {
+export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
     return (args) => {
         const command = args?.command;
         if (typeof command !== "string")
             return { reversible: false };
-        return { reversible: classifyCompoundReadonly(command, allowSet) === undefined };
+        const resolved = typeof boundary === "function" ? boundary() : boundary;
+        return { reversible: classifyCompoundReadonly(command, allowSet, resolved) === undefined };
     };
 }
 const EXIT1_INTERPRETATION = {

package/package.json

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