@tangle-network/hub-sdk 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -537,7 +537,7 @@ interface HubWorkflowEventFilter {
 }
 interface HubWorkflowTrigger {
   id: string;
-  kind: "provider_event" | "schedule";
+  kind: "provider_event" | "schedule" | "webhook";
   enabled: boolean;
   provider: string | null;
   connectionId: string | null;
@@ -598,6 +598,21 @@ interface HubWorkflowActionResult {
   output?: unknown;
   error?: string;
   costUsd?: number;
+  /** Graph-run identity: the topology node this action row belongs to. Present
+   *  when the id says something the row's position does not — an author's DAG
+   *  node id, and every cycle re-entry row (a node visited more than once
+   *  produces one row per visit). Absent on a linear run's rows, whose node id
+   *  IS their position: read it as `step-${index + 1}`. */
+  nodeId?: string;
+  /** Which visit of `nodeId` this row is (1-based). Present on cycle re-entry
+   *  rows only; a single-visit row omits it. */
+  visit?: number;
+  /** `script.run` only (single-run detail): the script's captured stdout
+   *  (size-capped), or an artifact ref carrying the full log by reference. */
+  logs?: unknown;
+  /** How an `onError` policy handled this action's failure so the run
+   *  continued (the action still reads `failed`). */
+  onError?: HubWorkflowOnErrorOutcome;
   /** `agent.run` only (single-run detail): the agent's execution detail —
    *  per-iteration spans (each with text), aggregate usage, partial text. */
   agentRun?: HubAgentRunDetail;
@@ -633,6 +648,16 @@ interface HubWorkflowRunDetail extends HubWorkflowRun {
    *  `getRun` / a `snapshot` event reads them without re-checking presence. */
   triggerContext: unknown;
   definitionSnapshot: string | null;
+  /** The terminal failed/cancelled run this one retries (enqueued via
+   *  {@link HubWorkflowsClient.retryRun}); null on runs that are not retries. */
+  retriedFromRunId: string | null;
+  /** The compiled graph topology the run executed (resolved from the run's
+   *  definition snapshot, so a post-run edit can't mislabel it) — null for a
+   *  linear run. Present on the HTTP run-detail response. */
+  graph?: HubWorkflowGraphSpec | null;
+  /** Per-completion guard verdicts (keyed `"from->to"`), present only when the
+   *  run carries a graph journal — i.e. a parked (`waiting`) graph run. */
+  edgeVerdicts?: HubWorkflowEdgeVerdicts[];
 }
 /**
  * The trigger fields a manual "Run now" supplies, as a flat `{ path: value }`
@@ -664,6 +689,17 @@ interface HubWorkflowRunCancelResult {
    *  watch/poll the run to confirm it settled `cancelled`. */
   signalled?: boolean;
 }
+/**
+ * Response of a run retry (`POST /v1/workflows/:id/runs/:runId/retry`): the
+ * NEWLY enqueued run's id — a fresh run of the same workflow with the same
+ * trigger context — plus the terminal run it was retried from. A finished
+ * run in any other state throws `HubSdkError` with code `RUN_NOT_RETRYABLE`;
+ * an unknown/foreign run throws `NOT_FOUND`.
+ */
+interface HubWorkflowRunRetried {
+  runId: string;
+  retriedFromRunId: string;
+}
 /**
  * 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
@@ -734,6 +770,35 @@ interface HubWorkflowRunsPage {
   runs: HubWorkflowRun[];
   nextCursor: string | null;
 }
+/** Trailing windows the fleet-insights endpoint accepts. */
+type HubWorkflowFleetWindow = "24h" | "7d" | "30d";
+/**
+ * One workflow's row in the fleet overview: its run tallies over the window.
+ * `lastRunStatus`/`lastRunAt` describe the newest run INSIDE the window (null
+ * when the workflow didn't run in it), and `successRate` is
+ * `succeeded / runsInWindow` — null, never a fabricated 0 or 1, when there is
+ * no denominator.
+ */
+interface HubWorkflowFleetEntry {
+  id: string;
+  name: string;
+  enabled: boolean;
+  runsInWindow: number;
+  succeeded: number;
+  failed: number;
+  /** Runs parked on a human `decision` step (status `waiting`). */
+  waiting: number;
+  successRate: number | null;
+  lastRunStatus: HubWorkflowRunStatus | null;
+  lastRunAt: string | null;
+}
+/** `GET /v1/workflows/insights/fleet` — the whole fleet, sorted failing-first. */
+interface HubWorkflowFleetInsights {
+  window: HubWorkflowFleetWindow;
+  /** ISO instant the window starts at (now minus the window length). */
+  windowStart: string;
+  workflows: HubWorkflowFleetEntry[];
+}
 interface HubWorkflow {
   id: string;
   name: string;
@@ -744,11 +809,22 @@ interface HubWorkflow {
   /** The durable YAML this workflow compiled from. */
   definitionYaml: string | null;
   validationErrors: HubWorkflowValidationError[];
+  /** Current head revision; null on pre-versioning rows until their next
+   *  update (they have no revision history to point at yet). */
+  headRev?: number | null;
   /** 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 get-detail response: the compiled graph topology (null
+   *  when the definition has no graph topology, or is chain-equivalent —
+   *  the legacy linear semantics). Omitted on the list projection. */
+  graph?: HubWorkflowGraphSpec | null;
+  /** Create response only, when the definition has a webhook trigger: the
+   *  hook delivery URL, plus the plaintext bearer token exactly once at mint
+   *  (absent when an active token already exists — rotate to re-reveal). */
+  hook?: HubWorkflowHookEndpoint;
   /** Present on the list response (latest run, or null if never run); omitted on detail. */
   lastRun?: HubWorkflowRunSummary | null;
   createdAt: string;
@@ -772,6 +848,305 @@ type HubWorkflowValidateResponse = {
 };
 /** JSON Schema for the YAML workflow definition. */
 type HubWorkflowSchemaResponse = Record<string, unknown>;
+/** How a node's incoming edges release it (default `"all"` — omitted on the
+ *  wire for it, so specs compiled before join rules existed round-trip). */
+type HubWorkflowGraphJoinRule = "all" | "any" | "any_failed" | "all_done";
+type HubWorkflowConditionOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "contains" | "exists" | "truthy";
+type HubWorkflowConditionScalar = string | number | boolean | null;
+/** The predicate on a guarded edge (`needs: [{ id, when }]`), evaluated by the
+ *  runner against the steps context on the source node's completion. */
+type HubWorkflowCondition = {
+  path: string;
+  op: HubWorkflowConditionOp;
+  value?: HubWorkflowConditionScalar | HubWorkflowConditionScalar[];
+} | {
+  all: HubWorkflowCondition[];
+} | {
+  any: HubWorkflowCondition[];
+} | {
+  not: HubWorkflowCondition;
+};
+interface HubWorkflowGraphNode {
+  id: string;
+  index: number;
+  join?: HubWorkflowGraphJoinRule;
+}
+interface HubWorkflowGraphEdge {
+  from: string;
+  to: string;
+  /** Guard the runner evaluates on the source's completion; unguarded edges
+   *  carry no `when`. */
+  when?: HubWorkflowCondition;
+}
+/** JSON-serializable form of a validated graph (as stored on run/workflow rows). */
+interface HubWorkflowGraphSpec {
+  nodes: HubWorkflowGraphNode[];
+  edges: HubWorkflowGraphEdge[];
+  maxNodeVisits: number;
+}
+/** One journal completion on the wire: the node that completed and the guard
+ *  verdict evaluated for each of its guarded outgoing edges, keyed by edgeKey
+ *  (`"from->to"`). Only GUARDED edges ever appear. */
+interface HubWorkflowEdgeVerdicts {
+  nodeId: string;
+  verdicts: Record<string, boolean>;
+}
+/** How an action's `onError` policy handled a failure so the run continued
+ *  (the action itself still reads `failed`). */
+interface HubWorkflowOnErrorOutcome {
+  policy: "continue" | "fallback";
+  /** The recovery leaf's result when the policy ran a `{ do }` fallback. */
+  fallback?: {
+    kind: string;
+    status: "succeeded" | "failed";
+    output?: unknown;
+    error?: string;
+    costUsd?: number;
+  };
+}
+type HubWorkflowRevisionSource = "user" | "copilot" | "intelligence";
+/** Lifecycle state of a revision. The head rev only ever points at an
+ *  `applied` revision; `proposed` is a service-token-authored suggestion
+ *  awaiting an owner decision; `rejected` is a declined proposal (kept for
+ *  audit). */
+type HubWorkflowRevisionStatus = "applied" | "proposed" | "rejected";
+/** Revision list projection — attribution + note + status, WITHOUT the YAML body. */
+interface HubWorkflowRevisionMeta {
+  rev: number;
+  createdAt: string;
+  createdBy: string;
+  source: HubWorkflowRevisionSource;
+  note: string | null;
+  status: HubWorkflowRevisionStatus;
+}
+/** One revision WITH its YAML (and the actions compiled alongside it). */
+interface HubWorkflowRevision extends HubWorkflowRevisionMeta {
+  yaml: string;
+  actions: HubWorkflowAction[];
+}
+/** A proposal (proposed or rejected revision) WITH its evidence — what the
+ *  proposer derived the suggestion from (e.g. health stats), plus
+ *  `rejectionReason` once declined. */
+interface HubWorkflowProposal extends HubWorkflowRevisionMeta {
+  evidence: unknown;
+}
+/** Input to {@link HubWorkflowsClient.propose}. Service-token callers only. */
+interface HubWorkflowProposalInput {
+  yaml: string;
+  note?: string;
+  /** Proposer-supplied justification (any JSON value) — carried verbatim onto
+   *  the revision and shown on the approval surface. */
+  evidence?: unknown;
+}
+/** One node's aggregate across the analyzed runs. */
+interface HubWorkflowNodeHealth {
+  /** The author's graph node id, or `step-N` for a linear run's nodes (and for
+   *  a node whose run cannot be mapped back to a definition). */
+  nodeId: string;
+  visits: number;
+  failures: number;
+  /** Null when no visit carried a cost row (never a fabricated 0). */
+  totalCostUsd: number | null;
+  /** Null when no visit recorded duration spans. */
+  avgDurationMs: number | null;
+}
+/** Failures grouped by a normalized error signature (ids/numbers/whitespace
+ *  stripped), most frequent first (top 5). */
+interface HubWorkflowFailureCluster {
+  signature: string;
+  count: number;
+  sampleRunIds: string[];
+}
+/** An agent.run node whose outputs are near-static across runs — a
+ *  CANDIDATE for distillation, reported with its measurements, never a
+ *  verdict. */
+interface HubWorkflowDistillationCandidate {
+  nodeId: string;
+  matchRatio: number;
+  samples: number;
+  avgCostUsd: number | null;
+}
+interface HubWorkflowHealth {
+  /** The requested window (the `runs` parameter). */
+  runsWindow: number;
+  /** Terminal runs that actually went into the stats. */
+  runsAnalyzed: number;
+  nodes: HubWorkflowNodeHealth[];
+  failureClusters: HubWorkflowFailureCluster[];
+  distillationCandidates: HubWorkflowDistillationCandidate[];
+}
+/** One KV entry with its metadata — the get/put/cas response shape. */
+interface HubWorkflowKvEntry {
+  key: string;
+  value: unknown;
+  version: number;
+  updatedAt: string;
+}
+/** Keyspace metadata row (never the value) — the list response's entry. */
+interface HubWorkflowKvEntryMeta {
+  key: string;
+  version: number;
+  updatedAt: string;
+}
+interface HubWorkflowKvListResponse {
+  entries: HubWorkflowKvEntryMeta[];
+}
+interface HubWorkflowKvDeleteResponse {
+  deleted: boolean;
+}
+/** The opaque ref a stored artifact is referred to by — the value a
+ *  script.run node returns as its step output. */
+interface HubWorkflowArtifactRef {
+  $artifact: string;
+  name: string;
+  contentType: string;
+  byteSize: number;
+  preview: string | null;
+}
+/** Artifact metadata (never the bytes), oldest first on the list response. */
+interface HubWorkflowArtifact {
+  id: string;
+  runId: string;
+  workflowId: string;
+  /** The graph node (or `step-N` positional id on linear runs) whose action
+   *  emitted the artifact. */
+  nodeId: string;
+  name: string;
+  contentType: string;
+  byteSize: number;
+  /** First 2KiB of textual content; null for binary content types. */
+  preview: string | null;
+  createdAt: string;
+}
+interface HubWorkflowArtifactsResponse {
+  artifacts: HubWorkflowArtifact[];
+}
+/** Raw artifact bytes from the download route, with their stored content type. */
+interface HubWorkflowArtifactDownload {
+  bytes: Uint8Array;
+  contentType: string;
+}
+type HubWorkflowTemplateCategory = "Code Review" | "Triage" | "Reports" | "Multi-agent";
+/** One author-time literal a gallery starter needs the user to supply. Every
+ *  declared parameter is required; `example` is a valid value that seeds the
+ *  form placeholder. */
+interface HubWorkflowTemplateParameter {
+  key: string;
+  label: string;
+  type: "string" | "integer";
+  help?: string;
+  example: string;
+}
+interface HubWorkflowTemplate {
+  id: string;
+  name: string;
+  summary: string;
+  category: HubWorkflowTemplateCategory;
+  icon: string;
+  requiresSandbox: boolean;
+  /** Providers the template references (a "uses GitHub" hint), sorted. */
+  providers: string[];
+  parameters: HubWorkflowTemplateParameter[];
+  /** The template with parameter tokens rendered to their example values. */
+  previewYaml: string;
+}
+/** A connection a definition needs, with where to connect it. */
+interface HubWorkflowConnectionRequirement {
+  provider: string;
+  connected: boolean;
+  kind: "integration" | "github_app";
+  /** Where to satisfy the requirement (App install flow for `github_app`,
+   *  integrations page otherwise); null when no target exists. */
+  connectUrl: string | null;
+}
+/**
+ * Result of instantiating a template. `created: false` is NOT an error — an
+ * actionable continuation listing the connections to satisfy before retrying
+ * the same call. Invalid parameters or a compile failure throw `HubSdkError`
+ * (400) instead, matching the create route's contract.
+ */
+type HubWorkflowTemplateInstantiateResult = {
+  created: true;
+  workflow: HubWorkflow;
+} | {
+  created: false;
+  connectionRequirements: HubWorkflowConnectionRequirement[];
+};
+type HubWorkflowDecisionStatus = "pending" | "resolved" | "expired" | "cancelled";
+type HubWorkflowDecisionOnTimeout = "wait" | "fail" | "default";
+/** How the answer arrived: a UI click, a provider-channel event (e.g. a Slack
+ *  reaction), or the timeout policy. */
+type HubWorkflowDecisionResolvedVia = "in_app" | "channel" | "system";
+interface HubWorkflowDecision {
+  id: string;
+  runId: string;
+  workflowId: string;
+  actionIndex: number;
+  title: string;
+  prompt: string | null;
+  options: string[];
+  status: HubWorkflowDecisionStatus;
+  onTimeout: HubWorkflowDecisionOnTimeout;
+  defaultChoice: string | null;
+  choice: string | null;
+  note: string | null;
+  timedOut: boolean;
+  requestedAt: string;
+  expiresAt: string | null;
+  resolvedAt: string | null;
+  /** Null while pending, and on a row settled without an answer (expired /
+   *  cancelled). */
+  resolvedVia: HubWorkflowDecisionResolvedVia | null;
+  /** `channel` answers only: the provider whose event carried the answer and
+   *  the raw external actor id it came from. */
+  resolvedViaProvider: string | null;
+  resolvedByExternalActor: string | null;
+}
+/** A pending decision on the cross-workflow list, named by its workflow
+ *  (null when the workflow was deleted while the run was parked). */
+interface HubWorkflowPendingDecision extends HubWorkflowDecision {
+  workflowName: string | null;
+}
+interface HubWorkflowPendingDecisionsResponse {
+  decisions: HubWorkflowPendingDecision[];
+}
+/** Result of resolving a decision. `resumed` is false when the resolution
+ *  stuck but the run could not be resumed (already terminal/cancelled). */
+interface HubWorkflowDecisionResolveResult {
+  runId: string;
+  decisionId: string;
+  choice: string;
+  resumed: boolean;
+}
+/** A workflow's webhook delivery endpoint. `token` is the plaintext bearer —
+ *  revealed only at mint/rotate time (only the hash is stored). */
+interface HubWorkflowHookEndpoint {
+  url: string;
+  token?: string;
+}
+interface HubWorkflowHookToken {
+  url: string;
+  token: string;
+}
+/** One step of an agent round's execution timeline (reasoning, or a tool call
+ *  with args + result), as the step-page endpoint serves it. */
+type HubWorkflowAgentStep = {
+  kind: "reasoning";
+  text: string;
+} | {
+  kind: "tool"; /** Tool name, e.g. "read", "bash". */
+  tool: string;
+  status: "pending" | "running" | "completed" | "error"; /** Arguments the tool was called with (pretty JSON). */
+  input?: string; /** Result the tool returned on success (pretty JSON / text). */
+  output?: string; /** Error message when the tool failed. */
+  error?: string;
+};
+/** One page of a round's step archive. `nextCursor` is the last `stepIndex`
+ *  held — pass it as `after` for the next page; null on the last page. */
+interface HubWorkflowRunStepsPage {
+  steps: HubWorkflowAgentStep[];
+  nextCursor: number | null;
+}
 //#endregion
 //#region src/client.d.ts
 type HubAuthHeaders = () => HeadersInit | Promise<HeadersInit>;
@@ -832,6 +1207,14 @@ declare class HubClient {
    * `HUB_HTTP_<status>` transport error — rather than handed back as bogus SSE.
    */
   private stream;
+  /**
+   * Fetch raw (non-envelope) bytes — the artifact download route, whose 200 is
+   * the artifact's own content type, not JSON. Error responses on such routes
+   * are still the standard envelope, so a failure surfaces exactly like
+   * {@link request}: a typed `HubSdkError` from a `{success:false}` body,
+   * otherwise an `HUB_HTTP_<status>` transport error.
+   */
+  private requestBytes;
   private buildHeaders;
 }
 interface HubTokenListOptions {
@@ -950,11 +1333,31 @@ declare class HubAuditClient {
 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);
+  private readonly download?;
+  constructor(request: <TData>(path: string, init: RequestInit) => Promise<TData>, stream?: ((path: string, init: RequestInit) => Promise<ReadableStream<Uint8Array>>) | undefined, download?: ((path: string, init: RequestInit) => Promise<HubWorkflowArtifactDownload>) | undefined);
   list(): Promise<HubWorkflow[]>;
+  /**
+   * Owner-wide fleet overview: one row per workflow with its run tallies over
+   * a trailing window (default 7d), sorted failing-first. Answers "how are ALL
+   * my workflows doing" in one call — the per-workflow insights endpoint is
+   * the drill-down, not a way to build this row set client-side.
+   */
+  fleetInsights(opts?: {
+    window?: HubWorkflowFleetWindow;
+  }): Promise<HubWorkflowFleetInsights>;
   get(id: string): Promise<HubWorkflow>;
   create(yaml: string): Promise<HubWorkflow>;
-  update(id: string, yaml: string): Promise<HubWorkflow>;
+  /**
+   * Replace the workflow's definition from YAML (recompiled server-side,
+   * triggers reconciled). Every landed update appends a revision;
+   * `opts.note` rides onto that revision row (e.g. "why this change"), visible
+   * in {@link listRevisions}. Throws `HubSdkError`: `WORKFLOW_INVALID` when the
+   * YAML doesn't compile or its connections aren't met, `CONFLICT` on a
+   * concurrent modification, `NOT_FOUND` for an unknown/foreign id.
+   */
+  update(id: string, yaml: string, opts?: {
+    note?: string;
+  }): Promise<HubWorkflow>;
   delete(id: string): Promise<void>;
   /**
    * Enable or disable a workflow without editing its YAML. Works even when the
@@ -1006,6 +1409,21 @@ declare class HubWorkflowsClient {
   cancel(id: string, runId: string, opts?: {
     signal?: AbortSignal;
   }): Promise<HubWorkflowRunCancelResult>;
+  /**
+   * Re-run a terminal failed/cancelled run: enqueues a FRESH run of the same
+   * workflow with the SAME trigger context the original ran against, linked
+   * back to it via `retriedFromRunId`. The original row is never mutated —
+   * execution is at-most-once, so a retry is always a new run, never a
+   * requeue. The response carries the NEW run id (and the run it retried);
+   * follow it with {@link getRun}/{@link watchRun}/{@link waitForRun} like any
+   * other run. Throws `HubSdkError`: `RUN_NOT_RETRYABLE` when the run is not
+   * terminal-failed/cancelled (queued/running/waiting, or succeeded),
+   * `WORKFLOW_DISABLED` when the workflow has since been disabled, `NOT_FOUND`
+   * for an unknown/foreign run id. Pass `opts.signal` to abort a slow request.
+   */
+  retryRun(id: string, runId: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<HubWorkflowRunRetried>;
   /**
    * 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
@@ -1043,7 +1461,178 @@ declare class HubWorkflowsClient {
     timeoutMs?: number;
     signal?: AbortSignal;
   }): Promise<HubWorkflowRunDetail>;
-  validate(yaml: string): Promise<HubWorkflowValidateResponse>;
+  /**
+   * The workflow's definition history, newest rev first — metadata only (rev,
+   * attribution, note); fetch the YAML per-rev with {@link getRevision}. Empty
+   * for a pre-versioning workflow until its next update.
+   */
+  listRevisions(id: string): Promise<HubWorkflowRevisionMeta[]>;
+  /**
+   * One revision WITH its YAML (and the actions compiled alongside it), for
+   * diff/inspect views. Throws `HubSdkError(REVISION_NOT_FOUND)` for an
+   * unknown rev, `NOT_FOUND` for an unknown/foreign workflow.
+   */
+  getRevision(id: string, rev: number): Promise<HubWorkflowRevision>;
+  /**
+   * Restore a prior rev's YAML as a NEW head revision (history is append-only)
+   * through the same compile path as {@link update}, so the restored definition
+   * is re-validated against today's connections/models. Throws `HubSdkError`:
+   * `REVISION_NOT_FOUND` for an unknown rev, `WORKFLOW_INVALID` when the old
+   * YAML no longer compiles, `CONFLICT` on a concurrent modification.
+   */
+  rollback(id: string, rev: number): Promise<HubWorkflow>;
+  /**
+   * Deterministic health stats over the workflow's last N terminal runs
+   * (default 20, max 100): per-node visits/failures/cost/duration, failure
+   * clusters by normalized error signature, and distillation CANDIDATES
+   * (agent.run nodes with near-static outputs — labeled with their
+   * measurements, never as verdicts). No model in this path.
+   */
+  health(id: string, opts?: {
+    runs?: number;
+  }): Promise<HubWorkflowHealth>;
+  /**
+   * Propose a definition change — the intelligence path. SERVICE-TOKEN
+   * callers only (user principals get `HubSdkError(SERVICE_TOKEN_REQUIRED)`,
+   * 403). The YAML is compile-validated server-side (`WORKFLOW_INVALID` on
+   * failure) and appended as a `proposed` revision; the head NEVER advances
+   * until an owner approves.
+   */
+  propose(id: string, input: HubWorkflowProposalInput): Promise<HubWorkflowProposal>;
+  /**
+   * Pending (proposed) and declined (rejected) revisions, newest first, with
+   * their evidence — the approval surface's input.
+   */
+  listProposals(id: string): Promise<HubWorkflowProposal[]>;
+  /**
+   * Accept a proposal: its YAML lands as a NEW applied head revision through
+   * the same compile + advance path as {@link rollback} (re-validated against
+   * today's connections/models), and the proposal settles to `applied`.
+   * Throws `HubSdkError`: `PROPOSAL_NOT_PENDING` (409) when the rev is not a
+   * pending proposal, `WORKFLOW_INVALID` when it no longer compiles,
+   * `CONFLICT` on a concurrent modification.
+   */
+  approveProposal(id: string, rev: number): Promise<HubWorkflow>;
+  /**
+   * Decline a proposal: the revision settles to `rejected` (head untouched);
+   * an optional reason is merged into its evidence as `rejectionReason`.
+   * Throws `HubSdkError(PROPOSAL_NOT_PENDING)` (409) when the rev is not a
+   * pending proposal.
+   */
+  rejectProposal(id: string, rev: number, opts?: {
+    reason?: string;
+  }): Promise<HubWorkflowProposal>;
+  /**
+   * Mint a fresh webhook hook token, retiring the current one immediately.
+   * The plaintext token is returned exactly once (only the hash is stored).
+   * Requires an active webhook trigger — otherwise `HubSdkError` with
+   * `NO_WEBHOOK_TRIGGER` (409).
+   */
+  rotateHookToken(id: string): Promise<HubWorkflowHookToken>;
+  /**
+   * One agent round's execution timeline, paged. `action` is the action's
+   * `${steps[N]}` position and `iteration` the round's position in that
+   * action's `iterations` — both exactly as the run detail serializes them.
+   * Pass the previous page's `nextCursor` as `after` for the next page; a null
+   * `nextCursor` means the round is fully read.
+   */
+  listRunSteps(id: string, runId: string, input: {
+    action: number;
+    iteration: number;
+    after?: number;
+    limit?: number;
+  }): Promise<HubWorkflowRunStepsPage>;
+  /**
+   * Store one artifact for a run (raw bytes) and return the opaque ref — the
+   * value a script.run node returns as its step output. `contentType` defaults
+   * to `application/octet-stream`; `nodeId` attributes the write to a graph
+   * node (owner credential only — a run-scoped token binds its own node).
+   * Throws `HubSdkError(ARTIFACT_TOO_LARGE)` past the server cap.
+   */
+  uploadArtifact(id: string, runId: string, input: {
+    name: string;
+    bytes: Uint8Array;
+    contentType?: string;
+    nodeId?: string;
+  }): Promise<HubWorkflowArtifactRef>;
+  /** Metadata for every artifact of the run (never the bytes), oldest first. */
+  listArtifacts(id: string, runId: string): Promise<HubWorkflowArtifactsResponse>;
+  /**
+   * The artifact's raw bytes with their stored content type — the route every
+   * `downloadUrl` attached to an `$artifact` ref in a run detail points at.
+   */
+  downloadArtifact(id: string, runId: string, artifactId: string): Promise<HubWorkflowArtifactDownload>;
+  /**
+   * The workflow's whole keyspace as metadata (key, version, updatedAt — never
+   * values), key-ordered. Bounded by the server's per-workflow key cap.
+   */
+  listKv(id: string): Promise<HubWorkflowKvListResponse>;
+  /** One KV entry (value + version); `HubSdkError(NOT_FOUND)` when absent. */
+  getKv(id: string, key: string): Promise<HubWorkflowKvEntry>;
+  /**
+   * Upsert a key; returns the entry with its NEW version (increments on every
+   * write). Throws `HubSdkError(KV_VALUE_TOO_LARGE)` past the 64KiB value cap
+   * or `KV_KEY_LIMIT` past the per-workflow key cap.
+   */
+  putKv(id: string, key: string, value: unknown): Promise<HubWorkflowKvEntry>;
+  /**
+   * Compare-and-swap: the write lands only when the stored version still
+   * equals `expectedVersion`; otherwise `HubSdkError(KV_VERSION_CONFLICT)`
+   * (409) — re-read and retry. Creation is {@link putKv}'s job.
+   */
+  casKv(id: string, key: string, expectedVersion: number, value: unknown): Promise<HubWorkflowKvEntry>;
+  /** Delete a key; idempotent — `deleted` reports whether a row was removed. */
+  deleteKv(id: string, key: string): Promise<HubWorkflowKvDeleteResponse>;
+  /** The curated starter gallery runnable on THIS deployment: metadata,
+   *  parameters, referenced providers, and a concrete `previewYaml` per card. */
+  listTemplates(): Promise<HubWorkflowTemplate[]>;
+  /**
+   * One-click create from a gallery template: substitutes `parameters` into
+   * the template server-side, then runs the SAME create path as
+   * {@link create}. A `{ created: false }` result is NOT an error — an
+   * actionable continuation listing the connections to satisfy before
+   * retrying. Invalid parameters or a compile failure throw `HubSdkError`
+   * (400); an unknown template id throws `NOT_FOUND`.
+   */
+  instantiateTemplate(templateId: string, parameters?: Record<string, string>): Promise<HubWorkflowTemplateInstantiateResult>;
+  /**
+   * The caller's open decisions across all workflows — the always-available
+   * "pending approvals" surface. Each entry carries its workflow's name (null
+   * when the workflow was deleted while the run was parked).
+   */
+  listPendingDecisions(): Promise<HubWorkflowPendingDecisionsResponse>;
+  /**
+   * The pending decision a run is parked on. Throws `HubSdkError(NOT_FOUND)`
+   * when the run is unknown/foreign or holds no pending decision.
+   */
+  getRunDecision(id: string, runId: string): Promise<HubWorkflowDecision>;
+  /**
+   * Answer the decision a run is parked on and resume it from the next action.
+   * `decisionId` is REQUIRED: a run can resolve one decision and re-park on the
+   * next, so an answer addressed only by run could silently land on a question
+   * the caller never saw — a mismatch throws `HubSdkError(DECISION_SUPERSEDED)`.
+   * Other typed failures: `INVALID_CHOICE` (400), `DECISION_ALREADY_RESOLVED` /
+   * `DECISION_EXPIRED` (409), `DECISION_NOT_FOUND` (404), `RUN_NOT_WAITING`
+   * (409 — answered, timed out, or cancelled first).
+   */
+  resolveRunDecision(id: string, runId: string, input: {
+    decisionId: string;
+    choice: string;
+    note?: string;
+  }): Promise<HubWorkflowDecisionResolveResult>;
+  /**
+   * Dry-run a YAML definition against the platform compiler without saving it.
+   *
+   * `opts.structural` selects the CI mode: the platform skips its owner-scoped
+   * connection/skill/profile resolution, so the verdict depends only on the
+   * definition and the deployment's capabilities — identical no matter which
+   * providers the calling account has connected. Use it in pipelines that
+   * assert "this YAML is well-formed"; leave it off in an editor, where naming
+   * the unconnected providers is the point.
+   */
+  validate(yaml: string, opts?: {
+    structural?: boolean;
+  }): Promise<HubWorkflowValidateResponse>;
   schema(): Promise<HubWorkflowSchemaResponse>;
 }
 //#endregion
@@ -1120,5 +1709,5 @@ declare function parseHubEventDelivery(input: string | unknown): HubEventDeliver
 //#region src/redaction.d.ts
 declare function redactHubValue(value: unknown): unknown;
 //#endregion
-export { type AuthenticateHubEventRequestInput, type DeriveHubEventCallbackSecretInput, 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, type HubChannel, type HubChannelCreateResponse, type HubChannelDeleteResponse, HubChannelsClient, type HubChannelsResponse, 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 HubEmailChannel, type HubEmailChannelCreateRequest, type HubEnv, type HubEnvelope, type HubErrorBody, type HubErrorCode, type HubErrorEnvelope, type HubEventCondition, type HubEventConditionScalar, type HubEventDelivery, HubEventDeliveryError, type HubEventRequestFailureCode, type HubEventRequestResult, type HubEventSignatureFailure, type HubEventSignatureResult, type HubEventSubscription, type HubEventSubscriptionCallback, type HubEventSubscriptionCreateRequest, type HubEventSubscriptionCreateResponse, type HubEventSubscriptionDeleteResponse, type HubEventSubscriptionFilter, type HubEventSubscriptionSource, HubEventSubscriptionsClient, type HubEventSubscriptionsResponse, 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 HubProviderEvent, 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, type VerifyHubEventSignatureInput, authenticateHubEventRequest, deriveHubEventCallbackSecret, parseHubEventDelivery, redactHubValue, resolveHubAuth, resolveHubBaseUrl, verifyHubEventSignature };
+export { type AuthenticateHubEventRequestInput, type DeriveHubEventCallbackSecretInput, 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, type HubChannel, type HubChannelCreateResponse, type HubChannelDeleteResponse, HubChannelsClient, type HubChannelsResponse, 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 HubEmailChannel, type HubEmailChannelCreateRequest, type HubEnv, type HubEnvelope, type HubErrorBody, type HubErrorCode, type HubErrorEnvelope, type HubEventCondition, type HubEventConditionScalar, type HubEventDelivery, HubEventDeliveryError, type HubEventRequestFailureCode, type HubEventRequestResult, type HubEventSignatureFailure, type HubEventSignatureResult, type HubEventSubscription, type HubEventSubscriptionCallback, type HubEventSubscriptionCreateRequest, type HubEventSubscriptionCreateResponse, type HubEventSubscriptionDeleteResponse, type HubEventSubscriptionFilter, type HubEventSubscriptionSource, HubEventSubscriptionsClient, type HubEventSubscriptionsResponse, 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 HubProviderEvent, 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 HubWorkflowAgentStep, type HubWorkflowArtifact, type HubWorkflowArtifactDownload, type HubWorkflowArtifactRef, type HubWorkflowArtifactsResponse, type HubWorkflowCondition, type HubWorkflowConditionOp, type HubWorkflowConditionScalar, type HubWorkflowConnectionRequirement, type HubWorkflowDecision, type HubWorkflowDecisionOnTimeout, type HubWorkflowDecisionResolveResult, type HubWorkflowDecisionResolvedVia, type HubWorkflowDecisionStatus, type HubWorkflowDistillationCandidate, type HubWorkflowEdgeVerdicts, type HubWorkflowEventFilter, type HubWorkflowFailureCluster, type HubWorkflowFleetEntry, type HubWorkflowFleetInsights, type HubWorkflowFleetWindow, type HubWorkflowGraphEdge, type HubWorkflowGraphJoinRule, type HubWorkflowGraphNode, type HubWorkflowGraphSpec, type HubWorkflowHealth, type HubWorkflowHookEndpoint, type HubWorkflowHookToken, type HubWorkflowKvDeleteResponse, type HubWorkflowKvEntry, type HubWorkflowKvEntryMeta, type HubWorkflowKvListResponse, type HubWorkflowNodeHealth, type HubWorkflowOnErrorOutcome, type HubWorkflowPendingDecision, type HubWorkflowPendingDecisionsResponse, type HubWorkflowProposal, type HubWorkflowProposalInput, type HubWorkflowRevision, type HubWorkflowRevisionMeta, type HubWorkflowRevisionSource, type HubWorkflowRevisionStatus, type HubWorkflowRun, type HubWorkflowRunCancelResult, type HubWorkflowRunDetail, type HubWorkflowRunEnqueued, type HubWorkflowRunInputs, type HubWorkflowRunRetried, type HubWorkflowRunStatus, type HubWorkflowRunStepsPage, type HubWorkflowRunStreamEvent, type HubWorkflowRunSummary, type HubWorkflowRunsPage, type HubWorkflowSchemaResponse, type HubWorkflowTemplate, type HubWorkflowTemplateCategory, type HubWorkflowTemplateInstantiateResult, type HubWorkflowTemplateParameter, type HubWorkflowTrigger, type HubWorkflowValidateResponse, type HubWorkflowValidationError, HubWorkflowsClient, type VerifyHubEventSignatureInput, authenticateHubEventRequest, deriveHubEventCallbackSecret, parseHubEventDelivery, redactHubValue, resolveHubAuth, resolveHubBaseUrl, verifyHubEventSignature };
 //# sourceMappingURL=index.d.ts.map