@sema-agent/core 7.21.1 → 7.22.0

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

@@ -26,11 +26,7 @@ function operandFamily(paths) {
 }
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? bashClassifyDefaultAllow());
-    return (args) => {
-        const command = shellCommandOf(args);
-        if (command === undefined)
-            return { reversible: false };
-        const resolved = typeof boundary === "function" ? boundary() : boundary;
+    const judge = (args, command, resolved, offers) => {
         const boundaryGate = (verdict) => readBoundaryMandate(command, allowSet, resolved, verdict);
         const outOfRootGate = () => readBoundaryMandate(command, allowSet, resolved, {});
         const backgrounded = isBackgroundShellCall(args);
@@ -49,9 +45,20 @@ export function bashReversibilityProbe(allow, boundary) {
         const loop = classifyBoundedReadonlyPollLoopDetailed(command, allowSet, resolved);
         if (loop.reason === undefined)
             return { reversible: true };
+        const seatOffer = (verdict) => (offers ? readRootCandidateOf(verdict) : {});
         if (boundaryDeclared(loop) || unjudgedRead(command, allowSet, resolved, loop))
-            return { reversible: false, mandated: true, ...readRootCandidateOf(loop) };
-        return { reversible: false, ...boundaryGate(detailed), ...readRootCandidateOf(detailed) };
+            return { reversible: false, mandated: true, ...seatOffer(loop) };
+        const refusedCause = recursiveReadCause(detailed);
+        return { reversible: false, ...boundaryGate(detailed), ...seatOffer(detailed), ...(refusedCause !== undefined ? { cause: refusedCause } : {}) };
+    };
+    return (args) => {
+        const command = shellCommandOf(args);
+        if (command === undefined)
+            return { reversible: false };
+        const resolved = typeof boundary === "function" ? boundary() : boundary;
+        if (resolved === undefined)
+            return judge(args, command, undefined, true);
+        return grantClearsSeat((c, b, o) => judge(args, c, b, o), command, resolved);
     };
 }
 function boundaryUnread(verdict) {
@@ -59,7 +66,9 @@ function boundaryUnread(verdict) {
 }
 function readRootCandidateOf(verdict) {
     const dir = verdict.outOfRootGrantCandidate;
-    return dir !== undefined ? { readRootCandidate: { dir, clearsThisAsk: true } } : {};
+    if (dir === undefined)
+        return {};
+    return { readRootCandidate: { dir, clearsThisAsk: true, ...(verdict.outOfRootGrantCoversExactPath === true ? { covers: "exact" } : {}) } };
 }
 function boundaryUndecided(verdict) {
     return verdict.undecidedPaths !== undefined && verdict.undecidedPaths.length > 0;
@@ -110,20 +119,16 @@ function recursiveReadCause(detailed) {
 }
 export function bashReadBoundaryProbe(boundary) {
     const allowSet = new Set(bashClassifyDefaultAllow());
-    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 judge = (command, resolved, offers) => {
         const seatVerdict = (verdict) => {
             if (boundaryDeclared(verdict) || unjudgedRead(command, allowSet, resolved, verdict)) {
                 const cause = recursiveReadCause(verdict);
                 return { reversible: false, mandated: true, ...(cause !== undefined ? { cause } : {}) };
             }
-            if (boundaryUndecided(verdict))
-                return { reversible: false };
+            if (boundaryUndecided(verdict)) {
+                const cause = recursiveReadCause(verdict);
+                return { reversible: false, ...(cause !== undefined ? { cause } : {}) };
+            }
             if (verdict.reason === undefined)
                 return { reversible: true };
             return undefined;
@@ -137,12 +142,32 @@ export function bashReadBoundaryProbe(boundary) {
         const compoundVerdict = seatVerdict(detailed);
         const loopVerdict = seatVerdict(loop);
         const mandated = [compoundVerdict, loopVerdict].find((verdict) => verdict?.mandated === true);
+        const offerFrom = (verdict) => (offers ? readRootCandidateOf(verdict) : {});
         if (mandated !== undefined)
-            return { ...mandated, ...readRootCandidateOf(detailed), ...readRootCandidateOf(loop) };
+            return { ...mandated, ...offerFrom(detailed), ...offerFrom(loop) };
         if (readBoundaryMandate(command, allowSet, resolved, detailed).mandated === true)
             return { reversible: false, mandated: true };
         return compoundVerdict ?? loopVerdict ?? { reversible: true };
     };
+    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 };
+        return grantClearsSeat(judge, command, resolved);
+    };
+}
+function grantClearsSeat(judge, command, resolved) {
+    const verdict = judge(command, resolved, true);
+    const dir = verdict.readRootCandidate?.dir;
+    if (dir === undefined)
+        return verdict;
+    if (judge(command, { ...resolved, roots: [...resolved.roots, dir] }, false).reversible)
+        return verdict;
+    const { readRootCandidate: _withdrawn, ...withoutOffer } = verdict;
+    return withoutOffer;
 }
 export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
 const EXIT1_INTERPRETATION = {

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

@@ -160,9 +160,11 @@ export interface HandsToolkitOptions {
      *  time. The write faces are untouched (their guard is createSensitivePathPolicy). */
     readDenyPatterns?: readonly ReadDenyEntry[];
     /** The deployment's built-in-table TIER selection ({@link import("./read-deny.js").ReadDenyBuiltinConfig}
-     *  `tiers` key): EXACTLY the listed tiers of {@link import("./read-deny.js").READ_FACE_BUILTIN_DENY_TABLE}
+     *  `tiers` key) — the ON/OFF switch for the built-in table, OFF unless this seat says otherwise:
+     *  EXACTLY the listed tiers of {@link import("./read-deny.js").READ_FACE_BUILTIN_DENY_TABLE}
      *  are active (`[]` = none — explicit and legal); absent = the default selection
-     *  ({@link import("./read-deny.js").READ_DENY_DEFAULT_TIERS} — every tier except `shell-history`).
+     *  ({@link import("./read-deny.js").READ_DENY_DEFAULT_TIERS}), which is EMPTY — an unconfigured
+     *  mount activates no built-in row.
      *  Composes with {@link readDenyBuiltinExclude} (tier selection first, then row removal) and never
      *  touches the additions seats. Unknown tier names throw at wiring time. Deployment seat ONLY —
      *  deliberately not a TaskSpec key, so no task can widen below its deployment. */

package/dist/tools/fs/read-deny.d.ts

@@ -82,8 +82,9 @@ export interface ReadDenyBuiltinRow {
 /**
  * READ_FACE_BUILTIN_DENY_TABLE — the FULL built-in table with tier metadata: the material basis of
  * the deployment admin face, what an org administrator "sees" before selecting tiers / excluding
- * rows. Activation is a separate fact: the default face is the table under
- * {@link READ_DENY_DEFAULT_TIERS} (shell-history rows exist here but are OFF by default).
+ * rows. Activation is a SEPARATE fact and is OFF by default: every row here is inert until a
+ * deployment names its tier ({@link READ_DENY_DEFAULT_TIERS} is empty), so this is the MENU, never
+ * the active set. Rows stay curated regardless — the menu has to be worth switching on.
  * The dotenv family is deliberately NOT here — workspace `.env` files are working material for the
  * tasks this engine runs; an `outside_workspace` tier is likewise deliberately absent.
  *
@@ -115,11 +116,12 @@ export interface ReadDenyBuiltinRow {
  */
 export declare const READ_FACE_BUILTIN_DENY_TABLE: readonly ReadDenyBuiltinRow[];
 /**
- * The DEFAULT tier selection: every tier EXCEPT `shell-history` — history files are
- * unrestricted unless a deployment opts the tier in. Derived, not re-listed: a tier added to the
- * closed set is default-ON unless this expression is deliberately revisited (`agent-config` joined
- * default-ON this way: an unconfigured deployment refuses the agent's own key-bearing settings files;
- * a deployment that debugs agent configuration selects `tiers` without it).
+ * The DEFAULT tier selection: EMPTY — an unconfigured deployment activates NO built-in row, so the
+ * table above judges nothing until a deployment selects tiers. Activation is a deployment decision
+ * with a visible seat, and the leg's wiring manifest reports which tiers it got.
+ *
+ * Still the NAMED default rather than nothing: `[]` and absence stay separately spellable on the
+ * seat, and a deployment profile wanting a different default changes THIS expression, not call sites.
  */
 export declare const READ_DENY_DEFAULT_TIERS: readonly ReadDenyBuiltinTier[];
 /**
@@ -127,7 +129,8 @@ export declare const READ_DENY_DEFAULT_TIERS: readonly ReadDenyBuiltinTier[];
  * HandsToolkitOptions; deliberately NOT a TaskSpec key and NOT in the governed workflow whitelist,
  * so no task or governed script can widen below its deployment).
  *  - `tiers` — EXACTLY-these tier selection: listed tiers are active, unlisted ones are not
- *    (`[]` = no built-in tiers at all — an explicit, legal posture; absent = {@link READ_DENY_DEFAULT_TIERS}).
+ *    (`[]` = no built-in tiers at all — an explicit, legal posture; absent = {@link READ_DENY_DEFAULT_TIERS},
+ *    which is itself empty, so absent and `[]` resolve alike today and stay separately spellable).
  *  - `exclude` — per-row removal by canonical pattern name, applied AFTER tier selection.
  * Unknown tier names / unknown row names refuse loudly — never silently ignored.
  */
@@ -142,11 +145,22 @@ export interface ReadDenyBuiltinConfig {
  * table under a candidate configuration with the engine's own rules.
  */
 export declare function resolveReadDenyBuiltins(config?: ReadDenyBuiltinConfig): readonly ReadDenyBuiltinRow[];
+/**
+ * The tiers a deployment configuration ACTIVATES — the tier names of {@link resolveReadDenyBuiltins}'s
+ * surviving rows, in {@link READ_DENY_BUILTIN_TIERS} order (the closed set is the ordering source, so
+ * two deployments that select the same tiers in different spellings report the same list).
+ *
+ * MATERIAL, not intentional: a tier whose every row was removed by `exclude` activates nothing and
+ * is NOT reported. An EMPTY result means the built-in table contributes nothing on this leg — the
+ * unconfigured default. Same loud validation as the resolution it wraps.
+ */
+export declare function activeReadDenyBuiltinTiers(config?: ReadDenyBuiltinConfig): readonly ReadDenyBuiltinTier[];
 /**
  * READ_FACE_DEFAULT_DENY_ENTRIES — the DEFAULT-ACTIVE built-in set: {@link READ_FACE_BUILTIN_DENY_TABLE}
- * under {@link READ_DENY_DEFAULT_TIERS} (shell-history rows are in the table, not in this face). This
- * is the export for consumers rendering "what does an unconfigured deployment refuse"; the
- * tier-annotated table is the admin-face export.
+ * under {@link READ_DENY_DEFAULT_TIERS}. That selection is EMPTY, so this is an EMPTY list — the
+ * honest answer to what it is asked ("what does an unconfigured deployment refuse": nothing, from
+ * this table). Kept, and kept derived, so a consumer rendering that answer keeps reading it; the
+ * tier-annotated table is where a consumer renders "what COULD be switched on".
  */
 export declare const READ_FACE_DEFAULT_DENY_ENTRIES: readonly ReadDenyEntry[];
 /** A compiled segment-run pattern (shared engine — the write guard delegates here too). */

package/dist/tools/fs/read-deny.js

@@ -55,7 +55,7 @@ export const READ_FACE_BUILTIN_DENY_TABLE = [
     { pattern: ".aider.conf.yml", tier: "agent-config" },
     { pattern: ".gemini/settings.json", tier: "agent-config" },
 ];
-export const READ_DENY_DEFAULT_TIERS = READ_DENY_BUILTIN_TIERS.filter((t) => t !== "shell-history");
+export const READ_DENY_DEFAULT_TIERS = [];
 export function resolveReadDenyBuiltins(config) {
     let activeTiers;
     if (config?.tiers === undefined) {
@@ -89,6 +89,10 @@ export function resolveReadDenyBuiltins(config) {
     }
     return READ_FACE_BUILTIN_DENY_TABLE.filter((r) => activeTiers.has(r.tier) && !excluded.has(r.pattern));
 }
+export function activeReadDenyBuiltinTiers(config) {
+    const rows = resolveReadDenyBuiltins(config);
+    return READ_DENY_BUILTIN_TIERS.filter((t) => rows.some((r) => r.tier === t));
+}
 export const READ_FACE_DEFAULT_DENY_ENTRIES = resolveReadDenyBuiltins().map((r) => r.pattern);
 function asciiLower(s) {
     let out = "";

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

@@ -541,12 +541,9 @@ export declare const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this fi
  * and partial-view shapes — leaves no trace the refusal renderer can stat for. It is therefore the
  * renderer's FALLBACK hint (least specific, appended only when no sharper branch fired); appending it
  * beside a sharper one would assert something false, since both of those shapes are files Read handled.
- * Kept byte-identical to the sentence Write rendered inline before it moved here.
  *
  * The deadlock is a property of the READ GATE,
- * not of Write — Edit and NotebookEdit hit the identical dead end and used to render the bare sentence
- * with no way out named. All three now pass this one constant, which is why it is no longer named for
- * the tool that happened to have it first: one sentence, three call sites, nothing to drift apart.
+ * not of Write — Edit and NotebookEdit hit the identical dead end.
  */
 export declare const READ_REFUSED_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.21.1",
+  "version": "7.22.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": 2390,
+  "count": 2394,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -712,6 +712,7 @@
     "McpImageResizer": "type",
     "McpInjectionDropFacts": "interface",
     "McpInjectionDropReason": "type",
+    "McpReconnectResult": "interface",
     "McpRefreshResult": "interface",
     "McpServerSpec": "interface",
     "McpServerStatus": "interface",
@@ -1061,6 +1062,8 @@
     "RENDER_HINT_MAX_LIST": "variable",
     "REPORT_FINDINGS_TOOL_NAME": "variable",
     "RESOURCE_CHECKPOINT_VERSION": "variable",
+    "RETENTION_CASCADE_DOMAINS": "variable",
+    "RETENTION_CASCADE_EXEMPT": "variable",
     "RETIRED_TOOL_NAMES": "variable",
     "RETRYABLE_REMOTE_ERROR_CODES": "variable",
     "ROLE_TIER_DEFAULTS": "variable",
@@ -1659,6 +1662,7 @@
     "atomicWriteFile": "function",
     "attachToolContract": "function",
     "autoModeArmingRecipeOf": "function",
+    "autoRunOnRecommendationEffective": "function",
     "backgroundAgentStoreContract": "function",
     "backgroundAgentStoreScopesContract": "function",
     "bashReadBoundaryProbe": "function",
@@ -3104,6 +3108,7 @@
     "McpImageResizer": "advanced",
     "McpInjectionDropFacts": "advanced",
     "McpInjectionDropReason": "advanced",
+    "McpReconnectResult": "advanced",
     "McpRefreshResult": "advanced",
     "McpServerSpec": "advanced",
     "McpServerStatus": "advanced",
@@ -3453,6 +3458,8 @@
     "RENDER_HINT_MAX_LIST": "advanced",
     "REPORT_FINDINGS_TOOL_NAME": "internal",
     "RESOURCE_CHECKPOINT_VERSION": "advanced",
+    "RETENTION_CASCADE_DOMAINS": "advanced",
+    "RETENTION_CASCADE_EXEMPT": "advanced",
     "RETIRED_TOOL_NAMES": "advanced",
     "RETRYABLE_REMOTE_ERROR_CODES": "advanced",
     "ROLE_TIER_DEFAULTS": "advanced",
@@ -4051,6 +4058,7 @@
     "atomicWriteFile": "advanced",
     "attachToolContract": "advanced",
     "autoModeArmingRecipeOf": "advanced",
+    "autoRunOnRecommendationEffective": "internal",
     "backgroundAgentStoreContract": "advanced",
     "backgroundAgentStoreScopesContract": "advanced",
     "bashReadBoundaryProbe": "advanced",