@agent-os-sdk/client 0.7.12 → 0.8.0

package/src/client/AgentOsClient.ts

@@ -27,54 +27,55 @@
  * ```
  */
 
-import { createRawClient, type RawClient } from "./raw.js";
 import {
     type AgentOsClientOptions,
     type AuthProvider,
     isApiTokenAuth,
-    isJwtAuth,
     isBrowser,
+    isJwtAuth,
 } from "./auth.js";
+import { createRawClient, type RawClient } from "./raw.js";
 
 import { AgentsModule } from "../modules/agents.js";
+import { BuilderModule } from "../modules/builder.js";
+import { CredentialsModule } from "../modules/credentials.js";
+import { KnowledgeModule } from "../modules/knowledge.js";
+import { MembersModule } from "../modules/members.js";
 import { RunsModule } from "../modules/runs.js";
+import { TenantsModule } from "../modules/tenants.js";
 import { ThreadsModule } from "../modules/threads.js";
 import { ToolsModule } from "../modules/tools.js";
-import { KnowledgeModule } from "../modules/knowledge.js";
 import { TriggersModule } from "../modules/triggers.js";
-import { CredentialsModule } from "../modules/credentials.js";
-import { BuilderModule } from "../modules/builder.js";
-import { MembersModule } from "../modules/members.js";
-import { TenantsModule } from "../modules/tenants.js";
 import { WorkspacesModule } from "../modules/workspaces.js";
 
 // Platform modules
-import { PromptsModule } from "../modules/prompts.js";
-import { TracesModule } from "../modules/traces.js";
-import { FilesModule } from "../modules/files.js";
-import { VectorStoresModule } from "../modules/vectorStores.js";
-import { EvaluationModule } from "../modules/evaluation.js";
+import { A2aModule } from "../modules/a2a.js";
+import { ApiTokensModule } from "../modules/apiTokens.js";
+import { ApprovalsModule } from "../modules/approvals.js";
+import { AuditModule } from "../modules/audit.js";
+import { CatalogModule } from "../modules/catalog.js";
 import { CheckpointsModule } from "../modules/checkpoints.js";
-import { PlaygroundModule } from "../modules/playground.js";
 import { CronsModule } from "../modules/crons.js";
 import { DlqModule } from "../modules/dlq.js";
-import { StoreModule } from "../modules/store.js";
-import { AuditModule } from "../modules/audit.js";
-import { UsageModule } from "../modules/usage.js";
+import { EvaluationModule } from "../modules/evaluation.js";
+import { FilesModule } from "../modules/files.js";
+import { GraphsModule } from "../modules/graphs.js";
+import { InfoModule } from "../modules/info.js";
 import { McpModule } from "../modules/mcp.js";
-import { A2aModule } from "../modules/a2a.js";
 import { MeModule } from "../modules/me.js";
-import { InfoModule } from "../modules/info.js";
-import { MetricsModule } from "../modules/metrics.js";
-import { GraphsModule } from "../modules/graphs.js";
-import { CatalogModule } from "../modules/catalog.js";
-import { ApprovalsModule } from "../modules/approvals.js";
-import { ApiTokensModule } from "../modules/apiTokens.js";
 import { MembershipsModule } from "../modules/memberships.js";
+import { MetricsModule } from "../modules/metrics.js";
+import { PlaygroundModule } from "../modules/playground.js";
+import { PresetsModule } from "../modules/presets.js";
+import { PromptsModule } from "../modules/prompts.js";
+import { StoreModule } from "../modules/store.js";
+import { TracesModule } from "../modules/traces.js";
+import { UsageModule } from "../modules/usage.js";
+import { VectorStoresModule } from "../modules/vectorStores.js";
 
 // Re-export auth types
-export type { AgentOsClientOptions, AuthProvider } from "./auth.js";
 export { isApiTokenAuth, isJwtAuth } from "./auth.js";
+export type { AgentOsClientOptions, AuthProvider } from "./auth.js";
 
 export class AgentOsClient {
     private readonly _client: RawClient;
@@ -126,6 +127,7 @@ export class AgentOsClient {
 
     public readonly apiTokens: ApiTokensModule;
     public readonly memberships: MembershipsModule;
+    public readonly presets: PresetsModule;
 
 
 
@@ -192,6 +194,7 @@ export class AgentOsClient {
 
         this.apiTokens = new ApiTokensModule(this._client);
         this.memberships = new MembershipsModule(this._client);
+        this.presets = new PresetsModule(this._client, getHeaders);
 
     }
 

package/src/client/HttpRequestBuilder.ts

@@ -0,0 +1,102 @@
+/**
+ * HttpRequestBuilder — Single source of truth for headers
+ * 
+ * All header generation flows through this builder.
+ * raw.ts should NOT generate headers directly.
+ * 
+ * Headers generated:
+ * - X-Request-Id: Per-request, always new (crypto.randomUUID)
+ * - X-Correlation-Id: Per-flow, immutable within flow
+ * - Authorization: Bearer token
+ * - X-Workspace-Id: Workspace binding (from context)
+ * - X-Idempotency-Key: Opt-in for POST requests
+ * - User-Agent: SDK version + runtime info
+ * 
+ * @see sdk-upgrade.md Section 1.3
+ */
+
+import type { OperationContext } from "./OperationContext.js";
+import { sanitizeHeader, sanitizeHeaders } from "./sanitize.js";
+
+// SDK version injected at build time, fallback for local dev
+declare const __SDK_VERSION__: string | undefined;
+const SDK_VERSION = typeof __SDK_VERSION__ !== "undefined" ? __SDK_VERSION__ : "0.7.12-dev";
+
+/**
+ * Options for building request headers
+ */
+export interface HttpRequestBuilderOptions {
+    /** Bearer token for Authorization header */
+    token?: string;
+    /** Operation context with correlationId and workspaceId */
+    context?: OperationContext;
+    /** Idempotency key for POST requests */
+    idempotencyKey?: string;
+    /** If true, throws if correlationId is missing */
+    requireFlow?: boolean;
+}
+
+/**
+ * Build headers for HTTP requests.
+ * This is the SINGLE SOURCE OF TRUTH for header generation.
+ */
+export class HttpRequestBuilder {
+    /**
+     * Build headers from options.
+     * 
+     * @throws Error if requireFlow is true and correlationId is missing
+     */
+    build(opts: HttpRequestBuilderOptions): Record<string, string> {
+        const headers: Record<string, string> = {};
+
+        // I2: X-Request-Id always exists (per request)
+        headers["X-Request-Id"] = crypto.randomUUID();
+
+        // User-Agent: Dynamic SDK version
+        headers["User-Agent"] = this.buildUserAgent();
+
+        // I3: X-Correlation-Id is per flow
+        if (opts.requireFlow && !opts.context?.correlationId) {
+            throw new Error("X-Correlation-Id required for flow-scoped operations");
+        }
+        if (opts.context?.correlationId) {
+            headers["X-Correlation-Id"] = opts.context.correlationId;
+        }
+
+        // Authorization
+        if (opts.token) {
+            headers["Authorization"] = `Bearer ${opts.token}`;
+        }
+
+        // X-Workspace-Id from context
+        if (opts.context?.workspaceId) {
+            headers["X-Workspace-Id"] = opts.context.workspaceId;
+        }
+
+        // I7: Idempotency is opt-in
+        if (opts.idempotencyKey) {
+            headers["X-Idempotency-Key"] = sanitizeHeader(opts.idempotencyKey);
+        }
+
+        return sanitizeHeaders(headers);
+    }
+
+    /**
+     * Build User-Agent string with SDK version and runtime info
+     */
+    private buildUserAgent(): string {
+        // Node.js environment
+        if (typeof process !== "undefined" && process.version) {
+            return `agent-os-sdk/${SDK_VERSION} (node/${process.version})`;
+        }
+        // Browser environment
+        if (typeof navigator !== "undefined" && navigator.userAgent) {
+            return `agent-os-sdk/${SDK_VERSION} (browser)`;
+        }
+        // Unknown environment
+        return `agent-os-sdk/${SDK_VERSION}`;
+    }
+}
+
+// Singleton instance for convenience
+export const httpRequestBuilder = new HttpRequestBuilder();

package/src/client/OperationContext.ts

@@ -0,0 +1,22 @@
+/**
+ * OperationContext — Immutable flow context
+ * 
+ * Created at the start of a logical flow and never mutates.
+ * 
+ * - correlationId: Tracks the entire logical operation (immutable per flow)
+ * - workspaceId: Optional workspace binding
+ * 
+ * @see sdk-upgrade.md Section 1.1
+ */
+
+export type OperationContext = Readonly<{
+    correlationId: string;
+    workspaceId?: string;
+}>;
+
+export function createOperationContext(input: {
+    correlationId: string;
+    workspaceId?: string;
+}): OperationContext {
+    return Object.freeze({ ...input });
+}

package/src/client/OperationContextProvider.ts

@@ -0,0 +1,89 @@
+/**
+ * OperationContextProvider — Flow lifecycle management
+ * 
+ * Provider defines the lifecycle of a flow context.
+ * Implementations can use AsyncLocalStorage or manual context passing.
+ * 
+ * @see sdk-upgrade.md Section 1.2
+ */
+
+import type { OperationContext } from "./OperationContext.js";
+
+/**
+ * Interface for context providers
+ */
+export interface OperationContextProvider {
+    get(): OperationContext | undefined;
+}
+
+/**
+ * Default provider that always returns undefined.
+ * Used when no flow context is established.
+ */
+export class DefaultContextProvider implements OperationContextProvider {
+    get(): OperationContext | undefined {
+        return undefined;
+    }
+}
+
+/**
+ * AsyncLocalStorage-based provider for Node.js environments.
+ * Automatically propagates context through async call chains.
+ * 
+ * Note: This class requires Node.js async_hooks module.
+ * Import and use only in Node.js environments.
+ */
+export class AsyncLocalStorageContextProvider implements OperationContextProvider {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private readonly storage: any;
+
+    constructor() {
+        // Dynamic import to avoid browser errors
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const asyncHooks = require("async_hooks");
+            this.storage = new asyncHooks.AsyncLocalStorage();
+        } catch {
+            throw new Error("AsyncLocalStorage requires Node.js environment");
+        }
+    }
+
+    get(): OperationContext | undefined {
+        return this.storage?.getStore();
+    }
+
+    /**
+     * Run a function within a context.
+     * The context is automatically available to all async operations within.
+     */
+    run<T>(context: OperationContext, fn: () => T): T {
+        return this.storage.run(context, fn);
+    }
+
+    /**
+     * Run an async function within a context.
+     */
+    runAsync<T>(context: OperationContext, fn: () => Promise<T>): Promise<T> {
+        return this.storage.run(context, fn);
+    }
+}
+
+/**
+ * Manual provider for environments without AsyncLocalStorage.
+ * Context must be explicitly set and cleared.
+ */
+export class ManualContextProvider implements OperationContextProvider {
+    private context: OperationContext | undefined;
+
+    get(): OperationContext | undefined {
+        return this.context;
+    }
+
+    set(context: OperationContext): void {
+        this.context = context;
+    }
+
+    clear(): void {
+        this.context = undefined;
+    }
+}

package/src/client/raw.ts

@@ -7,6 +7,8 @@
 
 import createClient, { type Client } from "openapi-fetch";
 import type { components, paths } from "../generated/openapi.js";
+import { httpRequestBuilder } from "./HttpRequestBuilder.js";
+import type { OperationContext } from "./OperationContext.js";
 
 // Re-export types for external use
 export type { components, paths };
@@ -111,6 +113,12 @@ export function createRawClient(options: ClientOptions) {
             retry?: boolean;
             /** Override timeout for this request */
             timeoutMs?: number;
+            /** Operation context for flow tracing */
+            context?: OperationContext;
+            /** Idempotency key for POST requests */
+            idempotencyKey?: string;
+            /** Require correlation ID (throws if missing) */
+            requireFlow?: boolean;
         }
     ): Promise<APIResponse<T>> {
         // Replace path params
@@ -152,15 +160,18 @@ export function createRawClient(options: ClientOptions) {
             headers["Content-Type"] = "application/json";
         }
 
-        // Detect idempotency from header or body
-        const hasIdempotencyKey = Boolean(
-            headers["Idempotency-Key"] ||
-            headers["idempotency-key"] ||
-            (opts?.body && typeof opts.body === "object" && (opts.body as Record<string, unknown>).idempotency_key)
-        );
+        // Build standard headers via HttpRequestBuilder (single source of truth)
+        const builderHeaders = httpRequestBuilder.build({
+            context: opts?.context,
+            idempotencyKey: opts?.idempotencyKey,
+            requireFlow: opts?.requireFlow,
+        });
+
+        // Merge builder headers (X-Request-Id, X-Correlation-Id, X-Idempotency-Key, User-Agent)
+        Object.assign(headers, builderHeaders);
 
-        // Generate client request ID for tracing
-        const clientRequestId = `sdk_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+        // Use X-Request-Id from builder as client request ID
+        const clientRequestId = headers["X-Request-Id"];
 
         // Call onRequest hook
         const startTime = Date.now();

package/src/client/sanitize.ts

@@ -0,0 +1,31 @@
+/**
+ * Header Sanitization — Security layer for HTTP headers
+ * 
+ * Removes control characters and enforces size limits.
+ * 
+ * @see sdk-upgrade.md Section 1.4
+ */
+
+const MAX_LEN = 1024;
+
+/**
+ * Sanitize a single header value.
+ * - Removes control characters (0x00-0x1F, 0x7F)
+ * - Truncates to MAX_LEN
+ */
+export function sanitizeHeader(v: string): string {
+    return v.replace(/[\u0000-\u001F\u007F]/g, "").slice(0, MAX_LEN);
+}
+
+/**
+ * Sanitize all header values in a record.
+ * Mutates in place for performance.
+ */
+export function sanitizeHeaders(h: Record<string, string>): Record<string, string> {
+    for (const k in h) {
+        if (Object.prototype.hasOwnProperty.call(h, k) && h[k] !== undefined) {
+            h[k] = sanitizeHeader(h[k]);
+        }
+    }
+    return h;
+}

package/src/index.ts

@@ -63,6 +63,21 @@ export {
     isRetryableError,
 } from "./errors/index.js";
 
+// ============================================================
+// Auth Hardening (Pedra Sólida)
+// ============================================================
+
+export type { OperationContext } from "./client/OperationContext.js";
+export { createOperationContext } from "./client/OperationContext.js";
+export type { OperationContextProvider } from "./client/OperationContextProvider.js";
+export {
+    DefaultContextProvider,
+    AsyncLocalStorageContextProvider,
+    ManualContextProvider,
+} from "./client/OperationContextProvider.js";
+export { HttpRequestBuilder, httpRequestBuilder } from "./client/HttpRequestBuilder.js";
+export { sanitizeHeader, sanitizeHeaders } from "./client/sanitize.js";
+
 // ============================================================
 // Utilities
 // ============================================================

package/src/modules/agents.ts

@@ -20,12 +20,17 @@ type AgentBundleSchema = components["schemas"]["AgentExportBundle"];
 export interface Agent {
     id: string;
     name: string;
-    description?: string;
     workspace_id: string;
     tenant_id: string;
     created_at: string;
     updated_at: string;
     live_bundle_id?: string | null;
+    // Dashboard fields (P1 fix)
+    status?: "live" | "draft";
+    has_draft?: boolean;
+    last_run_id?: string | null;
+    last_run_status?: string | null;
+    last_run_at?: string | null;
 }
 
 export interface AgentBundle extends AgentBundleSchema { }
@@ -87,35 +92,44 @@ export class AgentsModule {
 
     /**
      * Create a new agent.
+     * Backend only accepts `name` per CreateAgentRequest DTO.
      * @example
      * ```ts
-     * const { data: agent } = await client.agents.create({
-     *   name: "My Agent",
-     *   description: "Does cool stuff"
+     * const { data: agent } = await client.agents.create({ name: "My Agent" });
+     * 
+     * // With idempotency (safe to retry)
+     * const { data: agent } = await client.agents.create({ 
+     *   name: "My Agent", 
+     *   idempotency_key: "unique-key" 
      * });
      * ```
      */
     async create(body: {
         name: string;
-        description?: string;
-        graph_json?: unknown;
+        /** Idempotency key for safe retries. When set, duplicate requests with the same key return 409 Conflict. */
+        idempotency_key?: string;
     }): Promise<APIResponse<Agent>> {
+        const headers: Record<string, string> = { ...this.headers() };
+        if (body.idempotency_key) {
+            headers["X-Idempotency-Key"] = body.idempotency_key;
+        }
+
         return this.client.POST<Agent>("/v1/api/agents", {
-            body,
-            headers: this.headers(),
+            body: { name: body.name },
+            headers,
         });
     }
 
     /**
      * Update an existing agent.
+     * Uses PATCH per backend AgentsController.
      */
     async update(agentId: string, body: {
         name?: string;
-        description?: string;
         live_bundle_id?: string;
     }): Promise<APIResponse<Agent>> {
-        return this.client.PUT<Agent>("/v1/api/agents/{agentId}", {
-            params: { path: { agentId } },
+        return this.client.PATCH<Agent>("/v1/api/agents/{id}", {
+            params: { path: { id: agentId } },
             body,
             headers: this.headers(),
         });
@@ -184,14 +198,30 @@ export class AgentsModule {
      * Publish a new version (bundle) of the agent.
      * @param agentId The agent UUID
      * @param graph_spec The graph specification to publish
-     * @param options Optional settings: version_label for tagging, set_as_live to make this the active version
+     * @param options Optional settings: version_label for tagging, set_as_live to make this the active version, idempotency_key for safe retries
      * @returns Bundle response with version details
+     * @example
+     * ```ts
+     * const { data: bundle } = await client.agents.publish(agentId, graphSpec, {
+     *   idempotency_key: "publish-unique-key"
+     * });
+     * ```
      */
     async publish(
         agentId: string,
         graph_spec: Record<string, unknown>,
-        options?: { version_label?: string | null; set_as_live?: boolean }
+        options?: {
+            version_label?: string | null;
+            set_as_live?: boolean;
+            /** Idempotency key for safe retries */
+            idempotency_key?: string;
+        }
     ): Promise<APIResponse<components["schemas"]["BundleResponse"]>> {
+        const headers: Record<string, string> = { ...this.headers() };
+        if (options?.idempotency_key) {
+            headers["X-Idempotency-Key"] = options.idempotency_key;
+        }
+
         return this.client.POST<components["schemas"]["BundleResponse"]>("/v1/api/agents/{id}/publish", {
             params: { path: { id: agentId } },
             body: {
@@ -199,7 +229,7 @@ export class AgentsModule {
                 version_label: options?.version_label ?? null,
                 set_as_live: options?.set_as_live ?? true
             },
-            headers: this.headers()
+            headers
         });
     }
 

package/src/modules/credentials.ts

@@ -99,6 +99,7 @@ export class CredentialsModule {
 
     /**
      * Update a credential.
+     * Uses PATCH per backend CredentialsController.
      */
     async update(credentialId: string, body: {
         name?: string;
@@ -106,7 +107,7 @@ export class CredentialsModule {
         status?: string;
         sharing_mode?: string;
     }): Promise<APIResponse<Credential>> {
-        return this.client.PUT<Credential>("/v1/api/credentials/{id}", {
+        return this.client.PATCH<Credential>("/v1/api/credentials/{id}", {
             params: { path: { id: credentialId } },
             body,
             headers: this.headers(),

package/src/modules/crons.ts

@@ -79,13 +79,14 @@ export class CronsModule {
 
     /**
      * Update a cron job.
+     * Uses PATCH per backend CronsController.
      */
     async update(cronId: string, body: {
         schedule?: string;
         enabled?: boolean;
         input?: unknown;
     }): Promise<APIResponse<CronJob>> {
-        return this.client.PUT<CronJob>("/v1/api/crons/{id}", {
+        return this.client.PATCH<CronJob>("/v1/api/crons/{id}", {
             params: { path: { id: cronId } },
             body,
             headers: this.headers(),