@agent-os-sdk/client 0.1.2 → 0.2.2

package/src/modules/policies.ts

@@ -1,10 +1,8 @@
 /**
- * Policies Module - Governance Rules
- * 
- * // MOCK - This module contains mock implementations for future features
- * 
- * Defines and evaluates policies that control agent behavior.
- * Enables enterprise governance and compliance.
+ * Policies Module - Governance & Compliance
+ *
+ * NOT IMPLEMENTED - Backend endpoint not available.
+ * All methods return 501 NotImplemented.
  */
 
 import type { RawClient, APIResponse } from "../client/raw.js";
@@ -13,60 +11,59 @@ import type { RawClient, APIResponse } from "../client/raw.js";
 // Types
 // ============================================================================
 
-export type PolicyType = "allow" | "deny" | "require_approval" | "audit";
-export type PolicyScope = "tenant" | "workspace" | "agent" | "run";
+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;
-    type: PolicyType;
     scope: PolicyScope;
     scope_id?: string;
-    conditions: PolicyCondition[];
-    actions: PolicyAction[];
-    priority: number;
+    enforcement: PolicyEnforcement;
+    rules: PolicyRule[];
     enabled: boolean;
+    priority: number;
     created_at: string;
     updated_at: string;
 }
 
-export interface PolicyCondition {
-    field: string;
-    operator: "eq" | "neq" | "in" | "not_in" | "gt" | "lt" | "contains" | "regex";
-    value: unknown;
-}
-
-export interface PolicyAction {
-    type: "block" | "allow" | "require_approval" | "log" | "alert" | "modify";
-    config?: Record<string, unknown>;
-}
-
-export interface PolicyEvaluationInput {
-    action: string;
-    resource: string;
-    context: Record<string, unknown>;
+export interface PolicyEvaluation {
+    policy_id: string;
+    policy_name: string;
+    passed: boolean;
+    violated_rules: PolicyRule[];
+    audit_log_id?: string;
 }
 
 export interface PolicyEvaluationResult {
     allowed: boolean;
-    matched_policies: string[];
-    required_approvals: string[];
-    warnings: string[];
-    audit_entries: PolicyAuditEntry[];
+    evaluations: PolicyEvaluation[];
+    requires_approval: boolean;
+    blocking_policies: string[];
 }
 
-export interface PolicyAuditEntry {
-    policy_id: string;
-    policy_name: string;
-    decision: "allow" | "deny" | "pending_approval";
-    reason: string;
-    evaluated_at: string;
-}
+// ============================================================================
+// Helper for 501 responses
+// ============================================================================
 
-export interface PolicyListResponse {
-    items: Policy[];
-    total: number;
+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" }),
+    };
 }
 
 // ============================================================================
@@ -76,183 +73,40 @@ export interface PolicyListResponse {
 export class PoliciesModule {
     constructor(private client: RawClient, private headers: () => Record<string, string>) { }
 
-    // MOCK - Simulated list
-    /**
-     * List all policies.
-     */
+    /** @returns 501 Not Implemented */
     async list(params?: {
         scope?: PolicyScope;
+        scope_id?: string;
         enabled?: boolean;
-    }): Promise<APIResponse<PolicyListResponse>> {
-        // MOCK - Returns simulated data
-        const mockPolicies: PolicyListResponse = {
-            items: [
-                {
-                    id: "policy_1",
-                    name: "Block External Email",
-                    description: "Prevent agents from sending external emails without approval",
-                    type: "require_approval",
-                    scope: "tenant",
-                    conditions: [
-                        { field: "action", operator: "eq", value: "send_email" },
-                        { field: "recipient.domain", operator: "not_in", value: ["company.com"] },
-                    ],
-                    actions: [
-                        { type: "require_approval", config: { approver_role: "admin" } },
-                    ],
-                    priority: 100,
-                    enabled: true,
-                    created_at: new Date(Date.now() - 86400000).toISOString(),
-                    updated_at: new Date().toISOString(),
-                },
-                {
-                    id: "policy_2",
-                    name: "Audit All Tool Calls",
-                    description: "Log all tool calls for compliance",
-                    type: "audit",
-                    scope: "tenant",
-                    conditions: [
-                        { field: "action", operator: "eq", value: "tool_call" },
-                    ],
-                    actions: [
-                        { type: "log" },
-                    ],
-                    priority: 50,
-                    enabled: true,
-                    created_at: new Date(Date.now() - 86400000).toISOString(),
-                    updated_at: new Date().toISOString(),
-                },
-            ],
-            total: 2,
-        };
-        return { data: mockPolicies, error: undefined, response: new Response() };
+        limit?: number;
+        offset?: number;
+    }): Promise<APIResponse<{ items: Policy[]; total: number }>> {
+        return notImplemented<{ items: Policy[]; total: number }>("list");
     }
 
-    // MOCK - Simulated get
-    /**
-     * Get a policy by ID.
-     */
+    /** @returns 501 Not Implemented */
     async get(policyId: string): Promise<APIResponse<Policy>> {
-        // MOCK - Returns simulated data
-        const mockPolicy: Policy = {
-            id: policyId,
-            name: "Block External Email",
-            description: "Prevent agents from sending external emails without approval",
-            type: "require_approval",
-            scope: "tenant",
-            conditions: [
-                { field: "action", operator: "eq", value: "send_email" },
-            ],
-            actions: [
-                { type: "require_approval" },
-            ],
-            priority: 100,
-            enabled: true,
-            created_at: new Date(Date.now() - 86400000).toISOString(),
-            updated_at: new Date().toISOString(),
-        };
-        return { data: mockPolicy, error: undefined, response: new Response() };
+        return notImplemented<Policy>("get");
     }
 
-    // MOCK - Simulated create
-    /**
-     * Create a new policy.
-     */
+    /** @returns 501 Not Implemented */
     async create(body: {
         name: string;
         description?: string;
-        type: PolicyType;
         scope: PolicyScope;
         scope_id?: string;
-        conditions: PolicyCondition[];
-        actions: PolicyAction[];
-        priority?: number;
+        enforcement: PolicyEnforcement;
+        rules: PolicyRule[];
     }): Promise<APIResponse<Policy>> {
-        // MOCK - Returns simulated data
-        const mockPolicy: Policy = {
-            id: `policy_${Date.now()}`,
-            name: body.name,
-            description: body.description,
-            type: body.type,
-            scope: body.scope,
-            scope_id: body.scope_id,
-            conditions: body.conditions,
-            actions: body.actions,
-            priority: body.priority || 50,
-            enabled: true,
-            created_at: new Date().toISOString(),
-            updated_at: new Date().toISOString(),
-        };
-        return { data: mockPolicy, error: undefined, response: new Response() };
-    }
-
-    // MOCK - Simulated update
-    /**
-     * Update a policy.
-     */
-    async update(policyId: string, body: Partial<Policy>): Promise<APIResponse<Policy>> {
-        // MOCK - Returns simulated data
-        const mockPolicy: Policy = {
-            id: policyId,
-            name: body.name || "Updated Policy",
-            type: body.type || "allow",
-            scope: body.scope || "tenant",
-            conditions: body.conditions || [],
-            actions: body.actions || [],
-            priority: body.priority || 50,
-            enabled: body.enabled ?? true,
-            created_at: new Date(Date.now() - 86400000).toISOString(),
-            updated_at: new Date().toISOString(),
-        };
-        return { data: mockPolicy, error: undefined, response: new Response() };
-    }
-
-    // MOCK - Simulated delete
-    /**
-     * Delete a policy.
-     */
-    async delete(policyId: string): Promise<APIResponse<void>> {
-        // MOCK - Returns success
-        return { data: undefined, error: undefined, response: new Response() };
-    }
-
-    // MOCK - Simulated evaluate
-    /**
-     * Evaluate policies against an action (simulation).
-     */
-    async evaluate(input: PolicyEvaluationInput): Promise<APIResponse<PolicyEvaluationResult>> {
-        // MOCK - Returns simulated evaluation
-        const mockResult: PolicyEvaluationResult = {
-            allowed: true,
-            matched_policies: ["policy_2"],
-            required_approvals: [],
-            warnings: [],
-            audit_entries: [
-                {
-                    policy_id: "policy_2",
-                    policy_name: "Audit All Tool Calls",
-                    decision: "allow",
-                    reason: "Action logged for audit",
-                    evaluated_at: new Date().toISOString(),
-                },
-            ],
-        };
-        return { data: mockResult, error: undefined, response: new Response() };
+        return notImplemented<Policy>("create");
     }
 
-    // MOCK - Simulated enforce
-    /**
-     * Enforce policies (apply to current context).
-     */
-    async enforce(runId: string): Promise<APIResponse<PolicyEvaluationResult>> {
-        // MOCK - Returns simulated enforcement
-        const mockResult: PolicyEvaluationResult = {
-            allowed: true,
-            matched_policies: [],
-            required_approvals: [],
-            warnings: [],
-            audit_entries: [],
-        };
-        return { data: mockResult, error: undefined, response: new Response() };
+    /** @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 ========================
 
     /**