@agent-os-sdk/client 0.9.9 → 0.9.10

package/src/client/raw.ts

@@ -9,8 +9,9 @@ import createClient, { type Client } from "openapi-fetch";
 import type { components, paths } from "../generated/openapi.js";
 import { createErrorFromResponse } from "../errors/factory.js";
 import { AgentOsError, NetworkError, TimeoutError } from "../errors/index.js";
-import { httpRequestBuilder } from "./HttpRequestBuilder.js";
+import { httpRequestBuilder, sanitizeValidCorrelationId } from "./HttpRequestBuilder.js";
 import type { OperationContext } from "./OperationContext.js";
+import type { OperationContextProvider } from "./OperationContextProvider.js";
 import { mergeNetworkConfig, type NetworkConfig } from "./config.js";
 import { withRetry } from "./retry.js";
 import { withTimeout } from "./timeout.js";
@@ -22,6 +23,8 @@ export type ClientOptions = {
     baseUrl: string;
     headers?: Record<string, string>;
     headerProvider?: () => Promise<Record<string, string>>;
+    /** Optional flow context provider (ALS/manual). */
+    contextProvider?: OperationContextProvider;
     /** Network behavior (timeouts/retries). Defaults to DEFAULT_NETWORK_CONFIG. */
     network?: Partial<NetworkConfig>;
     /** Hooks for observability (OTEL, Sentry, etc.) */
@@ -39,6 +42,8 @@ export interface SDKHooks {
     onResponse?: (context: HookResponseContext) => void | Promise<void>;
     /** Called on any error (network, timeout, HTTP error) */
     onError?: (context: HookErrorContext) => void | Promise<void>;
+    /** Optional logger bridge used by SDK internal warnings. */
+    logger?: { warn?: (message: string) => void };
 }
 
 export interface HookRequestContext {
@@ -106,8 +111,67 @@ export function createTypedClient(options: ClientOptions): TypedClient {
  * Wraps openapi-fetch to provide the old interface while maintaining types.
  */
 export function createRawClient(options: ClientOptions) {
-    const { baseUrl, headers: defaultHeaders = {}, headerProvider } = options;
+    const { baseUrl, headers: defaultHeaders = {}, headerProvider, contextProvider } = options;
     const networkConfig = mergeNetworkConfig(options.network);
+    const warn = (message: string): void => {
+        const hookWarn = options.hooks?.logger?.warn;
+        if (typeof hookWarn === "function") {
+            hookWarn(message);
+            return;
+        }
+        if (typeof console !== "undefined" && typeof console.warn === "function") {
+            console.warn(message);
+        }
+    };
+    // Sticky fallback context for clients that don't provide per-operation context.
+    const fallbackContext: OperationContext = Object.freeze({
+        correlationId: crypto.randomUUID(),
+    });
+    let warnedStickyFallbackContext = false;
+    let warnedInvalidContextCorrelation = false;
+    const resolveEffectiveContext = (optsContext?: OperationContext): OperationContext => {
+        const providerContext = contextProvider?.get();
+        const usingStickyFallback = !optsContext && !providerContext;
+        if (usingStickyFallback && !contextProvider && !warnedStickyFallbackContext) {
+            warnedStickyFallbackContext = true;
+            warn(
+                "[AgentOS SDK] Using sticky fallback correlation context per client instance. " +
+                "For long-lived server clients, configure contextProvider (ALS/manual) to scope correlation per request."
+            );
+        }
+
+        const effectiveContext = optsContext ?? providerContext ?? fallbackContext;
+        const correlationProvidedByCaller =
+            effectiveContext !== fallbackContext
+            && typeof effectiveContext?.correlationId === "string";
+
+        if (correlationProvidedByCaller) {
+            const validCorrelation = sanitizeValidCorrelationId(effectiveContext.correlationId);
+            if (!validCorrelation) {
+                if (!warnedInvalidContextCorrelation) {
+                    warnedInvalidContextCorrelation = true;
+                    warn(
+                        "[AgentOS SDK] Invalid correlationId in operation context ignored; generated fallback correlation id. " +
+                        "Provide a valid correlationId (8-128 chars: A-Za-z0-9._:-)."
+                    );
+                }
+                // Caller provided invalid flow id: use per-request fallback (not sticky fallback context).
+                return {
+                    ...effectiveContext,
+                    correlationId: crypto.randomUUID(),
+                };
+            }
+
+            if (validCorrelation !== effectiveContext.correlationId) {
+                return {
+                    ...effectiveContext,
+                    correlationId: validCorrelation,
+                };
+            }
+        }
+
+        return effectiveContext;
+    };
     type ErrorPayload = { code?: string; message?: string; details?: unknown } & Record<string, unknown>;
     type HttpAgentOsError = AgentOsError & {
         response?: Response;
@@ -173,9 +237,11 @@ export function createRawClient(options: ClientOptions) {
             headers["Content-Type"] = "application/json";
         }
 
+        const effectiveContext = resolveEffectiveContext(opts?.context);
+
         // Build standard headers via HttpRequestBuilder (single source of truth)
         const builderHeaders = httpRequestBuilder.build({
-            context: opts?.context,
+            context: effectiveContext,
             idempotencyKey: opts?.idempotencyKey,
             requireFlow: opts?.requireFlow,
         });
@@ -357,7 +423,12 @@ export function createRawClient(options: ClientOptions) {
          */
         streamGet: async (
             path: string,
-            opts?: { params?: { path?: Record<string, string>; query?: Record<string, unknown> }; headers?: Record<string, string> }
+            opts?: {
+                params?: { path?: Record<string, string>; query?: Record<string, unknown> };
+                headers?: Record<string, string>;
+                context?: OperationContext;
+                requireFlow?: boolean;
+            }
         ): Promise<Response> => {
             let url = path;
             if (opts?.params?.path) {
@@ -377,9 +448,15 @@ export function createRawClient(options: ClientOptions) {
             }
             const fullUrl = `${baseUrl}${url}`;
             const dynamicHeaders = headerProvider ? await headerProvider() : {};
+            const effectiveContext = resolveEffectiveContext(opts?.context);
+            const builderHeaders = httpRequestBuilder.build({
+                context: effectiveContext,
+                requireFlow: opts?.requireFlow,
+            });
             const headers: Record<string, string> = {
                 ...defaultHeaders,
                 ...dynamicHeaders,
+                ...builderHeaders,
                 Accept: "text/event-stream",
                 ...opts?.headers,
             };
@@ -397,6 +474,9 @@ export function createRawClient(options: ClientOptions) {
                 body?: unknown;
                 headers?: Record<string, string>;
                 signal?: AbortSignal;
+                context?: OperationContext;
+                idempotencyKey?: string;
+                requireFlow?: boolean;
             }
         ): Promise<Response> => {
             let url = path;
@@ -407,9 +487,16 @@ export function createRawClient(options: ClientOptions) {
             }
             const fullUrl = `${baseUrl}${url}`;
             const dynamicHeaders = headerProvider ? await headerProvider() : {};
+            const effectiveContext = resolveEffectiveContext(opts?.context);
+            const builderHeaders = httpRequestBuilder.build({
+                context: effectiveContext,
+                idempotencyKey: opts?.idempotencyKey,
+                requireFlow: opts?.requireFlow,
+            });
             const headers: Record<string, string> = {
                 ...defaultHeaders,
                 ...dynamicHeaders,
+                ...builderHeaders,
                 "Content-Type": "application/json",
                 Accept: "text/event-stream",
                 ...opts?.headers,

package/src/index.ts

@@ -101,6 +101,7 @@ export * from "./modules/credentials.js";
 export * from "./modules/datasets.js";
 export * from "./modules/me.js";
 export * from "./modules/members.js";
+export * from "./modules/observability.js";
 export * from "./modules/presets.js";
 export * from "./modules/prompts.js";
 export * from "./modules/roles.js";

package/src/modules/agents.ts

@@ -53,6 +53,21 @@ export interface GraphValidationResponse {
     warnings?: string[];
 }
 
+export interface UpsertAgentCredentialBindingRequest {
+    credential_id: string;
+    alias: string;
+    priority?: number;
+}
+
+export interface AgentCredentialBindingUpsertResponse {
+    id: string;
+    updated: boolean;
+    agent_id: string;
+    credential_id: string;
+    alias: string;
+    priority: number;
+}
+
 export type AgentListResponse = PaginatedResponse<Agent>;
 
 export class AgentsModule {
@@ -259,6 +274,34 @@ export class AgentsModule {
         });
     }
 
+    /**
+     * Get Mermaid diagram for a specific bundle graph.
+     */
+    async getBundleMermaid(agentId: string, bundleId: string): Promise<APIResponse<BundleMermaidResponse>> {
+        return this.client.GET<BundleMermaidResponse>("/v1/api/agents/{agentId}/bundles/{bundleId}/graph/mermaid", {
+            params: { path: { agentId, bundleId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Creates or updates an agent credential binding by alias.
+     */
+    async upsertCredentialBinding(
+        agentId: string,
+        body: UpsertAgentCredentialBindingRequest
+    ): Promise<APIResponse<AgentCredentialBindingUpsertResponse>> {
+        return this.client.POST<AgentCredentialBindingUpsertResponse>("/v1/api/agents/{id}/credential-bindings", {
+            params: { path: { id: agentId } },
+            body: {
+                credential_id: body.credential_id,
+                alias: body.alias,
+                priority: body.priority ?? 0,
+            },
+            headers: this.headers(),
+        });
+    }
+
 }
 
 // Bundle manifest response type
@@ -274,3 +317,12 @@ export interface BundleManifestResponse {
     created_at?: string;
     graph_spec?: Record<string, unknown>;
 }
+
+export interface BundleMermaidResponse {
+    bundle_id: string;
+    agent_id: string;
+    mermaid: string;
+    format?: string;
+    node_count?: number;
+    edge_count?: number;
+}

package/src/modules/builder.ts

@@ -118,11 +118,6 @@ export type HintModel = {
 };
 
 export type GraphUpdateAction = {
-    // Legacy support
-    action: string;
-    // ... legacy fields omitted for brevity, keeping strict new protocol
-} | {
-    // New protocol (WAVE-3)
     graph_spec: Record<string, unknown>;
     hints?: HintModel[];
     has_errors?: boolean;
@@ -166,8 +161,6 @@ export type PatchOp = {
     label?: string;
     data?: Record<string, unknown>;
     set?: Record<string, unknown>;
-    source?: string;
-    target?: string;
     from?: string;
     to?: string;
     entrypoint?: string;

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", {