@sema-agent/core 7.7.0 → 7.8.0

package/dist/core/tool-registry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The static tool catalog's READ FACE (design/388 §2.1): `describeToolCatalog()` and the predicates
+ * every former name table is now DERIVED from. Readable without an env, a deps object or a tool
+ * instance — a host predicts a leg's roster from it (`predictMountedToolNames`), a policy module
+ * derives its covered set from it, a shell renders it.
+ *
+ * Every predicate here answers over DEFINITIONS and folds to names with "any definition under this
+ * name matches" — the rule that pins the two fail-open shapes a per-name table had (one name, two
+ * definitions; the table could only hold one).
+ *
+ * Layer-0 vocabulary: depends on the leaf catalog and the face vocabulary only.
+ */
+import { type ToolCatalogEntry, type ToolMountTag, type ToolPathAccess } from "./tool-face.js";
+/** The whole static catalog, one frozen row per definition (design/388 §2.1 `describeToolCatalog()`).
+ *  Replaces the retired name-keyed exports `HAND_TOOL_EFFECTS` / `DEFAULT_BUDGET_EXEMPT_TOOLS` /
+ *  `COMPACTABLE_TOOLS`: filter this instead (`e.mountedBy.includes("hands")`, `e.face.budgetExempt`,
+ *  `e.face.compactable`). */
+export declare function describeToolCatalog(): readonly ToolCatalogEntry[];
+/** Every definition under a wire name (a name may carry more than one — the two shells). */
+export declare function catalogEntriesNamed(name: string): readonly ToolCatalogEntry[];
+/** Every wire name the catalog knows, aliases included (a set — the two shells fold to one name). */
+export declare function catalogToolNames(): ReadonlySet<string>;
+/** A-11/12/13/14 — tools this engine can CONFINE BY PATH on a write: `pathTarget.access ≠ read`.
+ *  Today {Write, Edit, NotebookEdit}. */
+export declare function pathConfinableWriteToolNames(): ReadonlySet<string>;
+/** A-11 (the SECOND authorization domain) — the active-skill `allowPaths` face: confinable AND the
+ *  definition opted into skill scoping. Today {Write, Edit} — NotebookEdit is deliberately outside. */
+export declare function skillScopeWriteToolNames(): ReadonlySet<string>;
+/** A-8 — every definition that names a path target at all (read or write): the file-tool glob lane. */
+export declare function pathTargetingToolNames(): ReadonlySet<string>;
+/** A-10 — the micro-compaction whitelist (`compactable: true`). */
+export declare function compactableToolNames(): ReadonlySet<string>;
+/** A-5 — the aggregate-budget exemptions (`budgetExempt: true`). */
+export declare function budgetExemptToolNames(): ReadonlySet<string>;
+/** The value a call's args carry under a path target: `param` first, then each alias, first non-empty string wins. */
+export declare function pathTargetValue(args: unknown, pt: {
+    param: string;
+    aliases?: readonly string[];
+}): string | undefined;
+/** The path target of a wire name — the FIRST definition's (every definition under one name declares
+ *  the same target; the conformance test pins that). */
+/** A gated call as every fence sees it: the wire name, the args, and the OBJECT face a prepared leg stamped on the
+ *  request (absent on a BARE request — a policy invoked outside a Runner). */
+export interface ToolCallLike {
+    toolName: string;
+    args: unknown;
+    face?: {
+        pathTarget?: {
+            param: string;
+            aliases?: readonly string[];
+            access: ToolPathAccess;
+        };
+    } | undefined;
+}
+type CallPathTarget = {
+    param: string;
+    aliases?: readonly string[];
+    access: ToolPathAccess;
+};
+/**
+ * design/388 B6/B17 — the path target a PROTECTIVE fence reads (a deny-list judging a write's target: sensitive paths,
+ * frozen paths, write protection, the transcript gate; edit tracking): the object face's own declaration first, the
+ * catalog's declaration for the NAME as the FLOOR — for a bare request (a policy invoked outside a Runner) and for a
+ * face that declares none. Reading the catalog for an undeclared same-name tool can only TIGHTEN a deny-list (it adds
+ * a slot to judge — the pre-388 posture, never wider), which is exactly why this floor is wrong for a grant.
+ */
+export declare function protectivePathTargetOf(call: ToolCallLike): CallPathTarget | undefined;
+/**
+ * The path target a CONTAINMENT fence reads (a grant admitting a write BY its path: session `allowDirs`, the fs-write
+ * gate's accept/exempt dirs; the active-skill allowPaths face reads its own eligibility bit the same way): the object
+ * face's OWN declaration only — a same-name tool that declares no path target is an UNCONFIRMABLE write (the catalog's
+ * slot may not be the one it writes; a decoy in that slot would buy an admission), so the fence fails closed. A BARE
+ * request (no face at all — a policy invoked outside a Runner) reads the catalog for the name: the pre-388 reading, the
+ * documented migration seam for bare producers.
+ */
+export declare function declaredPathTargetOf(call: ToolCallLike): CallPathTarget | undefined;
+/** Is this call a write a PROTECTIVE fence judges (a protected target whose access ≠ read)? The name sets are its static view. */
+export declare function isProtectedWrite(call: ToolCallLike): boolean;
+/** Is this call a write a CONTAINMENT fence may ADMIT by its path (a declared target whose access ≠ read)? */
+export declare function isDeclaredWrite(call: ToolCallLike): boolean;
+/** design/388 A-18 — the file-op access a compaction summary records for a LIVE tool name: only the FILE families'
+ *  path targets name a file (a search tool's `path` is a search ROOT, not a file the model read); every other name
+ *  records nothing (retired spellings in persisted transcripts read the frozen history table at the call site). */
+export declare function fileOpAccessOf(name: string): ToolPathAccess | undefined;
+export declare function pathTargetOf(name: string): ToolCatalogEntry["face"]["pathTarget"];
+/**
+ * The rule vocabulary of a wire name from the STATIC catalog: `primaryParams` = the declared primaries, else
+ * the path target's `param` + aliases; `params` = the declared vocabulary, else the path target's names —
+ * and UNDEFINED when the catalog cannot know the full vocabulary (a definition whose schema is built inside
+ * its factory and declares no `ruleFace.params`): the static half never claims a vocabulary it has not
+ * read, so the rule compiler judges only what it knows and the leg's roster (which reads the schema)
+ * judges the rest. `undefined` as a whole for a name with nothing to say.
+ */
+export declare function catalogRuleFaceOf(name: string): {
+    primaryParams: string[];
+    params?: string[];
+} | undefined;
+/** A-1 / server B-1 — the hand band's declared effects by name (any `hands` definition; the WRITE shell
+ *  wins the name when both are listed, matching the by-name table this replaces — the read-only shell's
+ *  own instance carries `effect: "read"` and the effect roster reports THAT). */
+export declare function handBandEffects(): ReadonlyMap<string, NonNullable<ToolCatalogEntry["face"]["effect"]>>;
+/** A-3 / L4 — every `details.type` card the engine owns: the catalog's per-definition cards plus the
+ *  engine-minted ones (protocol channels, fs refusals). */
+export declare function engineCardTypes(): ReadonlySet<string>;
+/**
+ * L3 — the STATIC PREDICTION of a leg's core-mounted names for a set of active mount conditions:
+ * every definition listed under at least one active tag. `scenario` and `optional` definitions mount
+ * only when the vector names their tag (a host factory / a per-task opt-in decides them). Names are
+ * folded (the two shells predict one `Bash`).
+ */
+export declare function predictMountedToolNames(active: ReadonlySet<ToolMountTag>): ReadonlySet<string>;
+/** The closed set as a Set, for callers that validate a tag read off the wire. */
+export declare const TOOL_MOUNT_TAG_SET: ReadonlySet<string>;
+export { HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND } from "./tool-face.js";

package/dist/core/tool-registry.js

@@ -0,0 +1,114 @@
+import { TOOL_MOUNT_TAGS } from "./tool-face.js";
+import { ENGINE_CARDS, TOOL_CATALOG_ENTRIES } from "./tool-catalog-entries.js";
+export function describeToolCatalog() {
+    return TOOL_CATALOG_ENTRIES;
+}
+export function catalogEntriesNamed(name) {
+    return TOOL_CATALOG_ENTRIES.filter((e) => e.name === name);
+}
+export function catalogToolNames() {
+    const out = new Set();
+    for (const e of TOOL_CATALOG_ENTRIES) {
+        out.add(e.name);
+        for (const a of e.face.aliases ?? [])
+            out.add(a);
+    }
+    return out;
+}
+const names = (pred) => {
+    const out = new Set();
+    for (const e of TOOL_CATALOG_ENTRIES)
+        if (pred(e))
+            out.add(e.name);
+    return out;
+};
+export function pathConfinableWriteToolNames() {
+    return names((e) => e.face.pathTarget !== undefined && e.face.pathTarget.access !== "read");
+}
+export function skillScopeWriteToolNames() {
+    return names((e) => e.face.pathTarget !== undefined && e.face.pathTarget.access !== "read" && e.face.pathTarget.skillScopeEligible === true);
+}
+export function pathTargetingToolNames() {
+    return names((e) => e.face.pathTarget !== undefined);
+}
+export function compactableToolNames() {
+    return names((e) => e.face.compactable === true);
+}
+export function budgetExemptToolNames() {
+    return names((e) => e.face.budgetExempt === true);
+}
+export function pathTargetValue(args, pt) {
+    if (args === null || typeof args !== "object")
+        return undefined;
+    const a = args;
+    for (const k of [pt.param, ...(pt.aliases ?? [])]) {
+        const v = a[k];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    return undefined;
+}
+export function protectivePathTargetOf(call) {
+    return call.face?.pathTarget ?? pathTargetOf(call.toolName);
+}
+export function declaredPathTargetOf(call) {
+    return call.face !== undefined ? call.face.pathTarget : pathTargetOf(call.toolName);
+}
+export function isProtectedWrite(call) {
+    const pt = protectivePathTargetOf(call);
+    return pt !== undefined && pt.access !== "read";
+}
+export function isDeclaredWrite(call) {
+    const pt = declaredPathTargetOf(call);
+    return pt !== undefined && pt.access !== "read";
+}
+export function fileOpAccessOf(name) {
+    for (const e of TOOL_CATALOG_ENTRIES) {
+        if (e.name === name && (e.face.family === "file-read" || e.face.family === "file-write") && e.face.pathTarget !== undefined)
+            return e.face.pathTarget.access;
+    }
+    return undefined;
+}
+export function pathTargetOf(name) {
+    for (const e of TOOL_CATALOG_ENTRIES)
+        if (e.name === name && e.face.pathTarget !== undefined)
+            return e.face.pathTarget;
+    return undefined;
+}
+export function catalogRuleFaceOf(name) {
+    for (const e of TOOL_CATALOG_ENTRIES) {
+        if (e.name !== name)
+            continue;
+        const pt = e.face.pathTarget;
+        const primary = e.face.ruleFace?.primaryParams ?? (pt !== undefined ? [pt.param, ...(pt.aliases ?? [])] : []);
+        const params = e.face.ruleFace?.params ?? (pt !== undefined ? [pt.param, ...(pt.aliases ?? [])] : undefined);
+        if (params === undefined && primary.length === 0)
+            continue;
+        return { primaryParams: [...primary], ...(params !== undefined ? { params: [...new Set([...params, ...primary])] } : {}) };
+    }
+    return undefined;
+}
+export function handBandEffects() {
+    const out = new Map();
+    for (const e of TOOL_CATALOG_ENTRIES) {
+        if (!e.mountedBy.includes("hands"))
+            continue;
+        const eff = e.face.effect ?? "write";
+        const prior = out.get(e.name);
+        if (prior === undefined || prior === "read")
+            out.set(e.name, eff);
+    }
+    return out;
+}
+export function engineCardTypes() {
+    const out = new Set(Object.keys(ENGINE_CARDS));
+    for (const e of TOOL_CATALOG_ENTRIES)
+        for (const card of e.cards)
+            out.add(card);
+    return out;
+}
+export function predictMountedToolNames(active) {
+    return names((e) => e.mountedBy.some((t) => active.has(t)));
+}
+export const TOOL_MOUNT_TAG_SET = new Set(TOOL_MOUNT_TAGS);
+export { HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND } from "./tool-face.js";

package/dist/core/tool-result-budget.d.ts

@@ -46,8 +46,5 @@ export interface AggregateBudgetOptions {
         results: number;
     }) => void;
 }
-/** Default exemptions: tools whose result is self-bounded (read_file errors at its own token cap; the
- *  offload reader pages small slices). grep/bash/glob/web_fetch/MCP are the risk sources, NOT exempt. */
-export declare const DEFAULT_BUDGET_EXEMPT_TOOLS: ReadonlySet<string>;
 /** Cap each over-budget turn-batch (run of consecutive tool_result messages). Request-only; see file docs. */
 export declare function capAggregateToolResults(messages: AgentMessage[], opts: AggregateBudgetOptions): Promise<AgentMessage[]>;

package/dist/core/tool-result-budget.js

@@ -1,5 +1,6 @@
 import { isToolResult } from "./message-utils.js";
-import { buildPreview, buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX, toolResultContentSegment, toolResultProvenanceOf, } from "./tool-result-store.js";
+import { buildPreview, buildToolResultRef, PERSISTED_OUTPUT_PREFIX, toolResultContentSegment, toolResultProvenanceOf, } from "./tool-result-store.js";
+import { budgetExemptToolNames } from "./tool-registry.js";
 export const AGGREGATE_TOOL_RESULT_BUDGET_CHARS = 200_000;
 const HEAD = 1_000;
 const TAIL = 1_000;
@@ -33,10 +34,10 @@ function truncationPreview(full, head = HEAD, tail = TAIL) {
         `…[${total} chars total; ${tailStart - head} omitted to fit the per-turn result budget — re-run with a narrower query to see the rest.]\n` +
         `${full.slice(tailStart)}`);
 }
-export const DEFAULT_BUDGET_EXEMPT_TOOLS = new Set(["Read", OFFLOAD_TOOL_NAME]);
+const CATALOG_BUDGET_EXEMPT_TOOLS = budgetExemptToolNames();
 export async function capAggregateToolResults(messages, opts) {
     const budget = opts.budgetChars ?? AGGREGATE_TOOL_RESULT_BUDGET_CHARS;
-    const exempt = opts.exemptTools ?? DEFAULT_BUDGET_EXEMPT_TOOLS;
+    const exempt = opts.exemptTools ?? CATALOG_BUDGET_EXEMPT_TOOLS;
     let out;
     let i = 0;
     while (i < messages.length) {

package/dist/core/tool-result-store.d.ts

@@ -446,24 +446,6 @@ export declare function offloadPagebackHint(ref: string, form: "preview" | "clea
 export declare const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 /** Default per-result offload threshold (chars). ~5K tokens; configurable globally or per tool. */
 export declare const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20000;
-/**
- * CC 198 per-tool persistence thresholds, mirrored for the first-party mounts (PARITY-SPOT-USAGE-CONSTANTS
- * 2026-07-10 F1/F2). CC's GIa framework (pretty.js:286716-286721) resolves each tool's persist threshold as
- * `min(maxResultSizeChars, w6t=50000)`:
- *   - Read declares `maxResultSizeChars: 1/0` (:478260) → **never persisted**. Read already owns its bound
- *     (25K-token first-page auto-pagination) and the aggregate budget exempts it — wrapping it in offload
- *     re-truncated a page the tool had already sized (the F1 two-layer inconsistency). Structural exemption:
- *     applies even when a deployment sets an explicit global threshold.
- *   - Bash 30000 (:335231) / Grep 20000 (:333220) / Monitor 1e4 (:450030); everything else first-party
- *     declares 1e5 (Agent :453402, Glob :333570, TaskOutput :458260, …) → min(1e5, 50000) = 50000.
- * Unknown tools keep the deployment default ({@link DEFAULT_TOOL_RESULT_THRESHOLD_CHARS}) — we deliberately
- * do NOT mirror KIa's bare `$xa=400000` undeclared-tool fallback: our aggregate budget is 200K chars, so a
- * 400K inline result is unrepresentable anyway.
- */
-export declare function firstPartyOffloadPolicy(toolName: string): {
-    offload?: boolean;
-    offloadThresholdChars?: number;
-};
 /** Head+tail preview of an offloaded result, pointing at {@link OFFLOAD_TOOL_NAME} via `ref`. Exported so
  *  the per-message aggregate budget (design/64 §17.2) produces the SAME preview format (deterministic →
  *  byte-identical across queries → prompt-cache safe).

package/dist/core/tool-result-store.js

@@ -4,6 +4,7 @@ import { uuidv7 } from "../engine/session/uuid.js";
 import { defineTool, errorResult } from "./tools.js";
 import { deliverEngineNotice } from "./types.js";
 import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
+import { toolFace } from "./tool-catalog-entries.js";
 export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
 export class ToolResultRefConflictError extends Error {
     ref;
@@ -202,22 +203,6 @@ export function offloadPagebackHint(ref, form, reachableTools) {
 }
 export const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 export const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20_000;
-export function firstPartyOffloadPolicy(toolName) {
-    switch (toolName) {
-        case "Read":
-            return { offload: false };
-        case "Write":
-            return { offload: false };
-        case "Bash":
-            return { offloadThresholdChars: 30_000 };
-        case "Grep":
-            return { offloadThresholdChars: 20_000 };
-        case "Monitor":
-            return { offloadThresholdChars: 10_000 };
-        default:
-            return { offloadThresholdChars: 50_000 };
-    }
-}
 const PREVIEW_HEAD_CHARS = 1_000;
 const PREVIEW_TAIL_CHARS = 1_000;
 const READ_DEFAULT_LIMIT = 4_000;
@@ -398,7 +383,7 @@ async function offloadOversizedDetailStrings(details, store, thresholdChars, ses
 export function createReadToolResultTool(store) {
     return defineTool({
         name: OFFLOAD_TOOL_NAME,
-        contract: { contractId: "core.read_tool_result@1", implementationRevision: "1" },
+        ...toolFace("read-tool-result"),
         description: `Read the full content of a tool result that was too large and persisted (you saw it as ` +
             `<persisted-output ref="..."> with a preview). Pass the ref; use offset/limit to page through it.`,
         parameters: Type.Object({
@@ -406,7 +391,6 @@ export function createReadToolResultTool(store) {
             offset: Type.Optional(Type.Number({ description: "Char offset to start at (default 0)." })),
             limit: Type.Optional(Type.Number({ description: `Max chars to return (default ${READ_DEFAULT_LIMIT}, capped ${READ_MAX_LIMIT}).` })),
         }),
-        effect: "read",
         execute: async (args) => {
             const { ref, offset, limit } = args;
             const off = Math.max(0, intOr(offset, 0));