@agent-api/sdk 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog — @agent-api/sdk
 
+## 1.3.2
+
+### Added
+
+- Added volume image asset helpers for normalizing private volume paths and checking supported image paths/content types.
+
+## 1.3.1
+
+### Fixed
+
+- Made `local_workdir` grep behave like familiar grep: `path` may be omitted, a file path, or a directory subtree.
+- Model-facing `local_workdir` execution errors now return structured `{ ok: false, error }` tool results instead of aborting agent runs.
+
 ## 1.3.0
 
 ### Added

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export * from "./types/index.js";
 export { functionCallOutputInput, pendingFunctionCalls, runLocalFunctionHandlers, } from "./local-functions.js";
 export type { LocalFunctionHandler, LocalFunctionHandlers } from "./local-functions.js";
 export { mergeTools, publicToolToRequestTool, resolvePresetTools, resolvePresetToolsFromCatalog, } from "./preset-tools.js";
+export { isSupportedVolumeImageContentType, isSupportedVolumeImagePath, normalizeVolumeAssetPath, } from "./volume-assets.js";
 export type { PresetToolCatalogClient, ResolvePresetToolsOptions, ResolvePresetToolsResult, UnknownPresetToolBehavior, } from "./preset-tools.js";
 export { AuthResource, DeviceAuthFlowError, browserAuthSessionExpiresWithin } from "./resources/auth.js";

package/dist/index.js

@@ -4,4 +4,5 @@ export { APIError, APIConnectionError, APIStatusError, AuthenticationError, BadR
 export * from "./types/index.js";
 export { functionCallOutputInput, pendingFunctionCalls, runLocalFunctionHandlers, } from "./local-functions.js";
 export { mergeTools, publicToolToRequestTool, resolvePresetTools, resolvePresetToolsFromCatalog, } from "./preset-tools.js";
+export { isSupportedVolumeImageContentType, isSupportedVolumeImagePath, normalizeVolumeAssetPath, } from "./volume-assets.js";
 export { AuthResource, DeviceAuthFlowError, browserAuthSessionExpiresWithin } from "./resources/auth.js";

package/dist/local/core.d.ts

@@ -309,6 +309,7 @@ export declare class LocalFileStore {
     readLines(relativePath: string, params: LocalReadLinesParams): Promise<LocalFileLines>;
     patchLines(relativePath: string, params: LocalPatchLinesParams): Promise<LocalFileLinesPatch>;
     grep(params: LocalGrepParams): Promise<LocalGrepResponse>;
+    private grepCandidates;
     summarize(params?: LocalSummarizeParams): Promise<LocalSummary>;
     private walk;
 }

package/dist/local/core.js

@@ -310,7 +310,7 @@ export class LocalFileStore {
         const maxFiles = positiveInt(params.maxFiles, 500);
         const maxBytesPerFile = positiveInt(params.maxBytesPerFile, 512 * 1024);
         const maxLineLength = positiveInt(params.maxLineLength, 500);
-        const stats = await this.list(params.path ?? ".", { recursive: true, ignore: params.ignore });
+        const stats = await this.grepCandidates(params.path ?? ".", params.ignore);
         const matches = [];
         let filesScanned = 0;
         let scanTruncated = false;
@@ -348,6 +348,27 @@ export class LocalFileStore {
         }
         return { object: "list", matches, files_scanned: filesScanned, scan_truncated: scanTruncated };
     }
+    async grepCandidates(relativePath, ignore) {
+        const fullPath = this.resolvePath(relativePath);
+        const info = await stat(fullPath);
+        const portablePath = toPortablePath(path.relative(this.root, fullPath)) || ".";
+        if (ignored(portablePath, ignore)) {
+            return [];
+        }
+        if (info.isFile()) {
+            return [{
+                    path: portablePath,
+                    fullPath,
+                    type: "file",
+                    size: info.size,
+                    modifiedAt: info.mtime,
+                }];
+        }
+        if (info.isDirectory()) {
+            return await this.list(relativePath, { recursive: true, ignore });
+        }
+        return [];
+    }
     async summarize(params = {}) {
         const maxFiles = positiveInt(params.maxFiles, 2000);
         const maxPreviews = positiveInt(params.maxPreviews, 20);

package/dist/local/tools.d.ts

@@ -23,6 +23,7 @@ export declare class LocalWorkdirDriver {
     readonly accessMode: LocalWorkdirAccessMode;
     constructor(workdir: LocalWorkdir, options?: LocalWorkdirDriverOptions);
     dispatch(args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private dispatchUnsafe;
     requiresApproval(args: Record<string, unknown>): boolean;
     private dispatchApplyEdits;
     private dispatchWrite;

package/dist/local/tools.js

@@ -7,6 +7,15 @@ export class LocalWorkdirDriver {
         this.accessMode = options.accessMode ?? "approval";
     }
     async dispatch(args) {
+        const action = safeWorkdirAction(args);
+        try {
+            return await this.dispatchUnsafe(args);
+        }
+        catch (error) {
+            return localToolErrorResult(action, error);
+        }
+    }
+    async dispatchUnsafe(args) {
         const action = workdirAction(args);
         switch (action) {
             case "summarize":
@@ -45,7 +54,8 @@ export class LocalWorkdirDriver {
         if (this.accessMode === "full") {
             return false;
         }
-        return mutatingLocalWorkdirActions.has(workdirAction(args));
+        const action = safeWorkdirAction(args);
+        return action !== "unknown" && mutatingLocalWorkdirActions.has(action);
     }
     async dispatchApplyEdits(args) {
         const edits = editsArg(args);
@@ -129,6 +139,7 @@ const mutatingLocalWorkdirActions = new Set([
 const localWorkdirToolDescription = [
     "Inspect and modify the selected local workdir through one model-facing primitive.",
     "Use action=list/search/grep/summarize/context to discover files, read/read_lines for file content, preview_edits before edits, and apply_edits/write/mkdir/delete only when mutation is intended.",
+    "grep searches file contents for a literal substring; path may be omitted, a file path, or a directory subtree.",
     "In approval mode, mutating actions return requires_approval with a safe preview instead of changing files. In full mode, mutating actions execute immediately.",
     "Paths are relative to the selected local workdir; never use absolute paths.",
 ].join(" ");
@@ -139,7 +150,7 @@ function localWorkdirToolParameters() {
             enum: localWorkdirActions,
             description: "Workdir operation. Prefer summarize/list/search/grep before reading or editing. Prefer read_lines and apply_edits for source changes.",
         },
-        path: stringSchema("Relative path. File path for read/write/delete/edit actions; directory base for list/search/grep/summarize/context/snapshot."),
+        path: stringSchema("Relative path. File path for read/write/delete/edit actions. For grep, path may be a file or a directory subtree. For list/search/summarize/context/snapshot, path is a directory base."),
         query: stringSchema("Path/name query for search, or optional context query."),
         pattern: stringSchema("Literal text pattern for grep."),
         content: stringSchema("Text content for write."),
@@ -182,6 +193,10 @@ function workdirAction(args) {
     }
     return value;
 }
+function safeWorkdirAction(args) {
+    const value = typeof args.action === "string" ? args.action.trim().toLowerCase() : "";
+    return localWorkdirActions.includes(value) ? value : "unknown";
+}
 function summaryArgs(args) {
     return {
         path: optionalStringArg(args, "path"),
@@ -277,6 +292,27 @@ function localToolResult(action, value) {
     }
     return { ok: true, action, result };
 }
+function localToolErrorResult(action, error) {
+    const details = errorDetails(error);
+    return {
+        ok: false,
+        action,
+        error: details.message,
+        code: details.code,
+        path: details.path,
+    };
+}
+function errorDetails(error) {
+    if (error instanceof Error) {
+        const record = error;
+        return {
+            code: typeof record.code === "string" ? record.code : undefined,
+            message: error.message || "local_workdir action failed",
+            path: typeof record.path === "string" ? record.path : undefined,
+        };
+    }
+    return { message: String(error || "local_workdir action failed") };
+}
 function stringArg(args, key, alternateKey) {
     const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
     const fromOptions = args.options && typeof args.options === "object"

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.3.0";
-export declare const USER_AGENT = "@agent-api/sdk/1.3.0";
+export declare const VERSION = "1.3.2";
+export declare const USER_AGENT = "@agent-api/sdk/1.3.2";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "1.3.0";
+export const VERSION = "1.3.2";
 export const USER_AGENT = `@agent-api/sdk/${VERSION}`;

package/dist/volume-assets.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeVolumeAssetPath(src: string | null | undefined): string;
+export declare function isSupportedVolumeImagePath(src: string | null | undefined): boolean;
+export declare function isSupportedVolumeImageContentType(contentType: string | null | undefined): boolean;

package/dist/volume-assets.js

@@ -0,0 +1,37 @@
+const SUPPORTED_VOLUME_IMAGE_EXTENSIONS = new Set([
+    ".avif",
+    ".bmp",
+    ".gif",
+    ".jpeg",
+    ".jpg",
+    ".png",
+    ".svg",
+    ".webp",
+]);
+export function normalizeVolumeAssetPath(src) {
+    const value = src?.trim() ?? "";
+    if (!value)
+        return "";
+    if (isExternalAssetTarget(value))
+        return "";
+    let path = value.split("#", 1)[0]?.split("?", 1)[0]?.trim() ?? "";
+    path = path.replace(/^\/agent-volume\/+/i, "");
+    path = path.replace(/^\/+/, "");
+    path = path.replace(/\/+/g, "/");
+    if (!path || path === "." || path.includes(".."))
+        return "";
+    return path;
+}
+export function isSupportedVolumeImagePath(src) {
+    const path = normalizeVolumeAssetPath(src).toLowerCase();
+    if (!path)
+        return false;
+    const dot = path.lastIndexOf(".");
+    return dot >= 0 && SUPPORTED_VOLUME_IMAGE_EXTENSIONS.has(path.slice(dot));
+}
+export function isSupportedVolumeImageContentType(contentType) {
+    return (contentType ?? "").split(";", 1)[0]?.trim().toLowerCase().startsWith("image/") ?? false;
+}
+function isExternalAssetTarget(src) {
+    return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(src);
+}

package/dist-cjs/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.browserAuthSessionExpiresWithin = exports.DeviceAuthFlowError = exports.AuthResource = exports.resolvePresetToolsFromCatalog = exports.resolvePresetTools = exports.publicToolToRequestTool = exports.mergeTools = exports.runLocalFunctionHandlers = exports.pendingFunctionCalls = exports.functionCallOutputInput = exports.parseResponseError = exports.isRetryableStatus = exports.RateLimitError = exports.PermissionDeniedError = exports.NotFoundError = exports.InternalServerError = exports.BadRequestError = exports.AuthenticationError = exports.APIStatusError = exports.APIConnectionError = exports.APIError = exports.collectPage = exports.Page = exports.VERSION = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_STREAM_TIMEOUT_MS = exports.DEFAULT_MAX_RETRIES = exports.AgentAPI = void 0;
+exports.browserAuthSessionExpiresWithin = exports.DeviceAuthFlowError = exports.AuthResource = exports.normalizeVolumeAssetPath = exports.isSupportedVolumeImagePath = exports.isSupportedVolumeImageContentType = exports.resolvePresetToolsFromCatalog = exports.resolvePresetTools = exports.publicToolToRequestTool = exports.mergeTools = exports.runLocalFunctionHandlers = exports.pendingFunctionCalls = exports.functionCallOutputInput = exports.parseResponseError = exports.isRetryableStatus = exports.RateLimitError = exports.PermissionDeniedError = exports.NotFoundError = exports.InternalServerError = exports.BadRequestError = exports.AuthenticationError = exports.APIStatusError = exports.APIConnectionError = exports.APIError = exports.collectPage = exports.Page = exports.VERSION = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_STREAM_TIMEOUT_MS = exports.DEFAULT_MAX_RETRIES = exports.AgentAPI = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "AgentAPI", { enumerable: true, get: function () { return client_js_1.AgentAPI; } });
 Object.defineProperty(exports, "DEFAULT_MAX_RETRIES", { enumerable: true, get: function () { return client_js_1.DEFAULT_MAX_RETRIES; } });
@@ -46,6 +46,10 @@ Object.defineProperty(exports, "mergeTools", { enumerable: true, get: function (
 Object.defineProperty(exports, "publicToolToRequestTool", { enumerable: true, get: function () { return preset_tools_js_1.publicToolToRequestTool; } });
 Object.defineProperty(exports, "resolvePresetTools", { enumerable: true, get: function () { return preset_tools_js_1.resolvePresetTools; } });
 Object.defineProperty(exports, "resolvePresetToolsFromCatalog", { enumerable: true, get: function () { return preset_tools_js_1.resolvePresetToolsFromCatalog; } });
+var volume_assets_js_1 = require("./volume-assets.js");
+Object.defineProperty(exports, "isSupportedVolumeImageContentType", { enumerable: true, get: function () { return volume_assets_js_1.isSupportedVolumeImageContentType; } });
+Object.defineProperty(exports, "isSupportedVolumeImagePath", { enumerable: true, get: function () { return volume_assets_js_1.isSupportedVolumeImagePath; } });
+Object.defineProperty(exports, "normalizeVolumeAssetPath", { enumerable: true, get: function () { return volume_assets_js_1.normalizeVolumeAssetPath; } });
 var auth_js_1 = require("./resources/auth.js");
 Object.defineProperty(exports, "AuthResource", { enumerable: true, get: function () { return auth_js_1.AuthResource; } });
 Object.defineProperty(exports, "DeviceAuthFlowError", { enumerable: true, get: function () { return auth_js_1.DeviceAuthFlowError; } });

package/dist-cjs/local/core.js

@@ -325,7 +325,7 @@ class LocalFileStore {
         const maxFiles = positiveInt(params.maxFiles, 500);
         const maxBytesPerFile = positiveInt(params.maxBytesPerFile, 512 * 1024);
         const maxLineLength = positiveInt(params.maxLineLength, 500);
-        const stats = await this.list(params.path ?? ".", { recursive: true, ignore: params.ignore });
+        const stats = await this.grepCandidates(params.path ?? ".", params.ignore);
         const matches = [];
         let filesScanned = 0;
         let scanTruncated = false;
@@ -363,6 +363,27 @@ class LocalFileStore {
         }
         return { object: "list", matches, files_scanned: filesScanned, scan_truncated: scanTruncated };
     }
+    async grepCandidates(relativePath, ignore) {
+        const fullPath = this.resolvePath(relativePath);
+        const info = await (0, promises_1.stat)(fullPath);
+        const portablePath = toPortablePath(node_path_1.default.relative(this.root, fullPath)) || ".";
+        if (ignored(portablePath, ignore)) {
+            return [];
+        }
+        if (info.isFile()) {
+            return [{
+                    path: portablePath,
+                    fullPath,
+                    type: "file",
+                    size: info.size,
+                    modifiedAt: info.mtime,
+                }];
+        }
+        if (info.isDirectory()) {
+            return await this.list(relativePath, { recursive: true, ignore });
+        }
+        return [];
+    }
     async summarize(params = {}) {
         const maxFiles = positiveInt(params.maxFiles, 2000);
         const maxPreviews = positiveInt(params.maxPreviews, 20);

package/dist-cjs/local/tools.js

@@ -13,6 +13,15 @@ class LocalWorkdirDriver {
         this.accessMode = options.accessMode ?? "approval";
     }
     async dispatch(args) {
+        const action = safeWorkdirAction(args);
+        try {
+            return await this.dispatchUnsafe(args);
+        }
+        catch (error) {
+            return localToolErrorResult(action, error);
+        }
+    }
+    async dispatchUnsafe(args) {
         const action = workdirAction(args);
         switch (action) {
             case "summarize":
@@ -51,7 +60,8 @@ class LocalWorkdirDriver {
         if (this.accessMode === "full") {
             return false;
         }
-        return mutatingLocalWorkdirActions.has(workdirAction(args));
+        const action = safeWorkdirAction(args);
+        return action !== "unknown" && mutatingLocalWorkdirActions.has(action);
     }
     async dispatchApplyEdits(args) {
         const edits = editsArg(args);
@@ -136,6 +146,7 @@ const mutatingLocalWorkdirActions = new Set([
 const localWorkdirToolDescription = [
     "Inspect and modify the selected local workdir through one model-facing primitive.",
     "Use action=list/search/grep/summarize/context to discover files, read/read_lines for file content, preview_edits before edits, and apply_edits/write/mkdir/delete only when mutation is intended.",
+    "grep searches file contents for a literal substring; path may be omitted, a file path, or a directory subtree.",
     "In approval mode, mutating actions return requires_approval with a safe preview instead of changing files. In full mode, mutating actions execute immediately.",
     "Paths are relative to the selected local workdir; never use absolute paths.",
 ].join(" ");
@@ -146,7 +157,7 @@ function localWorkdirToolParameters() {
             enum: localWorkdirActions,
             description: "Workdir operation. Prefer summarize/list/search/grep before reading or editing. Prefer read_lines and apply_edits for source changes.",
         },
-        path: stringSchema("Relative path. File path for read/write/delete/edit actions; directory base for list/search/grep/summarize/context/snapshot."),
+        path: stringSchema("Relative path. File path for read/write/delete/edit actions. For grep, path may be a file or a directory subtree. For list/search/summarize/context/snapshot, path is a directory base."),
         query: stringSchema("Path/name query for search, or optional context query."),
         pattern: stringSchema("Literal text pattern for grep."),
         content: stringSchema("Text content for write."),
@@ -189,6 +200,10 @@ function workdirAction(args) {
     }
     return value;
 }
+function safeWorkdirAction(args) {
+    const value = typeof args.action === "string" ? args.action.trim().toLowerCase() : "";
+    return localWorkdirActions.includes(value) ? value : "unknown";
+}
 function summaryArgs(args) {
     return {
         path: optionalStringArg(args, "path"),
@@ -284,6 +299,27 @@ function localToolResult(action, value) {
     }
     return { ok: true, action, result };
 }
+function localToolErrorResult(action, error) {
+    const details = errorDetails(error);
+    return {
+        ok: false,
+        action,
+        error: details.message,
+        code: details.code,
+        path: details.path,
+    };
+}
+function errorDetails(error) {
+    if (error instanceof Error) {
+        const record = error;
+        return {
+            code: typeof record.code === "string" ? record.code : undefined,
+            message: error.message || "local_workdir action failed",
+            path: typeof record.path === "string" ? record.path : undefined,
+        };
+    }
+    return { message: String(error || "local_workdir action failed") };
+}
 function stringArg(args, key, alternateKey) {
     const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
     const fromOptions = args.options && typeof args.options === "object"

package/dist-cjs/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.USER_AGENT = exports.VERSION = void 0;
-exports.VERSION = "1.3.0";
+exports.VERSION = "1.3.2";
 exports.USER_AGENT = `@agent-api/sdk/${exports.VERSION}`;

package/dist-cjs/volume-assets.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeVolumeAssetPath = normalizeVolumeAssetPath;
+exports.isSupportedVolumeImagePath = isSupportedVolumeImagePath;
+exports.isSupportedVolumeImageContentType = isSupportedVolumeImageContentType;
+const SUPPORTED_VOLUME_IMAGE_EXTENSIONS = new Set([
+    ".avif",
+    ".bmp",
+    ".gif",
+    ".jpeg",
+    ".jpg",
+    ".png",
+    ".svg",
+    ".webp",
+]);
+function normalizeVolumeAssetPath(src) {
+    const value = src?.trim() ?? "";
+    if (!value)
+        return "";
+    if (isExternalAssetTarget(value))
+        return "";
+    let path = value.split("#", 1)[0]?.split("?", 1)[0]?.trim() ?? "";
+    path = path.replace(/^\/agent-volume\/+/i, "");
+    path = path.replace(/^\/+/, "");
+    path = path.replace(/\/+/g, "/");
+    if (!path || path === "." || path.includes(".."))
+        return "";
+    return path;
+}
+function isSupportedVolumeImagePath(src) {
+    const path = normalizeVolumeAssetPath(src).toLowerCase();
+    if (!path)
+        return false;
+    const dot = path.lastIndexOf(".");
+    return dot >= 0 && SUPPORTED_VOLUME_IMAGE_EXTENSIONS.has(path.slice(dot));
+}
+function isSupportedVolumeImageContentType(contentType) {
+    return (contentType ?? "").split(";", 1)[0]?.trim().toLowerCase().startsWith("image/") ?? false;
+}
+function isExternalAssetTarget(src) {
+    return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(src);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-api/sdk",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Production JavaScript SDK for the Managed Agent API",
   "license": "MIT",
   "repository": {