@sema-agent/core 7.48.0 → 7.49.0

package/dist/core/tool-face.js

@@ -1,6 +1,10 @@
 export const TOOL_FAMILIES = Object.freeze(["shell", "file-read", "file-write", "search", "web", "delegate", "plan", "scaffold", "memory", "protocol", "other"]);
 export const TOOL_MOUNT_TAGS = Object.freeze(["hands", "backgroundTasks", "workflow", "delegation", "hostInternals", "peerLane", "scheduler", "memory", "scenario", "always", "optional"]);
 export const TOOL_APPROVAL_CARDS = Object.freeze(["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"]);
+export function isToolApprovalCard(word) {
+    return typeof word === "string" && TOOL_APPROVAL_CARDS.includes(word);
+}
+export const RESERVED_APPROVAL_CARDS = Object.freeze(["question", "plan"]);
 export const TOOL_PATH_ACCESSES = Object.freeze(["read", "create", "edit"]);
 export const TOOL_PATH_BASES = Object.freeze(["cwd", "root"]);
 export const TOOL_PATH_ABSENCES = Object.freeze(["none", "base"]);
@@ -20,6 +24,7 @@ export const TOOL_KEYS_MAX = 1024;
 export const RENDER_HINT_MAX_CHARS = 64;
 export const RENDER_HINT_ACTIVITY_MAX_CHARS = 32;
 export const RENDER_HINT_MAX_LIST = 16;
+export const TOOL_LEG_KINDS = Object.freeze(["delegated", "teammate", "goal", "observer", "structured"]);
 export const MOUNT_TAG_IN_HANDS_BAND = {
     hands: true,
     backgroundTasks: true,

package/dist/core/tool-model-gate.d.ts

@@ -76,12 +76,12 @@ export declare function isModelGatedForClass(modelId: string, rule: ToolModelGat
 export declare function assertRestoreGatedToolsValue(value: unknown): asserts value is true | readonly string[] | undefined;
 /** Doors-facing decision (built + applied inside `prepareConfigDoors`' synchronous stretch —
  *  decision and application share one atomic window, no drift gap). */
-export interface ToolModelGateDecision {
+export interface ToolModelGateDecision<T extends ToolSpec = ToolSpec> {
     /** Present ⇔ at least one entry was removed: the fresh, PRIVATE survivor array `spec.tools` is
      *  rebound to (a caller mutating its original live array afterwards can neither re-add a removed
      *  entry nor displace anything — there are no indices left to misalign). `undefined` = no
      *  removal, the spec is left untouched. */
-    survivors: ToolSpec[] | undefined;
+    survivors: T[] | undefined;
     /** gate-class → removed wire names (sorted, unique) — the removal-notice payload. */
     removedByClass: ReadonlyMap<string, readonly string[]>;
     /** Stamped classes with no row in the merged table — announce-once material (the loud half of
@@ -116,10 +116,10 @@ export interface ToolModelGateDecision {
  *  - the exclusion valve (`excludeTools`, applied downstream at the roster splice) ALWAYS wins in
  *    the result: no restore channel resurrects an excluded name.
  */
-export declare function applyToolModelGate(input: {
-    tools: ReadonlyArray<ToolSpec> | undefined;
+export declare function applyToolModelGate<T extends ToolSpec>(input: {
+    tools: ReadonlyArray<T> | undefined;
     modelId: string;
     depsSeat: unknown;
     restoreGated: true | readonly string[] | undefined;
     envRaw: string | undefined;
-}): ToolModelGateDecision;
+}): ToolModelGateDecision<T>;

package/dist/core/tool-name-aliases.d.ts

@@ -10,8 +10,9 @@ import { type ProtocolNamespace } from "./protocol-table.js";
  *    rather than carried.
  *  - `canonicalToolName` is gone with it: with the mapping cleared it was the identity function, and
  *    keeping an identity shim invites the next mapping to grow back silently.
- *  - `TOMBSTONED_TOOLS` (per-name re-education messages) is gone: a retired name now gets the same
- *    loud generic roster miss as any unknown tool.
+ *  - `TOMBSTONED_TOOLS` (a second table of per-name re-education prose) is gone. A CALL to a retired name is
+ *    told what the one table here says about it ({@link judgeToolNameMiss}): the miss is `expected-absent`
+ *    with the successor, where any other unknown name stays the generic roster miss.
  *
  * What REMAINS is validation data: {@link RETIRED_TOOL_NAMES} maps every name the engine ever
  * retired to a one-line guidance string, and {@link judgeRuleToolName} is the ONE reading of it a rule's
@@ -78,8 +79,31 @@ export declare function splitNamespacedName(name: string): {
 } | undefined;
 /** See {@link RuleToolNameVerdict}. Pure; the one answer to "is this rule's tool name a name that reaches no tool". */
 export declare function judgeRuleToolName(name: string, roster: ReadonlySet<string>): RuleToolNameVerdict;
+/** The two kinds of tool-name miss — a closed set. `unknown`: the name is none the engine ever mounted (a typo, a
+ *  guess). `expected-absent`: the name is one the engine RETIRED ({@link RETIRED_TOOL_NAMES}), so its absence is no
+ *  surprise and the table says what replaced it (CC 2.1.296 spells the same two words for its render-time miss). */
+export declare const TOOL_MISS_KINDS: readonly ["unknown", "expected-absent"];
+declare const UNKNOWN_MISS: "unknown", ABSENT_MISS: "expected-absent";
+/** What {@link judgeToolNameMiss} answers: the kind (a {@link TOOL_MISS_KINDS} word) and, for `expected-absent`, the clause. */
+export type ToolNameMiss = {
+    readonly kind: typeof UNKNOWN_MISS;
+} | {
+    readonly kind: typeof ABSENT_MISS;
+    readonly detail: string;
+    readonly successor?: string;
+};
+/**
+ * The answer to "a call named `name` matched nothing in `roster`" — the ONE place a tool-call miss is classified:
+ * `expected-absent` (with the model-facing `detail`) for a retired name, `unknown` for everything else. It reads the
+ * table through {@link judgeRuleToolName}, so a rule's tool name and a call's tool name are judged by the same reading.
+ * The detail is the successor (`renamed "<name>"`) when the table names one AND this run mounts it — a successor the
+ * roster lacks (plan mode, no shell) is named as unavailable, never offered as the way forward, and is not returned as
+ * `successor` — else the table's own line (`folded into …` / `removed — …`), the grammar in the module header.
+ */
+export declare function judgeToolNameMiss(name: string, roster: ReadonlySet<string>): ToolNameMiss;
 /** The names a run mounts — every tool's primary name and its aliases: the roster {@link judgeRuleToolName} is given. */
 export declare function mountedToolNames(tools: ReadonlyArray<{
     readonly name: string;
     readonly aliases?: readonly string[];
 }>): Set<string>;
+export {};

package/dist/core/tool-name-aliases.js

@@ -80,6 +80,19 @@ export function judgeRuleToolName(name, roster) {
         return carriesNamespaceSeparator(name) ? UNPREFIXED : CURRENT;
     return unmintableSegmentOf(split) ?? CURRENT;
 }
+export const TOOL_MISS_KINDS = Object.freeze(["unknown", "expected-absent"]);
+const [UNKNOWN_MISS, ABSENT_MISS] = TOOL_MISS_KINDS;
+export function judgeToolNameMiss(name, roster) {
+    const v = judgeRuleToolName(name, roster);
+    if (v.kind !== "retired")
+        return { kind: UNKNOWN_MISS };
+    const next = v.currentName;
+    if (next === undefined)
+        return { kind: ABSENT_MISS, detail: v.guidance };
+    if (!roster.has(next))
+        return { kind: ABSENT_MISS, detail: `renamed to "${next}", which this run does not mount` };
+    return { kind: ABSENT_MISS, detail: `renamed to "${next}"`, successor: next };
+}
 export function mountedToolNames(tools) {
     return new Set(tools.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
 }

package/dist/core/tool-name-list.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The one reading and the one snapshot of a host-written tool-name list (an agent definition's allowed-tools or denied-tools list,
+ * a tool's alias list, a model-id list). The judge before the run, the spawn-time filter, the memory content-origin face and the
+ * roster snapshot all meet a list through here, so a hostile container is answered once and the same way everywhere.
+ */
+/** A fixed label of a host value's TYPE for a sentence that must not print or convert the value (`typeof` and the array test only). */
+export declare function valueTypeLabel(value: unknown): string;
+/**
+ * How a tool-name list's VALUE (an agent definition's allowed-tools or denied-tools list) reads as a list. A host that reads its
+ * definitions from a file can hand over anything, and a list can be hostile as a container (an accessor or a proxy trap that
+ * throws, an overridden iterator, holes): it is read BY INDEX over its length, once, into a dense copy — no iterator of the host
+ * runs, a hole reads as `undefined` (an entry that is not a string) — and a value that is not an array, or an array whose read
+ * throws, is reported as such and never printed or converted.
+ */
+export type ToolNameListReading = {
+    readonly kind: "entries";
+    readonly entries: readonly unknown[];
+} | {
+    readonly kind: "not_a_list";
+    readonly type: string;
+} | {
+    readonly kind: "unreadable";
+};
+/** What the mount keeps of a list it could not read: one frozen marker, so the judgment and every later reader meet the same
+ *  failure and never read the host's container again (a list that throws once and answers afterwards must not pass the second look). */
+export declare const UNREADABLE_LIST: object;
+export declare function readToolNameList(value: unknown): ToolNameListReading;
+/** A tool-name list as the mount keeps it: the dense copy when it reads as a list, the failure marker when it cannot be read, else
+ *  the value itself (not a list: the judge refuses it, and its type never changes). */
+export declare function snapshotToolNameList(value: unknown): unknown;

package/dist/core/tool-name-list.js

@@ -0,0 +1,55 @@
+export function valueTypeLabel(value) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+            return "a string";
+        case "undefined":
+            return "undefined";
+        case "number":
+            return "a number";
+        case "boolean":
+            return "a boolean";
+        case "bigint":
+            return "a bigint";
+        case "symbol":
+            return "a symbol";
+        case "function":
+            return "a function";
+        default:
+            try {
+                return Array.isArray(value) ? "an array" : "an object";
+            }
+            catch {
+                return "an object";
+            }
+    }
+}
+const isList = (value) => Array.isArray(value);
+export const UNREADABLE_LIST = Object.freeze({});
+export function readToolNameList(value) {
+    if (value === UNREADABLE_LIST)
+        return { kind: "unreadable" };
+    let list;
+    try {
+        list = isList(value) ? value : undefined;
+    }
+    catch {
+        return { kind: "not_a_list", type: "an object" };
+    }
+    if (list === undefined)
+        return { kind: "not_a_list", type: valueTypeLabel(value) };
+    try {
+        const entries = [];
+        for (let i = 0; i < list.length; i++)
+            entries.push(list[i]);
+        return { kind: "entries", entries };
+    }
+    catch {
+        return { kind: "unreadable" };
+    }
+}
+export function snapshotToolNameList(value) {
+    const read = readToolNameList(value);
+    return read.kind === "entries" ? read.entries : read.kind === "unreadable" ? UNREADABLE_LIST : value;
+}

package/dist/core/tool-name-readings.d.ts

@@ -193,10 +193,6 @@ export declare const NAME_READINGS: {
         readonly rank: "tier";
         readonly file: string;
     };
-    readonly "park.syncFirstRoute": {
-        readonly kind: "wire";
-        readonly file: string;
-    };
     readonly "report.riskAxes": {
         readonly kind: "seat";
         readonly rank: "tier";
@@ -259,11 +255,7 @@ export declare const NAME_READINGS: {
         readonly kind: "wire";
         readonly file: string;
     };
-    readonly "park.contentKindProjection": {
-        readonly kind: "wire";
-        readonly file: string;
-    };
-    readonly "resume.contentAskRow": {
+    readonly "card.reserved": {
         readonly kind: "wire";
         readonly file: string;
     };

package/dist/core/tool-name-readings.js

@@ -49,7 +49,6 @@ export const NAME_READINGS = {
     "offer.marks": seat("tier", OFFER),
     "offer.marks.egress": any(OFFER),
     "park.riskDescriptor": seat("tier", PARK),
-    "park.syncFirstRoute": wire(PARK),
     "report.riskAxes": seat("tier", CHAIN),
     "report.riskAxes.egress": any(CHAIN),
     "report.riskAxes.negatives": seat("member", CHAIN),
@@ -65,8 +64,7 @@ export const NAME_READINGS = {
     "reconcile.orphanEffect": spelling("src/core/session-reconcile.ts"),
     "inherited.questionFloat": wire(CHAIN),
     "inherited.askFace": wire(CHAIN),
-    "park.contentKindProjection": wire("src/core/checkpoint-store.ts"),
-    "resume.contentAskRow": wire("src/core/runner/decide-continuation.ts"),
+    "card.reserved": wire("src/core/tool-roster.ts"),
     "resume.editRecheckQuestionSkip": wire("src/core/runner/resume-apply.ts"),
     "resume.questionArgsShown": wire("src/core/runner/run-leg.ts"),
     "budget.exemptResult": wire("src/core/tool-result-budget.ts"),