@agent-os-sdk/client 0.1.1 → 0.1.2

package/src/modules/handoff.ts

@@ -0,0 +1,204 @@
+/**
+ * Handoff Module - Multi-Agent Delegation
+ * 
+ * // MOCK - This module contains mock implementations for future features
+ * 
+ * Provides first-class support for agent handoffs, delegation,
+ * thread forking, and run chain management.
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type HandoffMode = "same_thread" | "subthread" | "new_thread";
+
+export interface HandoffOptions {
+    mode: HandoffMode;
+    payload?: Record<string, unknown>;
+    constraints?: HandoffConstraints;
+    inherit_budget?: boolean;
+    inherit_policies?: boolean;
+}
+
+export interface HandoffConstraints {
+    max_tool_calls?: number;
+    max_tokens?: number;
+    tool_allowlist?: string[];
+    tool_denylist?: string[];
+    timeout_seconds?: number;
+}
+
+export interface HandoffResult {
+    run_id: string;
+    parent_run_id: string;
+    to_agent_id: string;
+    mode: HandoffMode;
+    thread_id: string;
+    status: "pending" | "running" | "completed" | "failed";
+    created_at: string;
+}
+
+export interface ForkOptions {
+    mode?: HandoffMode;
+    checkpoint_id?: string;
+    copy_messages?: boolean;
+    copy_state?: boolean;
+}
+
+export interface ForkResult {
+    original_thread_id: string;
+    forked_thread_id: string;
+    checkpoint_id?: string;
+    created_at: string;
+}
+
+export interface RunChainNode {
+    run_id: string;
+    agent_id: string;
+    agent_name: string;
+    status: string;
+    parent_run_id?: string;
+    children: RunChainNode[];
+    depth: number;
+    started_at: string;
+    completed_at?: string;
+}
+
+export interface RunChain {
+    root_run_id: string;
+    total_runs: number;
+    max_depth: number;
+    nodes: RunChainNode[];
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export class HandoffModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    // MOCK - Simulated handoff
+    /**
+     * Hand off current run to another agent.
+     */
+    async handoff(
+        runId: string,
+        toAgentId: string,
+        options?: HandoffOptions
+    ): Promise<APIResponse<HandoffResult>> {
+        // MOCK - Returns simulated data
+        const mockResult: HandoffResult = {
+            run_id: `run_handoff_${Date.now()}`,
+            parent_run_id: runId,
+            to_agent_id: toAgentId,
+            mode: options?.mode || "subthread",
+            thread_id: `thread_${Date.now()}`,
+            status: "pending",
+            created_at: new Date().toISOString(),
+        };
+        return { data: mockResult, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated fork
+    /**
+     * Fork a thread into a new conversation branch.
+     */
+    async fork(
+        threadId: string,
+        options?: ForkOptions
+    ): Promise<APIResponse<ForkResult>> {
+        // MOCK - Returns simulated data
+        const mockResult: ForkResult = {
+            original_thread_id: threadId,
+            forked_thread_id: `thread_fork_${Date.now()}`,
+            checkpoint_id: options?.checkpoint_id,
+            created_at: new Date().toISOString(),
+        };
+        return { data: mockResult, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated chain
+    /**
+     * Get the full run chain (delegation tree).
+     */
+    async getChain(runId: string): Promise<APIResponse<RunChain>> {
+        // MOCK - Returns simulated data
+        const mockChain: RunChain = {
+            root_run_id: runId,
+            total_runs: 3,
+            max_depth: 2,
+            nodes: [
+                {
+                    run_id: runId,
+                    agent_id: "agent_1",
+                    agent_name: "Main Agent",
+                    status: "completed",
+                    depth: 0,
+                    started_at: new Date(Date.now() - 60000).toISOString(),
+                    completed_at: new Date().toISOString(),
+                    children: [
+                        {
+                            run_id: `${runId}_child_1`,
+                            agent_id: "agent_2",
+                            agent_name: "Research Agent",
+                            status: "completed",
+                            parent_run_id: runId,
+                            depth: 1,
+                            started_at: new Date(Date.now() - 30000).toISOString(),
+                            completed_at: new Date().toISOString(),
+                            children: [],
+                        },
+                    ],
+                },
+            ],
+        };
+        return { data: mockChain, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated parents
+    /**
+     * Get parent runs in the chain.
+     */
+    async getParents(runId: string): Promise<APIResponse<RunChainNode[]>> {
+        // MOCK - Returns simulated data
+        const mockParents: RunChainNode[] = [
+            {
+                run_id: `parent_${runId}`,
+                agent_id: "agent_parent",
+                agent_name: "Parent Agent",
+                status: "completed",
+                depth: 0,
+                started_at: new Date(Date.now() - 120000).toISOString(),
+                completed_at: new Date(Date.now() - 60000).toISOString(),
+                children: [],
+            },
+        ];
+        return { data: mockParents, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated children
+    /**
+     * Get child runs in the chain.
+     */
+    async getChildren(runId: string): Promise<APIResponse<RunChainNode[]>> {
+        // MOCK - Returns simulated data
+        const mockChildren: RunChainNode[] = [
+            {
+                run_id: `child_1_${runId}`,
+                agent_id: "agent_child_1",
+                agent_name: "Child Agent 1",
+                status: "completed",
+                parent_run_id: runId,
+                depth: 1,
+                started_at: new Date(Date.now() - 30000).toISOString(),
+                completed_at: new Date().toISOString(),
+                children: [],
+            },
+        ];
+        return { data: mockChildren, error: undefined, response: new Response() };
+    }
+}

package/src/modules/incidents.ts

@@ -0,0 +1,339 @@
+/**
+ * Incidents Module - Operational Incidents & Postmortems
+ * 
+ * // MOCK - This module contains mock implementations for future features
+ * 
+ * Provides incident management, SLO tracking, and postmortem creation.
+ * Brings Datadog vibes to agent operations.
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type IncidentSeverity = "critical" | "major" | "minor" | "warning";
+export type IncidentStatus = "open" | "investigating" | "identified" | "monitoring" | "resolved";
+
+export interface Incident {
+    id: string;
+    title: string;
+    description: string;
+    severity: IncidentSeverity;
+    status: IncidentStatus;
+    affected_agents: string[];
+    affected_runs: string[];
+    root_cause?: string;
+    resolution?: string;
+    created_at: string;
+    updated_at: string;
+    resolved_at?: string;
+    created_by: string;
+}
+
+export interface SLO {
+    id: string;
+    name: string;
+    description?: string;
+    target_percentage: number;
+    current_percentage: number;
+    metric_type: "availability" | "latency" | "error_rate" | "success_rate";
+    threshold?: number;
+    window_days: number;
+    status: "healthy" | "at_risk" | "breached";
+    budget_remaining: number;
+    created_at: string;
+}
+
+export interface Postmortem {
+    id: string;
+    incident_id: string;
+    title: string;
+    summary: string;
+    timeline: PostmortemEvent[];
+    root_cause_analysis: string;
+    impact: string;
+    action_items: ActionItem[];
+    lessons_learned: string[];
+    created_at: string;
+    created_by: string;
+}
+
+export interface PostmortemEvent {
+    timestamp: string;
+    description: string;
+    actor?: string;
+}
+
+export interface ActionItem {
+    id: string;
+    description: string;
+    owner: string;
+    due_date?: string;
+    status: "open" | "in_progress" | "completed";
+}
+
+export interface IncidentListResponse {
+    items: Incident[];
+    total: number;
+    open_count: number;
+}
+
+export interface SLOListResponse {
+    items: SLO[];
+    total: number;
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export class IncidentsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    // ========== Incidents ==========
+
+    // MOCK - Simulated list
+    /**
+     * List all incidents.
+     */
+    async list(params?: {
+        status?: IncidentStatus;
+        severity?: IncidentSeverity;
+    }): Promise<APIResponse<IncidentListResponse>> {
+        // MOCK - Returns simulated data
+        const mockIncidents: IncidentListResponse = {
+            items: [
+                {
+                    id: "inc_1",
+                    title: "High error rate on Support Agent",
+                    description: "Error rate exceeded 5% threshold",
+                    severity: "major",
+                    status: "investigating",
+                    affected_agents: ["agent_support"],
+                    affected_runs: ["run_123", "run_124", "run_125"],
+                    created_at: new Date(Date.now() - 3600000).toISOString(),
+                    updated_at: new Date().toISOString(),
+                    created_by: "system",
+                },
+            ],
+            total: 1,
+            open_count: 1,
+        };
+        return { data: mockIncidents, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated get
+    /**
+     * Get an incident by ID.
+     */
+    async get(incidentId: string): Promise<APIResponse<Incident>> {
+        // MOCK - Returns simulated data
+        const mockIncident: Incident = {
+            id: incidentId,
+            title: "High error rate on Support Agent",
+            description: "Error rate exceeded 5% threshold",
+            severity: "major",
+            status: "investigating",
+            affected_agents: ["agent_support"],
+            affected_runs: ["run_123", "run_124", "run_125"],
+            created_at: new Date(Date.now() - 3600000).toISOString(),
+            updated_at: new Date().toISOString(),
+            created_by: "system",
+        };
+        return { data: mockIncident, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated create
+    /**
+     * Create a new incident.
+     */
+    async create(body: {
+        title: string;
+        description: string;
+        severity: IncidentSeverity;
+        affected_agents?: string[];
+    }): Promise<APIResponse<Incident>> {
+        // MOCK - Returns simulated data
+        const mockIncident: Incident = {
+            id: `inc_${Date.now()}`,
+            title: body.title,
+            description: body.description,
+            severity: body.severity,
+            status: "open",
+            affected_agents: body.affected_agents || [],
+            affected_runs: [],
+            created_at: new Date().toISOString(),
+            updated_at: new Date().toISOString(),
+            created_by: "user_current",
+        };
+        return { data: mockIncident, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated resolve
+    /**
+     * Resolve an incident.
+     */
+    async resolve(incidentId: string, resolution: string): Promise<APIResponse<Incident>> {
+        // MOCK - Returns simulated data
+        const mockIncident: Incident = {
+            id: incidentId,
+            title: "High error rate on Support Agent",
+            description: "Error rate exceeded 5% threshold",
+            severity: "major",
+            status: "resolved",
+            affected_agents: ["agent_support"],
+            affected_runs: [],
+            root_cause: "Model provider rate limit",
+            resolution,
+            created_at: new Date(Date.now() - 7200000).toISOString(),
+            updated_at: new Date().toISOString(),
+            resolved_at: new Date().toISOString(),
+            created_by: "system",
+        };
+        return { data: mockIncident, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated linkRuns
+    /**
+     * Link runs to an incident.
+     */
+    async linkRuns(incidentId: string, runIds: string[]): Promise<APIResponse<Incident>> {
+        // MOCK - Returns simulated data
+        const mockIncident: Incident = {
+            id: incidentId,
+            title: "High error rate on Support Agent",
+            description: "Error rate exceeded 5% threshold",
+            severity: "major",
+            status: "investigating",
+            affected_agents: ["agent_support"],
+            affected_runs: runIds,
+            created_at: new Date(Date.now() - 3600000).toISOString(),
+            updated_at: new Date().toISOString(),
+            created_by: "system",
+        };
+        return { data: mockIncident, error: undefined, response: new Response() };
+    }
+
+    // ========== SLOs ==========
+
+    // MOCK - Simulated listSLOs
+    /**
+     * List all SLOs.
+     */
+    async listSLOs(): Promise<APIResponse<SLOListResponse>> {
+        // MOCK - Returns simulated data
+        const mockSLOs: SLOListResponse = {
+            items: [
+                {
+                    id: "slo_availability",
+                    name: "Agent Availability",
+                    description: "99.9% availability for all agents",
+                    target_percentage: 99.9,
+                    current_percentage: 99.95,
+                    metric_type: "availability",
+                    window_days: 30,
+                    status: "healthy",
+                    budget_remaining: 0.05,
+                    created_at: new Date(Date.now() - 86400000 * 30).toISOString(),
+                },
+                {
+                    id: "slo_latency",
+                    name: "Response Latency",
+                    description: "P95 latency under 2s",
+                    target_percentage: 95,
+                    current_percentage: 97.5,
+                    metric_type: "latency",
+                    threshold: 2000,
+                    window_days: 7,
+                    status: "healthy",
+                    budget_remaining: 2.5,
+                    created_at: new Date(Date.now() - 86400000 * 7).toISOString(),
+                },
+                {
+                    id: "slo_errors",
+                    name: "Error Rate",
+                    description: "Error rate below 1%",
+                    target_percentage: 99,
+                    current_percentage: 98.2,
+                    metric_type: "error_rate",
+                    window_days: 7,
+                    status: "at_risk",
+                    budget_remaining: -0.8,
+                    created_at: new Date(Date.now() - 86400000 * 7).toISOString(),
+                },
+            ],
+            total: 3,
+        };
+        return { data: mockSLOs, error: undefined, response: new Response() };
+    }
+
+    // MOCK - Simulated setSLO
+    /**
+     * Create or update an SLO.
+     */
+    async setSLO(body: {
+        name: string;
+        description?: string;
+        target_percentage: number;
+        metric_type: SLO["metric_type"];
+        threshold?: number;
+        window_days: number;
+    }): Promise<APIResponse<SLO>> {
+        // MOCK - Returns simulated data
+        const mockSLO: SLO = {
+            id: `slo_${Date.now()}`,
+            name: body.name,
+            description: body.description,
+            target_percentage: body.target_percentage,
+            current_percentage: 100,
+            metric_type: body.metric_type,
+            threshold: body.threshold,
+            window_days: body.window_days,
+            status: "healthy",
+            budget_remaining: 100 - body.target_percentage,
+            created_at: new Date().toISOString(),
+        };
+        return { data: mockSLO, error: undefined, response: new Response() };
+    }
+
+    // ========== Postmortems ==========
+
+    // MOCK - Simulated createPostmortem
+    /**
+     * Create a postmortem for an incident.
+     */
+    async createPostmortem(incidentId: string, body: {
+        title: string;
+        summary: string;
+        root_cause_analysis: string;
+        impact: string;
+        lessons_learned: string[];
+        action_items: Omit<ActionItem, "id" | "status">[];
+    }): Promise<APIResponse<Postmortem>> {
+        // MOCK - Returns simulated data
+        const mockPostmortem: Postmortem = {
+            id: `pm_${Date.now()}`,
+            incident_id: incidentId,
+            title: body.title,
+            summary: body.summary,
+            timeline: [
+                { timestamp: new Date(Date.now() - 7200000).toISOString(), description: "Incident detected" },
+                { timestamp: new Date(Date.now() - 3600000).toISOString(), description: "Root cause identified" },
+                { timestamp: new Date().toISOString(), description: "Incident resolved" },
+            ],
+            root_cause_analysis: body.root_cause_analysis,
+            impact: body.impact,
+            action_items: body.action_items.map((item, i) => ({
+                ...item,
+                id: `action_${i}`,
+                status: "open" as const,
+            })),
+            lessons_learned: body.lessons_learned,
+            created_at: new Date().toISOString(),
+            created_by: "user_current",
+        };
+        return { data: mockPostmortem, error: undefined, response: new Response() };
+    }
+}

package/src/modules/members.ts

@@ -114,4 +114,15 @@ export class MembersModule {
             headers: this.headers(),
         });
     }
+
+    /**
+     * Ensure membership exists (auto-create on first access).
+     * This is used by the frontend for onboarding.
+     */
+    async ensure(tenantId?: string): Promise<APIResponse<Member>> {
+        return this.client.POST<Member>("/v1/api/memberships/ensure", {
+            body: { tenant_id: tenantId ?? null },
+            headers: this.headers(),
+        });
+    }
 }