@agent-api/sdk 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — @agent-api/sdk
 
+## 1.0.3
+
+### Added
+
+- Workbench volume APIs: `summarize`, `grep`, `readLines`, `patchLines`, `downloadArchive`.
+- `responses.retrieveVolume` for `GET /v1/responses/{response_id}/volume`.
+
+### 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

@@ -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
 

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/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.3";
+export declare const USER_AGENT = "@agent-api/sdk/1.0.3";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "1.0.2";
+export const VERSION = "1.0.3";
 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.3",
   "description": "Production JavaScript SDK for the Managed Agent API",
   "license": "MIT",
   "repository": {