@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/agent.md

@@ -0,0 +1,514 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.agent`: Agent
+
+8 operations (5 read, 2 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.agent.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [agent.d.ts](agent.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`cancelAgentRun`](#op-cancelagentrun) | `POST /api/v1/agent/runs/{run_id}/cancel` | destructive | `workflows:delete` | Cancel Agent Run |
+| [`createAgentRun`](#op-createagentrun) | `POST /api/v1/agent/runs` | write | `workflows:write` | Create Agent Run |
+| [`decideAgentApproval`](#op-decideagentapproval) | `POST /api/v1/agent/approvals/{approval_id}/decide` | write | `workflows:write` | Decide Agent Approval |
+| [`getAgentApprovalReceipts`](#op-getagentapprovalreceipts) | `GET /api/v1/agent/approvals/{approval_id}/receipts` | read | `workflows:read` | Get Agent Approval Receipts |
+| [`getAgentRun`](#op-getagentrun) | `GET /api/v1/agent/runs/{run_id}` | read | `workflows:read` | Get Agent Run |
+| [`listAgentApprovalHistory`](#op-listagentapprovalhistory) | `GET /api/v1/agent/approvals/history` | read | `workflows:read` | List Agent Approval History |
+| [`listAgentApprovals`](#op-listagentapprovals) | `GET /api/v1/agent/approvals` | read | `workflows:read` | List Agent Approvals |
+| [`listAgentRuns`](#op-listagentruns) | `GET /api/v1/agent/runs` | read | `workflows:read` | List Agent Runs |
+
+---
+
+<a id="op-cancelagentrun"></a>
+
+### `g8.api.agent.cancelAgentRun(input)`
+
+**Cancel Agent Run**
+
+- HTTP: `POST /api/v1/agent/runs/{run_id}/cancel`
+- operationId: `cancel_agent_run_agent_runs__run_id__cancel_post` (also callable as `g8.api.call("cancel_agent_run_agent_runs__run_id__cancel_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `workflows:delete`
+
+Stop a run and everything it spawned.
+
+OWNER ONLY, and that is stricter than the read routes on purpose: shared
+visibility lets an org SEE a teammate's run, while stopping it is
+destructive and not undone by restarting. Children are signalled before the
+root so a freed parent cannot leave orphans behind it.
+
+Idempotent on an already-terminal run: `cancelled: false` with a reason,
+not an error, so a double call does not look like a failure.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.run_id` | `string (uuid)` | yes | Run ID |
+
+**Returns** `ApiResponse_CancelAgentRunResponse_`: the envelope `{ data: CancelAgentRunResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CancelAgentRunResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `cancelled` | `boolean` | yes |  |
+| `work_item_id` | `string` | yes |  |
+| `children_cancelled` | `Array<string>` | no | Sub-agents signalled alongside the run. |
+| `detail` | `string` | no | default `""` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.agent.cancelAgentRun({ path: { run_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-createagentrun"></a>
+
+### `g8.api.agent.createAgentRun(input)`
+
+**Create Agent Run**
+
+- HTTP: `POST /api/v1/agent/runs`
+- operationId: `create_agent_run_agent_runs_post` (also callable as `g8.api.call("create_agent_run_agent_runs_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Start a durable agent run.
+
+"Run" is the public noun; the stored row is a work item and every internal
+name says so. The same translation `app_pages_router` makes for dashboards,
+and for the same reason: the public contract should read the way a builder
+thinks, not the way the table is named.
+
+`workflow_started: false` is a NORMAL outcome, not an error. The row is
+persisted either way; a false means the Temporal worker did not pick it up
+on this attempt and the reason is carried alongside it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateAgentRunRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateAgentRunRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.agent_id` | `string` | yes | 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. |
+| `body.goal` | `string` | yes | Free text the planner works from. min length 1 |
+| `body.title` | `string` | yes | min length 1, max length 500 |
+| `body.entry_point` | `string \| null` | no |  |
+| `body.seed_message` | `string \| null` | no | An opening user turn, rendered as the first message. |
+| `body.session_title` | `string \| null` | no |  |
+| `body.skill_mode` | `string \| null` | no | 'web_search' \| 'deep_thinking' \| 'research'. Unknown values are ignored. |
+| `body.subject_account_id` | `string \| null` | no | Bind the run to a company. |
+| `body.subject_campaign_id` | `string \| null` | no | Bind the run to a campaign. |
+| `body.visibility` | `string` | no | 'private' (default) keeps the run yours. 'shared' lets the organization see it, though only you can cancel it. default `"private"`, pattern `^(shared\|private)$` |
+
+**Returns** `ApiResponse_CreatedAgentRunResponse_`: the envelope `{ data: CreatedAgentRunResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CreatedAgentRunResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `session_id` | `string` | yes |  |
+| `work_item_id` | `string` | yes |  |
+| `workflow_started` | `boolean` | yes | 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_reason` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agent.createAgentRun({ body: { agent_id: "id", goal: "example", title: "Example" } });
+```
+
+---
+
+<a id="op-decideagentapproval"></a>
+
+### `g8.api.agent.decideAgentApproval(input)`
+
+**Decide Agent Approval**
+
+- HTTP: `POST /api/v1/agent/approvals/{approval_id}/decide`
+- operationId: `decide_agent_approval_agent_approvals__approval_id__decide_post` (also callable as `g8.api.call("decide_agent_approval_agent_approvals__approval_id__decide_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Approve, reject, or edit-and-approve a pending approval.
+
+Use `{decision, edit_payload}` for the existing decision mode, or exclusively
+`{use_human_authorization: true}` to relay a short-lived decision previously
+reviewed in the browser by the same personal-key owner. The relay accepts
+no caller-authored decision or edit fields. There is no client
+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.
+
+`DecideRequest` does not forbid unknown keys, so a misspelled `edit_payload`
+is dropped in silence and an `edit_and_approve` decides as a plain approve.
+This docstring is the operation description in the published contract, so
+getting it wrong here ships the wrong shape to every integrator generating a
+client from the spec, which is exactly how the earlier `expected_version` /
+`edited_payload` error nearly shipped.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.approval_id` | `string (uuid)` | yes | Approval ID |
+| `body` | `DecideAgentApprovalRequest` | yes | Request body; fields below. |
+
+Body fields (`DecideAgentApprovalRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.decision` | `"approve" \| "reject" \| "edit_and_approve" \| null` | no |  |
+| `body.edit_payload` | `Record<string, unknown> \| null` | no | The redirected step, for 'edit_and_approve'. Ignored for the other decisions. |
+| `body.use_human_authorization` | `boolean` | no | default `false` |
+
+**Returns** `ApiResponse_AgentApprovalResponse_`: the envelope `{ data: AgentApprovalResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentApprovalResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action_class` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `risk_level` | `string` | yes |  |
+| `step_id` | `string` | yes |  |
+| `summary` | `string` | yes |  |
+| `work_item_id` | `string` | yes |  |
+| `decided_at` | `string \| null` | no |  |
+| `decided_by` | `string \| null` | no |  |
+| `decision` | `string \| null` | no |  |
+| `decision_payload` | `Record<string, unknown> \| null` | no |  |
+| `detail` | `Record<string, unknown> \| null` | no |  |
+| `expires_at` | `string \| null` | no |  |
+| `is_expired` | `boolean` | no | default `false` |
+| `plan_digest` | `string \| null` | no | 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. |
+| `requested_at` | `string \| null` | no |  |
+| `snapshot_digest` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agent.decideAgentApproval({
+  path: { approval_id: "00000000-0000-0000-0000-000000000000" },
+  body: { decision: "approve" },
+});
+```
+
+---
+
+<a id="op-getagentapprovalreceipts"></a>
+
+### `g8.api.agent.getAgentApprovalReceipts(input)`
+
+**Get Agent Approval Receipts**
+
+- HTTP: `GET /api/v1/agent/approvals/{approval_id}/receipts`
+- operationId: `get_agent_approval_receipts_agent_approvals__approval_id__receipts_get` (also callable as `g8.api.call("get_agent_approval_receipts_agent_approvals__approval_id__receipts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Signed provenance receipts attributed to one approval.
+
+404 rather than 403 when the approval belongs to another tenant or to
+another user's private work item: existence never leaks across that
+boundary. Degrades to an empty list on a schema predating the receipt
+columns rather than 500ing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.approval_id` | `string (uuid)` | yes | Approval ID |
+
+**Returns** `ApiResponse_AgentApprovalReceiptsResponse_`: the envelope `{ data: AgentApprovalReceiptsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentApprovalReceiptsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `approval_id` | `string` | yes |  |
+| `receipts` | `Array<AgentApprovalReceipt>` | no | Empty rather than an error when the approval produced no receipts. |
+
+**Example**
+
+```ts
+const result = await g8.api.agent.getAgentApprovalReceipts({ path: { approval_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getagentrun"></a>
+
+### `g8.api.agent.getAgentRun(input)`
+
+**Get Agent Run**
+
+- HTTP: `GET /api/v1/agent/runs/{run_id}`
+- operationId: `get_agent_run_agent_runs__run_id__get` (also callable as `g8.api.call("get_agent_run_agent_runs__run_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Fetch one run.
+
+THE ONE ROUTE HERE THAT IS NOT PURE DELEGATION, because there is no
+`GET /v1/agent/work-items/{id}` on the JWT surface to call. Without it a
+builder can create a run, receive its id, and then have no way to poll it
+except by listing everything and filtering client-side.
+
+Its visibility rule is copied from `list_work_items`, NOT from
+`cancel_work_item`: a read may see the caller's own runs plus org-wide
+`visibility='shared'` ones, whereas cancel is owner-only because stopping
+someone else's work is destructive. Pinning the read to the stricter rule
+would hide a shared run that the list route shows, and the two disagreeing
+about the same row is worse than either answer alone.
+
+404, never 403, on a run the caller may not see: a non-owner must not be
+able to use this route to probe which runs exist in the org. Same reason
+`cancel_work_item` returns 404 for a non-owner.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.run_id` | `string (uuid)` | yes | Run ID |
+
+**Returns** `ApiResponse_AgentRunResponse_`: the envelope `{ data: AgentRunResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentRunResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `agent_id` | `string` | yes |  |
+| `created_at` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `title` | `string` | yes |  |
+| `updated_at` | `string` | yes |  |
+| `visibility` | `string` | yes |  |
+| `work_item_id` | `string` | yes |  |
+| `completed_at` | `string \| null` | no |  |
+| `credit_budget` | `integer \| null` | no |  |
+| `credits_spent` | `integer` | no | default `0` |
+| `current_step` | `string \| null` | no |  |
+| `entry_point` | `string \| null` | no |  |
+| `next_action` | `string \| null` | no |  |
+| `session_id` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agent.getAgentRun({ path: { run_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-listagentapprovalhistory"></a>
+
+### `g8.api.agent.listAgentApprovalHistory(input?)`
+
+**List Agent Approval History**
+
+- HTTP: `GET /api/v1/agent/approvals/history`
+- operationId: `list_agent_approval_history_agent_approvals_history_get` (also callable as `g8.api.call("list_agent_approval_history_agent_approvals_history_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Decided approvals, newest first, same shape as the pending list.
+
+Registered ABOVE `/approvals/{approval_id}/receipts` so the literal
+`history` segment cannot be captured as an `approval_id`. `GET
+/workflows/dispositions` 404'd in production for exactly that reason until
+2026-08-07; the ordering here is load-bearing, not cosmetic.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.decision` | `"approve" \| "reject" \| "edit_and_approve" \| "dismiss" \| null` | no | Optional filter on the recorded decision: 'approve', 'reject', 'edit_and_approve' or 'dismiss'. An unrecognised value is rejected with 422 rather than silently ignored. |
+
+**Returns** `ApiResponse_list_AgentApprovalResponse__`: the envelope `{ data: Array<AgentApprovalResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentApprovalResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action_class` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `risk_level` | `string` | yes |  |
+| `step_id` | `string` | yes |  |
+| `summary` | `string` | yes |  |
+| `work_item_id` | `string` | yes |  |
+| `decided_at` | `string \| null` | no |  |
+| `decided_by` | `string \| null` | no |  |
+| `decision` | `string \| null` | no |  |
+| `decision_payload` | `Record<string, unknown> \| null` | no |  |
+| `detail` | `Record<string, unknown> \| null` | no |  |
+| `expires_at` | `string \| null` | no |  |
+| `is_expired` | `boolean` | no | default `false` |
+| `plan_digest` | `string \| null` | no | 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. |
+| `requested_at` | `string \| null` | no |  |
+| `snapshot_digest` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agent.listAgentApprovalHistory();
+```
+
+---
+
+<a id="op-listagentapprovals"></a>
+
+### `g8.api.agent.listAgentApprovals(input?)`
+
+**List Agent Approvals**
+
+- HTTP: `GET /api/v1/agent/approvals`
+- operationId: `list_agent_approvals_agent_approvals_get` (also callable as `g8.api.call("list_agent_approvals_agent_approvals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Pending approvals this key may act on.
+
+An approval is the loop asking permission before it runs a tool. Each entry
+carries the `plan_digest` it is bound to and its `expires_at`, so a caller
+can tell an approval that still describes the plan from one that has drifted.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_AgentApprovalResponse__`: the envelope `{ data: Array<AgentApprovalResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentApprovalResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action_class` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `risk_level` | `string` | yes |  |
+| `step_id` | `string` | yes |  |
+| `summary` | `string` | yes |  |
+| `work_item_id` | `string` | yes |  |
+| `decided_at` | `string \| null` | no |  |
+| `decided_by` | `string \| null` | no |  |
+| `decision` | `string \| null` | no |  |
+| `decision_payload` | `Record<string, unknown> \| null` | no |  |
+| `detail` | `Record<string, unknown> \| null` | no |  |
+| `expires_at` | `string \| null` | no |  |
+| `is_expired` | `boolean` | no | default `false` |
+| `plan_digest` | `string \| null` | no | 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. |
+| `requested_at` | `string \| null` | no |  |
+| `snapshot_digest` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agent.listAgentApprovals();
+```
+
+---
+
+<a id="op-listagentruns"></a>
+
+### `g8.api.agent.listAgentRuns(input?)`
+
+**List Agent Runs**
+
+- HTTP: `GET /api/v1/agent/runs`
+- operationId: `list_agent_runs_agent_runs_get` (also callable as `g8.api.call("list_agent_runs_agent_runs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+List runs this key can see: its own, plus org-wide shared ones.
+
+Reconciles abandoned rows before reading, so a run whose worker was recycled
+reports `failed` rather than sitting at `running` forever.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.statuses` | `Array<string> \| null` | no | Optional repeatable status filter: ?statuses=running&statuses=queued |
+| `query.agent_id` | `string \| null` | no |  |
+| `query.include_shared` | `boolean` | no | When true (default), include org-wide shared runs. When false, return only runs this key owns. default `true` |
+| `query.limit` | `integer` | no | default `100` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_AgentRunListResponse_`: the envelope `{ data: AgentRunListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentRunListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `runs` | `Array<AgentRunResponse>` | yes |  |
+| `total` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agent.listAgentRuns();
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-agentapprovalreceipt"></a>
+
+### `AgentApprovalReceipt`
+
+One signed provenance row attributed to an approval.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes |  |
+| `entity_id` | `string` | yes |  |
+| `entity_type` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `contributed_by_role_at_time` | `string \| null` | no |  |
+| `contributed_by_user_id` | `string \| null` | no |  |
+| `metadata_json` | `Record<string, unknown> \| null` | no |  |
+| `via_api_key_id` | `string \| null` | no |  |
+| `via_campaign_id` | `string \| null` | no |  |
+| `via_import_batch_id` | `string \| null` | no |  |
+| `via_list_id` | `string \| null` | no |  |
+| `via_sequence_id` | `string \| null` | no |  |