@sema-agent/core 5.17.0-pre.0 → 5.18.0

package/dist/core/runner/tool-output-projection.js

@@ -62,7 +62,7 @@ const CC_DETAIL_TYPES = new Set([
     "agent", "task", "task-list", "task-output", "workflow-run",
     "web-fetch", "web-search", "todo", "cron-create", "cron-delete", "cron-list", "image",
     "task-stop", "tool-search", "repo-map", "fork", "enter-plan-mode", "exit-plan-mode",
-    "monitor-start", "path_not_in_root", "readonly_out_of_root",
+    "monitor-start", "path_not_in_root", "readonly_out_of_root", "bash_invalid_timeout",
     "report-findings", "schedule-wakeup", "send-message", "agent-transcript", "a2a", "document",
 ]);
 export const structuredFrom = (result) => {

package/dist/core/runner/turn-attachments.d.ts

@@ -94,6 +94,7 @@ export interface AttachmentInputs {
         mcpInstructions?: boolean;
     };
     undiscoveredTools?: readonly string[];
+    deferDirectCall?: boolean;
     changedFiles?: ReadonlyArray<{
         path: string;
         mtimeMs: number;
@@ -118,7 +119,7 @@ export interface AttachmentInputs {
     mcpDroppedTools?: ReadonlyArray<McpDroppedTool>;
 }
 export declare function collectDueAttachments(state: AttachmentState, inp: AttachmentInputs): readonly TurnAttachment[];
-export declare function renderToolSearchUsageReminder(undiscovered: readonly string[]): string;
+export declare function renderToolSearchUsageReminder(undiscovered: readonly string[], directCallEnabled?: boolean): string;
 export declare function renderDateChange(newDate: string): string;
 export declare function collectDateChange(state: DateChangeState, today: string): TurnAttachment | undefined;
 export declare function collectInstructionsChange(state: InstructionsChangeState, probed: ReadonlyArray<{

package/dist/core/runner/turn-attachments.js

@@ -145,7 +145,7 @@ export function collectDueAttachments(state, inp) {
         const sinceUse = state.toolSearchLastUseTurn === undefined ? Number.POSITIVE_INFINITY : cadenceNow - state.toolSearchLastUseTurn;
         if (sinceUse >= TOOL_SEARCH_REMINDER_CONFIG.EVERY_N_TURNS && cadenceNow - state.lastToolSearchReminderTurn >= TOOL_SEARCH_REMINDER_CONFIG.EVERY_N_TURNS) {
             state.lastToolSearchReminderTurn = cadenceNow;
-            (out ??= []).push({ source: "tool_search_usage_reminder", body: renderToolSearchUsageReminder(inp.undiscoveredTools) });
+            (out ??= []).push({ source: "tool_search_usage_reminder", body: renderToolSearchUsageReminder(inp.undiscoveredTools, inp.deferDirectCall !== false) });
         }
     }
     if (inp.config.planModeReminder && inp.planActive) {
@@ -248,14 +248,17 @@ function renderTaskReminder(state) {
     }
     return message;
 }
-export function renderToolSearchUsageReminder(undiscovered) {
+export function renderToolSearchUsageReminder(undiscovered, directCallEnabled = true) {
     const shown = undiscovered.slice(0, TOOL_SEARCH_REMINDER_CONFIG.MAX_NAMES);
     const more = undiscovered.length - shown.length;
     const names = `${shown.join(", ")}${more > 0 ? ` (+${more} more)` : ""}`;
     return (`Some available tools' schemas are not loaded in this conversation yet: ${names}. Before concluding a ` +
         `capability is missing or building a workaround, use ${TOOL_SEARCH_TOOL_NAME} to find and load relevant tools — ` +
-        `keywords to search, or query "select:<name>[,<name>...]" for specific tools. Calling a tool before its schema ` +
-        `is loaded will fail. This is just a gentle reminder - ignore if not applicable to the current work.`);
+        `keywords to search, or query "select:<name>[,<name>...]" for specific tools. ` +
+        (directCallEnabled
+            ? `You do not have these tools' parameters, so activate one rather than guessing its arguments. `
+            : `Calling a tool before its schema is loaded will fail. `) +
+        `This is just a gentle reminder - ignore if not applicable to the current work.`);
 }
 export function renderDateChange(newDate) {
     return `The date has changed. Today's date is now ${newDate}. DO NOT mention this to the user explicitly because they are already aware.`;
@@ -400,8 +403,8 @@ export function renderToolsDelta(input) {
     if (added.length > 0) {
         const swapped = input.staticFace === true ? (input.swappedUnderStatic ?? []).filter((n) => added.includes(n)) : [];
         blocks.push((input.staticFace === true
-            ? "The following deferred tools are now active — call them directly. Their parameter schemas were " +
-                "provided in the ToolSearch result (the tools list itself keeps compact placeholder entries):\n"
+            ? "The following deferred tools are now active — call them directly. The tools list keeps compact " +
+                'placeholder entries, so re-run ToolSearch ("select:<name>") if you need a parameter schema:\n'
             : "The following deferred tools are now available. Their full schemas are loaded — call them " +
                 "directly like any other tool:\n") +
             added.map((n) => `- ${n}`).join("\n") +

package/dist/core/session-reconcile.js

@@ -10,6 +10,20 @@ const INTERRUPTED_IDEMPOTENT = "[INTERRUPTED] The previous run ended before this
     "what you intended. If you decide not to re-issue it, verify the current state first.";
 const INTERRUPTED_NEVER_STARTED = "[INTERRUPTED] The run was aborted before this tool call started. It was never executed and had " +
     "no side effects — it is safe to re-issue this call if you still need it.";
+const INTERRUPTED_REPEAT_UNKNOWN = "[INTERRUPTED] Same as an earlier interrupted call in this batch: no result was recorded and the outcome is " +
+    "UNKNOWN — verify before relying on it.";
+const INTERRUPTED_REPEAT_SAFE = "[INTERRUPTED] Same as an earlier interrupted call in this batch: this tool is read-only/idempotent, so just " +
+    "call it again if you still need the result.";
+const INTERRUPTED_REPEAT_IDEMPOTENT = "[INTERRUPTED] Same as an earlier interrupted call in this batch: it is safe to REPLAY — re-issue it, or verify " +
+    "the current state if you decide not to.";
+const INTERRUPTED_REPEAT_NEVER_STARTED = "[INTERRUPTED] Same as an earlier interrupted call in this batch: it never started and had no side effects — " +
+    "safe to re-issue.";
+const REPEAT_TEXT = {
+    never_started: INTERRUPTED_REPEAT_NEVER_STARTED,
+    read: INTERRUPTED_REPEAT_SAFE,
+    idempotent: INTERRUPTED_REPEAT_IDEMPOTENT,
+    unknown: INTERRUPTED_REPEAT_UNKNOWN,
+};
 export function findOrphanToolCalls(messages, suspendedBatch) {
     const resolvedAt = new Map();
     const callSitesAt = new Map();
@@ -70,11 +84,15 @@ export async function reconcileInterruptedSession(session, toolEffects, suspende
     const { messages } = await session.buildContext();
     const orphans = findOrphanToolCalls(messages, suspendedBatch).filter((o) => o.kind !== "result");
     const recovered = [];
+    const statedInFull = new Set();
     for (const orphan of orphans) {
         const effect = toolEffects?.get(orphan.toolName) ?? "write";
         const effectText = effect === "read" ? INTERRUPTED_SAFE : effect === "idempotent" ? INTERRUPTED_IDEMPOTENT : INTERRUPTED_UNKNOWN;
         const neverStarted = startedToolCallIds !== undefined && !startedToolCallIds.has(orphan.toolCallId);
-        const text = neverStarted ? INTERRUPTED_NEVER_STARTED : effectText;
+        const fullText = neverStarted ? INTERRUPTED_NEVER_STARTED : effectText;
+        const cls = neverStarted ? "never_started" : effect === "read" ? "read" : effect === "idempotent" ? "idempotent" : "unknown";
+        const text = statedInFull.has(cls) ? REPEAT_TEXT[cls] : fullText;
+        statedInFull.add(cls);
         const errorKind = neverStarted ? "interrupted_never_started" : "interrupted_outcome_unknown";
         const entryId = await session.appendMessage({
             role: "toolResult",

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

@@ -982,6 +982,7 @@ export async function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.errorRetryAfterMs = undefined;
     handle.resultIsPartial = undefined;
     handle.stopSource = undefined;
+    handle.stoppedBy = undefined;
     handle.completionId = undefined;
     handle.terminalNotified = undefined;
     handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;

package/dist/core/tool-policy.d.ts

@@ -8,7 +8,7 @@ export interface ToolCallRequest {
         suspendCount: number;
     };
 }
-export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier";
+export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier" | "persisted_rule";
 export type PermissionResult = {
     action: "allow";
     updatedInput?: unknown;
@@ -43,6 +43,12 @@ export declare function toolPolicyNameSets(p: ToolPolicy | undefined): readonly
 export declare function createAllowDenyPolicy(opts: {
     allow?: string[];
     deny?: string[];
+    onInvalidName?: "throw" | "skip";
+    onInvalidNameIssue?: (issue: {
+        entry: string;
+        list: "allow" | "deny";
+        message: string;
+    }) => void;
 }): NamedToolPolicy;
 export declare function createApprovalPolicy(opts: {
     requireApproval: string[];
@@ -81,6 +87,7 @@ export interface AskRequest {
     args: unknown;
     readonly preview?: unknown;
     readonly boundInputHash?: string;
+    readonly ruleSuggestions?: readonly import("./permission-rule-model.js").RuleSuggestion[];
     message: string;
     readonly principal?: string;
     readonly sourceTaskId?: string;
@@ -100,6 +107,15 @@ export type AskOutcome = boolean | "unavailable" | {
 };
 export declare function withDelegationProvenance(onAsk: OnAsk, delegation: AskDelegationProvenance): OnAsk;
 export declare function askApproverIdentity(onAsk: unknown): unknown;
+export declare function tryCloneArgs<T>(v: T): {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+    cause?: unknown;
+};
+export declare function describeThrown(err: unknown): string;
 export type ResolvedAsk = PermissionResult & {
     approverUnavailable?: true;
     presentedInput?: unknown;

package/dist/core/tool-policy.js

@@ -2,6 +2,8 @@ import { homedir } from "node:os";
 import { isAbsolute, join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
 import { boundInputHashOf } from "./canonical-json.js";
+import { inlineUntrusted } from "./untrusted-text.js";
+import { parsePermissionRule } from "./permission-rules.js";
 import { writeTargetPath } from "../tools/fs/safety.js";
 export function decisionText(d) {
     return d.message;
@@ -43,6 +45,41 @@ export function toolPolicyNameSets(p) {
     return Array.isArray(sets) ? sets : [];
 }
 export function createAllowDenyPolicy(opts) {
+    const invalid = [];
+    const screen = (entries, list) => {
+        if (entries === undefined)
+            return undefined;
+        const kept = [];
+        for (const entry of entries) {
+            if (parsePermissionRule(entry).ruleContent === undefined) {
+                kept.push(entry);
+                continue;
+            }
+            invalid.push({
+                entry,
+                list,
+                message: `"${entry}" is a rule CONTENT form, not a tool name — a name set matches raw tool names, so this entry ` +
+                    `can never match any mounted tool (in an allow list it removes the tool entirely). Use the tool NAME here, ` +
+                    `and route the narrowing through the lane that speaks this grammar: parameter rules via ` +
+                    `createPermissionRulePolicy, Bash command prefixes via the persisted allow-rule lane.`,
+            });
+        }
+        return kept;
+    };
+    const screenedAllow = screen(opts.allow, "allow");
+    const screenedDeny = screen(opts.deny, "deny");
+    if (invalid.length > 0) {
+        if ((opts.onInvalidName ?? "throw") === "throw") {
+            const e = new Error(`createAllowDenyPolicy: ${invalid.length} entr${invalid.length === 1 ? "y is" : "ies are"} not tool name(s):\n` +
+                invalid.map((i) => `  [${i.list}] ${i.message}`).join("\n"));
+            e.code = "config.invalid_tool_name_set";
+            e.issues = invalid;
+            throw e;
+        }
+        for (const issue of invalid)
+            opts.onInvalidNameIssue?.(issue);
+    }
+    opts = { ...opts, ...(screenedAllow ? { allow: screenedAllow } : {}), ...(screenedDeny ? { deny: screenedDeny } : {}) };
     const allow = opts.allow ? new Set(opts.allow) : undefined;
     const deny = new Set(opts.deny ?? []);
     return {
@@ -90,7 +127,7 @@ export function createApprovalPolicy(opts) {
                 catch (err) {
                     return {
                         action: "deny",
-                        message: `approval errored for "${req.toolName}": ${err instanceof Error ? err.message : String(err)}`,
+                        message: `approval errored for "${req.toolName}": ${describeThrown(err)}`,
                     };
                 }
                 const okRaw = ok;
@@ -528,17 +565,36 @@ export function withDelegationProvenance(onAsk, delegation) {
 export function askApproverIdentity(onAsk) {
     return typeof onAsk === "function" ? (delegatedApproverRoot.get(onAsk) ?? onAsk) : onAsk;
 }
-function tryCloneArgs(v) {
+export function tryCloneArgs(v) {
     try {
         const value = structuredClone(v);
         if (containsSharedMemory(value))
-            return { ok: false };
+            return { ok: false, reason: "the value carries shared memory (SharedArrayBuffer), which a clone still aliases" };
         return { ok: true, value };
     }
+    catch (err) {
+        return { ok: false, reason: describeThrown(err), cause: err };
+    }
+}
+export function describeThrown(err) {
+    try {
+        if (typeof err === "string")
+            return containThrownText(err);
+        if (err instanceof Error) {
+            const message = err.message;
+            if (typeof message === "string" && message !== "")
+                return containThrownText(message);
+        }
+        return `a non-Error value was thrown (${err === null ? "null" : typeof err})`;
+    }
     catch {
-        return { ok: false };
+        return "the value could not be described";
     }
 }
+const THROWN_TEXT_MAX = 300;
+function containThrownText(text) {
+    return inlineUntrusted(text, THROWN_TEXT_MAX);
+}
 function containsSharedMemory(v, seen = new Set()) {
     if (typeof SharedArrayBuffer !== "undefined" && v instanceof SharedArrayBuffer)
         return true;
@@ -593,7 +649,7 @@ export async function resolveAsk(req, onAsk, signal) {
     if (!presented.ok) {
         return {
             action: "deny",
-            message: `approval for "${req.toolName}" could not present the args safely (unclonable value) — denied fail-closed`,
+            message: `approval for "${req.toolName}" could not present the args safely (unclonable value: ${presented.reason}) — denied fail-closed`,
             decisionReason: "mode",
         };
     }
@@ -603,7 +659,7 @@ export async function resolveAsk(req, onAsk, signal) {
         if (!approverView.ok) {
             return {
                 action: "deny",
-                message: `approval for "${req.toolName}" could not present the args safely (unclonable value) — denied fail-closed`,
+                message: `approval for "${req.toolName}" could not present the args safely (unclonable value: ${approverView.reason}) — denied fail-closed`,
                 decisionReason: "mode",
             };
         }
@@ -612,7 +668,7 @@ export async function resolveAsk(req, onAsk, signal) {
     catch (err) {
         return {
             action: "deny",
-            message: `approval errored for "${req.toolName}": ${err instanceof Error ? err.message : String(err)}`,
+            message: `approval errored for "${req.toolName}": ${describeThrown(err)}`,
             decisionReason: "mode",
         };
     }
@@ -635,7 +691,7 @@ export async function resolveAsk(req, onAsk, signal) {
         if (!edit.ok) {
             return {
                 action: "deny",
-                message: `the approved edit for "${req.toolName}" is not safely clonable — denied fail-closed`,
+                message: `the approved edit for "${req.toolName}" is not safely clonable (${edit.reason}) — denied fail-closed`,
                 decisionReason: "mode",
             };
         }

package/dist/core/tools.js

@@ -45,6 +45,7 @@ export function defineTool(spec, options) {
         executionMode,
         ...(spec.isConcurrencySafe ? { isConcurrencySafe: spec.isConcurrencySafe } : {}),
         ...(spec.effect ? { effect: spec.effect } : {}),
+        ...(spec.contentOrigin ? { contentOrigin: spec.contentOrigin } : {}),
         ...(spec.prepareArguments ? { prepareArguments: spec.prepareArguments } : {}),
         ...(spec.approvalPreview ? { approvalPreview: spec.approvalPreview } : {}),
         execute: async (toolCallId, rawParams, signal) => {

package/dist/core/trace.d.ts

@@ -181,6 +181,20 @@ export type TraceEvent = {
     site: string;
     message: string;
     ts: number;
+} | {
+    kind: "permission.persisted_rule_allowed";
+    version: 1;
+    taskId: string;
+    toolName: string;
+    toolCallId: string;
+    rule: string;
+    ts: number;
+} | {
+    kind: "permission.rule_store_unreadable";
+    version: 1;
+    taskId: string;
+    message: string;
+    ts: number;
 } | {
     kind: "brain.failover";
     version: 1;
@@ -217,6 +231,12 @@ export type TraceEvent = {
     estTokens: number;
     floor: number;
     ts: number;
+} | {
+    kind: "compaction.unevaluable";
+    version: 1;
+    taskId: string;
+    estTokens: number;
+    ts: number;
 } | {
     kind: "compaction.blocked";
     version: 1;

package/dist/core/types.d.ts

@@ -20,6 +20,7 @@ export interface Brain {
     complete?: CompleteSimpleFn;
 }
 export type ToolEffect = "read" | "write" | "idempotent";
+export type ToolContentOrigin = "external" | "execution" | "local";
 export interface ToolSpec<TParams extends TSchema = TSchema> {
     name: string;
     aliases?: string[];
@@ -30,6 +31,17 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
         name: string;
         description: string;
     }>;
+    agentToolFaces?: ReadonlyArray<{
+        name: string;
+        allowTools?: readonly string[];
+        denyTools?: readonly string[];
+        canRedelegate?: boolean;
+    }>;
+    agentToolPool?: ReadonlyArray<{
+        name: string;
+        aliases?: readonly string[];
+        contentOrigin?: ToolContentOrigin;
+    }>;
     approvalPreview?: (args: unknown) => unknown;
     agentModels?: readonly string[];
     withAgents?: (agents: ReadonlyArray<AgentDefinition>) => ToolSpec;
@@ -42,6 +54,7 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
     } | Promise<{
         reversible: boolean;
     }>;
+    contentOrigin?: ToolContentOrigin;
     executionMode?: "sequential" | "parallel";
     isConcurrencySafe?: (args: unknown) => boolean;
     parameters: TParams;
@@ -174,6 +187,7 @@ export interface HandsBandOptions {
     readImageDownsampler?: ((input: Buffer, mimeType: string) => Promise<import("./mcp.js").DownsampledImage | undefined>) | false;
     beforeWrite?: BeforeWriteHook;
     autoBackgroundOnTimeout?: boolean;
+    readCyberReminder?: boolean;
 }
 export interface AgentDefinition {
     name: string;
@@ -771,6 +785,7 @@ export interface RunnerDeps {
     checkpointStore?: import("./checkpoint-store.js").CheckpointStore;
     fileSnapshotStore?: import("./file-snapshot-store.js").FileSnapshotStore;
     sessionPolicyStore?: import("./session-policy-store.js").SessionPolicyStore;
+    permissionRuleStore?: import("./permission-rule-store.js").PermissionRuleStoreProvider;
     runtimeCapsResolver?: (principal: string | undefined) => RuntimeCaps | undefined | Promise<RuntimeCaps | undefined>;
     lockedConfig?: import("./locked-config.js").LockedConfig;
     compliancePostureResolver?: (principal: string | undefined) => import("./compliance.js").CompliancePosture | undefined | Promise<import("./compliance.js").CompliancePosture | undefined>;

package/dist/core/wiring-manifest.d.ts

@@ -43,6 +43,9 @@ export interface WiringManifest {
         backgroundAgentStore: boolean;
         hostChildEventSink: boolean;
     };
+    permissionRules: {
+        storeWired: boolean;
+    };
     governance: {
         audience: "operator";
         lockedConfig: boolean;
@@ -71,13 +74,14 @@ export interface WiringFacts {
     checkpointDurability?: StoreDurability;
     sessionDurability: StoreDurability;
     backgroundAgentStoreWired: boolean;
+    permissionRuleStoreWired: boolean;
     hostChildEventSinkWired: boolean;
     lockedConfigWired: boolean;
     complianceWired: boolean;
     memoryAdmissionWired: boolean;
     retentionPolicyWired: boolean;
 }
-export type StaticWiringDeps = Pick<RunnerDeps, "onAsk" | "onQuestion" | "interactionPosture" | "onElicit" | "checkpointStore" | "sessionStore" | "backgroundAgentStore" | "onBackgroundChildEvent" | "lockedConfig" | "compliancePostureResolver" | "memoryScopeAdmission" | "retentionPolicy">;
+export type StaticWiringDeps = Pick<RunnerDeps, "onAsk" | "onQuestion" | "interactionPosture" | "onElicit" | "checkpointStore" | "sessionStore" | "backgroundAgentStore" | "onBackgroundChildEvent" | "lockedConfig" | "compliancePostureResolver" | "memoryScopeAdmission" | "retentionPolicy" | "permissionRuleStore">;
 export type StaticWiringSpec = Pick<TaskSpec, "onAsk" | "onQuestion" | "checkpointStore" | "durableApproval" | "mcp" | "interactiveTools" | "interactionPosture">;
 export declare function resolveDeclaredDurability(store: {
     readonly durability?: StoreDurability;

package/dist/core/wiring-manifest.js

@@ -19,9 +19,9 @@ export function deriveAskEffective(form, parkEffective) {
         case "callback":
             return "human_reachable";
         case "allow":
-            return "auto_allow";
+            return parkEffective === true ? "park_only" : parkEffective === "unresolved" ? "unresolved" : "auto_allow";
         case "deny":
-            return "auto_deny";
+            return parkEffective === true ? "park_only" : parkEffective === "unresolved" ? "unresolved" : "auto_deny";
         case "absent":
             return parkEffective === true ? "park_only" : parkEffective === "unresolved" ? "unresolved" : "auto_deny";
         default: {
@@ -86,6 +86,7 @@ export function deriveWiringManifest(facts) {
         parkLane,
         session: { store: manifestDurabilityOf(facts.sessionDurability) },
         fleet: { backgroundAgentStore: facts.backgroundAgentStoreWired, hostChildEventSink: facts.hostChildEventSinkWired },
+        permissionRules: { storeWired: facts.permissionRuleStoreWired },
         governance: {
             audience: "operator",
             lockedConfig: facts.lockedConfigWired,
@@ -177,6 +178,7 @@ export function describeStaticWiring(deps, spec = {}) {
         ...(capable ? { checkpointDurability: resolveDeclaredDurability(checkpointStore, "checkpointStore") } : {}),
         sessionDurability: resolveDeclaredDurability(deps.sessionStore, "sessionStore"),
         backgroundAgentStoreWired: deps.backgroundAgentStore !== undefined,
+        permissionRuleStoreWired: deps.permissionRuleStore !== undefined,
         hostChildEventSinkWired: deps.onBackgroundChildEvent !== undefined,
         lockedConfigWired: deps.lockedConfig !== undefined,
         complianceWired: deps.compliancePostureResolver !== undefined,

package/dist/engine/llm/validation.js

@@ -1,5 +1,6 @@
 import { Compile } from "typebox/compile";
 import { Value } from "typebox/value";
+import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 const validatorCache = new WeakMap();
 const TYPEBOX_KIND = Symbol.for("TypeBox.Kind");
 function isRecord(value) {
@@ -253,6 +254,123 @@ function formatValidationPath(error) {
     const path = error.instancePath.replace(/^\//, "").replace(/\//g, ".");
     return path || "root";
 }
+const INSTANCE_PATH_MAX_BRANCHES = 256;
+function resolveInstancePath(root, instancePath) {
+    if (instancePath === "")
+        return { found: true, value: root, segments: [] };
+    const body = instancePath.startsWith("/") ? instancePath.slice(1) : instancePath;
+    const found = [];
+    let budget = INSTANCE_PATH_MAX_BRANCHES;
+    const walk = (cursor, remaining, segments) => {
+        if (found.length > 1 || budget <= 0)
+            return;
+        if (cursor === null || typeof cursor !== "object")
+            return;
+        const container = cursor;
+        for (let cut = remaining.indexOf("/");; cut = remaining.indexOf("/", cut + 1)) {
+            const key = cut === -1 ? remaining : remaining.slice(0, cut);
+            if (budget <= 0)
+                return;
+            budget--;
+            if (Object.prototype.hasOwnProperty.call(container, key)) {
+                if (cut === -1)
+                    found.push({ value: container[key], segments: [...segments, key] });
+                else
+                    walk(container[key], remaining.slice(key.length + 1), [...segments, key]);
+                if (found.length > 1)
+                    return;
+            }
+            if (cut === -1)
+                return;
+        }
+    };
+    walk(root, body, []);
+    if (found.length !== 1 || budget <= 0)
+        return { found: false };
+    return { found: true, value: found[0].value, segments: found[0].segments };
+}
+function accessorFrom(segments, property) {
+    const all = property === undefined ? [...segments] : [...segments, property];
+    return all.join(".");
+}
+function jsonTypeNameOf(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (Array.isArray(value))
+        return "array";
+    const t = typeof value;
+    return t === "object" ? "object" : t;
+}
+function synthesizeValidationIssues(errors, checkedValue) {
+    const sentences = [];
+    const rest = [];
+    for (const error of errors) {
+        const resolved = resolveInstancePath(checkedValue, error.instancePath);
+        const segments = resolved.found ? resolved.segments : undefined;
+        if (segments !== undefined && error.keyword === "required") {
+            const properties = error.params.requiredProperties ?? [];
+            for (const property of properties) {
+                sentences.push(`The required parameter \`${accessorFrom(segments, property)}\` is missing`);
+            }
+            continue;
+        }
+        if (segments !== undefined && error.keyword === "additionalProperties") {
+            const properties = error.params.additionalProperties ?? [];
+            for (const property of properties) {
+                sentences.push(`An unexpected parameter \`${accessorFrom(segments, property)}\` was provided`);
+            }
+            continue;
+        }
+        if (segments !== undefined && error.keyword === "type" && resolved.found) {
+            const expected = error.params.type;
+            const expectedText = Array.isArray(expected) ? expected.join(" | ") : (expected ?? "the declared type");
+            const provided = jsonTypeNameOf(resolved.value);
+            const accessor = accessorFrom(segments) || "root";
+            sentences.push(`The parameter \`${accessor}\` type is expected as \`${expectedText}\` but provided as \`${provided}\``);
+            continue;
+        }
+        rest.push(`  - ${formatValidationPath(error)}: ${error.message}`);
+    }
+    let restText = "";
+    if (rest.length > 0) {
+        const marker = (n) => `  … ${n} more issue${n === 1 ? "" : "s"} omitted`;
+        const kept = [];
+        let used = 0;
+        for (const line of rest) {
+            const cost = kept.length === 0 ? line.length : line.length + 1;
+            if (used + cost > VALIDATION_ERROR_ISSUES_MAX_CHARS)
+                break;
+            kept.push(line);
+            used += cost;
+        }
+        if (kept.length === rest.length) {
+            restText = kept.join("\n");
+        }
+        else {
+            while (kept.length > 0 && used + marker(rest.length - kept.length).length + 1 > VALIDATION_ERROR_ISSUES_MAX_CHARS) {
+                const removed = kept.pop();
+                used -= kept.length === 0 ? removed.length : removed.length + 1;
+            }
+            if (kept.length === 0) {
+                const clip = "… (issue truncated)";
+                const others = rest.length - 1;
+                const markerCost = others > 0 ? marker(others).length + 1 : 0;
+                const room = VALIDATION_ERROR_ISSUES_MAX_CHARS - markerCost - clip.length;
+                if (room > 0) {
+                    kept.push(`${sliceHeadSafe(rest[0], room)}${clip}`);
+                }
+            }
+            const omitted = rest.length - kept.length;
+            if (omitted > 0)
+                kept.push(marker(omitted));
+            restText = kept.join("\n");
+        }
+    }
+    const all = [...sentences, ...(restText ? [restText] : [])];
+    return all.join("\n") || "Unknown validation error";
+}
 export function validateToolCall(tools, toolCall) {
     const tool = findToolByName(tools, toolCall.name);
     if (!tool) {
@@ -284,10 +402,7 @@ export function validateToolArguments(tool, toolCall) {
     if (validator.Check(args)) {
         return args;
     }
-    const errors = validator
-        .Errors(args)
-        .map((error) => `  - ${formatValidationPath(error)}: ${error.message}`)
-        .join("\n") || "Unknown validation error";
+    const errors = synthesizeValidationIssues([...validator.Errors(args)], args);
     const schemaJson = (() => {
         try {
             const s = JSON.stringify(tool.parameters);
@@ -297,6 +412,7 @@ export function validateToolArguments(tool, toolCall) {
             return "(schema not serializable)";
         }
     })();
-    throw new Error(`Validation failed for tool "${toolCall.name}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(toolCall.arguments, null, 2)}\n\nExpected parameter schema:\n${schemaJson}`);
+    throw new Error(`Validation failed for tool "${toolCall.name}":\n${errors}\n\nExpected parameter schema:\n${schemaJson}`);
 }
 const VALIDATION_ERROR_SCHEMA_MAX_CHARS = 4_000;
+const VALIDATION_ERROR_ISSUES_MAX_CHARS = 2_000;

package/dist/engine/loop/agent-loop.d.ts

@@ -12,3 +12,5 @@ export type LoopStep = {
 };
 export type LoopTraceSink = (step: LoopStep) => void;
 export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn, runtime?: AgentCoreStreamRuntimeDeps, trace?: LoopTraceSink): Promise<AgentMessage[]>;
+export declare const ROSTER_LISTING_MAX = 25;
+export declare const ROSTER_SEARCH_HINT_NAME = "ToolSearch";

package/dist/engine/loop/agent-loop.js

@@ -1,4 +1,5 @@
 import { findToolByName, validateToolArguments } from "../llm/index.js";
+import { truncateError } from "../../core/tool-errors.js";
 import { resolveAgentCoreStreamFn } from "./runtime-deps.js";
 function appendTextDeltaToAssistantMessage(message, contentIndex, delta) {
     const content = [...message.content];
@@ -831,14 +832,26 @@ function prepareToolCallArguments(tool, toolCall) {
         arguments: preparedArguments,
     };
 }
+export const ROSTER_LISTING_MAX = 25;
+export const ROSTER_SEARCH_HINT_NAME = "ToolSearch";
+function formatRosterRecovery(availableTools) {
+    if (availableTools.length === 0)
+        return "";
+    const shown = availableTools.slice(0, ROSTER_LISTING_MAX);
+    const withheld = availableTools.length - shown.length;
+    const listing = withheld > 0 ? `${shown.join(", ")} … and ${withheld} more` : shown.join(", ");
+    const hint = availableTools.includes(ROSTER_SEARCH_HINT_NAME)
+        ? `. Use ${ROSTER_SEARCH_HINT_NAME} to look up a tool by name.`
+        : "";
+    return ` Available tools: ${listing}${hint}`;
+}
 async function prepareToolCall(currentContext, assistantMessage, toolCall, config, signal) {
     const tool = findToolByName(currentContext.tools, toolCall.name);
     if (!tool) {
         const availableTools = (currentContext.tools ?? []).map((t) => t.name);
-        const available = availableTools.join(", ");
         return {
             kind: "immediate",
-            result: createErrorToolResult(`Tool ${toolCall.name} not found.${available ? ` Available tools: ${available}` : ""}`, { details: { code: "tool.not_found", toolName: toolCall.name, availableTools } }),
+            result: createErrorToolResult(`Tool ${toolCall.name} not found.${formatRosterRecovery(availableTools)}`, { details: { code: "tool.not_found", toolName: toolCall.name, availableTools } }),
             isError: true,
         };
     }
@@ -1043,7 +1056,7 @@ async function finalizeExecutedToolCall(currentContext, assistantMessage, prepar
             }
         }
         catch (error) {
-            const note = `[post-tool processing failed (the tool already executed): ${error instanceof Error ? error.message : String(error)}]`;
+            const note = truncateError(`[post-tool processing failed (the tool already executed): ${error instanceof Error ? error.message : String(error)}]`);
             result = { ...result, content: [...result.content, { type: "text", text: note }] };
         }
         if (deliveryMark !== undefined && readDeliveryFailureMark(result.details) === undefined) {
@@ -1095,7 +1108,7 @@ function createErrorToolResult(message, source) {
         }
     }
     return {
-        content: [{ type: "text", text: message }],
+        content: [{ type: "text", text: truncateError(message) }],
         details,
     };
 }