@agent-os-sdk/client 0.9.9 → 0.9.11

package/dist/modules/workspaces.js

@@ -1,6 +1,7 @@
 /**
  * Workspaces Module - Fully Typed
  */
+import { parseSSE } from "../sse/client.js";
 export class WorkspacesModule {
     client;
     getTenantId;
@@ -74,4 +75,44 @@ 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, options) {
+        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(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;
+        }
+    }
 }

package/package.json

@@ -1,53 +1,52 @@
 {
-    "name": "@agent-os-sdk/client",
-    "version": "0.9.9",
-    "description": "Official TypeScript SDK for Agent OS platform",
-    "type": "module",
-    "main": "./dist/index.js",
-    "module": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-        ".": {
-            "import": "./dist/index.js",
-            "types": "./dist/index.d.ts"
-        }
-    },
-    "scripts": {
-        "generate": "tsx scripts/generate.ts",
-        "build": "tsc",
-        "dev": "tsc --watch",
-        "test": "vitest run",
-        "typecheck": "tsc --noEmit",
-        "prepublishOnly": "pnpm build"
-    },
-    "keywords": [
-        "agent-os",
-        "sdk",
-        "ai",
-        "agents",
-        "typescript"
-    ],
-    "author": "Agent OS Team",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/yuri12344/agent-os.git"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "openapi-fetch": "^0.13.0"
-    },
-    "devDependencies": {
-        "@types/node": "^25.2.1",
-        "openapi-typescript": "^7.4.0",
-        "tsx": "^4.19.0",
-        "typescript": "^5.5.0",
-        "vitest": "^4.0.18"
-    },
-    "files": [
-        "dist",
-        "src"
-    ]
+  "name": "@agent-os-sdk/client",
+  "version": "0.9.11",
+  "description": "Official TypeScript SDK for Agent OS platform",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "agent-os",
+    "sdk",
+    "ai",
+    "agents",
+    "typescript"
+  ],
+  "author": "Agent OS Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yuri12344/agent-os.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "openapi-typescript": "^7.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.18"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "generate": "tsx scripts/generate.ts",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/client/AgentOsClient.ts

@@ -66,6 +66,7 @@ import { InfoModule } from "../modules/info.js";
 import { MeModule } from "../modules/me.js";
 import { MembershipsModule } from "../modules/memberships.js";
 import { MetricsModule } from "../modules/metrics.js";
+import { ObservabilityModule } from "../modules/observability.js";
 import { PlaygroundModule } from "../modules/playground.js";
 import { PresetsModule } from "../modules/presets.js";
 import { PromptsModule } from "../modules/prompts.js";
@@ -119,6 +120,7 @@ export class AgentOsClient {
     readonly catalog: CatalogModule;
     readonly approvals: ApprovalsModule;
     readonly auth: AuthModule;
+    readonly observability: ObservabilityModule;
 
     // Convenience aliases
     readonly experiments: {
@@ -145,6 +147,7 @@ export class AgentOsClient {
         this._client = createRawClient({
             baseUrl: options.baseUrl,
             headerProvider: () => this._resolveHeaders(),
+            contextProvider: options.contextProvider,
             network: options.network,
             hooks: options.hooks,
         });
@@ -189,6 +192,7 @@ export class AgentOsClient {
         this.catalog = new CatalogModule(this._client);
         this.approvals = new ApprovalsModule(this._client, getHeaders);
         this.auth = new AuthModule(this._client, getHeaders);
+        this.observability = new ObservabilityModule(this._client, getHeaders);
 
         // Initialize convenience aliases
         this.experiments = {

package/src/client/HttpRequestBuilder.ts

@@ -23,6 +23,11 @@ declare const __SDK_VERSION__: string | undefined;
 const SDK_VERSION = typeof __SDK_VERSION__ !== "undefined" ? __SDK_VERSION__ : "0.7.12-dev";
 const CORRELATION_ID_PATTERN = /^[A-Za-z0-9._:-]{8,128}$/;
 
+export function sanitizeValidCorrelationId(raw?: string): string | null {
+    const candidate = sanitizeHeader((raw ?? "").trim());
+    return CORRELATION_ID_PATTERN.test(candidate) ? candidate : null;
+}
+
 /**
  * Options for building request headers
  */
@@ -81,8 +86,8 @@ export class HttpRequestBuilder {
     }
 
     private resolveCorrelationId(raw?: string): string {
-        const candidate = sanitizeHeader((raw ?? "").trim());
-        if (CORRELATION_ID_PATTERN.test(candidate)) {
+        const candidate = sanitizeValidCorrelationId(raw);
+        if (candidate) {
             return candidate;
         }
 

package/src/client/auth.ts

@@ -8,6 +8,7 @@
 
 import type { NetworkConfig } from "./config.js";
 import type { SDKHooks } from "./raw.js";
+import type { OperationContextProvider } from "./OperationContextProvider.js";
 
 // ============================================================================
 // Auth Provider Types
@@ -89,6 +90,9 @@ export type AgentOsClientOptions = {
     network?: Partial<NetworkConfig>
     /** Optional request lifecycle hooks for observability */
     hooks?: SDKHooks
+    /** Optional flow context provider (ALS/manual) for sticky correlation per operation. */
+    /** Recommended for long-lived server clients to avoid process-wide sticky fallback correlation. */
+    contextProvider?: OperationContextProvider
     /** Custom headers to add to all requests */
     headers?: Record<string, string>
 }

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,13 @@ 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;
+                signal?: AbortSignal;
+            }
         ): Promise<Response> => {
             let url = path;
             if (opts?.params?.path) {
@@ -377,13 +449,19 @@ 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,
             };
-            return fetch(fullUrl, { method: "GET", headers });
+            return fetch(fullUrl, { method: "GET", headers, signal: opts?.signal });
         },
 
         /**
@@ -397,6 +475,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 +488,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;