@sema-agent/core 7.55.0 → 7.56.0

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

@@ -2,7 +2,6 @@ import { Type, type Static, type TSchema } from "typebox";
 import type { AgentTool } from "../internal/harness-types.js";
 import { type ReservedApprovalCard, type ToolApprovalCard, type ToolFamily, type ToolHostTarget, type ToolRosterPathTarget, type ToolMountTag, type ToolPathTarget, type ToolRenderHints, type ToolRuleFace } from "./tool-face.js";
 import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
-import type { ToolMarkSource } from "./ask-origin.js";
 export declare const ROSTER_SOURCES: readonly ["builtin", "caller", "host", "mcp", "a2a", "external", "synthetic"];
 export type RosterSource = (typeof ROSTER_SOURCES)[number];
 export declare const ToolRosterRenderHints: Type.TObject<{
@@ -322,9 +321,11 @@ export declare function parkedToolIdentity(roster: ToolRoster | undefined, toolN
 /** design/388 B6 × B18 — the FACE members a park row carries beside its identity: the display family, the declared
  *  path target or URL slot, and the names the parked call was judged under. `names` is copied from the face the gate stamped on the
  *  request (the model's spelling first — the row carries the judged fact, it is not re-derived); a request with no face
- *  takes the roster's names for its row. A recheck that runs before the leg's roster exists (the pre-CAS resume-edit
- *  re-adjudication) rebuilds the call face from the row through {@link parkedCallFaceOf}, so it judges the same object
- *  the live gate judged. An empty object when the name is not on the snapshot (the row then reads pre-face and the
+ *  takes the roster's names for its row. The mount site (`engineMounted`) is the roster entry's, as the identity and face members
+ *  beside it are: a fact of the tool, not of the call, and never read off the request's face, which the policy that judges the call
+ *  can write. A recheck that runs before the leg's roster exists (the pre-CAS resume-edit
+ *  re-adjudication) rebuilds the call face from the row through {@link parkedCallFaceOf}, so it judges the members the row
+ *  recorded (identity, family, targets, names, mount site) — not the live face's rule name values or approval card. An empty object when the name is not on the snapshot (the row then reads pre-face and the
  *  recheck falls to the catalog for the name). */
 export declare function parkedToolFace(roster: ToolRoster | undefined, req: {
     readonly toolName: string;
@@ -336,6 +337,7 @@ export declare function parkedToolFace(roster: ToolRoster | undefined, req: {
     pathTarget?: ToolRosterEntry["pathTarget"];
     hostTarget?: ToolHostTarget;
     names?: readonly string[];
+    engineMounted?: true;
 };
 /** The live face a resumed park row is re-judged under: minted under the row's recorded spelling (`names[0]`) when that
  *  spelling still resolves to the row's own tool on this roster, else under the row's wire name — a spelling that no
@@ -356,6 +358,7 @@ export declare function parkedCallFaceOf(pending: {
     contractId?: string;
     shapeDigest?: string;
     implementationRevision?: string;
+    engineMounted?: true;
 }): import("./tool-policy.js").ToolCallFace | undefined;
 /** The optional `face` seat of a ToolCallRequest: present iff a face was read (a bare request carries no key). */
 export declare function callFaceSeat(face: import("./tool-policy.js").ToolCallFace | undefined): {
@@ -427,6 +430,8 @@ export declare function ruleFaceOfInstance(schema: TSchema | undefined, declared
     primaryParams: string[];
     params: string[];
 };
+/** The instance `row` describes: what runs when a call is judged by that row. A row no snapshot minted has none. */
+export declare function rowMember(row: ToolRosterEntry): AgentTool | undefined;
 /** The instance each NAME dispatches to when several are mounted under it: the LATER mount (the harness keeps the
  *  later one). The one selection — the roster's snapshot and every table keyed by a caller tool's name read it here. */
 export declare function survivorsByName<T extends {
@@ -478,28 +483,18 @@ export interface RosterSnapshotFacts {
     /** `TaskSpec.memory.trustedTools` — the exemption channel for an undeclared content class. */
     trustedTools: ReadonlySet<string>;
 }
-/** The leg's per-name safety-axis tables the builder keeps aligned with its mounts beside the effect map (the safety scan mints
- *  them; the protocol folds and the shell seat also write them). */
-export interface RosterAxisTables {
-    irreversibilityTier: Map<string, "never" | "maybe" | "always">;
-    irreversibleTools: Set<string>;
-    reversibilityProbes: Map<string, unknown>;
-    egressTools: Set<string>;
-    toolMarkSources: Map<string, Set<ToolMarkSource>>;
-}
 export declare class RosterBuilder {
     #private;
-    /** `axes` — the leg's safety-axis tables beside the effect map (a builder for a single probe tool may go without). */
-    constructor(effects: Map<string, ToolEffect>, axes?: RosterAxisTables);
+    /** `effects` — the leg's by-name effect map, which the builder keeps equal to the mounted set's answering members. The leg's
+     *  safety-axis tables are not the builder's: their marks live under the names they were laid on, and a call reads them under
+     *  the names it answers to. */
+    constructor(effects: Map<string, ToolEffect>);
     /** The mount array as a READ face. The order is the wire order. */
     get tools(): readonly AgentTool[];
     get length(): number;
     metaOf(tool: AgentTool): RosterMountMeta | undefined;
     /** Mount one instance at the tail; the leg's effect map then follows the mounted set (`#settleEffects`). The later mount under
-     *  a name is the one the harness dispatches to (`snapshot`'s yield rule). A `scenario` mount (a caller's own `TaskSpec.tools`
-     *  entry, the driver's frozen face — the declaration the safety scan judged) leaves the three safety axes as the scan wrote them;
-     *  any other mount under a name displaces the instance there, and the axes of the aliases the displaced instance answered to
-     *  move to the member they now resolve to (`#resettleAliases`). */
+     *  a name is the one the harness dispatches to (`snapshot`'s yield rule). */
     mount(tool: AgentTool, meta: RosterMountMeta): void;
     /** An ENGINE-INJECTED instance the harness list carries outside the mount array (the ToolSearch lane): a roster
      *  row — the model can call it — never a mount-array element (the disclosure lane owns that list and appends the

package/dist/core/tool-roster.js

@@ -140,7 +140,7 @@ export function parkedToolFace(roster, req) {
     if (e === undefined)
         return {};
     const judged = req.face?.names;
-    return { family: e.family, ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}), ...(e.hostTarget !== undefined ? { hostTarget: e.hostTarget } : {}), names: judged !== undefined && judged.includes(req.toolName) ? [...judged] : namesResolvingTo(roster, e) };
+    return { family: e.family, ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}), ...(e.hostTarget !== undefined ? { hostTarget: e.hostTarget } : {}), names: judged !== undefined && judged.includes(req.toolName) ? [...judged] : namesResolvingTo(roster, e), ...(engineMountedRow(e) ? { engineMounted: true } : {}) };
 }
 export function parkedRowLiveFace(roster, row) {
     const spelled = row.names?.[0];
@@ -159,6 +159,7 @@ export function parkedCallFaceOf(pending) {
         contractId: pending.contractId,
         shapeDigest: pending.shapeDigest,
         implementationRevision: pending.implementationRevision,
+        ...(pending.engineMounted === true ? { engineMounted: true } : {}),
     };
 }
 export function callFaceSeat(face) {
@@ -305,6 +306,10 @@ function capRenderHints(h) {
         out.approvalCard = h.approvalCard;
     return Object.keys(out).length > 0 ? out : undefined;
 }
+const ROW_MEMBERS = new WeakMap();
+export function rowMember(row) {
+    return ROW_MEMBERS.get(row);
+}
 export function survivorsByName(mounted) {
     const winner = new Map();
     for (const t of mounted)
@@ -313,18 +318,6 @@ export function survivorsByName(mounted) {
 }
 export const faceOf = (t) => t;
 const protocolFolded = (source) => source === "mcp" || source === "a2a";
-const setOrClear = (m, key, value) => {
-    if (value === undefined)
-        m.delete(key);
-    else
-        m.set(key, value);
-};
-const memberIf = (s, key, member) => {
-    if (member)
-        s.add(key);
-    else
-        s.delete(key);
-};
 function configError(code, message) {
     const e = new Error(message);
     e.code = code;
@@ -335,10 +328,8 @@ export class RosterBuilder {
     #engineLane = [];
     #meta = new WeakMap();
     #effects;
-    #axes;
-    constructor(effects, axes) {
+    constructor(effects) {
         this.#effects = effects;
-        this.#axes = axes;
     }
     get tools() {
         return this.#tools;
@@ -356,10 +347,7 @@ export class RosterBuilder {
         const displaced = this.#survivorNamed(tool.name);
         this.#admit(tool, meta);
         lane.push(tool);
-        const aliases = [...(displaced?.aliases ?? []), ...(tool.aliases ?? [])];
-        if (meta.mountedBy !== "scenario")
-            this.#resettleAliases(aliases);
-        return [tool.name, ...aliases];
+        return [tool.name, ...(displaced?.aliases ?? []), ...(tool.aliases ?? [])];
     }
     mountEngineLane(tool, meta) {
         this.#settleEffects(this.#mountOne(tool, meta, this.#engineLane));
@@ -389,28 +377,6 @@ export class RosterBuilder {
     #survivorNamed(name) {
         return survivorsByName([...this.#tools, ...this.#engineLane]).get(name);
     }
-    #resettleAliases(aliases) {
-        if (aliases.length === 0)
-            return;
-        const answering = toolNameIndex([...survivorsByName([...this.#tools, ...this.#engineLane]).values()]);
-        for (const a of new Set(aliases)) {
-            const owner = answering(a);
-            if (owner?.name === a)
-                continue;
-            this.#repoint(a, owner?.name);
-        }
-    }
-    #repoint(key, from) {
-        if (this.#axes === undefined)
-            return;
-        const pick = (m) => (from === undefined ? undefined : m.get(from));
-        const marks = pick(this.#axes.toolMarkSources);
-        setOrClear(this.#axes.irreversibilityTier, key, pick(this.#axes.irreversibilityTier));
-        setOrClear(this.#axes.reversibilityProbes, key, pick(this.#axes.reversibilityProbes));
-        setOrClear(this.#axes.toolMarkSources, key, marks === undefined ? undefined : new Set(marks));
-        memberIf(this.#axes.irreversibleTools, key, from !== undefined && this.#axes.irreversibleTools.has(from));
-        memberIf(this.#axes.egressTools, key, from !== undefined && this.#axes.egressTools.has(from));
-    }
     mountAll(tools, meta) {
         this.#settleEffects(tools.flatMap((t) => this.#mountOne(t, meta, this.#tools)));
     }
@@ -424,7 +390,6 @@ export class RosterBuilder {
             }
         }
         this.#settleEffects(this.#namesAfterRemoval(removed));
-        this.#resettleAliases(removed.flatMap((t) => t.aliases ?? []));
         return removed;
     }
     replaceAt(index, tool) {
@@ -465,7 +430,9 @@ export class RosterBuilder {
             emitted.add(t.name);
             const survivor = winner.get(t.name);
             const meta = this.#meta.get(survivor) ?? { source: "caller", mountedBy: "scenario" };
-            entries.push(mintRosterEntry(survivor, meta, facts));
+            const row = mintRosterEntry(survivor, meta, facts);
+            ROW_MEMBERS.set(row, survivor);
+            entries.push(row);
         }
         const roster = { schemaVersion: 1, count: entries.length, entries, digest: rosterDigestOf(entries) };
         const worn = rosterEngineNamesProblem(roster);

package/dist/core/tool-spec-members.js

@@ -1,6 +1,9 @@
+import { assertNoRetiredKeys, RETIRED_TOOL_SPEC_KEYS } from "./retired-keys.js";
 import { UNREADABLE_LIST, snapshotToolNameList } from "./tool-name-list.js";
+import { isCatalogContract } from "./tool-catalog-entries.js";
+import { isEngineDescriptor } from "../prompt-assembly/tool-catalog.js";
 export const TOOL_SPEC_MEMBERS = Object.keys({
-    name: true, aliases: true, description: true, descriptionClassic: true, label: true, parameters: true, execute: true, effect: true,
+    name: true, aliases: true, description: true, descriptionVariants: true, label: true, parameters: true, execute: true, effect: true,
     egress: true, irreversibility: true, reversibilityProbe: true, permissionSeat: true, isConcurrencySafe: true, executionMode: true,
     contentOrigin: true, offload: true, offloadThresholdChars: true, defer: true, alwaysLoad: true, prepareArguments: true,
     validateInput: true, approvalPreview: true, family: true, pathTarget: true, hostTarget: true, ruleFace: true, renderHints: true, compactable: true,
@@ -14,6 +17,7 @@ const FACE_PLACES = { elementKeys: FACE_LIST_KEYS };
 const MAX_NODES = 20_000;
 const MAX_DEPTH = 64;
 const COPIED = new WeakSet();
+const isEngineMint = (value) => isCatalogContract(value) || isEngineDescriptor(value);
 class DeclarationRefused extends Error {
 }
 function refuse(path, why) {
@@ -46,7 +50,7 @@ function copyNode(value, path, depth, state, lenient, places) {
         return value;
     if (typeof value === "function")
         return lenient ? inertFunction() : refuse(path, "a function inside declaration data");
-    if (COPIED.has(value))
+    if (COPIED.has(value) || isEngineMint(value))
         return value;
     const seen = lenient ? state.seenLenient : state.seen;
     const shared = seen.get(value);
@@ -158,6 +162,7 @@ export function frozenExtra(key, value, state) {
     }
 }
 export function frozenToolSpec(spec) {
+    assertNoRetiredKeys(spec, RETIRED_TOOL_SPEC_KEYS, "ToolSpec");
     const copy = {};
     const state = newCopyState();
     for (const name of TOOL_SPEC_MEMBERS) {

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

@@ -9,7 +9,7 @@
  */
 import type { TSchema } from "typebox";
 import type { ThinkingLevel, ToolInputValidationContext, ToolInputVerdict } from "../internal/harness.js";
-import type { DocumentContent, ImageContent, Model, TextContent } from "../internal/llm.js";
+import type { DocumentContent, ImageContent, Model, TextContent, ToolDescriptionVariant } from "../internal/llm.js";
 import type { AgentDefinition } from "./agent-definition.js";
 import type { TaskEvent } from "./task-event.js";
 import type { TaskSpec } from "./task-spec.js";
@@ -148,15 +148,18 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * across a canonical rename. Each alias keeps the same contract as {@link name} (a rule naming an alias reaches the tool).
      */
     aliases?: string[];
+    /** The model-facing description — the card's unconditional text: what the tool says when none of
+     *  {@link descriptionVariants} holds. */
     description: string;
     /**
-     * R2 双形轴(2026-07-18 裁):the CLASSIC-profile variant of {@link description}. The reference
-     * keys its tool descriptions on `LT(model_id)` (simple short form vs classic long form); sema's
-     * counterpart is {@link TaskSpec.promptProfile} — default "simple" (what CC serves every BYOM
-     * model id). When the run resolves to "classic" and this field is present, it REPLACES
-     * `description` at mount time. Absent = the tool has one form (description serves both profiles).
+     * The card's conditional variants, in order: at mount, the first whose `traits` condition holds over the run's
+     * prompt traits (`Model.promptTraits` with `TaskSpec.promptLean`) replaces {@link description}; none holds ⇒
+     * `description`. The reference keys its tool texts on the same capabilities (a long form where `lean_prompt` is
+     * absent): that form is a variant `{ id: "classic", traits: { noneOf: ["lean_prompt"] }, text }`. The chosen
+     * variant is reported in the tool's `cardId`. A variant whose id, condition or text is malformed refuses the task
+     * (`config.tool_face_invalid`).
      */
-    descriptionClassic?: string;
+    descriptionVariants?: readonly ToolDescriptionVariant[];
     /**
      * Human label for UIs. Defaults to `name`. When it differs from `name`, it rides the call's `tool_start` and `tool_end`
      * frames as `label` (the run builds the table from the leg's mounted tools) — the advisor tool's label is its advisor
@@ -816,6 +819,10 @@ export interface ToolExecuteContext {
      * the tool runs outside a Runner task.
      */
     parentCwd?: string;
+    /** The deployment's compiled host floor (`RunnerDeps.hostFloor`; Runner-filled, read-only, never a model argument): an engine executor
+     *  that connects — the fetch tool on every hop, WebSearch's SearXNG backend (handed it in the backend's `opts.hostFloor`) — judges each URL
+     *  by it before the request. Absent outside a Runner, or when none is declared. */
+    hostFloor?: import("./host-floor.js").HostFloor;
     /**
      * The RUNNING task's file-history LINEAGE (Runner-filled, read-only, never a model/tool argument;
      * present iff the run records file history — a `RunnerDeps.fileHistoryStore` wired, capture not `"off"`, not `"disabled"`): the history scope this run
@@ -1068,10 +1075,11 @@ export interface ToolExecuteContext {
      *  dropping the selector in transit would trim a same-model child's roster in a way nobody
      *  chose (the gate is a default, not a policy; there is no tighten-only axis to protect). */
     restoreGatedTools?: readonly string[] | true;
-    /** R2 双形轴 — the parent's resolved prompt profile, inherited down the delegation tree like the
-     *  tool-face controls (Runner-filled): a classic-profile parent's children speak classic too
-     *  unless the child spec says otherwise (child spec wins — profile is presentation, not policy). */
-    promptProfile?: "simple" | "classic";
+    /** The parent's task-level switch on the lean shape ({@link TaskSpec.promptLean} — its own, or the one it inherited;
+     *  absent when neither was written), inherited down the delegation tree like the tool-face controls
+     *  (Runner-filled): a child whose spec writes none takes it. Never the parent's effective traits — the child's model
+     *  answers the rest of its own trait set. */
+    promptLean?: boolean;
     /**
      * The parent SPEC seat this run hands its children ({@link import("./parent-spec-seat.js").ParentSpecSeat}):
      * `principal`, `oneShot` (only `true`), `clientContext` (the user's TZ/email facts), `onQuestion` (the FROZEN

package/dist/core/tools.js

@@ -3,13 +3,53 @@ import { formatToolError, formatZodValidationError } from "./tool-errors.js";
 import { readMember } from "./thrown-value.js";
 import { frozenToolSpec } from "./tool-spec-members.js";
 import { carryDelegationName } from "./delegation-name.js";
-import { attachToolContract, contractOriginOf } from "../prompt-assembly/tool-catalog.js";
-function normalizeContent(ret) {
+import { attachEngineToolContract, attachToolContract, contractOriginOf } from "../prompt-assembly/tool-catalog.js";
+import { isCatalogContract } from "./tool-catalog-entries.js";
+import { types } from "node:util";
+import { appendOwn, dataMember, isPlainRecord, receive } from "./mods/kernel/receive.js";
+import { carryNotStartedReceipt } from "./delegation-not-started.js";
+const TOOL_DATA_MODE = Object.freeze({ accessors: "call-once", depth: Infinity, others: "copy", contain: true, wire: true, isProxy: (v) => types.isProxy(v) });
+function receivedData(v) {
+    if (v === null || v === undefined || typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+        return v;
+    const r = receive(v, TOOL_DATA_MODE);
+    if (!r.ok)
+        return undefined;
+    carryNotStartedReceipt(v, r.value);
+    return r.value;
+}
+const CONTENT_BLOCK_FIELDS = Object.freeze({ text: ["text"], image: ["data", "mimeType"], document: ["data", "mimeType"] });
+function blockOf(element) {
+    if (!isPlainRecord(element))
+        return element;
+    const own = (field) => (Object.hasOwn(element, field) ? element[field] : undefined);
+    const type = own("type");
+    const fields = typeof type === "string" && Object.hasOwn(CONTENT_BLOCK_FIELDS, type) ? CONTENT_BLOCK_FIELDS[type] : undefined;
+    if (fields === undefined)
+        return element;
+    const block = { type };
+    for (const field of fields)
+        if (own(field) !== undefined)
+            Reflect.defineProperty(block, field, dataMember(own(field)));
+    return block;
+}
+function receivedContent(raw) {
+    const copy = receivedData(raw);
+    if (!Array.isArray(copy))
+        return undefined;
+    const out = [];
+    for (let i = 0; i < copy.length; i++)
+        if (Object.hasOwn(copy, i) && copy[i] !== undefined)
+            appendOwn(out, blockOf(copy[i]));
+    return out;
+}
+function receiveToolReturn(ret) {
     if (typeof ret === "string") {
         return { content: [{ type: "text", text: ret }], details: undefined, terminate: false, isError: false };
     }
     const raw = readMember(ret, "content");
-    if (typeof raw !== "string" && !Array.isArray(raw)) {
+    const content = typeof raw === "string" ? [{ type: "text", text: raw }] : receivedContent(raw);
+    if (content === undefined) {
         return {
             content: [{ type: "text", text: "Tool error: content must be a string or an array of content blocks." }],
             details: undefined,
@@ -17,8 +57,7 @@ function normalizeContent(ret) {
             isError: true,
         };
     }
-    const content = typeof raw === "string" ? [{ type: "text", text: raw }] : raw;
-    return { content, details: readMember(ret, "details"), terminate: readMember(ret, "terminate") === true, isError: readMember(ret, "isError") === true };
+    return { content: content, details: receivedData(readMember(ret, "details")), terminate: readMember(ret, "terminate") === true, isError: readMember(ret, "isError") === true };
 }
 function isEmptyToolContent(content) {
     if (content.length === 0)
@@ -78,7 +117,7 @@ function buildProduct(spec, owner, options) {
         name: spec.name,
         ...(spec.aliases && spec.aliases.length > 0 ? { aliases: [...spec.aliases] } : {}),
         description: spec.description,
-        ...(spec.descriptionClassic !== undefined ? { descriptionClassic: spec.descriptionClassic } : {}),
+        ...(spec.descriptionVariants !== undefined ? { descriptionVariants: spec.descriptionVariants } : {}),
         label: spec.label ?? spec.name,
         parameters: spec.parameters,
         executionMode,
@@ -121,7 +160,7 @@ function buildProduct(spec, owner, options) {
                 const baseCtx = { toolCallId, signal };
                 const ctx = options?.enrichCtx ? stampCallIdentity(options.enrichCtx(baseCtx), toolCallId, signal) : baseCtx;
                 const ret = await spec.execute.call(owner, params, ctx);
-                const { content, details, terminate, isError } = normalizeContent(ret);
+                const { content, details, terminate, isError } = receiveToolReturn(ret);
                 const guarded = isEmptyToolContent(content)
                     ? [{ type: "text", text: isError ? `(${spec.name} reported an error with no further output)` : `(${spec.name} completed with no output)` }]
                     : content;
@@ -129,7 +168,7 @@ function buildProduct(spec, owner, options) {
             }
             catch (err) {
                 const wrapped = new Error(formatToolError(err));
-                const marks = readMember(err, "details");
+                const marks = receivedData(readMember(err, "details"));
                 if (marks !== undefined)
                     wrapped.details = marks;
                 const errorKind = readMember(err, "errorKind");
@@ -141,7 +180,8 @@ function buildProduct(spec, owner, options) {
     };
     carryDelegationName(spec.execute, tool.execute);
     if (spec.contract) {
-        attachToolContract(tool, {
+        const attach = isCatalogContract(spec.contract) ? attachEngineToolContract : attachToolContract;
+        attach(tool, {
             contractId: spec.contract.contractId,
             implementationRevision: spec.contract.implementationRevision,
             origin: contractOriginOf(spec.contract.contractId),

package/dist/core/trace.d.ts

@@ -148,7 +148,7 @@ export type TraceEvent = {
      */
     tools?: ToolManifestRow[];
     totalChars: number;
-    /** design/148 S3 (additive, §10.2): the nine-element cache identity — digests only. */
+    /** design/148 S3 (additive, §10.2): the eight-element cache identity — digests only. */
     snapshot?: {
         cacheIdentity: string;
         elements: import("../prompt-assembly/turn-snapshot.js").CacheIdentityElements;
@@ -226,7 +226,7 @@ export type TraceEvent = {
      * tier. Absent on every reasoning-capable resolution (old consumers see identical frames).
      */
     dropped?: true;
-    /** design/148 S3 (additive, §10.2): the nine-element cache identity — digests only. */
+    /** design/148 S3 (additive, §10.2): the eight-element cache identity — digests only. */
     snapshot?: {
         cacheIdentity: string;
         elements: Record<string, string>;

package/dist/core/types.d.ts

@@ -23,7 +23,7 @@ export { DECLARATION_PATH_RULES, NO_DECLARATION_PATH_RULES, dataKind, declaratio
 export type { TaskLimits } from "./task-limits.js";
 export type { TaskStatus, RemoteEnvFailureNote, EffectiveMemoryScopes, TaskResult, HumanReviewGateRow } from "./task-result.js";
 export type { TerminalCause, PausedCause } from "./terminal-cause.js";
-export type { TaskEventIdentity, BrainStatusPhase, BrainRetryErrClass, BrainStatus, ToolActivity, HumanInputSource, HumanInputDelivery, DelegationTaskType, TaskEvent, HumanInputEvent, HumanInputAttachment, CompactOutcome } from "./task-event.js";
+export type { TaskEventIdentity, BrainStatusPhase, BrainRetryErrClass, BrainStatus, ToolActivity, HumanInputSource, HumanInputDelivery, DelegationTaskType, TaskEvent, HumanInputEvent, HumanInputAttachment, CompactOutcome, ExtensionRequester } from "./task-event.js";
 export type { TaskStream } from "./task-stream.js";
 export type { WorkflowGovernanceBaseline, RuntimeCaps, AutoModeDenySource } from "./runtime-caps.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";

package/dist/core/user-attachment.d.ts

@@ -30,6 +30,7 @@ import { type ReminderDisclosureCounts } from "./reminder-disclosure.js";
 import { type AgentMessage } from "../internal/harness.js";
 import type { ReadEntry } from "../tools/fs/safety.js";
 import type { ContextWindowOverlay } from "./context-settings.js";
+import { type LegModBus } from "./mods/stations.js";
 /** At most this many attachments on one objective. */
 export declare const USER_ATTACHMENTS_MAX = 20;
 /** The longest path or name an entry may carry (the platform path limit). */
@@ -148,6 +149,12 @@ export interface ReadUserAttachmentsInput {
     mark: string | undefined;
     counts: ReminderDisclosureCounts | undefined;
     signal: AbortSignal;
+    /** The leg's bus, where `prompt.mention` is raised for each attachment (absent ⇒ none is raised), and the delegated
+     *  leg's id its events carry. */
+    mentions?: {
+        readonly bus: LegModBus;
+        readonly agentId?: string;
+    };
 }
 /**
  * Read every declared attachment and mint its frame. Side-effect free toward the run: nothing is committed here — each
@@ -165,7 +172,7 @@ export interface AttachmentWindowInput {
 /** The objective lane's read: once the UserPromptSubmit hook let the objective through (a blocked objective reads
  *  nothing), and before the pre-call gate, which prices the frames (`chars`). Refuses the whole objective when the frames
  *  and the objective cannot ride one request ({@link refuseFramesOverWindow}). Commits nothing. */
-export declare function readObjectiveAttachments(prepared: Pick<import("./runner/contracts.js").Prepared, "userAttachments" | "modelFileReader" | "syntheticReadVerdict" | "cwdRef" | "reminderMark" | "reminderDisclosureCounts" | "abortController" | "harness">, inputId: string, blocked: boolean, window: AttachmentWindowInput): Promise<{
+export declare function readObjectiveAttachments(prepared: Pick<import("./runner/contracts.js").Prepared, "userAttachments" | "modelFileReader" | "syntheticReadVerdict" | "cwdRef" | "reminderMark" | "reminderDisclosureCounts" | "abortController" | "harness" | "modBus" | "hookIdentity">, inputId: string, blocked: boolean, window: AttachmentWindowInput): Promise<{
     frames: MintedAttachmentFrame[];
     chars: number;
 }>;

package/dist/core/user-attachment.js

@@ -10,6 +10,8 @@ import { commitReminderDisclosureEffects, planReminderDisclosure } from "./remin
 import { DEFAULT_CHARS_PER_TOKEN, estimateTokens, uuidv7 } from "../internal/harness.js";
 import { thrownText } from "./thrown-value.js";
 import { guardBudget } from "./context-guard.js";
+import { agentIdOf, failedHandlerClause } from "./mods/stations.js";
+import { extensionWords } from "./untrusted-egress.js";
 export const USER_ATTACHMENTS_MAX = 20;
 export const USER_ATTACHMENT_LABEL_MAX = 4096;
 export const USER_ATTACHMENT_KINDS = Object.freeze(["text", "notebook", "image", "pdf", "directory", "client_text", "client_image"]);
@@ -142,9 +144,12 @@ export function refuseUserAttachmentPathsWithoutWorkspace(screened) {
         throw userAttachmentRefusal(memberRef(entryRef(i), "path"), "this run has no workspace (its hand tools are off), so the engine has no file to read — send the file's bytes as a `text` or `image` entry instead.");
 }
 export function userAttachmentDeclarations(screened) {
-    return screened.map((a, i) => a.supply === "path"
-        ? { ordinal: i + 1, supply: a.supply, path: a.path }
-        : { ordinal: i + 1, supply: a.supply, name: a.name, bytes: a.supply === "content_text" ? Buffer.byteLength(a.text, "utf8") : Buffer.from(a.data, "base64").byteLength });
+    return screened.map((a, i) => declarationOf(a, i + 1));
+}
+function declarationOf(a, ordinal) {
+    return a.supply === "path"
+        ? { ordinal, supply: a.supply, path: a.path }
+        : { ordinal, supply: a.supply, name: a.name, bytes: a.supply === "content_text" ? Buffer.byteLength(a.text, "utf8") : Buffer.from(a.data, "base64").byteLength };
 }
 export async function admitUserAttachmentImages(screened) {
     const out = new Map();
@@ -218,6 +223,8 @@ function noteSentence(note, origin) {
             return "The listing was cut short, so it is incomplete.";
         case "too_large_to_restore":
             return "The file was read before the conversation was summarized, but its contents are too large to include here. Use the Read tool if you need them.";
+        case "extension_declined":
+            return "An extension of this deployment did not let this attachment through, so its contents were not attached; what it said is stated above.";
     }
 }
 function disclosureSentence(v) {
@@ -290,13 +297,65 @@ export async function readUserAttachments(input) {
     const count = input.screened.length;
     const seat = disclosureSeatOf(input.reader, input.mark, input.counts);
     const frames = [];
+    const mentions = input.mentions !== undefined && input.mentions.bus.hasHandlers("prompt.mention") ? input.mentions : undefined;
     for (const [i, a] of input.screened.entries()) {
         const ordinal = i + 1;
-        const r = await readOne(a, ordinal, input);
+        const r = mentions !== undefined ? await readMentioned(a, ordinal, input, mentions) : await readOne(a, ordinal, input);
         frames.push(mintFrame(r, { inputId: input.inputId, ordinal, count, mark: input.mark, origin: "user" }, seat));
     }
     return frames;
 }
+const declineOf = (x) => isPlainObject(x) && Object.keys(x).length === 1 && ((typeof x["deny"] === "string" && x["deny"] !== "") || (Object.hasOwn(x, "type") && x["type"] === null))
+    ? typeof x["deny"] === "string" ? { reason: x["deny"] } : {}
+    : undefined;
+async function readMentioned(a, ordinal, input, mentions) {
+    const label = a.supply === "path" ? a.path : a.name;
+    const declined = (text) => ({ supply: a.supply, label, outcome: "not_attached", shape: "file", data: [{ type: "text", text }], notes: [{ kind: "extension_declined" }], unscanned: [label, text], truncated: false });
+    const window = a.supply === "path" && a.lines !== undefined ? { offset: a.lines.start, ...(a.lines.end !== undefined ? { limit: a.lines.end - a.lines.start + 1 } : {}) } : {};
+    const e = { mention: declarationOf(a, ordinal), ...(mentions.agentId !== undefined ? { agentId: mentions.agentId } : {}), ...(a.supply === "path" ? { path: a.path, ...window } : {}) };
+    const reads = new Map();
+    const bottom = async (handed) => {
+        const spelled = respelled(a, handed);
+        const read = typeof spelled === "string" ? declined(`Not attached: ${spelled}.`) : await readOne(spelled, ordinal, input);
+        const answer = Object.freeze({ type: read.outcome === "not_attached" ? null : (read.kind ?? null), outcome: read.outcome });
+        reads.set(answer, read);
+        return answer;
+    };
+    let outcome;
+    try {
+        outcome = await mentions.bus.dispatch("prompt.mention", e, {
+            bottom,
+            signal: input.signal,
+            checkAnswer: (x) => (typeof x === "object" && x !== null && reads.has(x)) || declineOf(x) !== undefined ? undefined : "prompt.mention takes next(e), { deny: <reason> } or { type: null } — an extension does not supply an attachment's contents",
+            ranks: { of: (x) => (typeof x === "object" && x !== null && reads.has(x) ? 0 : 1), top: 1 },
+        });
+    }
+    catch (err) {
+        outcome = { kind: "failed", registration: "engine", cause: "threw", reason: `could not raise the station: ${thrownText(err)}`, skipped: [] };
+    }
+    if (outcome.kind === "aborted")
+        return declined("Not attached: the run was cancelled while an extension was judging it.");
+    if (outcome.kind === "failed")
+        return declined(`Not attached: a prompt.mention extension ${failedHandlerClause(outcome)}.`);
+    const read = typeof outcome.answer === "object" && outcome.answer !== null ? reads.get(outcome.answer) : undefined;
+    if (read !== undefined)
+        return read;
+    const reason = declineOf(outcome.answer)?.reason;
+    return declined(`Not attached: extension "${extensionWords(outcome.answeredBy ?? "engine", 80)}" declined it${reason !== undefined ? `: ${extensionWords(reason, 300)}` : ""}.`);
+}
+function respelled(a, handed) {
+    if (a.supply !== "path") {
+        return ["path", "offset", "limit"].some((k) => Object.hasOwn(handed, k)) ? "an extension handed down a path or line window for an attachment the host supplied (its bytes are its own; nothing is read)" : a;
+    }
+    const { path, offset, limit } = handed;
+    const line = (v) => v === undefined || (typeof v === "number" && Number.isInteger(v) && v >= 1);
+    if (typeof path !== "string" || path === "" || path.length > USER_ATTACHMENT_LABEL_MAX)
+        return "an extension handed down a path that is not one";
+    if (!line(offset) || !line(limit))
+        return "an extension handed down a line window that is not one (offset and limit are whole numbers from 1)";
+    const start = typeof offset === "number" ? offset : typeof limit === "number" ? 1 : undefined;
+    return start === undefined ? { supply: "path", path } : { supply: "path", path, lines: { start, ...(typeof limit === "number" ? { end: start + limit - 1 } : {}) } };
+}
 const refusalData = (r) => {
     const c = r.refusal?.content;
     return typeof c === "string" && c.length > 0 ? [{ type: "text", text: c }] : [];
@@ -439,6 +498,7 @@ export async function readObjectiveAttachments(prepared, inputId, blocked, windo
         mark: prepared.reminderMark,
         counts: prepared.reminderDisclosureCounts,
         signal: prepared.abortController.signal,
+        mentions: { bus: prepared.modBus, ...(agentIdOf(prepared.hookIdentity) !== undefined ? { agentId: agentIdOf(prepared.hookIdentity) } : {}) },
     });
     refuseFramesOverWindow(frames, prepared.harness.getModel(), window);
     return { frames, chars: frames.reduce((n, f) => n + f.seed.content.reduce((m, b) => m + (b.type === "text" ? b.text.length : 0), 0), 0) };

package/dist/core/wiring-manifest.d.ts

@@ -496,6 +496,13 @@ export interface WiringManifest {
     sessionRules?: {
         childrenReadLive: boolean;
     };
+    /**
+     * EFFECTIVE half only; present ⇔ the deployment declared a host floor (`RunnerDeps.hostFloor`): its POSTURE — whether an `only` list
+     * bounds what is reachable (`onlyMode`; `onlyCount: 0` with it = no structured egress at all) and how many entries each list holds.
+     * Deliberately not the entries' text (deployment-supplied hosts, the {@link WiringManifest.readDeny} class). IN the fingerprint: the
+     * declaration is the deployment's, so legs of one assembly agree.
+     */
+    hostFloor?: import("./host-floor.js").HostFloorPosture;
     /**
      * EFFECTIVE half only — the advisor tool on this leg, as the leg STARTED (a snapshot: a switch-off that lands later in the
      * leg is not in it; a host reads the conversation's current state off the transcript, `advisorHoldOf`). Present ⇔ the leg's
@@ -612,6 +619,8 @@ export interface WiringFacts {
     sessionRulesChildrenReadLive?: boolean;
     /** Effective half only — the advisor phase's answer ({@link WiringManifest.advisor}), relayed, never re-derived. */
     advisor?: WiringAdvisorFact;
+    /** Effective half only — the compiled host floor's posture ({@link WiringManifest.hostFloor}); absent ⇒ none declared. */
+    hostFloor?: import("./host-floor.js").HostFloorPosture;
 }
 /** {@link WiringManifest.advisor}. */
 export interface WiringAdvisorFact {

package/dist/core/wiring-manifest.js

@@ -228,6 +228,7 @@ export function deriveWiringManifest(facts) {
         ...(facts.half === "effective" && facts.projectMemory !== undefined ? { projectMemory: readWordFact(facts.projectMemory, ["on", "disabled", "absent"], "project-memory") } : {}),
         ...(facts.half === "effective" && facts.sessionRulesChildrenReadLive !== undefined ? { sessionRules: readSessionRulesFact(facts.sessionRulesChildrenReadLive) } : {}),
         ...(facts.half === "effective" && facts.advisor !== undefined ? { advisor: { ...facts.advisor, ...(facts.advisor.hold !== undefined ? { hold: { ...facts.advisor.hold } } : {}) } } : {}),
+        ...(facts.half === "effective" && facts.hostFloor !== undefined ? { hostFloor: { onlyMode: facts.hostFloor.onlyMode, denyCount: facts.hostFloor.denyCount, onlyCount: facts.hostFloor.onlyCount } } : {}),
         ...(facts.half === "effective" && facts.teamRole !== undefined ? { teamRole: facts.teamRole } : {}),
         ...(facts.half === "effective" && facts.peerPresence !== undefined && (facts.peerPresence.agent !== undefined || facts.peerPresence.intent !== undefined)
             ? { peerPresence: { ...(facts.peerPresence.agent !== undefined ? { agent: facts.peerPresence.agent } : {}), ...(facts.peerPresence.intent !== undefined ? { intent: facts.peerPresence.intent } : {}) } }

package/dist/core/workflow-journal-store.js

@@ -102,7 +102,7 @@ export function journalOversizeTombstone(result, bytes) {
         taskId: result.taskId,
         sessionId: result.sessionId,
         terminal: { kind: "failed", code: JOURNAL_OVERSIZE_ERROR_CODE, message },
-        result: message,
+        result: message, resultEntryIds: [],
         stats: result.stats,
     };
 }