@agent-api/sdk 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog — @agent-api/sdk
 
+## 1.0.2
+
+### Added
+
+- `user` on create-run params; `input_document` content parts in TypeScript types.
+- `response.requires_action` in streaming event types.
+- `readFile(..., { format: "raw" })` for binary volume files (`VolumeFileRaw` with `ArrayBuffer` content).
+- Route manifest coverage for volume rename, usage reconcile, and directory create/delete.
+
+### Fixed
+
+- README and route manifest now list all volume resource methods implemented since 1.0.1.
+
+## 1.0.1
+
+### Added
+
+- Durable volume resource methods for volume CRUD, entry listing/search, and file read/write/delete operations.
+- `volume_id` create-run parameter for attaching an existing durable volume to agent runs.
+
 ## 1.0.0
 
 ### Added
@@ -11,3 +31,4 @@
 ### Notes
 
 - Independent from the Python `cloudsway-agent` package; version and release tags are separate.
+- Registry: https://www.npmjs.com/package/@agent-api/sdk

package/README.md

@@ -2,6 +2,8 @@
 
 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)
+
 ## Install
 
 ```bash
@@ -44,7 +46,7 @@ src/
   errors.ts           # Typed error hierarchy + retry helpers
   pagination.ts       # Cursor pagination utilities
   streaming.ts        # SSE parser
-  resources/          # responses, models, presets, tools
+  resources/          # responses, models, presets, tools, volumes
   types/              # Request/response TypeScript types
   internal/http.ts    # Retries, timeouts, User-Agent
 ```
@@ -57,6 +59,23 @@ 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` |
+
+## Durable Volumes
+
+```typescript
+const volume = await client.volumes.create({ name: "research-notes" });
+
+await client.volumes.writeFile(volume.volume_id, "notes/summary.md", "# Summary\n");
+const file = await client.volumes.readFile(volume.volume_id, "notes/summary.md");
+const binary = await client.volumes.readFile(volume.volume_id, "assets/logo.png", { format: "raw" });
+
+const response = await client.agent.create({
+  preset: "pro-search",
+  input: "Use the attached workspace volume.",
+  volume_id: volume.volume_id,
+});
+```
 
 ## Production features
 
@@ -110,6 +129,6 @@ AGENT_API_INTEGRATION=1 AGENT_API_KEY=sk-... AGENT_API_BASE_URL=https://api.agen
 
 ## Scope
 
-The SDK covers the public agent/Responses API and discovery endpoints. Console
-auth, workspace administration, and internal audit records are intentionally
-out of scope.
+The SDK covers the public agent/Responses API, durable volume APIs, and discovery
+endpoints. Console auth, workspace administration, and internal audit records
+are intentionally out of scope.

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import { ModelsResource } from "./resources/models.js";
 import { PresetsResource } from "./resources/presets.js";
 import { ResponsesResource } from "./resources/responses.js";
 import { ToolsResource } from "./resources/tools.js";
+import { VolumesResource } from "./resources/volumes.js";
 import type { ClientOptions } from "./types/common.js";
 import { VERSION } from "./version.js";
 export declare const DEFAULT_TIMEOUT_MS = 600000;
@@ -19,6 +20,7 @@ export declare class AgentAPI {
     readonly models: ModelsResource;
     readonly presets: PresetsResource;
     readonly tools: ToolsResource;
+    readonly volumes: VolumesResource;
     private readonly http;
     constructor(options?: ClientOptions);
 }

package/dist/client.js

@@ -5,6 +5,7 @@ import { ModelsResource } from "./resources/models.js";
 import { PresetsResource } from "./resources/presets.js";
 import { ResponsesResource } from "./resources/responses.js";
 import { ToolsResource } from "./resources/tools.js";
+import { VolumesResource } from "./resources/volumes.js";
 import { VERSION } from "./version.js";
 export const DEFAULT_TIMEOUT_MS = 600_000;
 export const DEFAULT_STREAM_TIMEOUT_MS = 3_600_000;
@@ -21,6 +22,7 @@ export class AgentAPI {
     models;
     presets;
     tools;
+    volumes;
     http;
     constructor(options = {}) {
         this.apiKey = options.apiKey ?? readEnv("AGENT_API_KEY");
@@ -47,6 +49,7 @@ export class AgentAPI {
         this.models = new ModelsResource(this.http);
         this.presets = new PresetsResource(this.http);
         this.tools = new ToolsResource(this.http);
+        this.volumes = new VolumesResource(this.http);
     }
 }
 export { VERSION };

package/dist/internal/http.d.ts

@@ -12,6 +12,12 @@ export declare class HTTPClient {
     private readonly options;
     constructor(options: HTTPClientOptions);
     request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    requestRaw<T>(method: string, path: string, body: BodyInit, options?: RequestOptions): Promise<T>;
+    requestVoid(method: string, path: string, options?: RequestOptions): Promise<void>;
+    requestBinary(method: string, path: string, options?: RequestOptions): Promise<{
+        body: ArrayBuffer;
+        headers: Headers;
+    }>;
     stream<T>(path: string, body: unknown, options?: RequestOptions): Promise<AsyncIterable<T>>;
     private fetchWithRetry;
     private fetchOnce;

package/dist/internal/http.js

@@ -7,19 +7,30 @@ export class HTTPClient {
         this.options = options;
     }
     async request(method, path, body, options = {}) {
-        const response = await this.fetchWithRetry(method, path, body, options, false);
+        const response = await this.fetchWithRetry(method, path, body, options, false, false);
         return (await response.json());
     }
+    async requestRaw(method, path, body, options = {}) {
+        const response = await this.fetchWithRetry(method, path, body, options, false, true);
+        return (await response.json());
+    }
+    async requestVoid(method, path, options = {}) {
+        await this.fetchWithRetry(method, path, undefined, options, false, false);
+    }
+    async requestBinary(method, path, options = {}) {
+        const response = await this.fetchWithRetry(method, path, undefined, options, false, false);
+        return { body: await response.arrayBuffer(), headers: response.headers };
+    }
     async stream(path, body, options = {}) {
-        const response = await this.fetchWithRetry("POST", path, body, options, true);
+        const response = await this.fetchWithRetry("POST", path, body, options, true, false);
         return parseSSE(response);
     }
-    async fetchWithRetry(method, path, body, options, stream) {
+    async fetchWithRetry(method, path, body, options, stream, rawBody) {
         const maxRetries = options.maxRetries ?? this.options.maxRetries;
         let attempt = 0;
         for (;;) {
             try {
-                return await this.fetchOnce(method, path, body, options, stream);
+                return await this.fetchOnce(method, path, body, options, stream, rawBody);
             }
             catch (error) {
                 if (!(error instanceof APIError) || attempt >= maxRetries) {
@@ -36,7 +47,7 @@ export class HTTPClient {
             }
         }
     }
-    async fetchOnce(method, path, body, options, stream) {
+    async fetchOnce(method, path, body, options, stream, rawBody) {
         const controller = new AbortController();
         const timeout = options.timeout ?? (stream ? this.options.streamTimeout : this.options.timeout);
         const timeoutID = setTimeout(() => controller.abort(), timeout);
@@ -47,7 +58,7 @@ export class HTTPClient {
                 ...this.options.defaultHeaders,
                 ...options.headers,
             };
-            if (body !== undefined) {
+            if (body !== undefined && !rawBody) {
                 headers["Content-Type"] = "application/json";
             }
             if (this.options.apiKey) {
@@ -56,7 +67,7 @@ export class HTTPClient {
             const response = await this.options.fetchImpl(`${this.options.baseURL}${path}`, {
                 method,
                 headers,
-                body: body === undefined ? undefined : JSON.stringify(body),
+                body: body === undefined ? undefined : rawBody ? body : JSON.stringify(body),
                 signal: controller.signal,
             });
             if (!response.ok) {

package/dist/resources/volumes.d.ts

@@ -0,0 +1,25 @@
+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";
+export declare class VolumesResource {
+    private readonly http;
+    constructor(http: HTTPClient);
+    list(params?: ListVolumesParams, options?: RequestOptions): Promise<ListVolumesResponse>;
+    create(params?: CreateVolumeParams, options?: RequestOptions): Promise<VolumeInfo>;
+    retrieve(volumeID: string, options?: RequestOptions): Promise<VolumeInfo>;
+    update(volumeID: string, params: {
+        name: string;
+    }, options?: RequestOptions): Promise<VolumeInfo>;
+    delete(volumeID: string, options?: RequestOptions): Promise<void>;
+    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>;
+    writeFile(volumeID: string, path: string, content: string | ArrayBuffer | Blob, options?: RequestOptions): Promise<VolumeFileWrite>;
+    deleteFile(volumeID: string, path: string, options?: RequestOptions): Promise<void>;
+    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>;
+}

package/dist/resources/volumes.js

@@ -0,0 +1,75 @@
+import { buildQuery } from "../internal/query.js";
+export class VolumesResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(params = {}, options) {
+        return this.http.request("GET", `/v1/volumes${buildQuery({ limit: params.limit, page_token: params.page_token })}`, undefined, options);
+    }
+    create(params = {}, options) {
+        return this.http.request("POST", "/v1/volumes", params, options);
+    }
+    retrieve(volumeID, options) {
+        return this.http.request("GET", `/v1/volumes/${encodeURIComponent(volumeID)}`, undefined, options);
+    }
+    update(volumeID, params, options) {
+        return this.http.request("PATCH", `/v1/volumes/${encodeURIComponent(volumeID)}`, params, options);
+    }
+    delete(volumeID, options) {
+        return this.http.requestVoid("DELETE", `/v1/volumes/${encodeURIComponent(volumeID)}`, options);
+    }
+    listEntries(volumeID, params = {}, options) {
+        return this.http.request("GET", `/v1/volumes/${encodeURIComponent(volumeID)}/entries${buildQuery({
+            path: params.path,
+            limit: params.limit,
+            page_token: params.page_token,
+        })}`, undefined, options);
+    }
+    searchEntries(volumeID, params, options) {
+        return this.http.request("GET", `/v1/volumes/${encodeURIComponent(volumeID)}/search${buildQuery({
+            query: params.query,
+            path: params.path,
+            limit: params.limit,
+            page_token: params.page_token,
+        })}`, undefined, options);
+    }
+    readFile(volumeID, path, params = {}, options) {
+        const url = `/v1/volumes/${encodeURIComponent(volumeID)}/files/${volumePath(path)}${buildQuery({
+            max_bytes: params.max_bytes,
+            format: params.format,
+        })}`;
+        if (params.format === "raw") {
+            return this.http.requestBinary("GET", url, options).then(({ body, headers }) => ({
+                path,
+                size: Number(headers.get("X-Volume-Size") ?? body.byteLength),
+                truncated: headers.get("X-Volume-Truncated") === "true",
+                content: body,
+                content_type: headers.get("Content-Type") ?? undefined,
+            }));
+        }
+        return this.http.request("GET", url, undefined, options);
+    }
+    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);
+    }
+    reconcileUsage(volumeID, options) {
+        return this.http.request("POST", `/v1/volumes/${encodeURIComponent(volumeID)}/usage/reconcile`, undefined, options);
+    }
+    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);
+    }
+}
+function volumePath(path) {
+    return path
+        .split("/")
+        .filter(Boolean)
+        .map((part) => encodeURIComponent(part))
+        .join("/");
+}

package/dist/types/index.d.ts

@@ -4,3 +4,4 @@ export * from "./tools.js";
 export * from "./responses.js";
 export * from "./streaming.js";
 export * from "./catalog.js";
+export * from "./volumes.js";

package/dist/types/index.js

@@ -4,3 +4,4 @@ export * from "./tools.js";
 export * from "./responses.js";
 export * from "./streaming.js";
 export * from "./catalog.js";
+export * from "./volumes.js";

package/dist/types/input.d.ts

@@ -6,9 +6,12 @@ export interface Annotation {
     end_index?: number;
 }
 export interface ContentPart {
-    type: "input_text" | "output_text" | "input_image";
+    type: "input_text" | "output_text" | "input_image" | "input_document";
     text?: string;
     image_url?: string;
+    mime_type?: string;
+    filename?: string;
+    document_url?: string;
     annotations?: Annotation[];
     logprobs?: unknown[];
 }

package/dist/types/responses.d.ts

@@ -18,10 +18,12 @@ export interface ResponseCreateParamsBase {
     metadata?: Record<string, unknown>;
     store?: boolean;
     previous_response_id?: string;
+    volume_id?: string;
     prompt_cache_key?: string;
     memory?: MemoryOptions;
     plan_mode_preference?: AgentCapabilityPreference;
     sub_agent_preference?: AgentCapabilityPreference;
+    user?: string;
     stream?: boolean;
 }
 export interface ResponseCreateParamsNonStreaming extends ResponseCreateParamsBase {

package/dist/types/streaming.d.ts

@@ -17,7 +17,7 @@ export interface ResponseModelCallEvent {
     model_chain?: string[];
     attempt_count?: number;
 }
-export type ResponseStreamEventType = "response.created" | "response.in_progress" | "response.completed" | "response.failed" | "response.plan.updated" | "response.output_item.added" | "response.output_item.done" | "response.output_text.delta" | "response.output_text.done" | "response.reasoning.started" | "response.reasoning.search_queries" | "response.reasoning.search_results" | "response.reasoning.fetch_url_queries" | "response.reasoning.fetch_url_results" | "response.reasoning.stopped" | "response.tool.invocation.completed" | "response.step.completed" | "response.step.failed" | "response.step.skipped" | "response.model.requested" | "response.model.completed" | "response.model.failed";
+export type ResponseStreamEventType = "response.created" | "response.in_progress" | "response.completed" | "response.failed" | "response.requires_action" | "response.plan.updated" | "response.output_item.added" | "response.output_item.done" | "response.output_text.delta" | "response.output_text.done" | "response.reasoning.started" | "response.reasoning.search_queries" | "response.reasoning.search_results" | "response.reasoning.fetch_url_queries" | "response.reasoning.fetch_url_results" | "response.reasoning.stopped" | "response.tool.invocation.completed" | "response.step.completed" | "response.step.failed" | "response.step.skipped" | "response.model.requested" | "response.model.completed" | "response.model.failed";
 export interface ResponseStreamEvent {
     type: ResponseStreamEventType;
     sequence_number: number;

package/dist/types/tools.d.ts

@@ -10,6 +10,12 @@ export interface SmartWebSearchTool {
     max_tokens?: number;
     max_tokens_per_page?: number;
 }
+export interface LiteWebSearchTool {
+    name: "lite_web_search";
+    type?: "search";
+    max_tokens?: number;
+    max_tokens_per_page?: number;
+}
 export interface FetchURLTool {
     name: "fetch_url";
     type?: "url_reader";
@@ -27,7 +33,7 @@ export interface SkillTool {
     version?: string;
     arguments?: Record<string, unknown>;
 }
-export type Tool = WebSearchTool | SmartWebSearchTool | FetchURLTool | FunctionTool | SkillTool;
+export type Tool = WebSearchTool | SmartWebSearchTool | LiteWebSearchTool | FetchURLTool | FunctionTool | SkillTool;
 export interface PublicTool {
     object: "tool";
     name: string;

package/dist/types/volumes.d.ts

@@ -0,0 +1,67 @@
+export interface VolumeInfo {
+    volume_id: string;
+    tenant_id?: string;
+    name?: string;
+    oss_prefix?: string;
+    bytes_used?: number;
+    object_count?: number;
+    usage_reconciled_at_unix?: number;
+    created_at_unix?: number;
+    updated_at_unix?: number;
+}
+export interface VolumeEntry {
+    path: string;
+    is_dir: boolean;
+    size: number;
+    modified_at_unix?: number;
+}
+export interface ListVolumesParams {
+    limit?: number;
+    page_token?: string;
+}
+export interface ListVolumesResponse {
+    object: "list";
+    data: VolumeInfo[];
+    next_page_token?: string;
+}
+export interface CreateVolumeParams {
+    name?: string;
+}
+export interface ListVolumeEntriesParams {
+    path?: string;
+    limit?: number;
+    page_token?: string;
+}
+export interface SearchVolumeEntriesParams extends ListVolumeEntriesParams {
+    query: string;
+}
+export interface ListVolumeEntriesResponse {
+    object: "list";
+    entries: VolumeEntry[];
+    next_page_token?: string;
+}
+export interface ReadVolumeFileParams {
+    max_bytes?: number;
+    format?: "json";
+}
+export interface ReadVolumeFileRawParams {
+    max_bytes?: number;
+    format: "raw";
+}
+export interface VolumeFileRead {
+    path: string;
+    size: number;
+    truncated: boolean;
+    content: string;
+}
+export interface VolumeFileRaw {
+    path: string;
+    size: number;
+    truncated: boolean;
+    content: ArrayBuffer;
+    content_type?: string;
+}
+export interface VolumeFileWrite {
+    path: string;
+    size: number;
+}

package/dist/types/volumes.js

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

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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