@deepstrike/sdk 0.2.22 → 0.2.24

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) },
@@ -169,10 +170,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

@@ -84,6 +84,15 @@ export interface UsageEvent extends StreamEvent {
     cacheReadInputTokens?: number;
     /** Prompt tokens written to cache this request (billed ~1.25x). Subset of inputTokens. */
     cacheCreationInputTokens?: number;
+    /** I1: per-slot pro-rata attribution of `cacheReadInputTokens`. Estimated, not authoritative —
+     *  Anthropic returns a single cache-read total, so the SDK divides it evenly across the slots
+     *  that carried a `cache_control` breakpoint on the request. Missing when the provider doesn't
+     *  honor `cache_control` (OpenAI-family auto-cache) or when no breakpoints were placed. */
+    cacheReadInputTokensBySlot?: {
+        system?: number;
+        tools?: number;
+        messages?: number;
+    };
 }
 export type ToolChunk = string | {
     type: "text";
@@ -180,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.22",
+  "version": "0.2.24",
   "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.22",
+    "@deepstrike/core": "0.2.24",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },