@sema-agent/core 7.54.1 → 7.56.0

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

@@ -9,13 +9,13 @@
  */
 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";
 import type { BackgroundChildEvent } from "./delegation-frames.js";
 import type { ModelRef } from "./model-seat.js";
-import type { ToolFamily, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
+import type { ToolFamily, ToolHostTarget, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
 /**
  * Side-effect class of a tool. Used by wake/resume reconciliation: when a call was interrupted
  * before its result was recorded, the outcome is unknown, so core must decide whether re-doing it
@@ -62,12 +62,17 @@ export interface ReversibilityVerdict {
      * TIGHTENING (one more question survives one more configuration), so an over-claiming probe costs
      * its own deployment a re-confirmation and can never turn an ask into an allow.
      *
-     * The built-in shell probe sets it for exactly one family: a listed reader naming a path outside the
-     * session's allowed directories. That demotion HAS a clearing channel — widening the declared read
-     * directories retires it — and where the probe can name the directory, {@link readRootCandidate} carries
-     * it. A mandated ask WITHOUT that member has no configuration behind it: the rest of the family (an
-     * operator `shellGate:"always"`, the tool's egress/irreversibility marks, an org demand, an out-of-root
-     * arm with no named directory) is confirm-or-refuse, and must not be worded as though a grant answers it.
+     * The engine's own shell station raises a mandate for a path outside the session's allowed directories
+     * (read or written) and for a command whose reads it could not establish. A demotion by a path outside the
+     * directories HAS a clearing channel — widening the declared read directories retires it — and where the
+     * probe can name the directory, {@link readRootCandidate} carries it. A mandated ask WITHOUT that member has
+     * no configuration behind it: the rest of the family (an operator `shellGate:"always"`, the tool's
+     * egress/irreversibility marks, an org demand, an out-of-root arm with no named directory) is
+     * confirm-or-refuse, and must not be worded as though a grant answers it.
+     *
+     * WHY a matching allow rule did not clear the ask is said in the account of the finding and nowhere else:
+     * the card's disclosure sentence is {@link ReversibilityVerdict.reason} verbatim (the station's own sentence, for its findings).
+     * A mandated verdict with no `reason` is stated without one — the card names the outranked rule and stops.
      */
     mandated?: boolean;
     /**
@@ -143,21 +148,22 @@ 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}. CC 2.1.212
-     * 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`.
-     *
-     * ⚠️ Currently INERT (design/71 liveness sweep, 2026-06-12): mapped onto the tool object but no
-     * runtime path or emitted event reads it — the model and TaskStream consumers only ever see
-     * `name`. Kept for API stability; wire it into tool events or drop it before building on it.
+     * 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
+     * model's id. The model only ever sees `name`.
      */
     label?: string;
     /**
@@ -240,7 +246,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * gate station: PreToolUse hooks, policy, the auto-mode classifier), AFTER schema validation. A
      * refusal (`{ ok: false, message }`) is returned to the model as a typed error result and NO
      * approval card is shown for the call; `{ ok: true }` / `undefined` lets the call proceed to the
-     * gate unchanged. Upstream form (CC 2.1.250 `validateInput` → `{result:false, message, errorCode}`,
+     * gate unchanged. Upstream form (`validateInput` → `{result:false, message, errorCode}`,
      * consulted ahead of the permission prompt): a call the tool would refuse on its own precondition —
      * an Edit/Write/NotebookEdit whose target file was never Read this session — used to reach the
      * operator as a card that could only ever fail; the model then retried the same failing call under
@@ -425,7 +431,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
     contentOrigin?: ToolContentOrigin;
     /**
      * Batch execution mode (design/64 §1 P1, CC reads-parallel/writes-sequential partition). When omitted,
-     * `defineTool` derives it FAIL-CLOSED from `effect` (CC 2.1.206 `TOOL_DEFAULTS.isConcurrencySafe → false`):
+     * `defineTool` derives it FAIL-CLOSED from `effect` (`TOOL_DEFAULTS.isConcurrencySafe → false`):
      * `read` → `"parallel"`; `write`/`idempotent`/UNDECLARED → `"sequential"` — an unannotated tool never
      * silently rides a parallel batch, and two writes in one batch never race. Set explicitly to override.
      */
@@ -435,7 +441,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * refinement for a non-`"parallel"` tool — return `true` to let THIS CALL run in a parallel batch
      * (and, under `streamingToolExecution`, start in-stream). An explicit `executionMode:"parallel"`
      * needs no refinement (always safe); a throw = false (fail-closed). In the batch/stream paths the
-     * hook receives schema-VALIDATED (coerced) args — CC 206 `parsed.data` parity; a schema-invalid
+     * hook receives schema-VALIDATED (coerced) args — `parsed.data` parity; a schema-invalid
      * call is judged unsafe before the hook runs. Still treat defensively (direct callers may pass raw).
      * The one real consumer is Bash's read-only classifier.
      */
@@ -475,7 +481,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      */
     defer?: boolean;
     /**
-     * Inline-keep override, judged FIRST in the deferral chain (CC 220 counterpart:
+     * Inline-keep override, judged FIRST in the deferral chain (the reference's counterpart:
      * `alwaysLoad`, declared per MCP tool via `_meta["anthropic/alwaysLoad"]`, whose `isDeferredTool`
      * checks it before every deferral arm): `true` pins this tool's full schema inline in every
      * request — it is never deferred, regardless of its own {@link defer}, {@link TaskSpec.deferTools},
@@ -508,7 +514,9 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * CONTRACT this tool implements, independent of its presentation text. `defineTool` attaches it
      * to the materialized tool via the catalog side-table (identity follows the OBJECT, never the
      * wire name — a caller tool shadowing a built-in name never inherits the core contract). Omitted
-     * ⇒ the tool reports a deterministic `legacy:<shapeDigest>` contract in the assembly manifest.
+     * ⇒ the tool reports a deterministic `legacy:<shapeDigest>` contract in the assembly manifest. A `core.`
+     * id is the engine's: on a `TaskSpec.tools` spec it is refused (`config.tool_face_invalid`) unless it rides
+     * the contract object the engine's catalog minted (an engine definition mounted by hand) — never written by hand.
      */
     contract?: {
         /** Stable versioned id, e.g. `core.read@2` (built-ins) or `acme.deploy@1` (caller tools). */
@@ -548,6 +556,15 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * tool that merely takes a built-in's NAME inherits nothing).
      */
     pathTarget?: ToolPathTarget;
+    /**
+     * The parameter that names the URL this tool's call reaches ({@link ToolHostTarget}), for a tool whose own name host rules are
+     * written for (the engine's fetch tool name, `WebFetch`). Host rules on that name are then judged on the host this URL names:
+     * a deny or an ask reaches the tool whatever it declares (the catalog's slot is the protective floor), an allow only when it
+     * declares its own slot here (a tool that merely takes the name inherits nothing). Refused (`config.tool_face_invalid`) on a
+     * tool under any other name, an alias included — a host rule's grammar belongs to the rule's tool name, so the slot would never
+     * be read — and together with {@link pathTarget} (a face names one protected target). The `param` must be a top-level property.
+     */
+    hostTarget?: ToolHostTarget;
     /**
      * design/388 §2.2 ③ — the parameter vocabulary a permission rule (`Tool(param:pattern)`) may name.
      * DERIVED from the schema when absent (the scalar top-level parameters plus the path target's
@@ -590,7 +607,7 @@ export type ToolReturn = string | {
      *  Producer side of the tool-result 双面契约: `content` is the MODEL face (may carry model-directed
      *  framing/trailers), `details` is the HOST face (per-tool structured Output). Hosts render from the
      *  structured face and never re-parse the model face — see the `tool_end.structured` JSDoc
-     *  (CC 2.1.207 @765495, CC207-CORE-SWEEP P2-3) for the full contract. */
+     *  (P2-3) for the full contract. */
     details?: unknown;
     /** Hint the agent to stop after this tool batch. */
     terminate?: boolean;
@@ -802,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
@@ -1054,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
@@ -1200,7 +1222,7 @@ export interface ToolExecuteContext {
         sessionId: string;
     } | undefined;
     /**
-     * RB-201 FO-3 (form-one audit, CC 220 `Ipd`/`ein` parity) — the auto-mode classifier decider ARMED
+     * RB-201 FO-3 (form-one audit) — the auto-mode classifier decider ARMED
      * for THIS task (auto-mode intent ∧ `RunnerDeps.autoMode` present ∧ `RuntimeCaps.autoMode !== false`
      * — see {@link TaskSpec.permissionMode}; the same
      * instance `runToolGate`'s per-call ask review already consults, carrying its own live breaker
@@ -1342,7 +1364,7 @@ export interface ToolExecuteContext {
      */
     insideFork?: boolean;
     /**
-     * OBS-2 (CC 2.1.206 observer parity) — present iff this run's principal resolved
+     * OBS-2 — present iff this run's principal resolved
      * {@link RuntimeCaps.allowObservers}` === true` (EXPLICIT opt-in, default OFF — see the polarity
      * note there). The delegation tool honors {@link AgentDefinition.observer} declarations only under
      * this flag; absent ⇒ declarations resolve to unobserved with NO warn (the gate, not a mistake).

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 } 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,
@@ -98,6 +137,7 @@ function buildProduct(spec, owner, options) {
         ...(spec.boundaryLegs !== undefined ? { boundaryLegs: spec.boundaryLegs } : {}),
         ...(spec.boundaryLegsFor !== undefined ? { boundaryLegsFor: spec.boundaryLegsFor } : {}),
         ...(spec.pathTarget !== undefined ? { pathTarget: spec.pathTarget } : {}),
+        ...(spec.hostTarget !== undefined ? { hostTarget: spec.hostTarget } : {}),
         ...(spec.ruleFace !== undefined ? { ruleFace: spec.ruleFace } : {}),
         ...(spec.renderHints !== undefined ? { renderHints: spec.renderHints } : {}),
         ...(spec.compactable === true ? { compactable: true } : {}),
@@ -120,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;
@@ -128,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");
@@ -140,10 +180,11 @@ 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: spec.contract.contractId.startsWith("core.") ? "core" : "caller",
+            origin: contractOriginOf(spec.contract.contractId),
             ...(spec.aliases && spec.aliases.length > 0 ? { aliases: spec.aliases } : {}),
         });
     }

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>;
@@ -339,6 +339,10 @@ export type TraceEvent = {
      * by them.
      */
     turn?: number;
+    /** Which call beside the loop this row is: a `SideCallLane` word (the closed set lives with the account,
+     *  `runner/side-call-account.ts`). Present exactly when {@link turn} is absent — the one writer of side-call rows
+     *  stamps it; a main-loop row carries `turn` and no `lane`. */
+    lane?: string;
     /** Normalized prompt tokens that MISSED the cache (Anthropic-protocol `input_tokens`
      *  shape) — disjoint from `cacheRead`/`cacheWrite`. Carried the cache-inclusive total up to 2.13.x. */
     promptTokens: number;

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/untrusted-egress.d.ts

@@ -9,7 +9,7 @@ export { summarizeRedactions } from "./redaction-passes.js";
  * that tier. What a tool RETURNS is its content, read by the model that asked for it, and is not redacted (CC redacts
  * nothing there either); what is redacted is what the engine itself words or carries: errors, summaries, run rows.
  *
- * Two tiers, because the faces have two audiences (CC 2.1.212 alignment):
+ * Two tiers, because the faces have two audiences:
  *  - **`same-principal`** — the model, the script and the host that launched the work (tool results, workflow agent
  *    outputs / results / errors, run rows behind the scope-gated observe API, host error lanes): the credential
  *    vocabulary only. Paths and URLs in a worker's answer are the caller's OWN machine's paths — redacting them killed the

package/dist/core/untrusted-text.d.ts

@@ -138,7 +138,7 @@ export interface EnvelopeShapedScan {
 export declare function scanEnvelopeShaped(text: string): EnvelopeShapedScan;
 /**
  * Defuse a caller-declared occurrence of ONE specific envelope tag (opening AND closing) inside
- * content, CC `zZe` @8339092 verbatim: ``t.replace(new RegExp(`<(?=/?${e}(?:[>\\s/]|$))`, "gi"), "<\\")``.
+ * content, the reference's replacement: ``t.replace(new RegExp(`<(?=/?${e}(?:[>\\s/]|$))`, "gi"), "<\\")``.
  *
  * Homed here (beside {@link ENGINE_ENVELOPES}) rather than in the observer module that first needed
  * it: "escape one named envelope tag" is a containment primitive, and the registry's guard column

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/warm-resume.d.ts

@@ -5,7 +5,7 @@ import type { TaskResult, TaskSpec } from "./types.js";
  * session, then run a continuation on the fork. Fork-first is the safe path (design/114 §3.2):
  *  - **idempotent** — each call branches a FRESH session, so resuming twice can't corrupt the source's linear
  *    history (vs `runTask({sessionId})` reuse, which appends two divergent continuations onto one history);
- *  - **orphan-safe** — the fork drops an in-flight tool call (`settledForkOptions`), so a continuation of an agent
+ *  - **orphan-safe** — the fork drops an in-flight tool call (`settledForkOptions`, the judge a store's `fork` shares; a package-root export), so a continuation of an agent
  *    that died mid-tool-call gets a clean point rather than inheriting an `[INTERRUPTED]` orphan;
  *  - **fail-loud** — a missing source returns `null`; it NEVER silently starts a fresh EMPTY run the way
  *    `runTask({sessionId})` would via create-on-miss (the "looks warm, actually fresh" trap). Cross-restart /

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

@@ -472,6 +472,46 @@ export interface WiringManifest {
      * derivation, never a state. Out of {@link configFingerprint}: the request word is a per-task seat (`mods` reasoning).
      */
     fileHistory?: "on" | "disabled";
+    /**
+     * EFFECTIVE half only, ALWAYS present on an engine-minted effective manifest: did this leg read the deployment's project context, and if not,
+     * which half kept it out — one word per state. `"on"` — its prepare called `RunnerDeps.loadProjectMemory` (what the seam answered, content or
+     * nothing, is the deployment's). `"disabled"` — a seam is wired and the request turned it off (`TaskSpec.projectMemory: "disabled"`).
+     * `"absent"` — no seam is wired (the manifest's word for a seat nothing supplied, as `ask` / `question` spell it), whatever the request said.
+     * The member missing = an older mint or an external derivation, never a state. Out of {@link configFingerprint}: the request word is a
+     * per-task seat (`fileHistory` reasoning).
+     */
+    projectMemory?: "on" | "disabled" | "absent";
+    /**
+     * EFFECTIVE half only, ALWAYS present on an engine-minted effective manifest: are the legs THIS leg delegates (sync,
+     * background, forked, workflow, retained, resumed and observer-sidecar legs, at any depth) bound by a rule written to this
+     * leg's session AFTER they started. `childrenReadLive: true` ⇔ the leg enforces its own session-rule layer (a
+     * `sessionPolicyStore` is wired and the task carries a `sessionId`) and so hands that session's key on to the legs it
+     * delegates, each of which re-reads the row at every tool gate: a rule written mid-run binds the agent's next call, whether
+     * or not the session had a row when the agent was spawned. `false` ⇒ no layer, so no key is handed on (no store wired, or
+     * the task names no session). ABSENT = an older engine: assume nothing. A statement about the DEPS-VISIBLE assembly — a
+     * delegation tool mounted over a Runner with no store of its own cannot re-read (it announces
+     * `config.session_rules_unreadable` and keeps the spawn-time snapshot). Leg-local (excluded from {@link configFingerprint}:
+     * `sessionId` is a per-task seat); the leg-start snapshot, like the rest of this object.
+     */
+    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
+     * spec names an advisor model. `requested` = the ref as given (a Model's `id`; absent when the deployment switch ignored it
+     * unread); `main` = the leg's resolved model; `state` `on` (with `model`, the resolved advisor), `held` (the conversation
+     * switched it off; `hold` = the cause) or `not_attached` (`reason`; `routeCode` on `route_refused`). Out of
+     * {@link configFingerprint}: a per-task seat.
+     */
+    advisor?: WiringAdvisorFact;
     /** EFFECTIVE half only — a short, non-sensitive fingerprint (sha256 prefix over the canonical
      *  JSON of this manifest's own resolved facts; every field here is an enum/boolean/count, no
      *  secrets) so an operator can correlate legs that ran under the same resolved assembly. */
@@ -573,6 +613,24 @@ export interface WiringFacts {
     autoConsolidationOnRecommendation?: boolean;
     /** Effective half only — the file-history phase's word ({@link WiringManifest.fileHistory}); the engine always passes it. */
     fileHistory?: "on" | "disabled";
+    /** Effective half only — the project-context phase's word ({@link WiringManifest.projectMemory}); the engine always passes it. */
+    projectMemory?: WiringManifest["projectMemory"];
+    /** Effective half only — {@link WiringManifest.sessionRules}`.childrenReadLive`: this leg's session-rule layer published its key for its children's chain. Read off that wiring, never a constant. */
+    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 {
+    requested?: string;
+    main: string;
+    state: "on" | "not_attached" | "held";
+    model?: string;
+    reason?: import("./advisor-verdict.js").AdvisorNotAttachedReason;
+    routeCode?: import("../internal/llm.js").RouteRefusalCode;
+    hold?: import("./advisor-verdict.js").AdvisorHold;
 }
 /** Named view of the deps seats the static half reads (a `Pick` of the real {@link RunnerDeps} —
  *  single-source shapes, no parallel hand-copied interface). */