@agent-os-sdk/client 0.2.2 → 0.3.0

package/src/client/AgentOsClient.ts

@@ -2,7 +2,10 @@
  * Agent OS SDK - Main Client
  * 
  * Fully typed API client for Agent OS platform.
- * Supports both API Token (server) and JWT (browser) authentication.
+ * 
+ * Two authentication modes:
+ * - API Token (server-to-server): aosk_* tokens with embedded claims
+ * - JWT (browser): Supabase JWT + X-Workspace-Id header
  * 
  * @example
  * ```ts
@@ -17,8 +20,8 @@
  *   baseUrl: "https://api.agentos.io",
  *   auth: {
  *     type: "jwt",
- *     getToken: () => supabase.auth.getSession().then(s => s.data.session?.access_token),
- *     getWorkspaceId: () => localStorage.getItem("agentos.workspaceId")!
+ *     getToken: () => supabase.auth.getSession().then(s => s.data.session?.access_token ?? ""),
+ *     getWorkspaceId: () => localStorage.getItem("agentos.workspaceId") ?? ""
  *   }
  * });
  * ```
@@ -27,12 +30,9 @@
 import { createRawClient, type RawClient } from "./raw.js";
 import {
     type AgentOsClientOptions,
-    type AgentOsClientOptionsLegacy,
     type AuthProvider,
-    isNewAuthOptions,
     isApiTokenAuth,
     isJwtAuth,
-    isApiToken,
     isBrowser,
 } from "./auth.js";
 
@@ -48,7 +48,7 @@ import { MembersModule } from "../modules/members.js";
 import { TenantsModule } from "../modules/tenants.js";
 import { WorkspacesModule } from "../modules/workspaces.js";
 
-// New modules
+// Platform modules
 import { PromptsModule } from "../modules/prompts.js";
 import { TracesModule } from "../modules/traces.js";
 import { FilesModule } from "../modules/files.js";
@@ -68,7 +68,7 @@ import { InfoModule } from "../modules/info.js";
 import { MetricsModule } from "../modules/metrics.js";
 import { GraphsModule } from "../modules/graphs.js";
 
-// MOCK - Future modules (marked for replacement when backend is ready)
+// Future modules (mocked)
 import { HandoffModule } from "../modules/handoff.js";
 import { FlowsModule } from "../modules/flows.js";
 import { CapabilitiesModule } from "../modules/capabilities.js";
@@ -80,84 +80,49 @@ import { IncidentsModule } from "../modules/incidents.js";
 import { ArtifactsModule } from "../modules/artifacts.js";
 
 // Re-export auth types
-export type { AgentOsClientOptions, AgentOsClientOptionsLegacy, AuthProvider } from "./auth.js";
-export { isApiTokenAuth, isJwtAuth, isNewAuthOptions } from "./auth.js";
+export type { AgentOsClientOptions, AuthProvider } from "./auth.js";
+export { isApiTokenAuth, isJwtAuth } from "./auth.js";
 
 export class AgentOsClient {
     private readonly _client: RawClient;
     private readonly _baseUrl: string;
-    private readonly _auth: AuthProvider | null;
+    private readonly _auth: AuthProvider;
     private readonly _customHeaders: Record<string, string>;
 
-    // Legacy fields (for backwards compat)
-    private readonly _tenantId?: string;
-    private readonly _workspaceId?: string;
-    private readonly _token?: string;
-    private readonly _memberId?: string;
-
     // Core modules
-    /** Agents API: CRUD, versions, graph */
     readonly agents: AgentsModule;
-    /** Runs API: create, stream, cancel, resume, replay */
     readonly runs: RunsModule;
-    /** Threads API: conversations, state, messages */
     readonly threads: ThreadsModule;
-    /** Tools API: definitions, registry */
     readonly tools: ToolsModule;
-    /** Knowledge API: vector stores, RAG */
     readonly knowledge: KnowledgeModule;
-    /** Triggers API: webhooks, crons */
     readonly triggers: TriggersModule;
-    /** Credentials API: BYOK secrets */
     readonly credentials: CredentialsModule;
-    /** Builder API: Meta-agent for AI-assisted agent creation */
     readonly builder: BuilderModule;
-    /** Members API: Tenant member management */
     readonly members: MembersModule;
-    /** Tenants API: Tenant settings */
     readonly tenants: TenantsModule;
-    /** Workspaces API: Workspace management */
     readonly workspaces: WorkspacesModule;
 
-    // New modules
-    /** Prompts API: Prompt Hub CMS */
+    // Platform modules
     readonly prompts: PromptsModule;
-    /** Traces API: OTEL observability */
     readonly traces: TracesModule;
-    /** Files API: S3 file storage */
     readonly files: FilesModule;
-    /** VectorStores API: pgvector semantic search */
     readonly vectorStores: VectorStoresModule;
-    /** Evaluation API: Datasets & experiments */
     readonly evaluation: EvaluationModule;
-    /** Checkpoints API: Time-travel debugging */
     readonly checkpoints: CheckpointsModule;
-    /** Playground API: Ephemeral sandbox */
     readonly playground: PlaygroundModule;
-    /** Crons API: Cron job scheduling */
     readonly crons: CronsModule;
-    /** DLQ API: Dead letter queue */
     readonly dlq: DlqModule;
-    /** Store API: Key-value storage */
     readonly store: StoreModule;
-    /** Audit API: Audit logs */
     readonly audit: AuditModule;
-    /** Usage API: Quotas and usage */
     readonly usage: UsageModule;
-    /** MCP API: Model Context Protocol */
     readonly mcp: McpModule;
-    /** A2A API: Agent-to-Agent protocol */
     readonly a2a: A2aModule;
-    /** Me API: Current user identity */
     readonly me: MeModule;
-    /** Info API: Server information */
     readonly info: InfoModule;
-    /** Metrics API: Prometheus metrics */
     readonly metrics: MetricsModule;
-    /** Graphs API: Validation and introspection */
     readonly graphs: GraphsModule;
 
-    // MOCK - Future modules
+    // Future modules (mocked)
     readonly handoff: HandoffModule;
     readonly flows: FlowsModule;
     readonly capabilities: CapabilitiesModule;
@@ -168,7 +133,7 @@ export class AgentOsClient {
     readonly incidents: IncidentsModule;
     readonly artifacts: ArtifactsModule;
 
-    // Convenience Aliases
+    // Convenience aliases
     readonly experiments: {
         list: EvaluationModule["listExperiments"];
         get: EvaluationModule["getExperiment"];
@@ -181,46 +146,24 @@ export class AgentOsClient {
         create: (agentId: string, body: Parameters<AgentsModule["createVersion"]>[1]) => ReturnType<AgentsModule["createVersion"]>;
     };
 
-    constructor(options: AgentOsClientOptions | AgentOsClientOptionsLegacy) {
+    constructor(options: AgentOsClientOptions) {
         this._baseUrl = options.baseUrl;
+        this._auth = options.auth;
         this._customHeaders = options.headers ?? {};
 
-        // Detect auth mode
-        if (isNewAuthOptions(options)) {
-            // New auth provider mode
-            this._auth = options.auth;
-            this._validateAuth(options);
-        } else {
-            // Legacy mode - convert to new auth if possible
-            this._tenantId = options.tenantId;
-            this._workspaceId = options.workspaceId;
-            this._token = options.token;
-            this._memberId = options.memberId;
-
-            // Attempt to detect auth type from token
-            if (options.token && isApiToken(options.token)) {
-                // Token looks like API token - use as api_token
-                this._auth = { type: "api_token", apiKey: options.token };
-                console.warn(
-                    "[AgentOS SDK] Using legacy options with API token. " +
-                    "Consider migrating to: new AgentOsClient({ auth: { type: 'api_token', apiKey: '...' } })"
-                );
-            } else {
-                // Legacy JWT mode - keep using headers
-                this._auth = null;
-            }
-        }
+        // Validate auth configuration
+        this._validateAuth(options);
 
-        // Create raw HTTP client
+        // Create raw client with async header provider
         this._client = createRawClient({
             baseUrl: options.baseUrl,
-            headers: {}, // Headers resolved dynamically
+            headerProvider: () => this._resolveHeaders(),
         });
 
-        // Bound header getter
-        const getHeaders = () => this._getHeaders();
-        const getWorkspaceId = () => this._getWorkspaceIdSync();
-        const getTenantId = () => this._tenantId ?? "";
+        // Module header getter (sync fallback for backwards compat with module internals)
+        const getHeaders = () => this._customHeaders;
+        const getWorkspaceId = () => "";
+        const getTenantId = () => "";
 
         // Initialize core modules
         this.agents = new AgentsModule(this._client, getHeaders);
@@ -235,7 +178,7 @@ export class AgentOsClient {
         this.tenants = new TenantsModule(this._client, getHeaders);
         this.workspaces = new WorkspacesModule(this._client, getTenantId, getHeaders);
 
-        // Initialize new modules
+        // Initialize platform modules
         this.prompts = new PromptsModule(this._client, getHeaders);
         this.traces = new TracesModule(this._client, getHeaders);
         this.files = new FilesModule(this._client, getHeaders);
@@ -255,7 +198,7 @@ export class AgentOsClient {
         this.metrics = new MetricsModule(this._baseUrl, getHeaders);
         this.graphs = new GraphsModule(this._client, getHeaders);
 
-        // MOCK - Initialize future modules
+        // Initialize future modules (mocked)
         this.handoff = new HandoffModule(this._client, getHeaders);
         this.flows = new FlowsModule(this._client, getHeaders);
         this.capabilities = new CapabilitiesModule(this._client, getHeaders);
@@ -281,140 +224,79 @@ export class AgentOsClient {
     }
 
     /**
-     * Validate auth configuration
+     * Validate auth configuration at construction time
      */
     private _validateAuth(options: AgentOsClientOptions): void {
         const { auth, allowApiTokenInBrowser } = options;
 
-        // Browser guard for API tokens
+        // Browser security guard for API tokens
         if (isApiTokenAuth(auth) && isBrowser() && !allowApiTokenInBrowser) {
             throw new Error(
-                "[AgentOS SDK] API tokens should not be used in the browser. " +
-                "They may be exposed in network requests. " +
-                "Use JWT auth for browser clients, or set allowApiTokenInBrowser: true if you understand the risks."
+                "[AgentOS SDK] SECURITY: API tokens (aosk_*) are SERVER-SIDE only. " +
+                "Use JWT auth in the browser. Set allowApiTokenInBrowser: true only if you understand the risks."
             );
         }
     }
 
     /**
-     * Get headers for current request (sync version for modules)
+     * Resolve headers for each request (async)
+     * 
+     * SECURITY INVARIANTS:
+     * - JWT: Authorization + X-Workspace-Id (REQUIRED), NO X-Tenant-Id
+     * - API Token: Authorization only, NO X-Workspace-Id, NO X-Tenant-Id
      */
-    private _getHeaders(): Record<string, string> {
+    private async _resolveHeaders(): Promise<Record<string, string>> {
         const headers: Record<string, string> = {
             "Content-Type": "application/json",
             ...this._customHeaders,
         };
 
-        if (this._auth) {
-            // New auth mode
-            if (isApiTokenAuth(this._auth)) {
-                // API Token: Only Authorization header
-                const apiKey = typeof this._auth.apiKey === "function"
-                    ? "" // Will be resolved async
-                    : this._auth.apiKey;
-                if (apiKey) {
-                    headers["Authorization"] = `Bearer ${apiKey}`;
-                }
-                // NO X-Tenant-Id, NO X-Workspace-Id (backend resolves from claims)
-            } else if (isJwtAuth(this._auth)) {
-                // JWT: Authorization + X-Workspace-Id
-                // Note: For sync header getter, we use empty strings as placeholders
-                // The actual values are resolved in _getHeadersAsync
-                // This is a limitation of the current module architecture
-            }
-        } else {
-            // Legacy mode - use stored values
-            if (this._token) {
-                headers["Authorization"] = `Bearer ${this._token}`;
-            }
-            if (this._tenantId) {
-                headers["X-Tenant-Id"] = this._tenantId;
-            }
-            if (this._workspaceId) {
-                headers["X-Workspace-Id"] = this._workspaceId;
-            }
-            if (this._memberId) {
-                headers["X-Member-Id"] = this._memberId;
-            }
-        }
-
-        return headers;
-    }
-
-    /**
-     * Get headers for current request (async version - resolves auth functions)
-     */
-    async getHeadersAsync(): Promise<Record<string, string>> {
-        const headers: Record<string, string> = {
-            "Content-Type": "application/json",
-            ...this._customHeaders,
-        };
+        if (isApiTokenAuth(this._auth)) {
+            // API Token: Authorization header only
+            const apiKey = typeof this._auth.apiKey === "function"
+                ? await this._auth.apiKey()
+                : this._auth.apiKey;
 
-        if (this._auth) {
-            if (isApiTokenAuth(this._auth)) {
-                // API Token
-                const apiKey = typeof this._auth.apiKey === "function"
-                    ? await this._auth.apiKey()
-                    : this._auth.apiKey;
+            if (apiKey) {
                 headers["Authorization"] = `Bearer ${apiKey}`;
-                // NO X-Tenant-Id, NO X-Workspace-Id
-            } else if (isJwtAuth(this._auth)) {
-                // JWT
-                const [token, workspaceId] = await Promise.all([
-                    this._auth.getToken(),
-                    this._auth.getWorkspaceId(),
-                ]);
-
-                if (!token) {
-                    throw new Error("[AgentOS SDK] JWT token not available. User may not be authenticated.");
-                }
-                if (!workspaceId) {
-                    throw new Error("[AgentOS SDK] Workspace ID not available. Please select a workspace first.");
-                }
+            }
+            // NO X-Workspace-Id (embedded in token claims)
+            // NO X-Tenant-Id (embedded in token claims)
+
+        } else if (isJwtAuth(this._auth)) {
+            // JWT: Authorization + X-Workspace-Id
+            const [token, workspaceId] = await Promise.all([
+                Promise.resolve(this._auth.getToken()),
+                Promise.resolve(this._auth.getWorkspaceId()),
+            ]);
 
+            if (token) {
                 headers["Authorization"] = `Bearer ${token}`;
-                headers["X-Workspace-Id"] = workspaceId;
-                // NO X-Tenant-Id (backend derives from workspace membership)
-            }
-        } else {
-            // Legacy mode
-            if (this._token) {
-                headers["Authorization"] = `Bearer ${this._token}`;
-            }
-            if (this._tenantId) {
-                headers["X-Tenant-Id"] = this._tenantId;
             }
-            if (this._workspaceId) {
-                headers["X-Workspace-Id"] = this._workspaceId;
-            }
-            if (this._memberId) {
-                headers["X-Member-Id"] = this._memberId;
+
+            // CRITICAL: Workspace ID is REQUIRED for JWT auth
+            if (!workspaceId) {
+                throw new Error(
+                    "[AgentOS SDK] No active workspace selected. " +
+                    "Call getWorkspaceId() must return a valid workspace ID."
+                );
             }
+            headers["X-Workspace-Id"] = workspaceId;
+            // NO X-Tenant-Id (backend derives from workspace membership)
         }
 
         return headers;
     }
 
     /**
-     * Get workspace ID synchronously (for modules that need it)
+     * Get resolved headers (for debugging/testing)
      */
-    private _getWorkspaceIdSync(): string {
-        return this._workspaceId ?? "";
-    }
-
-    /** Current tenant ID (legacy) */
-    get tenantId(): string {
-        return this._tenantId ?? "";
-    }
-
-    /** Current workspace ID (legacy) */
-    get workspaceId(): string {
-        return this._workspaceId ?? "";
+    async getHeadersAsync(): Promise<Record<string, string>> {
+        return this._resolveHeaders();
     }
 
     /** Auth provider type */
-    get authType(): "api_token" | "jwt" | "legacy" {
-        if (!this._auth) return "legacy";
+    get authType(): "api_token" | "jwt" {
         return this._auth.type;
     }
 

package/src/client/auth.ts

@@ -1,8 +1,8 @@
 /**
  * Auth Provider Types for Agent OS SDK
  * 
- * Supports two modes:
- * - JWT (browser): Uses Supabase JWT + workspace header
+ * Two modes only:
+ * - JWT (browser): Uses Supabase JWT + X-Workspace-Id header
  * - API Token (server): Uses aosk_* token with embedded claims
  */
 
@@ -14,6 +14,9 @@
  * API Token authentication for server-to-server integrations.
  * Token format: aosk_live_* or aosk_test_*
  * 
+ * SECURITY: API tokens contain embedded workspace/tenant claims.
+ * The SDK sends ONLY Authorization header (no X-Workspace-Id, no X-Tenant-Id).
+ * 
  * @example
  * ```ts
  * const client = new AgentOsClient({
@@ -30,7 +33,11 @@ export type ApiTokenAuth = {
 
 /**
  * JWT authentication for browser/frontend clients.
- * Uses Supabase JWT with workspace header.
+ * Uses Supabase JWT with X-Workspace-Id header.
+ * 
+ * SECURITY: 
+ * - X-Workspace-Id is REQUIRED (throws if missing)
+ * - X-Tenant-Id is NEVER sent (backend derives from workspace membership)
  * 
  * @example
  * ```ts
@@ -48,12 +55,12 @@ export type JwtAuth = {
     type: "jwt"
     /** Function to get the JWT access token */
     getToken: () => string | Promise<string>
-    /** Function to get the current workspace ID */
+    /** Function to get the current workspace ID (REQUIRED) */
     getWorkspaceId: () => string | Promise<string>
 }
 
 /**
- * Auth provider union type
+ * Auth provider union type - only two modes supported
  */
 export type AuthProvider = ApiTokenAuth | JwtAuth
 
@@ -62,57 +69,27 @@ export type AuthProvider = ApiTokenAuth | JwtAuth
 // ============================================================================
 
 /**
- * New auth-aware options for AgentOsClient
+ * Options for AgentOsClient - auth is REQUIRED
  */
 export type AgentOsClientOptions = {
     /** Base URL of the Agent OS Control Plane */
     baseUrl: string
-    /** Authentication provider */
+    /** Authentication provider (REQUIRED) */
     auth: AuthProvider
     /** 
      * Allow API token in browser environment.
      * Default: false (throws error to prevent accidental exposure)
+     * Only set to true if you understand the security implications.
      */
     allowApiTokenInBrowser?: boolean
     /** Custom headers to add to all requests */
     headers?: Record<string, string>
 }
 
-/**
- * Legacy options (backwards compatibility)
- * @deprecated Use AgentOsClientOptions with auth provider instead
- */
-export type AgentOsClientOptionsLegacy = {
-    /** Base URL of the Agent OS API */
-    baseUrl: string
-    /** Tenant ID @deprecated */
-    tenantId: string
-    /** Workspace ID @deprecated */
-    workspaceId: string
-    /** Auth token @deprecated */
-    token?: string
-    /** Member ID @deprecated */
-    memberId?: string
-    /** Custom headers */
-    headers?: Record<string, string>
-}
-
 // ============================================================================
 // Type Guards
 // ============================================================================
 
-export function isNewAuthOptions(
-    opts: AgentOsClientOptions | AgentOsClientOptionsLegacy
-): opts is AgentOsClientOptions {
-    return "auth" in opts && opts.auth !== undefined
-}
-
-export function isLegacyOptions(
-    opts: AgentOsClientOptions | AgentOsClientOptionsLegacy
-): opts is AgentOsClientOptionsLegacy {
-    return "tenantId" in opts || "workspaceId" in opts
-}
-
 export function isApiTokenAuth(auth: AuthProvider): auth is ApiTokenAuth {
     return auth.type === "api_token"
 }

package/src/client/raw.ts

@@ -14,6 +14,7 @@ export type { paths, components };
 export type ClientOptions = {
     baseUrl: string;
     headers?: Record<string, string>;
+    headerProvider?: () => Promise<Record<string, string>>;
 };
 
 /**
@@ -52,7 +53,7 @@ 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 = {} } = options;
+    const { baseUrl, headers: defaultHeaders = {}, headerProvider } = options;
 
     async function request<T>(
         method: string,
@@ -88,8 +89,13 @@ export function createRawClient(options: ClientOptions) {
         }
 
         const fullUrl = `${baseUrl}${url}`;
+
+        // Resolve dynamic headers (e.g. auth)
+        const dynamicHeaders = headerProvider ? await headerProvider() : {};
+
         const headers: Record<string, string> = {
             ...defaultHeaders,
+            ...dynamicHeaders,
             ...opts?.headers,
         };
 

package/src/index.ts

@@ -38,7 +38,7 @@
 // ============================================================================
 // Main Client
 // ============================================================================
-export { AgentOsClient, type AgentOsClientOptions, type AgentOsClientOptionsLegacy, type AuthProvider } from "./client/AgentOsClient.js";
+export { AgentOsClient, type AgentOsClientOptions, type AuthProvider } from "./client/AgentOsClient.js";
 
 // Auth Provider Types
 export {
@@ -46,7 +46,6 @@ export {
     type JwtAuth,
     isApiTokenAuth,
     isJwtAuth,
-    isNewAuthOptions,
     isBrowser,
     isApiToken,
     isJwtToken,
@@ -122,7 +121,7 @@ export { HandoffModule, type HandoffOptions, type HandoffResult, type ForkOption
 export { FlowsModule, type Flow, type FlowStep, type FlowRun, type FlowVisualization, type FlowSimulationResult, type FlowStatus, type FlowListResponse } from "./modules/flows.js";
 export { CapabilitiesModule, type Capability, type CapabilityType, type CapabilityTest, type CapabilityMatrix } from "./modules/capabilities.js";
 export { PoliciesModule, type Policy, type PolicyScope, type PolicyEnforcement, type PolicyRule, type PolicyEvaluation, type PolicyEvaluationResult } from "./modules/policies.js";
-export { ApprovalsModule, type Approval, type ApprovalStatus, type ApprovalRequest, type ApprovalDecision, type ApprovalListResponse } from "./modules/approvals.js";
+export { ApprovalsModule, type Approval, type ApprovalStatus, type ApprovalDecision, type ApprovalListResponse, type ApprovalStatusResponse } from "./modules/approvals.js";
 export { BudgetsModule, type Budget, type BudgetPeriod, type BudgetScope, type BudgetResourceType, type BudgetUsage, type BudgetAlert, type BudgetBreakdownItem } from "./modules/budgets.js";
 export { DeploymentsModule, type Environment, type Deployment, type DeploymentStatus, type DeploymentConfig, type DeploymentHealth } from "./modules/deployments.js";
 export { IncidentsModule, type Incident, type IncidentSeverity, type IncidentStatus, type IncidentUpdate, type IncidentMetrics } from "./modules/incidents.js";