@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/rule-owner.js

@@ -0,0 +1,29 @@
+import { isPlainRecord } from "./mods/kernel/receive.js";
+import { principalNameOf } from "./principal-name.js";
+export const RULE_OWNER_KINDS = Object.freeze(["principal", "local-owner"]);
+export function sameRuleOwner(a, b) {
+    return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
+}
+export function readRuleOwner(raw) {
+    if (!isPlainRecord(raw))
+        return undefined;
+    const kind = raw.kind;
+    const word = RULE_OWNER_KINDS.find((k) => k === kind);
+    if (word === undefined)
+        return undefined;
+    switch (word) {
+        case "local-owner":
+            return { kind: "local-owner" };
+        case "principal": {
+            const principal = principalNameOf(raw.principal);
+            return principal === undefined ? undefined : { kind: "principal", principal };
+        }
+        default: {
+            const unhandled = word;
+            return unhandled;
+        }
+    }
+}
+export function ruleOwnerText(owner) {
+    return owner.kind === "principal" ? `principal "${owner.principal}"` : "the local owner";
+}

package/dist/core/runner/advisor-instructions.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The advisor tool's instructions to the model — the reference's text, verbatim — its two short forms (a re-attach after a
+ * withdrawal, and the withdrawal), the one transition that says which a leg owes, and the leg's seat for them. The frame is
+ * the `advisor_tool` attachment kind: it rides a fresh leg's first request, and a compaction inside a leg that mounts the
+ * tool restates the full text right after it lands. Model lane only: no `steering_injected` echo.
+ */
+import type { AnnouncedAdvisorState, AnnouncedListingSnapshotInput } from "../../internal/harness.js";
+import type { PostureFrameRef } from "../auto-mode-directive.js";
+import type { StoredSession } from "../session.js";
+import type { FrameReceiptLedger } from "./contracts.js";
+export declare const ADVISOR_TOOL_INSTRUCTIONS = "# Advisor Tool\n\nYou have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters -- when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.\n\nCall advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.\n\nAlso call advisor:\n- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.\n- When stuck -- errors recurring, approach not converging, results that don't fit.\n- When considering a change of approach.\n\nOn tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.\n\nGive the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.\n\nIf you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- \"I found X, you suggest Y, which constraint breaks the tie?\" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.";
+export declare const ADVISOR_TOOL_ABBREVIATED = "The advisor tool is available; the advisor instructions announced earlier apply.";
+export declare const ADVISOR_TOOL_REMOVED = "The advisor tool is no longer available; disregard the earlier advisor instructions.";
+/** What the model has been told about the advisor in the conversation's current segment (since the latest compaction): the session record's own word. */
+export type AdvisorInstructionState = AnnouncedAdvisorState["state"];
+/**
+ * The advisor instructions a leg owes, from what the model was told and whether the tool is mounted now: nothing told and
+ * mounted ⇒ the full text; told and not mounted ⇒ the withdrawal; withdrawn and mounted again ⇒ the short re-attach; every
+ * other pair owes nothing. `state` is what the model has been told once the frame is delivered.
+ */
+export declare function advisorInstructionFrame(told: AdvisorInstructionState | undefined, mounted: boolean): {
+    body: string;
+    state: AdvisorInstructionState;
+} | undefined;
+/** A leg's advisor-instructions seat: the frame its first request owes, the segment that was judged in, whether the tool is mounted. */
+export interface AdvisorInstructionSeat {
+    owed?: {
+        readonly body: string;
+        readonly state: AdvisorInstructionState;
+    };
+    readonly segment: string | null;
+    readonly mounted: boolean;
+}
+/** The owed frame as one engine-marked reminder — what a fresh leg's first message and a resumed leg's continuation both
+ *  carry — or `undefined` when nothing is owed. */
+export declare function advisorFrameText(prepared: {
+    readonly advisorInstruction?: AdvisorInstructionSeat;
+    readonly reminderMark: string;
+}): string | undefined;
+/** Register the owed frame's receipt on the message that carries it (`text`, the exact first text block): its commit
+ *  records what the model was told only once that message is in the transcript. Nothing owed ⇒ nothing registered. */
+export declare function registerAdvisorReceipt(prepared: {
+    readonly advisorInstruction?: AdvisorInstructionSeat;
+    readonly announcedListingsRef: AnnouncedListingSnapshotInput;
+    readonly frameReceipts: FrameReceiptLedger;
+}, text: string): void;
+/** The owed frame was delivered (its carrying message is in the transcript): what the model was told is recorded for the
+ *  segment it was told in, and the snapshot write is parked like every listing commit's. */
+export declare function settleAdvisorInstruction(prepared: {
+    readonly advisorInstruction?: AdvisorInstructionSeat;
+    readonly announcedListingsRef: AnnouncedListingSnapshotInput;
+    readonly frameReceipts: {
+        listingSnapshotOwed: boolean;
+    };
+}): void;
+/**
+ * A compaction landed on a leg that mounts the advisor: the full instructions it summarized away are appended to the
+ * transcript as one engine-minted message, before any reader of the new baseline — the posture's compaction rule, halt
+ * included (no engine message enters the transcript ahead of a person's next words). The record is left as it was: it names
+ * the segment before this compaction, so the next leg tells the model again (a duplicate, never a gap). Never throws.
+ */
+export declare function appendAdvisorRestate(prepared: {
+    readonly advisorInstruction?: AdvisorInstructionSeat;
+    readonly reminderMark: string;
+    readonly session: Pick<StoredSession, "appendMessage">;
+    readonly batchHaltRef: {
+        readonly current?: unknown;
+    };
+    readonly postureFrameRef: Pick<PostureFrameRef, "report">;
+}): Promise<void>;

package/dist/core/runner/advisor-instructions.js

@@ -0,0 +1,61 @@
+import { mintSystemReminder } from "../reminder-mint.js";
+import { thrownText } from "../thrown-value.js";
+export const ADVISOR_TOOL_INSTRUCTIONS = `# Advisor Tool
+
+You have access to an \`advisor\` tool backed by a stronger reviewer model. It takes NO parameters -- when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.
+
+Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
+
+Also call advisor:
+- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
+- When stuck -- errors recurring, approach not converging, results that don't fit.
+- When considering a change of approach.
+
+On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.
+
+Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.
+
+If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.`;
+export const ADVISOR_TOOL_ABBREVIATED = "The advisor tool is available; the advisor instructions announced earlier apply.";
+export const ADVISOR_TOOL_REMOVED = "The advisor tool is no longer available; disregard the earlier advisor instructions.";
+export function advisorInstructionFrame(told, mounted) {
+    if (mounted && told === undefined)
+        return { body: ADVISOR_TOOL_INSTRUCTIONS, state: "announced" };
+    if (mounted && told === "withdrawn")
+        return { body: ADVISOR_TOOL_ABBREVIATED, state: "announced" };
+    if (!mounted && told === "announced")
+        return { body: ADVISOR_TOOL_REMOVED, state: "withdrawn" };
+    return undefined;
+}
+export function advisorFrameText(prepared) {
+    const owed = prepared.advisorInstruction?.owed;
+    return owed === undefined ? undefined : mintSystemReminder(owed.body, prepared.reminderMark);
+}
+export function registerAdvisorReceipt(prepared, text) {
+    if (prepared.advisorInstruction?.owed !== undefined)
+        prepared.frameReceipts.pending.push({ source: "advisor_tool", text, commit: () => settleAdvisorInstruction(prepared) });
+}
+export function settleAdvisorInstruction(prepared) {
+    const seat = prepared.advisorInstruction;
+    const owed = seat?.owed;
+    if (seat === undefined || owed === undefined)
+        return;
+    seat.owed = undefined;
+    prepared.announcedListingsRef.advisor = { state: owed.state, segment: seat.segment };
+    prepared.frameReceipts.listingSnapshotOwed = true;
+}
+export async function appendAdvisorRestate(prepared) {
+    if (prepared.advisorInstruction?.mounted !== true || prepared.batchHaltRef.current !== undefined)
+        return;
+    const text = mintSystemReminder(ADVISOR_TOOL_INSTRUCTIONS, prepared.reminderMark);
+    try {
+        await prepared.session.appendMessage({ role: "user", content: [{ type: "text", text }], timestamp: Date.now(), engineMinted: true });
+    }
+    catch (err) {
+        try {
+            prepared.postureFrameRef.report?.(new Error(`the advisor instructions could not be restated after compaction (the next leg states them): ${thrownText(err)}`));
+        }
+        catch {
+        }
+    }
+}

package/dist/core/runner/advisor-tool.d.ts

@@ -0,0 +1,33 @@
+import type { AgentTool, SessionTreeEntry } from "../../internal/harness-types.js";
+import type { Model } from "../../internal/llm.js";
+import { type AdvisorFailure, type AdvisorOutcome } from "../advisor-verdict.js";
+import type { CompactionForkContext } from "../auto-compaction.js";
+import { type SideQueryResult } from "../side-query.js";
+import type { Brain, TaskSpec } from "../types.js";
+/** The advisor's own system prompt (the agent's system prompt follows it, marked as context). */
+export declare const ADVISOR_SYSTEM_PROMPT = "You are the advisor: a stronger reviewer model consulted by an agent in the middle of its task. Above is the agent's conversation as it stood in the agent's last request \u2014 its task, every tool call it made and every result it saw \u2014 ending at the point where it asked for advice.\n\nReply in plain text only. Do not call tools: any tool call you make is discarded and counts as no answer. Be concrete and short: name the decision the agent is facing, say what you would do and why, point at the specific evidence in the conversation that supports it, and flag anything the agent has assumed without checking. If the agent asked before declaring the task done, review the deliverable against the task as stated and list what is missing or wrong. If something you need is not in the conversation, say what is missing and what the agent should check first \u2014 that is still guidance.";
+/** The closing result the projection ends on: the asking call is answered, so both wire protocols take the list. */
+export declare const ADVISOR_HANDOFF = "You are the advisor now. Review everything above and reply with your guidance.";
+/** Everything one leg's advisor needs: the advisor model, the lane's accounted brain, and the leg's own readers. */
+export interface AdvisorSeat {
+    readonly model: Model;
+    readonly brain: Brain;
+    /** The request the main lane last sent on this leg (the engine-level context, before provider serialization). */
+    readonly lastSentRequest: () => CompactionForkContext | undefined;
+    readonly readBranch: () => Promise<ReadonlyArray<SessionTreeEntry>>;
+    readonly getApiKeyAndHeaders: TaskSpec["getApiKeyAndHeaders"];
+    /** Marks the run's totals a lower bound: a thrown request spent an amount nobody learned. */
+    readonly markUsageUnknown: () => void;
+}
+/** The `tool_end.structured` card of one advisor call. */
+export interface AdvisorCard extends AdvisorFailure {
+    readonly type: "advisor";
+    readonly outcome: AdvisorOutcome;
+    readonly model: string;
+    readonly servedModel?: string;
+    readonly stopReason?: string;
+    readonly hold?: true;
+    readonly usage?: SideQueryResult["usage"];
+}
+/** The leg's `advisor` tool over its seat; its label is the advisor model's id (it rides `tool_start` / `tool_end`). */
+export declare function createAdvisorTool(seat: AdvisorSeat): AgentTool;

package/dist/core/runner/advisor-tool.js

@@ -0,0 +1,112 @@
+import { Type } from "typebox";
+import { stripErrorCodePrefix, thrownBrainFailure } from "../../brain/errors.js";
+import { ADVISOR_TOOL_NAME, advisorFailureHolds, advisorHoldOf } from "../advisor-verdict.js";
+import { runSideQuery } from "../side-query.js";
+import { thrownText } from "../thrown-value.js";
+import { defineTool } from "../tools.js";
+import { mountRuleFace, toolFace } from "../tool-catalog-entries.js";
+import { egressText } from "../untrusted-egress.js";
+const ADVISOR_MESSAGE_MAX_CHARS = 2_000;
+export const ADVISOR_SYSTEM_PROMPT = `You are the advisor: a stronger reviewer model consulted by an agent in the middle of its task. Above is the agent's conversation as it stood in the agent's last request — its task, every tool call it made and every result it saw — ending at the point where it asked for advice.
+
+Reply in plain text only. Do not call tools: any tool call you make is discarded and counts as no answer. Be concrete and short: name the decision the agent is facing, say what you would do and why, point at the specific evidence in the conversation that supports it, and flag anything the agent has assumed without checking. If the agent asked before declaring the task done, review the deliverable against the task as stated and list what is missing or wrong. If something you need is not in the conversation, say what is missing and what the agent should check first — that is still guidance.`;
+export const ADVISOR_HANDOFF = "You are the advisor now. Review everything above and reply with your guidance.";
+const AGENT_INSTRUCTIONS_HEADER = "# The agent's instructions (context for you; they bind the agent, not you)";
+const HOLD_SENTENCE = "The advisor is off for this conversation until it is compacted; do not call it again before then.";
+function unavailable(model, failure, message, hold, extra = {}) {
+    const cause = failure.errorKind ?? failure.code ?? failure.stopReason;
+    const bounded = message !== undefined && message.trim() !== "" ? egressText("same-principal", message).slice(0, ADVISOR_MESSAGE_MAX_CHARS) : undefined;
+    const text = [`Advisor unavailable${cause !== undefined ? ` (${cause})` : ""}.`, ...(bounded !== undefined ? [bounded] : []), ...(hold ? [HOLD_SENTENCE] : [])].join(" ");
+    const card = {
+        type: "advisor",
+        outcome: "unavailable",
+        model: model.id,
+        ...extra,
+        ...(failure.stopReason !== undefined ? { stopReason: failure.stopReason } : {}),
+        ...(failure.code !== undefined ? { code: failure.code } : {}),
+        ...(failure.errorKind !== undefined ? { errorKind: failure.errorKind } : {}),
+        ...(hold ? { hold: true } : {}),
+    };
+    return { text, card };
+}
+function askingTurn(branch, toolCallId) {
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const e = branch[i];
+        if (e.type !== "message" || e.message.role !== "assistant")
+            continue;
+        const m = e.message;
+        if (!m.content.some((c) => c.type === "toolCall" && c.id === toolCallId))
+            continue;
+        return { ...m, content: m.content.filter((c) => c.type !== "toolCall" || c.id === toolCallId) };
+    }
+    return undefined;
+}
+function projection(sent, turn, toolCallId) {
+    const close = { role: "toolResult", toolCallId, toolName: ADVISOR_TOOL_NAME, content: [{ type: "text", text: ADVISOR_HANDOFF }], isError: false };
+    return [...sent.messages, turn, close];
+}
+function systemPromptOf(sent) {
+    const sentSystemText = sent.systemPrompt ?? sent.systemBlocks?.map((b) => b.text).join("") ?? "";
+    return sentSystemText === "" ? ADVISOR_SYSTEM_PROMPT : `${ADVISOR_SYSTEM_PROMPT}\n\n${AGENT_INSTRUCTIONS_HEADER}\n${sentSystemText}`;
+}
+function outcomeOf(model, r) {
+    const served = r.servedModel !== model.id ? { servedModel: r.servedModel } : {};
+    const base = { type: "advisor", model: model.id, ...served, stopReason: r.stopReason, usage: r.usage };
+    if ((r.stopReason === "stop" || r.stopReason === "length") && r.text.trim() !== "")
+        return { text: r.text, card: { ...base, outcome: "reviewed" } };
+    if (r.stopReason === "error" && r.errorCode === "refusal") {
+        const reason = r.errorMessage !== undefined ? stripErrorCodePrefix(r.errorMessage).trim() : "";
+        const bounded = reason !== "" ? egressText("same-principal", reason).slice(0, ADVISOR_MESSAGE_MAX_CHARS) : "";
+        return { text: `Advisor declined to advise on this request.${bounded !== "" ? ` Reason: ${bounded}` : ""}`, card: { ...base, outcome: "declined" } };
+    }
+    const failure = { ...(r.errorCode !== undefined ? { code: r.errorCode } : {}), ...(r.errorKind !== undefined ? { errorKind: r.errorKind } : {}), ...(r.inputTooLongRuledOut === true ? { inputTooLongRuledOut: true } : {}) };
+    const message = r.stopReason === "toolUse" ? "the advisor model answered with a tool call instead of guidance" : r.stopReason === "error" || r.stopReason === "aborted" ? (r.errorMessage !== undefined ? stripErrorCodePrefix(r.errorMessage) : undefined) : "the advisor model returned no guidance";
+    return unavailable(model, { ...failure, stopReason: r.stopReason }, message, advisorFailureHolds(failure), { ...served, usage: r.usage });
+}
+async function consult(seat, toolCallId, signal) {
+    const model = seat.model;
+    let branch;
+    try {
+        branch = await seat.readBranch();
+    }
+    catch {
+        return unavailable(model, {}, "the advisor's availability for this conversation could not be read; try again later", false);
+    }
+    const held = advisorHoldOf(branch);
+    if (held !== undefined)
+        return unavailable(model, held, undefined, true);
+    const sent = seat.lastSentRequest();
+    if (sent === undefined)
+        return unavailable(model, {}, "no request has been sent to the model on this resumed run yet; call advisor again", false);
+    const turn = askingTurn(branch, toolCallId) ?? { role: "assistant", content: [{ type: "toolCall", id: toolCallId, name: ADVISOR_TOOL_NAME, arguments: {} }] };
+    try {
+        const r = await runSideQuery({
+            model,
+            systemPrompt: systemPromptOf(sent),
+            messages: projection(sent, turn, toolCallId),
+            ...(sent.tools !== undefined && sent.tools.length > 0 ? { tools: sent.tools.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })) } : {}),
+            ...(signal !== undefined ? { signal } : {}),
+            ...(seat.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: seat.getApiKeyAndHeaders } : {}),
+        }, { brain: seat.brain });
+        return outcomeOf(model, r);
+    }
+    catch (e) {
+        seat.markUsageUnknown();
+        const failure = thrownBrainFailure(e);
+        return unavailable(model, { ...failure, stopReason: "error" }, stripErrorCodePrefix(thrownText(e)), advisorFailureHolds(failure));
+    }
+}
+export function createAdvisorTool(seat) {
+    return defineTool({
+        name: ADVISOR_TOOL_NAME,
+        ...toolFace("advisor"),
+        ruleFace: mountRuleFace("advisor"),
+        label: seat.model.id,
+        description: "Consult the advisor: a stronger reviewer model reads this conversation and returns guidance. Takes no parameters.",
+        parameters: Type.Object({}),
+        execute: async (_args, ctx) => {
+            const { text, card } = await consult(seat, ctx.toolCallId, ctx.signal);
+            return { content: text, details: card, isError: card.outcome === "unavailable" };
+        },
+    });
+}

package/dist/core/runner/announce-once-ledger.d.ts

@@ -1,6 +1,5 @@
 import type { AnnouncedListingSnapshot, AnnouncedListingSnapshotInput, AnnouncedMcpFailure } from "../../internal/harness.js";
-import type { SessionTreeEntry } from "../../internal/harness-types.js";
-import type { AnnounceOnceSink, DateAnchorRead } from "./contracts.js";
+import type { AnnounceOnceSink } from "./contracts.js";
 import type { McpDroppedTool, McpServerStatus } from "../mcp.js";
 import type { RunnerDeps } from "../types.js";
 /** Upper bound on the advisory-digest arm kept in the record (oldest dropped past it). A digest is
@@ -69,6 +68,20 @@ export declare function flushOwedAnnouncedSnapshot(prepared: {
     announcedListingsRef: AnnouncedListingSnapshotInput;
     session: Pick<AnnounceOnceSession, "appendAnnouncedListing">;
 }): Promise<void>;
+/**
+ * The one commit of a delivered `mcp_unavailable` frame — the receipt of the message that carried it (a leg's first request), run
+ * inside the `message_end` walk: the delivered pairs leave the pending list and join the session's told-failure record, whose
+ * snapshot write is parked for the next serialization point. The next prepare on the session announces only what the record lacks.
+ */
+export declare function settleMcpUnavailable(prepared: {
+    readonly mcpUnavailable?: {
+        pending: AnnouncedMcpFailure[];
+    };
+    readonly announcedListingsRef: AnnouncedListingSnapshotInput;
+    readonly frameReceipts: {
+        listingSnapshotOwed: boolean;
+    };
+}, delivered: ReadonlyArray<AnnouncedMcpFailure>): void;
 /** The run-local ledger — see the module header for the two commit disciplines it serves. */
 export interface AnnounceOnceLedger {
     /** The nearest announced snapshot on the branch as read at prepare (undefined = pre-entry
@@ -85,6 +98,9 @@ export interface AnnounceOnceLedger {
      *  the record is dropped; a new one is forwarded to `deps.onError` and recorded. With no sink wired
      *  nothing is recorded either — "announced" means delivered. Same signature as `RunnerDeps.onError`. */
     onError: NonNullable<RunnerDeps["onError"]>;
+    /** The record's one dedupe verb, for any announcement of a session fact: `deliver` runs unless `digest` is already in the
+     *  record, and the digest is recorded once it ran ({@link onError} is this verb over the operator sink). */
+    oncePerSession(digest: string, deliver: () => void): void;
     /** The operator-lane sink for a DEPLOYMENT fact (see {@link AnnounceOnceSink.onErrorOncePerRunner}): the same
      *  `(code, message)` digest, judged against what THIS RUNNER's sink has already been told rather than against
      *  the session's record. Writes no digest into the record and owes the transcript nothing. */
@@ -127,28 +143,4 @@ export declare function loadAnnounceOnceLedger(session: AnnounceOnceSession, che
  *  present-only arms, copied; `undefined` when nothing was announced on any face (the resume seed
  *  then falls to the lower rungs — unchanged contract). */
 export declare function serializeAnnouncedListings(ref: AnnouncedListingSnapshotInput): AnnouncedListingSnapshot | undefined;
-/** The custom-entry kind that carries the session's date anchor (engine-owned; never model-visible). */
-export declare const DATE_ANCHOR_CUSTOM_TYPE = "engine:date-anchor";
-/**
- * Read the session's date anchor off the active branch: the nearest anchor entry NEWER than the nearest
- * compaction, honored only when it was written for that same segment. An anchor written by a leg whose
- * prefix predates a compaction that landed in between therefore reads as absent — the one rule that makes a
- * compaction re-anchor the date. An unreadable branch returns undefined (the leg renders today, writes nothing).
- */
-export declare function readDateAnchor(session: {
-    getBranch(): Promise<ReadonlyArray<SessionTreeEntry>>;
-}): Promise<DateAnchorRead | undefined>;
-/**
- * The anchor write a leg owes when it settles, or undefined: owed when prepare found no anchor for the segment
- * (the leg rendered today) or the model has since been told a newer date; never after an unreadable branch.
- * Best-effort — a lost write costs one re-rendered prefix or one repeated reminder next leg, never a wrong date.
- */
-export declare function owedDateAnchor(session: {
-    appendCustomEntry(customType: string, data?: unknown): Promise<string>;
-}, seat: {
-    legDate: string;
-    anchor: DateAnchorRead | undefined;
-} | undefined, state: {
-    announcedDate: string;
-} | undefined): (() => Promise<void>) | undefined;
 export {};

package/dist/core/runner/announce-once-ledger.js

@@ -47,30 +47,37 @@ export async function flushOwedAnnouncedSnapshot(prepared) {
         return;
     await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
 }
+export function settleMcpUnavailable(prepared, delivered) {
+    prepared.mcpUnavailable?.pending.splice(0, delivered.length);
+    prepared.announcedListingsRef.mcpFailed = [...(prepared.announcedListingsRef.mcpFailed ?? []), ...delivered];
+    prepared.frameReceipts.listingSnapshotOwed = true;
+}
 export async function loadAnnounceOnceLedger(session, checkpointMirror, onError) {
     let recovered = true;
     const entry = await session.getAnnouncedListing().catch(() => {
         recovered = false;
         return undefined;
     });
-    const seed = checkpointMirror?.mcpFailed !== undefined || checkpointMirror?.advisories !== undefined ? checkpointMirror : entry;
+    const seed = checkpointMirror?.mcpFailed !== undefined || checkpointMirror?.advisories !== undefined || checkpointMirror?.advisor !== undefined ? checkpointMirror : entry;
     const listingSrc = checkpointMirror?.agents !== undefined || checkpointMirror?.skills !== undefined || checkpointMirror?.models !== undefined ? checkpointMirror : entry;
     let mcpFailed = (seed?.mcpFailed ?? []).map((f) => ({ ...f }));
     const advisories = new Set(seed?.advisories ?? []);
     let dirty = false;
+    const oncePerSession = (digest, deliver) => {
+        if (advisories.has(digest))
+            return;
+        deliver();
+        advisories.add(digest);
+        dirty = true;
+    };
     return {
         entry,
         recovered,
         onError: (err, ctx) => {
-            if (onError === undefined)
-                return;
-            const digest = warningDigest(err);
-            if (advisories.has(digest))
-                return;
-            onError(err, ctx);
-            advisories.add(digest);
-            dirty = true;
+            if (onError !== undefined)
+                oncePerSession(warningDigest(err), () => onError(err, ctx));
         },
+        oncePerSession,
         onErrorOncePerRunner: (err, ctx) => {
             if (onError === undefined)
                 return;
@@ -106,6 +113,7 @@ export async function loadAnnounceOnceLedger(session, checkpointMirror, onError)
             ...(listingSrc?.models !== undefined ? { models: [...listingSrc.models] } : {}),
             ...(mcpFailed.length > 0 ? { mcpFailed: mcpFailed.map((f) => ({ ...f })) } : {}),
             ...(advisories.size > 0 ? { advisories: withAnnounceDigests(undefined, [...advisories]) } : {}),
+            ...(seed?.advisor !== undefined ? { advisor: { ...seed.advisor } } : {}),
         }),
         settle: async (s, ref) => {
             if (advisories.size > 0)
@@ -119,6 +127,7 @@ export async function loadAnnounceOnceLedger(session, checkpointMirror, onError)
                 ...(ref.models !== undefined ? { models: ref.models } : {}),
                 ...(ref.mcpFailed !== undefined && ref.mcpFailed.length > 0 ? { mcpFailed: ref.mcpFailed } : {}),
                 ...(ref.advisories !== undefined && ref.advisories.length > 0 ? { advisories: ref.advisories } : {}),
+                ...(ref.advisor !== undefined ? { advisor: ref.advisor } : {}),
             })
                 .catch(() => undefined);
         },
@@ -131,43 +140,7 @@ export function serializeAnnouncedListings(ref) {
         ...(ref.models !== undefined ? { models: [...ref.models] } : {}),
         ...(ref.mcpFailed !== undefined ? { mcpFailed: ref.mcpFailed.map((f) => ({ ...f })) } : {}),
         ...(ref.advisories !== undefined ? { advisories: [...ref.advisories] } : {}),
+        ...(ref.advisor !== undefined ? { advisor: { ...ref.advisor } } : {}),
     };
     return Object.keys(out).length > 0 ? out : undefined;
 }
-export const DATE_ANCHOR_CUSTOM_TYPE = "engine:date-anchor";
-const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
-function normalizeDateAnchor(v) {
-    if (typeof v !== "object" || v === null)
-        return undefined;
-    const { prefixDate, announcedDate, segment } = v;
-    if (typeof prefixDate !== "string" || !ISO_DATE.test(prefixDate) || typeof announcedDate !== "string" || !ISO_DATE.test(announcedDate))
-        return undefined;
-    if (segment !== null && (typeof segment !== "string" || segment.length > 200))
-        return undefined;
-    return { prefixDate, announcedDate, segment };
-}
-export async function readDateAnchor(session) {
-    let branch;
-    try {
-        branch = await session.getBranch();
-    }
-    catch {
-        return undefined;
-    }
-    let found;
-    let i = branch.length - 1;
-    for (; i >= 0 && branch[i].type !== "compaction"; i--) {
-        const e = branch[i];
-        if (found === undefined && e.type === "custom" && e.customType === DATE_ANCHOR_CUSTOM_TYPE)
-            found = normalizeDateAnchor(e.data);
-    }
-    const segment = i >= 0 ? branch[i].id : null;
-    return { current: found !== undefined && found.segment === segment ? { prefixDate: found.prefixDate, announcedDate: found.announcedDate } : undefined, segment };
-}
-export function owedDateAnchor(session, seat, state) {
-    const read = seat?.anchor;
-    if (read === undefined || state === undefined || read.current?.announcedDate === state.announcedDate)
-        return undefined;
-    const data = { prefixDate: seat.legDate, announcedDate: state.announcedDate, segment: read.segment };
-    return () => session.appendCustomEntry(DATE_ANCHOR_CUSTOM_TYPE, data).then(() => undefined, () => undefined);
-}

package/dist/core/runner/approval-feedback.js

@@ -9,16 +9,19 @@ export function refuseUnfitFeedback(twin) {
     if (words === undefined)
         return;
     if (twin.decision !== "allow") {
-        throw new CheckpointError("checkpoint.invalid_outcome", "resume carried `feedback` on a `deny` — feedback is the approving person's words on an `allow` (a denial's words are `reason`); refusing rather than dropping it silently, the checkpoint stays pending");
+        throw feedbackRefusal("resume carried `feedback` on a `deny` — feedback is the approving person's words on an `allow` (a denial's words are `reason`); refusing rather than dropping it silently, the checkpoint stays pending");
     }
     const byPerson = twin.hostDecision.decidedBy === "person";
     if (!byPerson) {
-        throw new CheckpointError("checkpoint.invalid_outcome", `resume carried \`feedback\` on a decide made by "${twin.hostDecision.decidedBy}" — feedback is delivered to the model as the user's own words, which only a person's decide can be; refusing rather than attributing a machine's text to the user, the checkpoint stays pending`);
+        throw feedbackRefusal(`resume carried \`feedback\` on a decide made by "${twin.hostDecision.decidedBy}" — feedback is delivered to the model as the user's own words, which only a person's decide can be; refusing rather than attributing a machine's text to the user, the checkpoint stays pending`);
     }
     if (sanitizeUntrustedText(words) !== words) {
-        throw new CheckpointError("checkpoint.invalid_outcome", sentinelTagRefusal("resume allow feedback"));
+        throw feedbackRefusal(sentinelTagRefusal("resume allow feedback"));
     }
 }
+function feedbackRefusal(message) {
+    return new CheckpointError("checkpoint.invalid_outcome", message, { field: "feedback" });
+}
 export function approvalWordsOf(outcome) {
     return outcome.gate === "policy_ask" && outcome.decision === "allow" ? writtenFeedback(outcome.feedback) : undefined;
 }

package/dist/core/runner/assemble-result.d.ts

@@ -67,7 +67,7 @@ export interface Stats {
      *  (so it can't be re-derived from `costMicroUsd` alone). The {@link costBreakdown.compactionMicroUsd}
      *  source. Run-loop internal — not a public `TaskResult.stats` field. */
     compactionMicroUsd?: number;
-    /** The permission classifier's and a mod's model-call cost (micro-USD), accumulated by `recordSideCallUsage`. Folded
+    /** The permission classifier's, a mod's and the advisor tool's model-call cost (micro-USD), accumulated by `recordSideCallUsage`. Folded
      *  into `costMicroUsd` like compaction, but it STAYS inside {@link costBreakdown.llmRootMicroUsd} (an "of which" line,
      *  not a partition member). Absent until a call is booked. Run-loop internal — the public figure is
      *  `costBreakdown.sideCallMicroUsd`. */
@@ -148,6 +148,7 @@ export interface ResultFlags {
      *  ended for its own reason first) leaves this empty: the original terminal stands and the seat is
      *  NOT signed (the settle lane mints `task.halt_unconsumed` for it). */
     haltConsumption?: HaltConsumption;
+    answerEntryIds?: readonly string[];
     /** Call ids of answered-but-never-collected questions, echoed on
      *  `TaskResult.strandedHumanAnswers`. Pure pass-through; empty/absent ⇒ the field is omitted. The
      *  optional `onError` alert is NOT the disclosure — this mandatory result face is. */

package/dist/core/runner/assemble-result.js

@@ -178,5 +178,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
     const stampHaltedByUser = haltConsumed(flags.haltConsumption);
-    return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, terminal, ...(flags.model !== undefined ? { model: flags.model } : {}), ...(responseModel !== undefined ? { responseModel } : {}), result: result.trim(), salvagedOutput, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.editedFiles !== undefined && flags.editedFiles.length > 0 ? { editedFiles: flags.editedFiles } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveWriteFace !== undefined ? { effectiveWriteFace: flags.effectiveWriteFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), ...(flags.compaction !== undefined ? { compaction: flags.compaction } : {}), stats: publicStats };
+    return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, terminal, ...(flags.model !== undefined ? { model: flags.model } : {}), ...(responseModel !== undefined ? { responseModel } : {}), result: result.trim(), ...(flags.answerEntryIds !== undefined ? { resultEntryIds: [...flags.answerEntryIds] } : {}), salvagedOutput, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.editedFiles !== undefined && flags.editedFiles.length > 0 ? { editedFiles: flags.editedFiles } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveWriteFace !== undefined ? { effectiveWriteFace: flags.effectiveWriteFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), ...(flags.compaction !== undefined ? { compaction: flags.compaction } : {}), stats: publicStats };
 }

package/dist/core/runner/call-hook-stations.d.ts

@@ -89,8 +89,9 @@ export interface ApprovedCallScreenInput {
  * the call (the decide is the upper bound; the screen can only narrow): a deny, a failed or cancelled screening, or a
  * refused answer refuses the call in the live gate's own sentences; an ask is the question the decide already answered —
  * unless it demands a person and the decide was the deployment's policy (the one predicate every resume station holds a
- * decide against); a rewrite is what executes when the decide carried none of its own (the person's bytes are the upper
- * bound); context rides the result. Undefined when no handler hangs on `classic.PreToolUse`.
+ * decide against); a rewrite comes back as the args — what executes when the decide carried no edit, a refusal of the edit
+ * when it did (a person's bytes are the ceiling, rewrite-rejudge.ts); context rides the result. Undefined when no handler hangs
+ * on `classic.PreToolUse`.
  */
 export declare function createApprovedCallScreen(input: ApprovedCallScreenInput): ApprovedCallScreen | undefined;
 /**

package/dist/core/runner/caller-roster.d.ts

@@ -12,7 +12,8 @@
  * (string and symbol keys — what the mount's spread carries) plus every ToolSpec member name read through an ordinary
  * property read (how the phases read a declaration — non-enumerable, inherited or Proxy-answered included), each read once;
  * every declaration value is deep-copied and frozen by the one copier. A primitive is immutable and stays as read. A
- * read that throws refuses the run at the snapshot. Whether the ToolSpec arm can build the entry ({@link specArmCanConstruct})
+ * read that throws refuses the run at the snapshot, and so does an entry that carries a retired ToolSpec member under any
+ * reading of the key ({@link refuseRetiredMember}: the entry is asked once, before any face is minted). Whether the ToolSpec arm can build the entry ({@link specArmCanConstruct})
  * is asked of the entry once, there, and recorded on its face ({@link specArmCanBuild}); the mount refuses an entry it
  * cannot build from that record, so an `execute` that grows on the caller's object later is never read. The mount calls a
  * spec face's `execute` with the caller's own object as `this` ({@link callerEntryOrigin}). A `defineTool` product's face is
@@ -32,6 +33,7 @@
 import type { AgentTool } from "../../internal/harness.js";
 import type { TaskSpec } from "../types.js";
 import type { ToolSpec } from "../tool-spec.js";
+import type { ToolDeclarationCode } from "../governance-codes.js";
 import { type ToolCtxEnricher } from "../tools.js";
 declare const ROSTER_FACE: unique symbol;
 /** A roster entry as the snapshot minted it. The brand is private to this module and {@link rosterFaceOf} is the only
@@ -56,10 +58,27 @@ export declare function callerEntryOrigin(entry: object): object;
 /** Can the mount's ToolSpec arm build this roster entry? Only the verdict recorded at the snapshot answers: an object that
  *  is no face of this snapshot, a primitive, a product's face, is not built from. */
 export declare function specArmCanBuild(entry: RosterFace): boolean;
+/** A roster entry claiming an engine contract its catalog did not mint for it — the id written by hand, on a spec or on a product — refused where the
+ *  declaration enters. */
+export declare function callerEngineContractProblem(face: RosterFace): {
+    code: ToolDeclarationCode;
+    message: string;
+} | undefined;
+/** The retired-key door for one roster entry, asked of the LIVE entry once, before any member is copied: the key is present
+ *  iff ordinary property lookup answers a defined value ({@link retiredKeyOf} — an own enumerable member, a non-enumerable
+ *  one, a prototype's getter, a Proxy's trap alike), and a present one refuses the run by name with the sentence and code
+ *  the factory gives the same key on a `defineTool` spec (`config.deps_retired_key`). A lookup that throws is an entry whose
+ *  members cannot be read, refused as such. No face is ever minted from an entry that carries a retired member, so no later
+ *  phase has a key table of its own to consult for one. Every live object that is about to become a face meets it first:
+ *  {@link rosterFaceOf} asks it of each entry, and the per-task agents rebuild asks it of the object `withAgents` returned
+ *  before the stamp copy-back spreads that object (a spread drops a prototype's and a non-enumerable member). A value that
+ *  is no object holds no member. */
+export declare function refuseRetiredMember(entry: unknown, index: number): void;
 /** One entry of the roster, and the ONLY place a {@link RosterFace} is minted. Every object entry (a function included) becomes a frozen face, so no entry the snapshot holds is a
  *  live object: a primitive is immutable and stays as read; a `defineTool` product's face names the product for its sealed
  *  rebind; an entry the ToolSpec arm cannot build gets a face too, and the mount refuses it from the verdict recorded here —
- *  an `execute` or a mark that grows on the caller's object afterwards is never read. A read that throws refuses the run. */
+ *  an `execute` or a mark that grows on the caller's object afterwards is never read. An entry carrying a retired member is
+ *  refused first ({@link refuseRetiredMember}). A read that throws refuses the run. */
 export declare function rosterFaceOf(t: unknown, index: number): RosterFace;
 /** The mount's arm for a roster entry that is the face of a `defineTool` product: the exact product object is rebound to
  *  the run's ctx through the factory's sealed seat, compared with its face ({@link refuseProductDrift}), and the tool the