@agent-os-sdk/client 0.1.1 → 0.2.1

package/src/modules/flows.ts

@@ -0,0 +1,133 @@
+/**
+ * Flows Module - Workflow Orchestration
+ *
+ * NOT IMPLEMENTED - Backend endpoint not available.
+ * All methods return 501 NotImplemented.
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type FlowStatus = "draft" | "active" | "paused" | "completed" | "failed" | "cancelled";
+
+export interface FlowStep {
+    id: string;
+    name: string;
+    agent_id: string;
+    type: "agent" | "condition" | "parallel" | "wait" | "human_approval";
+    config?: Record<string, unknown>;
+    next_steps?: string[];
+    on_error?: string;
+}
+
+export interface Flow {
+    id: string;
+    name: string;
+    description?: string;
+    steps: FlowStep[];
+    status: FlowStatus;
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface FlowRun {
+    id: string;
+    flow_id: string;
+    status: FlowStatus;
+    current_step_id?: string;
+    completed_steps: string[];
+    failed_steps: string[];
+    context: Record<string, unknown>;
+    started_at: string;
+    completed_at?: string;
+}
+
+export interface FlowVisualization {
+    mermaid: string;
+    svg?: string;
+}
+
+export interface FlowSimulationResult {
+    success: boolean;
+    steps_executed: string[];
+    estimated_duration_seconds: number;
+    estimated_cost: number;
+    potential_issues: string[];
+}
+
+export interface FlowListResponse {
+    items: Flow[];
+    total: number;
+}
+
+// ============================================================================
+// Helper for 501 responses
+// ============================================================================
+
+function notImplemented<T>(method: string): APIResponse<T> {
+    return {
+        data: undefined,
+        error: {
+            code: "NOT_IMPLEMENTED",
+            message: `FlowsModule.${method}() is not implemented. Backend endpoint not available.`,
+        },
+        response: new Response(null, { status: 501, statusText: "Not Implemented" }),
+    };
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export class FlowsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /** @returns 501 Not Implemented */
+    async list(params?: { limit?: number; offset?: number }): Promise<APIResponse<FlowListResponse>> {
+        return notImplemented<FlowListResponse>("list");
+    }
+
+    /** @returns 501 Not Implemented */
+    async get(flowId: string): Promise<APIResponse<Flow>> {
+        return notImplemented<Flow>("get");
+    }
+
+    /** @returns 501 Not Implemented */
+    async create(body: { name: string; description?: string; steps: FlowStep[] }): Promise<APIResponse<Flow>> {
+        return notImplemented<Flow>("create");
+    }
+
+    /** @returns 501 Not Implemented */
+    async run(flowId: string, input?: Record<string, unknown>): Promise<APIResponse<FlowRun>> {
+        return notImplemented<FlowRun>("run");
+    }
+
+    /** @returns 501 Not Implemented */
+    async pause(flowRunId: string): Promise<APIResponse<FlowRun>> {
+        return notImplemented<FlowRun>("pause");
+    }
+
+    /** @returns 501 Not Implemented */
+    async resume(flowRunId: string): Promise<APIResponse<FlowRun>> {
+        return notImplemented<FlowRun>("resume");
+    }
+
+    /** @returns 501 Not Implemented */
+    async cancel(flowRunId: string): Promise<APIResponse<FlowRun>> {
+        return notImplemented<FlowRun>("cancel");
+    }
+
+    /** @returns 501 Not Implemented */
+    async visualize(flowId: string): Promise<APIResponse<FlowVisualization>> {
+        return notImplemented<FlowVisualization>("visualize");
+    }
+
+    /** @returns 501 Not Implemented */
+    async simulate(flowId: string, input?: Record<string, unknown>): Promise<APIResponse<FlowSimulationResult>> {
+        return notImplemented<FlowSimulationResult>("simulate");
+    }
+}

package/src/modules/handoff.ts

@@ -0,0 +1,140 @@
+/**
+ * Handoff Module - Multi-Agent Delegation
+ *
+ * NOT IMPLEMENTED - Backend endpoint not available.
+ * All methods return 501 NotImplemented.
+ */
+
+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[];
+}
+
+// ============================================================================
+// Helper for 501 responses
+// ============================================================================
+
+function notImplemented<T>(method: string): APIResponse<T> {
+    return {
+        data: undefined,
+        error: {
+            code: "NOT_IMPLEMENTED",
+            message: `HandoffModule.${method}() is not implemented. Backend endpoint not available.`,
+        },
+        response: new Response(null, { status: 501, statusText: "Not Implemented" }),
+    };
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export class HandoffModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /**
+     * Hand off current run to another agent.
+     * @returns 501 Not Implemented - Backend not available
+     */
+    async handoff(
+        runId: string,
+        toAgentId: string,
+        options?: HandoffOptions
+    ): Promise<APIResponse<HandoffResult>> {
+        return notImplemented<HandoffResult>("handoff");
+    }
+
+    /**
+     * Fork a thread into a new conversation branch.
+     * @returns 501 Not Implemented - Backend not available
+     */
+    async fork(threadId: string, options?: ForkOptions): Promise<APIResponse<ForkResult>> {
+        return notImplemented<ForkResult>("fork");
+    }
+
+    /**
+     * Get the full run chain (delegation tree).
+     * @returns 501 Not Implemented - Backend not available
+     */
+    async getChain(runId: string): Promise<APIResponse<RunChain>> {
+        return notImplemented<RunChain>("getChain");
+    }
+
+    /**
+     * Get parent runs in the chain.
+     * @returns 501 Not Implemented - Backend not available
+     */
+    async getParents(runId: string): Promise<APIResponse<RunChainNode[]>> {
+        return notImplemented<RunChainNode[]>("getParents");
+    }
+
+    /**
+     * Get child runs in the chain.
+     * @returns 501 Not Implemented - Backend not available
+     */
+    async getChildren(runId: string): Promise<APIResponse<RunChainNode[]>> {
+        return notImplemented<RunChainNode[]>("getChildren");
+    }
+}

package/src/modules/incidents.ts

@@ -0,0 +1,113 @@
+/**
+ * Incidents Module - Error & Alert Management
+ *
+ * NOT IMPLEMENTED - Backend endpoint not available.
+ * All methods return 501 NotImplemented.
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type IncidentSeverity = "low" | "medium" | "high" | "critical";
+export type IncidentStatus = "open" | "investigating" | "identified" | "monitoring" | "resolved" | "closed";
+
+export interface Incident {
+    id: string;
+    title: string;
+    description?: string;
+    severity: IncidentSeverity;
+    status: IncidentStatus;
+    agent_id?: string;
+    run_id?: string;
+    error_type?: string;
+    error_message?: string;
+    stack_trace?: string;
+    affected_users?: number;
+    created_at: string;
+    updated_at: string;
+    resolved_at?: string;
+}
+
+export interface IncidentUpdate {
+    id: string;
+    incident_id: string;
+    message: string;
+    status_change?: IncidentStatus;
+    created_by: string;
+    created_at: string;
+}
+
+export interface IncidentMetrics {
+    total_open: number;
+    by_severity: Record<IncidentSeverity, number>;
+    mttr_seconds: number;
+    trend_last_7_days: number[];
+}
+
+// ============================================================================
+// Helper for 501 responses
+// ============================================================================
+
+function notImplemented<T>(method: string): APIResponse<T> {
+    return {
+        data: undefined,
+        error: {
+            code: "NOT_IMPLEMENTED",
+            message: `IncidentsModule.${method}() is not implemented. Backend endpoint not available.`,
+        },
+        response: new Response(null, { status: 501, statusText: "Not Implemented" }),
+    };
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export class IncidentsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /** @returns 501 Not Implemented */
+    async list(params?: {
+        status?: IncidentStatus;
+        severity?: IncidentSeverity;
+        agent_id?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<APIResponse<{ items: Incident[]; total: number }>> {
+        return notImplemented<{ items: Incident[]; total: number }>("list");
+    }
+
+    /** @returns 501 Not Implemented */
+    async get(incidentId: string): Promise<APIResponse<Incident>> {
+        return notImplemented<Incident>("get");
+    }
+
+    /** @returns 501 Not Implemented */
+    async create(body: {
+        title: string;
+        description?: string;
+        severity: IncidentSeverity;
+        agent_id?: string;
+        run_id?: string;
+    }): Promise<APIResponse<Incident>> {
+        return notImplemented<Incident>("create");
+    }
+
+    /** @returns 501 Not Implemented */
+    async update(incidentId: string, status: IncidentStatus, message?: string): Promise<APIResponse<IncidentUpdate>> {
+        return notImplemented<IncidentUpdate>("update");
+    }
+
+    /** @returns 501 Not Implemented */
+    async resolve(incidentId: string, message?: string): Promise<APIResponse<Incident>> {
+        return notImplemented<Incident>("resolve");
+    }
+
+    /** @returns 501 Not Implemented */
+    async getMetrics(): Promise<APIResponse<IncidentMetrics>> {
+        return notImplemented<IncidentMetrics>("getMetrics");
+    }
+}

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(),
+        });
+    }
 }

package/src/modules/policies.ts

@@ -0,0 +1,112 @@
+/**
+ * Policies Module - Governance & Compliance
+ *
+ * NOT IMPLEMENTED - Backend endpoint not available.
+ * All methods return 501 NotImplemented.
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type PolicyScope = "agent" | "workspace" | "tenant" | "global";
+export type PolicyEnforcement = "hard" | "soft" | "audit_only";
+
+export interface PolicyRule {
+    id: string;
+    type: "allow" | "deny" | "require_approval" | "log";
+    condition: string;
+    action?: string;
+    message?: string;
+}
+
+export interface Policy {
+    id: string;
+    name: string;
+    description?: string;
+    scope: PolicyScope;
+    scope_id?: string;
+    enforcement: PolicyEnforcement;
+    rules: PolicyRule[];
+    enabled: boolean;
+    priority: number;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface PolicyEvaluation {
+    policy_id: string;
+    policy_name: string;
+    passed: boolean;
+    violated_rules: PolicyRule[];
+    audit_log_id?: string;
+}
+
+export interface PolicyEvaluationResult {
+    allowed: boolean;
+    evaluations: PolicyEvaluation[];
+    requires_approval: boolean;
+    blocking_policies: string[];
+}
+
+// ============================================================================
+// Helper for 501 responses
+// ============================================================================
+
+function notImplemented<T>(method: string): APIResponse<T> {
+    return {
+        data: undefined,
+        error: {
+            code: "NOT_IMPLEMENTED",
+            message: `PoliciesModule.${method}() is not implemented. Backend endpoint not available.`,
+        },
+        response: new Response(null, { status: 501, statusText: "Not Implemented" }),
+    };
+}
+
+// ============================================================================
+// Module
+// ============================================================================
+
+export class PoliciesModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /** @returns 501 Not Implemented */
+    async list(params?: {
+        scope?: PolicyScope;
+        scope_id?: string;
+        enabled?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<APIResponse<{ items: Policy[]; total: number }>> {
+        return notImplemented<{ items: Policy[]; total: number }>("list");
+    }
+
+    /** @returns 501 Not Implemented */
+    async get(policyId: string): Promise<APIResponse<Policy>> {
+        return notImplemented<Policy>("get");
+    }
+
+    /** @returns 501 Not Implemented */
+    async create(body: {
+        name: string;
+        description?: string;
+        scope: PolicyScope;
+        scope_id?: string;
+        enforcement: PolicyEnforcement;
+        rules: PolicyRule[];
+    }): Promise<APIResponse<Policy>> {
+        return notImplemented<Policy>("create");
+    }
+
+    /** @returns 501 Not Implemented */
+    async evaluate(context: {
+        agent_id: string;
+        action: string;
+        payload?: Record<string, unknown>;
+    }): Promise<APIResponse<PolicyEvaluationResult>> {
+        return notImplemented<PolicyEvaluationResult>("evaluate");
+    }
+}

package/src/modules/runs.ts

@@ -20,7 +20,7 @@ type CheckpointListResponse = components["schemas"]["CheckpointListResponse"];
 // Response types
 export interface Run {
     run_id: string;
-    status: "pending" | "running" | "completed" | "failed" | "cancelled" | "waiting_input";
+    status: RunStatus;
     thread_id?: string;
     agent_id: string;
     agent_version_id?: string;
@@ -34,8 +34,26 @@ export interface Run {
     completed_at?: string;
     duration_ms?: number;
     reused?: boolean;
+    // HITL (Human-in-the-Loop) fields
+    human_prompt?: string;
+    checkpoint_id?: string;
+    // Replay fields
+    replayed_from_run_id?: string;
+    replayed_from_checkpoint_id?: string;
+    replay_mode?: "best_effort" | "strict";
 }
 
+// Run status values
+export type RunStatus =
+    | "pending"
+    | "queued"
+    | "running"
+    | "completed"
+    | "failed"
+    | "cancelled"
+    | "waiting_for_human"
+    | "resumed";
+
 export interface RunEvent {
     id: string;
     run_id: string;
@@ -54,6 +72,24 @@ export interface CreateRunResponse {
 export type RunListResponse = PaginatedResponse<Run>;
 export type RunEventsResponse = PaginatedResponse<RunEvent>;
 
+/** Wave 2.3: Seq-based polling response for execution events */
+export interface RunEventsPollResponse {
+    events: RunEventDto[];
+    latest_seq: number;
+    next_after_seq: number;
+    has_more: boolean;
+}
+
+/** Single event from seq-based polling */
+export interface RunEventDto {
+    id: string;
+    seq: number;
+    type: string;
+    timestamp: string;
+    attempt_id: string;
+    payload: Record<string, unknown> | null;
+}
+
 export class RunsModule {
     constructor(
         private client: RawClient,
@@ -152,11 +188,30 @@ export class RunsModule {
 
     /**
      * Resume a run waiting for human input (HITL).
+     * After the run reaches status 'waiting_for_human', use this to provide
+     * the human response and continue execution.
+     * 
+     * @param runId - The run ID to resume
+     * @param body - The human input to provide
+     * @returns Updated run (status will change to 'resumed' then 'queued')
+     * 
+     * @example
+     * ```ts
+     * // List runs waiting for human input
+     * const waiting = await client.runs.list({ status: 'waiting_for_human' })
+     * 
+     * // Get the prompt
+     * const run = await client.runs.get(runId)
+     * console.log(run.human_prompt)  // "Deseja continuar com a compra?"
+     * 
+     * // Respond
+     * await client.runs.resume(runId, { input: { answer: "sim" } })
+     * ```
      */
-    async resume(runId: string, input: unknown): Promise<APIResponse<Run>> {
+    async resume(runId: string, body: { input: unknown }): Promise<APIResponse<Run>> {
         return this.client.POST<Run>("/v1/api/runs/{runId}/resume", {
             params: { path: { runId } },
-            body: { input },
+            body,
             headers: this.headers(),
         });
     }
@@ -173,11 +228,37 @@ export class RunsModule {
 
     /**
      * Replay from checkpoint (stateful).
+     * Creates a NEW run that starts from the specified checkpoint.
+     * 
+     * @param runId - The original run to replay from
+     * @param checkpointId - The checkpoint ID to start from
+     * @param options - Replay options
+     * @returns New run created from checkpoint
+     * 
+     * @example
+     * ```ts
+     * const checkpoints = await client.runs.getCheckpoints(runId)
+     * const newRun = await client.runs.replay(runId, checkpoints[2].id, {
+     *   mode: 'best_effort',
+     *   reason: 'Debugging step 3'
+     * })
+     * ```
      */
-    async replay(runId: string, checkpointId?: string, mode?: "best_effort" | "deterministic"): Promise<APIResponse<CreateRunResponse>> {
+    async replay(
+        runId: string,
+        checkpointId?: string,
+        options?: {
+            mode?: "best_effort" | "strict";
+            reason?: string;
+        }
+    ): Promise<APIResponse<CreateRunResponse>> {
         return this.client.POST<CreateRunResponse>("/v1/api/runs/{runId}/replay", {
             params: { path: { runId } },
-            body: { checkpoint_id: checkpointId, mode },
+            body: {
+                checkpoint_id: checkpointId,
+                mode: options?.mode,
+                reason: options?.reason
+            },
             headers: this.headers(),
         });
     }
@@ -201,6 +282,43 @@ export class RunsModule {
     /** Alias: runs.events() -> runs.getEvents() */
     events = (runId: string, params?: PaginationParams) => this.getEvents(runId, params);
 
+    /**
+     * Wave 2.3: Seq-based event polling for execution trace.
+     * Use this for incremental polling with reconnection support.
+     * 
+     * @param runId - Run ID to poll events for
+     * @param params - Polling options
+     * @returns Events with seq cursors for pagination
+     * 
+     * @example
+     * ```ts
+     * let afterSeq = 0;
+     * while (run.status === 'running') {
+     *   const { data } = await client.runs.pollEvents(runId, { afterSeq });
+     *   for (const event of data.events) {
+     *     console.log(event.type, event.payload);
+     *   }
+     *   afterSeq = data.next_after_seq;
+     *   await sleep(1000);
+     * }
+     * ```
+     */
+    async pollEvents(runId: string, params?: {
+        afterSeq?: number;
+        limit?: number;
+    }): Promise<APIResponse<RunEventsPollResponse>> {
+        return this.client.GET<RunEventsPollResponse>("/v1/api/runs/{runId}/events/stream", {
+            params: {
+                path: { runId },
+                query: {
+                    afterSeq: params?.afterSeq ?? 0,
+                    limit: params?.limit ?? 100
+                }
+            },
+            headers: this.headers(),
+        });
+    }
+
     // ======================== Checkpoints ========================
 
     /**