@builder.io/ai-utils 0.111.1 → 0.112.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.111.1",
+  "version": "0.112.1",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/codegen.d.ts

@@ -528,10 +528,10 @@ export declare const PublishEvidenceToolInputSchema: z.ZodObject<{
             "not-reproduced": "not-reproduced";
         }>;
         summary: z.ZodString;
-        screenshots: z.ZodArray<z.ZodObject<{
+        screenshots: z.ZodOptional<z.ZodArray<z.ZodObject<{
             path: z.ZodString;
             caption: z.ZodString;
-        }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         recordings: z.ZodOptional<z.ZodArray<z.ZodObject<{
             recording_id: z.ZodString;
         }, z.core.$strip>>>;
@@ -680,7 +680,7 @@ export interface TimelineSubmissionMetadata {
  * Configuration values proposed by the setup analyzer agent
  */
 export declare const SetupAnalysisValuesSchema: z.ZodObject<{
-    projectOverview: z.ZodObject<{
+    projectOverview: z.ZodNullable<z.ZodObject<{
         framework: z.ZodNullable<z.ZodString>;
         packageManager: z.ZodNullable<z.ZodEnum<{
             bun: "bun";
@@ -693,7 +693,7 @@ export declare const SetupAnalysisValuesSchema: z.ZodObject<{
             javascript: "javascript";
             typescript: "typescript";
         }>>;
-    }, z.core.$strip>;
+    }, z.core.$strip>>;
     rootDirectory: z.ZodNullable<z.ZodObject<{
         path: z.ZodString;
         reason: z.ZodString;
@@ -732,9 +732,86 @@ export declare const SetupAnalysisValuesSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type SetupAnalysisValues = z.infer<typeof SetupAnalysisValuesSchema>;
+/**
+ * What a ProposeConfig call may carry: any subset of the setup values. A
+ * nullable field set to null, or any field omitted, means "no suggestion";
+ * the array fields (runtimeDependencies, environmentVariables) aren't
+ * nullable, so `[]` or omitting them means the same. Either way the existing
+ * value is left unchanged when the user applies the proposal.
+ */
+export declare const ProposedSetupValuesSchema: z.ZodObject<{
+    projectOverview: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        framework: z.ZodNullable<z.ZodString>;
+        packageManager: z.ZodNullable<z.ZodEnum<{
+            bun: "bun";
+            npm: "npm";
+            pnpm: "pnpm";
+            yarn: "yarn";
+        }>>;
+        isMonorepo: z.ZodBoolean;
+        detectedLanguage: z.ZodNullable<z.ZodEnum<{
+            javascript: "javascript";
+            typescript: "typescript";
+        }>>;
+    }, z.core.$strip>>>;
+    rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        path: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    installCommand: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        command: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    runtimeDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        version: z.ZodString;
+        source: z.ZodString;
+    }, z.core.$strip>>>;
+    devServer: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        command: z.ZodString;
+        url: z.ZodString;
+        port: z.ZodNumber;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    environmentVariables: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        description: z.ZodString;
+        isRequired: z.ZodBoolean;
+        isSecret: z.ZodBoolean;
+        defaultValue: z.ZodNullable<z.ZodString>;
+        source: z.ZodString;
+    }, z.core.$strip>>>;
+    validationScript: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        command: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    npmrcContents: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    hasHotModuleReload: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        value: z.ZodBoolean;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProposedSetupValues = z.infer<typeof ProposedSetupValuesSchema>;
+/**
+ * True only when a proposal affirmatively says nothing needs installing: an
+ * explicitly empty install command (`{ command: "" }`) and an explicit empty
+ * `runtimeDependencies` list. A null or omitted install command means "no
+ * suggestion", so it is unknown rather than "no dependencies", even when the
+ * proposal also carries projectOverview.
+ */
+export declare function proposalNeedsNoDependencies(config: ProposedSetupValues | null | undefined): boolean;
+/**
+ * `noDependencies` for replaying a stored propose_config step. Uses the
+ * decision recorded on the action (`toolMeta.noDependencies`) when present,
+ * so a replay always matches the live run. Actions recorded before that
+ * marker existed keep the original replay reading (no install command and no
+ * runtime dependencies means nothing to install), so old sessions don't
+ * change on reload.
+ */
+export declare function replayedProposalNeedsNoDependencies(config: ProposedSetupValues | null | undefined, recorded: ToolActionMeta | undefined): boolean;
 export declare const ProposeConfigToolInputSchema: z.ZodObject<{
     config: z.ZodObject<{
-        projectOverview: z.ZodObject<{
+        projectOverview: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             framework: z.ZodNullable<z.ZodString>;
             packageManager: z.ZodNullable<z.ZodEnum<{
                 bun: "bun";
@@ -747,43 +824,43 @@ export declare const ProposeConfigToolInputSchema: z.ZodObject<{
                 javascript: "javascript";
                 typescript: "typescript";
             }>>;
-        }, z.core.$strip>;
-        rootDirectory: z.ZodNullable<z.ZodObject<{
+        }, z.core.$strip>>>;
+        rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             path: z.ZodString;
             reason: z.ZodString;
-        }, z.core.$strip>>;
-        installCommand: z.ZodNullable<z.ZodObject<{
+        }, z.core.$strip>>>;
+        installCommand: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             command: z.ZodString;
             reason: z.ZodString;
-        }, z.core.$strip>>;
-        runtimeDependencies: z.ZodArray<z.ZodObject<{
+        }, z.core.$strip>>>;
+        runtimeDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
             tool: z.ZodString;
             version: z.ZodString;
             source: z.ZodString;
-        }, z.core.$strip>>;
-        devServer: z.ZodNullable<z.ZodObject<{
+        }, z.core.$strip>>>;
+        devServer: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             command: z.ZodString;
             url: z.ZodString;
             port: z.ZodNumber;
             reason: z.ZodString;
-        }, z.core.$strip>>;
-        environmentVariables: z.ZodArray<z.ZodObject<{
+        }, z.core.$strip>>>;
+        environmentVariables: z.ZodOptional<z.ZodArray<z.ZodObject<{
             key: z.ZodString;
             description: z.ZodString;
             isRequired: z.ZodBoolean;
             isSecret: z.ZodBoolean;
             defaultValue: z.ZodNullable<z.ZodString>;
             source: z.ZodString;
-        }, z.core.$strip>>;
-        validationScript: z.ZodNullable<z.ZodObject<{
+        }, z.core.$strip>>>;
+        validationScript: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             command: z.ZodString;
             reason: z.ZodString;
-        }, z.core.$strip>>;
-        npmrcContents: z.ZodNullable<z.ZodString>;
-        hasHotModuleReload: z.ZodNullable<z.ZodObject<{
+        }, z.core.$strip>>>;
+        npmrcContents: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        hasHotModuleReload: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             value: z.ZodBoolean;
             reason: z.ZodString;
-        }, z.core.$strip>>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>;
     message: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -1706,10 +1783,10 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
                 "not-reproduced": "not-reproduced";
             }>;
             summary: z.ZodString;
-            screenshots: z.ZodArray<z.ZodObject<{
+            screenshots: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 path: z.ZodString;
                 caption: z.ZodString;
-            }, z.core.$strip>>;
+            }, z.core.$strip>>>;
             recordings: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 recording_id: z.ZodString;
             }, z.core.$strip>>>;
@@ -1762,7 +1839,7 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
     }, z.core.$strip>;
     ProposeConfig: z.ZodObject<{
         config: z.ZodObject<{
-            projectOverview: z.ZodObject<{
+            projectOverview: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                 framework: z.ZodNullable<z.ZodString>;
                 packageManager: z.ZodNullable<z.ZodEnum<{
                     bun: "bun";
@@ -1775,43 +1852,43 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
                     javascript: "javascript";
                     typescript: "typescript";
                 }>>;
-            }, z.core.$strip>;
-            rootDirectory: z.ZodNullable<z.ZodObject<{
+            }, z.core.$strip>>>;
+            rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                 path: z.ZodString;
                 reason: z.ZodString;
-            }, z.core.$strip>>;
-            installCommand: z.ZodNullable<z.ZodObject<{
+            }, z.core.$strip>>>;
+            installCommand: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                 command: z.ZodString;
                 reason: z.ZodString;
-            }, z.core.$strip>>;
-            runtimeDependencies: z.ZodArray<z.ZodObject<{
+            }, z.core.$strip>>>;
+            runtimeDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 tool: z.ZodString;
                 version: z.ZodString;
                 source: z.ZodString;
-            }, z.core.$strip>>;
-            devServer: z.ZodNullable<z.ZodObject<{
+            }, z.core.$strip>>>;
+            devServer: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                 command: z.ZodString;
                 url: z.ZodString;
                 port: z.ZodNumber;
                 reason: z.ZodString;
-            }, z.core.$strip>>;
-            environmentVariables: z.ZodArray<z.ZodObject<{
+            }, z.core.$strip>>>;
+            environmentVariables: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 key: z.ZodString;
                 description: z.ZodString;
                 isRequired: z.ZodBoolean;
                 isSecret: z.ZodBoolean;
                 defaultValue: z.ZodNullable<z.ZodString>;
                 source: z.ZodString;
-            }, z.core.$strip>>;
-            validationScript: z.ZodNullable<z.ZodObject<{
+            }, z.core.$strip>>>;
+            validationScript: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                 command: z.ZodString;
                 reason: z.ZodString;
-            }, z.core.$strip>>;
-            npmrcContents: z.ZodNullable<z.ZodString>;
-            hasHotModuleReload: z.ZodNullable<z.ZodObject<{
+            }, z.core.$strip>>>;
+            npmrcContents: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            hasHotModuleReload: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                 value: z.ZodBoolean;
                 reason: z.ZodString;
-            }, z.core.$strip>>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>;
         message: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
@@ -2406,6 +2483,15 @@ export declare const PublishAgentMessageRequestSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>], "type">>]>;
         is_error: z.ZodOptional<z.ZodBoolean>;
+        error_kind: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+            command_not_found: "command_not_found";
+            guardrail: "guardrail";
+            invalid_input: "invalid_input";
+            non_zero_exit: "non_zero_exit";
+            policy_block: "policy_block";
+            tool_failure: "tool_failure";
+            user_abort: "user_abort";
+        }>>>;
         cache: z.ZodOptional<z.ZodBoolean>;
         ephemeral: z.ZodOptional<z.ZodBoolean>;
         structured_result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -2817,6 +2903,15 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>], "type">>]>;
         is_error: z.ZodOptional<z.ZodBoolean>;
+        error_kind: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+            command_not_found: "command_not_found";
+            guardrail: "guardrail";
+            invalid_input: "invalid_input";
+            non_zero_exit: "non_zero_exit";
+            policy_block: "policy_block";
+            tool_failure: "tool_failure";
+            user_abort: "user_abort";
+        }>>>;
         cache: z.ZodOptional<z.ZodBoolean>;
         ephemeral: z.ZodOptional<z.ZodBoolean>;
         structured_result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -3185,6 +3280,19 @@ export interface ActionItem {
     incomplete?: boolean;
     suggestions?: PromptSuggestion[];
     errors?: string[];
+    /**
+     * Decisions the service recorded for a tool call, persisted with the
+     * action so replays reproduce what the live run showed. Optional and
+     * ignored by clients that don't know it.
+     */
+    toolMeta?: ToolActionMeta;
+}
+export interface ToolActionMeta {
+    /**
+     * ProposeConfig: `proposalNeedsNoDependencies` for this call's config.
+     * Absent on actions recorded before it existed.
+     */
+    noDependencies?: boolean;
 }
 export interface GenerateCompletionStepThinking {
     type: "thinking";
@@ -3647,7 +3755,8 @@ export interface GenerateCompletionStepIde {
 }
 export interface GenerateCompletionStepProposeConfig {
     type: "propose_config";
-    config: SetupAnalysisValues;
+    /** May be partial: omitted or null fields mean "no suggestion". */
+    config: ProposedSetupValues;
     message?: string;
     /** When true, the project requires no dependency installation. The UI should not show an Apply dialog for dependencies. */
     noDependencies?: boolean;

package/src/codegen.js

@@ -277,7 +277,7 @@ export const PowerShellToolInputSchema = z
         description: "The PowerShell command to run, for example 'npm install' or 'yarn test'",
     }),
     timeout: z.number().nullish().meta({
-        description: "The timeout in milliseconds for the command to run. Choose an appropriate timeout based on the command",
+        description: "Optional timeout in milliseconds (max/default 600000). Omit it for installs, builds, type checks and test runs, which are often slow on Windows.",
     }),
     description: z.string().nullish().meta({
         description: "A human readable description of the command to run, for example 'install dependencies' or 'run tests'. This description will be used to explain the command to the user.",
@@ -789,8 +789,9 @@ export const PublishEvidenceToolInputSchema = z
             }),
             caption: z.string(),
         }))
+            .optional()
             .meta({
-            description: "Stills that support the fix; the PR shows them under the recording.",
+            description: "Stills that support the fix; the PR shows them under the recording. Expected for a 'fixed' issue; omit it or send [] when there are none.",
         }),
         recordings: z
             .array(z.object({
@@ -847,12 +848,17 @@ export const ReportTestOutcomeToolInputSchema = z
  */
 export const SetupAnalysisValuesSchema = z
     .object({
-    projectOverview: z.object({
+    // Nullable: in a partial proposal (e.g. only runtimeDependencies) a null
+    // field, or an empty array field, means "no suggestion" and leaves the
+    // existing value unchanged when applied.
+    projectOverview: z
+        .object({
         framework: z.string().nullable(),
         packageManager: z.enum(["npm", "yarn", "pnpm", "bun"]).nullable(),
         isMonorepo: z.boolean(),
         detectedLanguage: z.enum(["typescript", "javascript"]).nullable(),
-    }),
+    })
+        .nullable(),
     rootDirectory: z
         .object({
         path: z.string(),
@@ -901,9 +907,52 @@ export const SetupAnalysisValuesSchema = z
         .nullable(),
 })
     .meta({ title: "SetupAnalysisValues" });
+/**
+ * What a ProposeConfig call may carry: any subset of the setup values. A
+ * nullable field set to null, or any field omitted, means "no suggestion";
+ * the array fields (runtimeDependencies, environmentVariables) aren't
+ * nullable, so `[]` or omitting them means the same. Either way the existing
+ * value is left unchanged when the user applies the proposal.
+ */
+export const ProposedSetupValuesSchema = SetupAnalysisValuesSchema.partial().meta({ title: "ProposedSetupValues" });
+/**
+ * True only when a proposal affirmatively says nothing needs installing: an
+ * explicitly empty install command (`{ command: "" }`) and an explicit empty
+ * `runtimeDependencies` list. A null or omitted install command means "no
+ * suggestion", so it is unknown rather than "no dependencies", even when the
+ * proposal also carries projectOverview.
+ */
+export function proposalNeedsNoDependencies(config) {
+    var _a;
+    if (!config || !Array.isArray(config.runtimeDependencies))
+        return false;
+    if (config.runtimeDependencies.length > 0)
+        return false;
+    const installCommand = config.installCommand;
+    return (installCommand != null &&
+        typeof installCommand === "object" &&
+        !((_a = installCommand.command) === null || _a === void 0 ? void 0 : _a.trim()));
+}
+/**
+ * `noDependencies` for replaying a stored propose_config step. Uses the
+ * decision recorded on the action (`toolMeta.noDependencies`) when present,
+ * so a replay always matches the live run. Actions recorded before that
+ * marker existed keep the original replay reading (no install command and no
+ * runtime dependencies means nothing to install), so old sessions don't
+ * change on reload.
+ */
+export function replayedProposalNeedsNoDependencies(config, recorded) {
+    var _a;
+    if (typeof (recorded === null || recorded === void 0 ? void 0 : recorded.noDependencies) === "boolean") {
+        return recorded.noDependencies;
+    }
+    return (config != null &&
+        !((_a = config.installCommand) === null || _a === void 0 ? void 0 : _a.command) &&
+        (!config.runtimeDependencies || config.runtimeDependencies.length === 0));
+}
 export const ProposeConfigToolInputSchema = z
     .object({
-    config: SetupAnalysisValuesSchema,
+    config: ProposedSetupValuesSchema,
     message: z.string().optional(),
 })
     .meta({ title: "ProposeConfigToolInput" });

package/src/index.d.ts

@@ -26,4 +26,5 @@ export * from "./credits.js";
 export * from "./embeddings.js";
 export * from "./system-one.js";
 export * from "./mcp-servers.js";
+export * from "./tool-failure.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/index.js

@@ -26,4 +26,5 @@ export * from "./credits.js";
 export * from "./embeddings.js";
 export * from "./system-one.js";
 export * from "./mcp-servers.js";
+export * from "./tool-failure.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/messages.d.ts

@@ -570,6 +570,15 @@ export declare const ContentMessageItemToolResultSchema: z.ZodObject<{
         }, z.core.$strip>;
     }, z.core.$strip>], "type">>]>;
     is_error: z.ZodOptional<z.ZodBoolean>;
+    error_kind: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        command_not_found: "command_not_found";
+        guardrail: "guardrail";
+        invalid_input: "invalid_input";
+        non_zero_exit: "non_zero_exit";
+        policy_block: "policy_block";
+        tool_failure: "tool_failure";
+        user_abort: "user_abort";
+    }>>>;
     cache: z.ZodOptional<z.ZodBoolean>;
     ephemeral: z.ZodOptional<z.ZodBoolean>;
     structured_result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;

package/src/messages.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ToolFailureKindSchema } from "./tool-failure.js";
 export function getContentText(message) {
     if (typeof message === "string") {
         return message;
@@ -167,6 +168,11 @@ export const ContentMessageItemToolResultSchema = z
         ])),
     ]),
     is_error: z.boolean().optional(),
+    // An unrecognized kind (e.g. from a newer client) parses as absent so a
+    // strict parse never rejects the request over it.
+    error_kind: ToolFailureKindSchema.optional().catch(undefined).meta({
+        description: "Why the call failed, set by the code that failed. Only meaningful with `is_error: true`; when absent the service infers the reason from the message.",
+    }),
     cache: z.boolean().optional(),
     ephemeral: z.boolean().optional(),
     structured_result: z.record(z.string(), z.any()).optional(),

package/src/propose-config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/src/propose-config.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { proposalNeedsNoDependencies, replayedProposalNeedsNoDependencies, } from "./codegen";
+const overview = {
+    framework: "vite",
+    packageManager: "npm",
+    isMonorepo: false,
+    detectedLanguage: "typescript",
+};
+describe("proposalNeedsNoDependencies", () => {
+    it("is unknown (false) when the install command is null, even with projectOverview", () => {
+        // null means "no suggestion", and partial proposals may carry
+        // projectOverview forward, so this is not an affirmative signal.
+        expect(proposalNeedsNoDependencies({
+            projectOverview: overview,
+            installCommand: null,
+            runtimeDependencies: [],
+        })).toBe(false);
+    });
+    it("is true for an explicitly empty install command and no runtime deps", () => {
+        expect(proposalNeedsNoDependencies({
+            installCommand: { command: "", reason: "nothing to install" },
+            runtimeDependencies: [],
+        })).toBe(true);
+    });
+    it("is unknown (false) for a partial env-vars-only proposal", () => {
+        expect(proposalNeedsNoDependencies({
+            projectOverview: null,
+            installCommand: null,
+            runtimeDependencies: [],
+            environmentVariables: [
+                {
+                    key: "API_URL",
+                    description: "",
+                    isRequired: true,
+                    isSecret: false,
+                    defaultValue: null,
+                    source: ".env.example",
+                },
+            ],
+        })).toBe(false);
+        expect(proposalNeedsNoDependencies({ environmentVariables: [] })).toBe(false);
+    });
+    it("is false when something needs installing or config is missing", () => {
+        expect(proposalNeedsNoDependencies({
+            projectOverview: overview,
+            installCommand: { command: "npm ci", reason: "lockfile" },
+            runtimeDependencies: [],
+        })).toBe(false);
+        expect(proposalNeedsNoDependencies({
+            projectOverview: overview,
+            installCommand: null,
+            runtimeDependencies: [{ tool: "node", version: "22", source: "" }],
+        })).toBe(false);
+        expect(proposalNeedsNoDependencies(undefined)).toBe(false);
+    });
+});
+describe("replayedProposalNeedsNoDependencies", () => {
+    const fullShapeProposal = {
+        projectOverview: overview,
+        rootDirectory: null,
+        installCommand: null,
+        runtimeDependencies: [],
+        devServer: null,
+        environmentVariables: [],
+        validationScript: null,
+        npmrcContents: null,
+        hasHotModuleReload: null,
+    };
+    it("uses the recorded decision, so a new full-shape proposal replays like live", () => {
+        const live = proposalNeedsNoDependencies(fullShapeProposal);
+        expect(live).toBe(false);
+        expect(replayedProposalNeedsNoDependencies(fullShapeProposal, {
+            noDependencies: live,
+        })).toBe(false);
+    });
+    it("uses a recorded decision for a partial proposal too", () => {
+        const partial = { environmentVariables: [], runtimeDependencies: [] };
+        expect(replayedProposalNeedsNoDependencies(partial, {
+            noDependencies: proposalNeedsNoDependencies(partial),
+        })).toBe(false);
+        expect(replayedProposalNeedsNoDependencies({
+            installCommand: { command: "", reason: "static" },
+            runtimeDependencies: [],
+        }, { noDependencies: true })).toBe(true);
+    });
+    it("keeps the original replay reading for legacy actions without a marker", () => {
+        expect(replayedProposalNeedsNoDependencies(fullShapeProposal, undefined)).toBe(true);
+        expect(replayedProposalNeedsNoDependencies({
+            ...fullShapeProposal,
+            installCommand: { command: "npm ci", reason: "lockfile" },
+        }, undefined)).toBe(false);
+        expect(replayedProposalNeedsNoDependencies(undefined, undefined)).toBe(false);
+    });
+});

package/src/tool-failure.d.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+/**
+ * Why a tool result came out the way it did. `is_error` alone conflates a
+ * broken tool with a tool that worked and reported a negative outcome (no
+ * matches, failing tests), so only `tool_failure` means the tool itself broke.
+ * Closed set: these are the values of the `reason` label on the service's
+ * tool-result metric, so adding one adds metric series.
+ */
+export declare const ToolResultReasonSchema: z.ZodEnum<{
+    command_not_found: "command_not_found";
+    empty_result: "empty_result";
+    guardrail: "guardrail";
+    invalid_input: "invalid_input";
+    non_zero_exit: "non_zero_exit";
+    policy_block: "policy_block";
+    success: "success";
+    tool_failure: "tool_failure";
+    user_abort: "user_abort";
+}>;
+export type ToolResultReason = z.infer<typeof ToolResultReasonSchema>;
+/** A reason only a failed tool call can have. */
+export declare const ToolFailureKindSchema: z.ZodEnum<{
+    command_not_found: "command_not_found";
+    guardrail: "guardrail";
+    invalid_input: "invalid_input";
+    non_zero_exit: "non_zero_exit";
+    policy_block: "policy_block";
+    tool_failure: "tool_failure";
+    user_abort: "user_abort";
+}>;
+export type ToolFailureKind = z.infer<typeof ToolFailureKindSchema>;
+export declare function isToolFailureKind(value: unknown): value is ToolFailureKind;
+export interface ToolFailure {
+    kind: ToolFailureKind;
+    /** Tool-specific detail for logs and tests. Never a metric label. */
+    code?: string;
+    /** Whether repeating the same call unchanged can succeed. */
+    retryable: boolean;
+}
+export interface Failure extends ToolFailure {
+    /** Shown to the model or the user; never empty. */
+    message: string;
+}
+/**
+ * Return type for fallible helpers, in place of `T | undefined`, so a caller
+ * can't drop the reason a call failed.
+ */
+export type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: Failure;
+};
+export declare function okResult<T>(value: T): {
+    ok: true;
+    value: T;
+};
+export declare function failResult(kind: ToolFailureKind, message: string, options: {
+    retryable: boolean;
+    code?: string;
+}): {
+    ok: false;
+    error: Failure;
+};
+/**
+ * Throw from inside a tool to fail it with a kind. A tool runner turns it
+ * into a typed failure; any other thrown error stays untyped.
+ */
+export declare class ToolError extends Error {
+    readonly failure: ToolFailure;
+    constructor(kind: ToolFailureKind, message: string, options: {
+        retryable: boolean;
+        code?: string;
+        cause?: unknown;
+    });
+}
+/** A failed tool resolution, in the shape both the CLI and the service runners accept. */
+export interface ToolFailureReturn {
+    isError: true;
+    toolResult: string;
+    error: ToolFailure;
+    title?: string;
+    structuredResult?: Record<string, any>;
+}
+export declare function toolFail(kind: ToolFailureKind, message: string, options: {
+    retryable: boolean;
+    code?: string;
+    title?: string;
+    structuredResult?: Record<string, any>;
+}): ToolFailureReturn;
+/** Passes a fallible helper's failure through as the tool's own. */
+export declare function toolFailFrom(failure: Failure, options?: {
+    title?: string;
+}): ToolFailureReturn;

package/src/tool-failure.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+/**
+ * Why a tool result came out the way it did. `is_error` alone conflates a
+ * broken tool with a tool that worked and reported a negative outcome (no
+ * matches, failing tests), so only `tool_failure` means the tool itself broke.
+ * Closed set: these are the values of the `reason` label on the service's
+ * tool-result metric, so adding one adds metric series.
+ */
+export const ToolResultReasonSchema = z
+    .enum([
+    "success",
+    "empty_result",
+    "non_zero_exit",
+    "command_not_found",
+    "policy_block",
+    "guardrail",
+    "invalid_input",
+    "user_abort",
+    "tool_failure",
+])
+    .meta({ title: "ToolResultReason" });
+/** A reason only a failed tool call can have. */
+export const ToolFailureKindSchema = ToolResultReasonSchema.exclude([
+    "success",
+    "empty_result",
+]).meta({ title: "ToolFailureKind" });
+export function isToolFailureKind(value) {
+    return ToolFailureKindSchema.safeParse(value).success;
+}
+export function okResult(value) {
+    return { ok: true, value };
+}
+export function failResult(kind, message, options) {
+    return { ok: false, error: { kind, message, ...options } };
+}
+/**
+ * Throw from inside a tool to fail it with a kind. A tool runner turns it
+ * into a typed failure; any other thrown error stays untyped.
+ */
+export class ToolError extends Error {
+    constructor(kind, message, options) {
+        super(message, { cause: options.cause });
+        this.name = "ToolError";
+        this.failure = {
+            kind,
+            retryable: options.retryable,
+            ...(options.code ? { code: options.code } : {}),
+        };
+    }
+}
+export function toolFail(kind, message, options) {
+    const { retryable, code, title, structuredResult } = options;
+    return {
+        isError: true,
+        toolResult: message,
+        error: { kind, retryable, ...(code ? { code } : {}) },
+        ...(title !== undefined ? { title } : {}),
+        ...(structuredResult ? { structuredResult } : {}),
+    };
+}
+/** Passes a fallible helper's failure through as the tool's own. */
+export function toolFailFrom(failure, options = {}) {
+    return toolFail(failure.kind, failure.message, {
+        retryable: failure.retryable,
+        code: failure.code,
+        title: options.title,
+    });
+}

package/src/tool-failure.test.d.ts

@@ -0,0 +1 @@
+export {};

package/src/tool-failure.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { ContentMessageItemToolResultSchema } from "./messages";
+import { failResult, isToolFailureKind, okResult } from "./tool-failure";
+const base = {
+    type: "tool_result",
+    tool_use_id: "toolu_1",
+    content: "Grep produced too much output.",
+    is_error: true,
+};
+describe("tool_result error_kind", () => {
+    it("keeps a valid kind", () => {
+        expect(ContentMessageItemToolResultSchema.parse({
+            ...base,
+            error_kind: "guardrail",
+        }).error_kind).toBe("guardrail");
+    });
+    it("parses an unknown kind as absent instead of rejecting", () => {
+        const parsed = ContentMessageItemToolResultSchema.parse({
+            ...base,
+            error_kind: "rate_limited",
+        });
+        expect(parsed.error_kind).toBeUndefined();
+        expect(parsed.content).toBe(base.content);
+    });
+    it("parses a result without a kind", () => {
+        expect(ContentMessageItemToolResultSchema.parse(base).error_kind).toBeUndefined();
+    });
+    it("strips other unknown keys, as older schemas strip error_kind", () => {
+        const parsed = ContentMessageItemToolResultSchema.parse({
+            ...base,
+            error_code: "x",
+        });
+        expect(parsed).not.toHaveProperty("error_code");
+    });
+});
+describe("isToolFailureKind", () => {
+    it.each(["guardrail", "tool_failure", "user_abort"])("accepts %s", (kind) => {
+        expect(isToolFailureKind(kind)).toBe(true);
+    });
+    it.each(["success", "empty_result", "rate_limited", 1, undefined])("rejects %s", (kind) => {
+        expect(isToolFailureKind(kind)).toBe(false);
+    });
+});
+describe("Result helpers", () => {
+    it("builds both variants", () => {
+        expect(okResult(3)).toEqual({ ok: true, value: 3 });
+        expect(failResult("invalid_input", "Bad URL", { retryable: false, code: "url" })).toEqual({
+            ok: false,
+            error: {
+                kind: "invalid_input",
+                message: "Bad URL",
+                retryable: false,
+                code: "url",
+            },
+        });
+    });
+});