@sema-agent/core 5.13.0 → 5.14.0

package/dist/stores/file/index.js

@@ -45,7 +45,7 @@ export class FileStorageBackend {
             const corruptRead = opts.onCorruptRead !== undefined ? { onCorruptRead: opts.onCorruptRead } : undefined;
             const repo = new FileSessionRepo(this.root, corruptRead);
             this.fileSessions = repo;
-            this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget" });
+            this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable" });
             this.sessionStore = this.ttl;
             this.fileCheckpoints = new FileCheckpointStore(this.root, opts.checkpoint);
             this.checkpointStore = this.fileCheckpoints;

package/dist/stores/file/session-store.d.ts

@@ -24,5 +24,7 @@ export declare class FileSessionRepo implements SessionRepo {
     delete(metadata: SessionMetadata): Promise<void>;
     fork(sourceMetadata: SessionMetadata, options?: SessionForkOptions): Promise<Session>;
     exportEntries(sessionId: string): Promise<SessionTreeEntry[]>;
-    importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[]): Promise<void>;
+    importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[], options?: {
+        preserveActorAssertions?: boolean;
+    }): Promise<void>;
 }

package/dist/stores/file/session-store.js

@@ -191,9 +191,9 @@ export class FileSessionRepo {
     async exportEntries(sessionId) {
         return this.read(sessionId).entries;
     }
-    async importEntries(sessionId, owner, entries) {
+    async importEntries(sessionId, owner, entries, options) {
         void owner;
-        const validated = validateEntriesForImport(entries);
+        const validated = validateEntriesForImport(entries, options);
         evictSharedSessionStorage(canonicalStoreKey(this.pathFor(sessionId)));
         const createdAt = new Date().toISOString();
         const lines = [JSON.stringify({ kind: "meta", id: sessionId, createdAt })];

package/dist/stores/file/shared-ledger.js

@@ -88,7 +88,14 @@ export class SharedLedgerTable {
         }
         const core = new LedgerCore(key, paths, this.model, this.live);
         this.live.set(key, core);
-        core.bootstrap();
+        try {
+            core.bootstrap();
+        }
+        catch (e) {
+            if (this.live.get(key) === core)
+                this.live.delete(key);
+            throw e;
+        }
         return core;
     }
 }

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

@@ -21,3 +21,6 @@ export declare function formatOutOfRootReadApprovalOption(directory: string): st
 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;
+export declare const POLL_LOOP_MAX_BEATS = 120;
+export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
+export declare function classifyBoundedReadonlyPollLoop(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;

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

@@ -462,3 +462,97 @@ export function classifySimpleCommandReadBoundary(command, boundary) {
 export function classifyCompoundReadonly(command, allow, boundary) {
     return classifyCompoundReadonlyDetailed(command, allow, boundary).reason;
 }
+export const POLL_LOOP_MAX_BEATS = 120;
+export const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
+const POLL_BODY_HARD_REJECT = /[<>$()`|&{}\n\r\\]/;
+const NON_ASCII_WHITESPACE = /[^\S \t]/;
+const POLL_LOOP_SHAPE = /^for[ \t]+([A-Za-z_][A-Za-z0-9_]*)[ \t]+in[ \t]+(.+?)[ \t]*;[ \t]*do[ \t]+(.+?)[ \t]*;[ \t]*done[ \t]*;?$/;
+function pollLoopQuotesBalanced(s) {
+    let open;
+    for (const ch of s) {
+        if (open === undefined && (ch === '"' || ch === "'"))
+            open = ch;
+        else if (open === ch)
+            open = undefined;
+    }
+    return open === undefined;
+}
+function pollLoopBeatsOf(iterable) {
+    const seq = /^\$\(seq[ \t]+(\d{1,7})[ \t]+(\d{1,7})\)$/.exec(iterable);
+    const brace = seq === null ? /^\{(\d{1,7})\.\.(\d{1,7})\}$/.exec(iterable) : null;
+    const range = seq ?? brace;
+    if (range !== null) {
+        const lo = Number(range[1]);
+        const hi = Number(range[2]);
+        return hi >= lo ? hi - lo + 1 : undefined;
+    }
+    const items = iterable.split(/[ \t]+/);
+    return items.every((t) => /^[A-Za-z0-9_.-]{1,64}$/.test(t)) ? items.length : undefined;
+}
+function pollLoopSleepReason(segment) {
+    const toks = segment.split(/[ \t]+/);
+    if (toks.length !== 2)
+        return "`sleep` in a poll loop must take exactly one literal numeric argument";
+    const v = toks[1];
+    if (!/^\d+(\.\d+)?$/.test(v) || v.length > 8 || Number(v) > POLL_LOOP_MAX_SLEEP_SECONDS) {
+        return `\`sleep ${v}\` is not a literal duration within the ${POLL_LOOP_MAX_SLEEP_SECONDS}s per-beat cap — not auto-allowed`;
+    }
+    return undefined;
+}
+export function classifyBoundedReadonlyPollLoop(command, allow, boundary) {
+    if (NON_ASCII_WHITESPACE.test(command)) {
+        return "the command contains a non-ASCII or control whitespace character (only space and tab are allowed) — its word boundaries cannot be read the way bash would split them, so it is not auto-allowed";
+    }
+    const trimmed = command.trim();
+    if (!trimmed)
+        return "empty command";
+    if (!pollLoopQuotesBalanced(trimmed)) {
+        return "unbalanced quote — the command's structure cannot be read reliably, so it is not auto-allowed";
+    }
+    const m = POLL_LOOP_SHAPE.exec(trimmed);
+    if (m === null) {
+        return "not a bounded read-only poll loop (`for <v> in <literal bound>; do <read commands>; done` is the only accepted control structure)";
+    }
+    const varName = m[1];
+    const iterable = m[2];
+    const body = m[3];
+    if (!/^[a-z]$/.test(varName)) {
+        return `the loop variable "${varName}" must be a single lowercase letter — a name like PATH/IFS/LD_PRELOAD would change how the body's commands resolve`;
+    }
+    const beats = pollLoopBeatsOf(iterable);
+    if (beats === undefined) {
+        return `the loop bound "${iterable}" is not a recognized literal — only \`$(seq <int> <int>)\`, \`{<int>..<int>}\` (ascending) or a literal word list is accepted`;
+    }
+    if (beats > POLL_LOOP_MAX_BEATS) {
+        return `the loop runs ${beats} iterations, above the ${POLL_LOOP_MAX_BEATS}-iteration cap for auto-allow`;
+    }
+    if (POLL_BODY_HARD_REJECT.test(body)) {
+        return "the loop body may not contain redirection, pipes, backgrounding, substitution, subshells, braces, escapes, or line breaks";
+    }
+    const readSegments = [];
+    for (const rawSegment of body.split(";")) {
+        const segment = rawSegment.trim();
+        if (segment.length === 0)
+            return "empty command in the loop body";
+        const parsed = parseLeadingCommandName(segment);
+        if ("reject" in parsed)
+            return parsed.reject;
+        if (parsed.name === "sleep") {
+            const sleepReason = pollLoopSleepReason(segment);
+            if (sleepReason !== undefined)
+                return sleepReason;
+            continue;
+        }
+        readSegments.push(segment);
+    }
+    if (readSegments.length === 0) {
+        return "the loop body has no read command — a sleep-only loop observes nothing and is not auto-allowed";
+    }
+    const verdict = classifyCompoundReadonlyDetailed(readSegments.join("; "), allow, boundary);
+    if (verdict.reason !== undefined)
+        return verdict.reason;
+    if (verdict.undecidedPaths !== undefined) {
+        return `the loop body carries an unexpanded glob (${verdict.undecidedPaths.join(", ")}) — what a REPEATED read touches is decided at run time, so it is not auto-allowed`;
+    }
+    return undefined;
+}

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

@@ -7,10 +7,10 @@ import { hasBackgroundShell } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
 import { imageMagicMatches, withinAnyRoot } from "./safety.js";
-import { isRemoteExecutionEnv } from "../../core/remote-env.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, } from "./fs-shared.js";
-import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyCompoundReadonly, classifySimpleCommandReadBoundary, } from "./bash-readonly-classifier.js";
+import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonly, classifySimpleCommandReadBoundary, } from "./bash-readonly-classifier.js";
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
     return (args) => {
@@ -18,7 +18,9 @@ export function bashReversibilityProbe(allow, boundary) {
         if (typeof command !== "string")
             return { reversible: false };
         const resolved = typeof boundary === "function" ? boundary() : boundary;
-        return { reversible: classifyCompoundReadonly(command, allowSet, resolved) === undefined };
+        if (classifyCompoundReadonly(command, allowSet, resolved) === undefined)
+            return { reversible: true };
+        return { reversible: classifyBoundedReadonlyPollLoop(command, allowSet, resolved) === undefined };
     };
 }
 const EXIT1_INTERPRETATION = {
@@ -399,7 +401,22 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
         },
     };
 }
-function bashDescription(coAuthor, caps, bgNotifies = false, bgRetained = false) {
+function bgReapClause(sessionScoped, envIsolatedOwned) {
+    if (!sessionScoped)
+        return "when this task ends";
+    return envIsolatedOwned
+        ? "at session end, not when this task ends — UNLESS this task's own isolated sandbox is torn down, which reaps it right then instead"
+        : "at session end, not when this task ends: it keeps running across tasks in the same session, and a later task can still read its output or stop it";
+}
+function bgNohupCaveat(envIsolatedOwned) {
+    return envIsolatedOwned
+        ? " — on a per-task isolated sandbox this only helps if the sandbox itself survives; if the deployment tears it down at task end, host the deliverable outside the sandbox instead"
+        : "";
+}
+function bgRetainedIsolatedNote() {
+    return " This environment declares retention for background processes — normally one keeps running past this task and the session. The one exception: a per-task isolated sandbox that gets torn down still reaps it right then despite the retention declaration; if the deliverable must survive that too, host it outside the sandbox instead.";
+}
+function bashDescription(coAuthor, caps, bgNotifies = false, bgRetained = false, bgSessionScoped = false, bgEnvIsolatedOwned = false) {
     const coAuthorLines = coAuthor === false
         ? "- Follow the deployment's commit-message conventions."
         : `- End git commit messages with:\nCo-Authored-By: ${coAuthor}`;
@@ -409,7 +426,7 @@ function bashDescription(coAuthor, caps, bgNotifies = false, bgRetained = false)
 - IMPORTANT: Avoid using this tool to run \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.
 - File search by name: use the Glob tool (NOT \`find\` or \`ls\`); content search: use the Grep tool (NOT \`grep\`/\`rg\` in the shell).
 - \`timeout\` is in milliseconds: default ${caps.defaultMs}, max ${caps.maxMs}.
-- \`run_in_background\` runs the command detached: it keeps running across turns and ${bgNotifies ? "re-invokes you when it exits" : "you read its output later with TaskOutput(task_id)"}. No \`&\` needed.${bgRetained ? "" : " Background processes do NOT survive the session — they are reaped when the task ends. A deliverable that must stay alive afterwards (a server, a daemon) needs a self-detaching FOREGROUND start instead: run `nohup cmd >log 2>&1 &` as a normal foreground command (portable; setsid does not exist on macOS), or use a service manager."}
+- \`run_in_background\` runs the command detached: it keeps running across turns and ${bgNotifies ? "re-invokes you when it exits" : "you read its output later with TaskOutput(task_id)"}. No \`&\` needed.${bgRetained ? (bgEnvIsolatedOwned ? bgRetainedIsolatedNote() : "") : ` Background processes do NOT survive the session — they are reaped ${bgReapClause(bgSessionScoped, bgEnvIsolatedOwned)}. A deliverable that must stay alive afterwards (a server, a daemon) needs a self-detaching FOREGROUND start instead: run \`nohup cmd >log 2>&1 &\` as a normal foreground command (portable; setsid does not exist on macOS), or use a service manager${bgNohupCaveat(bgEnvIsolatedOwned)}.`}
 
 # Git
 - Interactive flags (\`-i\`, e.g. \`git rebase -i\`, \`git add -i\`) are not supported in this environment.
@@ -463,20 +480,22 @@ async function adoptBackgroundShell(req) {
         return { ok: false, reason, killed: false, killMsg: kill !== undefined && !kill.ok ? kill.error.message : "killBackground threw" };
     }
 }
-function backgroundLifetimeNote(caps) {
-    return caps.retainBackgroundProcesses === true
-        ? ""
-        : ` NOTE: background processes do NOT survive the session (reaped at task end). If this is a deliverable service that must stay alive afterwards, host it with a FOREGROUND command instead: \`nohup cmd >log 2>&1 &\` (self-detaching — survives the session).`;
+function backgroundLifetimeNote(caps, sessionScoped, envIsolatedOwned) {
+    if (caps.retainBackgroundProcesses === true)
+        return envIsolatedOwned ? bgRetainedIsolatedNote() : "";
+    return ` NOTE: background processes do NOT survive the session (reaped ${bgReapClause(sessionScoped, envIsolatedOwned)}). If this is a deliverable service that must stay alive afterwards, host it with a FOREGROUND command instead: \`nohup cmd >log 2>&1 &\` (self-detaching — survives the session)${bgNohupCaveat(envIsolatedOwned)}.`;
 }
 export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = { current: rootCanonical }, taskOpts = {}) {
     const timeoutCaps = resolveBashTimeoutCaps(taskOpts);
     const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
     const bgNotifies = taskOpts.taskRegistry !== undefined && taskOpts.onTaskNotification !== undefined;
     const bgRetained = hasBackgroundShell(env) && env.backgroundCapabilities.retainBackgroundProcesses === true;
+    const bgSessionScoped = taskOpts.sessionId !== undefined && taskOpts.taskRegistry !== undefined;
+    const bgEnvIsolatedOwned = hasDestroy(env) && isIsolated(env);
     return defineTool({
         name: "Bash",
         contract: { contractId: "core.bash@1", implementationRevision: "1" },
-        description: bashDescription(coAuthor, timeoutCaps, bgNotifies, bgRetained),
+        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)` })),
@@ -535,7 +554,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                         ? ` Time budget: requested ${requestedTimeoutSec}s, capped at ${bgCaps.maxBgTimeoutSec}s (env ceiling: requests above ${bgCaps.maxBgTimeoutSec}s are reduced to it) — auto-terminates if still running after ${appliedTimeoutSec}s.`
                         : ` Time budget: auto-terminates if still running after ${appliedTimeoutSec}s (hard cap ${bgCaps.maxBgTimeoutSec}s).`
                     : "";
-                const lifetimeNote = backgroundLifetimeNote(bgCaps);
+                const lifetimeNote = backgroundLifetimeNote(bgCaps, bgSessionScoped, bgEnvIsolatedOwned);
                 const registry = taskOpts.taskRegistry;
                 if (registry !== undefined) {
                     const onNotify = taskOpts.onTaskNotification;
@@ -649,7 +668,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                                         ? `You will be notified when it completes — do not poll.`
                                         : `Poll TaskOutput until its status is no longer "running".`) +
                                 adoptBudgetNote +
-                                backgroundLifetimeNote(adoptCaps) +
+                                backgroundLifetimeNote(adoptCaps, bgSessionScoped, bgEnvIsolatedOwned) +
                                 (tail ? `\n--- output so far (tail) ---\n${tail}` : ""),
                             details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}), ...(outputFile !== undefined ? { output_file: outputFile } : {}), ...(cause === "timeout" ? { autoBackgrounded: true } : {}) },
                         };

package/dist/tools/fs/safety.js

@@ -309,15 +309,29 @@ export async function canonicalizeTarget(env, path, signal, baseCwd) {
     let abs = absR.value;
     for (let hop = 0; hop < 16; hop++) {
         const exists = await env.exists(abs, signal);
-        if (!(exists.ok && exists.value)) {
-            return { ok: true, key: await canonicalizeNewPath(env, abs, signal) };
+        if (!exists.ok) {
+            return { ok: false, message: `cannot determine whether "${path}" exists: ${exists.error.message}`, unresolvedSymlink: true };
+        }
+        if (!exists.value) {
+            const newPath = await canonicalizeNewPath(env, abs, signal);
+            if (!newPath.ok) {
+                return { ok: false, message: newPath.message, unresolvedSymlink: true };
+            }
+            return { ok: true, key: newPath.key };
         }
         const canon = await env.canonicalPath(abs, signal);
         if (canon.ok)
             return { ok: true, key: canon.value };
         const info = await env.fileInfo(abs, signal);
-        if (!(info.ok && info.value.kind === "symlink")) {
-            return { ok: true, key: abs };
+        if (!info.ok) {
+            return { ok: false, message: `cannot determine whether "${path}" is a symlink: ${info.error.message}`, unresolvedSymlink: true };
+        }
+        if (info.value.kind !== "symlink") {
+            const viaAncestors = await canonicalizeNewPath(env, abs, signal, { skipLeaf: true });
+            if (!viaAncestors.ok) {
+                return { ok: false, message: viaAncestors.message, unresolvedSymlink: true };
+            }
+            return { ok: true, key: viaAncestors.key };
         }
         if (!env.readLink) {
             return { ok: false, message: `cannot resolve symlink "${path}" (env has no readLink)`, unresolvedSymlink: true };
@@ -328,7 +342,10 @@ export async function canonicalizeTarget(env, path, signal, baseCwd) {
         }
         const linkTarget = isAbsolutePathForm(link.value) ? link.value : `${parentDir(abs)}${nativeSepOf(abs)}${link.value}`;
         const reabs = await env.absolutePath(linkTarget, signal);
-        abs = reabs.ok ? reabs.value : linkTarget;
+        if (!reabs.ok) {
+            return { ok: false, message: `cannot resolve symlink target "${linkTarget}" for "${path}": ${reabs.error.message}`, unresolvedSymlink: true };
+        }
+        abs = reabs.value;
     }
     return { ok: false, message: `symlink chain for "${path}" exceeded the hop cap; target unresolved`, unresolvedSymlink: true };
 }
@@ -339,21 +356,28 @@ function parentDir(abs) {
     const head = abs.slice(0, i);
     return /^[A-Za-z]:$/.test(head) ? head + abs[i] : head;
 }
-async function canonicalizeNewPath(env, abs, signal) {
+async function canonicalizeNewPath(env, abs, signal, opts) {
     const sep = nativeSepOf(abs);
     const parts = isWinFormPath(abs) ? abs.split(/[\\/]/) : abs.split("/");
     const tail = [];
+    if (opts?.skipLeaf === true && parts.length > 1)
+        tail.push(parts.pop());
     while (parts.length > 1) {
         const candidate = parts.join(sep) || sep;
         const ex = await env.exists(candidate, signal);
-        if (ex.ok && ex.value) {
+        if (!ex.ok) {
+            return { ok: false, message: `cannot determine whether ancestor "${candidate}" exists: ${ex.error.message}` };
+        }
+        if (ex.value) {
             const canon = await env.canonicalPath(candidate, signal);
-            const baseCanon = canon.ok ? canon.value : candidate;
-            return [baseCanon, ...tail.reverse()].join(nativeSepOf(baseCanon));
+            if (!canon.ok) {
+                return { ok: false, message: `cannot canonicalize existing ancestor "${candidate}": ${canon.error.message}` };
+            }
+            return { ok: true, key: [canon.value, ...tail.reverse()].join(nativeSepOf(canon.value)) };
         }
         tail.push(parts.pop());
     }
-    return abs;
+    return { ok: true, key: abs };
 }
 export function violationText(toolName, v) {
     return `Error (${toolName}): ${v.message}`;

package/package.json

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