@agent-os-sdk/client 0.1.0 → 0.1.2

package/src/modules/artifacts.ts

@@ -0,0 +1,287 @@
+/**
+ * Artifacts Module - Output Management
+ * 
+ * // MOCK - This module contains mock implementations for future features
+ * 
+ * Manages artifacts as first-class outputs with integrity,
+ * lineage tracking, and signatures.
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ArtifactType = "file" | "image" | "document" | "code" | "data" | "other";
+
+export interface Artifact {
+    id: string;
+    name: string;
+    type: ArtifactType;
+    mime_type: string;
+    size_bytes: number;
+    sha256: string;
+    url?: string;
+    run_id?: string;
+    thread_id?: string;
+    metadata: Record<string, unknown>;
+    signed: boolean;
+    signature?: string;
+    created_at: string;
+    created_by: string;
+}
+
+export interface ArtifactLineage {
+    artifact_id: string;
+    source: LineageSource;
+    transformations: LineageTransformation[];
+    dependencies: string[];
+}
+
+export interface LineageSource {
+    type: "run" | "upload" | "tool" | "agent";
+    id: string;
+    name: string;
+    timestamp: string;
+}
+
+export interface LineageTransformation {
+    step: number;
+    operation: string;
+    run_id?: string;
+    tool_name?: string;
+    timestamp: string;
+}
+
+export interface ArtifactListResponse {
+    items: Artifact[];
+    total: number;
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export class ArtifactsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    // MOCK - Simulated list
+    /**
+     * List all artifacts.
+     */
+    async list(params?: {
+        run_id?: string;
+        thread_id?: string;
+        type?: ArtifactType;
+    }): Promise<APIResponse<ArtifactListResponse>> {
+        // MOCK - Returns simulated data
+        const mockArtifacts: ArtifactListResponse = {
+            items: [
+                {
+                    id: "artifact_1",
+                    name: "report.pdf",
+                    type: "document",
+                    mime_type: "application/pdf",
+                    size_bytes: 245000,
+                    sha256: "abc123def456...",
+                    url: "https://storage.example.com/artifacts/report.pdf",
+                    run_id: "run_123",
+                    thread_id: "thread_456",
+                    metadata: { pages: 12, author: "Agent Support" },
+                    signed: true,
+                    signature: "sig_abc123",
+                    created_at: new Date(Date.now() - 3600000).toISOString(),
+                    created_by: "agent_support",
+                },
+                {
+                    id: "artifact_2",
+                    name: "analysis.json",
+                    type: "data",
+                    mime_type: "application/json",
+                    size_bytes: 15000,
+                    sha256: "xyz789ghi012...",
+                    url: "https://storage.example.com/artifacts/analysis.json",
+                    run_id: "run_124",
+                    metadata: { records: 500 },
+                    signed: false,
+                    created_at: new Date(Date.now() - 7200000).toISOString(),
+                    created_by: "agent_analyzer",
+                },
+            ],
+            total: 2,
+        };
+        return { data: mockArtifacts, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated get
+    /**
+     * Get an artifact by ID.
+     */
+    async get(artifactId: string): Promise<APIResponse<Artifact>> {
+        // MOCK - Returns simulated data
+        const mockArtifact: Artifact = {
+            id: artifactId,
+            name: "report.pdf",
+            type: "document",
+            mime_type: "application/pdf",
+            size_bytes: 245000,
+            sha256: "abc123def456...",
+            url: "https://storage.example.com/artifacts/report.pdf",
+            run_id: "run_123",
+            metadata: { pages: 12 },
+            signed: true,
+            signature: "sig_abc123",
+            created_at: new Date(Date.now() - 3600000).toISOString(),
+            created_by: "agent_support",
+        };
+        return { data: mockArtifact, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated create
+    /**
+     * Create a new artifact reference.
+     */
+    async create(body: {
+        name: string;
+        type: ArtifactType;
+        mime_type: string;
+        size_bytes: number;
+        sha256: string;
+        run_id?: string;
+        thread_id?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<APIResponse<Artifact>> {
+        // MOCK - Returns simulated data
+        const mockArtifact: Artifact = {
+            id: `artifact_${Date.now()}`,
+            name: body.name,
+            type: body.type,
+            mime_type: body.mime_type,
+            size_bytes: body.size_bytes,
+            sha256: body.sha256,
+            run_id: body.run_id,
+            thread_id: body.thread_id,
+            metadata: body.metadata || {},
+            signed: false,
+            created_at: new Date().toISOString(),
+            created_by: "user_current",
+        };
+        return { data: mockArtifact, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated delete
+    /**
+     * Delete an artifact.
+     */
+    async delete(artifactId: string): Promise<APIResponse<void>> {
+        // MOCK - Returns success
+        return { data: undefined, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated sign
+    /**
+     * Sign an artifact for integrity verification.
+     */
+    async sign(artifactId: string): Promise<APIResponse<Artifact>> {
+        // MOCK - Returns simulated signed artifact
+        const mockArtifact: Artifact = {
+            id: artifactId,
+            name: "report.pdf",
+            type: "document",
+            mime_type: "application/pdf",
+            size_bytes: 245000,
+            sha256: "abc123def456...",
+            metadata: {},
+            signed: true,
+            signature: `sig_${Date.now()}`,
+            created_at: new Date(Date.now() - 3600000).toISOString(),
+            created_by: "agent_support",
+        };
+        return { data: mockArtifact, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated lineage
+    /**
+     * Get artifact lineage (provenance tracking).
+     */
+    async lineage(artifactId: string): Promise<APIResponse<ArtifactLineage>> {
+        // MOCK - Returns simulated lineage
+        const mockLineage: ArtifactLineage = {
+            artifact_id: artifactId,
+            source: {
+                type: "run",
+                id: "run_123",
+                name: "Support Agent Run",
+                timestamp: new Date(Date.now() - 3600000).toISOString(),
+            },
+            transformations: [
+                {
+                    step: 1,
+                    operation: "generate",
+                    run_id: "run_123",
+                    tool_name: "document_generator",
+                    timestamp: new Date(Date.now() - 3500000).toISOString(),
+                },
+                {
+                    step: 2,
+                    operation: "format",
+                    run_id: "run_123",
+                    tool_name: "pdf_formatter",
+                    timestamp: new Date(Date.now() - 3400000).toISOString(),
+                },
+            ],
+            dependencies: ["artifact_raw_data", "artifact_template"],
+        };
+        return { data: mockLineage, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated getForRun
+    /**
+     * Get all artifacts produced by a run.
+     */
+    async getForRun(runId: string): Promise<APIResponse<ArtifactListResponse>> {
+        // MOCK - Returns simulated data
+        const mockArtifacts: ArtifactListResponse = {
+            items: [
+                {
+                    id: "artifact_run_1",
+                    name: "output.json",
+                    type: "data",
+                    mime_type: "application/json",
+                    size_bytes: 5000,
+                    sha256: "run_output_hash",
+                    run_id: runId,
+                    metadata: {},
+                    signed: false,
+                    created_at: new Date().toISOString(),
+                    created_by: "agent",
+                },
+            ],
+            total: 1,
+        };
+        return { data: mockArtifacts, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated attachToThread
+    /**
+     * Attach an artifact to a thread.
+     */
+    async attachToThread(threadId: string, artifactId: string): Promise<APIResponse<Artifact>> {
+        // MOCK - Returns simulated data
+        const mockArtifact: Artifact = {
+            id: artifactId,
+            name: "attached_file.pdf",
+            type: "document",
+            mime_type: "application/pdf",
+            size_bytes: 100000,
+            sha256: "attached_hash",
+            thread_id: threadId,
+            metadata: {},
+            signed: false,
+            created_at: new Date().toISOString(),
+            created_by: "user",
+        };
+        return { data: mockArtifact, error: undefined, response: new Response() };
+    }
+}

package/src/modules/budgets.ts

@@ -0,0 +1,236 @@
+/**
+ * Budgets Module - Cost Control
+ * 
+ * // MOCK - This module contains mock implementations for future features
+ * 
+ * Provides budget management, cost estimation, and spending limits.
+ * Critical for CFO happiness and auto-protection.
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type BudgetPeriod = "hourly" | "daily" | "weekly" | "monthly" | "total";
+export type BudgetScope = "tenant" | "workspace" | "agent" | "environment";
+
+export interface Budget {
+    id: string;
+    name: string;
+    scope: BudgetScope;
+    scope_id: string;
+    period: BudgetPeriod;
+    limit_amount: number;
+    currency: string;
+    current_usage: number;
+    usage_percentage: number;
+    alert_thresholds: number[]; // e.g., [50, 80, 90]
+    hard_limit: boolean; // If true, blocks execution when exceeded
+    created_at: string;
+    updated_at: string;
+}
+
+export interface BudgetUsage {
+    budget_id: string;
+    period_start: string;
+    period_end: string;
+    total_cost: number;
+    breakdown: BudgetBreakdown[];
+}
+
+export interface BudgetBreakdown {
+    category: string;
+    amount: number;
+    percentage: number;
+    run_count: number;
+}
+
+export interface CostEstimate {
+    estimated_min: number;
+    estimated_max: number;
+    estimated_avg: number;
+    currency: string;
+    breakdown: {
+        input_tokens: number;
+        output_tokens: number;
+        tool_calls: number;
+        model_cost: number;
+    };
+    warnings: string[];
+}
+
+export interface BudgetListResponse {
+    items: Budget[];
+    total: number;
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export class BudgetsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    // MOCK - Simulated list
+    /**
+     * List all budgets.
+     */
+    async list(params?: { scope?: BudgetScope }): Promise<APIResponse<BudgetListResponse>> {
+        // MOCK - Returns simulated data
+        const mockBudgets: BudgetListResponse = {
+            items: [
+                {
+                    id: "budget_tenant",
+                    name: "Monthly Tenant Budget",
+                    scope: "tenant",
+                    scope_id: "tenant_123",
+                    period: "monthly",
+                    limit_amount: 5000,
+                    currency: "USD",
+                    current_usage: 1250.50,
+                    usage_percentage: 25.01,
+                    alert_thresholds: [50, 80, 90],
+                    hard_limit: false,
+                    created_at: new Date(Date.now() - 2592000000).toISOString(),
+                    updated_at: new Date().toISOString(),
+                },
+                {
+                    id: "budget_agent_1",
+                    name: "Agent Daily Budget",
+                    scope: "agent",
+                    scope_id: "agent_support",
+                    period: "daily",
+                    limit_amount: 50,
+                    currency: "USD",
+                    current_usage: 12.30,
+                    usage_percentage: 24.6,
+                    alert_thresholds: [80, 95],
+                    hard_limit: true,
+                    created_at: new Date(Date.now() - 86400000).toISOString(),
+                    updated_at: new Date().toISOString(),
+                },
+            ],
+            total: 2,
+        };
+        return { data: mockBudgets, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated get
+    /**
+     * Get a budget by ID.
+     */
+    async get(budgetId: string): Promise<APIResponse<Budget>> {
+        // MOCK - Returns simulated data
+        const mockBudget: Budget = {
+            id: budgetId,
+            name: "Monthly Tenant Budget",
+            scope: "tenant",
+            scope_id: "tenant_123",
+            period: "monthly",
+            limit_amount: 5000,
+            currency: "USD",
+            current_usage: 1250.50,
+            usage_percentage: 25.01,
+            alert_thresholds: [50, 80, 90],
+            hard_limit: false,
+            created_at: new Date(Date.now() - 2592000000).toISOString(),
+            updated_at: new Date().toISOString(),
+        };
+        return { data: mockBudget, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated set
+    /**
+     * Create or update a budget.
+     */
+    async set(body: {
+        name: string;
+        scope: BudgetScope;
+        scope_id: string;
+        period: BudgetPeriod;
+        limit_amount: number;
+        currency?: string;
+        alert_thresholds?: number[];
+        hard_limit?: boolean;
+    }): Promise<APIResponse<Budget>> {
+        // MOCK - Returns simulated data
+        const mockBudget: Budget = {
+            id: `budget_${Date.now()}`,
+            name: body.name,
+            scope: body.scope,
+            scope_id: body.scope_id,
+            period: body.period,
+            limit_amount: body.limit_amount,
+            currency: body.currency || "USD",
+            current_usage: 0,
+            usage_percentage: 0,
+            alert_thresholds: body.alert_thresholds || [80, 90],
+            hard_limit: body.hard_limit ?? false,
+            created_at: new Date().toISOString(),
+            updated_at: new Date().toISOString(),
+        };
+        return { data: mockBudget, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated getUsage
+    /**
+     * Get budget usage details.
+     */
+    async getUsage(budgetId: string): Promise<APIResponse<BudgetUsage>> {
+        // MOCK - Returns simulated data
+        const mockUsage: BudgetUsage = {
+            budget_id: budgetId,
+            period_start: new Date(Date.now() - 2592000000).toISOString(),
+            period_end: new Date().toISOString(),
+            total_cost: 1250.50,
+            breakdown: [
+                { category: "GPT-4", amount: 800.00, percentage: 63.97, run_count: 450 },
+                { category: "Claude", amount: 300.50, percentage: 24.03, run_count: 200 },
+                { category: "Embeddings", amount: 100.00, percentage: 8.00, run_count: 1000 },
+                { category: "Tools", amount: 50.00, percentage: 4.00, run_count: 300 },
+            ],
+        };
+        return { data: mockUsage, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated estimateCost
+    /**
+     * Estimate cost for a run before execution.
+     */
+    async estimateCost(params: {
+        agent_id: string;
+        input?: Record<string, unknown>;
+        max_iterations?: number;
+    }): Promise<APIResponse<CostEstimate>> {
+        // MOCK - Returns simulated estimate
+        const mockEstimate: CostEstimate = {
+            estimated_min: 0.05,
+            estimated_max: 0.25,
+            estimated_avg: 0.12,
+            currency: "USD",
+            breakdown: {
+                input_tokens: 2000,
+                output_tokens: 3000,
+                tool_calls: 5,
+                model_cost: 0.10,
+            },
+            warnings: [],
+        };
+        return { data: mockEstimate, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated setBudgetForRun
+    /**
+     * Set a hard budget cap for a specific run.
+     */
+    async setBudgetForRun(runId: string, limit: number): Promise<APIResponse<{ run_id: string; limit: number }>> {
+        // MOCK - Returns simulated data
+        return {
+            data: { run_id: runId, limit },
+            error: undefined,
+            response: new Response()
+        };
+    }
+}

package/src/modules/builder.ts

@@ -36,7 +36,7 @@ export type BuilderChatResponse = {
 
 export class BuilderModule {
     constructor(
-        private kernelBaseUrl: string,
+        private baseUrl: string,
         private headers: () => Record<string, string>
     ) { }
 
@@ -49,7 +49,7 @@ export class BuilderModule {
         request: BuilderChatRequest,
         options?: SSEOptions
     ): AsyncGenerator<BuilderStreamEvent> {
-        const url = `${this.kernelBaseUrl}/v1/internal/builder/${agentId}/chat`;
+        const url = `${this.baseUrl}/v1/internal/builder/${agentId}/chat`;
 
         const response = await fetch(url, {
             method: "POST",
@@ -117,7 +117,7 @@ export class BuilderModule {
         agentId: string,
         request: BuilderChatRequest
     ): Promise<BuilderChatResponse> {
-        const url = `${this.kernelBaseUrl}/v1/internal/builder/${agentId}/chat/sync`;
+        const url = `${this.baseUrl}/v1/internal/builder/${agentId}/chat/sync`;
 
         const response = await fetch(url, {
             method: "POST",