@sema-agent/core 7.26.0 → 7.26.1

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

@@ -281,7 +281,9 @@ export function createShellReadEstablisher(env, readRoots) {
         return { paths: frontier, canonical: canonicalOfMatch };
     };
     const enumerateTraversal = async (rootCanonical, signal) => {
-        const members = [];
+        const found = [];
+        const listedDirs = new Set();
+        let root;
         const stack = [{ dir: rootCanonical, spell: rootCanonical }];
         const visited = new Set([rootCanonical]);
         let dirsUsed = 0;
@@ -291,18 +293,23 @@ export function createShellReadEstablisher(env, readRoots) {
                 return { unverifiable: `"${rootCanonical}" holds more than ${MAX_GLOB_DIRS} directories, too many to enumerate to verify what a recursive read would open` };
             const listed = await env.listDir(dir, signal);
             if (!listed.ok) {
+                if (dir === rootCanonical && listed.error.code === "not_directory")
+                    root = "file";
                 if (listed.error.code === "not_directory" || listed.error.code === "not_found")
                     continue;
                 return { unverifiable: `"${dir}" cannot be enumerated to verify what a recursive read would open (${listed.error.code})` };
             }
+            listedDirs.add(dir);
+            if (dir === rootCanonical)
+                root = "directory";
             for (const entry of listed.value) {
-                if (members.length >= MAX_GLOB_MATCHES)
+                if (found.length >= MAX_GLOB_MATCHES)
                     return { unverifiable: `"${rootCanonical}" holds more than ${MAX_GLOB_MATCHES} entries, too many to enumerate to verify what a recursive read would open` };
                 const path = joinUnder(spell, entry.name);
                 const canonicalPath = joinUnder(dir, entry.name);
                 if (entry.kind === "symlink") {
                     const canon = await env.canonicalPath(canonicalPath, signal);
-                    members.push({ path, ...(canon.ok ? { canonical: canon.value } : {}), symlink: true });
+                    found.push({ path, ...(canon.ok ? { canonical: canon.value } : {}), symlink: true });
                     if (canon.ok && !visited.has(canon.value)) {
                         visited.add(canon.value);
                         stack.push({ dir: canon.value, spell: path });
@@ -316,10 +323,11 @@ export function createShellReadEstablisher(env, readRoots) {
                     }
                     continue;
                 }
-                members.push({ path, canonical: canonicalPath, symlink: false });
+                found.push({ path, canonical: canonicalPath, symlink: false });
             }
         }
-        return { members };
+        const members = found.map(({ path, canonical, symlink }) => ({ path, ...(canonical !== undefined ? { canonical } : {}), node: (symlink && canonical !== undefined && listedDirs.has(canonical) ? "directory" : "file") }));
+        return { ...(root !== undefined ? { root } : {}), members };
     };
     const canonicalReadOf = async (candidate, spelling, spellings, established, origin, canonicalKnown, signal) => {
         const real = canonicalKnown !== undefined ? { value: canonicalKnown, exact: true } : await resolve(spelling, signal);
@@ -338,16 +346,19 @@ export function createShellReadEstablisher(env, readRoots) {
         for (const candidate of judgedCandidatesOf(segment)) {
             const traversal = candidate.provenance === "traversal_root";
             const land = async (read, spellings, folded) => {
-                out.push(read);
-                if (!traversal || (read.established !== "canonical" && read.established !== "expansion") || read.target === undefined)
+                if (!traversal || (read.established !== "canonical" && read.established !== "expansion") || read.target === undefined) {
+                    out.push(read);
                     return;
+                }
                 const walkedTree = await enumerateTraversal(read.target, signal);
                 if ("unverifiable" in walkedTree) {
+                    out.push(read);
                     out.push({ candidate, established: "unestablishable", spellings, origin: folded, cause: walkedTree.unverifiable });
                     return;
                 }
+                out.push({ ...read, ...(walkedTree.root !== undefined ? { node: walkedTree.root } : {}) });
                 for (const m of walkedTree.members)
-                    out.push(await canonicalReadOf(candidate, m.path, [m.path], "expansion", folded, m.canonical, signal));
+                    out.push({ ...(await canonicalReadOf(candidate, m.path, [m.path], "expansion", folded, m.canonical, signal)), node: m.node });
             };
             for (const lexical of lexicalReadsOf(candidate, boundary)) {
                 if (lexical.established !== "lexical") {

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

@@ -133,6 +133,9 @@ export interface EstablishedRead {
     readonly spellings: readonly string[];
     /** The pattern or traversal root an `expansion` came from, as folded. */
     readonly origin?: string;
+    /** What the environment said the target IS, where a read asked — only a traversal asks (it lists the root and
+     *  every member it walks; a link's answer is its target's). Absent = nothing asked; a plain read never lists. */
+    readonly node?: "directory" | "file";
     /** Why the candidate could not be established. */
     readonly cause?: string;
 }

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

@@ -135,7 +135,9 @@ export function readRootGrantCandidateOf(judged, boundary) {
         return undefined;
     if (paths.some(hasWin32AliasedComponent))
         return undefined;
-    const readsDirectory = new Set(outside.filter((f) => f.read.candidate.provenance === "traversal_root" || f.read.candidate.provenance === "cd_target").map((f) => f.read.target));
+    const readsDirectory = new Set(outside
+        .filter((f) => (f.read.candidate.provenance === "traversal_root" && f.read.node !== "file") || f.read.candidate.provenance === "cd_target")
+        .map((f) => f.read.target));
     const dirOf = (path) => (readsDirectory.has(path) ? path : parentDirLexically(path));
     let candidate = dirOf(paths[0]);
     for (const path of paths.slice(1)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.26.0",
+  "version": "7.26.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": 2424,
+  "count": 2449,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -225,6 +225,7 @@
     "CONSOLIDATION_SYSTEM_PROMPT": "variable",
     "CONTRACT_KIT_ENGINE_VERSION": "variable",
     "COORDINATOR_ROLE_PROMPT": "variable",
+    "CORRUPT_BODY_FORMS": "variable",
     "CROSS_SESSION_CLASSIFIER_RULE": "variable",
     "CROSS_SESSION_DIALOG_EXPIRY_DEFAULT": "variable",
     "CROSS_SESSION_DIALOG_EXPIRY_VALUES": "variable",
@@ -337,6 +338,7 @@
     "ControlPlaneCorruptError": "class",
     "ControlPlaneRebuildReceipt": "interface",
     "CoreCompatRange": "interface",
+    "CorruptBodyForm": "type",
     "CrossSessionCodecError": "class",
     "CrossSessionDialogExpiry": "type",
     "CrossSessionEnvelopeFields": "interface",
@@ -430,6 +432,7 @@
     "ErasureSelect": "type",
     "EscalationRecord": "interface",
     "EscalationTrigger": "type",
+    "EstablishedRead": "interface",
     "EventDedupe": "type",
     "EventDefaultPolicy": "type",
     "EvictPolicy": "type",
@@ -1094,11 +1097,15 @@
     "RUN_WORKFLOW_TOOL_NAME": "variable",
     "RawPrefixInputs": "interface",
     "RawRuleSyncState": "interface",
+    "ReadBackShapeSubject": "interface",
+    "ReadCandidate": "interface",
     "ReadDenyBuiltinConfig": "interface",
     "ReadDenyBuiltinRow": "interface",
     "ReadDenyBuiltinTier": "type",
     "ReadDenyEntry": "type",
     "ReadDenyMatcher": "interface",
+    "ReadEstablishment": "type",
+    "ReadFinding": "interface",
     "ReadOnlyCommandRow": "interface",
     "ReadOnlyFlagArity": "type",
     "ReadOnlyShellVerdict": "type",
@@ -1251,6 +1258,10 @@
     "SETTLEMENT_KINDS": "variable",
     "SHARED_MEMORY_LIST_PAGE_SIZE": "variable",
     "SHARED_MEMORY_READ_CAP_BYTES": "variable",
+    "SHELL_READ_DECISION": "variable",
+    "SHELL_READ_FINDINGS": "variable",
+    "SHELL_READ_FINDING_RANK": "variable",
+    "SHELL_READ_SEATS": "variable",
     "SHELL_WRAPPER_TABLE": "variable",
     "SKILL_TOOL_NAME": "variable",
     "STALE_RUNNING_REAP_ATTRIBUTION": "variable",
@@ -1340,6 +1351,17 @@
     "SharedMemoryStoreReader": "interface",
     "ShellCommandShape": "interface",
     "ShellGateDoctrine": "type",
+    "ShellReadAdmission": "type",
+    "ShellReadBoundary": "interface",
+    "ShellReadDisposition": "type",
+    "ShellReadFinding": "type",
+    "ShellReadJudgeInput": "interface",
+    "ShellReadJudgment": "interface",
+    "ShellReadPlan": "interface",
+    "ShellReadSeat": "type",
+    "ShellReadSegment": "interface",
+    "ShellReadStationSeat": "type",
+    "ShellReadVerdict": "interface",
     "ShellRedirection": "interface",
     "ShellSegment": "interface",
     "ShellWord": "interface",
@@ -1369,6 +1391,7 @@
     "StopSource": "type",
     "StoreDurability": "type",
     "StoreFidelity": "type",
+    "StoreReadBackShapeHooks": "interface",
     "StoredRules": "interface",
     "StoredSession": "class",
     "StoredSessionRules": "interface",
@@ -2040,6 +2063,7 @@
     "judgeParkedToolIdentity": "function",
     "judgePeerAdmission": "function",
     "judgePeerRecordFile": "function",
+    "judgeShellRead": "function",
     "killProcessTree": "function",
     "languageFor": "function",
     "leafIdAfterEntry": "function",
@@ -2361,6 +2385,7 @@
     "splitWorkflowMeta": "function",
     "sqliteQuery": "function",
     "startWorkflow": "function",
+    "storeReadBackShapeContract": "function",
     "stripEngineMetadata": "function",
     "stripFormatCharacters": "function",
     "stripRev": "function",
@@ -2651,6 +2676,7 @@
     "CONSOLIDATION_SYSTEM_PROMPT": "internal",
     "CONTRACT_KIT_ENGINE_VERSION": "advanced",
     "COORDINATOR_ROLE_PROMPT": "advanced",
+    "CORRUPT_BODY_FORMS": "advanced",
     "CROSS_SESSION_CLASSIFIER_RULE": "advanced",
     "CROSS_SESSION_DIALOG_EXPIRY_DEFAULT": "advanced",
     "CROSS_SESSION_DIALOG_EXPIRY_VALUES": "advanced",
@@ -2763,6 +2789,7 @@
     "ControlPlaneCorruptError": "advanced",
     "ControlPlaneRebuildReceipt": "advanced",
     "CoreCompatRange": "advanced",
+    "CorruptBodyForm": "advanced",
     "CrossSessionCodecError": "advanced",
     "CrossSessionDialogExpiry": "advanced",
     "CrossSessionEnvelopeFields": "advanced",
@@ -2856,6 +2883,7 @@
     "ErasureSelect": "advanced",
     "EscalationRecord": "advanced",
     "EscalationTrigger": "advanced",
+    "EstablishedRead": "advanced",
     "EventDedupe": "advanced",
     "EventDefaultPolicy": "advanced",
     "EvictPolicy": "advanced",
@@ -3520,11 +3548,15 @@
     "RUN_WORKFLOW_TOOL_NAME": "stable",
     "RawPrefixInputs": "advanced",
     "RawRuleSyncState": "advanced",
+    "ReadBackShapeSubject": "advanced",
+    "ReadCandidate": "advanced",
     "ReadDenyBuiltinConfig": "advanced",
     "ReadDenyBuiltinRow": "advanced",
     "ReadDenyBuiltinTier": "advanced",
     "ReadDenyEntry": "advanced",
     "ReadDenyMatcher": "advanced",
+    "ReadEstablishment": "advanced",
+    "ReadFinding": "advanced",
     "ReadOnlyCommandRow": "advanced",
     "ReadOnlyFlagArity": "advanced",
     "ReadOnlyShellVerdict": "advanced",
@@ -3677,6 +3709,10 @@
     "SETTLEMENT_KINDS": "advanced",
     "SHARED_MEMORY_LIST_PAGE_SIZE": "advanced",
     "SHARED_MEMORY_READ_CAP_BYTES": "advanced",
+    "SHELL_READ_DECISION": "advanced",
+    "SHELL_READ_FINDINGS": "advanced",
+    "SHELL_READ_FINDING_RANK": "advanced",
+    "SHELL_READ_SEATS": "advanced",
     "SHELL_WRAPPER_TABLE": "advanced",
     "SKILL_TOOL_NAME": "internal",
     "STALE_RUNNING_REAP_ATTRIBUTION": "advanced",
@@ -3766,6 +3802,17 @@
     "SharedMemoryStoreReader": "advanced",
     "ShellCommandShape": "advanced",
     "ShellGateDoctrine": "advanced",
+    "ShellReadAdmission": "advanced",
+    "ShellReadBoundary": "advanced",
+    "ShellReadDisposition": "advanced",
+    "ShellReadFinding": "advanced",
+    "ShellReadJudgeInput": "advanced",
+    "ShellReadJudgment": "advanced",
+    "ShellReadPlan": "advanced",
+    "ShellReadSeat": "advanced",
+    "ShellReadSegment": "advanced",
+    "ShellReadStationSeat": "advanced",
+    "ShellReadVerdict": "advanced",
     "ShellRedirection": "advanced",
     "ShellSegment": "advanced",
     "ShellWord": "advanced",
@@ -3795,6 +3842,7 @@
     "StopSource": "advanced",
     "StoreDurability": "advanced",
     "StoreFidelity": "advanced",
+    "StoreReadBackShapeHooks": "advanced",
     "StoredRules": "advanced",
     "StoredSession": "stable",
     "StoredSessionRules": "advanced",
@@ -4466,6 +4514,7 @@
     "judgeParkedToolIdentity": "advanced",
     "judgePeerAdmission": "advanced",
     "judgePeerRecordFile": "advanced",
+    "judgeShellRead": "advanced",
     "killProcessTree": "internal",
     "languageFor": "internal",
     "leafIdAfterEntry": "internal",
@@ -4787,6 +4836,7 @@
     "splitWorkflowMeta": "advanced",
     "sqliteQuery": "advanced",
     "startWorkflow": "advanced",
+    "storeReadBackShapeContract": "advanced",
     "stripEngineMetadata": "advanced",
     "stripFormatCharacters": "advanced",
     "stripRev": "advanced",