@agent-os-sdk/client 0.1.0

package/src/index.ts

@@ -0,0 +1,161 @@
+/**
+ * Agent OS SDK - Fully Typed
+ * 
+ * Internal typed SDK for Agent OS platform.
+ * All API calls are fully typed from OpenAPI specification.
+ * 
+ * @example
+ * ```ts
+ * import { AgentOsClient, unwrap } from "@agent-os/sdk";
+ * 
+ * const api = new AgentOsClient({
+ *   baseUrl: import.meta.env.VITE_API_URL,
+ *   tenantId: auth.tenantId,
+ *   workspaceId: auth.workspaceId,
+ *   token: auth.token,
+ * });
+ * 
+ * // Style 1: Handle response manually
+ * const { data, error } = await api.agents.list();
+ * if (data) {
+ *   data.items.forEach(agent => console.log(agent.name));
+ * }
+ * 
+ * // Style 2: Unwrap (throws on error, returns data directly)
+ * const agents = await unwrap(api.agents.list());
+ * agents.items.forEach(agent => console.log(agent.name));
+ * 
+ * // Streaming
+ * for await (const event of api.runs.createAndStream({
+ *   agent_id: "...",
+ *   input: { message: "Hello" },
+ * })) {
+ *   console.log(event);
+ * }
+ * ```
+ */
+
+// ============================================================================
+// Main Client
+// ============================================================================
+export { AgentOsClient, type AgentOsClientOptions } from "./client/AgentOsClient.js";
+
+// ============================================================================
+// Helpers & Utilities
+// ============================================================================
+export {
+    unwrap,
+    toResult,
+    SDKError,
+    type PaginationParams,
+    type PaginatedResponse,
+    type Result,
+    type Unwrapped,
+} from "./client/helpers.js";
+
+// ============================================================================
+// Raw Client & Core Types
+// ============================================================================
+export {
+    createRawClient,
+    createTypedClient,
+    type RawClient,
+    type TypedClient,
+    type ClientOptions,
+    type APIResponse,
+} from "./client/raw.js";
+
+// Export OpenAPI types
+export type { paths, components } from "./client/raw.js";
+
+// ============================================================================
+// Module Classes
+// ============================================================================
+
+// Core modules
+export { AgentsModule, type Agent, type AgentVersion, type AgentListResponse, type AgentGraphResponse } from "./modules/agents.js";
+export { RunsModule, type Run, type RunEvent, type RunListResponse, type RunEventsResponse, type CreateRunResponse } from "./modules/runs.js";
+export { ThreadsModule, type Thread, type ThreadState, type ThreadMessage, type ThreadRun, type ThreadListResponse, type ThreadMessagesResponse } from "./modules/threads.js";
+export { ToolsModule, type Tool, type ToolListResponse } from "./modules/tools.js";
+export { KnowledgeModule, type KnowledgeDataset, type KnowledgeSearchResponse } from "./modules/knowledge.js";
+export { TriggersModule, type Trigger, type TriggerListResponse } from "./modules/triggers.js";
+export { CredentialsModule, type Credential, type CredentialListResponse, type CredentialType } from "./modules/credentials.js";
+export { BuilderModule, type BuilderChatRequest, type BuilderChatResponse, type BuilderStreamEvent, type GraphUpdateAction } from "./modules/builder.js";
+export { MembersModule, type Member, type MemberListResponse } from "./modules/members.js";
+export { TenantsModule, type Tenant } from "./modules/tenants.js";
+export { WorkspacesModule, type Workspace, type WorkspaceListResponse } from "./modules/workspaces.js";
+
+// Platform modules
+export { PromptsModule, type Prompt, type PromptVersion, type PromptListResponse } from "./modules/prompts.js";
+export { TracesModule, type Trace, type Span, type TraceListResponse, type SpanData, type FeedbackRequest } from "./modules/traces.js";
+export { FilesModule, type StoredFile, type FileListResponse, type PresignedUpload } from "./modules/files.js";
+export { VectorStoresModule, type VectorStore, type VectorStoreListResponse, type VectorQueryResult } from "./modules/vectorStores.js";
+export { EvaluationModule, type EvalDataset, type Experiment, type ExampleData } from "./modules/evaluation.js";
+export { CheckpointsModule, type Checkpoint, type CheckpointsResponse } from "./modules/checkpoints.js";
+export { PlaygroundModule, type PlaygroundSession } from "./modules/playground.js";
+export { CronsModule, type CronJob, type CronJobListResponse } from "./modules/crons.js";
+export { DlqModule, type DlqMessage, type DlqListResponse } from "./modules/dlq.js";
+export { StoreModule, type StoreValue } from "./modules/store.js";
+export { AuditModule, type AuditLogEntry, type AuditListResponse } from "./modules/audit.js";
+export { UsageModule, type UsageResponse, type UsageQuota } from "./modules/usage.js";
+export { McpModule, type McpServer } from "./modules/mcp.js";
+export { A2aModule, type JsonRpcRequest, type JsonRpcResponse, type A2aAgentCard } from "./modules/a2a.js";
+export { MeModule, type MeResponse } from "./modules/me.js";
+export { InfoModule, type ServerInfo } from "./modules/info.js";
+export { MetricsModule, type MetricsResponse } from "./modules/metrics.js";
+export { GraphsModule, type GraphValidationResult, type GraphIntrospectionResult } from "./modules/graphs.js";
+
+// ============================================================================
+// SSE Streaming
+// ============================================================================
+export { streamSSE, type SSEEvent, type SSEOptions, type RunStreamEvent } from "./sse/client.js";
+
+// ============================================================================
+// Convenience Type Re-exports
+// ============================================================================
+export type {
+    // Agent types
+    Agent as AgentSchema,
+    CreateAgentRequest,
+    UpdateAgentRequest,
+    AgentBundle,
+    CreateAgentVersionRequest,
+    // Run types
+    RunResponse,
+    RunDetailResponse,
+    WaitRunResponse,
+    BatchRunResponse,
+    CancelRunResponse,
+    ReplayRequest,
+    // Thread types
+    ThreadRequest,
+    ThreadSearchRequest,
+    AddMessageRequest,
+    // Checkpoint types
+    CheckpointDetail,
+    CheckpointListResponse,
+    // Credential types
+    CreateCredentialRequest,
+    UpdateCredentialRequest,
+    // Cron types
+    CreateCronJobRequest,
+    UpdateCronJobRequest,
+    // Member types
+    InviteMemberRequest,
+    UpdateMemberRequest,
+    // Prompt types
+    CreatePromptRequest,
+    CreatePromptVersionRequest,
+    // File types
+    CreatePresignedUploadRequest,
+    PresignedUploadResponse,
+    // Vector Store types
+    VectorStoreResponse,
+    VectorQueryRequest,
+    VectorQueryResponse,
+    // Evaluation types
+    CreateDatasetRequest,
+    CreateExperimentRequest,
+    // Error types
+    ProblemDetails,
+} from "./client/raw.js";

package/src/modules/a2a.ts

@@ -0,0 +1,64 @@
+/**
+ * A2A Module - Fully Typed (Agent-to-Agent Protocol)
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+    id?: string | number;
+}
+
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    id?: string | number;
+}
+
+export interface A2aAgentCard {
+    agent_id: string;
+    name: string;
+    description?: string;
+    capabilities?: string[];
+    endpoint: string;
+}
+
+export class A2aModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /**
+     * Send a JSON-RPC request to an agent.
+     */
+    async call(request: JsonRpcRequest): Promise<APIResponse<JsonRpcResponse>> {
+        return this.client.POST<JsonRpcResponse>("/v1/api/a2a", {
+            body: request,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get agent card (discovery).
+     */
+    async getAgentCard(agentId: string): Promise<APIResponse<A2aAgentCard>> {
+        return this.client.GET<A2aAgentCard>("/v1/api/a2a/agents/{id}/card", {
+            params: { path: { id: agentId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * List available A2A agents.
+     */
+    async listAgents(): Promise<APIResponse<{ items: A2aAgentCard[]; total: number }>> {
+        return this.client.GET<{ items: A2aAgentCard[]; total: number }>("/v1/api/a2a/agents", {
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/agents.ts

@@ -0,0 +1,229 @@
+/**
+ * Agents Module - Fully Typed
+ * 
+ * Naming conventions:
+ * - get* for singular items: getAgent(id)
+ * - list* for collections: listAgents()
+ * - create*, update*, delete* for mutations
+ */
+
+import type { RawClient, APIResponse, components } from "../client/raw.js";
+import type { PaginationParams, PaginatedResponse } from "../client/helpers.js";
+
+// Type aliases for this module
+type AgentSchema = components["schemas"]["AgentBundleAgent"];
+type AgentBundle = components["schemas"]["AgentBundle"];
+type AgentVersionSchema = components["schemas"]["AgentBundleVersion"];
+
+// Response types
+export interface Agent {
+    id: string;
+    name: string;
+    description?: string;
+    workspace_id: string;
+    tenant_id: string;
+    created_at: string;
+    updated_at: string;
+    live_version_id?: string | null;
+}
+
+export interface AgentVersion {
+    id: string;
+    agent_id: string;
+    version_tag: string;
+    artifact_uri?: string;
+    artifact_hash?: string;
+    format?: string;
+    graph_spec?: unknown;
+    created_at: string;
+}
+
+export interface AgentGraphResponse {
+    mermaid?: string;
+    json?: unknown;
+}
+
+export interface GraphValidationResponse {
+    valid: boolean;
+    errors?: string[];
+    warnings?: string[];
+}
+
+export type AgentListResponse = PaginatedResponse<Agent>;
+export type AgentVersionListResponse = PaginatedResponse<AgentVersion>;
+
+export class AgentsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    // ======================== CRUD ========================
+
+    /**
+     * List all agents in the workspace.
+     * @example
+     * ```ts
+     * const { data } = await client.agents.list({ limit: 10 });
+     * data?.items.forEach(agent => console.log(agent.name));
+     * ```
+     */
+    async list(params?: PaginationParams & {
+        workspace_id?: string;
+    }): Promise<APIResponse<AgentListResponse>> {
+        return this.client.GET<AgentListResponse>("/v1/api/agents", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a single agent by ID.
+     * @example
+     * ```ts
+     * const { data: agent } = await client.agents.get("agent-uuid");
+     * ```
+     */
+    async get(agentId: string): Promise<APIResponse<Agent>> {
+        return this.client.GET<Agent>("/v1/api/agents/{agentId}", {
+            params: { path: { agentId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Create a new agent.
+     * @example
+     * ```ts
+     * const { data: agent } = await client.agents.create({
+     *   name: "My Agent",
+     *   description: "Does cool stuff"
+     * });
+     * ```
+     */
+    async create(body: {
+        name: string;
+        description?: string;
+        graph_json?: unknown;
+    }): Promise<APIResponse<Agent>> {
+        return this.client.POST<Agent>("/v1/api/agents", {
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Update an existing agent.
+     */
+    async update(agentId: string, body: {
+        name?: string;
+        description?: string;
+        live_version_id?: string;
+    }): Promise<APIResponse<Agent>> {
+        return this.client.PUT<Agent>("/v1/api/agents/{agentId}", {
+            params: { path: { agentId } },
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Delete an agent.
+     */
+    async delete(agentId: string): Promise<APIResponse<void>> {
+        return this.client.DELETE<void>("/v1/api/agents/{agentId}", {
+            params: { path: { agentId } },
+            headers: this.headers(),
+        });
+    }
+
+    // ======================== Versions ========================
+
+    /**
+     * List all versions of an agent.
+     * @example
+     * ```ts
+     * const { data } = await client.agents.listVersions("agent-uuid");
+     * ```
+     */
+    async listVersions(agentId: string): Promise<APIResponse<AgentVersion[]>> {
+        return this.client.GET<AgentVersion[]>("/v1/api/agents/{agentId}/versions", {
+            params: { path: { agentId } },
+            headers: this.headers(),
+        });
+    }
+
+    /** Alias for listVersions (convenience) */
+    versions = (agentId: string) => this.listVersions(agentId);
+
+    /**
+     * Create a new version of an agent.
+     */
+    async createVersion(agentId: string, body: {
+        version_tag: string;
+        artifact_uri?: string;
+        artifact_hash?: string;
+        format?: string;
+        graph_spec?: unknown;
+    }): Promise<APIResponse<AgentVersion>> {
+        return this.client.POST<AgentVersion>("/v1/api/agents/{agentId}/versions", {
+            params: { path: { agentId } },
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a specific version of an agent.
+     */
+    async getVersion(agentId: string, versionId: string): Promise<APIResponse<AgentVersion>> {
+        return this.client.GET<AgentVersion>("/v1/api/agents/{agentId}/versions/{versionId}", {
+            params: { path: { agentId, versionId } },
+            headers: this.headers(),
+        });
+    }
+
+    // ======================== Graph ========================
+
+    /**
+     * Get the graph for an agent (Mermaid or JSON).
+     */
+    async getGraph(agentId: string, format?: "mermaid" | "json"): Promise<APIResponse<AgentGraphResponse>> {
+        return this.client.GET<AgentGraphResponse>("/v1/api/agents/{agentId}/graph", {
+            params: { path: { agentId }, query: { format } },
+            headers: this.headers(),
+        });
+    }
+
+    /** Alias for getGraph (convenience) */
+    graph = (agentId: string, format?: "mermaid" | "json") => this.getGraph(agentId, format);
+
+    /**
+     * Validate the graph configuration.
+     */
+    async validateGraph(agentId: string): Promise<APIResponse<GraphValidationResponse>> {
+        return this.client.POST<GraphValidationResponse>("/v1/api/agents/{agentId}/graph/validate", {
+            params: { path: { agentId } },
+            headers: this.headers(),
+        });
+    }
+
+    // ======================== Import/Export ========================
+
+    /**
+     * Export an agent with all its versions.
+     */
+    async export(agentId: string): Promise<APIResponse<AgentBundle>> {
+        return this.client.GET<AgentBundle>("/v1/api/agents/{id}/export", {
+            params: { path: { id: agentId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Import an agent bundle.
+     */
+    async import(bundle: AgentBundle): Promise<APIResponse<Agent>> {
+        return this.client.POST<Agent>("/v1/api/agents/import", {
+            body: bundle,
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/audit.ts

@@ -0,0 +1,74 @@
+/**
+ * Audit Module - Fully Typed
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+export interface AuditLogEntry {
+    id: string;
+    tenant_id: string;
+    workspace_id?: string;
+    actor: string;
+    actor_type: "user" | "system" | "api_token";
+    action: string;
+    resource: string;
+    resource_id?: string;
+    metadata?: Record<string, unknown>;
+    ip_address?: string;
+    user_agent?: string;
+    created_at: string;
+}
+
+export interface AuditListResponse {
+    items: AuditLogEntry[];
+    total: number;
+}
+
+export class AuditModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /**
+     * List audit log entries.
+     */
+    async list(params?: {
+        actor?: string;
+        action?: string;
+        resource?: string;
+        workspace_id?: string;
+        from?: string;
+        to?: string;
+        skip?: number;
+        take?: number;
+    }): Promise<APIResponse<AuditListResponse>> {
+        return this.client.GET<AuditListResponse>("/v1/api/audit", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a specific audit log entry.
+     */
+    async get(auditId: string): Promise<APIResponse<AuditLogEntry>> {
+        return this.client.GET<AuditLogEntry>("/v1/api/audit/{id}", {
+            params: { path: { id: auditId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Search audit logs by action pattern.
+     */
+    async search(params?: {
+        query?: string;
+        from?: string;
+        to?: string;
+        skip?: number;
+        take?: number;
+    }): Promise<APIResponse<AuditListResponse>> {
+        return this.client.GET<AuditListResponse>("/v1/api/audit/search", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/builder.ts

@@ -0,0 +1,166 @@
+/**
+ * Builder Module - Meta-Agent for Agent Building
+ * 
+ * Connects to the kernel's meta-agent for AI-assisted agent creation.
+ * Uses SSE streaming for real-time responses and graph updates.
+ */
+
+import { streamSSE, type SSEEvent, type SSEOptions } from "../sse/client.js";
+
+export type BuilderChatRequest = {
+    message: string;
+    current_graph_spec?: Record<string, unknown>;
+    thread_id?: string;
+};
+
+export type GraphUpdateAction = {
+    action: string;
+    node_name?: string;
+    node_type?: string;
+    properties?: Record<string, unknown>;
+    edge_from?: string;
+    edge_to?: string;
+};
+
+export type BuilderStreamEvent =
+    | { type: "message"; data: { text: string } }
+    | { type: "graph_update"; data: GraphUpdateAction }
+    | { type: "done"; data: { response: string; actions: GraphUpdateAction[]; thread_id: string } }
+    | { type: "error"; data: { error: string } };
+
+export type BuilderChatResponse = {
+    response: string;
+    actions: GraphUpdateAction[];
+    thread_id: string;
+};
+
+export class BuilderModule {
+    constructor(
+        private kernelBaseUrl: string,
+        private headers: () => Record<string, string>
+    ) { }
+
+    /**
+     * Stream chat with meta-agent (SSE).
+     * Returns async generator of events.
+     */
+    async *chat(
+        agentId: string,
+        request: BuilderChatRequest,
+        options?: SSEOptions
+    ): AsyncGenerator<BuilderStreamEvent> {
+        const url = `${this.kernelBaseUrl}/v1/internal/builder/${agentId}/chat`;
+
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+                ...this.headers(),
+            },
+            body: JSON.stringify(request),
+            signal: options?.signal,
+        });
+
+        if (!response.ok) {
+            throw new Error(`Builder chat failed: ${response.status}`);
+        }
+
+        if (!response.body) {
+            throw new Error("No response body");
+        }
+
+        options?.onOpen?.();
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+
+                let eventType = "message";
+                let eventData = "";
+
+                for (const line of lines) {
+                    if (line.startsWith("event:")) {
+                        eventType = line.slice(6).trim();
+                    } else if (line.startsWith("data:")) {
+                        eventData = line.slice(5).trim();
+                    } else if (line === "" && eventData) {
+                        try {
+                            const parsed = JSON.parse(eventData);
+                            yield { type: eventType, data: parsed } as BuilderStreamEvent;
+                        } catch {
+                            // Skip invalid JSON
+                        }
+                        eventData = "";
+                        eventType = "message";
+                    }
+                }
+            }
+        } finally {
+            reader.releaseLock();
+        }
+    }
+
+    /**
+     * Sync chat with meta-agent (no streaming).
+     */
+    async chatSync(
+        agentId: string,
+        request: BuilderChatRequest
+    ): Promise<BuilderChatResponse> {
+        const url = `${this.kernelBaseUrl}/v1/internal/builder/${agentId}/chat/sync`;
+
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...this.headers(),
+            },
+            body: JSON.stringify(request),
+        });
+
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Builder chat failed: ${response.status} - ${error}`);
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Convenience method: chat and collect all events.
+     */
+    async chatCollect(
+        agentId: string,
+        request: BuilderChatRequest
+    ): Promise<BuilderChatResponse> {
+        let fullResponse = "";
+        const allActions: GraphUpdateAction[] = [];
+        let threadId = request.thread_id ?? "";
+
+        for await (const event of this.chat(agentId, request)) {
+            if (event.type === "message") {
+                fullResponse += event.data.text;
+            } else if (event.type === "graph_update") {
+                allActions.push(event.data);
+            } else if (event.type === "done") {
+                threadId = event.data.thread_id;
+            }
+        }
+
+        return {
+            response: fullResponse,
+            actions: allActions,
+            thread_id: threadId,
+        };
+    }
+}