@sema-agent/core 2.1.0 → 2.3.0

package/dist/agents/observer.d.ts

@@ -68,6 +68,15 @@ export declare class ObserverDigestTap {
     finish(reason: string): void;
 }
 export type ObserverPairingState = "armed" | "denied" | "stopped" | "retired" | "blocked";
+export declare const OBSERVER_STOPPED_BY_USER_ERROR_NAME = "AgentStoppedByUserError";
+export declare const OBSERVER_RESUME_STATE_ERROR_NAME = "ResumeAgentStateError";
+export declare class ObserverStoppedByUserError extends Error {
+    constructor(message: string);
+}
+export declare class ObserverResumeStateError extends Error {
+    constructor(message: string);
+}
+export declare const OBSERVER_FRESH_START_NOTE = "[Note: your previous observation context was lost; this is a fresh start mid-task.]";
 export interface ObserverSpawner {
     spawnFirstRun(args: {
         framingPrompt: string;
@@ -76,6 +85,10 @@ export interface ObserverSpawner {
     deliver(args: {
         digest: string;
     }): Promise<void>;
+    restartFresh?(args: {
+        framingPrompt: string;
+        digest: string;
+    }): Promise<void>;
 }
 export declare class ObserverPairing {
     state: ObserverPairingState;
@@ -102,6 +115,7 @@ export declare class ObserverPairing {
     private safeOnError;
     drain(): Promise<void>;
     private pump;
+    private deliverBatch;
     retire(state: Exclude<ObserverPairingState, "armed">): void;
 }
 export declare function markObserverTaskId(taskId: string): void;

package/dist/agents/observer.js

@@ -209,6 +209,24 @@ export class ObserverDigestTap {
         this.safeFlush(slice);
     }
 }
+export const OBSERVER_STOPPED_BY_USER_ERROR_NAME = "AgentStoppedByUserError";
+export const OBSERVER_RESUME_STATE_ERROR_NAME = "ResumeAgentStateError";
+export class ObserverStoppedByUserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = OBSERVER_STOPPED_BY_USER_ERROR_NAME;
+    }
+}
+export class ObserverResumeStateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = OBSERVER_RESUME_STATE_ERROR_NAME;
+    }
+}
+function errorName(err) {
+    return err instanceof Error ? err.name : undefined;
+}
+export const OBSERVER_FRESH_START_NOTE = "[Note: your previous observation context was lost; this is a fresh start mid-task.]";
 export class ObserverPairing {
     state = "armed";
     observedEnvelopeName;
@@ -278,18 +296,22 @@ export class ObserverPairing {
                 const batch = this.buffer.splice(0, this.buffer.length);
                 try {
                     const digest = renderObserverDigestBatch(this, batch);
-                    if (!this.firstRunDone) {
-                        await this.spawner.spawnFirstRun({ framingPrompt: this.framingPrompt, digest });
-                        this.firstRunDone = true;
-                    }
-                    else {
-                        await this.spawner.deliver({ digest });
-                    }
+                    await this.deliverBatch(digest);
                 }
                 catch (err) {
-                    this.state = "stopped";
-                    this.buffer = [];
+                    if (errorName(err) === OBSERVER_STOPPED_BY_USER_ERROR_NAME) {
+                        this.state = "stopped";
+                        this.buffer = [];
+                        this.safeOnError(err);
+                        return;
+                    }
                     this.safeOnError(err);
+                    if (this.buffer.length > 0) {
+                        const strandedCount = this.buffer.length;
+                        this.buffer = [];
+                        this.safeOnError(new Error(`observer delivery: ${strandedCount} segment(s) enqueued mid-fault were stranded and dropped (never attempted) after: ${err instanceof Error ? err.message : String(err)}`));
+                    }
+                    return;
                 }
             }
         }
@@ -297,6 +319,33 @@ export class ObserverPairing {
             this.delivering = false;
         }
     }
+    async deliverBatch(digest) {
+        if (!this.firstRunDone) {
+            await this.spawner.spawnFirstRun({ framingPrompt: this.framingPrompt, digest });
+            this.firstRunDone = true;
+            return;
+        }
+        try {
+            await this.spawner.deliver({ digest });
+        }
+        catch (err) {
+            if (errorName(err) !== OBSERVER_RESUME_STATE_ERROR_NAME)
+                throw err;
+            const restart = this.spawner.restartFresh?.bind(this.spawner);
+            if (restart === undefined)
+                throw err;
+            try {
+                await restart({ framingPrompt: `${this.framingPrompt}\n\n${OBSERVER_FRESH_START_NOTE}`, digest });
+                this.firstRunDone = true;
+            }
+            catch (restartErr) {
+                this.firstRunDone = false;
+                throw restartErr instanceof Error
+                    ? new Error(`${restartErr.message} (after resume-state loss: ${err instanceof Error ? err.message : String(err)})`, { cause: restartErr })
+                    : restartErr;
+            }
+        }
+    }
     retire(state) {
         if (this.state !== "armed")
             return;

package/dist/agents/send-message-tool.js

@@ -37,6 +37,7 @@ export function createSendMessageTool(opts) {
         contract: { contractId: "core.send_message@1", implementationRevision: "1" },
         executionMode: "parallel",
         description: `Send a follow-up message to a previously spawned background agent. ` +
+            `Your plain text output is NOT visible to other agents — to communicate, you MUST call this tool. Messages addressed to you are delivered automatically; you don't check an inbox. ` +
             `'to' is the agent's name (set at spawn via Agent({name})) or its task_id (a…). A RUNNING agent receives the ` +
             `message at its next turn (queued — never interrupts its current work); a FINISHED agent resumes as a new ` +
             `background run with its full prior conversation preserved, so don't re-explain what it already knows. Names ` +
@@ -50,7 +51,7 @@ export function createSendMessageTool(opts) {
         parameters: Type.Object({
             to: Type.String({ description: 'Recipient: the agent\'s name, or its task_id (a…) returned by the Agent tool with run_in_background. "main" is reserved for the spawning conversation.' }),
             message: Type.String({ description: "The follow-up request. The agent continues from its full prior context." }),
-            summary: Type.Optional(Type.String({ maxLength: 200, description: "A short (3-5 word) description of the follow-up." })),
+            summary: Type.Optional(Type.String({ maxLength: 200, description: "A 5-10 word summary shown as a preview in the UI (required when message is a string)" })),
         }),
         execute: async (args, ctx) => {
             const a = args;
@@ -60,6 +61,28 @@ export function createSendMessageTool(opts) {
                 return { content: "Message not sent: 'to' was empty. Pass the agent's task_id (a…).", details: { error: "empty to" }, isError: true };
             if (!message)
                 return { content: "Message not sent: 'message' was empty.", details: { error: "empty message" }, isError: true };
+            if (to === "*") {
+                return {
+                    content: 'Message not sent: broadcast (to: "*") is no longer supported — send a message per recipient.',
+                    details: { error: "broadcast_unsupported", to },
+                    isError: true,
+                };
+            }
+            if (to.includes("@")) {
+                return {
+                    content: "Message not sent: to must be a bare teammate name — there is only one team per session.",
+                    details: { error: "qualified_name_unsupported", to },
+                    isError: true,
+                };
+            }
+            const summaryArg = typeof a.summary === "string" ? a.summary.trim() : "";
+            if (summaryArg === "") {
+                return {
+                    content: "Message not sent: summary is required when message is a string — pass a 5-10 word summary of the follow-up.",
+                    details: { error: "summary_required", to },
+                    isError: true,
+                };
+            }
             const senderId = ctx.taskId ?? opts.owner;
             if (senderId !== undefined && isObserverTaskId(senderId)) {
                 return { content: OBSERVER_SENDMESSAGE_SENDER_REFUSAL, details: { error: "observer_sender" }, isError: true };
@@ -89,6 +112,17 @@ export function createSendMessageTool(opts) {
                         details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeqGlobal },
                     };
                 }
+                const hasParent = ctx.parentTaskId !== undefined ||
+                    opts.uplink !== undefined ||
+                    opts.senderName !== undefined ||
+                    opts.siblingRetain !== undefined;
+                if (!hasParent) {
+                    return {
+                        content: `You are the main conversation — "main" addresses you. Send to a named agent instead.`,
+                        details: { error: "main_is_self", to },
+                        isError: true,
+                    };
+                }
                 return {
                     content: `Message not sent: "main" (the spawning conversation) is not a deliverable target here. ` +
                         `Your completion is reported to it automatically — finish your task and your final report will be relayed.`,
@@ -126,10 +160,10 @@ export function createSendMessageTool(opts) {
                 if (row.name === undefined || row.agentType === "fork")
                     return undefined;
                 const whoT3 = handle === to ? `agent ${handle}` : `agent "${to}" (${handle})`;
-                if (row.status === "killed") {
+                if (row.status === "killed" && row.stoppedBy === "user") {
                     return {
-                        content: `Message not sent: ${whoT3} was stopped${row.stoppedBy !== undefined ? ` (by ${row.stoppedBy})` : ""} — a stopped agent is not revived. Launch a new agent with the needed context instead.`,
-                        details: { error: "killed", to, ...(row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}) },
+                        content: `Message not sent: ${whoT3} was stopped by the user and was not resumed. Treat its work as cancelled; only start a new agent for it if the user explicitly asks.`,
+                        details: { error: "killed", to, stoppedBy: row.stoppedBy },
                         isError: true,
                     };
                 }
@@ -419,11 +453,13 @@ export function createSendMessageTool(opts) {
             }
             if (row.status === "killed") {
                 const by = opts.registry.getStopAttribution(targetId);
-                return {
-                    content: `Message not sent: ${who} was stopped${by ? ` (by ${by})` : ""} — a stopped agent is not resumable. Launch a new agent with the needed context instead.`,
-                    details: { error: "killed", to, ...(by !== undefined ? { stoppedBy: by } : {}) },
-                    isError: true,
-                };
+                if (by === "user") {
+                    return {
+                        content: `Message not sent: ${who} was stopped by the user and was not resumed. Treat its work as cancelled; only start a new agent for it if the user explicitly asks.`,
+                        details: { error: "killed", to, stoppedBy: by },
+                        isError: true,
+                    };
+                }
             }
             const runLedger = ctx.subagentRetain ?? opts.retain;
             const smLedgerSessionId = ctx.sessionId ?? opts.sessionId;
@@ -445,6 +481,13 @@ export function createSendMessageTool(opts) {
                     isError: true,
                 };
             }
+            if (ledger.get(resumeToolUseId)?.running === true) {
+                return {
+                    content: `Message not sent: ${who} (or a prior follow-up to it) is still running — wait for its completion notification.`,
+                    details: { error: "steering.still_running", to },
+                    isError: true,
+                };
+            }
             return await withTargetLane(targetLaneKey(access.scope, targetId), async () => {
                 const resume = createSubagentResume({
                     ledger,
@@ -470,7 +513,9 @@ export function createSendMessageTool(opts) {
                 const summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
                 const fromPrefix = ctx.parentTaskId !== undefined ? `(message from teammate "${opts.senderName ?? senderId ?? "unknown"}")\n` : "";
                 try {
-                    const marker = await resume(`${fromPrefix}${summary ? `[${summary}] ${message}` : message}`);
+                    const safeSummary = summary !== undefined ? escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, summary) : undefined;
+                    const safeMessage = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, message);
+                    const marker = await resume(`${fromPrefix}${safeSummary ? `[${safeSummary}] ${safeMessage}` : safeMessage}`);
                     return {
                         content: `Message sent — ${who} resumed in the background with its prior context intact (correlation marker [${marker}]).\n` +
                             `You will be notified automatically when it completes; its reply will carry [${marker}]. Continue with other work — do not poll.`,

package/dist/agents/subagent.d.ts

@@ -133,6 +133,7 @@ export declare function asyncLaunchedReceipt(p: {
     taskId: string;
     workingLine: string;
     notify: boolean;
+    oneShot?: boolean;
     notes?: (string | undefined)[];
 }): string;
 export declare function createSubagentTool(opts: SubagentToolOptions): ToolSpec;

package/dist/agents/subagent.js

@@ -21,7 +21,7 @@ import { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_
 export { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getOrCreateSessionRetainLedger, ensureSessionReapHook, createResumePrompt, } from "./retain-ledger.js";
 import { recordRosterSpawn } from "./roster-store.js";
-import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
+import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, ObserverResumeStateError, ObserverStoppedByUserError, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
 import { SubagentStepRecorder } from "./subagent-steps.js";
 const BG_AGENT_RESULT_MAX = 4_000;
 const BG_AGENT_RESULT_FULL_MAX = 200_000;
@@ -129,6 +129,9 @@ function createToolStatsCounter(delegationToolName) {
         snapshot() {
             return t.readCount + t.searchCount + t.bashCount + t.editFileCount + t.otherToolCount > 0 ? { ...t } : undefined;
         },
+        total() {
+            return t.readCount + t.searchCount + t.bashCount + t.editFileCount + t.otherToolCount;
+        },
     };
 }
 export const FORK_SUBAGENT_TYPE = "fork";
@@ -622,15 +625,20 @@ export function forkWorktreeTranslationNote(parentCwd, worktreeDir) {
 }
 export function asyncLaunchedReceipt(p) {
     const noteLines = (p.notes ?? []).filter((n) => n !== undefined && n !== "");
+    const oneShotBlocked = p.notify && p.oneShot === true;
     return (`Async agent launched successfully. (This tool result is internal metadata — never quote or paste any part of it, including the task_id below, into a user-facing reply.)\n` +
         `task_id: ${p.taskId} (internal ID - do not mention to user. Use SendMessage with to: '${p.taskId}', summary: '<5-10 word recap>' to continue this agent.)\n` +
-        (p.notify
-            ? `${p.workingLine} You will be notified automatically when it completes. You know nothing about its results until that notification arrives — do not report, assume, or predict them; continue other work or respond to the user in the meantime.\n`
-            : `${p.workingLine} Its result is NOT pushed automatically — retrieve progress and results with TaskOutput(task_id) where mounted.\n`) +
+        (oneShotBlocked
+            ? `${p.workingLine} This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput(task_id: "${p.taskId}", block: true). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.\n`
+            : p.notify
+                ? `${p.workingLine} You will be notified automatically when it completes. You know nothing about its results until that notification arrives — do not report, assume, or predict them; continue other work or respond to the user in the meantime.\n`
+                : `${p.workingLine} Its result is NOT pushed automatically — retrieve progress and results with TaskOutput(task_id) where mounted.\n`) +
         noteLines.map((n) => `${n}\n`).join("") +
-        (p.notify
-            ? `In your own words, briefly tell the user what you launched — do not echo this tool result. Agent results will arrive in a subsequent message. If the user asks for progress, say the agent is still running.`
-            : `In your own words, briefly tell the user what you launched — do not echo this tool result. The result will NOT arrive on its own — retrieve it with TaskOutput(task_id) where mounted before relying on it.`));
+        (oneShotBlocked
+            ? `In your own words, briefly tell the user what you launched — do not echo this tool result. Do not assume a later message will deliver the result: this submission ends after this turn, so retrieve it now with the blocking TaskOutput wait above before writing your final answer.`
+            : p.notify
+                ? `In your own words, briefly tell the user what you launched — do not echo this tool result. Agent results will arrive in a subsequent message. If the user asks for progress, say the agent is still running.`
+                : `In your own words, briefly tell the user what you launched — do not echo this tool result. The result will NOT arrive on its own — retrieve it with TaskOutput(task_id) where mounted before relying on it.`));
 }
 export function createSubagentTool(opts) {
     const catalog = opts.runner.agentCatalog;
@@ -1105,9 +1113,17 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             let observerTap;
             let observerSessionId;
             let observerFailure;
+            let observerDegradedCount = 0;
+            let observerDegradedFirst;
             const noteObserverFailure = (err) => {
-                if (observerFailure === undefined) {
-                    observerFailure = (err instanceof Error ? err.message : String(err)).slice(0, REPORT_FIELD_MAX);
+                const msg = (err instanceof Error ? err.message : String(err)).slice(0, REPORT_FIELD_MAX);
+                if (observerPairing !== undefined && observerPairing.state === "armed") {
+                    observerDegradedCount++;
+                    if (observerDegradedFirst === undefined)
+                        observerDegradedFirst = msg;
+                }
+                else if (observerFailure === undefined) {
+                    observerFailure = msg;
                 }
                 try {
                     opts.onObserverError?.(err, {
@@ -1139,7 +1155,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 pendingTrigger.push(prompt);
                 const observerDef = observerArm.observerDefinition;
                 const envelopeName = observerSlug(childAgentName ?? def.name);
-                const sid = uuidv7();
+                let sid = uuidv7();
                 observerSessionId = sid;
                 markObserverTaskId(sid);
                 const reportOpts = {
@@ -1163,15 +1179,36 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 });
                 const runObserverLeg = async (spec) => {
                     if (!isObserverTaskId(sid))
-                        throw new Error("observer identity revoked — delivery refused");
+                        throw new ObserverStoppedByUserError("observer identity revoked — delivery refused");
                     const r = await opts.runner.runTask(spec);
                     if (r.status !== "completed") {
+                        if (r.errorCode === "resume.session_not_found") {
+                            throw new ObserverResumeStateError(`observer session no longer exists${r.errorMessage ? `: ${r.errorMessage}` : ""}`);
+                        }
                         throw new Error(`observer run ended ${r.status}${r.errorMessage ? `: ${r.errorMessage}` : ""}`);
                     }
                 };
                 const spawner = {
                     spawnFirstRun: ({ framingPrompt, digest }) => runObserverLeg(observerSpec(`${framingPrompt}\n\n${digest}`, false)),
                     deliver: ({ digest }) => runObserverLeg(observerSpec(digest, true)),
+                    restartFresh: async ({ framingPrompt, digest }) => {
+                        const dead = sid;
+                        const fresh = uuidv7();
+                        markObserverTaskId(fresh);
+                        sid = fresh;
+                        observerSessionId = fresh;
+                        try {
+                            await runObserverLeg(observerSpec(`${framingPrompt}\n\n${digest}`, false));
+                        }
+                        finally {
+                            unmarkObserverTaskId(dead);
+                            try {
+                                await opts.runner.sessions.release(dead);
+                            }
+                            catch {
+                            }
+                        }
+                    },
                 };
                 observerPairing = new ObserverPairing({
                     observedEnvelopeName: envelopeName,
@@ -1209,9 +1246,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         t.unref?.();
                     });
                     const outcome = await Promise.race([observerPairing.drain().then(() => "drained"), timeout]);
+                    observerPairing.retire(outcome === "timeout" ? "stopped" : "retired");
                     if (outcome === "timeout")
                         noteObserverFailure(new Error("observer unresponsive at settle (delivery drain timed out)"));
-                    observerPairing.retire(outcome === "timeout" ? "stopped" : "retired");
                     if (observerSessionId !== undefined) {
                         try {
                             await opts.runner.sessions.release(observerSessionId);
@@ -1240,7 +1277,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     clearTimeout(timer);
                 return outcome;
             };
-            const observerNoteFor = (outcome) => observerFailure !== undefined ? " [observer: failed]" : outcome === "still_draining" ? " [observer: still draining]" : "";
+            const observerNoteFor = (outcome) => observerFailure !== undefined
+                ? " [observer: failed]"
+                : outcome === "still_draining"
+                    ? " [observer: still draining]"
+                    : observerDegradedCount > 0
+                        ? ` [observer: degraded, ${observerDegradedCount} digest batch(es) lost]`
+                        : "";
             const stepRecorder = new SubagentStepRecorder(ctx.toolCallId);
             const toolStatsCounter = createToolStatsCounter(opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME);
             let assistantTextTail = "";
@@ -1736,6 +1779,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             taskId,
                             workingLine: `The forked agent inherits your full current context and works on its prompt in the background.`,
                             notify: Boolean(notify),
+                            oneShot: ctx.oneShot === true,
                             notes: [
                                 modelNote,
                                 extraToolsNote,
@@ -2366,6 +2410,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         taskId,
                         workingLine: `The agent is working in the background.`,
                         notify: Boolean(notify),
+                        oneShot: ctx.oneShot === true,
                         notes: [
                             modelNote,
                             extraToolsNote,
@@ -2381,6 +2426,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 };
             }
             let child;
+            const syncStartedAt = Date.now();
             let retainEntry;
             if (ctx.onSubagentSpawn || observerPairing) {
                 retainEntry = ctx.onSubagentSpawn ? await tryRetainChild(ctx.subagentRetain) : undefined;
@@ -2488,9 +2534,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 child.blockedReason ? `blocked_reason: ${inlineUntrusted(child.blockedReason, REPORT_FIELD_MAX)}` : "",
                 child.errorMessage ? `error: ${inlineUntrusted(child.errorMessage, REPORT_FIELD_MAX)}` : "",
                 errClass ? `error_kind: ${errClass.errorKind} (retryable: ${errClass.retryable})` : "",
-                observerFailure !== undefined ? `observer: failed (${inlineUntrusted(observerFailure, REPORT_FIELD_MAX)})` : "",
+                observerFailure !== undefined
+                    ? `observer: failed (${inlineUntrusted(observerFailure, REPORT_FIELD_MAX)})`
+                    : observerDegradedCount > 0
+                        ? `observer: degraded — ${observerDegradedCount} digest batch(es) never reached it (first: ${inlineUntrusted(observerDegradedFirst ?? "", REPORT_FIELD_MAX)})`
+                        : "",
                 `stats: turns=${child.stats.turns} tokens=${child.stats.tokens}`,
-                retainEntry || failureRetained ? `transcript_id: ${child.sessionId}` : "",
+                !retainEntry && failureRetained ? `transcript_id: ${child.sessionId} (internal ID - do not mention to user; inspect via AgentTranscript where mounted)` : "",
                 retainEntry ? `resumable: true` : "",
                 failureRetained
                     ? `session_retained: this child's session is kept for a short time (~15 min) so its transcript stays inspectable via transcript_id; it is released automatically afterwards.`
@@ -2521,6 +2571,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         : "(no text result)",
                 "",
                 "Verify this result before concluding. If it leaves more to do, continue or delegate again.",
+                retainEntry
+                    ? `transcript_id: ${child.sessionId} (internal ID - do not mention to user. Transcript inspectable via AgentTranscript where mounted; this child is continued through the deployment's resume handle, not by SendMessage.)`
+                    : "",
+                `<usage>subagent_tokens: ${child.stats.tokens}\ntool_uses: ${toolStatsCounter.total()}\nduration_ms: ${Date.now() - syncStartedAt}</usage>`,
             ].filter(Boolean);
             return {
                 content: lines.join("\n"),

package/dist/agents/teacher.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { mapNestedSuspend, isDurablePause } from "./suspend-guard.js";
+import { isDefineToolProduct, stampDefineToolBrand } from "../core/tools.js";
 import { delimitUntrusted, inlineUntrusted } from "../core/untrusted-text.js";
 export const TEACHER_PROMPT = `You are an expert advisor to a less-capable "student" agent that got stuck.
 You receive the task and the student's recent failed attempts. Your job is to help the student RECOVER,
@@ -119,29 +120,56 @@ async function runTeacherCore(runner, studentSpec, teacher) {
         errorStreak = sig === lastErrSig ? errorStreak + 1 : 1;
         lastErrSig = sig;
     };
-    const wrap = (t) => ({
-        ...t,
-        execute: async (args, ctx) => {
-            try {
-                const out = await t.execute(args, ctx);
-                const text = typeof out === "string"
-                    ? out
-                    : out && typeof out === "object" && "content" in out
-                        ? String(out.content)
-                        : (JSON.stringify(out) ?? "");
-                logTool(t.name, args, text);
-                errorStreak = 0;
-                lastErrSig = "";
-                return out;
-            }
-            catch (e) {
-                const errText = String(e);
-                logTool(t.name, args, `ERROR: ${errText}`);
-                onToolFail(t.name, errText);
-                throw e;
-            }
-        },
-    });
+    const wrap = (t) => {
+        if (isDefineToolProduct(t)) {
+            const product = t;
+            return stampDefineToolBrand({
+                ...t,
+                execute: async (toolCallId, rawParams, signal, onUpdate) => {
+                    try {
+                        const out = await product.execute(toolCallId, rawParams, signal, onUpdate);
+                        const blocks = out && typeof out === "object" && "content" in out ? out.content : out;
+                        const text = Array.isArray(blocks)
+                            ? blocks.map((b) => (b && typeof b === "object" && "text" in b ? String(b.text) : "")).join("\n")
+                            : String(blocks ?? "");
+                        logTool(t.name, rawParams, text);
+                        errorStreak = 0;
+                        lastErrSig = "";
+                        return out;
+                    }
+                    catch (e) {
+                        const errText = String(e);
+                        logTool(t.name, rawParams, `ERROR: ${errText}`);
+                        onToolFail(t.name, errText);
+                        throw e;
+                    }
+                },
+            });
+        }
+        return {
+            ...t,
+            execute: async (args, ctx) => {
+                try {
+                    const out = await t.execute(args, ctx);
+                    const text = typeof out === "string"
+                        ? out
+                        : out && typeof out === "object" && "content" in out
+                            ? String(out.content)
+                            : (JSON.stringify(out) ?? "");
+                    logTool(t.name, args, text);
+                    errorStreak = 0;
+                    lastErrSig = "";
+                    return out;
+                }
+                catch (e) {
+                    const errText = String(e);
+                    logTool(t.name, args, `ERROR: ${errText}`);
+                    onToolFail(t.name, errText);
+                    throw e;
+                }
+            },
+        };
+    };
     const tools = studentSpec.tools?.map(wrap);
     const helperBase = () => teacher.helperModel
         ? { model: teacher.helperModel }

package/dist/core/context-edit.js

@@ -2,7 +2,20 @@ import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "
 import { isToolResult } from "./message-utils.js";
 const CLEARED_MARKER = "[tool result cleared to save context]";
 const refNote = (ref) => `full text persisted; call ReadToolResult with ref "${ref}" to read it back`;
-const mediaNote = (n) => `${n} attachment${n === 1 ? "" : "s"} no longer visible after this clear`;
+const mediaNote = (blocks) => {
+    const byType = new Map();
+    for (const b of blocks) {
+        const t = b.type ?? "untyped";
+        byType.set(t, (byType.get(t) ?? 0) + 1);
+    }
+    const n = blocks.length;
+    if (byType.size === 1) {
+        const [t, c] = [...byType][0];
+        return `${c} ${t} attachment${c === 1 ? "" : "s"} no longer visible after this clear`;
+    }
+    const breakdown = [...byType].map(([t, c]) => `${c} ${t}`).join(", ");
+    return `${n} attachments (${breakdown}) no longer visible after this clear`;
+};
 const clearedMarker = (notes) => {
     const present = notes.filter((n) => n !== undefined);
     return present.length > 0 ? `[tool result cleared to save context — ${present.join("; ")}]` : CLEARED_MARKER;
@@ -91,8 +104,8 @@ export function clearStaleToolResults(messages, opts) {
                 }
             }
         }
-        const mediaCount = rawContent.filter((c) => c?.type !== "text").length;
-        const marker = clearedMarker([ref, mediaCount > 0 ? mediaNote(mediaCount) : undefined]);
+        const mediaBlocks = rawContent.filter((c) => c?.type !== "text");
+        const marker = clearedMarker([ref, mediaBlocks.length > 0 ? mediaNote(mediaBlocks) : undefined]);
         const cleared = {
             ...out[idx],
             content: [{ type: "text", text: marker }],

package/dist/core/file-snapshot-store.js

@@ -204,9 +204,18 @@ export class InMemoryFileSnapshotStore {
         try {
             for (const hash of new Set(manifest.values())) {
                 written.add(hash);
+                if (hash === "" || hash === "." || hash === ".." || !/^[A-Za-z0-9_.-]+$/.test(hash)) {
+                    return { ok: false, error: { code: "read_failed", message: `unsafe blob hash ${JSON.stringify(hash)}` } };
+                }
                 if (this.blobs.has(hash))
                     continue;
-                const bytes = await srcGetBlob(hash);
+                let bytes;
+                try {
+                    bytes = await srcGetBlob(hash);
+                }
+                catch (err) {
+                    return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fetch failed: ${err.message}` } };
+                }
                 if (!bytes)
                     return { ok: false, error: { code: "read_failed", message: `missing source blob ${hash}` } };
                 if (createHash("sha256").update(bytes).digest("hex") !== hash) {

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

@@ -68,6 +68,7 @@ export interface Stats {
 export interface ResultFlags {
     threw: unknown;
     model?: string;
+    unpricedSpend?: boolean;
     abortedForTimeout: boolean;
     abortedForTurns: boolean;
     abortedLive?: boolean;

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

@@ -36,14 +36,16 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     const taskId = spec.taskId ?? sessionId;
     const text = final ? assistantText(final) : "";
     stats.totalInputTokens = stats.promptTokens;
-    const compactionMicroUsd = stats.compactionMicroUsd ?? 0;
-    const nestedSubagentMicroUsd = stats.nested?.costMicroUsd ?? 0;
-    stats.costBreakdown = {
-        llmRootMicroUsd: Math.max(0, stats.costMicroUsd - compactionMicroUsd),
-        nestedSubagentMicroUsd,
-        memoryConsolidationMicroUsd: 0,
-        compactionMicroUsd,
-    };
+    if (!flags.unpricedSpend) {
+        const compactionMicroUsd = stats.compactionMicroUsd ?? 0;
+        const nestedSubagentMicroUsd = stats.nested?.costMicroUsd ?? 0;
+        stats.costBreakdown = {
+            llmRootMicroUsd: Math.max(0, stats.costMicroUsd - compactionMicroUsd),
+            nestedSubagentMicroUsd,
+            memoryConsolidationMicroUsd: 0,
+            compactionMicroUsd,
+        };
+    }
     let status;
     const result = text;
     let errorMessage;
@@ -139,5 +141,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     }
     const { compactionMicroUsd: _internalCompaction, ...publicStats } = stats;
     void _internalCompaction;
+    if (flags.unpricedSpend)
+        delete publicStats.costMicroUsd;
     return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, checkpointToken, checkpointGate, stats: publicStats };
 }

package/dist/core/runner/prepare-task.d.ts

@@ -114,6 +114,7 @@ export interface Prepared {
         apply: (committedArtifactDigest?: string) => void;
     } | undefined;
     activeTools: Set<string>;
+    deferredToolNames?: ReadonlySet<string>;
     memoryEngineSession?: {
         engine: MemoryEngine;
         handle: MemorySessionHandle;