@agent-api/sdk 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog — @agent-api/sdk
 
+## 1.0.4
+
+### Added
+
+- `preferred_sites` create-run parameter (up to 3 hostnames) to bias web search and fetch toward specific domains when allowed tools include `web_search` or `web_fetch`.
+
+## 1.0.3
+
+### Added
+
+- Workbench volume APIs: `summarize`, `grep`, `readLines`, `patchLines`, `downloadArchive`.
+- `responses.retrieveVolume` for `GET /v1/responses/{response_id}/volume`.
+- Create-run params `model_routing` (`auto` | `chain`) and `routing_strategy` (`balanced` | `high-quality` | `cost-effective`) for platform model selection when `model_routing` is `auto`.
+
+### Changed
+
+- **Breaking:** `readFile` returns smart delivery metadata (`encoding`, `mime_type`, `content`, `image_url`, etc.); use `{ format: "raw" }` for binary bytes.
+- **Breaking:** `deleteFile` and `deleteDirectory` replaced by unified `deletePath`, returning `{ path, recursive }`.
+
 ## 1.0.2
 
 ### 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.0.2)
+**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.0.4)
 
 ## Install
 
@@ -59,7 +59,7 @@ src/
 | `client.models` | `list` |
 | `client.presets` | `list` |
 | `client.tools` | `list` |
-| `client.volumes` | `list`, `create`, `retrieve`, `update`, `delete`, `listEntries`, `searchEntries`, `readFile`, `writeFile`, `deleteFile`, `reconcileUsage`, `createDirectory`, `deleteDirectory` |
+| `client.volumes` | `list`, `create`, `retrieve`, `update`, `delete`, `listEntries`, `searchEntries`, `readFile`, `writeFile`, `deletePath`, `reconcileUsage`, `createDirectory`, `downloadArchive`, `summarize`, `readLines`, `patchLines`, `grep` |
 
 ## Durable Volumes
 
@@ -106,6 +106,21 @@ for await (const event of stream) {
 }
 ```
 
+## Model routing
+
+Use `model_routing: "auto"` to let the platform pick a model (openmark). Optionally constrain the pool with `models`, and tune selection with `routing_strategy`:
+
+```typescript
+const response = await client.responses.create({
+  input: "Compare two cloud providers for ML workloads.",
+  model_routing: "auto",
+  routing_strategy: "cost-effective",
+  models: ["openai/gpt-5.4", "google/gemini-3-flash-preview"],
+});
+```
+
+Use model ids in vendor/model form (values from `client.models.list()`). Omit `model_routing` (or set `"chain"`) for strict fallback order via `model` / `models`. `routing_strategy` is only valid when `model_routing` is `"auto"`.
+
 ## Client options
 
 ```typescript

package/dist/resources/responses.d.ts

@@ -3,6 +3,7 @@ import { Page } from "../pagination.js";
 import type { RequestOptions } from "../types/common.js";
 import type { AgentResponse, CancelResponse, ListChildrenResponse, ListEventsParams, ListEventsResponse, ListResponsesParams, ListResponsesResponse, ResponseCreateParamsNonStreaming, ResponseCreateParamsStreaming, ResponseListItem } from "../types/responses.js";
 import type { ResponseStreamEvent } from "../types/streaming.js";
+import type { VolumeInfo } from "../types/volumes.js";
 export declare class ResponsesResource {
     private readonly http;
     private readonly path;
@@ -16,4 +17,5 @@ export declare class ResponsesResource {
     cancel(responseID: string, options?: RequestOptions): Promise<CancelResponse>;
     listChildren(responseID: string, options?: RequestOptions): Promise<ListChildrenResponse>;
     listEvents(responseID: string, params?: ListEventsParams, options?: RequestOptions): Promise<ListEventsResponse>;
+    retrieveVolume(responseID: string, options?: RequestOptions): Promise<VolumeInfo>;
 }

package/dist/resources/responses.js

@@ -46,4 +46,7 @@ export class ResponsesResource {
             view: params.view,
         })}`, undefined, options);
     }
+    retrieveVolume(responseID, options) {
+        return this.http.request("GET", `${this.path}/${encodeURIComponent(responseID)}/volume`, undefined, options);
+    }
 }

package/dist/resources/volumes.d.ts

@@ -1,6 +1,6 @@
 import type { HTTPClient } from "../internal/http.js";
 import type { RequestOptions } from "../types/common.js";
-import type { CreateVolumeParams, ListVolumeEntriesParams, ListVolumeEntriesResponse, ListVolumesParams, ListVolumesResponse, ReadVolumeFileParams, ReadVolumeFileRawParams, SearchVolumeEntriesParams, VolumeFileRead, VolumeFileRaw, VolumeFileWrite, VolumeInfo } from "../types/volumes.js";
+import type { CreateVolumeParams, DownloadVolumeArchiveParams, GrepVolumeParams, ListVolumeEntriesParams, ListVolumeEntriesResponse, ListVolumesParams, ListVolumesResponse, PatchVolumeFileLinesParams, ReadVolumeFileLinesParams, ReadVolumeFileParams, ReadVolumeFileRawParams, SearchVolumeEntriesParams, SummarizeVolumeParams, VolumeArchive, VolumeFileDeliver, VolumeFileLines, VolumeFileLinesPatch, VolumeFileRaw, VolumeFileWrite, VolumeGrepResponse, VolumeInfo, VolumePathDelete, VolumeSummary } from "../types/volumes.js";
 export declare class VolumesResource {
     private readonly http;
     constructor(http: HTTPClient);
@@ -14,12 +14,16 @@ export declare class VolumesResource {
     listEntries(volumeID: string, params?: ListVolumeEntriesParams, options?: RequestOptions): Promise<ListVolumeEntriesResponse>;
     searchEntries(volumeID: string, params: SearchVolumeEntriesParams, options?: RequestOptions): Promise<ListVolumeEntriesResponse>;
     readFile(volumeID: string, path: string, params: ReadVolumeFileRawParams, options?: RequestOptions): Promise<VolumeFileRaw>;
-    readFile(volumeID: string, path: string, params?: ReadVolumeFileParams, options?: RequestOptions): Promise<VolumeFileRead>;
+    readFile(volumeID: string, path: string, params?: ReadVolumeFileParams, options?: RequestOptions): Promise<VolumeFileDeliver>;
     writeFile(volumeID: string, path: string, content: string | ArrayBuffer | Blob, options?: RequestOptions): Promise<VolumeFileWrite>;
-    deleteFile(volumeID: string, path: string, options?: RequestOptions): Promise<void>;
+    deletePath(volumeID: string, path: string, options?: RequestOptions): Promise<VolumePathDelete>;
     reconcileUsage(volumeID: string, options?: RequestOptions): Promise<VolumeInfo>;
     createDirectory(volumeID: string, path: string, options?: RequestOptions): Promise<{
         path: string;
     }>;
-    deleteDirectory(volumeID: string, path: string, options?: RequestOptions): Promise<void>;
+    downloadArchive(volumeID: string, params?: DownloadVolumeArchiveParams, options?: RequestOptions): Promise<VolumeArchive>;
+    summarize(volumeID: string, params?: SummarizeVolumeParams, options?: RequestOptions): Promise<VolumeSummary>;
+    readLines(volumeID: string, path: string, params: ReadVolumeFileLinesParams, options?: RequestOptions): Promise<VolumeFileLines>;
+    patchLines(volumeID: string, path: string, params: PatchVolumeFileLinesParams, options?: RequestOptions): Promise<VolumeFileLinesPatch>;
+    grep(volumeID: string, params: GrepVolumeParams, options?: RequestOptions): Promise<VolumeGrepResponse>;
 }

package/dist/resources/volumes.js

@@ -35,11 +35,12 @@ export class VolumesResource {
         })}`, undefined, options);
     }
     readFile(volumeID, path, params = {}, options) {
+        const format = "format" in params ? params.format : undefined;
         const url = `/v1/volumes/${encodeURIComponent(volumeID)}/files/${volumePath(path)}${buildQuery({
             max_bytes: params.max_bytes,
-            format: params.format,
+            format,
         })}`;
-        if (params.format === "raw") {
+        if (format === "raw") {
             return this.http.requestBinary("GET", url, options).then(({ body, headers }) => ({
                 path,
                 size: Number(headers.get("X-Volume-Size") ?? body.byteLength),
@@ -53,8 +54,8 @@ export class VolumesResource {
     writeFile(volumeID, path, content, options) {
         return this.http.requestRaw("PUT", `/v1/volumes/${encodeURIComponent(volumeID)}/files/${volumePath(path)}`, content, options);
     }
-    deleteFile(volumeID, path, options) {
-        return this.http.requestVoid("DELETE", `/v1/volumes/${encodeURIComponent(volumeID)}/files/${volumePath(path)}`, options);
+    deletePath(volumeID, path, options) {
+        return this.http.request("DELETE", `/v1/volumes/${encodeURIComponent(volumeID)}/paths/${volumePath(path)}`, undefined, options);
     }
     reconcileUsage(volumeID, options) {
         return this.http.request("POST", `/v1/volumes/${encodeURIComponent(volumeID)}/usage/reconcile`, undefined, options);
@@ -62,8 +63,36 @@ export class VolumesResource {
     createDirectory(volumeID, path, options) {
         return this.http.request("POST", `/v1/volumes/${encodeURIComponent(volumeID)}/directories`, { path }, options);
     }
-    deleteDirectory(volumeID, path, options) {
-        return this.http.requestVoid("DELETE", `/v1/volumes/${encodeURIComponent(volumeID)}/directories/${volumePath(path)}`, options);
+    downloadArchive(volumeID, params = {}, options) {
+        const archivePath = normalizeArchivePath(params.path);
+        return this.http
+            .requestBinary("GET", `/v1/volumes/${encodeURIComponent(volumeID)}/archive${buildQuery({ path: archivePath || undefined })}`, options)
+            .then(({ body, headers }) => ({
+            path: archivePath,
+            content: body,
+            content_type: headers.get("Content-Type") ?? undefined,
+        }));
+    }
+    summarize(volumeID, params = {}, options) {
+        return this.http.request("POST", `/v1/volumes/${encodeURIComponent(volumeID)}/summarize`, params, options);
+    }
+    readLines(volumeID, path, params, options) {
+        return this.http.request("GET", `/v1/volumes/${encodeURIComponent(volumeID)}/file_lines/${volumePath(path)}${buildQuery({
+            start_line: params.start_line,
+            end_line: params.end_line,
+            max_bytes: params.max_bytes,
+        })}`, undefined, options);
+    }
+    patchLines(volumeID, path, params, options) {
+        return this.http.request("PATCH", `/v1/volumes/${encodeURIComponent(volumeID)}/file_lines/${volumePath(path)}`, params, options);
+    }
+    grep(volumeID, params, options) {
+        return this.http.request("GET", `/v1/volumes/${encodeURIComponent(volumeID)}/grep${buildQuery({
+            pattern: params.pattern,
+            path: params.path,
+            limit: params.limit,
+            page_token: params.page_token,
+        })}`, undefined, options);
     }
 }
 function volumePath(path) {
@@ -73,3 +102,9 @@ function volumePath(path) {
         .map((part) => encodeURIComponent(part))
         .join("/");
 }
+function normalizeArchivePath(path) {
+    if (!path) {
+        return "";
+    }
+    return path.trim().replace(/^\/+/, "").replace(/\/+/g, "/").replace(/\/$/, "");
+}

package/dist/types/common.d.ts

@@ -3,6 +3,8 @@ export type JSONValue = JSONPrimitive | JSONValue[] | {
     [key: string]: JSONValue;
 };
 export type AgentCapabilityPreference = "off" | "auto" | "preferred" | "required";
+export type ModelRoutingMode = "auto" | "chain";
+export type ModelRoutingStrategy = "balanced" | "high-quality" | "cost-effective";
 export interface ClientOptions {
     apiKey?: string;
     baseURL?: string;

package/dist/types/responses.d.ts

@@ -1,4 +1,4 @@
-import type { AgentCapabilityPreference, ErrorInfo, OutputItemStatus, ResponseStatus, Usage } from "./common.js";
+import type { AgentCapabilityPreference, ErrorInfo, ModelRoutingMode, ModelRoutingStrategy, OutputItemStatus, ResponseStatus, Usage } from "./common.js";
 import type { ContentPart, Input, MemoryOptions, ReasoningConfig, ResponseFormat } from "./input.js";
 import type { Tool } from "./tools.js";
 export interface ResponseCreateParamsBase {
@@ -7,6 +7,8 @@ export interface ResponseCreateParamsBase {
     language_preference?: string;
     model?: string;
     models?: string[];
+    model_routing?: ModelRoutingMode;
+    routing_strategy?: ModelRoutingStrategy;
     preset?: "fast-search" | "pro-search" | "deep-research" | "advanced-deep-research" | string;
     max_output_tokens?: number;
     max_steps?: number;
@@ -19,6 +21,7 @@ export interface ResponseCreateParamsBase {
     store?: boolean;
     previous_response_id?: string;
     volume_id?: string;
+    preferred_sites?: string[];
     prompt_cache_key?: string;
     memory?: MemoryOptions;
     plan_mode_preference?: AgentCapabilityPreference;

package/dist/types/volumes.d.ts

@@ -42,17 +42,23 @@ export interface ListVolumeEntriesResponse {
 }
 export interface ReadVolumeFileParams {
     max_bytes?: number;
-    format?: "json";
 }
 export interface ReadVolumeFileRawParams {
     max_bytes?: number;
     format: "raw";
 }
-export interface VolumeFileRead {
+export type VolumeFileEncoding = "text" | "extracted_text" | "url" | "base64";
+export interface VolumeFileDeliver {
     path: string;
+    encoding: VolumeFileEncoding;
+    mime_type: string;
     size: number;
     truncated: boolean;
-    content: string;
+    content?: string;
+    content_base64?: string;
+    image_url?: string;
+    expires_at_unix?: number;
+    extraction_warnings?: string[];
 }
 export interface VolumeFileRaw {
     path: string;
@@ -65,3 +71,76 @@ export interface VolumeFileWrite {
     path: string;
     size: number;
 }
+export interface VolumePathDelete {
+    path: string;
+    recursive: boolean;
+}
+export interface DownloadVolumeArchiveParams {
+    path?: string;
+}
+export interface VolumeArchive {
+    path: string;
+    content: ArrayBuffer;
+    content_type?: string;
+}
+export interface SummarizeVolumeParams {
+    path?: string;
+}
+export interface VolumeSummaryPreview {
+    path: string;
+    size: number;
+    preview: string;
+    preview_truncated?: boolean;
+}
+export interface VolumeSummary {
+    summary_path: string;
+    file_count: number;
+    total_bytes: number;
+    top_paths_by_size: string[];
+    text_previews: VolumeSummaryPreview[];
+    generated_at_unix: number;
+}
+export interface ReadVolumeFileLinesParams {
+    start_line: number;
+    end_line?: number;
+    max_bytes?: number;
+}
+export interface VolumeFileLines {
+    path: string;
+    start_line: number;
+    end_line: number;
+    total_lines: number;
+    lines: string[];
+    file_truncated: boolean;
+    size: number;
+}
+export interface PatchVolumeFileLinesParams {
+    start_line: number;
+    end_line?: number;
+    replacement?: string;
+}
+export interface VolumeFileLinesPatch {
+    path: string;
+    start_line: number;
+    end_line: number;
+    total_lines: number;
+    size: number;
+}
+export interface GrepVolumeParams {
+    pattern: string;
+    path?: string;
+    limit?: number;
+    page_token?: string;
+}
+export interface VolumeGrepMatch {
+    path: string;
+    line_number: number;
+    line: string;
+}
+export interface VolumeGrepResponse {
+    object: "list";
+    matches: VolumeGrepMatch[];
+    next_page_token?: string;
+    files_scanned: number;
+    scan_truncated: boolean;
+}

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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