@sema-agent/core 2.4.0 → 2.6.0

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

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { Value } from "typebox/value";
 import { defineTool } from "../tools.js";
 export const TOOL_SEARCH_NAME = "ToolSearch";
 const DEFER_AUTO_FRACTION = 0.1;
@@ -24,17 +25,24 @@ function inlinedChars(t) {
     return t.description.length + schema.length;
 }
 export function classifyDeferred(opts) {
+    const pinned = new Set(opts.alwaysLoadNames ?? []);
+    for (const s of opts.specs) {
+        if (s.alwaysLoad === true)
+            pinned.add(s.name);
+    }
     const deferred = new Set();
     for (const s of opts.specs) {
-        if (s.defer === true)
+        if (s.defer === true && !pinned.has(s.name))
             deferred.add(s.name);
     }
     for (const name of opts.mcpToolNames)
-        deferred.add(name);
+        if (!pinned.has(name))
+            deferred.add(name);
     for (const name of opts.deferNames ?? [])
-        deferred.add(name);
+        if (!pinned.has(name))
+            deferred.add(name);
     if (opts.deferMode === "auto") {
-        const candidates = opts.fullTools.filter((t) => !deferred.has(t.name));
+        const candidates = opts.fullTools.filter((t) => !deferred.has(t.name) && !pinned.has(t.name));
         const total = candidates.reduce((n, t) => n + inlinedChars(t), 0);
         const window = (opts.model.contextTokens ?? opts.model.contextWindow ?? 0) * CHARS_PER_TOKEN;
         if (window > 0 && total > DEFER_AUTO_FRACTION * window) {
@@ -52,17 +60,33 @@ export function buildDeferredRegistry(deferred, tools) {
     }
     return reg;
 }
-export function createPlaceholderTool(info) {
+export function createPlaceholderTool(info, direct) {
     const sn = safeName(info.name);
+    const teachingRejection = () => {
+        throw new Error(`Tool "${sn}" is not active yet. Call ${TOOL_SEARCH_NAME} with {"query":"select:${sn}"} ` +
+            `(or a keyword \`query\`) to load its full schema, then call ${sn} with the proper arguments.`);
+    };
+    if (direct !== undefined) {
+        return {
+            name: info.name,
+            label: info.name,
+            description: `${info.hint} — deferred: call ${TOOL_SEARCH_NAME}({"query":"select:${sn}"}) to load its parameters before use.`,
+            parameters: EMPTY_PARAMS,
+            execute: async (toolCallId, params, signal) => {
+                if (Value.Check(direct.parameters, params)) {
+                    await direct.activate();
+                    return direct.invoke(toolCallId, params, signal);
+                }
+                return teachingRejection();
+            },
+        };
+    }
     return defineTool({
         name: info.name,
         description: `${info.hint} — deferred: call ${TOOL_SEARCH_NAME}({"query":"select:${sn}"}) to load its parameters before use.`,
         parameters: EMPTY_PARAMS,
         effect: "read",
-        execute: () => {
-            throw new Error(`Tool "${sn}" is not active yet. Call ${TOOL_SEARCH_NAME} with {"query":"select:${sn}"} ` +
-                `(or a keyword \`query\`) to load its full schema, then call ${sn} with the proper arguments.`);
-        },
+        execute: () => teachingRejection(),
     });
 }
 export function scoreToolMatch(query, info) {
@@ -159,10 +183,14 @@ export function createToolSearchTool(opts) {
         name: TOOL_SEARCH_NAME,
         contract: { contractId: "core.tool_search@1", implementationRevision: "1" },
         description: "Discover and activate deferred tools. Most tools start as name-only placeholders to keep requests " +
-            "small; to USE one you must activate it here first. Query forms: " +
+            "small; to USE one you must activate it here first. When any instruction, reminder, or another " +
+            'tool\'s description names a deferred tool, activate it with query "select:<name>" before calling it. ' +
+            "Query forms: " +
             '"select:ToolA,ToolB" — activate these exact tools by name; ' +
             '"notebook jupyter" — keyword search, up to max_results best matches; ' +
             "a bare tool name — activates that tool directly. " +
+            "Activate every tool you expect to need in one call (select accepts a comma-separated list) " +
+            "rather than one at a time. " +
             "Activated tools become callable with their full parameters on your next turn.",
         parameters: Type.Object({
             query: Type.Optional(Type.String({
@@ -182,7 +210,7 @@ export function createToolSearchTool(opts) {
                 : "";
             const missingNote = callableNote +
                 (missUnknown.length > 0
-                    ? `\nNot found: ${missUnknown.map((n) => safeName(n)).join(", ")} — no deferred tool has this exact name. ` +
+                    ? `\nNot found: ${missUnknown.map((n) => safeName(n)).join(", ")} — not in the deferred registry under this exact name (lookup is case-sensitive). ` +
                         "(Already-active and non-deferred tools are callable directly and don't appear here.)"
                     : "");
             if (matched.length === 0) {

package/dist/core/session-reconcile.d.ts

@@ -4,6 +4,7 @@ import type { ToolEffect } from "./types.js";
 export interface OrphanToolCall {
     toolCallId: string;
     toolName: string;
+    kind?: "result";
 }
 export interface ReconcileReport {
     recovered: Array<OrphanToolCall & {

package/dist/core/session-reconcile.js

@@ -13,6 +13,7 @@ const INTERRUPTED_NEVER_STARTED = "[INTERRUPTED] The run was aborted before this
     "no side effects — it is safe to re-issue this call if you still need it.";
 export function findOrphanToolCalls(messages, suspendedBatch) {
     const resolvedAt = new Map();
+    const callSitesAt = new Map();
     messages.forEach((m, i) => {
         if (m.role === "toolResult") {
             const at = resolvedAt.get(m.toolCallId);
@@ -21,35 +22,54 @@ export function findOrphanToolCalls(messages, suspendedBatch) {
             else
                 at.push(i);
         }
-    });
-    const nextReuseAfter = (id, from) => {
-        for (let i = from + 1; i < messages.length; i++) {
-            const m = messages[i];
-            if (m?.role !== "assistant")
-                continue;
-            if (m.content.some((p) => p.type === "toolCall" && p.id === id))
-                return i;
+        else if (m.role === "assistant") {
+            for (const part of m.content) {
+                if (part.type !== "toolCall")
+                    continue;
+                const at = callSitesAt.get(part.id);
+                if (at === undefined)
+                    callSitesAt.set(part.id, [i]);
+                else
+                    at.push(i);
+            }
         }
-        return Number.POSITIVE_INFINITY;
-    };
+    });
+    const nextReuseAfter = (id, from) => callSitesAt.get(id)?.find((j) => j > from) ?? Number.POSITIVE_INFINITY;
     const orphans = [];
     messages.forEach((m, i) => {
-        if (m.role !== "assistant")
-            return;
-        for (const part of m.content) {
-            if (part.type !== "toolCall" || suspendedBatch?.has(part.id))
-                continue;
-            const bound = nextReuseAfter(part.id, i);
-            const closed = (resolvedAt.get(part.id) ?? []).some((at) => at > i && at < bound);
-            if (!closed)
-                orphans.push({ toolCallId: part.id, toolName: part.name });
+        if (m.role === "assistant") {
+            for (const part of m.content) {
+                if (part.type !== "toolCall" || suspendedBatch?.has(part.id))
+                    continue;
+                const bound = nextReuseAfter(part.id, i);
+                const closed = (resolvedAt.get(part.id) ?? []).some((at) => at > i && at < bound);
+                if (!closed)
+                    orphans.push({ toolCallId: part.id, toolName: part.name });
+            }
+        }
+        else if (m.role === "toolResult") {
+            if (suspendedBatch?.has(m.toolCallId))
+                return;
+            const sites = callSitesAt.get(m.toolCallId) ?? [];
+            const results = resolvedAt.get(m.toolCallId) ?? [];
+            let paired = false;
+            for (const j of sites) {
+                if (j >= i)
+                    break;
+                if (!results.some((at) => at > j && at < i)) {
+                    paired = true;
+                    break;
+                }
+            }
+            if (!paired)
+                orphans.push({ toolCallId: m.toolCallId, toolName: m.toolName, kind: "result" });
         }
     });
     return orphans;
 }
 export async function reconcileInterruptedSession(session, toolEffects, suspendedBatch, startedToolCallIds) {
     const { messages } = await session.buildContext();
-    const orphans = findOrphanToolCalls(messages, suspendedBatch);
+    const orphans = findOrphanToolCalls(messages, suspendedBatch).filter((o) => o.kind !== "result");
     const recovered = [];
     for (const orphan of orphans) {
         const effect = toolEffects?.get(canonicalToolName(orphan.toolName)) ?? "write";

package/dist/core/skills-directory.d.ts

@@ -0,0 +1,13 @@
+import type { SkillSpec } from "./types.js";
+export type SkillsDirectoryWarningCode = "no_skill_file" | "no_frontmatter" | "missing_name" | "invalid_name" | "name_mismatch" | "missing_description" | "description_too_long" | "allowed_tool_not_mounted" | "attachment_skipped" | "read_failed";
+export interface SkillsDirectoryWarning {
+    code: SkillsDirectoryWarningCode;
+    skill: string;
+    detail: string;
+}
+export interface SkillsDirectoryOptions {
+    deployedTools?: readonly string[];
+    onWarning?: (warning: SkillsDirectoryWarning) => void;
+    maxAttachmentBytes?: number;
+}
+export declare function createSkillsFromDirectory(dir: string, options?: SkillsDirectoryOptions): SkillSpec[];

package/dist/core/skills-directory.js

@@ -0,0 +1,214 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+const SKILL_FILE = "SKILL.md";
+const RESOURCE_DIRS = ["assets", "references", "scripts"];
+const NAME_MAX_CHARS = 64;
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const DESCRIPTION_MAX_CHARS = 1024;
+const DEFAULT_MAX_ATTACHMENT_BYTES = 256 * 1024;
+const FENCE = "---";
+function parseSkillFile(text) {
+    const fields = new Map();
+    const normalized = text.replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    if (lines[0]?.trim() !== FENCE)
+        return { fields, body: normalized, hadFrontmatter: false };
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === FENCE) {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return { fields, body: normalized, hadFrontmatter: false };
+    for (let i = 1; i < end; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        if (/^\s/.test(line))
+            continue;
+        const kv = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(trimmed);
+        if (!kv)
+            continue;
+        const [, key, raw] = kv;
+        if (fields.has(key))
+            continue;
+        fields.set(key, unquote(raw.trim()));
+    }
+    let body = lines.slice(end + 1).join("\n");
+    if (body.startsWith("\n"))
+        body = body.slice(1);
+    return { fields, body, hadFrontmatter: true };
+}
+function unquote(value) {
+    if (value.length < 2)
+        return value;
+    const q = value[0];
+    if ((q !== '"' && q !== "'") || value[value.length - 1] !== q)
+        return value;
+    const inner = value.slice(1, -1);
+    return q === '"' ? inner.replace(/\\t/g, "\t").replace(/\\n/g, "\n") : inner;
+}
+function listRelativeFiles(base, dir, prefix, out) {
+    let entries;
+    try {
+        entries = readdirSync(join(base, dir), { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+        const rel = `${prefix}${e.name}`;
+        if (e.isDirectory())
+            listRelativeFiles(base, join(dir, e.name), `${rel}/`, out);
+        else if (e.isFile())
+            out.push(rel);
+    }
+}
+function readAttachments(skillDir, skillName, budgetBytes, warn) {
+    const relPaths = [];
+    for (const d of RESOURCE_DIRS) {
+        let st;
+        try {
+            st = statSync(join(skillDir, d));
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            listRelativeFiles(skillDir, d, `${d}/`, relPaths);
+    }
+    relPaths.sort();
+    const files = [];
+    let spent = 0;
+    for (const rel of relPaths) {
+        let bytes;
+        try {
+            bytes = readFileSync(join(skillDir, rel));
+        }
+        catch (err) {
+            warn({ code: "attachment_skipped", skill: skillName, detail: `${rel}: unreadable (${errText(err)})` });
+            continue;
+        }
+        if (!isDecodableText(bytes)) {
+            warn({ code: "attachment_skipped", skill: skillName, detail: `${rel}: not text (attachment content is a string; binary is not carried)` });
+            continue;
+        }
+        if (spent + bytes.byteLength > budgetBytes) {
+            warn({ code: "attachment_skipped", skill: skillName, detail: `${rel}: over the ${budgetBytes}-byte attachment budget for this skill` });
+            continue;
+        }
+        spent += bytes.byteLength;
+        files.push({ path: rel, content: bytes.toString("utf8") });
+    }
+    return files;
+}
+function isDecodableText(bytes) {
+    if (bytes.includes(0))
+        return false;
+    const decoded = bytes.toString("utf8");
+    return Buffer.byteLength(decoded, "utf8") === bytes.byteLength;
+}
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function manifestFromAllowedTools(declared, skillName, deployedTools, warn) {
+    const names = [];
+    for (const n of declared.split(/\s+/)) {
+        if (n !== "" && !names.includes(n))
+            names.push(n);
+    }
+    if (names.length === 0)
+        return undefined;
+    let allowTools = names;
+    if (deployedTools !== undefined) {
+        const mounted = new Set(deployedTools);
+        allowTools = names.filter((n) => mounted.has(n));
+        for (const n of names) {
+            if (!mounted.has(n)) {
+                warn({
+                    code: "allowed_tool_not_mounted",
+                    skill: skillName,
+                    detail: `allowed-tools names "${n}", which this deployment does not mount — dropped (a skill declaration may only narrow capability, never add a tool)`,
+                });
+            }
+        }
+    }
+    return { allowTools, lineageId: `skill:${skillName}` };
+}
+export function createSkillsFromDirectory(dir, options = {}) {
+    const warn = (w) => {
+        options.onWarning?.(w);
+    };
+    const budget = options.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES;
+    let entries;
+    try {
+        const st = statSync(dir);
+        if (!st.isDirectory())
+            throw new Error("not a directory");
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        throw new Error(`skills directory could not be read: ${dir} (${errText(err)})`);
+    }
+    const dirNames = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    const skills = [];
+    for (const name of dirNames) {
+        const skillDir = join(dir, name);
+        let text;
+        try {
+            text = readFileSync(join(skillDir, SKILL_FILE), "utf8");
+        }
+        catch {
+            warn({ code: "no_skill_file", skill: name, detail: `no ${SKILL_FILE} in this directory — skipped` });
+            continue;
+        }
+        const parsed = parseSkillFile(text);
+        if (!parsed.hadFrontmatter) {
+            warn({ code: "no_frontmatter", skill: name, detail: `${SKILL_FILE} has no fenced --- frontmatter block — skipped` });
+            continue;
+        }
+        const declaredName = parsed.fields.get("name");
+        if (declaredName === undefined || declaredName === "") {
+            warn({ code: "missing_name", skill: name, detail: "frontmatter has no `name` (required) — skipped" });
+            continue;
+        }
+        if (declaredName.length > NAME_MAX_CHARS || !NAME_RE.test(declaredName)) {
+            warn({
+                code: "invalid_name",
+                skill: name,
+                detail: `\`name\` must be ≤${NAME_MAX_CHARS} chars of lowercase alphanumerics in hyphen-separated runs — skipped`,
+            });
+            continue;
+        }
+        if (declaredName !== name) {
+            warn({ code: "name_mismatch", skill: name, detail: `frontmatter \`name\` is "${declaredName}" but the directory is "${name}" — skipped` });
+            continue;
+        }
+        const description = parsed.fields.get("description");
+        if (description === undefined || description === "") {
+            warn({ code: "missing_description", skill: name, detail: "frontmatter has no `description` (required) — skipped" });
+            continue;
+        }
+        if (description.length > DESCRIPTION_MAX_CHARS) {
+            warn({ code: "description_too_long", skill: name, detail: `\`description\` is ${description.length} chars, over the ${DESCRIPTION_MAX_CHARS} cap — skipped` });
+            continue;
+        }
+        const allowed = parsed.fields.get("allowed-tools");
+        const manifest = allowed === undefined ? undefined : manifestFromAllowedTools(allowed, name, options.deployedTools, warn);
+        const files = readAttachments(skillDir, name, budget, warn);
+        skills.push({
+            name: declaredName,
+            description,
+            content: parsed.body,
+            ...(manifest !== undefined ? { manifest } : {}),
+            ...(files.length > 0 ? { files } : {}),
+        });
+    }
+    return skills;
+}

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

@@ -68,6 +68,7 @@ export declare function settleBackgroundAgentLane(core: DurableAgentCore, id: st
     error?: string;
     errorCode?: string;
     retryable?: boolean;
+    errorKind?: string;
     stoppedBy?: StopSource;
     seq?: number;
 }): "completed" | "failed" | "killed" | undefined;
@@ -102,6 +103,7 @@ export declare function settleRevivedAgentLane(core: DurableAgentCore, id: strin
     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

@@ -706,6 +706,8 @@ export function settleBackgroundAgentLane(core, id, outcome) {
             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)
@@ -844,6 +846,9 @@ 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;
@@ -1030,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) {
@@ -1065,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
@@ -1072,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 {
@@ -1092,6 +1101,7 @@ ${resultText}` : "(no result text)"}`;
             ...(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-shared.d.ts

@@ -139,6 +139,7 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
     error?: string;
     errorCode?: string;
     errorRetryable?: boolean;
+    errorKind?: string;
     resultIsPartial?: boolean;
     stopSource?: StopSource;
     stoppedBy?: StopSource;

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

@@ -135,6 +135,7 @@ export declare class TaskRegistry {
         error?: string;
         errorCode?: string;
         retryable?: boolean;
+        errorKind?: string;
         stoppedBy?: StopSource;
         seq?: number;
     }): "completed" | "failed" | "killed" | undefined;
@@ -170,6 +171,7 @@ export declare class TaskRegistry {
         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;

package/dist/core/task-registry.js

@@ -368,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")

package/dist/core/trace.d.ts

@@ -138,6 +138,7 @@ export type TraceEvent = {
     taskId: string;
     model: string;
     provider?: string;
+    turn?: number;
     promptTokens: number;
     completionTokens: number;
     cacheRead: number;
@@ -155,6 +156,8 @@ export type TraceEvent = {
     version: 1;
     taskId: string;
     name: string;
+    toolCallId?: string;
+    turn?: number;
     durationMs: number;
     ok: boolean;
     effect?: ToolEffect;

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,8 @@ export interface TaskSpec {
     tools?: ToolSpec[];
     excludeTools?: string[];
     deferTools?: string[];
+    alwaysLoadTools?: string[];
+    deferSelfResolve?: boolean;
     promptProfile?: "simple" | "classic";
     agents?: AgentDefinition[];
     toolPolicy?: import("./tool-policy.js").ToolPolicy;
@@ -514,9 +517,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 +537,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>;