@agent-os-sdk/client 0.9.9 → 0.9.11

package/src/modules/files.ts

@@ -4,21 +4,23 @@
 
 import type { RawClient, APIResponse, components } from "../client/raw.js";
 
+type FileListItem = components["schemas"]["FileListItem"];
+type FileDetail = components["schemas"]["FileDetail"];
 type CreatePresignedUploadRequest = components["schemas"]["CreatePresignedUploadRequest"];
 type PresignedUploadResponse = components["schemas"]["PresignedUploadResponse"];
 type ConfirmUploadRequest = components["schemas"]["ConfirmUploadRequest"];
+type FileConfirmResponse = components["schemas"]["FileConfirmResponse"];
+type PresignedDownloadResponse = components["schemas"]["PresignedDownloadResponse"];
 
 export interface StoredFile {
     id: string;
     filename: string;
     content_type: string;
     size_bytes: number;
-    sha256: string;
-    storage_uri: string;
-    workspace_id: string;
-    uploaded_by?: string;
+    sha256?: string;
     status: "pending" | "confirmed" | "deleted";
     created_at: string;
+    updated_at?: string;
 }
 
 export interface FileListResponse {
@@ -29,39 +31,109 @@ export interface FileListResponse {
 export interface PresignedUpload {
     file_id: string;
     upload_url: string;
-    expires_at: string;
+    expires_in: number;
+    object_key: string;
+}
+
+export interface ConfirmedUpload {
+    file_id: string;
+    status: string;
+    size_bytes: number;
+    sha256?: string;
 }
 
 export interface PresignedDownload {
+    file_id: string;
     download_url: string;
-    expires_at: string;
+    filename: string;
+    content_type: string;
+    size_bytes: number;
+    expires_in: number;
 }
 
 export class FilesModule {
     constructor(private client: RawClient, private headers: () => Record<string, string>) { }
 
+    private resolveWorkspaceId(workspaceId?: string): string {
+        if (workspaceId && workspaceId.trim().length > 0) {
+            return workspaceId.trim();
+        }
+
+        const headers = this.headers();
+        const fromHeader = headers["X-Workspace-Id"] ?? headers["x-workspace-id"];
+        if (fromHeader && fromHeader.trim().length > 0) {
+            return fromHeader.trim();
+        }
+
+        throw new Error("workspace_id is required (pass workspaceId or set X-Workspace-Id in client headers)");
+    }
+
+    private static toStoredFile(item: FileListItem | FileDetail): StoredFile {
+        return {
+            id: item.id ?? "",
+            filename: item.filename ?? "",
+            content_type: item.content_type ?? "application/octet-stream",
+            size_bytes: item.size_bytes ?? 0,
+            sha256: "sha256" in item ? item.sha256 ?? undefined : undefined,
+            status: (item.status ?? "pending") as StoredFile["status"],
+            created_at: item.created_at ?? "",
+            updated_at: "updated_at" in item ? item.updated_at ?? undefined : undefined,
+        };
+    }
+
     /**
-     * List all files.
+     * List files in a workspace.
      */
     async list(params?: {
         workspace_id?: string;
+        status?: string;
         limit?: number;
         offset?: number;
     }): Promise<APIResponse<FileListResponse>> {
-        return this.client.GET<FileListResponse>("/v1/api/files", {
-            params: { query: params },
+        const workspaceId = this.resolveWorkspaceId(params?.workspace_id);
+        const response = await this.client.GET<FileListItem[]>("/v1/api/workspaces/{workspaceId}/files", {
+            params: {
+                path: { workspaceId },
+                query: {
+                    status: params?.status,
+                    limit: params?.limit,
+                    offset: params?.offset,
+                },
+            },
             headers: this.headers(),
         });
+
+        const items = Array.isArray(response.data)
+            ? response.data.map((item) => FilesModule.toStoredFile(item))
+            : [];
+
+        return {
+            ...response,
+            data: {
+                items,
+                total: items.length,
+            },
+        };
     }
 
     /**
      * Get a file by ID.
      */
-    async get(fileId: string): Promise<APIResponse<StoredFile>> {
-        return this.client.GET<StoredFile>("/v1/api/files/{id}", {
-            params: { path: { id: fileId } },
+    async get(fileId: string, workspaceId?: string): Promise<APIResponse<StoredFile>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        const response = await this.client.GET<FileDetail>("/v1/api/workspaces/{workspaceId}/files/{fileId}", {
+            params: { path: { workspaceId: resolvedWorkspaceId, fileId } },
             headers: this.headers(),
         });
+
+        if (!response.data) {
+            return response as APIResponse<StoredFile>;
+        }
+
+        return {
+            ...response,
+            data: FilesModule.toStoredFile(response.data),
+        };
     }
 
     /**
@@ -69,44 +141,68 @@ export class FilesModule {
      */
     async createUpload(body: {
         filename: string;
-        content_type: string;
+        content_type?: string;
         size_bytes?: number;
         expected_sha256?: string;
-    }): Promise<APIResponse<PresignedUpload>> {
-        return this.client.POST<PresignedUpload>("/v1/api/files/upload", {
-            body,
+    }, workspaceId?: string): Promise<APIResponse<PresignedUpload>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        const requestBody: CreatePresignedUploadRequest = {
+            filename: body.filename,
+            content_type: body.content_type,
+            size_bytes: body.size_bytes,
+            expected_sha256: body.expected_sha256,
+        };
+        return this.client.POST<PresignedUploadResponse>("/v1/api/workspaces/{workspaceId}/files/presign", {
+            params: { path: { workspaceId: resolvedWorkspaceId } },
+            body: requestBody,
             headers: this.headers(),
-        });
+        }) as Promise<APIResponse<PresignedUpload>>;
     }
 
     /**
      * Confirm an upload.
      */
-    async confirmUpload(fileId: string, sha256: string): Promise<APIResponse<StoredFile>> {
-        return this.client.POST<StoredFile>("/v1/api/files/{id}/confirm", {
-            params: { path: { id: fileId } },
-            body: { sha256 },
+    async confirmUpload(fileId: string, sha256?: string, workspaceId?: string): Promise<APIResponse<ConfirmedUpload>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        const requestBody: ConfirmUploadRequest = { sha256 };
+        return this.client.POST<FileConfirmResponse>("/v1/api/workspaces/{workspaceId}/files/{fileId}/confirm", {
+            params: { path: { workspaceId: resolvedWorkspaceId, fileId } },
+            body: requestBody,
             headers: this.headers(),
-        });
+        }) as Promise<APIResponse<ConfirmedUpload>>;
     }
 
     /**
      * Get a presigned download URL.
      */
-    async getDownloadUrl(fileId: string): Promise<APIResponse<PresignedDownload>> {
-        return this.client.GET<PresignedDownload>("/v1/api/files/{id}/download", {
-            params: { path: { id: fileId } },
+    async getDownloadUrl(fileId: string, workspaceId?: string): Promise<APIResponse<PresignedDownload>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        return this.client.GET<PresignedDownloadResponse>("/v1/api/workspaces/{workspaceId}/files/{fileId}/download", {
+            params: { path: { workspaceId: resolvedWorkspaceId, fileId } },
             headers: this.headers(),
-        });
+        }) as Promise<APIResponse<PresignedDownload>>;
     }
 
     /**
      * Delete a file.
      */
-    async delete(fileId: string): Promise<APIResponse<void>> {
-        return this.client.DELETE<void>("/v1/api/files/{id}", {
-            params: { path: { id: fileId } },
+    async delete(fileId: string, workspaceId?: string): Promise<APIResponse<void>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        return this.client.DELETE<void>("/v1/api/workspaces/{workspaceId}/files/{fileId}", {
+            params: { path: { workspaceId: resolvedWorkspaceId, fileId } },
             headers: this.headers(),
         });
     }
+
+    /**
+     * Alias for createUpload with explicit semantic name.
+     */
+    async createPresignedUpload(body: {
+        filename: string;
+        content_type?: string;
+        size_bytes?: number;
+        expected_sha256?: string;
+    }, workspaceId?: string): Promise<APIResponse<PresignedUpload>> {
+        return this.createUpload(body, workspaceId);
+    }
 }

package/src/modules/graphs.ts

@@ -115,7 +115,7 @@ export interface GraphsIntrospectResponse {
     mermaid: string;
     nodes: string[];
     edges: [string, string][];
-    graph_type?: string;
+    type?: string;
 }
 
 // ============ Module ============

package/src/modules/members.ts

@@ -159,7 +159,6 @@ export class MembersModule {
 
     /**
      * Remove a member from the tenant.
-     * Note: Use delete() - remove() is provided as alias for backwards compatibility.
      */
     async delete(memberId: string): Promise<APIResponse<void>> {
         return this.client.DELETE<void>("/v1/api/members/{id}", {
@@ -168,12 +167,6 @@ export class MembersModule {
         });
     }
 
-    /** 
-     * Alias for delete() (backwards compatibility)
-     * @deprecated Use delete() instead
-     */
-    remove = (memberId: string) => this.delete(memberId);
-
     /**
      * Resend invitation email.
      */

package/src/modules/observability.ts

@@ -0,0 +1,28 @@
+import type { APIResponse, RawClient } from "../client/raw.js";
+
+export type FrontendLogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
+
+export interface FrontendLogPayload {
+    level: FrontendLogLevel;
+    message: string;
+    stack?: string;
+    route?: string;
+    url?: string;
+    user_agent?: string;
+    session_id?: string;
+    context?: Record<string, unknown>;
+}
+
+export class ObservabilityModule {
+    constructor(
+        private client: RawClient,
+        private headers: () => Record<string, string>
+    ) { }
+
+    async logFrontend(payload: FrontendLogPayload): Promise<APIResponse<Record<string, unknown>>> {
+        return this.client.POST<Record<string, unknown>>("/v1/api/observability/frontend-log", {
+            body: payload,
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/runs.ts

@@ -110,13 +110,15 @@ export class RunsModule {
         agent_id: string;
         thread?: { thread_id?: string } | { new_thread: true };
         input?: unknown;
+        /** Optional bundle pinning (draft/published). When omitted, backend resolves live bundle. */
+        bundle_id?: string;
         /** Idempotency key for safe retries. When set, duplicate requests with the same key return the original response. */
         idempotency_key?: string;
     }): Promise<APIResponse<CreateRunResponse>> {
-        // Send Idempotency-Key in HEADER (enterprise standard) + body (backend compat)
+        // Send canonical X-Idempotency-Key header + body idempotency_key for backend contract parity.
         const headers: Record<string, string> = {};
         if (body.idempotency_key) {
-            headers["Idempotency-Key"] = body.idempotency_key;
+            headers["X-Idempotency-Key"] = body.idempotency_key;
         }
 
         return this.client.POST<CreateRunResponse>("/v1/api/runs", {

package/src/modules/threads.ts

@@ -93,10 +93,10 @@ export class ThreadsModule {
         /** Idempotency key for safe retries. When set, duplicate requests with the same key return the original response. */
         idempotency_key?: string;
     }): Promise<APIResponse<Thread>> {
-        // Send Idempotency-Key in HEADER (enterprise standard) + body (backend compat)
+        // Send canonical X-Idempotency-Key header + body idempotency_key for backend contract parity.
         const headers: Record<string, string> = { ...this.headers() };
         if (body?.idempotency_key) {
-            headers["Idempotency-Key"] = body.idempotency_key;
+            headers["X-Idempotency-Key"] = body.idempotency_key;
         }
 
         return this.client.POST<Thread>("/v1/api/threads", {

package/src/modules/vectorStores.ts

@@ -11,7 +11,6 @@ type VectorStoreFileResponse = components["schemas"]["VectorStoreFileResponse"];
 export interface VectorStore {
     id: string;
     name: string;
-    workspace_id: string;
     embedding_provider: string;
     embedding_model: string;
     dimension: number;
@@ -52,6 +51,42 @@ export interface VectorStoreFilesResponse {
     total: number;
 }
 
+type VectorStoreLike = VectorStoreResponse & {
+    embeddingProvider?: string;
+    embeddingModel?: string;
+    credentialBindingAlias?: string;
+    fileCount?: number;
+    createdAt?: string;
+};
+
+type VectorStoreFileLike = VectorStoreFileResponse & {
+    fileId?: string;
+    createdAt?: string;
+};
+
+function toVectorStore(item: VectorStoreLike): VectorStore {
+    return {
+        id: item.id ?? "",
+        name: item.name ?? "",
+        embedding_provider: item.embedding_provider ?? item.embeddingProvider ?? "",
+        embedding_model: item.embedding_model ?? item.embeddingModel ?? "",
+        dimension: item.dimension ?? 0,
+        credential_binding_alias: item.credential_binding_alias ?? item.credentialBindingAlias ?? undefined,
+        file_count: item.file_count ?? item.fileCount ?? 0,
+        created_at: item.created_at ?? item.createdAt ?? "",
+    };
+}
+
+function toVectorStoreFile(item: VectorStoreFileLike): VectorStoreFile {
+    return {
+        id: item.id ?? "",
+        file_id: item.file_id ?? item.fileId ?? "",
+        filename: item.filename ?? "",
+        status: (item.status ?? "pending") as VectorStoreFile["status"],
+        created_at: item.created_at ?? item.createdAt ?? "",
+    };
+}
+
 export class VectorStoresModule {
     constructor(private client: RawClient, private headers: () => Record<string, string>) { }
 
@@ -63,20 +98,41 @@ export class VectorStoresModule {
         limit?: number;
         offset?: number;
     }): Promise<APIResponse<VectorStoreListResponse>> {
-        return this.client.GET<VectorStoreListResponse>("/v1/api/vector-stores", {
+        const response = await this.client.GET<VectorStoreResponse[]>("/v1/api/vector-stores", {
             params: { query: params },
             headers: this.headers(),
         });
+
+        const items = Array.isArray(response.data)
+            ? response.data.map((item) => toVectorStore(item))
+            : [];
+
+        return {
+            ...response,
+            data: {
+                items,
+                total: items.length,
+            },
+        };
     }
 
     /**
      * Get a vector store by ID.
      */
     async get(storeId: string): Promise<APIResponse<VectorStore>> {
-        return this.client.GET<VectorStore>("/v1/api/vector-stores/{id}", {
-            params: { path: { id: storeId } },
+        const response = await this.client.GET<VectorStoreResponse>("/v1/api/vector-stores/{vectorStoreId}", {
+            params: { path: { vectorStoreId: storeId } },
             headers: this.headers(),
         });
+
+        if (!response.data) {
+            return response as APIResponse<VectorStore>;
+        }
+
+        return {
+            ...response,
+            data: toVectorStore(response.data),
+        };
     }
 
     /**
@@ -89,18 +145,27 @@ export class VectorStoresModule {
         dimension?: number;
         credential_binding_alias?: string;
     }): Promise<APIResponse<VectorStore>> {
-        return this.client.POST<VectorStore>("/v1/api/vector-stores", {
+        const response = await this.client.POST<VectorStoreResponse>("/v1/api/vector-stores", {
             body,
             headers: this.headers(),
         });
+
+        if (!response.data) {
+            return response as APIResponse<VectorStore>;
+        }
+
+        return {
+            ...response,
+            data: toVectorStore(response.data),
+        };
     }
 
     /**
      * Delete a vector store.
      */
     async delete(storeId: string): Promise<APIResponse<void>> {
-        return this.client.DELETE<void>("/v1/api/vector-stores/{id}", {
-            params: { path: { id: storeId } },
+        return this.client.DELETE<void>("/v1/api/vector-stores/{vectorStoreId}", {
+            params: { path: { vectorStoreId: storeId } },
             headers: this.headers(),
         });
     }
@@ -115,11 +180,11 @@ export class VectorStoresModule {
         top_k?: number;
         min_score?: number;
     }): Promise<APIResponse<VectorQueryResult>> {
-        return this.client.POST<VectorQueryResult>("/v1/api/vector-stores/{id}/query", {
-            params: { path: { id: storeId } },
+        return this.client.POST<VectorQueryResponse>("/v1/api/vector-stores/{vectorStoreId}/query", {
+            params: { path: { vectorStoreId: storeId } },
             body,
             headers: this.headers(),
-        });
+        }) as Promise<APIResponse<VectorQueryResult>>;
     }
 
     // ======================== Files ========================
@@ -128,32 +193,64 @@ export class VectorStoresModule {
      * List files in a vector store.
      */
     async listFiles(storeId: string, params?: {
-        limit?: number;
-        offset?: number;
+        skip?: number;
+        take?: number;
     }): Promise<APIResponse<VectorStoreFilesResponse>> {
-        return this.client.GET<VectorStoreFilesResponse>("/v1/api/vector-stores/{id}/files", {
-            params: { path: { id: storeId }, query: params },
+        const response = await this.client.GET<VectorStoreFileResponse[]>("/v1/api/vector-stores/{vectorStoreId}/files", {
+            params: { path: { vectorStoreId: storeId }, query: params },
             headers: this.headers(),
         });
+
+        const items = Array.isArray(response.data)
+            ? response.data.map((item) => toVectorStoreFile(item))
+            : [];
+
+        return {
+            ...response,
+            data: {
+                items,
+                total: items.length,
+            },
+        };
     }
 
     /**
      * Attach a file to a vector store.
      */
     async attachFile(storeId: string, fileId: string): Promise<APIResponse<VectorStoreFile>> {
-        return this.client.POST<VectorStoreFile>("/v1/api/vector-stores/{id}/files", {
-            params: { path: { id: storeId } },
+        const response = await this.client.POST<VectorStoreFileResponse>("/v1/api/vector-stores/{vectorStoreId}/files", {
+            params: { path: { vectorStoreId: storeId } },
             body: { file_id: fileId },
             headers: this.headers(),
         });
+
+        if (!response.data) {
+            return response as APIResponse<VectorStoreFile>;
+        }
+
+        return {
+            ...response,
+            data: toVectorStoreFile(response.data),
+        };
     }
 
     /**
      * Remove a file from a vector store.
      */
     async removeFile(storeId: string, fileId: string): Promise<APIResponse<void>> {
-        return this.client.DELETE<void>("/v1/api/vector-stores/{id}/files/{fileId}", {
-            params: { path: { id: storeId, fileId } },
+        return this.client.DELETE<void>("/v1/api/vector-stores/{vectorStoreId}/files/{fileId}", {
+            params: { path: { vectorStoreId: storeId, fileId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Bind a vector store to an agent.
+     */
+    async bindAgent(storeId: string, agentId: string): Promise<APIResponse<void>> {
+        return this.client.POST<void>("/v1/api/vector-stores/{vectorStoreId}/bind-agent", {
+            params: { path: { vectorStoreId: storeId } },
+            body: { agent_id: agentId },
             headers: this.headers(),
         });
     }

package/src/modules/workspaces.ts

@@ -3,9 +3,29 @@
  */
 
 import type { RawClient, APIResponse, components } from "../client/raw.js";
+import { parseSSE } from "../sse/client.js";
 
 type UpdateWorkspaceRequest = components["schemas"]["UpdateWorkspaceRequest"];
 
+// ─── Workspace Event Types ─────────────────────────────────────
+
+/** Event emitted by workspace-level SSE stream. */
+export interface WorkspaceEvent {
+    type: string;
+    workspace_id: string;
+    run_id?: string;
+    agent_id?: string;
+    old_status?: string;
+    new_status?: string;
+    ts: number;
+}
+
+/** Options for followEvents(). */
+export interface WorkspaceFollowOptions {
+    /** AbortSignal to kill the SSE connection. Required for cleanup. */
+    signal?: AbortSignal;
+}
+
 export interface Workspace {
     id: string;
     tenant_id: string;
@@ -106,6 +126,50 @@ export class WorkspacesModule {
             headers: this.headers(),
         });
     }
+
+    // ======================== FOLLOW (Workspace SSE) ========================
+
+    /**
+     * Stream events for a specific workspace via SSE.
+     * Server validates ACL: caller must have access to the workspace.
+     *
+     * @param workspaceId - Workspace to stream events for
+     * @param options - AbortSignal for cleanup (MUST be used to avoid leaking connections)
+     *
+     * @example
+     * ```ts
+     * const controller = new AbortController();
+     * for await (const event of client.workspaces.followEvents(workspaceId, { signal: controller.signal })) {
+     *   if (event.type === 'run_status_changed') {
+     *     console.log(`Run ${event.run_id} → ${event.new_status}`);
+     *   }
+     * }
+     * // On cleanup:
+     * controller.abort();
+     * ```
+     */
+    async *followEvents(workspaceId: string, options?: WorkspaceFollowOptions): AsyncGenerator<WorkspaceEvent, void, unknown> {
+        const response = await this.client.streamGet(
+            "/v1/api/workspaces/{workspaceId}/events/stream",
+            {
+                params: { path: { workspaceId } },
+                headers: this.headers(),
+                signal: options?.signal,
+            }
+        );
+
+        try {
+            for await (const rawEvent of parseSSE<WorkspaceEvent>(response)) {
+                if (rawEvent.data != null) {
+                    yield rawEvent.data;
+                }
+            }
+        } catch (err) {
+            // Abort is normal cleanup — not an error worth surfacing.
+            if (options?.signal?.aborted) return;
+            throw err;
+        }
+    }
 }
 
 export interface WorkspaceQuotaResponse {