@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/agent.d.ts

@@ -0,0 +1,330 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.agent` (Agent): 8 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"cancel_agent_run_agent_runs__run_id__cancel_post">;
+ *
+ * Reference with examples: agent.md
+ */
+/* eslint-disable */
+
+/** `g8.api.agent.<member>` -> the operationId it calls. */
+export interface AgentMembers {
+  cancelAgentRun: "cancel_agent_run_agent_runs__run_id__cancel_post";
+  createAgentRun: "create_agent_run_agent_runs_post";
+  decideAgentApproval: "decide_agent_approval_agent_approvals__approval_id__decide_post";
+  getAgentApprovalReceipts: "get_agent_approval_receipts_agent_approvals__approval_id__receipts_get";
+  getAgentRun: "get_agent_run_agent_runs__run_id__get";
+  listAgentApprovalHistory: "list_agent_approval_history_agent_approvals_history_get";
+  listAgentApprovals: "list_agent_approvals_agent_approvals_get";
+  listAgentRuns: "list_agent_runs_agent_runs_get";
+}
+
+/** Input and output of every `g8.api.agent` operation, keyed by operationId. */
+export interface AgentOperations {
+  /**
+   * POST /agent/runs/{run_id}/cancel
+   * Cancel Agent Run
+   * tier: destructive · scope: workflows:delete
+   */
+  cancel_agent_run_agent_runs__run_id__cancel_post: {
+    input: {
+    path: {
+      /** Run ID */
+      run_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CancelAgentRunResponse_;
+  };
+  /**
+   * POST /agent/runs
+   * Create Agent Run
+   * tier: write · scope: workflows:write
+   */
+  create_agent_run_agent_runs_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateAgentRunRequest;
+  };
+    output: ApiResponse_CreatedAgentRunResponse_;
+  };
+  /**
+   * POST /agent/approvals/{approval_id}/decide
+   * Decide Agent Approval
+   * tier: write · scope: workflows:write
+   */
+  decide_agent_approval_agent_approvals__approval_id__decide_post: {
+    input: {
+    path: {
+      /** Approval ID */
+      approval_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: DecideAgentApprovalRequest;
+  };
+    output: ApiResponse_AgentApprovalResponse_;
+  };
+  /**
+   * GET /agent/approvals/{approval_id}/receipts
+   * Get Agent Approval Receipts
+   * tier: read · scope: workflows:read
+   */
+  get_agent_approval_receipts_agent_approvals__approval_id__receipts_get: {
+    input: {
+    path: {
+      /** Approval ID */
+      approval_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AgentApprovalReceiptsResponse_;
+  };
+  /**
+   * GET /agent/runs/{run_id}
+   * Get Agent Run
+   * tier: read · scope: workflows:read
+   */
+  get_agent_run_agent_runs__run_id__get: {
+    input: {
+    path: {
+      /** Run ID */
+      run_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AgentRunResponse_;
+  };
+  /**
+   * GET /agent/approvals/history
+   * List Agent Approval History
+   * tier: read · scope: workflows:read
+   */
+  list_agent_approval_history_agent_approvals_history_get: {
+    input: {
+    query?: {
+      /** Optional filter on the recorded decision: 'approve', 'reject', 'edit_and_approve' or 'dismiss'. An unrecognised value is rejected with 422 rather than silently ignored. */
+      decision?: ("approve" | "reject" | "edit_and_approve" | "dismiss") | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_AgentApprovalResponse__;
+  };
+  /**
+   * GET /agent/approvals
+   * List Agent Approvals
+   * tier: read · scope: workflows:read
+   */
+  list_agent_approvals_agent_approvals_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_AgentApprovalResponse__;
+  };
+  /**
+   * GET /agent/runs
+   * List Agent Runs
+   * tier: read · scope: workflows:read
+   */
+  list_agent_runs_agent_runs_get: {
+    input: {
+    query?: {
+      /** Optional repeatable status filter: ?statuses=running&statuses=queued */
+      statuses?: Array<string> | null;
+      agent_id?: string | null;
+      /** When true (default), include org-wide shared runs. When false, return only runs this key owns. */
+      include_shared?: boolean;
+      limit?: number;
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AgentRunListResponse_;
+  };
+}
+
+// 17 schemas referenced above (the same as G8Contract.<Name>).
+
+/** One signed provenance row attributed to an approval. */
+export interface AgentApprovalReceipt {
+  action: string;
+  contributed_by_role_at_time?: string | null;
+  contributed_by_user_id?: string | null;
+  entity_id: string;
+  entity_type: string;
+  id: string;
+  metadata_json?: Record<string, unknown> | null;
+  via_api_key_id?: string | null;
+  via_campaign_id?: string | null;
+  via_import_batch_id?: string | null;
+  via_list_id?: string | null;
+  via_sequence_id?: string | null;
+}
+
+export interface AgentApprovalReceiptsResponse {
+  approval_id: string;
+  /** Empty rather than an error when the approval produced no receipts. */
+  receipts?: Array<AgentApprovalReceipt>;
+}
+
+/** One approval: the loop asking permission before a consequential step. */
+export interface AgentApprovalResponse {
+  action_class: string;
+  decided_at?: string | null;
+  decided_by?: string | null;
+  decision?: string | null;
+  decision_payload?: Record<string, unknown> | null;
+  detail?: Record<string, unknown> | null;
+  expires_at?: string | null;
+  id: string;
+  is_expired?: boolean;
+  /** The plan this approval was bound to. Compare it to the run's current plan to tell an approval that still describes the work from one that has drifted. */
+  plan_digest?: string | null;
+  requested_at?: string | null;
+  risk_level: string;
+  snapshot_digest?: string | null;
+  step_id: string;
+  summary: string;
+  work_item_id: string;
+}
+
+export interface AgentRunListResponse {
+  runs: Array<AgentRunResponse>;
+  total: number;
+}
+
+/** One run. Identical shape whether read from the list or on its own. */
+export interface AgentRunResponse {
+  agent_id: string;
+  completed_at?: string | null;
+  created_at: string;
+  credit_budget?: number | null;
+  credits_spent?: number;
+  current_step?: string | null;
+  entry_point?: string | null;
+  next_action?: string | null;
+  session_id?: string | null;
+  status: string;
+  title: string;
+  updated_at: string;
+  visibility: string;
+  work_item_id: string;
+}
+
+export interface ApiResponse_AgentApprovalReceiptsResponse_ {
+  data: AgentApprovalReceiptsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AgentApprovalResponse_ {
+  data: AgentApprovalResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AgentRunListResponse_ {
+  data: AgentRunListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_AgentRunResponse_ {
+  data: AgentRunResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CancelAgentRunResponse_ {
+  data: CancelAgentRunResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CreatedAgentRunResponse_ {
+  data: CreatedAgentRunResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_AgentApprovalResponse__ {
+  data: Array<AgentApprovalResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface CancelAgentRunResponse {
+  cancelled: boolean;
+  /** Sub-agents signalled alongside the run. */
+  children_cancelled?: Array<string>;
+  detail?: string;
+  work_item_id: string;
+}
+
+/** Start a durable agent run. See the module docstring for what is omitted. */
+export interface CreateAgentRunRequest {
+  /** Which agent drives the loop: 'onboarding', 'dialer_setup', 'sequencer_setup', 'campaign_run', 'voice_setup', 'marketplace', 'dev_setup', or a free-form value for an ad-hoc session. */
+  agent_id: string;
+  entry_point?: string | null;
+  /** Free text the planner works from. */
+  goal: string;
+  /** An opening user turn, rendered as the first message. */
+  seed_message?: string | null;
+  session_title?: string | null;
+  /** 'web_search' | 'deep_thinking' | 'research'. Unknown values are ignored. */
+  skill_mode?: string | null;
+  /** Bind the run to a company. */
+  subject_account_id?: string | null;
+  /** Bind the run to a campaign. */
+  subject_campaign_id?: string | null;
+  title: string;
+  /** 'private' (default) keeps the run yours. 'shared' lets the organization see it, though only you can cancel it. */
+  visibility?: string;
+}
+
+export interface CreatedAgentRunResponse {
+  session_id: string;
+  work_item_id: string;
+  /** False is NORMAL, not an error: the run is stored either way and no worker picked it up on this attempt. Poll the run rather than retrying the create, which would start a second one. */
+  workflow_started: boolean;
+  workflow_started_reason?: string | null;
+}
+
+/**
+ * Decide directly, or relay a stored human authorization exclusively.
+ *
+ * There is no client-supplied version to pass. Double-decide is settled
+ * server-side by `WHERE decided_at IS NULL`, so exactly one caller wins and the
+ * loser gets 409 rather than overwriting the first decision.
+ */
+export type DecideAgentApprovalRequest = ({
+  decision: "approve" | "reject" | "edit_and_approve";
+  use_human_authorization?: false;
+}) | {
+  use_human_authorization: true;
+};
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}