@sema-agent/core 2.3.0 → 2.5.0

package/dist/core/task-notification.d.ts

@@ -10,6 +10,8 @@ export interface TaskNotificationPayload {
     source?: string;
     stoppedBy?: "user" | "parent" | "system" | (string & {});
     summary: string;
+    error?: string;
+    errorCode?: string;
     exitCode?: number;
     result?: string;
     partial?: boolean;

package/dist/core/task-registry-agent.d.ts

@@ -66,6 +66,9 @@ export declare function settleBackgroundAgentLane(core: DurableAgentCore, id: st
     result?: string;
     resultFull?: string;
     error?: string;
+    errorCode?: string;
+    retryable?: boolean;
+    errorKind?: string;
     stoppedBy?: StopSource;
     seq?: number;
 }): "completed" | "failed" | "killed" | undefined;
@@ -98,6 +101,9 @@ export declare function settleRevivedAgentLane(core: DurableAgentCore, id: strin
     result?: string;
     resultFull?: string;
     error?: string;
+    errorCode?: string;
+    retryable?: boolean;
+    errorKind?: string;
 }): "completed" | "failed" | "killed" | undefined;
 export declare function unmarkRetainedContinuationLane(core: DurableAgentCore, id: string): void;
 export declare function attachAgentNotifyLane(core: DurableAgentCore, id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;

package/dist/core/task-registry-agent.js

@@ -3,6 +3,7 @@ import { uuidv7 } from "../internal/harness.js";
 import { canAccessAgentRecord, BackgroundAgentStoreError, } from "./background-agent-store.js";
 import { shutdownDebug } from "./shutdown-debug.js";
 import { delimitUntrusted } from "./untrusted-text.js";
+import { boundedRedactedSummary } from "./untrusted-egress.js";
 import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
 import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
 export function ensureDurableHeartbeatLane(core) {
@@ -636,6 +637,7 @@ export async function consumeParkedFlipLane(core, id, stores, ticket) {
     handle.resolveParkedStop = undefined;
     handle.updatedAt = Date.now();
     handle.completionId = undefined;
+    handle.terminalNotified = undefined;
     if (flipped.seq !== undefined)
         handle.cycleSeq = flipped.seq;
     return true;
@@ -681,6 +683,7 @@ export function settleBackgroundAgentLane(core, id, outcome) {
     handle.status = outcome.status;
     mintCompletionId(handle);
     handle.notify = undefined;
+    handle.onReapTerminal = undefined;
     for (const [, , qResolve] of handle.preAttachQueue ?? [])
         qResolve?.({ ok: false, reason: "not_running" });
     handle.preAttachQueue = undefined;
@@ -699,6 +702,12 @@ export function settleBackgroundAgentLane(core, id, outcome) {
     }
     if (outcome.error !== undefined && !(outcome.status === "killed" && outcome.error === BG_AGENT_REAP_STOP_ERROR)) {
         handle.error = outcome.error;
+        if (outcome.errorCode !== undefined)
+            handle.errorCode = outcome.errorCode;
+        if (outcome.retryable !== undefined)
+            handle.errorRetryable = outcome.retryable;
+        if (outcome.errorKind !== undefined)
+            handle.errorKind = outcome.errorKind;
     }
     handle.updatedAt = Date.now();
     if (outcome.seq !== undefined)
@@ -837,9 +846,13 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.resultFull = undefined;
     handle.spillRef = undefined;
     handle.error = undefined;
+    handle.errorCode = undefined;
+    handle.errorRetryable = undefined;
+    handle.errorKind = undefined;
     handle.resultIsPartial = undefined;
     handle.stopSource = undefined;
     handle.completionId = undefined;
+    handle.terminalNotified = undefined;
     handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
     handle.cycleSeq = (handle.cycleSeq ?? 1) + 1;
     handle.updatedAt = Date.now();
@@ -1022,6 +1035,7 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
             ...(row.resultIsPartial ? { partial_result: true } : {}),
             ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
         },
+        ...(row.status === "failed" ? { isError: true } : {}),
     };
 }
 export async function spillClippedAgentResult(handle, full, clipped, store, sessionId) {
@@ -1057,6 +1071,9 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
     }
     const fullResult = handle.result ? (handle.resultFull ?? handle.result) : undefined;
     const resultText = fullResult !== undefined ? await spillClippedAgentResult(handle, fullResult, clipTaskOutput(fullResult, handle.outputFile), store, sessionId) : undefined;
+    const kindClause = handle.status === "failed" && handle.errorKind !== undefined && handle.errorRetryable !== undefined
+        ? ` (error_kind: ${handle.errorKind}, retryable: ${handle.errorRetryable})`
+        : "";
     const body = running
         ? oneShot === true
             ? `status: running
@@ -1064,7 +1081,7 @@ This is a ONE-SHOT submission — there is no later turn for a background notifi
             : `status: running
 The agent is still working — you will be notified when it completes.`
         : `status: ${handle.status}
-${handle.error ? `error: ${handle.error}
+${handle.error ? `error: ${handle.error}${kindClause}
 ` : ""}${handle.result ? `--- result${handle.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
 ${resultText}` : "(no result text)"}`;
     return {
@@ -1076,9 +1093,15 @@ ${resultText}` : "(no result text)"}`;
             retrieval_status: retrieval,
             ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
             ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            ...(handle.status === "failed" && handle.error !== undefined
+                ? { error: delimitUntrusted("agent error", boundedRedactedSummary(handle.error, 300)) }
+                : {}),
+            ...(handle.status === "failed" && handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
+            ...(handle.status === "failed" && handle.errorRetryable !== undefined ? { retryable: handle.errorRetryable } : {}),
             ...(handle.resultIsPartial ? { partial_result: true } : {}),
             ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
         },
+        ...(handle.status === "failed" ? { isError: true } : {}),
     };
 }
 export async function stopBackgroundAgentLane(core, handle) {

package/dist/core/task-registry-monitor.js

@@ -1,5 +1,5 @@
 import { delimitUntrusted } from "./untrusted-text.js";
-import { assertOwnership, defaultMonitorTimers, MONITOR_MAX_TIMEOUT_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_BATCH_WINDOW_MS, MONITOR_MAX_BATCHES_PER_MINUTE, MONITOR_STORM_BURST, MONITOR_STORM_KILL_AFTER_MS, MONITOR_LINE_BUF_CAP, MONITOR_SPILL_CAP_BYTES, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
+import { assertOwnership, defaultMonitorTimers, MONITOR_MAX_TIMEOUT_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_BATCH_WINDOW_MS, MONITOR_MAX_BATCHES_PER_MINUTE, MONITOR_STORM_BURST, MONITOR_STORM_KILL_AFTER_MS, MONITOR_LINE_BUF_CAP, MONITOR_SPILL_CAP_CHARS, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
 import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
 export function registerMonitorLane(core, input) {
     assertOwnership(input, "registerMonitor");
@@ -49,14 +49,14 @@ function spillRolledMonitorChunk(handle, stream, dropped) {
     const store = handle.toolResultStore;
     if (store === undefined)
         return;
-    const used = handle.spillBytesUsed ?? 0;
-    if (used >= MONITOR_SPILL_CAP_BYTES) {
+    const used = handle.spillCharsUsed ?? 0;
+    if (used >= MONITOR_SPILL_CAP_CHARS) {
         handle.spillCapped = true;
         return;
     }
     const n = stream === "out" ? (handle.spillSegCount ?? 0) : (handle.spillErrSegCount ?? 0);
     const ref = buildToolResultRef(handle.spillSessionId ?? "no-session", `${handle.id}_${stream}_seg${n}`);
-    handle.spillBytesUsed = used + dropped.length;
+    handle.spillCharsUsed = used + dropped.length;
     if (stream === "out")
         handle.spillSegCount = n + 1;
     else
@@ -88,7 +88,7 @@ function monitorSpillNote(handle) {
     const coverage = handle.spillFailed === true
         ? " — a write failed partway through; the ref chain may be INCOMPLETE, read what is there"
         : handle.spillCapped === true
-            ? ` — spill cap (${MONITOR_SPILL_CAP_BYTES} bytes) reached; earlier segments retained, later rolls were not spilled`
+            ? ` — spill cap (${MONITOR_SPILL_CAP_CHARS} chars) reached; earlier segments retained, later rolls were not spilled`
             : "";
     return `; spilled to ${clauses.join(", ")} (read back via ${OFFLOAD_TOOL_NAME})${coverage}`;
 }
@@ -359,7 +359,7 @@ function explicitStopTerminalNote(handle, alreadyGone) {
         task_type: "monitor",
         ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
         status: "killed",
-        stoppedBy: handle.stoppedBy,
+        ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
         summary: `${terminalTaskSummary("monitor", label, "killed")} — ${detail}${droppedGapNote(handle.spool)}`,
         ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
     });

package/dist/core/task-registry-shared.d.ts

@@ -16,6 +16,8 @@ export interface UnifiedTaskOutput {
     retrieval_status: TaskRetrievalStatus;
     content?: string;
     error?: string;
+    errorCode?: string;
+    retryable?: boolean;
     stoppedBy?: StopSource;
     seq?: number;
     partial_result?: boolean;
@@ -135,9 +137,14 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
     resultFull?: string;
     spillRef?: string;
     error?: string;
+    errorCode?: string;
+    errorRetryable?: boolean;
+    errorKind?: string;
     resultIsPartial?: boolean;
     stopSource?: StopSource;
     stoppedBy?: StopSource;
+    onReapTerminal?: () => void;
+    terminalNotified?: true;
 }
 export interface MonitorTimers {
     setInterval: (fn: () => unknown, ms: number) => unknown;
@@ -188,7 +195,7 @@ export interface MonitorTaskHandle extends SemaTaskHandle {
     spillSessionId?: string;
     spillSegCount?: number;
     spillErrSegCount?: number;
-    spillBytesUsed?: number;
+    spillCharsUsed?: number;
     spillCapped?: true;
     spillFailed?: true;
 }
@@ -237,7 +244,7 @@ export declare function statusFromBackground(status: string, exitCode?: number):
 export declare function rollSpoolText(spool: {
     rolledChars: number;
 }, s: string, cap: number, onDrop?: (dropped: string) => void): string;
-export declare const MONITOR_SPILL_CAP_BYTES: number;
+export declare const MONITOR_SPILL_CAP_CHARS: number;
 export declare function accountDroppedBytes(spool: {
     droppedBytes?: number;
     dropUnknown?: true;

package/dist/core/task-registry-shared.js

@@ -94,7 +94,7 @@ export function rollSpoolText(spool, s, cap, onDrop) {
     onDrop?.(dropped);
     return s.slice(0, half) + s.slice(s.length - half);
 }
-export const MONITOR_SPILL_CAP_BYTES = 64 * 1024 * 1024;
+export const MONITOR_SPILL_CAP_CHARS = 64 * 1024 * 1024;
 export function accountDroppedBytes(spool, poll) {
     const d = poll.bytesDroppedBeforeCursor ?? 0;
     if (d > 0)

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

@@ -133,6 +133,9 @@ export declare class TaskRegistry {
         result?: string;
         resultFull?: string;
         error?: string;
+        errorCode?: string;
+        retryable?: boolean;
+        errorKind?: string;
         stoppedBy?: StopSource;
         seq?: number;
     }): "completed" | "failed" | "killed" | undefined;
@@ -166,9 +169,14 @@ export declare class TaskRegistry {
         result?: string;
         resultFull?: string;
         error?: string;
+        errorCode?: string;
+        retryable?: boolean;
+        errorKind?: string;
     }): "completed" | "failed" | "killed" | undefined;
     unmarkRetainedContinuation(id: string): void;
     attachAgentNotify(id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;
+    attachAgentTerminalNotifier(id: string, fn: () => void): void;
+    claimAgentTerminalNotify(id: string): boolean;
     deliverToRunningAgent(id: string, access: TaskAccess, notification: import("./task-notification.js").TaskNotificationPayload, opts?: {
         priority?: import("./task-notification.js").SystemInjectionPriority;
     }): Promise<{

package/dist/core/task-registry.js

@@ -52,6 +52,23 @@ function bashMirrorGapNote(handle) {
         ? " [!] The output file is INCOMPLETE (one or more writes to it failed) — trust the result text / TaskOutput over the file."
         : "";
 }
+function explicitStopBashTerminalNote(handle, alreadyGone) {
+    const resultText = handle.spool !== undefined ? bashTerminalResult(handle.spool) : "";
+    const detail = alreadyGone
+        ? "killed before completion (stopped via TaskStop; the process was already gone)"
+        : "killed before completion (stopped via TaskStop)";
+    handle.onTerminal?.({
+        task_id: handle.id,
+        task_type: "background_bash",
+        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+        ...(handle.outputFile !== undefined ? { output_file: handle.outputFile } : {}),
+        status: "killed",
+        ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+        summary: `${terminalTaskSummary("bash", (handle.description ?? "background command").slice(0, 200), "killed")} — ${detail}${bashMirrorGapNote(handle)}${handle.spool !== undefined ? droppedGapNote(handle.spool) : ""}`,
+        ...(resultText.length > 0 ? { result: resultText, partial: true } : {}),
+        ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+    });
+}
 function monitorInTimeoutWindow(handle) {
     return handle.status === "running" && handle.deadlineAt !== undefined && handle.timers.now() < handle.deadlineAt;
 }
@@ -145,6 +162,23 @@ export class TaskRegistry {
     attachAgentNotify(id, notify, cycle) {
         return attachAgentNotifyLane(this.core, id, notify, cycle);
     }
+    attachAgentTerminalNotifier(id, fn) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_agent")
+            return;
+        if (handle.status !== "running" && handle.status !== "parked" && handle.status !== "pending")
+            return;
+        handle.onReapTerminal = fn;
+    }
+    claimAgentTerminalNotify(id) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_agent")
+            return true;
+        if (handle.terminalNotified === true)
+            return false;
+        handle.terminalNotified = true;
+        return true;
+    }
     async deliverToRunningAgent(id, access, notification, opts) {
         return deliverToRunningAgentLane(this.core, id, access, notification, opts);
     }
@@ -334,6 +368,17 @@ export class TaskRegistry {
     async settleKilledForOwner(access, opts) {
         const source = opts?.source ?? "parent";
         const clause = (by) => by === "user" ? "stopped by user" : by === "parent" ? "its parent run ended" : `stopped by ${by}`;
+        if (source === "user") {
+            for (const handle of this.handles.values()) {
+                if (handle.type !== "background_agent" || handle.status !== "running")
+                    continue;
+                if (!canAccess(handle, { owner: access.owner, scope: access.scope }))
+                    continue;
+                if (opts?.skipSessionScoped && handle.sessionScoped)
+                    continue;
+                this.markStopSource(handle.id, source);
+            }
+        }
         let settled = 0;
         for (const handle of this.handles.values()) {
             if (handle.type !== "background_bash" && handle.type !== "monitor")
@@ -471,8 +516,17 @@ export class TaskRegistry {
             if (!canAccess(handle, access))
                 continue;
             this.markStopSource(handle.id, "system");
+            const reapTerminalNote = handle.onReapTerminal;
             handle.abort.abort();
             this.settleBackgroundAgent(handle.id, { status: "killed", error: "session released" });
+            if (reapTerminalNote !== undefined && handle.terminalNotified !== true) {
+                handle.terminalNotified = true;
+                try {
+                    reapTerminalNote();
+                }
+                catch {
+                }
+            }
             reaped++;
         }
         this.pokeBgQuiescence(sessionId);
@@ -1122,7 +1176,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                 handle.status = "killed";
                 handle.updatedAt = Date.now();
                 mintCompletionId(handle);
-                this.pokeBgQuiescence(handle.owner);
+                this.notifyTerminalOnce(handle, () => explicitStopBashTerminalNote(handle, true));
                 return {
                     content: `Terminated ${handle.id} (the process was already gone).`,
                     details: {
@@ -1151,7 +1205,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
         handle.status = "killed";
         handle.updatedAt = Date.now();
         mintCompletionId(handle);
-        this.pokeBgQuiescence(handle.owner);
+        this.notifyTerminalOnce(handle, () => explicitStopBashTerminalNote(handle, false));
         return {
             content: `Terminated ${handle.id}.`,
             details: {
@@ -1193,9 +1247,10 @@ export function createTaskOutputTool(opts) {
             let effectiveTimeoutMs = requestedMs;
             let waitClampNote = "";
             const wall = opts.deadlineMs?.();
+            const requestedWaitMs = Math.max(1, Math.floor(requestedMs ?? BLOCK_DEFAULT_TIMEOUT_MS));
             if (args.block !== false && wall !== undefined) {
                 const remainMs = wall - Date.now() - BLOCK_WAIT_WRITEOUT_RESERVE_MS;
-                const wantMs = Math.min(BLOCK_MAX_TIMEOUT_MS, Math.max(1, Math.floor(requestedMs ?? BLOCK_DEFAULT_TIMEOUT_MS)));
+                const wantMs = Math.min(BLOCK_MAX_TIMEOUT_MS, requestedWaitMs);
                 if (remainMs <= 0) {
                     effectiveTimeoutMs = 1;
                     waitClampNote =
@@ -1203,7 +1258,7 @@ export function createTaskOutputTool(opts) {
                 }
                 else if (remainMs < wantMs) {
                     effectiveTimeoutMs = remainMs;
-                    waitClampNote = `\n\nNOTE: wait clamped to ${Math.round(remainMs / 1000)}s (requested ${Math.round(wantMs / 1000)}s) — the task's wall-clock deadline is near. If the task is still running after this wait, do NOT re-wait: proceed with other work or write out your results now.`;
+                    waitClampNote = `\n\nNOTE: wait clamped to ${Math.round(remainMs / 1000)}s (requested ${Math.round(requestedWaitMs / 1000)}s) — the task's wall-clock deadline is near. If the task is still running after this wait, do NOT re-wait: proceed with other work or write out your results now.`;
                 }
             }
             const r = await opts.registry.pollTask(id, { owner: ctx.taskId ?? opts.owner, scope: ctx.principal ?? opts.scope, ...((ctx.sessionId ?? opts.sessionId) !== undefined ? { sessionId: ctx.sessionId ?? opts.sessionId } : {}) }, {

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

@@ -45,6 +45,7 @@ export declare class ScopedToolResultStore implements ToolResultStore {
 }
 export declare function isVolatileOffloadStore(store: ToolResultStore): boolean;
 export declare const OFFLOAD_TOOL_NAME = "ReadToolResult";
+export declare function offloadPagebackHint(ref: string, form: "preview" | "cleared", reachableTools?: ReadonlySet<string>): string;
 export declare const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 export declare const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20000;
 export declare function firstPartyOffloadPolicy(toolName: string): {
@@ -54,6 +55,6 @@ export declare function firstPartyOffloadPolicy(toolName: string): {
 export declare function buildPreview(full: string, ref: string, sizes?: {
     head: number;
     tail: number;
-}): string;
-export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string): AgentTool;
+}, reachableTools?: ReadonlySet<string>): string;
+export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string, reachableTools?: () => ReadonlySet<string> | undefined): AgentTool;
 export declare function createReadToolResultTool(store: ToolResultStore): AgentTool;

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "./tools.js";
+import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
 export function assertSafeToolResultRef(ref) {
     const bad = ref === "" ||
         ref === "." ||
@@ -92,6 +93,13 @@ export function isVolatileOffloadStore(store) {
     return store instanceof InMemoryToolResultStore;
 }
 export const OFFLOAD_TOOL_NAME = "ReadToolResult";
+export function offloadPagebackHint(ref, form, reachableTools) {
+    const activate = reachableTools !== undefined && !reachableTools.has(OFFLOAD_TOOL_NAME)
+        ? `${OFFLOAD_TOOL_NAME} is not active yet — call ${TOOL_SEARCH_NAME} with {"query":"select:${OFFLOAD_TOOL_NAME}"} to activate it, then `
+        : "";
+    const core = `${activate === "" && form === "preview" ? "Call" : `${activate}call`} ${OFFLOAD_TOOL_NAME} with ref`;
+    return form === "preview" ? `${core}="${ref}" (offset, limit) to read more.` : `full text persisted; ${core} "${ref}" to read it back`;
+}
 export const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 export const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20_000;
 export function firstPartyOffloadPolicy(toolName) {
@@ -122,7 +130,7 @@ function totalTextChars(content) {
             n += b.text.length;
     return n;
 }
-export function buildPreview(full, ref, sizes) {
+export function buildPreview(full, ref, sizes, reachableTools) {
     const total = full.length;
     const headChars = sizes?.head ?? PREVIEW_HEAD_CHARS;
     const tailChars = sizes?.tail ?? PREVIEW_TAIL_CHARS;
@@ -131,11 +139,11 @@ export function buildPreview(full, ref, sizes) {
     const tail = full.slice(tailStart);
     return (`${PERSISTED_OUTPUT_PREFIX}"${ref}" chars="${total}">\n` +
         `${head}\n` +
-        `…[truncated — ${total} chars total. Call ${OFFLOAD_TOOL_NAME} with ref="${ref}" (offset, limit) to read more.]\n` +
+        `…[truncated — ${total} chars total. ${offloadPagebackHint(ref, "preview", reachableTools)}]\n` +
         `${tail}\n` +
         `</persisted-output>`);
 }
-export function withToolResultOffload(tool, store, thresholdChars, sessionId) {
+export function withToolResultOffload(tool, store, thresholdChars, sessionId, reachableTools) {
     const wrappedExecute = async (toolCallId, params, signal, onUpdate) => {
         const res = await tool.execute(toolCallId, params, signal, onUpdate);
         if (totalTextChars(res.content) <= thresholdChars)
@@ -149,7 +157,7 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId) {
         const ref = buildToolResultRef(sessionId, toolCallId);
         await store.put(ref, full);
         const images = res.content.filter((b) => b.type !== "text");
-        return { ...res, content: [{ type: "text", text: buildPreview(full, ref) }, ...images] };
+        return { ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] };
     };
     return { ...tool, execute: wrappedExecute };
 }

package/dist/core/trace.d.ts

@@ -104,6 +104,13 @@ export type TraceEvent = {
     }>;
     overrideReasons?: Record<string, string>;
     ts: number;
+} | {
+    kind: "config.additional_directory_skipped";
+    version: 1;
+    taskId: string;
+    entry: string;
+    reason: string;
+    ts: number;
 } | {
     kind: "task.end";
     version: 1;

package/dist/core/types.d.ts

@@ -47,6 +47,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
     offload?: boolean;
     offloadThresholdChars?: number;
     defer?: boolean;
+    alwaysLoad?: boolean;
     contract?: {
         contractId: string;
         implementationRevision: string;
@@ -256,6 +257,7 @@ export interface TaskSpec {
     tools?: ToolSpec[];
     excludeTools?: string[];
     deferTools?: string[];
+    alwaysLoadTools?: string[];
     promptProfile?: "simple" | "classic";
     agents?: AgentDefinition[];
     toolPolicy?: import("./tool-policy.js").ToolPolicy;
@@ -514,9 +516,9 @@ export type TaskEvent = ({
     };
     usageMissing?: true;
     stopReason?: string;
-} & TaskEventIdentity) | {
+} & TaskEventIdentity) | ({
     type: "compacted";
-    trigger: "auto" | "manual";
+    trigger: "auto" | "manual" | "forced";
     tokensBefore: number;
     tokensAfter?: number;
     triggerTokensBefore?: number;
@@ -534,7 +536,12 @@ export type TaskEvent = ({
     clampedRatio?: number;
     clampReason?: "budget" | "walltime" | "tolerance";
     phaseDurations?: import("./auto-compaction.js").CompactionPhaseDurations;
-} | ({
+} & TaskEventIdentity) | ({
+    type: "compaction_outcome";
+    outcome: Exclude<CompactOutcome, "compacted"> | "suppressed";
+    trigger: "auto" | "manual" | "forced";
+    reason?: string;
+} & TaskEventIdentity) | ({
     type: "steering_injected";
     source: "deadline_nudge" | "finalize" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
     preview: string;

package/dist/engine/compaction/compaction.d.ts

@@ -8,6 +8,9 @@ export interface CompactionDetails {
     modifiedFiles: string[];
     modifiedFilesByRecency?: string[];
     invokedSkills?: InvokedSkillRetention[];
+    elidedMessages?: number;
+    persistedOutputRefs?: string[];
+    activeTools?: string[];
 }
 export interface CompactionResult<T = unknown> {
     summary: string;
@@ -68,6 +71,8 @@ export interface CompactionPreparation {
     previousSummary?: string;
     fileOps: FileOperations;
     invokedSkills: InvokedSkillRetention[];
+    persistedOutputRefs?: string[];
+    elidedMessages?: number;
     settings: CompactionSettings;
 }
 export declare function prepareCompaction(pathEntries: SessionTreeEntry[], settings: CompactionSettings, charsPerToken?: number, windowTokens?: number): Result<CompactionPreparation | undefined, CompactionError>;

package/dist/engine/compaction/compaction.js

@@ -2,7 +2,7 @@ import { resolveAgentCoreCompleteFn, } from "../loop/runtime-deps.js";
 import { asAgentMessage, convertToLlm, createCompactionSummaryMessage, createCustomMessage, } from "../harness/messages.js";
 import { buildSessionContext } from "../session/session.js";
 import { CompactionError, err, ok, } from "../harness/types.js";
-import { budgetInvokedSkillsRetention, computeFileLists, createFileOps, extractFileOpsFromMessage, extractInvokedSkills, formatFileOperations, readRetainedInvokedSkills, replaceInvokedSkillBodiesForSummary, serializeConversation, stripFileOperationsFooter, } from "./utils.js";
+import { budgetInvokedSkillsRetention, computeFileLists, createFileOps, extractFileOpsFromMessage, extractInvokedSkills, extractPersistedOutputRefs, formatFileOperations, formatPersistedOutputRefs, PERSISTED_OUTPUT_REFS_MAX_ENTRIES, readElidedMessages, readPersistedOutputRefs, readRetainedInvokedSkills, replaceInvokedSkillBodiesForSummary, serializeConversation, stripFileOperationsFooter, } from "./utils.js";
 function safeJsonStringify(value) {
     try {
         return JSON.stringify(value) ?? "undefined";
@@ -256,6 +256,51 @@ export function findTurnStartIndex(entries, entryIndex, startIndex) {
     }
     return -1;
 }
+function enforceToolPairContainment(entries, startIndex, endIndex, cutIndex) {
+    const callSites = new Map();
+    for (let i = startIndex; i < endIndex; i++) {
+        const entry = entries[i];
+        if (entry.type !== "message")
+            continue;
+        const msg = entry.message;
+        if (msg.role !== "assistant" || !Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (block.type === "toolCall" && typeof block.id === "string") {
+                const at = callSites.get(block.id);
+                if (at === undefined)
+                    callSites.set(block.id, [i]);
+                else
+                    at.push(i);
+            }
+        }
+    }
+    if (callSites.size === 0)
+        return cutIndex;
+    for (let i = cutIndex; i < endIndex; i++) {
+        const entry = entries[i];
+        if (entry.type !== "message")
+            continue;
+        const msg = entry.message;
+        if (msg.role !== "toolResult")
+            continue;
+        const sites = callSites.get(msg.toolCallId);
+        if (sites === undefined)
+            continue;
+        let site = -1;
+        for (const s of sites) {
+            if (s < i)
+                site = s;
+            else
+                break;
+        }
+        if (site === -1 || site >= cutIndex)
+            continue;
+        cutIndex = site;
+        i = site;
+    }
+    return cutIndex;
+}
 export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens, charsPerToken = DEFAULT_CHARS_PER_TOKEN) {
     const cutPoints = findValidCutPoints(entries, startIndex, endIndex);
     if (cutPoints.length === 0) {
@@ -290,6 +335,7 @@ export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens, ch
             break;
         }
     }
+    cutIndex = enforceToolPairContainment(entries, startIndex, endIndex, cutIndex);
     const cutEntry = entries[cutIndex];
     const isUserMessage = cutEntry.type === "message" && cutEntry.message.role === "user";
     const turnStartIndex = isUserMessage ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
@@ -721,6 +767,21 @@ export function prepareCompaction(pathEntries, settings, charsPerToken = DEFAULT
         ? Math.max(0, windowTokens - settings.reserveTokens - settings.keepRecentTokens) * charsPerToken
         : undefined;
     const invokedSkills = budgetInvokedSkillsRetention(extractInvokedSkills([...messagesToSummarize, ...turnPrefixMessages], prevRetainedSkills), retentionBudgetChars);
+    const refSet = new Set();
+    if (prevCompactionIndex >= 0 && !pathEntries[prevCompactionIndex].fromHook) {
+        for (const r of readPersistedOutputRefs(pathEntries[prevCompactionIndex].details)) {
+            refSet.add(r);
+        }
+    }
+    extractPersistedOutputRefs(messagesToSummarize, refSet);
+    if (cutPoint.isSplitTurn) {
+        extractPersistedOutputRefs(turnPrefixMessages, refSet);
+    }
+    const persistedOutputRefs = [...refSet].slice(-PERSISTED_OUTPUT_REFS_MAX_ENTRIES);
+    const prevElided = prevCompactionIndex >= 0 && !pathEntries[prevCompactionIndex].fromHook
+        ? readElidedMessages(pathEntries[prevCompactionIndex].details)
+        : undefined;
+    const elidedMessages = (prevElided ?? 0) + messagesToSummarize.length + turnPrefixMessages.length;
     const [summarizeReady, prefixReady] = replaceInvokedSkillBodiesForSummary([messagesToSummarize, turnPrefixMessages], new Set(invokedSkills.map((s) => s.name)));
     return ok({
         firstKeptEntryId,
@@ -731,6 +792,8 @@ export function prepareCompaction(pathEntries, settings, charsPerToken = DEFAULT
         previousSummary,
         fileOps,
         invokedSkills,
+        persistedOutputRefs,
+        elidedMessages,
         settings,
     });
 }
@@ -750,7 +813,7 @@ Summarize the prefix to provide context for the retained suffix:
 Be concise. Focus on what's needed to understand the kept suffix.`;
 export { computeFileLists, serializeConversation } from "./utils.js";
 export async function compact(preparation, model, apiKey, headers, customInstructions, signal, thinkingLevel, streamFn, runtime, charsPerToken, onInputTruncated, onPtlRetry) {
-    const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, previousSummary, fileOps, invokedSkills, settings, } = preparation;
+    const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, previousSummary, fileOps, invokedSkills, persistedOutputRefs, elidedMessages, settings, } = preparation;
     if (!firstKeptEntryId) {
         return err(new CompactionError("invalid_session", "First kept entry has no UUID - session may need migration"));
     }
@@ -784,6 +847,7 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
     }
     const { readFiles, modifiedFiles, modifiedFilesByRecency } = computeFileLists(fileOps);
     summary += formatFileOperations(readFiles, modifiedFiles);
+    summary += formatPersistedOutputRefs(persistedOutputRefs ?? []);
     return ok({
         summary,
         firstKeptEntryId,
@@ -793,6 +857,8 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
             modifiedFiles,
             modifiedFilesByRecency,
             ...(invokedSkills !== undefined && invokedSkills.length > 0 ? { invokedSkills } : {}),
+            ...(persistedOutputRefs !== undefined && persistedOutputRefs.length > 0 ? { persistedOutputRefs } : {}),
+            ...(elidedMessages !== undefined && elidedMessages > 0 ? { elidedMessages } : {}),
         },
     });
 }

package/dist/engine/compaction/utils.d.ts

@@ -21,6 +21,12 @@ export declare function budgetInvokedSkillsRetention(newestFirst: InvokedSkillRe
 export declare function replaceInvokedSkillBodiesForSummary(groups: AgentMessage[][], retainedNames: ReadonlySet<string>): AgentMessage[][];
 export declare function readRetainedInvokedSkills(details: unknown): InvokedSkillRetention[];
 export declare function renderInvokedSkillsRetention(skills: InvokedSkillRetention[]): string;
+export declare const PERSISTED_OUTPUT_REFS_MAX_ENTRIES = 50;
+export declare function extractPersistedOutputRefs(messages: AgentMessage[], into: Set<string>): void;
+export declare function readElidedMessages(details: unknown): number | undefined;
+export declare function readCompactionActiveTools(details: unknown): string[];
+export declare function readPersistedOutputRefs(details: unknown): string[];
+export declare function formatPersistedOutputRefs(refs: string[]): string;
 export declare function computeFileLists(fileOps: FileOperations): {
     readFiles: string[];
     modifiedFiles: string[];