@agent-api/sdk 1.1.2 → 1.1.3

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.2)
+**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,8 @@ 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";

package/dist/index.js

@@ -3,6 +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/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.2";
-export declare const USER_AGENT = "@agent-api/sdk/1.1.2";
+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.2";
+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.2",
+  "version": "1.1.3",
   "description": "Production JavaScript SDK for the Managed Agent API",
   "license": "MIT",
   "repository": {