@deepstrike/sdk 0.2.23 → 0.2.25

package/dist/index.d.ts

@@ -56,7 +56,9 @@ export type { CreateProviderOptions, EndpointProfileId } from "./providers/catal
 export { ProviderReplayValidationError, DEGRADED_REASONING_PLACEHOLDER } from "./providers/replay-validator.js";
 export { assessProviderReplayability, peekProviderReplay, seedProviderReplayFromEvents, isReplayCompatibleWithProvider, } from "./runtime/provider-replay.js";
 export { tool, streamingTool, executeTools, readFile, validateToolArguments } from "./tools/index.js";
-export type { RegisteredTool } from "./tools/index.js";
+export type { RegisteredTool, ToolExecContext } from "./tools/index.js";
+export { safeTool, ok, fail, ToolError, formatToolError } from "./tools/errors.js";
+export type { ToolEnvelope, ToolEnvelopeOk, ToolEnvelopeFail } from "./tools/errors.js";
 export { scanSkillDir, readSkillFile } from "./skills/loader.js";
 export type { SkillMetadata } from "./skills/loader.js";
 export { WorkingMemory } from "./memory/working.js";
@@ -72,7 +74,7 @@ export { Governance, governancePolicyToKernelEvent } from "./governance.js";
 export type { GovernanceVerdict, GovernancePolicy, GovernanceConstraint } from "./governance.js";
 export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness/harness.js";
 export type { HarnessRequest, HarnessOutcome, HarnessLoopOptions, QualityGate, CriterionResult, HarnessEvent, VerdictFn } from "./harness/harness.js";
-export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, RetryConfig, TokenUsage, ProviderToolSpec, ProviderRunState, ProviderReplay, RenderedContext, ReplayabilityAssessment, CacheBreakpointStrategy, } from "./types.js";
+export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, ToolAuditFailedEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, RetryConfig, TokenUsage, ProviderToolSpec, ProviderRunState, ProviderReplay, RenderedContext, ReplayabilityAssessment, CacheBreakpointStrategy, } from "./types.js";
 export type { AgentCapabilityFilter, AgentIdentity, AgentIsolation, AgentRunSpec, AgentProcessChangedObservation, ContextInheritance, KernelAgentRole, LoopResult, MilestoneCheckResult, MilestoneContract, MilestonePhase, MilestonePolicy, SubAgentResult, TerminationReason, WorkflowSpec, WorkflowNodeSpec, WorkflowTaskSpec, WorkflowSpawnInfo, } from "./types/agent.js";
 export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, workflowSpecToKernel, workflowNodeSpecToKernel, submitWorkflowNodesToKernel, submitWorkflowToKernel, submitWorkflowNodesTool, startWorkflowTool, fanoutSynthesize, generateAndFilter, verifyRules, genEval, } from "./types/agent.js";
 export type { AcceptanceCriterion, VerificationContract, ContractCheckResult, } from "./collaboration/contract.js";

package/dist/index.js

@@ -39,6 +39,7 @@ export { ProviderReplayValidationError, DEGRADED_REASONING_PLACEHOLDER } from ".
 export { assessProviderReplayability, peekProviderReplay, seedProviderReplayFromEvents, isReplayCompatibleWithProvider, } from "./runtime/provider-replay.js";
 // ── Tools & Skills ─────────────────────────────────────────────────────────
 export { tool, streamingTool, executeTools, readFile, validateToolArguments } from "./tools/index.js";
+export { safeTool, ok, fail, ToolError, formatToolError } from "./tools/errors.js";
 export { scanSkillDir, readSkillFile } from "./skills/loader.js";
 // ── Memory ─────────────────────────────────────────────────────────────────
 export { WorkingMemory } from "./memory/working.js";

package/dist/runtime/execution-plane.js

@@ -1,4 +1,5 @@
-import { isAsyncIterable, normalizeToolChunk, toolChunkText, validateToolArguments } from "../tools/index.js";
+import { isAsyncIterable, maybeWarnFailureShapedChunk, normalizeToolChunk, toolChunkText, validateToolArguments } from "../tools/index.js";
+import { formatToolError } from "../tools/errors.js";
 import { readSkillFile } from "../skills/loader.js";
 import { LargeResultSpool } from "./large-result-spool.js";
 export class LocalExecutionPlane {
@@ -102,6 +103,20 @@ export class LocalExecutionPlane {
         const registered = this.tools.get(call.name);
         if (!registered)
             return { callId: call.id, output: `unknown tool: ${call.name}`, isError: true };
+        // `audit` failure buffer is hoisted above the try-block so the catch path can flush any
+        // best-effort failures recorded before the main throw.
+        const auditFailures = [];
+        const callCtx = {
+            ...(ctx.cwd !== undefined ? { cwd: ctx.cwd } : {}),
+            audit: async (label, fn) => {
+                try {
+                    await fn();
+                }
+                catch (err) {
+                    auditFailures.push({ label, error: formatToolError(err) });
+                }
+            },
+        };
         try {
             const args = JSON.parse(call.arguments || "{}");
             const originalArgsStr = JSON.stringify(args);
@@ -119,7 +134,8 @@ export class LocalExecutionPlane {
             }
             // M3/G4: pass the run context (incl. `cwd`) so cwd-aware tools scope their work to the
             // sub-agent's worktree. `RunContext` is structurally assignable to the tool's `ToolExecContext`.
-            const output = await registered.execute(args, ctx);
+            // The per-call `audit` helper (above) layers best-effort side-effect handling on top.
+            const output = await registered.execute(args, callCtx);
             if (isAsyncIterable(output)) {
                 let combined = "";
                 const iterator = output[Symbol.asyncIterator]();
@@ -145,16 +161,28 @@ export class LocalExecutionPlane {
                     }
                     const delta = toolChunkText(next.value);
                     combined += delta;
+                    if (delta)
+                        maybeWarnFailureShapedChunk(call.name, delta);
                     yield { type: "tool_delta", callId: call.id, name: call.name, ...(delta ? { delta } : {}), chunk };
                 }
+                for (const f of auditFailures) {
+                    yield { type: "tool_audit_failed", callId: call.id, name: call.name, label: f.label, error: f.error };
+                }
                 return { callId: call.id, output: combined, isError: false };
             }
+            for (const f of auditFailures) {
+                yield { type: "tool_audit_failed", callId: call.id, name: call.name, label: f.label, error: f.error };
+            }
             return { callId: call.id, output, isError: false };
         }
         catch (err) {
+            // Audit failures recorded before the main throw are still informational; surface them.
+            for (const f of auditFailures) {
+                yield { type: "tool_audit_failed", callId: call.id, name: call.name, label: f.label, error: f.error };
+            }
             return {
                 callId: call.id,
-                output: String(err),
+                output: formatToolError(err),
                 isError: true,
                 isFatal: Boolean(err?.isFatal),
                 errorKind: err?.errorKind,
@@ -185,7 +213,7 @@ export async function resolvePermissionRequest(request, ctx) {
         return {
             approved: false,
             responder: "permission_handler",
-            reason: `permission handler failed: ${String(err)}`,
+            reason: `permission handler failed: ${formatToolError(err)}`,
         };
     }
 }

package/dist/runtime/mcp-proxy-plane.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { LocalExecutionPlane } from "./execution-plane.js";
+import { formatToolError } from "../tools/errors.js";
 class McpConnection {
     serverName;
     config;
@@ -97,7 +98,7 @@ class McpConnection {
             return { output: text || JSON.stringify(result), isError: result.isError ?? false };
         }
         catch (err) {
-            return { output: String(err), isError: true };
+            return { output: formatToolError(err), isError: true };
         }
     }
     async stop() {

package/dist/runtime/process-sandbox-plane.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { mkdir } from "node:fs/promises";
 import { tool } from "../tools/index.js";
 import { LocalExecutionPlane } from "./execution-plane.js";
+import { formatToolError } from "../tools/errors.js";
 /**
  * ExecutionPlane that runs subprocesses with a sandbox directory as cwd.
  * Extends LocalExecutionPlane with two built-in tools:
@@ -73,7 +74,7 @@ export class ProcessSandboxPlane extends LocalExecutionPlane {
             child.stdout.on("data", capture);
             child.stderr.on("data", capture);
             child.on("close", code => settle(Buffer.concat(chunks).toString("utf8"), code !== 0));
-            child.on("error", err => settle(String(err), true));
+            child.on("error", err => settle(formatToolError(err), true));
         });
     }
     makeBashTool() {

package/dist/runtime/remote-vpc-plane.js

@@ -1,4 +1,5 @@
 import { LocalExecutionPlane } from "./execution-plane.js";
+import { formatToolError } from "../tools/errors.js";
 /**
  * ExecutionPlane that forwards tool calls over HTTP to a worker inside a customer VPC.
  *
@@ -76,7 +77,7 @@ export class RemoteVpcPlane {
             return { output: result.output, isError: result.isError ?? false };
         }
         catch (err) {
-            return { output: String(err), isError: true };
+            return { output: formatToolError(err), isError: true };
         }
     }
 }

package/dist/runtime/runner.js

@@ -15,6 +15,7 @@ import { governancePolicyToKernelEvent, governanceFilterSchema } from "../govern
 import { kernelObservationToSessionEvent, withCategory } from "./kernel-event-log.js";
 import { assertNativeProfile } from "./os-profile.js";
 import { LargeResultSpool } from "./large-result-spool.js";
+import { formatToolError } from "../tools/errors.js";
 export class RuntimeRunner {
     opts;
     interrupted = false;
@@ -381,7 +382,7 @@ export class RuntimeRunner {
             return ok(reducer(inputs), "completed");
         }
         catch (err) {
-            return ok(`reducer "${node.reducer}" threw: ${err instanceof Error ? err.message : String(err)}`, "error");
+            return ok(`reducer "${node.reducer}" threw: ${formatToolError(err)}`, "error");
         }
     }
     /**
@@ -1114,7 +1115,7 @@ export class RuntimeRunner {
                         if (abortSignal?.aborted) {
                             this.interrupted = true;
                         }
-                        const errMsg = String(err).toLowerCase();
+                        const errMsg = formatToolError(err).toLowerCase();
                         if ((errMsg.includes("413") || errMsg.includes("too long") || errMsg.includes("context length exceeded") || errMsg.includes("context_length_exceeded")) &&
                             !hasAttemptedReactiveCompact) {
                             hasAttemptedReactiveCompact = true;
@@ -1124,7 +1125,7 @@ export class RuntimeRunner {
                             }
                         }
                         if (!shouldRetry) {
-                            yield { type: "error", message: String(err) };
+                            yield { type: "error", message: formatToolError(err) };
                             action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
                             break;
                         }
@@ -1405,7 +1406,7 @@ export class RuntimeRunner {
             // Classify by NAPI status code or message pattern — `invalid_arg` for surface-shape rejects,
             // `error` for everything else — then emit run_terminal so observability sees a clean end.
             // The yield-error path mirrors what the in-flight provider-stream catch does.
-            const errMsg = err instanceof Error ? err.message : String(err);
+            const errMsg = formatToolError(err);
             const code = err.code;
             const isInvalidArg = code === "InvalidArg" ||
                 errMsg.toLowerCase().includes("invalidarg") ||

package/dist/tools/errors.d.ts

@@ -0,0 +1,59 @@
+import type { ToolExecContext, RegisteredTool } from "./index.js";
+/**
+ * Stable JSON shape returned to the model by `safeTool`. The model can branch on `code` instead
+ * of pattern-matching a free-form string. `hint` is the self-correcting affordance — a short
+ * suggestion ("call document_outline first") that the agent can follow on its own.
+ */
+export interface ToolEnvelopeOk<T = unknown> {
+    success: true;
+    data?: T;
+}
+export interface ToolEnvelopeFail {
+    success: false;
+    code: string;
+    error: string;
+    hint?: string;
+}
+export type ToolEnvelope<T = unknown> = ToolEnvelopeOk<T> | ToolEnvelopeFail;
+/**
+ * Error class understood by `safeTool` and by the runtime's error-aware serialization. A throw
+ * of `ToolError` produces `{ success:false, code, error, hint? }`; a plain `Error` (or anything
+ * with a string `.code`/`.hint`) is honored too, so existing code that already sets `code` on a
+ * custom Error keeps working without migration.
+ */
+export declare class ToolError extends Error {
+    code: string;
+    hint?: string;
+    constructor(message: string, opts?: {
+        code?: string;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+export declare function ok<T>(data?: T): ToolEnvelopeOk<T>;
+export declare function fail(code: string, error: string, hint?: string): ToolEnvelopeFail;
+/**
+ * Error-aware serialization for tool-execution error paths. Replaces `String(err)` at the
+ * sites that hand the model (or the host's stream) a failure message.
+ *
+ * - `Error` with no extra fields → `err.message` (clean, no `"Error: "` prefix).
+ * - `Error` carrying `code` / `hint` / `cause` → JSON `{message, name?, code?, hint?, cause?}`.
+ * - Plain objects → `JSON.stringify(...)` (replaces the old `"[object Object]"`).
+ * - Primitives / null / undefined → `String(...)` (unchanged).
+ */
+export declare function formatToolError(err: unknown): string;
+/**
+ * `tool()` equivalent that wraps the body in a try/catch and returns a stable
+ * `{success, code, error, hint?}` JSON envelope to the model:
+ *
+ * - body returns plain data → `{success:true, data}`
+ * - body returns an envelope (via `ok()`/`fail()`) → passed through
+ * - body throws `ToolError` → `{success:false, code, error, hint?}`
+ * - body throws any other `Error` → `{success:false, code: error.code ?? "internal", error: error.message}`
+ * - body throws a non-Error → `{success:false, code:"internal", error: formatToolError(...)}`
+ *
+ * The classic `tool()` factory is unchanged. `safeTool` is opt-in: import and switch one tool at
+ * a time. Designed for the consumer-side pattern users had to hand-roll to escape the legacy
+ * `String(err)` foot-gun.
+ */
+export declare function safeTool<T = unknown>(name: string, description: string, parameters: Record<string, unknown>, fn: (args: Record<string, unknown>, ctx?: ToolExecContext) => Promise<ToolEnvelope<T> | T> | ToolEnvelope<T> | T): RegisteredTool;

package/dist/tools/errors.js

@@ -0,0 +1,113 @@
+import { tool } from "./index.js";
+/**
+ * Error class understood by `safeTool` and by the runtime's error-aware serialization. A throw
+ * of `ToolError` produces `{ success:false, code, error, hint? }`; a plain `Error` (or anything
+ * with a string `.code`/`.hint`) is honored too, so existing code that already sets `code` on a
+ * custom Error keeps working without migration.
+ */
+export class ToolError extends Error {
+    code;
+    hint;
+    constructor(message, opts = {}) {
+        super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = "ToolError";
+        this.code = opts.code ?? "internal";
+        if (opts.hint !== undefined)
+            this.hint = opts.hint;
+    }
+}
+export function ok(data) {
+    return data === undefined ? { success: true } : { success: true, data };
+}
+export function fail(code, error, hint) {
+    return hint === undefined ? { success: false, code, error } : { success: false, code, error, hint };
+}
+function isEnvelope(v) {
+    return typeof v === "object" && v !== null && "success" in v &&
+        typeof v.success === "boolean";
+}
+/**
+ * Error-aware serialization for tool-execution error paths. Replaces `String(err)` at the
+ * sites that hand the model (or the host's stream) a failure message.
+ *
+ * - `Error` with no extra fields → `err.message` (clean, no `"Error: "` prefix).
+ * - `Error` carrying `code` / `hint` / `cause` → JSON `{message, name?, code?, hint?, cause?}`.
+ * - Plain objects → `JSON.stringify(...)` (replaces the old `"[object Object]"`).
+ * - Primitives / null / undefined → `String(...)` (unchanged).
+ */
+export function formatToolError(err) {
+    if (err == null)
+        return String(err);
+    if (typeof err === "string")
+        return err;
+    if (err instanceof Error) {
+        const anyErr = err;
+        const code = anyErr.code;
+        const hint = anyErr.hint;
+        const cause = anyErr.cause;
+        if (code === undefined && hint === undefined && cause === undefined) {
+            return err.message || err.name || "Error";
+        }
+        const payload = { message: err.message };
+        if (err.name && err.name !== "Error")
+            payload.name = err.name;
+        if (code !== undefined)
+            payload.code = code;
+        if (hint !== undefined)
+            payload.hint = hint;
+        if (cause !== undefined)
+            payload.cause = cause instanceof Error ? cause.message : cause;
+        try {
+            return JSON.stringify(payload);
+        }
+        catch {
+            return err.message || err.name || "Error";
+        }
+    }
+    if (typeof err === "object") {
+        try {
+            return JSON.stringify(err);
+        }
+        catch {
+            return Object.prototype.toString.call(err);
+        }
+    }
+    return String(err);
+}
+/**
+ * `tool()` equivalent that wraps the body in a try/catch and returns a stable
+ * `{success, code, error, hint?}` JSON envelope to the model:
+ *
+ * - body returns plain data → `{success:true, data}`
+ * - body returns an envelope (via `ok()`/`fail()`) → passed through
+ * - body throws `ToolError` → `{success:false, code, error, hint?}`
+ * - body throws any other `Error` → `{success:false, code: error.code ?? "internal", error: error.message}`
+ * - body throws a non-Error → `{success:false, code:"internal", error: formatToolError(...)}`
+ *
+ * The classic `tool()` factory is unchanged. `safeTool` is opt-in: import and switch one tool at
+ * a time. Designed for the consumer-side pattern users had to hand-roll to escape the legacy
+ * `String(err)` foot-gun.
+ */
+export function safeTool(name, description, parameters, fn) {
+    const wrapped = async (args, ctx) => {
+        try {
+            const result = await fn(args, ctx);
+            if (isEnvelope(result))
+                return JSON.stringify(result);
+            return JSON.stringify(ok(result));
+        }
+        catch (err) {
+            if (err instanceof ToolError) {
+                return JSON.stringify(fail(err.code, err.message || err.name, err.hint));
+            }
+            if (err instanceof Error) {
+                const anyErr = err;
+                const code = typeof anyErr.code === "string" ? anyErr.code : "internal";
+                const hint = typeof anyErr.hint === "string" ? anyErr.hint : undefined;
+                return JSON.stringify(fail(code, err.message || err.name || "Error", hint));
+            }
+            return JSON.stringify(fail("internal", formatToolError(err)));
+        }
+    };
+    return tool(name, description, parameters, wrapped);
+}

package/dist/tools/index.d.ts

@@ -1,9 +1,16 @@
 import type { ToolChunk, ToolSchema, ToolResult } from "../types.js";
 /** M3/G4: the runtime context a tool may read when executing. Carries the working directory the tool
  *  should operate in — set to a sub-agent's git worktree for `isolation: "worktree"` nodes. A narrow,
- *  dependency-free shape; the execution plane's `RunContext` is structurally assignable to it. */
+ *  dependency-free shape; the execution plane's `RunContext` is structurally assignable to it.
+ *
+ *  `audit` is the "best-effort post-commit side-effect" channel: wrap an audit-log write,
+ *  metrics emit, or any non-essential persistence in `await ctx.audit(label, () => store.write(...))`.
+ *  If the side-effect throws, the failure is recorded as a `tool_audit_failed` stream event and
+ *  the tool still completes successfully — avoiding the foot-gun where a transient audit-store
+ *  outage flips an already-committed write into `isError: true` and triggers a duplicate retry. */
 export interface ToolExecContext {
     cwd?: string;
+    audit?: (label: string, fn: () => Promise<void> | void) => Promise<void>;
 }
 export interface RegisteredTool {
     schema: ToolSchema;
@@ -23,4 +30,5 @@ export declare function executeTools(calls: {
     name: string;
     arguments: string;
 }[], registry: Map<string, RegisteredTool>): Promise<ToolResult[]>;
+export declare function maybeWarnFailureShapedChunk(toolName: string, deltaText: string): void;
 export declare const readFile: RegisteredTool;

package/dist/tools/index.js

@@ -1,3 +1,4 @@
+import { formatToolError } from "./errors.js";
 export function tool(name, description, parameters, fn) {
     return {
         schema: { name, description, parameters: JSON.stringify(parameters) },
@@ -36,6 +37,22 @@ export function validateToolArguments(schemaJson, args) {
 function validateValue(schema, parent, key, path, state) {
     let value = parent[key];
     const expectedType = schema.type;
+    // 0. 多态联合 (oneOf / anyOf) —— 先于单一 type 分支匹配
+    const union = (schema.oneOf ?? schema.anyOf);
+    if (Array.isArray(union)) {
+        for (const sub of union) {
+            // 先克隆再试：避免某分支的 auto-cast/裁剪部分改写后又失败，污染后续分支
+            const probe = { v: structuredClone(parent[key]) };
+            const probeState = { repaired: false };
+            if (!validateValue(sub, probe, "v", path, probeState)) {
+                parent[key] = probe.v; // 接受首个匹配分支(连同它内部的 repair)
+                if (probeState.repaired)
+                    state.repaired = true;
+                return undefined;
+            }
+        }
+        return `${path} does not match any allowed shape`;
+    }
     // 1. 类型自动规整 (Auto-cast)
     if (typeof expectedType === "string") {
         if (expectedType === "boolean") {
@@ -91,14 +108,25 @@ function validateValue(schema, parent, key, path, state) {
             if (!value || typeof value !== "object" || Array.isArray(value))
                 return `${path} must be object`;
             const obj = value;
-            // 3a. 裁剪多余字段
+            // 3a. 裁剪多余字段 —— 尊重 additionalProperties。
+            // 缺省/false 维持旧的"裁剪"行为（所有现存工具都依赖它）；只有显式 true 或子 schema 才放行。
             const properties = schema.properties ?? {};
             const allowedKeys = new Set(Object.keys(properties));
+            const additional = schema.additionalProperties;
             for (const objKey of Object.keys(obj)) {
-                if (!allowedKeys.has(objKey)) {
-                    delete obj[objKey];
-                    state.repaired = true;
+                if (allowedKeys.has(objKey))
+                    continue;
+                if (additional === true)
+                    continue; // 任意键放行：不校验、不裁剪
+                if (additional && typeof additional === "object") {
+                    // 用子 schema 递归校验每个额外键的值（也会 auto-cast / 补默认）
+                    const err = validateValue(additional, obj, objKey, `${path}.${objKey}`, state);
+                    if (err)
+                        return err;
+                    continue;
                 }
+                delete obj[objKey]; // additionalProperties 缺省/false → 维持旧行为
+                state.repaired = true;
             }
             for (const required of schema.required ?? []) {
                 if (!(required in obj))
@@ -169,10 +197,44 @@ export async function executeTools(calls, registry) {
             return { callId: c.id, output, isError: false };
         }
         catch (err) {
-            return { callId: c.id, output: String(err), isError: true };
+            return { callId: c.id, output: formatToolError(err), isError: true };
         }
     }));
 }
+/**
+ * One-shot heuristic: detect when a streaming tool yielded text that *looks* like a failure
+ * envelope. The runtime cannot block the tool from doing it, but we warn (once per tool) so
+ * the author migrates to throwing — the canonical "streaming tool fails" path. Aligns with
+ * the non-streaming tool() / safeTool() contract: failures throw, successes return data.
+ */
+const _warnedFailureShapes = new Set();
+export function maybeWarnFailureShapedChunk(toolName, deltaText) {
+    if (!deltaText || _warnedFailureShapes.has(toolName))
+        return;
+    const trimmed = deltaText.trim();
+    if (trimmed.length < 2 || trimmed[0] !== "{")
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return;
+    const obj = parsed;
+    const looksLikeFailure = obj.success === false ||
+        obj.isError === true ||
+        obj.is_error === true;
+    if (!looksLikeFailure)
+        return;
+    _warnedFailureShapes.add(toolName);
+    console.warn(`[deepstrike] streaming tool "${toolName}" yielded a failure-shaped chunk ` +
+        `(success:false / isError:true). Streaming tools should fail by throwing; ` +
+        `the runtime will catch and surface the error consistently. ` +
+        `Returning a failure-shaped chunk is a foot-gun: the kernel still sees isError:false.`);
+}
 export const readFile = tool("read_file", "Read the contents of a file.", { type: "object", properties: { path: { type: "string" } }, required: ["path"] }, async ({ path }) => {
     const { readFile: fsRead } = await import("fs/promises");
     return fsRead(String(path), "utf8");

package/dist/types.d.ts

@@ -189,6 +189,16 @@ export interface ToolDeniedEvent extends StreamEvent {
     toolName: string;
     reason: string;
 }
+/** A tool's `ctx.audit(label, fn)` best-effort side-effect threw. The tool itself completed
+ *  successfully (no isError flip, no retry); this event lets the host log / monitor that an
+ *  audit-store / metrics-emit / non-essential persistence step failed. */
+export interface ToolAuditFailedEvent extends StreamEvent {
+    type: "tool_audit_failed";
+    callId: string;
+    name: string;
+    label: string;
+    error: string;
+}
 export interface TokenUsage {
     /** Full prompt size: uncached input + cache reads + cache writes. */
     inputTokens: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.23",
+    "@deepstrike/core": "0.2.25",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },