@agent-os-sdk/client 0.1.1 → 0.1.2

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",

package/src/modules/capabilities.ts

@@ -0,0 +1,176 @@
+/**
+ * Capabilities Module - Agent Permissions System
+ * 
+ * // MOCK - This module contains mock implementations for future features
+ * 
+ * Manages what agents/runs can do. Formal capability system
+ * that enables enterprise-grade governance.
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Capability {
+    id: string;
+    name: string;
+    description?: string;
+    type: "tool" | "network" | "file" | "mcp" | "token" | "custom";
+    config: CapabilityConfig;
+}
+
+export interface CapabilityConfig {
+    // Tool capabilities
+    tool_allowlist?: string[];
+    tool_denylist?: string[];
+    max_tool_calls?: number;
+
+    // Network capabilities
+    allowed_domains?: string[];
+    blocked_domains?: string[];
+    allow_egress?: boolean;
+
+    // File capabilities
+    file_read?: boolean;
+    file_write?: boolean;
+    allowed_paths?: string[];
+
+    // MCP capabilities
+    mcp_server_allowlist?: string[];
+
+    // Token/cost capabilities
+    max_tokens?: number;
+    max_input_tokens?: number;
+    max_output_tokens?: number;
+
+    // Streaming
+    streaming_allowed?: boolean;
+}
+
+export interface CapabilitySet {
+    agent_id?: string;
+    run_id?: string;
+    capabilities: Capability[];
+    inherited_from?: string;
+    effective_at: string;
+}
+
+export interface CapabilityOverride {
+    run_id: string;
+    overrides: Partial<CapabilityConfig>;
+    reason?: string;
+    applied_at: string;
+    applied_by: string;
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export class CapabilitiesModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    // MOCK - Simulated get for agent
+    /**
+     * Get capabilities for an agent.
+     */
+    async getForAgent(agentId: string): Promise<APIResponse<CapabilitySet>> {
+        // MOCK - Returns simulated data
+        const mockCaps: CapabilitySet = {
+            agent_id: agentId,
+            capabilities: [
+                {
+                    id: "cap_tools",
+                    name: "Tool Access",
+                    type: "tool",
+                    config: {
+                        tool_allowlist: ["web_search", "calculator", "file_read"],
+                        max_tool_calls: 50,
+                    },
+                },
+                {
+                    id: "cap_network",
+                    name: "Network Access",
+                    type: "network",
+                    config: {
+                        allow_egress: true,
+                        allowed_domains: ["*.google.com", "*.openai.com"],
+                    },
+                },
+                {
+                    id: "cap_tokens",
+                    name: "Token Limits",
+                    type: "token",
+                    config: {
+                        max_tokens: 100000,
+                        max_input_tokens: 50000,
+                        max_output_tokens: 50000,
+                    },
+                },
+            ],
+            effective_at: new Date().toISOString(),
+        };
+        return { data: mockCaps, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated set for agent
+    /**
+     * Set capabilities for an agent.
+     */
+    async setForAgent(agentId: string, capabilities: Capability[]): Promise<APIResponse<CapabilitySet>> {
+        // MOCK - Returns simulated data
+        const mockCaps: CapabilitySet = {
+            agent_id: agentId,
+            capabilities,
+            effective_at: new Date().toISOString(),
+        };
+        return { data: mockCaps, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated get for run
+    /**
+     * Get effective capabilities for a run.
+     */
+    async getForRun(runId: string): Promise<APIResponse<CapabilitySet>> {
+        // MOCK - Returns simulated data
+        const mockCaps: CapabilitySet = {
+            run_id: runId,
+            capabilities: [
+                {
+                    id: "cap_tools",
+                    name: "Tool Access",
+                    type: "tool",
+                    config: {
+                        tool_allowlist: ["web_search"],
+                        max_tool_calls: 10,
+                    },
+                },
+            ],
+            inherited_from: "agent_123",
+            effective_at: new Date().toISOString(),
+        };
+        return { data: mockCaps, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated override for run
+    /**
+     * Override capabilities for a specific run.
+     */
+    async overrideForRun(
+        runId: string,
+        overrides: Partial<CapabilityConfig>,
+        reason?: string
+    ): Promise<APIResponse<CapabilityOverride>> {
+        // MOCK - Returns simulated data
+        const mockOverride: CapabilityOverride = {
+            run_id: runId,
+            overrides,
+            reason,
+            applied_at: new Date().toISOString(),
+            applied_by: "user_123",
+        };
+        return { data: mockOverride, error: undefined, response: new Response() };
+    }
+}