@sema-agent/core 7.31.1 → 7.32.1

package/dist/tools/fs/repo-map.d.ts

@@ -1,5 +1,6 @@
 import type { AgentTool } from "../../internal/harness-types.js";
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+import { type RootsSeat } from "./safety.js";
 import type { ReadDenyMatcher } from "./read-deny.js";
 import type { ContainmentFace } from "./containment-face.js";
 /** Extract top-level symbol names (deduped, in first-seen order) from source text. A lightweight
@@ -13,4 +14,4 @@ import type { ContainmentFace } from "./containment-face.js";
  *  (src/core/auto-promote.ts) consumes it in ESCALATE-ONLY mode — a clean scan contributes nothing;
  *  it can only ever raise an escalation, never clear one. */
 export declare function extractSymbols(text: string): string[];
-export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ContainmentFace): AgentTool;
+export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: RootsSeat, readDeny?: ReadDenyMatcher, readFace?: ContainmentFace): AgentTool;

package/dist/tools/fs/safety.d.ts

@@ -434,6 +434,8 @@ export declare function joinForFamily(family: PathFamily, base: string, rel: str
  *  view's "does the TARGET" — a symlink AT a guarded spelling resolves away from it canonically,
  *  and only this view still names it. */
 export declare function lexicalViewOf(spelled: string, base: string): string;
+/** A face's extra containment roots: a fixed list, or a getter over a run's live set (read once per resolution). */
+export type RootsSeat = readonly string[] | (() => readonly string[] | undefined);
 /**
  * Resolve a model-supplied path to a canonical key AND enforce rootPath containment. Existing paths
  * use `canonicalPath` (resolves symlinks, so the same file cannot get two keys). New paths
@@ -441,7 +443,7 @@ export declare function lexicalViewOf(spelled: string, base: string): string;
  * therefore cannot land the target outside root. Returns the canonical key, or a `path_not_in_root`
  * violation. Defense-in-depth at the tool layer; NOT a substitute for a sandboxed `executionEnv`.
  */
-export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean, readDeny?: {
+export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRoots?: RootsSeat, exactFileReadExemption?: (canonicalKey: string) => boolean, readDeny?: {
     matchTarget(canonicalKey: string, lexicalView?: string, opts?: {
         readonly aliasResolved?: boolean;
     }): {

package/dist/tools/fs/safety.js

@@ -448,11 +448,12 @@ function within(rootCanonical, p) {
         return true;
     return pN.identity.startsWith(rootN.identity.endsWith(SEP) ? rootN.identity : rootN.identity + SEP);
 }
-export async function resolveKey(env, rootCanonical, path, signal, baseCwd, additionalRootsCanonical, exactFileReadExemption, readDeny, containmentFace) {
+export async function resolveKey(env, rootCanonical, path, signal, baseCwd, additionalRoots, exactFileReadExemption, readDeny, containmentFace) {
     const canon = await canonicalizeTarget(env, path, signal, pathFamilyOf({ root: rootCanonical }), baseCwd);
     if (!canon.ok)
         return { ok: false, violation: { code: "invalid", message: canon.message } };
     const key = canon.key;
+    const additionalRootsCanonical = typeof additionalRoots === "function" ? additionalRoots() : additionalRoots;
     if (isBlockedDevicePath(key)) {
         return { ok: false, violation: { code: "invalid", message: `path "${path}" is a blocked device/special file (reading it can hang the process); refused.` } };
     }

package/dist/tools/fs/shell-read-check.d.ts

@@ -89,6 +89,9 @@ export interface ShellReadStationOptions {
     readonly boundaryOf: (toolName: string, cwd: string | undefined) => ShellReadBoundary | undefined;
     /** The listed read verbs (decides whether a segment is read by verb slots or word by word). */
     readonly readers?: ReadonlySet<string>;
+    /** `true` ⇔ every root `boundaryOf` returns is already a canonical identity (the Runner's): the station never
+     *  re-resolves one, so a root swapped for a link after it was declared or granted cannot bring in the link's target. */
+    readonly rootsCanonical?: boolean;
 }
 /** What a consumer hands {@link judgeShellRead}: the command as written, the environment whose filesystem
  *  answers where its words land (symlinks resolved, patterns expanded — a `NodeExecutionEnv` over a real

package/dist/tools/fs/shell-read-check.js

@@ -170,7 +170,7 @@ export function createShellReadStation(opts) {
         const key = roots.join("\0");
         let e = establishers.get(key);
         if (e === undefined) {
-            e = createShellReadEstablisher(opts.env, roots);
+            e = createShellReadEstablisher(opts.env, roots, { rootsCanonical: opts.rootsCanonical === true });
             establishers.set(key, e);
         }
         return e;

package/dist/tools/fs/shell-read-establish.d.ts

@@ -79,4 +79,6 @@ export declare function establishShellReadsLexically(plan: ShellReadPlan, bounda
  * as declared (canonical by contract); they are resolved once more per instance because the comparison is
  * against `realpath` output on both sides — an aliased root would otherwise refuse every read under itself.
  */
-export declare function createShellReadEstablisher(env: ExecutionEnv, readRoots: readonly string[]): ShellReadEstablisher;
+export declare function createShellReadEstablisher(env: ExecutionEnv, readRoots: readonly string[], opts?: {
+    readonly rootsCanonical?: boolean;
+}): ShellReadEstablisher;

package/dist/tools/fs/shell-read-establish.js

@@ -145,14 +145,14 @@ export function establishShellReadsLexically(plan, boundary) {
     }
     return { plan, reads, nested, roots: boundary.roots };
 }
-export function createShellReadEstablisher(env, readRoots) {
+export function createShellReadEstablisher(env, readRoots, opts) {
     const lexicalOnly = boundaryIsTheSandbox(env);
     const resolverIsAuthoritative = canonicalPathIsAuthoritative(env);
     const family = pathFamilyOf({ root: readRoots[0] ?? "/" });
     const SEP = family === "posix" ? /\// : /[\\/]/;
     const TRAILING_SEP = family === "posix" ? /\/+$/ : /[\\/]+$/;
     const joinUnder = (dir, name) => `${dir.replace(TRAILING_SEP, "")}/${name}`;
-    let rootsOnce;
+    let rootsOnce = opts?.rootsCanonical === true ? Promise.resolve(readRoots) : undefined;
     const canonicalRoots = async (signal) => {
         rootsOnce ??= (async () => {
             const out = [];

package/dist/tools/monitor.d.ts

@@ -73,10 +73,11 @@ export interface MonitorToolOptions {
      *  spawns a shell command too, so what it runs is what the station judged, re-established before the watch
      *  spawns. Absent ⇒ no station judged this mount; nothing is re-established. */
     shellReadAdmission?: ShellReadAdmission;
-    /** RB-465-b (HRD-PTL-3 残件): spec-level retain (`TaskSpec.retainBackgroundProcesses`) — the SECOND
-     *  retain lane, OR-composed with the env capability at the teardown sweep. Without this bit the mount
-     *  could only see the env lane, so a deployment retaining per spec still got the "session ends it"
-     *  wording in the persistent-watch receipt. Purely a RECEIPT input — enforcement stays at the sweep. */
+    /** RB-465-b (HRD-PTL-3 残件): spec-level retain (`TaskSpec.retainBackgroundProcesses`) — the task lane of
+     *  THE retain predicate (`retainsBackgroundProcesses`), OR-composed with the env capability. Read twice,
+     *  by the same predicate: the persistent-watch receipt's wording, and the row's `retained` mark at
+     *  registration (so the session reap and the exit-boundary hard face judge the row the way the receipt
+     *  described it). */
     retainBackgroundProcesses?: boolean;
     /** The task root in the SAME canonical spelling `createBashTool` is built with, so a dead-cwd self-heal
      *  lands both tools on one directory. Absent ⇒ the diagnosis says it has no reset target, rather than

package/dist/tools/monitor.js

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../core/tools.js";
-import { hasBackgroundShell } from "../core/background-shell.js";
+import { envDeclaresRetain, hasBackgroundShell, retainsBackgroundProcesses } from "../core/background-shell.js";
 import { MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, } from "../core/task-registry.js";
 import { toolFace } from "../core/tool-catalog-entries.js";
 import { isDeadCwd, diagnoseDeadCwd } from "./fs/dead-cwd.js";
@@ -101,6 +101,7 @@ export function createMonitorTool(env, opts) {
                     persistent: isPersistent,
                     ...(sessionScoped ? { sessionScoped: true } : {}),
                     ...(isPersistent ? {} : { timeoutMs }),
+                    ...(opts.retainBackgroundProcesses !== undefined ? { retainBackgroundProcesses: opts.retainBackgroundProcesses } : {}),
                     ...(onNotify !== undefined ? { onEvent: (n) => onNotify(n, { priority: "next" }) } : {}),
                     ...(opts.timers !== undefined ? { timers: opts.timers } : {}),
                     ...(opts.batchWindowMs !== undefined ? { batchWindowMs: opts.batchWindowMs } : {}),
@@ -135,12 +136,12 @@ export function createMonitorTool(env, opts) {
             const persistentBudget = bgTimeout !== undefined
                 ? `the execution environment's background time budget ends the watch after ${bgTimeout}s`
                 : `the execution environment's background time budget still applies`;
-            const retainedByEnv = env.backgroundCapabilities.retainBackgroundProcesses === true;
+            const retainedByEnv = envDeclaresRetain(env);
             const retainedBySpec = opts.retainBackgroundProcesses === true;
-            const retained = retainedByEnv || retainedBySpec;
+            const retained = retainsBackgroundProcesses({ env: retainedByEnv, task: retainedBySpec });
             const persistentAnchor = sessionScoped
                 ? retained
-                    ? ". This run retains background processes (environment capability or task spec), so at the run teardown the watch is marked retained and " +
+                    ? ". This run retains background processes (environment capability or task spec), so the watch is retained and " +
                         "survives the session's release: only your TaskStop, the command's own exit, or that budget end it."
                     : "; it runs until then, until you stop it, or until the session ends."
                 : retained

package/dist/tools/todo.d.ts

@@ -2,9 +2,9 @@ import type { ToolSpec } from "../core/types.js";
 /**
  * design/102 (K-8 CC full-body) — TodoWrite parity (CONTEXT leg). A private, in-task plan the model rewrites to
  * track multi-step work. State lives in this factory's closure — FRESH per task (each `assembleCodeTools` call
- * makes its own) and torn down with the task; nothing durable, no deps, no egress. `effect:"idempotent"` because
+ * makes its own), one list per calling session (`ctx.sessionId`; upstream keys it by agent, so an Agent child sharing
+ * the instance never replaces the leader's plan); nothing durable, no deps, no egress. `effect:"idempotent"` because
  * re-sending the whole list is repeat-safe. Distinct from `present_plan` (that SUSPENDS for human review); this is
- * the model's own scratch. Returns a RAW {@link ToolSpec} pushed via `spec.tools` (prepare-task defines it) — NOT
- * mounted default-on, so it stays INERT for non-full-body runs. (A later slice may project the list to the wire.)
+ * the model's own scratch, a RAW {@link ToolSpec} pushed via `spec.tools` — NOT mounted default-on (INERT elsewhere).
  */
 export declare function createTodoWriteTool(): ToolSpec;

package/dist/tools/todo.js

@@ -2,7 +2,7 @@ import { Type } from "typebox";
 import { errorResult } from "../core/tools.js";
 import { toolFace } from "../core/tool-catalog-entries.js";
 export function createTodoWriteTool() {
-    let todos = [];
+    const lists = new Map();
     return {
         name: "TodoWrite",
         ...toolFace("todo-write"),
@@ -81,9 +81,10 @@ export function createTodoWriteTool() {
                 activeForm: Type.String({ minLength: 1, description: "Present-continuous form shown while in progress (e.g. \"Running the tests\")." }),
             })),
         }),
-        execute: (args) => {
+        execute: (args, ctx) => {
+            const key = ctx?.sessionId ?? "";
             const shape = (t) => ({ content: t.content, status: t.status, activeForm: t.activeForm });
-            const oldTodos = todos.map(shape);
+            const oldTodos = (lists.get(key) ?? []).map(shape);
             const written = args.todos;
             for (let i = 0; i < written.length; i++) {
                 const activeForm = written[i].activeForm;
@@ -96,7 +97,7 @@ export function createTodoWriteTool() {
                 }
             }
             const allDone = written.every((t) => t.status === "completed");
-            todos = allDone ? [] : written;
+            lists.set(key, allDone ? [] : written);
             const newTodos = written.map(shape);
             const open = written.filter((t) => t.status !== "completed").length;
             return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.31.1",
+  "version": "7.32.1",
   "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": 2478,
+  "count": 2484,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -177,10 +177,12 @@
     "BackgroundAgentStoreError": "class",
     "BackgroundAgentUsage": "interface",
     "BackgroundChildEvent": "interface",
+    "BackgroundHardKillOutcome": "type",
     "BackgroundPoll": "interface",
     "BackgroundShellCapability": "interface",
     "BackgroundShellError": "class",
     "BackgroundShellErrorCode": "type",
+    "BackgroundShellHardKillReceipt": "interface",
     "BackgroundShellId": "type",
     "BackgroundShellStatus": "type",
     "BackgroundSpawnOptions": "type",
@@ -905,6 +907,7 @@
     "PERMISSION_MODE_CLASSES": "variable",
     "PERMISSION_RULE_SYNC_PATH": "variable",
     "PERMISSION_RULE_WRITER": "variable",
+    "PERSISTED_RULE_MANDATES": "variable",
     "PLAN_SYSTEM_PROMPT": "variable",
     "PLAN_WHEN_TO_USE": "variable",
     "PREFIX_INPUT_CLASSIFICATION": "variable",
@@ -1013,6 +1016,7 @@
     "PersistedRuleCoverage": "interface",
     "PersistedRuleHit": "interface",
     "PersistedRuleHitRule": "interface",
+    "PersistedRuleMandate": "type",
     "PersistedRuleMatch": "type",
     "PersistedRuleTool": "type",
     "PersistedRuleUnreadable": "interface",
@@ -1131,6 +1135,7 @@
     "ReadOnlyFlagArity": "type",
     "ReadOnlyShellVerdict": "type",
     "ReadRootGrantCandidate": "interface",
+    "ReadRootGrantScreen": "type",
     "RealApprovalGateBit": "interface",
     "ReasoningFormat": "type",
     "ReasoningIntensity": "type",
@@ -2056,6 +2061,7 @@
     "isPeerSessionId": "function",
     "isPeerSessionProcessAlive": "function",
     "isPermissionModeClass": "function",
+    "isPersistedRuleMandate": "function",
     "isPersonalScope": "function",
     "isProcessLive": "function",
     "isProtectedWrite": "function",
@@ -2657,10 +2663,12 @@
     "BackgroundAgentStoreError": "advanced",
     "BackgroundAgentUsage": "advanced",
     "BackgroundChildEvent": "advanced",
+    "BackgroundHardKillOutcome": "advanced",
     "BackgroundPoll": "advanced",
     "BackgroundShellCapability": "advanced",
     "BackgroundShellError": "advanced",
     "BackgroundShellErrorCode": "advanced",
+    "BackgroundShellHardKillReceipt": "advanced",
     "BackgroundShellId": "advanced",
     "BackgroundShellStatus": "advanced",
     "BackgroundSpawnOptions": "advanced",
@@ -3385,6 +3393,7 @@
     "PERMISSION_MODE_CLASSES": "advanced",
     "PERMISSION_RULE_SYNC_PATH": "advanced",
     "PERMISSION_RULE_WRITER": "advanced",
+    "PERSISTED_RULE_MANDATES": "advanced",
     "PLAN_SYSTEM_PROMPT": "advanced",
     "PLAN_WHEN_TO_USE": "advanced",
     "PREFIX_INPUT_CLASSIFICATION": "advanced",
@@ -3493,6 +3502,7 @@
     "PersistedRuleCoverage": "advanced",
     "PersistedRuleHit": "advanced",
     "PersistedRuleHitRule": "advanced",
+    "PersistedRuleMandate": "advanced",
     "PersistedRuleMatch": "advanced",
     "PersistedRuleTool": "advanced",
     "PersistedRuleUnreadable": "advanced",
@@ -3611,6 +3621,7 @@
     "ReadOnlyFlagArity": "advanced",
     "ReadOnlyShellVerdict": "advanced",
     "ReadRootGrantCandidate": "advanced",
+    "ReadRootGrantScreen": "advanced",
     "RealApprovalGateBit": "advanced",
     "ReasoningFormat": "advanced",
     "ReasoningIntensity": "advanced",
@@ -4536,6 +4547,7 @@
     "isPeerSessionId": "advanced",
     "isPeerSessionProcessAlive": "advanced",
     "isPermissionModeClass": "advanced",
+    "isPersistedRuleMandate": "advanced",
     "isPersonalScope": "advanced",
     "isProcessLive": "advanced",
     "isProtectedWrite": "advanced",