@agent-api/sdk 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog — @agent-api/sdk
 
+## 1.1.2
+
+### Added
+
+- Added a model-facing `local_workspace` driver/tool primitive for local workspace operations.
+- Added approval-aware dispatch for mutating local workspace actions.
+
+### Changed
+
+- Replaced fragmented local workspace tool presentation with an action-based adapter over the low-level local APIs.
+
 ## 1.1.1
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 Production JavaScript/TypeScript SDK for the Managed Agent API.
 
-**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.1.1)
+**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.1.3)
 
 ## Install
 
@@ -97,6 +97,31 @@ const response = await client.agent.create({
 });
 ```
 
+## Preset tools and local/client tools
+
+`tools` is the concrete model-visible tool list. Tool names must be unique because model tool calls select tools by name. When you send `preset` and `tools` together, the explicit `tools` array replaces the preset's default tools. Hybrid apps that add local function tools should resolve the preset defaults first, merge in their local tools, then pass the merged array. The SDK rejects duplicate tool names before submitting requests.
+
+```typescript
+import { resolvePresetTools } from "@agent-api/sdk";
+import { createLocalWorkspaceToolRegistry, LocalWorkspace } from "@agent-api/sdk/local";
+
+const workspace = new LocalWorkspace("/path/to/project", { trusted: true });
+const registry = createLocalWorkspaceToolRegistry(workspace);
+
+const { tools } = await resolvePresetTools(client, {
+  preset: "pro-search",
+  tools: registry.definitions(),
+});
+
+const response = await client.agent.create({
+  preset: "pro-search",
+  input: "Research the topic and update local notes.",
+  tools,
+});
+```
+
+For long-running apps, cache `client.presets.list()` and `client.tools.list()` and refresh them periodically. Use `resolvePresetToolsFromCatalog()` with cached catalogs when you want deterministic request construction without fetching on every turn.
+
 ## Skills
 
 `localSkillFromDirectory()` reads `SKILL.md` into the descriptor for initial local-skill auto-focus; later focused reads still use the local skill tool bridge.

package/dist/index.d.ts

@@ -5,6 +5,10 @@ export { APIError, APIConnectionError, APIStatusError, AuthenticationError, BadR
 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 type { PresetToolCatalogClient, ResolvePresetToolsOptions, ResolvePresetToolsResult, UnknownPresetToolBehavior, } from "./preset-tools.js";
+export { LocalWorkspaceDriver, createLocalWorkspaceToolRegistry, localWorkspaceToolDefinition, localWorkspaceToolInstructions, } from "./local/tools.js";
+export type { LocalWorkspaceAction, LocalWorkspaceAccessMode, LocalWorkspaceToolRegistry, LocalWorkspaceToolRegistryOptions, } from "./local/tools.js";
 export { localSkillFromDirectory, pendingLocalSkillCalls, runLocalSkillHandlers } from "./local-skills.js";
 export type { LocalSkillDirectoryOptions } from "./local-skills.js";
 export { AuthResource, DeviceAuthFlowError } from "./resources/auth.js";

package/dist/index.js

@@ -3,5 +3,7 @@ export { Page, collectPage } from "./pagination.js";
 export { APIError, APIConnectionError, APIStatusError, AuthenticationError, BadRequestError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, isRetryableStatus, parseResponseError, } from "./errors.js";
 export * from "./types/index.js";
 export { functionCallOutputInput, pendingFunctionCalls, runLocalFunctionHandlers, } from "./local-functions.js";
+export { mergeTools, publicToolToRequestTool, resolvePresetTools, resolvePresetToolsFromCatalog, } from "./preset-tools.js";
+export { LocalWorkspaceDriver, createLocalWorkspaceToolRegistry, localWorkspaceToolDefinition, localWorkspaceToolInstructions, } from "./local/tools.js";
 export { localSkillFromDirectory, pendingLocalSkillCalls, runLocalSkillHandlers } from "./local-skills.js";
 export { AuthResource, DeviceAuthFlowError } from "./resources/auth.js";

package/dist/local/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./core.js";
 export * from "./context.js";
+export * from "./tools.js";

package/dist/local/index.js

@@ -1,2 +1,3 @@
 export * from "./core.js";
 export * from "./context.js";
+export * from "./tools.js";

package/dist/local/tools.d.ts

@@ -0,0 +1,34 @@
+import type { FunctionTool } from "../types/tools.js";
+import type { LocalWorkspace } from "./core.js";
+export type LocalWorkspaceAccessMode = "approval" | "full";
+export type LocalWorkspaceAction = "summarize" | "list" | "search" | "grep" | "read" | "read_lines" | "context" | "snapshot" | "classify_path" | "preview_edits" | "apply_edits" | "write" | "mkdir" | "delete";
+export interface LocalWorkspaceToolRegistryOptions {
+    accessMode?: LocalWorkspaceAccessMode;
+    toolName?: string;
+}
+export interface LocalWorkspaceToolRegistry {
+    readonly workspace: LocalWorkspace;
+    readonly accessMode: LocalWorkspaceAccessMode;
+    readonly toolName: string;
+    definitions(): FunctionTool[];
+    handlers(): Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>>;
+    execute(name: string, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    requiresApproval(name: string, args?: Record<string, unknown>): boolean;
+}
+export interface LocalWorkspaceDriverOptions {
+    accessMode?: LocalWorkspaceAccessMode;
+}
+export declare class LocalWorkspaceDriver {
+    readonly workspace: LocalWorkspace;
+    readonly accessMode: LocalWorkspaceAccessMode;
+    constructor(workspace: LocalWorkspace, options?: LocalWorkspaceDriverOptions);
+    dispatch(args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    requiresApproval(args: Record<string, unknown>): boolean;
+    private dispatchApplyEdits;
+    private dispatchWrite;
+    private dispatchMkdir;
+    private dispatchDelete;
+}
+export declare function createLocalWorkspaceToolRegistry(workspace: LocalWorkspace, options?: LocalWorkspaceToolRegistryOptions): LocalWorkspaceToolRegistry;
+export declare function localWorkspaceToolDefinition(name?: string): FunctionTool;
+export declare function localWorkspaceToolInstructions(): string;

package/dist/local/tools.js

@@ -0,0 +1,373 @@
+import { createLocalContextPackage } from "./context.js";
+export class LocalWorkspaceDriver {
+    workspace;
+    accessMode;
+    constructor(workspace, options = {}) {
+        this.workspace = workspace;
+        this.accessMode = options.accessMode ?? "approval";
+    }
+    async dispatch(args) {
+        const action = workspaceAction(args);
+        switch (action) {
+            case "summarize":
+                return localToolResult(action, localSummaryResult(await this.workspace.summarize(summaryArgs(args))));
+            case "list":
+                return localToolResult(action, await this.workspace.listEntries(optionalStringArg(args, "path") ?? ".", listArgs(args)));
+            case "search":
+                return localToolResult(action, await this.workspace.searchEntries(searchEntriesArgs(args)));
+            case "grep":
+                return localToolResult(action, await this.workspace.grep(grepArgs(args)));
+            case "read":
+                return localToolResult(action, await this.workspace.readFile(stringArg(args, "path"), readFileArgs(args)));
+            case "read_lines":
+                return localToolResult(action, await this.workspace.readLines(stringArg(args, "path"), readLinesArgs(args)));
+            case "context":
+                return localToolResult(action, await createLocalContextPackage(this.workspace, contextPackageArgs(args)));
+            case "snapshot":
+                return localToolResult(action, await this.workspace.snapshot(snapshotArgs(args)));
+            case "classify_path":
+                return localToolResult(action, this.workspace.classifyPath(stringArg(args, "path")));
+            case "preview_edits":
+                return localToolResult(action, await this.workspace.previewEdits(editsArg(args)));
+            case "apply_edits":
+                return await this.dispatchApplyEdits(args);
+            case "write":
+                return await this.dispatchWrite(args);
+            case "mkdir":
+                return await this.dispatchMkdir(args);
+            case "delete":
+                return await this.dispatchDelete(args);
+            default:
+                throw new Error(`unsupported local_workspace action: ${action}`);
+        }
+    }
+    requiresApproval(args) {
+        if (this.accessMode === "full") {
+            return false;
+        }
+        return mutatingLocalWorkspaceActions.has(workspaceAction(args));
+    }
+    async dispatchApplyEdits(args) {
+        const edits = editsArg(args);
+        if (this.accessMode !== "full") {
+            return approvalRequired("apply_edits", args, await this.workspace.previewEdits(edits));
+        }
+        return localToolResult("apply_edits", await this.workspace.applyEdits(edits));
+    }
+    async dispatchWrite(args) {
+        if (this.accessMode !== "full") {
+            return approvalRequired("write", args);
+        }
+        return localToolResult("write", await this.workspace.writeText(stringArg(args, "path"), stringArg(args, "content")));
+    }
+    async dispatchMkdir(args) {
+        if (this.accessMode !== "full") {
+            return approvalRequired("mkdir", args);
+        }
+        return localToolResult("mkdir", await this.workspace.createDirectory(stringArg(args, "path")));
+    }
+    async dispatchDelete(args) {
+        if (this.accessMode !== "full") {
+            return approvalRequired("delete", args);
+        }
+        return localToolResult("delete", await this.workspace.deletePath(stringArg(args, "path")));
+    }
+}
+export function createLocalWorkspaceToolRegistry(workspace, options = {}) {
+    const toolName = options.toolName ?? "local_workspace";
+    const driver = new LocalWorkspaceDriver(workspace, { accessMode: options.accessMode });
+    const definition = localWorkspaceToolDefinition(toolName);
+    return {
+        workspace,
+        accessMode: driver.accessMode,
+        toolName,
+        definitions: () => [{ ...definition }],
+        handlers: () => ({ [toolName]: (args) => driver.dispatch(args) }),
+        execute: async (name, args) => {
+            if (name !== toolName) {
+                throw new Error(`unknown local workspace tool: ${name}`);
+            }
+            return await driver.dispatch(args);
+        },
+        requiresApproval: (name, args = {}) => name === toolName && driver.requiresApproval(args),
+    };
+}
+export function localWorkspaceToolDefinition(name = "local_workspace") {
+    return {
+        type: "function",
+        name,
+        description: localWorkspaceToolDescription,
+        parameters: localWorkspaceToolParameters(),
+        strict: false,
+    };
+}
+export function localWorkspaceToolInstructions() {
+    return localWorkspaceToolDescription;
+}
+const localWorkspaceActions = [
+    "summarize",
+    "list",
+    "search",
+    "grep",
+    "read",
+    "read_lines",
+    "context",
+    "snapshot",
+    "classify_path",
+    "preview_edits",
+    "apply_edits",
+    "write",
+    "mkdir",
+    "delete",
+];
+const mutatingLocalWorkspaceActions = new Set([
+    "apply_edits",
+    "write",
+    "mkdir",
+    "delete",
+]);
+const localWorkspaceToolDescription = [
+    "Inspect and modify the selected local workspace 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.",
+    "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 workspace; never use absolute paths.",
+].join(" ");
+function localWorkspaceToolParameters() {
+    return objectSchema({
+        action: {
+            type: "string",
+            enum: localWorkspaceActions,
+            description: "Workspace 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."),
+        query: stringSchema("Path/name query for search, or optional context query."),
+        pattern: stringSchema("Literal text pattern for grep."),
+        content: stringSchema("Text content for write."),
+        start_line: integerSchema("1-based start line for read_lines and edit entries."),
+        end_line: integerSchema("1-based inclusive end line; omit or 0 for EOF when supported."),
+        replacement: stringSchema("Replacement text for simple single edit flows."),
+        edits: {
+            type: "array",
+            minItems: 1,
+            description: "Line edits for preview_edits/apply_edits.",
+            items: objectSchema({
+                path: requiredStringSchema("Relative file path."),
+                start_line: requiredIntegerSchema("1-based start line."),
+                end_line: integerSchema("1-based inclusive end line."),
+                replacement: stringSchema("Replacement text. Empty string deletes the line range."),
+                expected_sha256: stringSchema("Optional expected SHA-256 for conflict detection."),
+            }, ["path", "start_line"]),
+        },
+        options: objectSchema({
+            recursive: booleanSchema("List recursively."),
+            include_directories: booleanSchema("Include directories in list results."),
+            max_depth: integerSchema("Maximum recursive list depth."),
+            limit: integerSchema("Maximum entries or matches."),
+            max_files: integerSchema("Maximum files to scan or package."),
+            max_bytes: integerSchema("Maximum total bytes to read/package."),
+            max_bytes_per_file: integerSchema("Maximum bytes per file."),
+            max_previews: integerSchema("Maximum summary previews."),
+            include_content: booleanSchema("Include file contents in context packages."),
+            include_summary: booleanSchema("Include workspace summary in context packages."),
+            include_search: booleanSchema("Include grep results in context packages when query is set."),
+            include_secrets: booleanSchema("Include likely secret file contents in context packages."),
+            hash: booleanSchema("Include SHA-256 hashes in snapshots."),
+        }),
+    }, ["action"]);
+}
+function workspaceAction(args) {
+    const value = stringArg(args, "action").trim().toLowerCase();
+    if (!localWorkspaceActions.includes(value)) {
+        throw new Error(`unsupported local_workspace action: ${value}`);
+    }
+    return value;
+}
+function summaryArgs(args) {
+    return {
+        path: optionalStringArg(args, "path"),
+        maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
+        maxPreviews: optionalNumberArg(args, "maxPreviews", "max_previews"),
+    };
+}
+function grepArgs(args) {
+    return {
+        pattern: stringArg(args, "pattern"),
+        path: optionalStringArg(args, "path"),
+        limit: optionalNumberArg(args, "limit"),
+        maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
+    };
+}
+function listArgs(args) {
+    return {
+        recursive: optionalBooleanArg(args, "recursive"),
+        includeDirectories: optionalBooleanArg(args, "includeDirectories", "include_directories"),
+        maxDepth: optionalNumberArg(args, "maxDepth", "max_depth"),
+    };
+}
+function searchEntriesArgs(args) {
+    return {
+        query: stringArg(args, "query"),
+        path: optionalStringArg(args, "path"),
+        limit: optionalNumberArg(args, "limit"),
+    };
+}
+function readFileArgs(args) {
+    return {
+        maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
+    };
+}
+function readLinesArgs(args) {
+    return {
+        startLine: numberArg(args, "startLine", "start_line"),
+        endLine: optionalNumberArg(args, "endLine", "end_line"),
+        maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
+    };
+}
+function snapshotArgs(args) {
+    return {
+        path: optionalStringArg(args, "path"),
+        hash: optionalBooleanArg(args, "hash"),
+        maxBytesPerFile: optionalNumberArg(args, "maxBytesPerFile", "max_bytes_per_file"),
+    };
+}
+function contextPackageArgs(args) {
+    return {
+        path: optionalStringArg(args, "path"),
+        query: optionalStringArg(args, "query"),
+        maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
+        maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
+        maxBytesPerFile: optionalNumberArg(args, "maxBytesPerFile", "max_bytes_per_file"),
+        includeContent: optionalBooleanArg(args, "includeContent", "include_content"),
+        includeSummary: optionalBooleanArg(args, "includeSummary", "include_summary"),
+        includeSearch: optionalBooleanArg(args, "includeSearch", "include_search"),
+        includeSecrets: optionalBooleanArg(args, "includeSecrets", "include_secrets"),
+    };
+}
+function editsArg(args) {
+    const edits = args.edits;
+    if (Array.isArray(edits) && edits.length > 0) {
+        return edits.map((edit) => {
+            if (!edit || typeof edit !== "object") {
+                throw new Error("each edit must be an object");
+            }
+            return editArg(edit);
+        });
+    }
+    if (typeof args.path === "string" && typeof (args.startLine ?? args.start_line) === "number") {
+        return [editArg(args)];
+    }
+    throw new Error("edits must be a non-empty array");
+}
+function editArg(record) {
+    return {
+        path: stringArg(record, "path"),
+        startLine: numberArg(record, "startLine", "start_line"),
+        endLine: optionalNumberArg(record, "endLine", "end_line"),
+        replacement: typeof record.replacement === "string" ? record.replacement : "",
+        expectedSha256: optionalStringArg(record, "expectedSha256", "expected_sha256"),
+    };
+}
+function localSummaryResult(summary) {
+    return summary;
+}
+function localToolResult(action, value) {
+    const result = value;
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        return { ok: true, action, ...result };
+    }
+    return { ok: true, action, result };
+}
+function stringArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${key} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalStringArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (value == null || value === "")
+        return undefined;
+    if (typeof value !== "string") {
+        throw new Error(`${key} must be a string`);
+    }
+    return value;
+}
+function numberArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${key} must be a number`);
+    }
+    return Math.trunc(value);
+}
+function optionalNumberArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (value == null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${key} must be a number`);
+    }
+    return Math.trunc(value);
+}
+function optionalBooleanArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (value == null)
+        return undefined;
+    if (typeof value !== "boolean") {
+        throw new Error(`${key} must be a boolean`);
+    }
+    return value;
+}
+function approvalRequired(action, args, preview) {
+    return {
+        ok: false,
+        action,
+        requires_approval: true,
+        arguments: args,
+        preview,
+        message: `local_workspace action ${action} requires approval`,
+    };
+}
+function objectSchema(properties, required = []) {
+    return {
+        type: "object",
+        properties,
+        required,
+        additionalProperties: false,
+    };
+}
+function stringSchema(description) {
+    return { type: "string", description };
+}
+function requiredStringSchema(description) {
+    return stringSchema(description);
+}
+function integerSchema(description) {
+    return { type: "integer", description };
+}
+function booleanSchema(description) {
+    return { type: "boolean", description };
+}
+function requiredIntegerSchema(description) {
+    return integerSchema(description);
+}

package/dist/preset-tools.d.ts

@@ -0,0 +1,53 @@
+import type { ListPresetsResponse, Preset } from "./types/catalog.js";
+import type { ListToolsResponse, PublicTool, Tool } from "./types/tools.js";
+export interface PresetToolCatalogClient {
+    presets: {
+        list(): Promise<ListPresetsResponse>;
+    };
+    tools: {
+        list(): Promise<ListToolsResponse>;
+    };
+}
+export type UnknownPresetToolBehavior = "stub" | "omit" | "error";
+export interface ResolvePresetToolsOptions {
+    /**
+     * Preset id whose policy.allowed_tools should be resolved.
+     */
+    preset: string;
+    /**
+     * Additional caller/client tools to append after the preset tools.
+     */
+    tools?: readonly Tool[];
+    /**
+     * Optional pre-fetched preset catalog. Use this when your app caches discovery
+     * responses and wants deterministic request construction.
+     */
+    presets?: readonly Preset[];
+    /**
+     * Optional pre-fetched tool catalog.
+     */
+    toolCatalog?: readonly PublicTool[];
+    /**
+     * Behavior when a preset allows a tool that is not present in the supplied
+     * or fetched tool catalog. "stub" keeps a name-only tool definition so the
+     * backend can still enrich it by name.
+     */
+    unknownPresetTool?: UnknownPresetToolBehavior;
+}
+export interface ResolvePresetToolsResult {
+    preset: Preset;
+    tools: Tool[];
+    missingToolNames: string[];
+}
+/**
+ * Resolve a preset's allowed tool names into concrete request tools and append
+ * caller-provided tools. This is a convenience for hybrid apps that need to add
+ * local/client tools while preserving the preset's default server tools.
+ *
+ * The Agent API request surface remains OpenAI-compatible: the returned array
+ * is intended for the normal CreateResponseRequest.tools field.
+ */
+export declare function resolvePresetTools(client: PresetToolCatalogClient, options: ResolvePresetToolsOptions): Promise<ResolvePresetToolsResult>;
+export declare function resolvePresetToolsFromCatalog(options: ResolvePresetToolsOptions): ResolvePresetToolsResult;
+export declare function mergeTools(...groups: Array<readonly Tool[]>): Tool[];
+export declare function publicToolToRequestTool(tool: PublicTool): Tool;

package/dist/preset-tools.js

@@ -0,0 +1,85 @@
+import { validateUniqueToolNames } from "./tool-validation.js";
+/**
+ * Resolve a preset's allowed tool names into concrete request tools and append
+ * caller-provided tools. This is a convenience for hybrid apps that need to add
+ * local/client tools while preserving the preset's default server tools.
+ *
+ * The Agent API request surface remains OpenAI-compatible: the returned array
+ * is intended for the normal CreateResponseRequest.tools field.
+ */
+export async function resolvePresetTools(client, options) {
+    const presets = options.presets ?? (await client.presets.list()).data;
+    const toolCatalog = options.toolCatalog ?? (await client.tools.list()).data;
+    return resolvePresetToolsFromCatalog({ ...options, presets, toolCatalog });
+}
+export function resolvePresetToolsFromCatalog(options) {
+    const presetId = options.preset.trim();
+    if (!presetId) {
+        throw new Error("preset is required");
+    }
+    const preset = options.presets?.find((row) => row.preset === presetId);
+    if (!preset) {
+        throw new Error(`preset not found: ${presetId}`);
+    }
+    const catalogByName = new Map();
+    for (const tool of options.toolCatalog ?? []) {
+        const name = tool.name?.trim();
+        if (name)
+            catalogByName.set(name, tool);
+    }
+    const missingToolNames = [];
+    const presetTools = [];
+    const unknownPresetTool = options.unknownPresetTool ?? "stub";
+    for (const name of preset.policy?.allowed_tools ?? []) {
+        const trimmed = name.trim();
+        if (!trimmed)
+            continue;
+        const catalogTool = catalogByName.get(trimmed);
+        if (catalogTool) {
+            presetTools.push(publicToolToRequestTool(catalogTool));
+            continue;
+        }
+        missingToolNames.push(trimmed);
+        if (unknownPresetTool === "error") {
+            throw new Error(`preset tool not found in catalog: ${trimmed}`);
+        }
+        if (unknownPresetTool === "stub") {
+            presetTools.push({ name: trimmed });
+        }
+    }
+    return {
+        preset,
+        tools: mergeTools(presetTools, options.tools ?? []),
+        missingToolNames,
+    };
+}
+export function mergeTools(...groups) {
+    const out = [];
+    for (const group of groups) {
+        for (const tool of group) {
+            const name = tool.name?.trim();
+            if (!name) {
+                throw new Error("tools[].name is required");
+            }
+            out.push({ ...tool, name });
+        }
+    }
+    validateUniqueToolNames(out);
+    return out;
+}
+export function publicToolToRequestTool(tool) {
+    const out = { name: tool.name };
+    if (tool.type)
+        out.type = tool.type;
+    if (tool.description)
+        out.description = tool.description;
+    if (tool.parameters)
+        out.parameters = tool.parameters;
+    if (tool.max_tokens != null)
+        out.max_tokens = tool.max_tokens;
+    if (tool.max_tokens_per_page != null)
+        out.max_tokens_per_page = tool.max_tokens_per_page;
+    if (tool.version)
+        out.version = tool.version;
+    return out;
+}

package/dist/resources/responses.js

@@ -1,6 +1,7 @@
 import { addOutputText } from "../internal/output-text.js";
 import { buildQuery } from "../internal/query.js";
 import { collectPage } from "../pagination.js";
+import { validateUniqueToolNames } from "../tool-validation.js";
 export class ResponsesResource {
     http;
     path;
@@ -9,6 +10,7 @@ export class ResponsesResource {
         this.path = path;
     }
     create(params, options) {
+        validateUniqueToolNames(params.tools);
         if (params.stream) {
             return this.http.stream(this.path, params, options);
         }

package/dist/tool-validation.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "./types/tools.js";
+export declare function validateUniqueToolNames(tools: readonly Tool[] | undefined): void;

package/dist/tool-validation.js

@@ -0,0 +1,15 @@
+export function validateUniqueToolNames(tools) {
+    if (!tools)
+        return;
+    const seen = new Set();
+    for (const tool of tools) {
+        const name = tool.name?.trim();
+        if (!name) {
+            throw new Error("tools[].name is required");
+        }
+        if (seen.has(name)) {
+            throw new Error(`duplicate tools[].name: ${name}`);
+        }
+        seen.add(name);
+    }
+}

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-api/sdk",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Production JavaScript SDK for the Managed Agent API",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,7 @@
     "build": "tsc -p tsconfig.json",
     "sync-version": "node scripts/sync-version.mjs",
     "prepack": "npm run sync-version && npm run build",
-    "test": "npm run sync-version && npm run build && node --test test/index.test.mjs test/local-function-integration.test.mjs test/local-runtime.test.mjs",
+    "test": "npm run sync-version && npm run build && node --test test/index.test.mjs test/local-function-integration.test.mjs test/local-runtime.test.mjs test/local-tools.test.mjs",
     "test:integration": "npm run sync-version && npm run build && node --test test/integration.test.mjs",
     "test:integration:local-functions": "npm run sync-version && npm run build && node --test test/local-function-integration.test.mjs",
     "check:routes": "node scripts/check-routes.mjs"