@agentfield/sdk 0.1.43 → 0.1.44-rc.2

package/dist/index.d.ts

@@ -160,6 +160,7 @@ interface ExecutionStatusUpdate {
     error?: string;
     durationMs?: number;
     progress?: number;
+    statusReason?: string;
 }
 declare class AgentFieldClient {
     private readonly http;
@@ -187,9 +188,10 @@ declare class AgentFieldClient {
         workflowId?: string;
         reasonerId: string;
         agentNodeId: string;
-        status: 'running' | 'succeeded' | 'failed';
+        status: 'waiting' | 'running' | 'succeeded' | 'failed';
         parentExecutionId?: string;
         parentWorkflowId?: string;
+        statusReason?: string;
         inputData?: Record<string, any>;
         result?: any;
         error?: string;
@@ -980,4 +982,108 @@ declare class StatelessRateLimiter {
     executeWithRetry<T>(fn: () => Promise<T>): Promise<T>;
 }
 
-export { AIClient, type AIConfig, type AIEmbeddingOptions, type AIRequestOptions, type AIStream, Agent, type AgentCapability, type AgentConfig, type AgentHandler, AgentRouter, type AgentRouterOptions, type AgentState, type AuditTrailExport, type AuditTrailFilters, type Awaitable, type CompactCapability, type CompactDiscoveryResponse, DIDAuthenticator, type DIDIdentity, type DIDIdentityPackage, type DIDRegistrationRequest, type DIDRegistrationResponse, type DeploymentType, DidClient, DidInterface, DidManager, type DiscoveryFormat, type DiscoveryOptions, type DiscoveryPagination, type DiscoveryResponse, type DiscoveryResult, ExecutionContext, type ExecutionCredential, type ExecutionMetadata, type GenerateCredentialOptions, type GenerateCredentialParams, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, type HealthStatus, MCPClient, MCPClientRegistry, type MCPConfig, type MCPHealthSummary, type MCPServerConfig, type MCPTool, MCPToolRegistrar, type MCPToolRegistrarOptions, type MCPToolRegistration, type MemoryChangeEvent, MemoryClient, type MemoryConfig, MemoryEventClient, type MemoryEventHandler, MemoryInterface, type MemoryRequestMetadata, type MemoryRequestOptions, type MemoryScope, type MemoryWatchHandler, RateLimitError, type RateLimiterOptions, type ReasonerCapability, ReasonerContext, type ReasonerDefinition, type ReasonerHandler, type ReasonerOptions, type ServerlessAdapter, type ServerlessEvent, type ServerlessResponse, type SkillCapability, SkillContext, type SkillDefinition, type SkillHandler, type SkillOptions, StatelessRateLimiter, type VectorSearchOptions, type VectorSearchResult, type WorkflowCredential, type WorkflowMetadata, type WorkflowProgressOptions, WorkflowReporter, type ZodSchema, getCurrentContext, getCurrentSkillContext };
+/**
+ * Canonical execution status utilities for the AgentField TypeScript SDK.
+ *
+ * Mirrors the control plane's status normalization and terminal-state logic
+ * so that SDK consumers can classify execution statuses consistently.
+ */
+/** Canonical execution status values used by the control plane. */
+declare const ExecutionStatus: {
+    readonly PENDING: "pending";
+    readonly QUEUED: "queued";
+    readonly WAITING: "waiting";
+    readonly RUNNING: "running";
+    readonly SUCCEEDED: "succeeded";
+    readonly FAILED: "failed";
+    readonly CANCELLED: "cancelled";
+    readonly TIMEOUT: "timeout";
+    readonly UNKNOWN: "unknown";
+};
+type ExecutionStatusValue = (typeof ExecutionStatus)[keyof typeof ExecutionStatus];
+/** All canonical status strings. */
+declare const CANONICAL_STATUSES: ReadonlySet<string>;
+/** Statuses that represent a completed execution (no further transitions). */
+declare const TERMINAL_STATUSES: ReadonlySet<string>;
+/** Statuses that represent an active, pollable execution. */
+declare const ACTIVE_STATUSES: ReadonlySet<string>;
+/**
+ * Normalize an arbitrary status string to its canonical form.
+ *
+ * Returns `"unknown"` for unrecognized or empty values.
+ */
+declare function normalizeStatus(status: string | null | undefined): string;
+/** Return `true` if the status represents a terminal (completed) execution. */
+declare function isTerminal(status: string | null | undefined): boolean;
+/** Return `true` if the status represents an active, pollable execution. */
+declare function isActive(status: string | null | undefined): boolean;
+
+/**
+ * Approval workflow helpers for the AgentField TypeScript SDK.
+ *
+ * Provides methods to request human approval for an execution,
+ * poll for approval status, and wait until resolved.
+ */
+/** Payload sent when requesting approval. */
+interface RequestApprovalPayload {
+    title?: string;
+    description?: string;
+    templateType?: string;
+    payload?: Record<string, any>;
+    projectId: string;
+    expiresInHours?: number;
+}
+/** Response from the control plane after creating an approval request. */
+interface ApprovalRequestResponse {
+    approvalRequestId: string;
+    approvalRequestUrl: string;
+}
+/** Approval status returned by the polling endpoint. */
+interface ApprovalStatusResponse {
+    status: 'pending' | 'approved' | 'rejected' | 'expired';
+    response?: Record<string, any>;
+    requestUrl?: string;
+    requestedAt?: string;
+    respondedAt?: string;
+}
+/** Options for the blocking `waitForApproval` helper. */
+interface WaitForApprovalOptions {
+    /** Initial polling interval in milliseconds (default: 5000). */
+    pollIntervalMs?: number;
+    /** Maximum polling interval in milliseconds (default: 60000). */
+    maxIntervalMs?: number;
+    /** Total timeout in milliseconds (default: unlimited). */
+    timeoutMs?: number;
+}
+declare class ApprovalClient {
+    private readonly http;
+    private readonly nodeId;
+    private readonly headers;
+    constructor(opts: {
+        baseURL: string;
+        nodeId: string;
+        apiKey?: string;
+        headers?: Record<string, string>;
+    });
+    /**
+     * Request human approval, transitioning the execution to `waiting`.
+     *
+     * Calls `POST /api/v1/agents/{node}/executions/{id}/request-approval`.
+     */
+    requestApproval(executionId: string, payload: RequestApprovalPayload): Promise<ApprovalRequestResponse>;
+    /**
+     * Get the current approval status for an execution.
+     *
+     * Calls `GET /api/v1/agents/{node}/executions/{id}/approval-status`.
+     */
+    getApprovalStatus(executionId: string): Promise<ApprovalStatusResponse>;
+    /**
+     * Poll approval status with exponential backoff until resolved.
+     *
+     * Returns once the status is no longer `pending` (i.e. approved, rejected,
+     * or expired).
+     */
+    waitForApproval(executionId: string, opts?: WaitForApprovalOptions): Promise<ApprovalStatusResponse>;
+}
+
+export { ACTIVE_STATUSES, AIClient, type AIConfig, type AIEmbeddingOptions, type AIRequestOptions, type AIStream, Agent, type AgentCapability, type AgentConfig, type AgentHandler, AgentRouter, type AgentRouterOptions, type AgentState, ApprovalClient, type ApprovalRequestResponse, type ApprovalStatusResponse, type AuditTrailExport, type AuditTrailFilters, type Awaitable, CANONICAL_STATUSES, type CompactCapability, type CompactDiscoveryResponse, DIDAuthenticator, type DIDIdentity, type DIDIdentityPackage, type DIDRegistrationRequest, type DIDRegistrationResponse, type DeploymentType, DidClient, DidInterface, DidManager, type DiscoveryFormat, type DiscoveryOptions, type DiscoveryPagination, type DiscoveryResponse, type DiscoveryResult, ExecutionContext, type ExecutionCredential, type ExecutionMetadata, ExecutionStatus, type ExecutionStatusValue, type GenerateCredentialOptions, type GenerateCredentialParams, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, type HealthStatus, MCPClient, MCPClientRegistry, type MCPConfig, type MCPHealthSummary, type MCPServerConfig, type MCPTool, MCPToolRegistrar, type MCPToolRegistrarOptions, type MCPToolRegistration, type MemoryChangeEvent, MemoryClient, type MemoryConfig, MemoryEventClient, type MemoryEventHandler, MemoryInterface, type MemoryRequestMetadata, type MemoryRequestOptions, type MemoryScope, type MemoryWatchHandler, RateLimitError, type RateLimiterOptions, type ReasonerCapability, ReasonerContext, type ReasonerDefinition, type ReasonerHandler, type ReasonerOptions, type RequestApprovalPayload, type ServerlessAdapter, type ServerlessEvent, type ServerlessResponse, type SkillCapability, SkillContext, type SkillDefinition, type SkillHandler, type SkillOptions, StatelessRateLimiter, TERMINAL_STATUSES, type VectorSearchOptions, type VectorSearchResult, type WaitForApprovalOptions, type WorkflowCredential, type WorkflowMetadata, type WorkflowProgressOptions, WorkflowReporter, type ZodSchema, getCurrentContext, getCurrentSkillContext, isActive, isTerminal, normalizeStatus };

package/dist/index.js

@@ -806,6 +806,7 @@ var AgentFieldClient = class {
       type: event.reasonerId,
       agent_node_id: event.agentNodeId,
       status: event.status,
+      status_reason: event.statusReason,
       parent_execution_id: event.parentExecutionId,
       parent_workflow_id: event.parentWorkflowId ?? event.workflowId ?? event.runId,
       input_data: event.inputData ?? {},
@@ -830,7 +831,8 @@ var AgentFieldClient = class {
       result: update.result,
       error: update.error,
       duration_ms: update.durationMs,
-      progress: update.progress !== void 0 ? Math.round(update.progress) : void 0
+      progress: update.progress !== void 0 ? Math.round(update.progress) : void 0,
+      status_reason: update.statusReason
     };
     const bodyStr = JSON.stringify(payload);
     const authHeaders = this.didAuthenticator.signRequest(Buffer.from(bodyStr));
@@ -3219,6 +3221,165 @@ function sanitize(value) {
   return value.replace(/[^0-9a-zA-Z]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
 }
 
-export { AIClient, Agent, AgentRouter, DIDAuthenticator, DidClient, DidInterface, DidManager, ExecutionContext, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, MCPClient, MCPClientRegistry, MCPToolRegistrar, MemoryClient, MemoryEventClient, MemoryInterface, RateLimitError, ReasonerContext, SkillContext, StatelessRateLimiter, WorkflowReporter, getCurrentContext, getCurrentSkillContext };
+// src/status/ExecutionStatus.ts
+var ExecutionStatus = {
+  PENDING: "pending",
+  QUEUED: "queued",
+  WAITING: "waiting",
+  RUNNING: "running",
+  SUCCEEDED: "succeeded",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+  TIMEOUT: "timeout",
+  UNKNOWN: "unknown"
+};
+var CANONICAL_STATUSES = new Set(
+  Object.values(ExecutionStatus)
+);
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  ExecutionStatus.SUCCEEDED,
+  ExecutionStatus.FAILED,
+  ExecutionStatus.CANCELLED,
+  ExecutionStatus.TIMEOUT
+]);
+var ACTIVE_STATUSES = /* @__PURE__ */ new Set([
+  ExecutionStatus.PENDING,
+  ExecutionStatus.QUEUED,
+  ExecutionStatus.WAITING,
+  ExecutionStatus.RUNNING
+]);
+var STATUS_ALIASES = {
+  success: "succeeded",
+  successful: "succeeded",
+  completed: "succeeded",
+  complete: "succeeded",
+  done: "succeeded",
+  ok: "succeeded",
+  error: "failed",
+  failure: "failed",
+  errored: "failed",
+  canceled: "cancelled",
+  cancel: "cancelled",
+  timed_out: "timeout",
+  wait: "queued",
+  awaiting_approval: "waiting",
+  awaiting_human: "waiting",
+  approval_pending: "waiting",
+  in_progress: "running",
+  processing: "running"
+};
+function normalizeStatus(status) {
+  if (status == null) return "unknown";
+  const normalized = status.trim().toLowerCase();
+  if (!normalized) return "unknown";
+  if (CANONICAL_STATUSES.has(normalized)) return normalized;
+  return STATUS_ALIASES[normalized] ?? "unknown";
+}
+function isTerminal(status) {
+  return TERMINAL_STATUSES.has(normalizeStatus(status));
+}
+function isActive(status) {
+  return ACTIVE_STATUSES.has(normalizeStatus(status));
+}
+var ApprovalClient = class {
+  http;
+  nodeId;
+  headers;
+  constructor(opts) {
+    this.http = axios5.create({
+      baseURL: opts.baseURL.replace(/\/$/, ""),
+      timeout: 3e4,
+      httpAgent,
+      httpsAgent
+    });
+    this.nodeId = opts.nodeId;
+    const merged = { ...opts.headers ?? {} };
+    if (opts.apiKey) {
+      merged["X-API-Key"] = opts.apiKey;
+    }
+    this.headers = merged;
+  }
+  /**
+   * Request human approval, transitioning the execution to `waiting`.
+   *
+   * Calls `POST /api/v1/agents/{node}/executions/{id}/request-approval`.
+   */
+  async requestApproval(executionId, payload) {
+    const body = {
+      title: payload.title ?? "Approval Request",
+      description: payload.description ?? "",
+      template_type: payload.templateType ?? "plan-review-v1",
+      payload: payload.payload ?? {},
+      project_id: payload.projectId,
+      expires_in_hours: payload.expiresInHours ?? 72
+    };
+    const res = await this.http.post(
+      `/api/v1/agents/${encodeURIComponent(this.nodeId)}/executions/${encodeURIComponent(executionId)}/request-approval`,
+      body,
+      { headers: { ...this.headers, "Content-Type": "application/json" } }
+    );
+    return {
+      approvalRequestId: res.data.approval_request_id ?? "",
+      approvalRequestUrl: res.data.approval_request_url ?? ""
+    };
+  }
+  /**
+   * Get the current approval status for an execution.
+   *
+   * Calls `GET /api/v1/agents/{node}/executions/{id}/approval-status`.
+   */
+  async getApprovalStatus(executionId) {
+    const res = await this.http.get(
+      `/api/v1/agents/${encodeURIComponent(this.nodeId)}/executions/${encodeURIComponent(executionId)}/approval-status`,
+      { headers: this.headers }
+    );
+    const data = res.data;
+    return {
+      status: data.status ?? "pending",
+      response: data.response,
+      requestUrl: data.request_url,
+      requestedAt: data.requested_at,
+      respondedAt: data.responded_at
+    };
+  }
+  /**
+   * Poll approval status with exponential backoff until resolved.
+   *
+   * Returns once the status is no longer `pending` (i.e. approved, rejected,
+   * or expired).
+   */
+  async waitForApproval(executionId, opts) {
+    const pollInterval = opts?.pollIntervalMs ?? 5e3;
+    const maxInterval = opts?.maxIntervalMs ?? 6e4;
+    const timeout = opts?.timeoutMs;
+    const backoffFactor = 2;
+    const startTime = Date.now();
+    let interval = pollInterval;
+    while (true) {
+      if (timeout != null && Date.now() - startTime >= timeout) {
+        throw new Error(
+          `Approval for execution ${executionId} timed out after ${timeout}ms`
+        );
+      }
+      await sleep(interval);
+      let data;
+      try {
+        data = await this.getApprovalStatus(executionId);
+      } catch {
+        interval = Math.min(interval * backoffFactor, maxInterval);
+        continue;
+      }
+      if (data.status !== "pending") {
+        return data;
+      }
+      interval = Math.min(interval * backoffFactor, maxInterval);
+    }
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export { ACTIVE_STATUSES, AIClient, Agent, AgentRouter, ApprovalClient, CANONICAL_STATUSES, DIDAuthenticator, DidClient, DidInterface, DidManager, ExecutionContext, ExecutionStatus, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, MCPClient, MCPClientRegistry, MCPToolRegistrar, MemoryClient, MemoryEventClient, MemoryInterface, RateLimitError, ReasonerContext, SkillContext, StatelessRateLimiter, TERMINAL_STATUSES, WorkflowReporter, getCurrentContext, getCurrentSkillContext, isActive, isTerminal, normalizeStatus };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map