@tangle-network/hub-sdk 0.2.2 → 0.3.0

package/README.md

@@ -125,11 +125,50 @@ const hub = HubClient.fromEnv({
 });
 ```
 
+## Workflows
+
+`hub.workflows` covers the `/v1/workflows` surface — the same resource the
+platform web UI and the `tangle workflows` CLI drive. It authenticates with the
+`sk-tan-*` API key (or a session), **not** a hub capability token. Alongside
+CRUD (`list`/`get`/`create`/`update`/`delete`), `setEnabled`, `validate`, and
+`schema`, it can trigger and observe runs:
+
+```ts
+const hub = HubClient.fromEnv();
+
+// Trigger a run with the trigger fields the workflow reads, then wait for it.
+const { runId } = await hub.workflows.run("wf_123", {
+  "pull_request.number": "123",
+});
+const run = await hub.workflows.waitForRun("wf_123", runId, {
+  timeoutMs: 300_000,
+});
+console.log(run.status, run.actionResults);
+
+// Or tail live progress as it executes.
+for await (const event of hub.workflows.watchRun("wf_123", runId)) {
+  if (event.type === "token") process.stdout.write(event.delta);
+  if (event.type === "run.done") console.log("\n", event.status);
+}
+
+// One page of run history + a single run's full detail.
+const { runs, nextCursor } = await hub.workflows.listRuns("wf_123");
+const detail = await hub.workflows.getRun("wf_123", runs[0].id);
+```
+
+`run` throws `HubSdkError` with `MISSING_RUN_INPUTS` (the workflow reads trigger
+fields none were supplied for — `details.missing` names them) or
+`WORKFLOW_DISABLED` (enable it first). `waitForRun` throws
+`WORKFLOW_RUN_TIMEOUT` if the run has not finished within `timeoutMs`. Live
+`watchRun` ticks require the worker executing the run to share the API process;
+across instances only `snapshot` + `run.done` arrive, and the persisted record
+read via `getRun` stays the source of truth.
+
 ## Exports
 
 - `HubClient`, `HubClient.fromEnv(options?)`
 - `HubConnectionsClient`, `HubPermissionsClient`, `HubTokensClient`,
-  `HubToolsClient`, `HubApprovalsClient`, `HubAuditClient`
+  `HubToolsClient`, `HubApprovalsClient`, `HubAuditClient`, `HubWorkflowsClient`
 - `HubSdkError` — typed `code: HubErrorCode`, redacted `details`, optional
   HTTP `status`
 - `HUB_URL_ENV_VAR`, `HUB_API_KEY_ENV_VAR`, `HUB_CAPABILITY_TOKEN_ENV_VAR` —

package/dist/index.d.ts

@@ -14,7 +14,7 @@ interface HubErrorBody {
   message: string;
   details?: unknown;
 }
-type HubErrorCode = "HUB_UNAUTHENTICATED" | "HUB_FORBIDDEN" | "HUB_INVALID_INPUT" | "HUB_PROVIDER_MISSING" | "HUB_CONNECTION_MISSING" | "HUB_CONNECTION_REVOKED" | "HUB_TOKEN_EXPIRED" | "HUB_TOKEN_REPLAYED" | "HUB_TOKEN_REVOKED" | "HUB_TOKEN_ACTION_MISMATCH" | "HUB_POLICY_DENIED" | "HUB_APPROVAL_REQUIRED" | "HUB_EXECUTOR_FAILURE" | "HUB_PROVIDER_FAILURE" | "HUB_CONFIG_MISSING" | "HUB_CONFIG_INVALID" | "HUB_NOT_FOUND" | "HUB_NOT_IMPLEMENTED";
+type HubErrorCode = "HUB_UNAUTHENTICATED" | "HUB_FORBIDDEN" | "HUB_INVALID_INPUT" | "HUB_INVALID_STATE" | "HUB_PROVIDER_MISSING" | "HUB_CONNECTION_MISSING" | "HUB_CONNECTION_REVOKED" | "HUB_TOKEN_EXPIRED" | "HUB_TOKEN_REPLAYED" | "HUB_TOKEN_REVOKED" | "HUB_TOKEN_ACTION_MISMATCH" | "HUB_POLICY_DENIED" | "HUB_APPROVAL_REQUIRED" | "HUB_EXECUTOR_FAILURE" | "HUB_PROVIDER_FAILURE" | "HUB_CONFIG_MISSING" | "HUB_CONFIG_INVALID" | "HUB_NOT_FOUND" | "HUB_NOT_IMPLEMENTED" | "HUB_CONFLICT" | "VALIDATION_ERROR" | "WORKFLOW_INVALID" | "NOT_FOUND" | "UNAUTHORIZED" | "CONFLICT" | "MISSING_RUN_INPUTS" | "WORKFLOW_DISABLED" | "PAYLOAD_TOO_LARGE" | "WORKFLOW_RUN_TIMEOUT" | `HUB_HTTP_${number}`;
 interface HubStatusResponse {
   contract: unknown;
   principal: HubPrincipal;
@@ -46,6 +46,39 @@ interface HubConnection {
 interface HubConnectionsResponse {
   connections: HubConnection[];
 }
+/** A connector's auth model. */
+type HubProviderAuthKind = "oauth2" | "api_key" | "none" | "custom";
+interface HubProvider {
+  providerId: string;
+  title: string;
+  /** The connector's auth model. */
+  authKind: HubProviderAuthKind;
+  /** For api-key connectors, the manifest's free-text hint shown when
+   *  collecting the key (e.g. "Paste your Airtable personal access token");
+   *  null for OAuth/native providers that don't collect a key inline. */
+  authHint: string | null;
+  category: string;
+  scopes: string[];
+  /** Actions + trigger events combined (legacy census; prefer the split
+   *  counts below when present). */
+  capabilityCount: number;
+  /** Actions callable via `integration.invoke`. Absent on older servers, and
+   *  for native GitHub when the executor catalog is unavailable. */
+  actionCount?: number;
+  /** Trigger events the connector delivers (not invokable). Absent on older
+   *  servers. */
+  triggerCount?: number;
+  /** True for the native GitHub path; false for substrate-bundled connectors. */
+  native: boolean;
+  /** True when the provider's OAuth app credentials are wired, i.e. a connect
+   *  flow can actually start. UIs offer Connect only for configured providers. */
+  configured: boolean;
+}
+interface HubProvidersResponse {
+  providers: HubProvider[];
+  /** Count of substrate-bundled connector manifests behind this catalog. */
+  substrateBundled: number;
+}
 interface HubOAuthStartRequest {
   provider: string;
   returnUrl?: string;
@@ -72,12 +105,51 @@ interface HubOAuthStartResponse {
   scopes: string[];
   cli: boolean;
 }
+interface HubWhatsappEmbeddedSignupStartRequest {
+  returnUrl?: string;
+}
+interface HubWhatsappEmbeddedSignupStartResponse {
+  provider: "whatsapp-business";
+  appId: string;
+  configId: string;
+  sdkVersion: string;
+  state: string;
+  expiresAt: string;
+  scopes: string[];
+}
+interface HubWhatsappEmbeddedSignupCompleteRequest {
+  code: string;
+  state: string;
+  wabaId: string;
+  phoneNumberId: string;
+  businessId?: string;
+  flowEvent?: string;
+}
+interface HubWhatsappEmbeddedSignupCompleteResponse {
+  connectionId: string;
+  provider: "whatsapp-business";
+  reconnected: boolean;
+  connection: HubConnection | null;
+}
 interface HubOAuthCallbackResponse {
   connectionId: string;
   provider: string;
   cli: boolean;
   reconnected: boolean;
 }
+/** Connect a non-OAuth (api-key) connector by submitting the user's key. The
+ *  server validates the key with a live probe before persisting; `provider` is
+ *  carried in the path, `apiKey` in the body. */
+interface HubApiKeyConnectRequest {
+  provider: string;
+  apiKey: string;
+}
+/** Result of an api-key connect: the created (or reconnected) connection.
+ *  Synchronous — there is no redirect leg, unlike the OAuth flow. */
+interface HubApiKeyConnectResponse {
+  connection: HubConnection;
+  reconnected: boolean;
+}
 interface HubConnectionDeleteRequest {
   connectionId: string;
 }
@@ -110,6 +182,10 @@ interface HubToolSource {
   health: "healthy" | "unhealthy" | "rate_limited" | "unknown";
   configured: boolean;
 }
+/** Per-tool catalog risk class. The first three mirror the platform's
+ *  `HubActionRisk`; `unknown` is surfaced honestly for tools the catalog can't
+ *  classify (substrate connectors). */
+type HubToolRisk = "read" | "write" | "destructive" | "unknown";
 interface HubTool {
   path: string;
   providerId?: string;
@@ -121,6 +197,7 @@ interface HubTool {
   connectionStatus?: "connected" | "missing" | "unknown";
   requiredConnectionProviderId?: string;
   policyState?: "allow" | "ask" | "deny" | "unknown";
+  risk?: HubToolRisk;
 }
 interface HubToolSourcesResponse {
   sources: HubToolSource[];
@@ -184,6 +261,16 @@ interface HubPolicyUpdateRequest {
 interface HubPolicyListRequest {
   connectionId: string;
 }
+interface HubPolicyDeleteRequest {
+  connectionId: string;
+  actionPath: string;
+}
+interface HubPolicyDeleteResponse {
+  connectionId: string;
+  actionPath: string;
+  /** Whether a stored override existed and was removed (false = already default). */
+  deleted: boolean;
+}
 interface HubPolicy {
   id: string;
   connectionId: string;
@@ -199,6 +286,20 @@ interface HubPolicyResponse {
 interface HubPolicyListResponse {
   policies: HubPolicy[];
 }
+interface HubAllowWritesResponse {
+  connectionId: string;
+  providerId: string;
+  /** Write actions the connection's provider exposes. */
+  writeActions: number;
+  /** Rows newly created (excludes actions that already had a policy). */
+  granted: number;
+  actionPaths: string[];
+}
+interface HubRevertWritesResponse {
+  connectionId: string;
+  /** `allow_writes` rows deleted. */
+  reverted: number;
+}
 type HubApprovalStatus = "pending" | "approved" | "denied" | "expired" | "consumed";
 interface HubApproval {
   id: string;
@@ -298,6 +399,253 @@ interface HubGithubAppIsRepoInstalledResponse {
   installed: boolean;
   installationId: number | null;
 }
+interface HubWorkflowAction {
+  kind: string;
+  config: Record<string, unknown>;
+}
+/** Inbound-event matcher for a `provider_event` trigger. */
+interface HubWorkflowEventFilter {
+  event: string;
+  action?: string;
+  repo?: string;
+}
+interface HubWorkflowTrigger {
+  id: string;
+  kind: "provider_event" | "schedule";
+  enabled: boolean;
+  provider: string | null;
+  connectionId: string | null;
+  eventFilter: HubWorkflowEventFilter | null;
+  cron: string | null;
+  timezone: string | null;
+  nextFireAt: string | null;
+  lastFiredAt: string | null;
+}
+interface HubWorkflowValidationError {
+  path: string;
+  message: string;
+}
+type HubWorkflowRunStatus = "queued" | "running" | "waiting" | "succeeded" | "failed" | "cancelled";
+/** One agent iteration of an `agent.run`, as the single-run detail carries it
+ *  (JSON-clean ISO timestamps) — including the round's own output `text`. */
+interface HubAgentIterationSpan {
+  index: number;
+  name: string;
+  status: "succeeded" | "failed";
+  startedAt: string;
+  completedAt: string;
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  costUsd?: number;
+  error?: string;
+  text?: string;
+}
+/** An `agent.run`'s execution detail (single-run detail endpoint): per-iteration
+ *  spans plus aggregate usage, present on success AND failure. `partialText` is
+ *  failure-only — on success the final text is the action's `output`. */
+interface HubAgentRunDetail {
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  costUsd?: number;
+  partialText?: string;
+  iterations?: HubAgentIterationSpan[];
+}
+/** Per-action result inside a run. `output` on success, `error` on failure. */
+interface HubWorkflowActionResult {
+  index: number;
+  kind: string;
+  /** `running` is the provisional in-flight status the run-history list and
+   *  single-run detail endpoints return for an action of a run that is still
+   *  executing (reconciled to `failed` only once the run itself reaches a
+   *  terminal state); a consumer polling either endpoint can observe it.
+   *  `skipped` is an action whose `if` guard resolved false, so it never ran —
+   *  terminal and distinct from `failed` (it has no `output`, `error`, or cost). */
+  status: "succeeded" | "failed" | "running" | "skipped";
+  /**
+   * Action output on success. Present on the single-run detail endpoint;
+   * intentionally omitted from the paginated run-history list response (an
+   * output can be an arbitrarily large response body, and the list would
+   * otherwise carry unbounded payloads), so it is absent there.
+   */
+  output?: unknown;
+  error?: string;
+  costUsd?: number;
+  /** `agent.run` only (single-run detail): the agent's execution detail —
+   *  per-iteration spans (each with text), aggregate usage, partial text. */
+  agentRun?: HubAgentRunDetail;
+}
+/** A single workflow run, as returned by the run-history endpoint. */
+interface HubWorkflowRun {
+  id: string;
+  status: HubWorkflowRunStatus;
+  actionResults: HubWorkflowActionResult[];
+  /** Terminal run error (credit-exhausted, connection revoked, …); null on a clean run. */
+  error: string | null;
+  attempts: number;
+  /** Single-run detail only: the definition YAML captured at enqueue (null for
+   *  runs from before snapshots, or a workflow with no stored definition). */
+  definitionSnapshot?: string | null;
+  /** Single-run detail only: the trigger payload/context the run executed
+   *  against (capped server-side). Absent on the paginated list. */
+  triggerContext?: unknown;
+  createdAt: string;
+  startedAt: string | null;
+  completedAt: string | null;
+}
+/**
+ * A single run as returned by the single-run detail endpoint
+ * (`GET /v1/workflows/:id/runs/:runId`) and carried in the `snapshot` stream
+ * event. Unlike a run-history list item it always carries `workflowId` and the
+ * per-action `output` / `agentRun` detail (all size-capped server-side).
+ */
+interface HubWorkflowRunDetail extends HubWorkflowRun {
+  workflowId: string;
+  /** The detail endpoint always returns these (unlike the run-history list,
+   *  where they're absent) — narrowed to required here so a consumer of
+   *  `getRun` / a `snapshot` event reads them without re-checking presence. */
+  triggerContext: unknown;
+  definitionSnapshot: string | null;
+}
+/**
+ * The trigger fields a manual "Run now" supplies, as a flat `{ path: value }`
+ * map (e.g. `{ "pull_request.number": "123" }`). Keys are the `path`s of the
+ * workflow's {@link HubManualRunInput}s; the server nests them into a trigger
+ * context so the run resolves exactly as a real trigger delivery would.
+ */
+type HubWorkflowRunInputs = Record<string, string>;
+/** Response of a manual run enqueue (`POST /v1/workflows/:id/run`). */
+interface HubWorkflowRunEnqueued {
+  runId: string;
+}
+/**
+ * Result of cancelling a run (`POST /v1/workflows/:id/runs/:runId/cancel`).
+ *
+ * `cancelled` — a `queued` run was stopped synchronously in the store; it is
+ * already terminal. `cancelling` — a `running` run was signalled to abort; it
+ * settles `cancelled` a moment later as its in-flight action tears down. Observe
+ * the true terminal state via {@link HubWorkflowRunDetail} (`getRun`) or the run
+ * event stream (`watchRun`). A finished run throws `HubSdkError` with code
+ * `RUN_NOT_CANCELLABLE`; an unknown/foreign run throws `NOT_FOUND`.
+ */
+interface HubWorkflowRunCancelResult {
+  runId: string;
+  status: "cancelled" | "cancelling";
+  /** Only on a `cancelling` result: whether the abort reached a worker running
+   *  this run on the API instance that served the request. `false` → the run
+   *  just finished, or executes on another instance and will stop on its own;
+   *  watch/poll the run to confirm it settled `cancelled`. */
+  signalled?: boolean;
+}
+/**
+ * A live event from a run's SSE stream (`GET /v1/workflows/:id/runs/:runId/events`),
+ * as surfaced by {@link HubWorkflowsClient.watchRun}. `snapshot` is the current
+ * persisted run detail sent first; the lifecycle/token events mirror the run as
+ * it executes; `ping` is a keepalive; `run.done` is terminal and closes the
+ * stream. Unknown server event types are dropped rather than surfaced, so new
+ * event kinds don't break older clients.
+ */
+type HubWorkflowRunStreamEvent = {
+  type: "snapshot";
+  run: HubWorkflowRunDetail;
+} | {
+  type: "action.started";
+  index: number;
+  kind: string;
+  at: string;
+} | {
+  type: "action.finished";
+  index: number;
+  kind: string;
+  status: "succeeded" | "failed" | "skipped";
+  costUsd?: number;
+  error?: string;
+  at: string;
+} | {
+  type: "iteration.started";
+  actionIndex: number;
+  iterationIndex: number;
+  model?: string;
+  at: string;
+} | {
+  type: "iteration.ended";
+  actionIndex: number;
+  iterationIndex: number;
+  status: "succeeded" | "failed";
+  outputPreview?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  costUsd?: number;
+  at: string;
+} | {
+  type: "token";
+  actionIndex: number;
+  delta: string;
+  at: string;
+} | {
+  type: "ping";
+} | {
+  type: "run.done";
+  status: "succeeded" | "failed" | "cancelled";
+  error?: string | null;
+  at?: string;
+} | {
+  type: "run.waiting";
+  decisionId: string;
+  at?: string;
+};
+/** Latest-run snapshot attached to each workflow on the list response. */
+interface HubWorkflowRunSummary {
+  id: string;
+  status: HubWorkflowRunStatus;
+  error: string | null;
+  createdAt: string;
+  completedAt: string | null;
+}
+/** One page of run history; `nextCursor` is null on the last page. */
+interface HubWorkflowRunsPage {
+  runs: HubWorkflowRun[];
+  nextCursor: string | null;
+}
+interface HubWorkflow {
+  id: string;
+  name: string;
+  description: string | null;
+  enabled: boolean;
+  /** Compiled engine actions (connection refs resolved to ids). */
+  actions: HubWorkflowAction[];
+  /** The durable YAML this workflow compiled from. */
+  definitionYaml: string | null;
+  validationErrors: HubWorkflowValidationError[];
+  /** Present on get/create/update detail responses; omitted on list. */
+  triggers?: HubWorkflowTrigger[];
+  /** Present on the detail response: the trigger fields a manual run must supply,
+   *  derived from the definition's `${trigger.*}` references (empty when none). */
+  manualRunInputs?: HubManualRunInput[];
+  /** Present on the list response (latest run, or null if never run); omitted on detail. */
+  lastRun?: HubWorkflowRunSummary | null;
+  createdAt: string;
+  updatedAt: string;
+}
+/** A trigger field a manual "Run now" must supply (derived from the
+ *  definition's `${trigger.*}` references). `required` is false only when every
+ *  read is wrapped in a `default(...)`. */
+interface HubManualRunInput {
+  path: string;
+  required: boolean;
+}
+type HubWorkflowValidateResponse = {
+  valid: true;
+  name: string;
+  actionCount: number;
+  triggerCount: number;
+} | {
+  valid: false;
+  errors: HubWorkflowValidationError[];
+};
+/** JSON Schema for the YAML workflow definition. */
+type HubWorkflowSchemaResponse = Record<string, unknown>;
 //#endregion
 //#region src/client.d.ts
 type HubAuthHeaders = () => HeadersInit | Promise<HeadersInit>;
@@ -339,10 +687,23 @@ declare class HubClient {
   readonly approvals: HubApprovalsClient;
   readonly audit: HubAuditClient;
   readonly githubApp: HubGithubAppClient;
+  readonly workflows: HubWorkflowsClient;
   constructor(options: HubClientOptions);
   static fromEnv(options?: HubClientFromEnvOptions): HubClient;
   status(): Promise<HubStatusResponse>;
   private request;
+  /**
+   * Open a streaming (Server-Sent Events) response and return its raw body.
+   * Shares auth-header building + `fetch` with {@link request}, but does NOT
+   * buffer or JSON-parse the body — the caller consumes the stream.
+   *
+   * A successful stream comes back as `text/event-stream`. Anything else is an
+   * error envelope (404/429/401 JSON) or a transport failure (gateway/HTML
+   * page); it is surfaced the same way {@link request} surfaces errors — a
+   * typed `HubSdkError` from a `{success:false}` envelope, otherwise an
+   * `HUB_HTTP_<status>` transport error — rather than handed back as bogus SSE.
+   */
+  private stream;
   private buildHeaders;
 }
 interface HubTokenListOptions {
@@ -365,9 +726,25 @@ declare class HubPermissionsClient {
   constructor(request: <TData>(path: string, init: RequestInit) => Promise<TData>);
   list(connectionId: string): Promise<HubPolicyListResponse>;
   set(input: HubPolicyUpdateRequest): Promise<HubPolicyResponse>;
+  /** Reset an action to its default by deleting any stored override. */
+  delete(input: HubPolicyDeleteRequest): Promise<HubPolicyDeleteResponse>;
+  /** Bulk-allow every write action of a connection's provider. Reads are
+   *  already allowed for sandbox agents; destructive actions stay `ask`.
+   *  Idempotent: actions with an existing policy are left untouched. */
+  allowWrites(connectionId: string): Promise<HubAllowWritesResponse>;
+  /** Inverse of `allowWrites`: delete only the rows it created for this
+   *  connection. Manual per-action decisions are left intact. */
+  revertWrites(connectionId: string): Promise<HubRevertWritesResponse>;
 }
 interface HubToolSearchOptions {
   provider?: string;
+  /** Max tools to return. The server defaults to a relevance-ranked shortlist
+   *  (20); pass a higher value (bounded server-side) to enumerate a provider's
+   *  full action list, e.g. for a catalog/browse UI. The cap bounds the MERGED
+   *  response across sources — with no `provider` set, a low limit can exclude
+   *  some providers' tools, so scope by `provider` when you need one connector's
+   *  complete list. */
+  limit?: number;
 }
 interface HubToolInvokeOptions {
   connectionId?: string;
@@ -390,7 +767,18 @@ declare class HubConnectionsClient {
   private readonly request;
   constructor(request: <TData>(path: string, init: RequestInit) => Promise<TData>);
   list(): Promise<HubConnectionsResponse>;
+  /** Connector catalog: every provider the hub can expose, each flagged with
+   *  `configured` (whether its OAuth app credentials are wired). Callers render
+   *  this alongside `list()` to offer Connect for not-yet-connected providers. */
+  providers(): Promise<HubProvidersResponse>;
   start(provider: string, options?: HubConnectionStartOptions): Promise<HubOAuthStartResponse>;
+  startWhatsappEmbeddedSignup(options?: HubWhatsappEmbeddedSignupStartRequest): Promise<HubWhatsappEmbeddedSignupStartResponse>;
+  completeWhatsappEmbeddedSignup(input: HubWhatsappEmbeddedSignupCompleteRequest): Promise<HubWhatsappEmbeddedSignupCompleteResponse>;
+  /** Connect a non-OAuth (api-key) connector by submitting the user's key.
+   *  The server validates the key with a live probe before persisting and
+   *  returns the created (or reconnected) connection — there is no redirect,
+   *  unlike `start`. */
+  connectApiKey(provider: string, apiKey: string): Promise<HubApiKeyConnectResponse>;
   revoke(connectionId: string): Promise<HubConnectionDeleteResponse>;
   health(connectionId: string): Promise<HubConnectionHealthResponse>;
 }
@@ -417,9 +805,108 @@ declare class HubAuditClient {
   constructor(request: <TData>(path: string, init: RequestInit) => Promise<TData>);
   list(options?: HubAuditListRequest): Promise<HubAuditResponse>;
 }
+declare class HubWorkflowsClient {
+  private readonly request;
+  private readonly stream?;
+  constructor(request: <TData>(path: string, init: RequestInit) => Promise<TData>, stream?: ((path: string, init: RequestInit) => Promise<ReadableStream<Uint8Array>>) | undefined);
+  list(): Promise<HubWorkflow[]>;
+  get(id: string): Promise<HubWorkflow>;
+  create(yaml: string): Promise<HubWorkflow>;
+  update(id: string, yaml: string): Promise<HubWorkflow>;
+  delete(id: string): Promise<void>;
+  /**
+   * Enable or disable a workflow without editing its YAML. Works even when the
+   * workflow's connection was revoked (a disabled workflow can't be recompiled
+   * via `update`, but it can still be paused/resumed here).
+   */
+  setEnabled(id: string, enabled: boolean): Promise<HubWorkflow>;
+  /**
+   * One page of run history, newest first. Pass the previous page's
+   * `nextCursor` to fetch the next; a null `nextCursor` means the last page.
+   */
+  listRuns(id: string, opts?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<HubWorkflowRunsPage>;
+  /**
+   * Enqueue an immediate ("Run now") run and return its `runId`. The run goes
+   * through the identical execution path a trigger delivery uses.
+   *
+   * `inputs` supplies the trigger fields the workflow reads (its
+   * {@link HubWorkflow.manualRunInputs}), as a flat `{ path: value }` map — e.g.
+   * `{ "pull_request.number": "123" }`. Omit it for a one-click run of a
+   * workflow that reads no trigger fields. Throws `HubSdkError`:
+   * `MISSING_RUN_INPUTS` when a required field is absent (`details.missing`
+   * names them), `WORKFLOW_DISABLED` when the workflow is paused, `NOT_FOUND`
+   * for an unknown/foreign id. Pass `opts.signal` to abort a slow request.
+   */
+  run(id: string, inputs?: HubWorkflowRunInputs, opts?: {
+    signal?: AbortSignal;
+  }): Promise<HubWorkflowRunEnqueued>;
+  /**
+   * A single run's full detail: per-action `output` + `agentRun` execution
+   * detail (size-capped server-side) and the trigger context — the deep "why
+   * did this run do what it did" view. `NOT_FOUND` when the run is unknown or
+   * does not belong to both the caller and this workflow.
+   */
+  getRun(id: string, runId: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<HubWorkflowRunDetail>;
+  /**
+   * Stop a queued or in-flight run. A `queued` run is cancelled synchronously
+   * and comes back `{ status: "cancelled" }` (already terminal); a `running` run
+   * is signalled to abort and comes back `{ status: "cancelling", signalled }` —
+   * it settles `cancelled` a moment later as its current action tears down, which
+   * a {@link watchRun}/{@link getRun} observes. Throws `HubSdkError`:
+   * `RUN_NOT_CANCELLABLE` when the run already finished, `NOT_FOUND` for an
+   * unknown/foreign run id. Pass `opts.signal` to abort a slow request.
+   */
+  cancel(id: string, runId: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<HubWorkflowRunCancelResult>;
+  /**
+   * Stream a run's live progress as an async iterable of typed events. The
+   * first event is always a `snapshot` of the current persisted state; then
+   * `action.*` / `iteration.*` / `token` ticks arrive as the run executes;
+   * `ping` is a keepalive; a terminal `run.done` ends the iteration. If the run
+   * is already finished when the stream opens, it yields the snapshot then
+   * `run.done` and completes.
+   *
+   * Live ticks require the worker executing the run to share the API process;
+   * across instances only `snapshot` + `run.done` (from the server's terminal
+   * poll) arrive — the persisted record, read via {@link getRun}, stays the
+   * source of truth. Pass `signal` to cancel; iterating to `run.done` (or
+   * breaking early) releases the connection.
+   */
+  watchRun(id: string, runId: string, opts?: {
+    signal?: AbortSignal;
+  }): AsyncGenerator<HubWorkflowRunStreamEvent>;
+  /**
+   * Poll {@link getRun} until the run reaches a terminal state (`succeeded` or
+   * `failed`) and return its detail. The scripting primitive behind "run and
+   * print the result": pairs with {@link run} for a one-call trigger-and-wait.
+   *
+   * Returns as soon as the run leaves the active set (`queued` / `running`) —
+   * i.e. on `succeeded`, `failed`, or any future non-active status — so a new
+   * terminal state can never hang the wait. Polls every `pollIntervalMs`
+   * (default 2000). With `timeoutMs` set, throws
+   * `HubSdkError(WORKFLOW_RUN_TIMEOUT)` — carrying the last observed status on
+   * `details.status` — only once the deadline has actually passed; the last
+   * wait is clamped to the remaining time so a `timeoutMs` shorter than the
+   * poll interval still waits the full requested window rather than giving up a
+   * poll early. Pass `signal` to cancel the wait between polls.
+   */
+  waitForRun(id: string, runId: string, opts?: {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+  }): Promise<HubWorkflowRunDetail>;
+  validate(yaml: string): Promise<HubWorkflowValidateResponse>;
+  schema(): Promise<HubWorkflowSchemaResponse>;
+}
 //#endregion
 //#region src/redaction.d.ts
 declare function redactHubValue(value: unknown): unknown;
 //#endregion
-export { HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, type HubApproval, type HubApprovalCapabilityToken, type HubApprovalDecisionResponse, type HubApprovalStatus, HubApprovalsClient, HubAuditClient, type HubAuditEvent, type HubAuditListRequest, type HubAuditResponse, type HubAuthHeaders, type HubCapabilityToken, HubClient, type HubClientFromEnvOptions, type HubClientOptions, type HubConnection, type HubConnectionDeleteRequest, type HubConnectionDeleteResponse, type HubConnectionHealthError, type HubConnectionHealthInfo, type HubConnectionHealthRequest, type HubConnectionHealthResponse, type HubConnectionHealthStatus, type HubConnectionStartOptions, HubConnectionsClient, type HubConnectionsResponse, type HubEnv, type HubEnvelope, type HubErrorBody, type HubErrorCode, type HubErrorEnvelope, type HubExecRequest, type HubExecResponse, HubGithubAppClient, type HubGithubAppInstallation, type HubGithubAppInstallationResponse, type HubGithubAppIsRepoInstalledRequest, type HubGithubAppIsRepoInstalledResponse, type HubGithubAppListReposResponse, type HubGithubAppMintInstallationTokenRequest, type HubGithubAppMintInstallationTokenResponse, type HubOAuthCallbackErrorQuery, type HubOAuthCallbackQuery, type HubOAuthCallbackResponse, type HubOAuthCallbackSuccessQuery, type HubOAuthStartRequest, type HubOAuthStartResponse, HubPermissionsClient, type HubPolicy, type HubPolicyDecision, type HubPolicyListRequest, type HubPolicyListResponse, type HubPolicyResponse, type HubPolicyUpdateRequest, type HubPrincipal, type HubPrincipalKind, HubSdkError, type HubStatusConnections, type HubStatusResponse, type HubSuccessEnvelope, type HubTokenListOptions, type HubTokenMintRequest, type HubTokenMintResponse, type HubTokenRevokeResponse, HubTokensClient, type HubTokensListResponse, type HubTool, type HubToolInvokeOptions, type HubToolSearchOptions, type HubToolSource, type HubToolSourcesResponse, HubToolsClient, type HubToolsDescribeRequest, type HubToolsDescribeResponse, type HubToolsSearchRequest, type HubToolsSearchResponse, type HubUnimplementedErrorEnvelope, redactHubValue, resolveHubAuth, resolveHubBaseUrl };
+export { HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, type HubAgentIterationSpan, type HubAgentRunDetail, type HubApiKeyConnectRequest, type HubApiKeyConnectResponse, type HubApproval, type HubApprovalCapabilityToken, type HubApprovalDecisionResponse, type HubApprovalStatus, HubApprovalsClient, HubAuditClient, type HubAuditEvent, type HubAuditListRequest, type HubAuditResponse, type HubAuthHeaders, type HubCapabilityToken, HubClient, type HubClientFromEnvOptions, type HubClientOptions, type HubConnection, type HubConnectionDeleteRequest, type HubConnectionDeleteResponse, type HubConnectionHealthError, type HubConnectionHealthInfo, type HubConnectionHealthRequest, type HubConnectionHealthResponse, type HubConnectionHealthStatus, type HubConnectionStartOptions, HubConnectionsClient, type HubConnectionsResponse, type HubEnv, type HubEnvelope, type HubErrorBody, type HubErrorCode, type HubErrorEnvelope, type HubExecRequest, type HubExecResponse, HubGithubAppClient, type HubGithubAppInstallation, type HubGithubAppInstallationResponse, type HubGithubAppIsRepoInstalledRequest, type HubGithubAppIsRepoInstalledResponse, type HubGithubAppListReposResponse, type HubGithubAppMintInstallationTokenRequest, type HubGithubAppMintInstallationTokenResponse, type HubManualRunInput, type HubOAuthCallbackErrorQuery, type HubOAuthCallbackQuery, type HubOAuthCallbackResponse, type HubOAuthCallbackSuccessQuery, type HubOAuthStartRequest, type HubOAuthStartResponse, HubPermissionsClient, type HubPolicy, type HubPolicyDecision, type HubPolicyDeleteRequest, type HubPolicyDeleteResponse, type HubPolicyListRequest, type HubPolicyListResponse, type HubPolicyResponse, type HubPolicyUpdateRequest, type HubPrincipal, type HubPrincipalKind, type HubProvider, type HubProviderAuthKind, type HubProvidersResponse, HubSdkError, type HubStatusConnections, type HubStatusResponse, type HubSuccessEnvelope, type HubTokenListOptions, type HubTokenMintRequest, type HubTokenMintResponse, type HubTokenRevokeResponse, HubTokensClient, type HubTokensListResponse, type HubTool, type HubToolInvokeOptions, type HubToolRisk, type HubToolSearchOptions, type HubToolSource, type HubToolSourcesResponse, HubToolsClient, type HubToolsDescribeRequest, type HubToolsDescribeResponse, type HubToolsSearchRequest, type HubToolsSearchResponse, type HubUnimplementedErrorEnvelope, type HubWhatsappEmbeddedSignupCompleteRequest, type HubWhatsappEmbeddedSignupCompleteResponse, type HubWhatsappEmbeddedSignupStartRequest, type HubWhatsappEmbeddedSignupStartResponse, type HubWorkflow, type HubWorkflowAction, type HubWorkflowActionResult, type HubWorkflowEventFilter, type HubWorkflowRun, type HubWorkflowRunCancelResult, type HubWorkflowRunDetail, type HubWorkflowRunEnqueued, type HubWorkflowRunInputs, type HubWorkflowRunStatus, type HubWorkflowRunStreamEvent, type HubWorkflowRunSummary, type HubWorkflowRunsPage, type HubWorkflowSchemaResponse, type HubWorkflowTrigger, type HubWorkflowValidateResponse, type HubWorkflowValidationError, HubWorkflowsClient, redactHubValue, resolveHubAuth, resolveHubBaseUrl };
 //# sourceMappingURL=index.d.ts.map