@sema-agent/core 2.5.0 → 2.7.0

package/dist/core/background-agent-store.d.ts

@@ -37,6 +37,9 @@ export interface BackgroundAgentRecord {
     finalOutput?: string;
     finalOutputFull?: string;
     error?: string;
+    errorCode?: string;
+    errorRetryable?: boolean;
+    errorKind?: string;
     resultIsPartial?: boolean;
     recentSteps?: SubagentStep[];
     editedFiles?: SubagentEditedFile[];

package/dist/core/mcp.d.ts

@@ -68,6 +68,7 @@ export declare function mcpToolTotalTimeoutMs(perCallMs: number): number;
 export declare const MCP_IDLE_TIMEOUT_STDIO_DEFAULT_MS: number;
 export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
 export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
+export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
 export declare function normalizeMcpName(name: string): string;
 export declare function clampNameSegment(seg: string, max?: number): string;
 export * from "./image-downsample.js";
@@ -106,3 +107,11 @@ export type McpSchemaNormalizeResult = {
 export declare function normalizeMcpToolSchema(schema: unknown): McpSchemaNormalizeResult;
 export declare function mcpToolSchemaProblem(schema: unknown): string | undefined;
 export declare function materializeMcpTools(specs: McpServerSpec[], principal?: string, onElicit?: OnElicit, imageResizer?: McpImageResizer): Promise<MaterializedMcp>;
+export declare function classifyDirReadInvalidParams(message: string): "not_found" | "not_directory";
+export declare function parseCallToolResultLenient(data: unknown): {
+    success: true;
+    data: unknown;
+} | {
+    success: false;
+    error: unknown;
+};

package/dist/core/mcp.js

@@ -5,7 +5,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { ElicitRequestSchema, ErrorCode, ListResourcesResultSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolResultSchema, ElicitRequestSchema, ErrorCode, ListResourcesResultSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { MCP_IMAGE_MAX_BASE64, sharpImageResizer } from "./image-downsample.js";
 import { truncateError } from "./tool-errors.js";
 import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
@@ -137,6 +137,14 @@ function armMcpIdleWatchdog(health, idleMs, outerSignal) {
 function mcpStartupTimeoutMs() {
     return parseEnvMs("MCP_TIMEOUT");
 }
+const MCP_SPEC_ERROR_CODE_NAMES = new Map([
+    [-32020, "header mismatch (the server saw an HTTP header that disagreed with the tool parameter mapped onto it)"],
+    [-32021, "missing required client capability (the server requires a capability this client does not declare)"],
+    [-32022, "unsupported protocol version (the server implements no protocol revision this client offers)"],
+]);
+export function describeMcpSpecErrorCode(code) {
+    return typeof code === "number" ? MCP_SPEC_ERROR_CODE_NAMES.get(code) : undefined;
+}
 function isTransportLost(err) {
     if (err instanceof McpError && err.code === ErrorCode.ConnectionClosed)
         return true;
@@ -180,6 +188,15 @@ function rethrowHonestMcpError(err, ctx) {
         e.details = { transportLost: true, server: ctx.server };
         throw e;
     }
+    if (err instanceof McpError) {
+        const condition = describeMcpSpecErrorCode(err.code);
+        if (condition !== undefined) {
+            const e = new Error(`${ctx.what} on MCP server "${serverLabel}" was rejected with MCP protocol error ${err.code} — ${condition}. The server's error text follows as external/untrusted data:\n${delimitUntrusted(`${ctx.server} error`, truncateMcpErrorText(err.message))}`, { cause: err });
+            e.errorKind = "protocol_error";
+            e.details = { server: ctx.server, specErrorCode: err.code };
+            throw e;
+        }
+    }
     if (ctx.attributeServer) {
         const msg = err instanceof Error ? err.message : String(err);
         throw new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${delimitUntrusted(`${ctx.server} error`, truncateMcpErrorText(msg))}`, { cause: err });
@@ -653,6 +670,15 @@ const LEGACY_READ_MCP_RESOURCE = "ReadMcpResource";
 const LEGACY_READ_MCP_RESOURCE_DIR = "ReadMcpResourceDir";
 const MCP_SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
 const MAX_DIR_READ_PAGES = 20;
+const DIR_READ_NOT_A_DIRECTORY_RE = /not a directory|isn'?t a directory|not a folder/i;
+const DIR_READ_NOT_FOUND_RE = /not found|no such|does not exist|doesn'?t exist|unknown (?:resource|uri)/i;
+export function classifyDirReadInvalidParams(message) {
+    if (DIR_READ_NOT_A_DIRECTORY_RE.test(message))
+        return "not_directory";
+    if (DIR_READ_NOT_FOUND_RE.test(message))
+        return "not_found";
+    return "not_directory";
+}
 function resourceLine(r) {
     return `${r.uri}${r.name ? ` — ${r.name}` : ""}${r.mimeType ? ` (${r.mimeType})` : ""}${r.description ? `: ${r.description}` : ""}`;
 }
@@ -672,7 +698,7 @@ async function readDirViaExtension(rs, uri, signal, timeoutMs, watchdog) {
             if (err instanceof McpError && err.code === ErrorCode.InvalidParams) {
                 if (pages > 0)
                     return { kind: "ok", resources, cursorInvalid: true };
-                return { kind: "not_directory" };
+                return { kind: classifyDirReadInvalidParams(err.message), detail: err.message };
             }
             if (err instanceof McpError && err.code === ErrorCode.MethodNotFound)
                 return { kind: "unsupported" };
@@ -866,9 +892,22 @@ function buildResourceTools(resourceServers) {
                     const ext = rs.client.getServerCapabilities()?.extensions?.[MCP_SKILLS_EXTENSION];
                     if (ext?.directoryRead === true) {
                         const r = await readDirViaExtension(rs, uri, signal, timeoutMs, watchdog).catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs } }));
+                        const serverSaid = (detail) => `\nThe server's error text follows as external/untrusted data:\n${delimitUntrusted(`${server} error`, truncateMcpErrorText(detail))}`;
+                        if (r.kind === "not_found") {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `Resource not found: ${inlineUntrusted(uri)} — the server reports no such resource, so re-reading it will not help either. Use ${LIST_MCP_RESOURCES} to see what this server exposes.${serverSaid(r.detail)}`,
+                                    },
+                                ],
+                                details: { resources: [], notFound: true },
+                                terminate: false,
+                            };
+                        }
                         if (r.kind === "not_directory") {
                             return {
-                                content: [{ type: "text", text: `Not a directory resource: ${inlineUntrusted(uri)}. If it is a file resource, use ${READ_MCP_RESOURCE} instead.` }],
+                                content: [{ type: "text", text: `Not a directory resource: ${inlineUntrusted(uri)}. If it is a file resource, use ${READ_MCP_RESOURCE} instead.${serverSaid(r.detail)}` }],
                                 details: { resources: [] },
                                 terminate: false,
                             };
@@ -929,6 +968,17 @@ const LenientListToolsResultSchema = {
         return { success: true, data: { tools, ...(typeof nextCursor === "string" ? { nextCursor } : {}) } };
     },
 };
+export function parseCallToolResultLenient(data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data) || !("structuredContent" in data)) {
+        return CallToolResultSchema.safeParse(data);
+    }
+    const { structuredContent, ...rest } = data;
+    const parsed = CallToolResultSchema.safeParse(rest);
+    if (!parsed.success)
+        return parsed;
+    return { success: true, data: { ...parsed.data, structuredContent } };
+}
+const LENIENT_CALL_TOOL_RESULT_SCHEMA = { safeParse: parseCallToolResultLenient };
 async function listToolsLenient(client, options) {
     return client.request({ method: "tools/list", params: {} }, LenientListToolsResultSchema, options);
 }
@@ -1059,7 +1109,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer) {
                 let res;
                 try {
                     res = await client
-                        .callTool({ name: remoteName, arguments: (params ?? {}) }, undefined, {
+                        .callTool({ name: remoteName, arguments: (params ?? {}) }, LENIENT_CALL_TOOL_RESULT_SCHEMA, {
                         signal: watchdog.combinedSignal,
                         timeout: timeoutMs,
                         resetTimeoutOnProgress: true,
@@ -1106,7 +1156,8 @@ function intakeListedTools(listed, spec, client, health, imageResizer) {
 }
 function asServerWarning(spec, err) {
     const detail = err instanceof Error ? err.message : String(err);
-    const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${detail})`, { cause: err });
+    const condition = err instanceof McpError ? describeMcpSpecErrorCode(err.code) : undefined;
+    const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${condition !== undefined ? `${condition}: ` : ""}${detail})`, { cause: err });
     warning.code = "mcp.server_unavailable";
     return warning;
 }

package/dist/core/runner/prepare-task.js

@@ -1225,14 +1225,18 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 shellGatedBash = !egressTools.has("Bash") && !irreversibilityTier.has("Bash");
                 irreversibilityTier.set("Bash", shellGate === "always" ? "always" : "maybe");
                 irreversibleTools.add("Bash");
+                const shellReadBoundary = () => ({
+                    roots: [rootCanonical, ...additionalRootsCanonical],
+                    ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
+                });
                 if (shellGate === "classify")
-                    reversibilityProbes.set("Bash", bashReversibilityProbe());
+                    reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
                 if (backgroundTaskToolsActive) {
                     shellGatedMonitor = !egressTools.has("Monitor") && !irreversibilityTier.has("Monitor");
                     irreversibilityTier.set("Monitor", shellGate === "always" ? "always" : "maybe");
                     irreversibleTools.add("Monitor");
                     if (shellGate === "classify")
-                        reversibilityProbes.set("Monitor", bashReversibilityProbe());
+                        reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
                 }
             }
         }
@@ -1826,7 +1830,25 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 throw e;
             }
             const registry = buildDeferredRegistry(deferred, tools);
-            const placeholders = new Map([...registry.values()].map((i) => [i.name, createPlaceholderTool(i)]));
+            const realByName = new Map(tools.map((t) => [t.name, t]));
+            const directCallFor = (name) => {
+                if (spec.deferSelfResolve === false)
+                    return undefined;
+                const real = realByName.get(name);
+                if (real === undefined)
+                    return undefined;
+                return {
+                    parameters: real.parameters,
+                    invoke: (toolCallId, params, signal) => real.execute(toolCallId, params, signal),
+                    activate: async () => {
+                        if (activeTools.has(name))
+                            return;
+                        activeTools.add(name);
+                        await rematerialize(activeTools);
+                    },
+                };
+            };
+            const placeholders = new Map([...registry.values()].map((i) => [i.name, createPlaceholderTool(i, directCallFor(i.name))]));
             const { messages } = await session.buildContext();
             for (const n of extractDiscoveredToolNames(messages, registry)) {
                 if (deferred.has(n))

package/dist/core/runner/runtask.js

@@ -844,6 +844,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                 taskId: rs.telemetry.taskId,
                 model: m.model,
                 provider: m.provider,
+                turn: stats.turns + 1,
                 promptTokens: turnInput,
                 completionTokens: u.output || 0,
                 cacheRead: u.cacheRead || 0,
@@ -1011,6 +1012,8 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
             version: 1,
             taskId: rs.telemetry.taskId,
             name: event.toolName,
+            toolCallId: event.toolCallId,
+            turn: stats.turns + 1,
             durationMs: toolStarted !== undefined ? toolNow - toolStarted : 0,
             ok: !event.isError,
             ts: toolNow,

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

@@ -1,4 +1,5 @@
-import type { AgentMessage, AgentTool } from "../../internal/harness-types.js";
+import { type TSchema } from "typebox";
+import type { AgentMessage, AgentTool, AgentToolResult } 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";
@@ -27,7 +28,12 @@ export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, too
     name: string;
     description: string;
 }>): Map<string, DeferredToolInfo>;
-export declare function createPlaceholderTool(info: DeferredToolInfo): AgentTool;
+export interface PlaceholderDirectCall {
+    parameters: TSchema;
+    invoke: (toolCallId: string, params: unknown, signal?: AbortSignal) => Promise<AgentToolResult<unknown>>;
+    activate: () => Promise<void>;
+}
+export declare function createPlaceholderTool(info: DeferredToolInfo, direct?: PlaceholderDirectCall): AgentTool;
 export declare function scoreToolMatch(query: string, info: DeferredToolInfo): number;
 export interface ToolSearchArgs {
     query?: string;

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;
@@ -59,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) {
@@ -193,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/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.js

@@ -723,6 +723,9 @@ export function settleBackgroundAgentLane(core, id, outcome) {
         ...(handle.resultFull !== undefined ? { finalOutputFull: handle.resultFull } : {}),
         ...(handle.resultIsPartial ? { resultIsPartial: true } : {}),
         ...(handle.error !== undefined ? { error: handle.error } : {}),
+        ...(handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
+        ...(handle.errorRetryable !== undefined ? { errorRetryable: handle.errorRetryable } : {}),
+        ...(handle.errorKind !== undefined ? { errorKind: handle.errorKind } : {}),
     }, ["parkedCheckpointToken", "parkClaimId", "parkedAt"]);
     return outcome.status;
 }
@@ -856,7 +859,22 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
     handle.cycleSeq = (handle.cycleSeq ?? 1) + 1;
     handle.updatedAt = Date.now();
-    durableAgentWriteLane(handle, { status: "running" }, ["settledAt", "stoppedBy", "finalOutput", "finalOutputFull", "error", "resultIsPartial", "completionId", "summary", "recentSteps", "editedFiles", "usage"]);
+    durableAgentWriteLane(handle, { status: "running" }, [
+        "settledAt",
+        "stoppedBy",
+        "finalOutput",
+        "finalOutputFull",
+        "error",
+        "errorCode",
+        "errorRetryable",
+        "errorKind",
+        "resultIsPartial",
+        "completionId",
+        "summary",
+        "recentSteps",
+        "editedFiles",
+        "usage",
+    ]);
     return { ok: true, cycle: handle.reviveCycle };
 }
 export function settleRevivedAgentLane(core, id, cycle, outcome) {
@@ -1019,8 +1037,11 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
             },
         };
     }
+    const kindClause = row.status === "failed" && row.errorKind !== undefined && row.errorRetryable !== undefined
+        ? ` (error_kind: ${row.errorKind}, retryable: ${row.errorRetryable})`
+        : "";
     const body = `status: ${row.status}
-${row.error ? `error: ${row.error}
+${row.error ? `error: ${row.error}${kindClause}
 ` : ""}${row.finalOutput ? `--- result${row.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
 ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}`;
     return {
@@ -1034,6 +1055,8 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
             ...(row.seq !== undefined ? { seq: row.seq } : {}),
             ...(row.resultIsPartial ? { partial_result: true } : {}),
             ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
+            ...(row.status === "failed" && row.errorCode !== undefined ? { errorCode: row.errorCode } : {}),
+            ...(row.status === "failed" && row.errorRetryable !== undefined ? { retryable: row.errorRetryable } : {}),
         },
         ...(row.status === "failed" ? { isError: true } : {}),
     };

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

@@ -258,6 +258,7 @@ export interface TaskSpec {
     excludeTools?: string[];
     deferTools?: string[];
     alwaysLoadTools?: string[];
+    deferSelfResolve?: boolean;
     promptProfile?: "simple" | "classic";
     agents?: AgentDefinition[];
     toolPolicy?: import("./tool-policy.js").ToolPolicy;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { SESSION_LOG_DIGEST_SCHEME, sessionEntryDigest, sessionLogDigest, sessio
 export type { ResumeTaskConfig } from "./core/runner/runtask.js";
 export { defineTool } from "./core/tools.js";
 export { SKILL_TOOL_NAME } from "./core/runner/synthetic-tools.js";
+export { createSkillsFromDirectory, type SkillsDirectoryOptions, type SkillsDirectoryWarning, type SkillsDirectoryWarningCode, } from "./core/skills-directory.js";
 export { REPORT_FINDINGS_TOOL_NAME, type ReportedFinding } from "./core/runner/synthetic-tools.js";
 export { formatToolError, formatZodValidationError, formatValidationPath, truncateError, errorClassOf } from "./core/tool-errors.js";
 export type { WorkerErrorClass } from "./core/tool-errors.js";
@@ -66,6 +67,7 @@ export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, CheckResult, } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, type ToolResultStore, type ToolResultSlice, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type ResourceLedger, type ResourceLimitReason, } from "./core/checkpoint-store.js";

package/dist/index.js

@@ -2,6 +2,7 @@ export { Runner, runTask, DEFAULT_MAX_TURNS } from "./core/runner/runtask.js";
 export { SESSION_LOG_DIGEST_SCHEME, sessionEntryDigest, sessionLogDigest, sessionLogDigestsComparable, } from "./engine/session/log-digest.js";
 export { defineTool } from "./core/tools.js";
 export { SKILL_TOOL_NAME } from "./core/runner/synthetic-tools.js";
+export { createSkillsFromDirectory, } from "./core/skills-directory.js";
 export { REPORT_FINDINGS_TOOL_NAME } from "./core/runner/synthetic-tools.js";
 export { formatToolError, formatZodValidationError, formatValidationPath, truncateError, errorClassOf } from "./core/tool-errors.js";
 export { createWebFetchTool, webFetchToolSpec, htmlToText, createWebSearchTool, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
@@ -57,6 +58,7 @@ export { runExecGate } from "./core/exec-gate.js";
 export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core/untrusted-text.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingWalltimeMs, winnerFromOutcome, validatePendingSteer, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -5,4 +5,16 @@ export declare function parseLeadingCommandName(command: string): {
     reject: string;
 };
 export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>): string | undefined;
-export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>): string | undefined;
+export interface BashReadonlyRootBoundary {
+    roots: readonly string[];
+    cwd?: string;
+    homeDir?: string;
+}
+export interface CompoundReadonlyVerdict {
+    reason?: string;
+    outOfRootRead?: true;
+    outOfRootPaths?: readonly string[];
+}
+export declare function formatOutOfRootReadApprovalOption(directory: string): string;
+export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;

package/dist/tools/fs/bash-readonly-classifier.js

@@ -1,4 +1,4 @@
-import { isBlockedDevicePath, normalizeAbsPathLexically } from "./safety.js";
+import { isBlockedDevicePath, normalizeAbsPathLexically, withinAnyRoot } from "./safety.js";
 export const BASH_READONLY_DEFAULT_ALLOW = [
     "ls", "cat", "head", "tail", "wc", "pwd", "echo", "whoami", "uname",
     "grep", "cut", "tr", "basename", "dirname", "stat", "du", "df", "which",
@@ -49,12 +49,102 @@ function foldQuoteRemovalToken(tok) {
     }
     return out;
 }
-export function classifyCompoundReadonly(command, allow) {
+export function formatOutOfRootReadApprovalOption(directory) {
+    const trimmed = directory.replace(/[/\\]+$/, "");
+    const cut = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+    const leaf = cut >= 0 ? trimmed.slice(cut + 1) : trimmed;
+    return `Yes, allow reading from ${leaf || directory}/ from this project`;
+}
+const NO_PATH_OPERAND_COMMANDS = new Set(["pwd", "echo", "whoami", "uname", "which", "tr", "basename", "dirname"]);
+function isAbsolutePathToken(p) {
+    return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p);
+}
+function isPathShapedToken(tok) {
+    return tok.includes("/") || tok.startsWith("~") || tok === "." || tok === "..";
+}
+function normalizeAbsPathLexicalEitherFamily(p) {
+    const s = p.replace(/\\/g, "/");
+    return /^[A-Za-z]:\//.test(s) ? s.slice(0, 2) + normalizeAbsPathLexically(s.slice(2)) : normalizeAbsPathLexically(s);
+}
+function resolveOperandLexically(base, operand, homeDir) {
+    let raw = operand;
+    if (raw === "~" || raw.startsWith("~/")) {
+        if (homeDir === undefined || !isAbsolutePathToken(homeDir))
+            return undefined;
+        raw = raw === "~" ? homeDir : `${homeDir.replace(/[/\\]+$/, "")}/${raw.slice(2)}`;
+    }
+    else if (raw.startsWith("~")) {
+        return undefined;
+    }
+    if (isAbsolutePathToken(raw))
+        return normalizeAbsPathLexicalEitherFamily(raw);
+    if (base === undefined || !isAbsolutePathToken(base))
+        return undefined;
+    return normalizeAbsPathLexicalEitherFamily(`${base.replace(/[/\\]+$/, "")}/${raw}`);
+}
+function collectSegmentBoundaryFindings(toks, boundary) {
+    const name = toks[0];
+    if (NO_PATH_OPERAND_COMMANDS.has(name))
+        return [];
+    const args = toks.slice(1);
+    const findings = [];
+    const candidates = [];
+    if (name === "cd") {
+        const target = args.find((t) => !t.startsWith("-") || t === "-");
+        if (target === undefined) {
+            return [{ kind: "unresolvable", reason: '`cd` with no argument targets the home directory, which cannot be checked against the allowed directories — not auto-allowed' }];
+        }
+        if (target === "-") {
+            return [{ kind: "unresolvable", reason: '`cd -` targets the previous working directory, which cannot be resolved statically — not auto-allowed' }];
+        }
+        candidates.push(target);
+    }
+    else {
+        const patternSuppliedByFlag = name === "grep" && args.some((t) => t === "-e" || t.startsWith("-e") || t === "-f" || t.startsWith("-f") || t.startsWith("--regexp") || t.startsWith("--file"));
+        let sawOperand = false;
+        for (let k = 0; k < args.length; k++) {
+            const t = args[k];
+            if (name === "cut" && (t === "-d" || t === "--delimiter" || t === "--output-delimiter")) {
+                k++;
+                continue;
+            }
+            if (t.startsWith("-") && t !== "-") {
+                const eq = t.indexOf("=");
+                const value = eq > 0 ? t.slice(eq + 1) : "";
+                if (value.length > 0 && isAbsolutePathToken(value))
+                    candidates.push(value);
+                continue;
+            }
+            if (t === "-")
+                continue;
+            const isGrepPatternSlot = name === "grep" && !patternSuppliedByFlag && !sawOperand;
+            sawOperand = true;
+            if (isGrepPatternSlot)
+                continue;
+            if (isPathShapedToken(t))
+                candidates.push(t);
+        }
+    }
+    for (const candidate of candidates) {
+        const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], candidate, boundary.homeDir);
+        if (resolved === undefined) {
+            findings.push({
+                kind: "unresolvable",
+                reason: `"${name}" names the path "${candidate}", which cannot be resolved statically — not auto-allowed`,
+            });
+            continue;
+        }
+        if (!withinAnyRoot(boundary.roots, resolved))
+            findings.push({ kind: "outside", command: name, path: resolved });
+    }
+    return findings;
+}
+export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
     const trimmed = command.trim();
     if (!trimmed)
-        return "empty command";
+        return { reason: "empty command" };
     if (SHELL_SEGMENT_HARD_REJECT.test(trimmed)) {
-        return "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed";
+        return { reason: "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed" };
     }
     const source = trimmed.endsWith(";") ? trimmed.slice(0, -1) : trimmed;
     const segments = [];
@@ -70,7 +160,7 @@ export function classifyCompoundReadonly(command, allow) {
                 i++;
             }
             else
-                return "`&` backgrounding is not allowed — a backgrounded process outlives the command";
+                return { reason: "`&` backgrounding is not allowed — a backgrounded process outlives the command" };
         }
         else if (c === "|") {
             if (source[i + 1] === "|") {
@@ -97,7 +187,7 @@ export function classifyCompoundReadonly(command, allow) {
     for (const segment of segments) {
         const reason = coarseReadonlyCheck(segment, allow);
         if (reason !== undefined)
-            return reason;
+            return { reason };
     }
     const HEAD_AUTO_ALLOW_MAX = 1_000_000;
     const headBoundIsSmall = (name, toks) => {
@@ -128,11 +218,13 @@ export function classifyCompoundReadonly(command, allow) {
         return byteBound;
     };
     const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity };
+    const foldedSegments = [];
     for (let si = 0; si < segments.length; si++) {
         const toks = segments[si].trim().split(/\s+/).filter((t) => t.length > 0)
             .map(foldQuoteRemovalToken);
         if (toks.length === 0)
             continue;
+        foldedSegments.push(toks);
         const name = toks[0];
         const nonOption = toks.slice(1).filter((t) => !t.startsWith("-"));
         if (!(pipeFed[si] ?? false)) {
@@ -165,21 +257,44 @@ export function classifyCompoundReadonly(command, allow) {
                 }
             }
             if (floor !== undefined && hasStdinDash) {
-                return `"${name}" reads stdin via an explicit "-" argument and would block until the tool timeout — not auto-allowed`;
+                return { reason: `"${name}" reads stdin via an explicit "-" argument and would block until the tool timeout — not auto-allowed` };
             }
             if (floor !== undefined && nonOption.length < floor) {
-                return `"${name}" with no file argument reads stdin and would block until the tool timeout — not auto-allowed`;
+                return { reason: `"${name}" with no file argument reads stdin and would block until the tool timeout — not auto-allowed` };
             }
         }
         if (name === "tail" && toks.slice(1).some((t) => t === "--follow" || t.startsWith("--follow=") || /^[-+][^\s]*[fF]/.test(t))) {
-            return "`tail` in follow mode never terminates — not auto-allowed";
+            return { reason: "`tail` in follow mode never terminates — not auto-allowed" };
         }
         const GENERATOR_DEVICES = new Set(["/dev/zero", "/dev/random", "/dev/urandom", "/dev/full"]);
         const deviceArgs = toks.slice(1).filter((t) => !t.startsWith("-")).map(normalizeAbsPathLexically).filter(isBlockedDevicePath);
         const rescuedByHead = headBoundIsSmall(name, toks) && deviceArgs.every((d) => GENERATOR_DEVICES.has(d));
         if (!rescuedByHead && deviceArgs.length > 0) {
-            return "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) — not auto-allowed";
+            return { reason: "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) — not auto-allowed" };
         }
     }
-    return undefined;
+    if (boundary !== undefined) {
+        const outside = [];
+        for (const toks of foldedSegments) {
+            for (const finding of collectSegmentBoundaryFindings(toks, boundary)) {
+                if (finding.kind === "unresolvable")
+                    return { reason: finding.reason };
+                if (!outside.some((o) => o.path === finding.path))
+                    outside.push(finding);
+            }
+        }
+        if (outside.length > 0) {
+            const paths = outside.map((o) => `"${o.path}"`).join(", ");
+            const allowed = boundary.roots.length > 0 ? boundary.roots.join(", ") : "(none)";
+            return {
+                reason: `"${outside[0].command}" reads ${paths}, outside the allowed directories for this session: ${allowed} — not auto-allowed`,
+                outOfRootRead: true,
+                outOfRootPaths: outside.map((o) => o.path),
+            };
+        }
+    }
+    return {};
+}
+export function classifyCompoundReadonly(command, allow, boundary) {
+    return classifyCompoundReadonlyDetailed(command, allow, boundary).reason;
 }

package/dist/tools/fs/fs-bash.d.ts

@@ -1,7 +1,8 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type CwdRef } from "./fs-shared.js";
-export declare function bashReversibilityProbe(allow?: readonly string[]): (args: unknown) => {
+import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
+export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => {
     reversible: boolean;
 };
 export interface ExecClampOption {

package/dist/tools/fs/fs-bash.js

@@ -9,13 +9,14 @@ import { imageMagicMatches, withinAnyRoot } from "./safety.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, } from "./fs-shared.js";
 import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyCompoundReadonly } from "./bash-readonly-classifier.js";
-export function bashReversibilityProbe(allow) {
+export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
     return (args) => {
         const command = args?.command;
         if (typeof command !== "string")
             return { reversible: false };
-        return { reversible: classifyCompoundReadonly(command, allowSet) === undefined };
+        const resolved = typeof boundary === "function" ? boundary() : boundary;
+        return { reversible: classifyCompoundReadonly(command, allowSet, resolved) === undefined };
     };
 }
 const EXIT1_INTERPRETATION = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",