@sema-agent/core 2.7.0 → 2.8.0

package/dist/agents/send-message-tool.d.ts

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import type { Runner } from "../core/runner/runtask.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
+import { type ToolCtxEnricher } from "../core/tools.js";
 import { SubagentRetainLedger } from "./retain-ledger.js";
 import { type SubagentSteerHandle } from "./subagent.js";
 export declare const SEND_MESSAGE_TOOL_NAME = "SendMessage";
@@ -35,6 +36,7 @@ export interface SendMessageToolOptions {
         content: string;
         details?: unknown;
     }>;
+    enrichCtx?: ToolCtxEnricher;
 }
 export declare const SEND_MESSAGE_SUMMARY_MAX = 200;
 export declare function clipSendMessageSummary(raw: string): string;

package/dist/agents/send-message-tool.js

@@ -554,5 +554,5 @@ export function createSendMessageTool(opts) {
                 }
             });
         },
-    });
+    }, opts.enrichCtx !== undefined ? { enrichCtx: opts.enrichCtx } : {});
 }

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

@@ -1278,6 +1278,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...(internals?.parentRetainLedger !== undefined ? { siblingRetain: internals.parentRetainLedger } : {}),
                     ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
                     ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
+                    enrichCtx: enrichSpecToolCtx,
                     ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
                     ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
                     ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),

package/dist/core/store-contracts/file-snapshot-store-contract.d.ts

@@ -1,3 +1,5 @@
 import type { FileSnapshotStore } from "../file-snapshot-store.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
-export declare function fileSnapshotStoreContract(make: () => FileSnapshotStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function fileSnapshotStoreContract(make: () => FileSnapshotStore, runAssertion?: ContractAssertionRunner, options?: {
+    blobGc?: "immediate" | "eventual";
+}): Promise<void>;

package/dist/core/store-contracts/file-snapshot-store-contract.js

@@ -4,8 +4,9 @@ import { beginContract } from "./contract-harness.js";
 const bytes = (s) => new TextEncoder().encode(s);
 const sha256 = (s) => createHash("sha256").update(bytes(s)).digest("hex");
 const srcBlob = async (hash) => hash === sha256("alpha") ? bytes("alpha") : hash === sha256("beta") ? bytes("beta") : undefined;
-export async function fileSnapshotStoreContract(make, runAssertion) {
+export async function fileSnapshotStoreContract(make, runAssertion, options) {
     const { run, settle } = beginContract(runAssertion);
+    const blobGc = options?.blobGc ?? "immediate";
     run("kit prerequisites: exportManifest/getBlob/putBlob/importManifest are implemented (REQUIRED by this kit)", async () => {
         const probe = make();
         const missing = ["exportManifest", "getBlob", "putBlob", "importManifest"].filter((m) => typeof probe[m] !== "function");
@@ -115,12 +116,19 @@ export async function fileSnapshotStoreContract(make, runAssertion) {
         assert.deepEqual(await store.listKeys("sc"), ["k1"]);
         assert.deepEqual([...(await store.getBlob(sha256("alpha")))], [...bytes("alpha")]);
     });
-    run("reap keep-nothing drops the key and GCs the now-unreferenced blobs", async () => {
+    run("reap keep-nothing drops the key IMMEDIATELY (every backend)", async () => {
         const store = make();
         await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
         assert.equal(await store.reap("sc", []), 1);
         assert.equal(await store.has("sc", "k1"), false);
-        assert.equal(await store.getBlob(sha256("alpha")), undefined);
     });
+    if (blobGc === "immediate") {
+        run("reap keep-nothing GCs the now-unreferenced blob bytes immediately (blobGc: immediate)", async () => {
+            const store = make();
+            await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
+            assert.equal(await store.reap("sc", []), 1);
+            assert.equal(await store.getBlob(sha256("alpha")), undefined);
+        });
+    }
     await settle();
 }

package/dist/core/tools.d.ts

@@ -1,6 +1,6 @@
 import type { TSchema } from "typebox";
 import type { AgentTool } from "../internal/harness.js";
-import type { ToolSpec } from "./types.js";
+import type { ToolExecuteContext, ToolSpec } from "./types.js";
 export declare function errorResult(text: string, details?: unknown): {
     content: string;
     isError: true;
@@ -8,4 +8,8 @@ export declare function errorResult(text: string, details?: unknown): {
 };
 export declare function isDefineToolProduct(x: unknown): x is AgentTool;
 export declare function stampDefineToolBrand<T extends object>(tool: T): T;
-export declare function defineTool<TParams extends TSchema = TSchema>(spec: ToolSpec<TParams>): AgentTool<TParams>;
+export type ToolCtxEnricher = (base: ToolExecuteContext) => ToolExecuteContext;
+export interface DefineToolOptions {
+    enrichCtx?: ToolCtxEnricher;
+}
+export declare function defineTool<TParams extends TSchema = TSchema>(spec: ToolSpec<TParams>, options?: DefineToolOptions): AgentTool<TParams>;

package/dist/core/tools.js

@@ -33,7 +33,7 @@ export function stampDefineToolBrand(tool) {
     Object.defineProperty(tool, DEFINE_TOOL_BRAND, { value: true, enumerable: false });
     return tool;
 }
-export function defineTool(spec) {
+export function defineTool(spec, options) {
     const executionMode = spec.executionMode ?? (spec.effect === "read" ? "parallel" : "sequential");
     const tool = {
         name: spec.name,
@@ -60,7 +60,8 @@ export function defineTool(spec) {
             }
             let ret;
             try {
-                ret = await spec.execute(params, { toolCallId, signal });
+                const baseCtx = { toolCallId, signal };
+                ret = await spec.execute(params, options?.enrichCtx ? { ...options.enrichCtx(baseCtx), toolCallId, signal } : baseCtx);
             }
             catch (err) {
                 throw new Error(formatToolError(err));

package/dist/index.d.ts

@@ -69,7 +69,7 @@ export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, Ch
 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 { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, 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";
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";
 export { captureManifest, applyManifest } from "./core/file-snapshot-store.js";

package/dist/index.js

@@ -60,7 +60,7 @@ 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 { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, } 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";
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";
 export { captureManifest, applyManifest } from "./core/file-snapshot-store.js";

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

@@ -17,4 +17,5 @@ export interface CompoundReadonlyVerdict {
 }
 export declare function formatOutOfRootReadApprovalOption(directory: string): string;
 export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+export declare function classifySimpleCommandReadBoundary(command: 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

@@ -82,6 +82,13 @@ function resolveOperandLexically(base, operand, homeDir) {
         return undefined;
     return normalizeAbsPathLexicalEitherFamily(`${base.replace(/[/\\]+$/, "")}/${raw}`);
 }
+function tokenizeSegment(segment) {
+    return segment
+        .trim()
+        .split(/\s+/)
+        .filter((t) => t.length > 0)
+        .map(foldQuoteRemovalToken);
+}
 function collectSegmentBoundaryFindings(toks, boundary) {
     const name = toks[0];
     if (NO_PATH_OPERAND_COMMANDS.has(name))
@@ -220,8 +227,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
     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);
+        const toks = tokenizeSegment(segments[si]);
         if (toks.length === 0)
             continue;
         foldedSegments.push(toks);
@@ -273,27 +279,35 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
             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" };
         }
     }
-    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),
-            };
+    if (boundary !== undefined)
+        return evaluateReadBoundary(foldedSegments, boundary);
+    return {};
+}
+function evaluateReadBoundary(foldedSegments, boundary) {
+    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);
         }
     }
-    return {};
+    if (outside.length === 0)
+        return {};
+    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),
+    };
+}
+export function classifySimpleCommandReadBoundary(command, boundary) {
+    const toks = tokenizeSegment(command);
+    if (toks.length === 0)
+        return {};
+    return evaluateReadBoundary([toks], boundary);
 }
 export function classifyCompoundReadonly(command, allow, boundary) {
     return classifyCompoundReadonlyDetailed(command, allow, boundary).reason;

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

@@ -31,9 +31,10 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
 }): AgentTool;
-export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption, timeoutOpts?: {
+export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption, opts?: {
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
+    additionalRoots?: readonly string[];
 }): AgentTool;
 export declare function createEnvTaskOutputTool(env: ExecutionEnv): AgentTool;
 export declare function createEnvTaskStopTool(env: ExecutionEnv, registry?: TaskRegistry): AgentTool;

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

@@ -8,7 +8,7 @@ import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
 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";
+import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyCompoundReadonly, classifySimpleCommandReadBoundary, } from "./bash-readonly-classifier.js";
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
     return (args) => {
@@ -627,16 +627,20 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
         },
     });
 }
-export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, timeoutOpts) {
-    const timeoutCaps = resolveBashTimeoutCaps(timeoutOpts);
+export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, opts) {
+    const timeoutCaps = resolveBashTimeoutCaps(opts);
     const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
     const sample = [...allow].slice(0, 6).join(", ");
+    const readRoots = [rootCanonical, ...(opts?.additionalRoots ?? [])];
+    const mintedOutputFiles = new Set();
     return defineTool({
         name: "Bash",
         contract: { contractId: "core.bash_readonly@1", implementationRevision: "1" },
         description: `Run a SINGLE read-only inspection command (e.g. ${sample}, …) and return its output. Shell ` +
             "operators (pipes, redirects, ;, &&, command substitution, subshells) are rejected and only " +
-            "allowlisted commands run. Still subject to the deployment's approval policy.",
+            "allowlisted commands run. Reads are confined to the workspace root(s): a path outside them is " +
+            "refused, as is one that cannot be resolved statically (e.g. a `~` path). 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).` })),
@@ -647,7 +651,17 @@ export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, tim
             const reason = coarseReadonlyCheck(command, allow);
             if (reason)
                 return errorResult(`Error (Bash): ${reason}`);
-            return runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, execClamp, ctx.toolCallId, true);
+            const boundary = classifySimpleCommandReadBoundary(command, { roots: [...readRoots, ...mintedOutputFiles], cwd: rootCanonical });
+            if (boundary.reason !== undefined) {
+                return errorResult(`Error (Bash): ${boundary.reason}. bash_readonly is confined to the workspace roots; it has no approval path, so the call is refused rather than escalated.`, { code: "readonly_out_of_root", paths: boundary.outOfRootPaths ?? [] });
+            }
+            const result = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, execClamp, ctx.toolCallId, true);
+            if (typeof result !== "string") {
+                const outputFile = result.details.output_file;
+                if (typeof outputFile === "string")
+                    mintedOutputFiles.add(outputFile);
+            }
+            return result;
         },
     });
 }

package/dist/tools/fs/index.js

@@ -38,6 +38,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
             ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), opts.execClamp, {
                 ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
                 ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
+                ...(additionalRoots !== undefined ? { additionalRoots } : {}),
             })
             : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {
                 taskRegistry: opts.taskRegistry,

package/package.json

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