@sema-agent/core 2.8.0 → 2.9.0

package/dist/core/runner/runtask.js

@@ -688,13 +688,6 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     queue.push({ type: "compaction_outcome", outcome, trigger: passTrigger, ...ident() });
                 }
             }
-            if (comp.compacted && !forceManual) {
-                if (recordCompactionAndCheckRapidRefill(rapidRefill, stats.turns)) {
-                    compactionBreaker.failures = MAX_CONSECUTIVE_COMPACTION_FAILURES;
-                    runnerHooks.onError?.(new Error("compaction.rapid_refill: the context refilled within <3 turns of compaction 3 times in a row — compaction disabled for the rest of this task (thrash spiral; the transcript is dominated by incompressible content)"), { phase: "compaction", sessionId: prepared.sessionId });
-                    queue.push({ type: "compaction_outcome", outcome: "disabled", trigger: passTrigger, reason: "rapid_refill: compaction disabled for the rest of this task", ...ident() });
-                }
-            }
             runnerHooks.recordCompactionReuse(prepared, comp);
             if (comp.compacted) {
                 queue.push({
@@ -713,6 +706,11 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     ...(comp.clampReason !== undefined ? { clampReason: comp.clampReason } : {}),
                     ...ident(),
                 });
+                if (!forceManual && recordCompactionAndCheckRapidRefill(rapidRefill, stats.turns)) {
+                    compactionBreaker.failures = MAX_CONSECUTIVE_COMPACTION_FAILURES;
+                    queue.push({ type: "compaction_outcome", outcome: "disabled", trigger: passTrigger, reason: "rapid_refill: compaction disabled for the rest of this task", ...ident() });
+                    runnerHooks.onError?.(new Error("compaction.rapid_refill: the context refilled within <3 turns of compaction 3 times in a row — compaction disabled for the rest of this task (thrash spiral; the transcript is dominated by incompressible content)"), { phase: "compaction", sessionId: prepared.sessionId });
+                }
                 if (comp.phaseDurations !== undefined && comp.durationMs !== undefined) {
                     const pd = comp.phaseDurations;
                     const pdDur = comp.durationMs;
@@ -2074,6 +2072,9 @@ export class Runner {
                 phase: s.phase,
                 ...(s.detail !== undefined ? { detail: s.detail } : {}),
                 ...(s.retryInSec !== undefined ? { retryInSec: s.retryInSec } : {}),
+                ...(s.retryInMs !== undefined ? { retryInMs: s.retryInMs } : {}),
+                ...(s.attempt !== undefined ? { attempt: s.attempt } : {}),
+                ...(s.maxRetries !== undefined ? { maxRetries: s.maxRetries } : {}),
                 ...ident(),
             });
         };
@@ -2675,6 +2676,7 @@ export class Runner {
             minTokens: rs.counters.compactionFloor,
             brain: compactionBrain,
             windowSafety: windowSafetyOptions(prepared.model),
+            onCompactionFailed: (reason) => queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "auto", reason, ...ident() }),
         });
         try {
             if (comp?.compacted) {
@@ -3516,6 +3518,17 @@ export class Runner {
                 comp = finishComp;
             }
             catch (err) {
+                const failMsg = String(err instanceof Error ? err.message : err);
+                const failReason = failMsg.length > 512 ? `${failMsg.slice(0, 512)}…` : failMsg;
+                emitTrace(spec.tracer ?? this.deps.tracer, () => ({
+                    kind: "compaction.failed",
+                    version: 1,
+                    taskId: spec.taskId ?? prepared.sessionId,
+                    trigger: "auto",
+                    reason: failReason,
+                    ts: Date.now(),
+                }));
+                opts?.onCompactionFailed?.(failReason);
                 this.deps.onError?.(err, { phase: "compaction", sessionId: prepared.sessionId });
             }
         }

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

@@ -1,5 +1,5 @@
 import { type TSchema } from "typebox";
-import type { AgentMessage, AgentTool, AgentToolResult } from "../../internal/harness-types.js";
+import type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode } from "../../internal/harness-types.js";
 import type { Model } from "../../internal/llm.js";
 import type { ToolSpec } from "../types.js";
 export declare const TOOL_SEARCH_NAME = "ToolSearch";
@@ -29,10 +29,14 @@ export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, too
     description: string;
 }>): Map<string, DeferredToolInfo>;
 export interface PlaceholderDirectCall {
-    parameters: TSchema;
-    invoke: (toolCallId: string, params: unknown, signal?: AbortSignal) => Promise<AgentToolResult<unknown>>;
+    resolveReal: () => PlaceholderDirectTarget | undefined;
+    executionMode?: ToolExecutionMode;
     activate: () => Promise<void>;
 }
+export interface PlaceholderDirectTarget {
+    parameters: TSchema;
+    invoke: (toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<unknown>) => Promise<AgentToolResult<unknown>>;
+}
 export declare function createPlaceholderTool(info: DeferredToolInfo, direct?: PlaceholderDirectCall): AgentTool;
 export declare function scoreToolMatch(query: string, info: DeferredToolInfo): number;
 export interface ToolSearchArgs {
@@ -52,4 +56,5 @@ export declare function createToolSearchTool(opts: {
     rematerialize: (active: ReadonlySet<string>) => Promise<void>;
     listingRide?: (newlyActivated: readonly string[]) => string | undefined;
     mountedNames?: () => ReadonlySet<string>;
+    directCallEnabled?: boolean;
 }): AgentTool;

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

@@ -43,7 +43,8 @@ export function classifyDeferred(opts) {
             deferred.add(name);
     if (opts.deferMode === "auto") {
         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 inlineFace = opts.fullTools.filter((t) => !deferred.has(t.name));
+        const total = inlineFace.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) {
             for (const t of candidates)
@@ -70,12 +71,16 @@ export function createPlaceholderTool(info, direct) {
         return {
             name: info.name,
             label: info.name,
-            description: `${info.hint} — deferred: call ${TOOL_SEARCH_NAME}({"query":"select:${sn}"}) to load its parameters before use.`,
+            description: `${info.hint} — deferred: its parameters are not listed here. Call ` +
+                `${TOOL_SEARCH_NAME}({"query":"select:${sn}"}) to load them; a call that already matches this ` +
+                `tool's real parameters runs directly and activates it.`,
             parameters: EMPTY_PARAMS,
-            execute: async (toolCallId, params, signal) => {
-                if (Value.Check(direct.parameters, params)) {
+            ...(direct.executionMode !== undefined ? { executionMode: direct.executionMode } : {}),
+            execute: async (toolCallId, params, signal, onUpdate) => {
+                const real = direct.resolveReal();
+                if (real !== undefined && Value.Check(real.parameters, params)) {
                     await direct.activate();
-                    return direct.invoke(toolCallId, params, signal);
+                    return real.invoke(toolCallId, params, signal, onUpdate);
                 }
                 return teachingRejection();
             },
@@ -178,13 +183,22 @@ export function extractDiscoveredToolNames(messages, registry) {
 }
 export function createToolSearchTool(opts) {
     const { registry, active, rematerialize, listingRide, mountedNames } = opts;
+    const directCallEnabled = opts.directCallEnabled !== false;
+    const activationPosture = directCallEnabled
+        ? "Most tools start as name-only placeholders to keep requests small; activating one here loads its full " +
+            "parameter schema. Until you have that schema you cannot reliably form a call, so activate a tool rather " +
+            "than guessing its arguments — a call that does match the real schema executes and activates the tool. " +
+            "When any instruction, reminder, or another tool's description names a deferred tool, activate it here " +
+            'with query "select:<name>". '
+        : "Most tools start as name-only placeholders to keep requests 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. ';
     let activationChain = Promise.resolve();
     return defineTool({
         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. When any instruction, reminder, or another " +
-            'tool\'s description names a deferred tool, activate it with query "select:<name>" before calling it. ' +
+        description: "Discover and activate deferred tools. " +
+            activationPosture +
             "Query forms: " +
             '"select:ToolA,ToolB" — activate these exact tools by name; ' +
             '"notebook jupyter" — keyword search, up to max_results best matches; ' +

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

@@ -1,5 +1,5 @@
 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 type SkillsDirectoryWarningCode = "no_skill_file" | "no_frontmatter" | "missing_name" | "invalid_name" | "name_mismatch" | "missing_description" | "description_too_long" | "allowed_tool_not_mounted" | "disallowed_tools_unenforced" | "attachment_skipped" | "read_failed";
 export interface SkillsDirectoryWarning {
     code: SkillsDirectoryWarningCode;
     skill: string;

package/dist/core/skills-directory.js

@@ -1,5 +1,6 @@
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { canonicalToolName } from "./tool-name-aliases.js";
 const SKILL_FILE = "SKILL.md";
 const RESOURCE_DIRS = ["assets", "references", "scripts"];
 const NAME_MAX_CHARS = 64;
@@ -22,26 +23,139 @@ function parseSkillFile(text) {
     }
     if (end === -1)
         return { fields, body: normalized, hadFrontmatter: false };
-    for (let i = 1; i < end; i++) {
+    let i = 1;
+    while (i < end) {
         const line = lines[i];
         const trimmed = line.trim();
-        if (trimmed === "" || trimmed.startsWith("#"))
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            i++;
             continue;
-        if (/^\s/.test(line))
+        }
+        if (/^\s/.test(line)) {
+            i++;
             continue;
+        }
         const kv = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(trimmed);
-        if (!kv)
+        if (!kv) {
+            i++;
             continue;
+        }
         const [, key, raw] = kv;
+        const rawValue = raw.trim();
+        const block = parseBlockScalarHeader(rawValue);
+        if (block !== undefined) {
+            const read = readBlockScalar(lines, i + 1, end, block);
+            i = read.next;
+            if (!fields.has(key))
+                fields.set(key, read.value);
+            continue;
+        }
+        if (rawValue.startsWith("[") && !isFlowSequenceClosed(rawValue)) {
+            const joined = readFlowSequenceContinuation(lines, i + 1, end, rawValue);
+            i = joined.next;
+            if (!fields.has(key))
+                fields.set(key, joined.value);
+            continue;
+        }
+        i++;
         if (fields.has(key))
             continue;
-        fields.set(key, unquote(raw.trim()));
+        fields.set(key, unquote(rawValue));
     }
     let body = lines.slice(end + 1).join("\n");
     if (body.startsWith("\n"))
         body = body.slice(1);
     return { fields, body, hadFrontmatter: true };
 }
+function parseBlockScalarHeader(value) {
+    const m = /^([|>])([0-9+-]*)$/.exec(value);
+    if (!m)
+        return undefined;
+    const rest = m[2];
+    if (!/^(?:[1-9]?[+-]?|[+-][1-9]?)$/.test(rest))
+        return undefined;
+    const digit = /[1-9]/.exec(rest)?.[0];
+    return { style: m[1] === "|" ? "literal" : "folded", ...(digit !== undefined ? { indent: Number(digit) } : {}) };
+}
+function readBlockScalar(lines, start, end, header) {
+    const indentOf = (s) => /^[ \t]*/.exec(s)[0].length;
+    let indent = header.indent;
+    if (indent === undefined) {
+        for (let j = start; j < end; j++) {
+            if (lines[j].trim() === "")
+                continue;
+            indent = indentOf(lines[j]);
+            break;
+        }
+    }
+    if (indent === undefined || indent === 0)
+        return { value: "", next: start };
+    const taken = [];
+    let j = start;
+    for (; j < end; j++) {
+        const line = lines[j];
+        if (line.trim() === "") {
+            taken.push("");
+            continue;
+        }
+        if (indentOf(line) < indent)
+            break;
+        taken.push(line.slice(indent));
+    }
+    while (taken.length > 0 && taken[taken.length - 1] === "")
+        taken.pop();
+    if (header.style === "literal")
+        return { value: taken.join("\n"), next: j };
+    let folded = "";
+    let blanks = 0;
+    let started = false;
+    let prevMoreIndented = false;
+    for (const cur of taken) {
+        if (cur === "") {
+            blanks++;
+            continue;
+        }
+        const moreIndented = indentOf(cur) > 0;
+        if (!started) {
+            folded = cur;
+            started = true;
+        }
+        else if (blanks > 0) {
+            folded += "\n".repeat(blanks) + cur;
+        }
+        else if (moreIndented || prevMoreIndented) {
+            folded += `\n${cur}`;
+        }
+        else {
+            folded += ` ${cur}`;
+        }
+        blanks = 0;
+        prevMoreIndented = moreIndented;
+    }
+    return { value: folded, next: j };
+}
+function isFlowSequenceClosed(text) {
+    let depth = 0;
+    for (const ch of text) {
+        if (ch === "[")
+            depth++;
+        else if (ch === "]")
+            depth--;
+    }
+    return depth <= 0;
+}
+function readFlowSequenceContinuation(lines, start, end, head) {
+    let acc = head;
+    let j = start;
+    for (; j < end; j++) {
+        acc += ` ${lines[j].trim()}`;
+        if (isFlowSequenceClosed(acc)) {
+            j++;
+            break;
+        }
+    }
+    return { value: acc, next: j };
+}
 function unquote(value) {
     if (value.length < 2)
         return value;
@@ -51,7 +165,13 @@ function unquote(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) {
+function isInsideRoot(root, p) {
+    if (p === root)
+        return true;
+    const rel = relative(root, p);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function listRelativeFiles(base, dir, prefix, out, walk) {
     let entries;
     try {
         entries = readdirSync(join(base, dir), { withFileTypes: true });
@@ -61,24 +181,68 @@ function listRelativeFiles(base, dir, prefix, out) {
     }
     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())
+        const abs = join(base, dir, e.name);
+        const resolved = resolveInsideSkill(abs, rel, walk);
+        if (resolved === undefined)
+            continue;
+        if (resolved.stats.isDirectory()) {
+            if (walk.visited.has(resolved.real))
+                continue;
+            walk.visited.add(resolved.real);
+            listRelativeFiles(base, join(dir, e.name), `${rel}/`, out, walk);
+        }
+        else if (resolved.stats.isFile()) {
             out.push(rel);
+        }
+    }
+}
+function resolveInsideSkill(abs, rel, walk) {
+    let real;
+    let stats;
+    try {
+        real = realpathSync(abs);
+        stats = statSync(abs);
+    }
+    catch (err) {
+        walk.warn({ code: "attachment_skipped", skill: walk.skill, detail: `${rel}: could not be resolved (${errText(err)})` });
+        return undefined;
+    }
+    if (!isInsideRoot(walk.realRoot, real)) {
+        walk.warn({
+            code: "attachment_skipped",
+            skill: walk.skill,
+            detail: `${rel}: resolves outside the skill directory — skipped (attachments are collected from the declared skill directory only)`,
+        });
+        return undefined;
     }
+    return { real, stats };
 }
 function readAttachments(skillDir, skillName, budgetBytes, warn) {
+    let realRoot;
+    try {
+        realRoot = realpathSync(skillDir);
+    }
+    catch (err) {
+        warn({ code: "read_failed", skill: skillName, detail: `the skill directory could not be resolved (${errText(err)}) — attachments skipped` });
+        return [];
+    }
+    const walk = { realRoot, skill: skillName, warn, visited: new Set([realRoot]) };
     const relPaths = [];
     for (const d of RESOURCE_DIRS) {
-        let st;
+        let exists = true;
         try {
-            st = statSync(join(skillDir, d));
+            statSync(join(skillDir, d));
         }
         catch {
-            continue;
+            exists = false;
         }
-        if (st.isDirectory())
-            listRelativeFiles(skillDir, d, `${d}/`, relPaths);
+        if (!exists)
+            continue;
+        const resolved = resolveInsideSkill(join(skillDir, d), d, walk);
+        if (resolved === undefined || !resolved.stats.isDirectory())
+            continue;
+        walk.visited.add(resolved.real);
+        listRelativeFiles(skillDir, d, `${d}/`, relPaths, walk);
     }
     relPaths.sort();
     const files = [];
@@ -114,20 +278,60 @@ function isDecodableText(bytes) {
 function errText(err) {
     return err instanceof Error ? err.message : String(err);
 }
-function manifestFromAllowedTools(declared, skillName, deployedTools, warn) {
+const ALL_TOOLS_WILDCARD = "*";
+function splitToolNames(declared) {
+    let text = declared.trim();
+    if (text.startsWith("[") && text.endsWith("]"))
+        text = text.slice(1, -1);
     const names = [];
-    for (const n of declared.split(/\s+/)) {
-        if (n !== "" && !names.includes(n))
-            names.push(n);
+    let current = "";
+    let depth = 0;
+    const flush = () => {
+        const name = unquote(current.trim());
+        if (name !== "")
+            names.push(name);
+        current = "";
+    };
+    for (const ch of text) {
+        if (ch === "(") {
+            depth++;
+            current += ch;
+        }
+        else if (ch === ")") {
+            if (depth > 0)
+                depth--;
+            current += ch;
+        }
+        else if (depth === 0 && (ch === "," || /\s/.test(ch))) {
+            flush();
+        }
+        else {
+            current += ch;
+        }
+    }
+    flush();
+    return names;
+}
+function manifestFromAllowedTools(declared, disallowed, skillName, deployedTools, warn) {
+    const names = [];
+    const seen = new Set();
+    for (const n of splitToolNames(declared)) {
+        const key = canonicalToolName(n);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        names.push(n);
     }
     if (names.length === 0)
         return undefined;
+    if (names.some((n) => n === ALL_TOOLS_WILDCARD))
+        return undefined;
     let allowTools = names;
     if (deployedTools !== undefined) {
-        const mounted = new Set(deployedTools);
-        allowTools = names.filter((n) => mounted.has(n));
+        const mounted = new Set(deployedTools.map(canonicalToolName));
+        allowTools = names.filter((n) => mounted.has(canonicalToolName(n)));
         for (const n of names) {
-            if (!mounted.has(n)) {
+            if (!mounted.has(canonicalToolName(n))) {
                 warn({
                     code: "allowed_tool_not_mounted",
                     skill: skillName,
@@ -136,6 +340,10 @@ function manifestFromAllowedTools(declared, skillName, deployedTools, warn) {
             }
         }
     }
+    if (disallowed.length > 0) {
+        const denied = new Set(disallowed.map(canonicalToolName));
+        allowTools = allowTools.filter((n) => !denied.has(canonicalToolName(n)));
+    }
     return { allowTools, lineageId: `skill:${skillName}` };
 }
 export function createSkillsFromDirectory(dir, options = {}) {
@@ -153,10 +361,23 @@ export function createSkillsFromDirectory(dir, options = {}) {
     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 dirNames = [];
+    for (const e of entries) {
+        if (e.isDirectory()) {
+            dirNames.push(e.name);
+            continue;
+        }
+        if (!e.isSymbolicLink())
+            continue;
+        try {
+            if (statSync(join(dir, e.name)).isDirectory())
+                dirNames.push(e.name);
+        }
+        catch (err) {
+            warn({ code: "read_failed", skill: e.name, detail: `entry is a symbolic link that could not be resolved (${errText(err)}) — skipped` });
+        }
+    }
+    dirNames.sort();
     const skills = [];
     for (const name of dirNames) {
         const skillDir = join(dir, name);
@@ -200,7 +421,15 @@ export function createSkillsFromDirectory(dir, options = {}) {
             continue;
         }
         const allowed = parsed.fields.get("allowed-tools");
-        const manifest = allowed === undefined ? undefined : manifestFromAllowedTools(allowed, name, options.deployedTools, warn);
+        const disallowed = splitToolNames(parsed.fields.get("disallowed-tools") ?? "");
+        const manifest = allowed === undefined ? undefined : manifestFromAllowedTools(allowed, disallowed, name, options.deployedTools, warn);
+        if (disallowed.length > 0 && manifest === undefined) {
+            warn({
+                code: "disallowed_tools_unenforced",
+                skill: name,
+                detail: `disallowed-tools names ${disallowed.map((n) => `"${n}"`).join(", ")}, but this skill produced no allowlist to subtract from (allowed-tools is absent or claims every tool) — the deny declaration is NOT enforced (express it in the task's own tool policy)`,
+            });
+        }
         const files = readAttachments(skillDir, name, budget, warn);
         skills.push({
             name: declaredName,

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

@@ -2,7 +2,7 @@ import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./backgro
 import { type StopSource, type TaskAccess, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
 import { type ToolResultStore } from "./tool-result-store.js";
 export declare function ensureDurableHeartbeatLane(core: DurableAgentCore): void;
-export declare function durableAgentWriteLane(handle: BackgroundAgentTaskHandle, patch: Partial<BackgroundAgentRecord>, clear?: (keyof BackgroundAgentRecord)[]): void;
+export declare function durableAgentWriteLane(handle: BackgroundAgentTaskHandle, patch: Partial<BackgroundAgentRecord>, clear?: readonly (keyof BackgroundAgentRecord)[]): void;
 export declare function durableAgentArmedLane(core: DurableAgentCore, id: string): boolean;
 export declare function durableAgentRowProbeLane(core: DurableAgentCore, id: string): (() => Promise<boolean>) | undefined;
 export declare function beginDurableClaimLane(core: DurableAgentCore, id: string): boolean;
@@ -71,6 +71,7 @@ export declare function settleBackgroundAgentLane(core: DurableAgentCore, id: st
     errorKind?: string;
     stoppedBy?: StopSource;
     seq?: number;
+    cycle?: number;
 }): "completed" | "failed" | "killed" | undefined;
 export declare function abortBackgroundAgentsForOwnerLane(core: DurableAgentCore, access: TaskAccess, opts?: {
     skipSessionScoped?: boolean;