@sema-agent/core 7.34.0 → 7.35.0

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

@@ -14,8 +14,14 @@ export interface FileSessionRepoOptions {
      * Never fires on plain ENOENT / `not_found` — that is honest absence, and the torn TAIL stays silent
      * too (dying mid-write is the append log's documented crash-recovery shape, not corruption).
      * Swallow-guarded: a throwing sink cannot re-introduce the fault the fail-open avoids.
+     *
+     * `sessionId` rides every disclosure about ONE session — its log's skipped records and tally, and its log
+     * skipped from a listing — naming the session the repo was reading (on a listing, the id its file name
+     * spells); a disclosure about the sessions directory itself carries none.
      */
-    onCorruptRead?: (info: CorruptReadInfo) => void;
+    onCorruptRead?: (info: CorruptReadInfo & {
+        sessionId?: string;
+    }) => void;
 }
 export declare class FileSessionRepo implements SessionRepo {
     private readonly dir;
@@ -26,7 +32,7 @@ export declare class FileSessionRepo implements SessionRepo {
      *  check on the way out possible without pinning a storage the table itself only holds weakly. */
     private readonly joined;
     constructor(root: string, opts?: FileSessionRepoOptions);
-    /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}. */
+    /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}'s whole-file level; `sessionId` when the file is one session's log. */
     private disclose;
     private pathFor;
     /**

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

@@ -74,8 +74,8 @@ export class FileSessionRepo {
         ensureDir(this.tmpDir);
         this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
     }
-    disclose(path, reason) {
-        this.onCorruptRead?.({ kind: "file", path, reason });
+    disclose(path, reason, sessionId) {
+        this.onCorruptRead?.({ kind: "file", path, reason, ...(sessionId !== undefined ? { sessionId } : {}) });
     }
     pathFor(id) {
         return join(this.dir, `${sanitizePathComponent(id)}${SUFFIX}`);
@@ -89,7 +89,7 @@ export class FileSessionRepo {
         const lines = readJsonlRecords(path, (info) => {
             if (info.kind === "replay")
                 tally = info;
-            this.onCorruptRead?.(info);
+            this.onCorruptRead?.({ ...info, sessionId: id });
         }, SESSION_LINE_JUDGE);
         let meta;
         const entries = [];
@@ -174,7 +174,7 @@ export class FileSessionRepo {
             }
             catch (err) {
                 if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the listing`);
+                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the listing`, id);
                 }
             }
         }
@@ -203,7 +203,7 @@ export class FileSessionRepo {
             }
             catch (err) {
                 if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the placed listing`);
+                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the placed listing`, id);
                 }
                 continue;
             }

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

@@ -42,7 +42,8 @@ export interface FileReadStationOptions {
     readonly exempt?: (canonicalKey: string) => boolean;
 }
 export declare function createFileReadStation(opts: FileReadStationOptions): FileReadStation;
-/** One gate input over the leg's read stations: each call is judged by the station whose membership holds it. */
+/** One gate input over the leg's read stations: each call is judged by the station whose membership holds the first of
+ *  its names any station holds (the spelling first). */
 export declare function composeReadChecks(stations: ReadonlyArray<{
     readonly check: ShellReadCheck;
     readonly tools: ReadonlySet<string>;

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

@@ -1,5 +1,5 @@
 import { effectivePathSpellingOf } from "../../core/effective-path-target.js";
-import { pathTargetOf } from "../../core/tool-registry.js";
+import { firstNamed, pathTargetOf, ruleNamesOf } from "../../core/tool-registry.js";
 import { fitMiddle, READ_DENY_SENTENCE_PART_MAX } from "./read-deny.js";
 import { resolveKey, violationDetails } from "./safety.js";
 import { grantOfferFor, parentDirLexically } from "./shell-read-judge.js";
@@ -16,10 +16,12 @@ export function createFileReadStation(opts) {
         admissions.set(toolCallId, key);
     };
     const check = {
-        judge(toolName, args, cwd, signal, callOpts) {
-            if (!opts.tools.has(toolName))
+        judge(call, args, cwd, signal, callOpts) {
+            const member = ruleNamesOf(call).find((n) => opts.tools.has(n));
+            if (member === undefined)
                 return null;
-            const selection = effectivePathSpellingOf({ toolName, args }, pathTargetOf(toolName), { root: opts.rootCanonical, cwd });
+            const toolName = call.toolName;
+            const selection = effectivePathSpellingOf({ toolName, args }, pathTargetOf(member), { root: opts.rootCanonical, cwd });
             if (selection === undefined || "refused" in selection || selection.spelled === undefined)
                 return null;
             const spelled = selection.spelled;
@@ -36,7 +38,7 @@ export function createFileReadStation(opts) {
                 if (callOpts.seat === "rejudge") {
                     return { disposition: "refuse", finding: "outside_roots", sentence: `Error (${toolName}): the approved edit reads "${fitMiddle(target, READ_DENY_SENTENCE_PART_MAX)}", outside the directories allowed for this session (${allowed}) — re-submit it as a fresh call and answer its card.`, details };
                 }
-                const info = pathTargetOf(toolName)?.absent === "base" ? await opts.env.fileInfo(target, signal) : undefined;
+                const info = pathTargetOf(member)?.absent === "base" ? await opts.env.fileInfo(target, signal) : undefined;
                 const readsDirectory = info?.ok === true && info.value.kind === "directory";
                 const offer = grantOfferFor(readsDirectory ? target : parentDirLexically(target), target, { roots, ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}) });
                 return {
@@ -64,8 +66,14 @@ export function composeReadChecks(stations) {
         return undefined;
     if (stations.length === 1)
         return stations[0].check;
+    const byName = new Map();
+    for (const s of stations)
+        for (const n of s.tools)
+            if (!byName.has(n))
+                byName.set(n, s);
+    const stationOf = (call) => firstNamed(byName, ruleNamesOf(call))?.value;
     return {
-        judge: (toolName, args, cwd, signal, callOpts) => stations.find((s) => s.tools.has(toolName))?.check.judge(toolName, args, cwd, signal, callOpts) ?? null,
-        unanswered: (toolName, cause) => (stations.find((s) => s.tools.has(toolName)) ?? stations[0]).check.unanswered(toolName, cause),
+        judge: (call, args, cwd, signal, callOpts) => stationOf(call)?.check.judge(call, args, cwd, signal, callOpts) ?? null,
+        unanswered: (call, cause) => (stationOf(call) ?? stations[0]).check.unanswered(call, cause),
     };
 }

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

@@ -22,6 +22,7 @@ import { violationDetails } from "./safety.js";
 import { type ShellReadPlan } from "./shell-read-plan.js";
 import { type EstablishedRead, type ShellReadBoundary, type ShellReadDisposition, type ShellReadFinding, type ShellReadSeat } from "./shell-read-judge.js";
 import type { ReadRootGrantCandidate } from "../../core/tool-spec.js";
+import { type ToolCallLike } from "../../core/tool-registry.js";
 /** The ONE mint of the containment card — the targets a finding established OUTSIDE the roots (an out-of-root read, a
  *  target that resolves elsewhere by the spawn). */
 declare function containmentDetails(paths: readonly string[]): {
@@ -89,14 +90,21 @@ export type ShellReadStationSeat = Exclude<ShellReadSeat, "rejudge">;
  * is load-bearing for the gate: a call the station does not cover must not cost the fold a suspension
  * point. `unanswered` is the verdict the fold substitutes when the wait elapsed or threw — fail-closed as
  * `unestablishable` on the call's own seat.
+ *
+ * Both take the CALL (`{ toolName, face }`), not a name: a station is a tighten keyed on the engine's own tool names,
+ * so it holds a call made under ANY of the call's names (`ruleNamesOf` — a tool that answers to `Bash` under another
+ * wire name is judged as `Bash`). The first of the names the station's membership holds keys its seat, its boundary
+ * and the admission the engine's tool reads before it spawns; the sentences name the call's wire name.
  */
 export interface ShellReadCheck {
-    judge(toolName: string, args: unknown, cwd: string | undefined, signal: AbortSignal | undefined, opts: {
+    judge(call: ReadStationCall, args: unknown, cwd: string | undefined, signal: AbortSignal | undefined, opts: {
         readonly toolCallId?: string;
         readonly seat?: "rejudge";
     }): Promise<ShellReadVerdict> | null;
-    unanswered(toolName: string, cause: string): ShellReadVerdict;
+    unanswered(call: ReadStationCall, cause: string): ShellReadVerdict;
 }
+/** The call a read station judges: its wire name and the face the gate stamped (whose `names` the station reads). */
+export type ReadStationCall = Pick<ToolCallLike, "toolName" | "face">;
 /** The pre-spawn admission the shell tools call: re-establishes what the station established for this
  *  call and refuses when any canonical target moved. `undefined` ⇒ spawn. A call the station never judged
  *  (no gate ran) has nothing to re-establish and spawns. */

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

@@ -8,6 +8,7 @@ import { planShellReads } from "./shell-read-plan.js";
 import { createShellReadEstablisher, establishShellReadsLexically } from "./shell-read-establish.js";
 import { programArgs, spellsOption } from "./shell-read-write-targets.js";
 import { allFindings, decideShellRead, denyRowAtOrBelow, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, } from "./shell-read-judge.js";
+import { ruleNamesOf } from "../../core/tool-registry.js";
 import { normalizeReadRootCandidate } from "../../core/read-root-candidate.js";
 import { argvOf, lexShellText } from "../../shell/lex.js";
 function containmentDetails(paths) {
@@ -359,26 +360,29 @@ export function createShellReadStation(opts) {
         }
         admissions.set(toolCallId, a);
     };
+    const memberOf = (call) => ruleNamesOf(call).find((n) => opts.tools.has(n));
     const check = {
-        judge(toolName, args, cwd, signal, callOpts) {
-            if (!opts.tools.has(toolName))
+        judge(call, args, cwd, signal, callOpts) {
+            const member = memberOf(call);
+            if (member === undefined)
                 return null;
             const command = shellCommandOf(args);
             if (command === undefined)
                 return null;
-            const boundary = opts.boundaryOf(toolName, cwd);
+            const boundary = opts.boundaryOf(member, cwd);
             if (boundary === undefined)
                 return null;
-            const seat = callOpts.seat ?? opts.seatOf(toolName);
+            const seat = callOpts.seat ?? opts.seatOf(member);
             return (async () => {
-                const run = await runShellReadStation(toolName, command, boundary, seat, readers, establisherFor(boundary.roots), opts.env, signal);
+                const run = await runShellReadStation(call.toolName, command, boundary, seat, readers, establisherFor(boundary.roots), opts.env, signal);
                 if (run.verdict.disposition !== "refuse" && callOpts.toolCallId !== undefined)
-                    remember(callOpts.toolCallId, { toolName, boundary: run.boundary, established: run.established, command });
+                    remember(callOpts.toolCallId, { toolName: member, boundary: run.boundary, established: run.established, command });
                 return run.verdict;
             })();
         },
-        unanswered(toolName, cause) {
-            const seat = opts.seatOf(toolName);
+        unanswered(call, cause) {
+            const toolName = call.toolName;
+            const seat = opts.seatOf(memberOf(call) ?? toolName);
             const fold = { finding: "unestablishable" };
             const disposition = decideShellRead("unestablishable", seat);
             const account = `${cause}, so where this command reads could not be established ${NOT_AUTO_ALLOWED}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.34.0",
+  "version": "7.35.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": 2530,
+  "count": 2537,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -940,6 +940,7 @@
     "PROJECT_ID_REGEX": "variable",
     "PROJECT_MARKER_PATH": "variable",
     "PROTOCOL_TABLE": "variable",
+    "PROVIDER_ECHO_SHAPE": "variable",
     "PackSectionDeclaration": "interface",
     "ParentSpecSeat": "interface",
     "ParentSpecSeatFields": "type",
@@ -1487,6 +1488,7 @@
     "TOOL_CARD_ID_MAX_CHARS": "variable",
     "TOOL_CONFORMANCE_VECTORS": "variable",
     "TOOL_CONTRACT_MAX_CHARS": "variable",
+    "TOOL_DECLARATION_CODES": "variable",
     "TOOL_FAMILIES": "variable",
     "TOOL_KEYS_MAX": "variable",
     "TOOL_KEY_MAX_CHARS": "variable",
@@ -1550,6 +1552,7 @@
     "ToolConformanceVector": "interface",
     "ToolContentOrigin": "type",
     "ToolContractDescriptor": "interface",
+    "ToolDeclarationCode": "type",
     "ToolDisclosureManifest": "interface",
     "ToolDisclosureSnapshot": "interface",
     "ToolEffect": "type",
@@ -2105,6 +2108,7 @@
     "isPersonalScope": "function",
     "isProcessLive": "function",
     "isProtectedWrite": "function",
+    "isProviderEchoShape": "function",
     "isQuestionUnavailable": "function",
     "isRemoteExecutionEnv": "function",
     "isRetryableRemoteErrorCode": "function",
@@ -2385,6 +2389,7 @@
     "retryBackoffMs": "function",
     "riskSeverity": "function",
     "rosterMemberBoundProblem": "function",
+    "rosterToolName": "function",
     "routeKeyOf": "function",
     "routePairingStatus": "function",
     "routePeerDeliveryReceipt": "function",
@@ -2395,6 +2400,7 @@
     "ruleBasesNeeded": "function",
     "ruleFaceOfInstance": "function",
     "ruleFacesFromRoster": "function",
+    "ruleNamesOf": "function",
     "ruleOffersOfRecord": "function",
     "ruleReachesProgramRun": "function",
     "ruleSourceOf": "function",
@@ -2529,6 +2535,7 @@
     "workflowWhenToUseText": "function",
     "workflowsCapability": "function",
     "worldStillMatchesMint": "function",
+    "wrapToolPolicy": "function",
     "writableRootOf": "function",
     "writeRootAdoptionFile": "function",
     "writeThenLink": "function",
@@ -3472,6 +3479,7 @@
     "PROJECT_ID_REGEX": "advanced",
     "PROJECT_MARKER_PATH": "advanced",
     "PROTOCOL_TABLE": "advanced",
+    "PROVIDER_ECHO_SHAPE": "advanced",
     "PackSectionDeclaration": "advanced",
     "ParentSpecSeat": "advanced",
     "ParentSpecSeatFields": "advanced",
@@ -4019,6 +4027,7 @@
     "TOOL_CARD_ID_MAX_CHARS": "advanced",
     "TOOL_CONFORMANCE_VECTORS": "advanced",
     "TOOL_CONTRACT_MAX_CHARS": "advanced",
+    "TOOL_DECLARATION_CODES": "advanced",
     "TOOL_FAMILIES": "advanced",
     "TOOL_KEYS_MAX": "advanced",
     "TOOL_KEY_MAX_CHARS": "advanced",
@@ -4082,6 +4091,7 @@
     "ToolConformanceVector": "advanced",
     "ToolContentOrigin": "advanced",
     "ToolContractDescriptor": "advanced",
+    "ToolDeclarationCode": "advanced",
     "ToolDisclosureManifest": "advanced",
     "ToolDisclosureSnapshot": "internal",
     "ToolEffect": "advanced",
@@ -4637,6 +4647,7 @@
     "isPersonalScope": "advanced",
     "isProcessLive": "advanced",
     "isProtectedWrite": "advanced",
+    "isProviderEchoShape": "advanced",
     "isQuestionUnavailable": "advanced",
     "isRemoteExecutionEnv": "advanced",
     "isRetryableRemoteErrorCode": "advanced",
@@ -4917,6 +4928,7 @@
     "retryBackoffMs": "advanced",
     "riskSeverity": "advanced",
     "rosterMemberBoundProblem": "advanced",
+    "rosterToolName": "advanced",
     "routeKeyOf": "advanced",
     "routePairingStatus": "advanced",
     "routePeerDeliveryReceipt": "advanced",
@@ -4927,6 +4939,7 @@
     "ruleBasesNeeded": "advanced",
     "ruleFaceOfInstance": "advanced",
     "ruleFacesFromRoster": "advanced",
+    "ruleNamesOf": "advanced",
     "ruleOffersOfRecord": "advanced",
     "ruleReachesProgramRun": "advanced",
     "ruleSourceOf": "advanced",
@@ -5061,6 +5074,7 @@
     "workflowWhenToUseText": "advanced",
     "workflowsCapability": "advanced",
     "worldStillMatchesMint": "advanced",
+    "wrapToolPolicy": "advanced",
     "writableRootOf": "advanced",
     "writeRootAdoptionFile": "advanced",
     "writeThenLink": "advanced",