Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

48.3 KB
Raw Blame
/**
 * Frontend client for the durable `openhuman.flows_*` run surface (issue B2 /
 * B3 / B4 / B5b). Wraps the subset of controllers the B3a approval card, the
 * B3b run inspector, the B4 agent-proposal card, and the B5b Workflow Canvas
 * need:
 *   - `flows_create`    — persist a new flow (B4 — only ever called from the
 *     user's own "Save & enable" click on `WorkflowProposalCard`; the agent's
 *     `propose_workflow` tool only validates and never reaches this RPC)
 *   - `flows_resume`    — resume a `pending_approval` run past its checkpoint
 *   - `flows_list_runs` — recent runs for a flow, newest first (B3b)
 *   - `flows_get_run`   — a single run record by id (B3b)
 *   - `flows_get`       — a single flow by id, graph included (B5b.1 canvas)
 *
 * Wire shape note: every `crates/openhuman-core/src/flows/ops.rs` handler returns its
 * value via `Outcome::single_log(value, "...")`, which
 * `into_cli_compatible_json` ALWAYS wraps as `{ result: value, logs: [...] }`
 * (see `crates/openhuman-rpc/src/mod.rs`) because a log message is always attached. `callCoreRpc`
 * already unwraps the outer JSON-RPC envelope, so the value this client
 * receives is that `{ result, logs }` object — {@link unwrapCliEnvelope} peels
 * it back to the actual payload. This mirrors the private helper of the same
 * name in `channelConnectionsApi.ts`.
 *
 * `flows_resume`'s payload is NOT a `FlowRun` row — it's the raw tinyflows
 * resume outcome (`{ output, pending_approvals, thread_id }`). The persisted
 * `FlowRun` record (with `status`/`steps`/etc.) only comes back from
 * `flows_list_runs` / `flows_get_run`. The approval card only needs to know
 * the resume call succeeded, so it doesn't need the full row.
 */
import debug from 'debug';

import type { WorkflowGraph } from '../../lib/flows/types';
import { coerceWorkflowProposal } from '../../lib/workflows/workflowProposal';
import type { WorkflowProposal } from '../../store/chatRuntimeSlice';
import { trackAnalyticsEvent } from '../analytics';
import { callCoreRpc } from '../coreRpcClient';

const log = debug('flowsApi');

/**
 * `openhuman.flows_resume` and `openhuman.flows_run` both drive the tinyflows
 * engine and can run up to ~600s server-side (`FLOW_RUN_TIMEOUT_SECS` in
 * `crates/openhuman-core/src/flows/ops.rs`). Give the client a slightly larger budget than
 * the default 30s so a slow run/resume doesn't fail client-side while the
 * engine is still running.
 */
const FLOW_RESUME_TIMEOUT_MS = 610_000;

// ---------------------------------------------------------------------------
// Wire types — mirror `crates/openhuman-core/src/flows/types.rs`. No rename_all attribute
// on the Rust structs, so field names are snake_case on the wire as-is.
// ---------------------------------------------------------------------------

/** Lifecycle status of a durable flow run. */
export type FlowRunStatus =
  | 'running'
  | 'completed'
  | 'completed_with_warnings'
  | 'pending_approval'
  | 'failed'
  | 'cancelled'
  // A run whose future was dropped mid-flight (harness tool abort, chat turn
  // end, timeout, or an app restart), reconciled to a terminal state by the
  // core's `RunRowFinalizer` drop-guard or its boot-time orphan sweep (bug
  // B42). Carries a human `error` reason; rendered as a settled, non-active run.
  | 'interrupted';

/** One reconstructed step of a persisted `FlowRun` (`crates/openhuman-core/src/flows/types.rs::FlowRunStep`). */
export interface FlowRunStep {
  node_id: string;
  output: unknown;
  /** Output port the node routed on, if any (branching/switch nodes). Omitted when absent. */
  port?: string;
  /**
   * Live step outcome as observed by `FlowRunObserver::on_step_finish` — `undefined`
   * for a step reconstructed post-hoc (e.g. the trigger node) rather than
   * observed live, not "unknown/neutral" in the UI sense.
   */
  status?: 'success' | 'error';
  /** Wall-clock duration of this step, if the observer recorded one. */
  duration_ms?: number;
  /**
   * Config `=`-expressions that resolved to `null` while running this step
   * (`location` is the config path, e.g. `args.to`). Empty/absent when clean.
   */
  diagnostics?: Array<{ location: string; expression: string }>;
}

/** A persisted flow run record (`crates/openhuman-core/src/flows/types.rs::FlowRun`). */
export interface FlowRun {
  /** Same value as `thread_id` (the tinyflows checkpointer key). */
  id: string;
  flow_id: string;
  thread_id: string;
  status: FlowRunStatus;
  started_at: string;
  /**
   * RFC3339 timestamp stamped when the run settled — set for every terminal
   * status, including `'interrupted'` (the drop-guard / boot sweep stamps it
   * exactly like a normal terminal write). `null`/absent only while the run is
   * still `'running'`.
   */
  finished_at?: string | null;
  steps: FlowRunStep[];
  /** Node ids paused awaiting approval when `status === 'pending_approval'`. */
  pending_approvals: string[];
  /**
   * Human-readable failure reason. Set for `'failed'` runs and for
   * `'interrupted'` ones (where it carries the reconciliation reason — tool
   * abort / turn end / app restart), so the UI can surface *why* a run stopped
   * rather than showing a bare terminal state.
   */
  error?: string | null;
}

/**
 * Raw resume outcome returned by `openhuman.flows_resume` — the immediate
 * tinyflows engine result, not the persisted `FlowRun` row. Call
 * {@link getFlowRun} afterwards (thread_id === run id) if the caller needs the
 * up-to-date persisted status.
 */
interface FlowResumeResult {
  output: unknown;
  pending_approvals: string[];
  thread_id: string;
}

/**
 * A saved automation workflow (`crates/openhuman-core/src/flows/types.rs::Flow`) — the
 * Workflows list page (B5a) row shape. `graph` is the raw tinyflows
 * `WorkflowGraph`; the list page doesn't need to interpret it, only the
 * canvas (B5b) does, so it's kept as `unknown` here.
 */
export interface Flow {
  /** Stable identifier (UUID) for this flow. */
  id: string;
  /** Human-readable name shown in the Workflows UI. */
  name: string;
  /**
   * One line saying what this automation is for.
   *
   * Empty is normal and must be rendered as such, not as a missing value:
   * every flow saved before this field existed has none, and the canvas does
   * not require one. Surfaced in the agent's skills catalogue, where an empty
   * description falls back to describing the graph's shape.
   */
  description: string;
  /** Whether this flow may currently be triggered/run. */
  enabled: boolean;
  /** The validated, migrated workflow graph — opaque to this client. */
  graph: unknown;
  /** RFC3339 creation timestamp. */
  created_at: string;
  /** RFC3339 last-update timestamp. */
  updated_at: string;
  /** RFC3339 timestamp of the most recent run, if any. */
  last_run_at: string | null;
  /** Outcome of the most recent run: `"completed"` | `"pending_approval"` | `"failed"`. */
  last_status: string | null;
  /** "Require approval for outbound actions" toggle (issue B2). */
  require_approval: boolean;
}

/**
 * Result of `openhuman.flows_validate` (`crates/openhuman-core/src/flows/types.rs::FlowValidation`).
 * `valid === false` means the graph is structurally rejected and won't
 * persist/enable; `warnings` are advisory and orthogonal to validity (a valid
 * graph can still carry them). `errors` carries at most one message — the
 * first structural error tinyflows's validator reports — so it's a
 * graph-level signal, not a per-node list.
 */
export interface FlowValidation {
  valid: boolean;
  /** All structural errors in one pass (multi-error validation), not just the first. */
  errors: string[];
  /** Structured, per-node counterpart to {@link errors} (additive). */
  error_details?: FlowValidationErrorDetail[];
  warnings: string[];
}

/** One structured validation error (`crates/openhuman-core/src/flows/types.rs::FlowValidationError`). */
export interface FlowValidationErrorDetail {
  /** Stable machine-readable code, e.g. `missing_trigger`, `unknown_node`. */
  code: string;
  /** Human-readable message (identical to the matching {@link FlowValidation.errors} entry). */
  message: string;
  /** The node this error anchors to, when node-specific. */
  node_id?: string;
  /** The offending config field, when field-specific (reserved). */
  field?: string;
}

/** Where a {@link FlowDraft} originated (`crates/openhuman-core/src/flows/types.rs::DraftOrigin`). */
type DraftOrigin = 'chat' | 'canvas' | 'import';

/**
 * A core-managed, durable workflow draft (`crates/openhuman-core/src/flows/types.rs::FlowDraft`)
 * — the shared working copy the agent tools and the canvas both read/write by
 * id across turns and reloads. Never live; promote runs the normal save gates.
 */
interface FlowDraft {
  id: string;
  /** The saved flow this draft edits, if any (promote → update vs create). */
  flow_id?: string;
  name: string;
  /** Work-in-progress graph (may be incomplete/invalid) — opaque to this client. */
  graph: unknown;
  origin: DraftOrigin;
  created_at: string;
  updated_at: string;
}

/**
 * Source format for {@link importFlow}. `native` is a tinyflows `WorkflowGraph`
 * JSON; `n8n` is an n8n workflow export (mapped best-effort host-side); `auto`
 * (the default) detects the shape.
 */
type FlowImportFormat = 'native' | 'n8n' | 'auto';

/**
 * Result of `openhuman.flows_import` (`crates/openhuman-core/src/flows/types.rs::FlowImport`).
 * The `graph` is the normalized, migrated + validated `WorkflowGraph` ready to
 * open on the canvas as an unsaved draft; `warnings` carries non-fatal import
 * notes (unmapped n8n node types, untranslated expressions, a synthesized or
 * demoted trigger). Import NEVER persists — the user Saves via the normal gate.
 */
interface FlowImport {
  graph: unknown;
  warnings: string[];
}

/**
 * A secret-free credential reference for the node-config credential picker
 * (`crates/openhuman-core/src/flows/types.rs::FlowConnection`). `connection_ref` is
 * `"composio:<toolkit>:<connection_id>"` (composio) or `"http_cred:<name>"`
 * (raw HTTP cred). `toolkit` is present only for composio; `scheme`
 * (`"bearer"|"basic"|"header"`) only for http.
 */
export interface FlowConnection {
  connection_ref: string;
  kind: 'composio' | 'http';
  display: string;
  toolkit?: string;
  scheme?: string;
}

/** Optional fields for {@link updateFlow}. Omitted fields are left untouched. */
interface FlowUpdate {
  name?: string;
  /** Omit to leave the stored description untouched; `''` clears it. */
  description?: string;
  graph?: unknown;
  requireApproval?: boolean;
  /**
   * Optimistic-concurrency token: the flow's `updated_at` as last observed. If
   * the flow changed since, the update is refused with a {@link FlowVersionConflict}
   * error instead of clobbering. Omit for last-write-wins.
   */
  expectedVersion?: string;
  /** Run the agent author hard-gates before persisting (F3). */
  strict?: boolean;
}

/** A revision snapshot (`crates/openhuman-core/src/flows/types.rs::FlowRevision`). */
interface FlowRevision {
  id: string;
  flow_id: string;
  graph: unknown;
  name: string;
  require_approval: boolean;
  created_at: string;
}

/**
 * The structured error `flows_update` returns on an optimistic-concurrency
 * conflict (encoded in the RPC error message as JSON). Detect it by parsing a
 * caught update error — see {@link parseFlowVersionConflict}.
 */
interface FlowVersionConflict {
  code: 'version_conflict';
  message: string;
  current: Flow;
}

/**
 * If `err` is a `flows_update` version-conflict error, returns the structured
 * conflict (with the current server flow) so the UI can offer reload/diff;
 * otherwise `null`.
 *
 * @knipignore Documented flow history extension contract.
 */
export function parseFlowVersionConflict(err: unknown): FlowVersionConflict | null {
  const message = err instanceof Error ? err.message : typeof err === 'string' ? err : '';
  if (!message.includes('version_conflict')) return null;
  try {
    const parsed = JSON.parse(message) as Partial<FlowVersionConflict>;
    if (parsed?.code === 'version_conflict' && parsed.current) {
      return parsed as FlowVersionConflict;
    }
  } catch {
    // Not a JSON conflict payload.
  }
  return null;
}

/** Lifecycle status of a {@link FlowSuggestion} (`crates/openhuman-core/src/flows/types.rs::SuggestionStatus`). */
export type SuggestionStatus = 'new' | 'dismissed' | 'built';

/**
 * A Flow Scout workflow suggestion (`crates/openhuman-core/src/flows/types.rs::FlowSuggestion`)
 * — a *pitch*, not a graph. Rendered as a card in the Flows page "Suggested for
 * you" section. `build_prompt` is the natural-language brief handed to the
 * `workflow_builder` agent when the user clicks "Build this".
 */
export interface FlowSuggestion {
  id: string;
  title: string;
  one_liner: string;
  rationale: string;
  /** `schedule` | `app_event` | `manual` — omitted when the agent didn't set one. */
  trigger_hint?: string | null;
  steps_outline: string[];
  suggested_connections: string[];
  suggested_slugs: string[];
  build_prompt: string;
  confidence: number;
  status: SuggestionStatus;
  created_at: string;
  source_run_id?: string | null;
}

// ---------------------------------------------------------------------------
// CLI-compatible envelope unwrapping.
// ---------------------------------------------------------------------------

function asRecord(value: unknown): Record<string, unknown> | null {
  if (!value || typeof value !== 'object' || Array.isArray(value)) {
    return null;
  }
  return value as Record<string, unknown>;
}

/**
 * Every `flows_*` handler goes through `Outcome::single_log`, so the value
 * `callCoreRpc` resolves is always `{ result: <payload>, logs: string[] }`.
 * Peel that back to `<payload>`. Falls through unchanged if the shape doesn't
 * match (defensive — keeps this client working if a future handler switches
 * to a log-less `Outcome::new` and stops wrapping).
 */
function unwrapCliEnvelope<T>(payload: unknown): T {
  const record = asRecord(payload);
  if (record && 'result' in record && 'logs' in record && Array.isArray(record.logs)) {
    return record.result as T;
  }
  return payload as T;
}

// ---------------------------------------------------------------------------
// RPC client.
// ---------------------------------------------------------------------------

/**
 * Create (and, by default, enable) a new saved flow via `openhuman.flows_create`
 * (issue B4). This is the ONLY path that persists a flow — the agent's
 * `propose_workflow` tool (`crates/openhuman-core/src/flows/tools.rs`) only validates a
 * candidate graph and returns a summary; `WorkflowProposalCard`'s "Save &
 * enable" button is what calls this function, directly from the client, on
 * the user's explicit action. `requireApproval` defaults server-side to
 * `false` when omitted, but the B4 proposal flow always passes it explicitly
 * (defaulting to `true` on the Rust tool side) so a saved agent-proposed flow
 * starts with its outbound-action approval gate on.
 *
 * B29 (save/enable safety) Rule 1: when `graph`'s trigger fires without a
 * human in the loop (`schedule` / `app_event` / `webhook`), the server
 * ALWAYS persists the flow `enabled: false`, regardless of what the caller
 * intended — no creation path may silently hand back an armed, unattended
 * automation. The returned {@link Flow}'s `enabled` field reflects this, so
 * every caller MUST check it: if the caller represents an explicit
 * user-arming action (e.g. `WorkflowProposalCard`'s "Save & enable" click),
 * follow up with {@link setFlowEnabled} to actually arm it — that is a
 * legitimate explicit enable, not the silent copilot auto-arm Rule 1 guards
 * against. A caller with no such explicit intent (e.g. a background/copilot
 * save) should leave it disabled and let the user arm it later.
 */
export async function createFlow(
  name: string,
  graph: unknown,
  requireApproval?: boolean,
  description?: string
): Promise<Flow> {
  log('createFlow: request name=%s requireApproval=%s', name, requireApproval ?? 'default');
  const params: Record<string, unknown> = { name, graph };
  if (requireApproval !== undefined) params.require_approval = requireApproval;
  if (description !== undefined) params.description = description;
  const response = await callCoreRpc<unknown>({ method: 'openhuman.flows_create', params });
  const flow = unwrapCliEnvelope<Flow>(response);
  log('createFlow: response id=%s name=%s enabled=%s', flow.id, flow.name, flow.enabled);
  return flow;
}

/**
 * Resume a `pending_approval` flow run past its checkpoint via
 * `openhuman.flows_resume`. `approvals` should name the node ids from the
 * triggering notification's `node_ids` payload — the Rust side rejects the
 * call outright unless at least one named id matches a currently-pending gate.
 */
export async function resumeFlow(
  id: string,
  threadId: string,
  approvals: string[]
): Promise<FlowResumeResult> {
  log('resumeFlow: request id=%s threadId=%s approvals=%o', id, threadId, approvals);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_resume',
    params: { id, thread_id: threadId, approvals },
    timeoutMs: FLOW_RESUME_TIMEOUT_MS,
  });
  const result = unwrapCliEnvelope<FlowResumeResult>(response);
  log(
    'resumeFlow: response threadId=%s pendingApprovals=%d',
    result.thread_id,
    result.pending_approvals?.length ?? 0
  );
  trackAnalyticsEvent('automation_run_resumed', { automation_kind: 'flow' });
  return result;
}

/**
 * List recent runs for a flow, newest first, via `openhuman.flows_list_runs`.
 * `limit` defaults to 20 server-side. Not used by the B3a approval card —
 * exported now for the B3b run-history inspector.
 */
export async function listFlowRuns(flowId: string, limit?: number): Promise<FlowRun[]> {
  log('listFlowRuns: request flowId=%s limit=%s', flowId, limit ?? 'default');
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_list_runs',
    params: limit === undefined ? { id: flowId } : { id: flowId, limit },
  });
  const runs = unwrapCliEnvelope<FlowRun[]>(response);
  log('listFlowRuns: response count=%d', runs.length);
  return runs;
}

/**
 * List the most recent runs across ALL flows, newest first, via
 * `openhuman.flows_list_all_runs` (the aggregate "All runs" page). `limit`
 * defaults to 100 server-side. Each run carries its `flow_id` for grouping.
 */
export async function listAllFlowRuns(limit?: number): Promise<FlowRun[]> {
  log('listAllFlowRuns: request limit=%s', limit ?? 'default');
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_list_all_runs',
    params: limit === undefined ? {} : { limit },
  });
  const runs = unwrapCliEnvelope<FlowRun[]>(response);
  log('listAllFlowRuns: response count=%d', runs.length);
  return runs;
}

/**
 * Load a single flow run record by id (== thread_id) via
 * `openhuman.flows_get_run`. Not used by the B3a approval card — exported now
 * for the B3b run-history inspector.
 */
export async function getFlowRun(runId: string): Promise<FlowRun> {
  log('getFlowRun: request runId=%s', runId);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_get_run',
    params: { run_id: runId },
  });
  const run = unwrapCliEnvelope<FlowRun>(response);
  log('getFlowRun: response id=%s status=%s', run.id, run.status);
  return run;
}

/**
 * List all saved flows via `openhuman.flows_list` (the Workflows list page,
 * B5a). No params. Unlike the run-surface calls above, the payload IS the
 * `Flow[]` array directly — there is no outer `{ flows: [...] }` wrapper (see
 * `crates/openhuman-core/src/flows/ops.rs::flows_list`, which returns `Vec<Flow>`
 * straight through `Outcome::single_log`).
 */
export async function listFlows(): Promise<Flow[]> {
  log('listFlows: request');
  const response = await callCoreRpc<unknown>({ method: 'openhuman.flows_list', params: {} });
  const flows = unwrapCliEnvelope<Flow[]>(response);
  log('listFlows: response count=%d', flows.length);
  return flows;
}

/**
 * Enable or disable a saved flow via `openhuman.flows_set_enabled`. Returns
 * the updated `Flow` row directly (same no-wrapper shape as `flows_list`'s
 * elements).
 */
export async function setFlowEnabled(id: string, enabled: boolean): Promise<Flow> {
  log('setFlowEnabled: request id=%s enabled=%s', id, enabled);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_set_enabled',
    params: { id, enabled },
  });
  const flow = unwrapCliEnvelope<Flow>(response);
  log('setFlowEnabled: response id=%s enabled=%s', flow.id, flow.enabled);
  return flow;
}

/**
 * Load a single saved flow by id via `openhuman.flows_get` (the Workflow
 * Canvas, B5b.1). Returns the `Flow` directly (same no-wrapper shape as
 * `flows_list`'s elements and `flows_set_enabled` — see
 * `crates/openhuman-core/src/flows/schemas.rs::handle_get`, which delegates straight to
 * `ops::flows_get` through `Outcome::single_log`).
 */
export async function getFlow(id: string): Promise<Flow> {
  log('getFlow: request id=%s', id);
  const response = await callCoreRpc<unknown>({ method: 'openhuman.flows_get', params: { id } });
  const flow = unwrapCliEnvelope<Flow>(response);
  log('getFlow: response id=%s name=%s', flow.id, flow.name);
  return flow;
}

/**
 * Run a saved flow to completion (or until it pauses on a human-approval
 * gate) via `openhuman.flows_run`. This is the call that actually drives the
 * tinyflows engine, so it shares `flows_resume`'s ~600s server-side budget
 * (see {@link FLOW_RESUME_TIMEOUT_MS}). This BLOCKS the caller until the run
 * settles — prefer {@link runFlowDetached} for any UI entry point (Run
 * buttons) that must not freeze while a run is in flight; `runFlow` remains
 * for callers that genuinely want to await the final result.
 *
 * `input` is the free-form trigger payload. `inputs` supplies values for the
 * flow's *declared* workflow inputs by name — read the declarations from the
 * flow's `graph.inputs`. A missing required value, a wrong type, or a name the
 * flow does not declare is rejected server-side before the run starts, so this
 * rejects without leaving a run row behind.
 */
export async function runFlow(
  id: string,
  input?: unknown,
  inputs?: Record<string, unknown>
): Promise<FlowResumeResult> {
  log('runFlow: request id=%s inputs=%d', id, Object.keys(inputs ?? {}).length);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_run',
    params: { id, input: input ?? null, inputs: inputs ?? null },
    timeoutMs: FLOW_RESUME_TIMEOUT_MS,
  });
  const result = unwrapCliEnvelope<FlowResumeResult>(response);
  log(
    'runFlow: response threadId=%s pendingApprovals=%d',
    result.thread_id,
    result.pending_approvals?.length ?? 0
  );
  trackAnalyticsEvent('automation_run_started', { automation_kind: 'flow' });
  return result;
}

/**
 * Immediate response from `openhuman.flows_run_detached` — the run has been
 * registered and its `running` row inserted, but it has NOT finished (or even
 * necessarily started executing its first action node) yet. Poll
 * {@link getFlowRun} / subscribe to `flow:run_progress` for the terminal
 * state — see {@link runFlowDetached}.
 */
export interface FlowRunDetachedResult {
  run_id: string;
  flow_id: string;
  status: 'running';
  detached: true;
}

/**
 * Start a saved flow WITHOUT waiting for it to finish, via
 * `openhuman.flows_run_detached` (F-M1 / F-M2). Unlike {@link runFlow}, this
 * returns as soon as the run is registered and its `running` row exists — well
 * under a second, regardless of how long the flow itself takes — so it uses
 * the client's *default* RPC timeout rather than {@link FLOW_RESUME_TIMEOUT_MS}.
 *
 * This is the fire-and-forget entry point both UI Run controls use (the
 * Workflow Canvas overlay and the Workflows list row action): calling it
 * BEFORE subscribing to progress would be pointless (nothing to subscribe
 * to yet), so callers should set up their `flow:run_progress` subscription /
 * poller using the returned `run_id` immediately after this resolves, not
 * after the run itself completes.
 *
 * `inputs` carries values for the flow's *declared* workflow inputs by name
 * (see {@link runFlow}). Because this is the entry point both Run controls use,
 * a flow with a required input is only runnable from the UI through here — the
 * caller is expected to collect the values first. They are validated
 * synchronously, so a bad set rejects here rather than surfacing later as a
 * failed background run.
 */
export async function runFlowDetached(
  id: string,
  input?: unknown,
  inputs?: Record<string, unknown>
): Promise<FlowRunDetachedResult> {
  log('runFlowDetached: request id=%s inputs=%d', id, Object.keys(inputs ?? {}).length);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_run_detached',
    params: { id, input: input ?? null, inputs: inputs ?? null },
  });
  const result = unwrapCliEnvelope<FlowRunDetachedResult>(response);
  log(
    'runFlowDetached: response runId=%s status=%s detached=%s',
    result.run_id,
    result.status,
    result.detached
  );
  trackAnalyticsEvent('automation_run_started', { automation_kind: 'flow' });
  return result;
}

/**
 * Permanently delete a saved flow via `openhuman.flows_delete`. The server
 * unbinds any live trigger (schedule cron job / app-event binding) before
 * removing the row, so deleting an enabled flow also stops it firing. Returns
 * the removed id (the payload is `{ id, removed: true }`); callers typically
 * just refetch the list.
 */
export async function deleteFlow(id: string): Promise<string> {
  log('deleteFlow: request id=%s', id);
  const response = await callCoreRpc<unknown>({ method: 'openhuman.flows_delete', params: { id } });
  const payload = unwrapCliEnvelope<{ id: string; removed: boolean }>(response);
  log('deleteFlow: response id=%s removed=%s', payload.id, payload.removed);
  return payload.id;
}

/**
 * Duplicate a saved flow via `openhuman.flows_duplicate`. The copy is created
 * DISABLED and unbound (no live trigger), with a derived name, so duplicating an
 * enabled flow never silently starts a second live schedule. Returns the new
 * `Flow` row.
 */
export async function duplicateFlow(id: string): Promise<Flow> {
  log('duplicateFlow: request id=%s', id);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_duplicate',
    params: { id },
  });
  const flow = unwrapCliEnvelope<Flow>(response);
  log('duplicateFlow: response newId=%s name=%s', flow.id, flow.name);
  return flow;
}

/**
 * Update a saved flow's name and/or graph via `openhuman.flows_update` (the
 * Workflow Canvas Save path, B5b.2 / Phase 3d). The server re-validates the
 * graph before persisting and rejects a structurally-invalid one, so callers
 * should {@link validateFlow} first to surface errors pre-save. Omitted fields
 * are left untouched; returns the updated `Flow` row.
 */
export async function updateFlow(id: string, update: FlowUpdate): Promise<Flow> {
  log(
    'updateFlow: request id=%s name=%s graph=%s requireApproval=%s',
    id,
    update.name ?? '(unchanged)',
    update.graph === undefined ? '(unchanged)' : 'present',
    update.requireApproval ?? 'unchanged'
  );
  const params: Record<string, unknown> = { id };
  if (update.name !== undefined) params.name = update.name;
  if (update.description !== undefined) params.description = update.description;
  if (update.graph !== undefined) params.graph = update.graph;
  if (update.requireApproval !== undefined) params.require_approval = update.requireApproval;
  if (update.expectedVersion !== undefined) params.expected_version = update.expectedVersion;
  if (update.strict !== undefined) params.strict = update.strict;
  const response = await callCoreRpc<unknown>({ method: 'openhuman.flows_update', params });
  const flow = unwrapCliEnvelope<Flow>(response);
  log('updateFlow: response id=%s name=%s', flow.id, flow.name);
  return flow;
}

/**
 * List a flow's revision history via `openhuman.flows_get_history` (newest first).
 *
 * @knipignore Documented flow history extension contract.
 */
export async function getFlowHistory(id: string, limit?: number): Promise<FlowRevision[]> {
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_get_history',
    params: { id, limit },
  });
  const result = unwrapCliEnvelope<{ revisions: FlowRevision[] }>(response);
  return result.revisions ?? [];
}

/**
 * Roll a flow back to a prior revision via `openhuman.flows_rollback` (restores
 * that revision's graph through the normal update path — itself snapshotted, so
 * a rollback is undoable). Honours optimistic concurrency via `expectedVersion`.
 *
 * @knipignore Documented flow history extension contract.
 */
export async function rollbackFlow(
  id: string,
  revisionId: string,
  expectedVersion?: string
): Promise<Flow> {
  log('rollbackFlow: request id=%s revision=%s', id, revisionId);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_rollback',
    params: { id, revision_id: revisionId, expected_version: expectedVersion },
  });
  return unwrapCliEnvelope<Flow>(response);
}

/**
 * Validate a candidate `WorkflowGraph` via `openhuman.flows_validate`. Pure and
 * cheap server-side (no config load), so it's safe to call on a debounce while
 * editing. Returns {@link FlowValidation} — check `valid` to gate Save, and
 * surface `warnings` separately (they never block).
 */
export async function validateFlow(graph: unknown): Promise<FlowValidation> {
  log('validateFlow: request');
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_validate',
    params: { graph },
  });
  const validation = unwrapCliEnvelope<FlowValidation>(response);
  log(
    'validateFlow: response valid=%s errors=%d warnings=%d',
    validation.valid,
    validation.errors.length,
    validation.warnings.length
  );
  return validation;
}

/**
 * List the secret-free credential references (composio + http) available to a
 * node's config credential picker via `openhuman.flows_list_connections`. No
 * params; returns the `FlowConnection[]` directly (same no-wrapper shape as
 * `flows_list`).
 */
export async function listFlowConnections(): Promise<FlowConnection[]> {
  log('listFlowConnections: request');
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_list_connections',
    params: {},
  });
  const connections = unwrapCliEnvelope<FlowConnection[]>(response);
  log('listFlowConnections: response count=%d', connections.length);
  return connections;
}

/**
 * Import a workflow definition (native tinyflows JSON or an n8n export) via
 * `openhuman.flows_import`. The server migrates + validates it host-side and
 * returns the normalized graph plus non-fatal warnings WITHOUT persisting — the
 * caller opens the result on the canvas as a draft and Saves via the existing
 * `flows_create` gate. Rejects (throws) when the definition is structurally
 * invalid or unparseable server-side, so the UI can surface a load error
 * instead of opening a broken canvas.
 */
export async function importFlow(
  graph: unknown,
  format: FlowImportFormat = 'auto'
): Promise<FlowImport> {
  log('importFlow: request format=%s', format);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_import',
    params: { graph, format },
  });
  const result = unwrapCliEnvelope<FlowImport>(response);
  log('importFlow: response warnings=%d', result.warnings?.length ?? 0);
  return result;
}

// ── Catalog RPCs for the UI (Phase 5, item 16) ───────────────────────────────

/** One search hit from `openhuman.flows_search_tool_catalog` (secret-free). */
interface ToolCatalogEntry {
  slug: string;
  toolkit: string;
  description?: string | null;
  required_args?: string[];
  output_fields?: string[];
  primary_array_path?: string | null;
  /** Curated/featured toolkits rank first. */
  featured?: boolean;
}

/**
 * Search the live Composio tool catalog via `openhuman.flows_search_tool_catalog`.
 *
 * @knipignore Documented tool catalog extension contract.
 */
export async function searchToolCatalog(
  query: string,
  opts?: { toolkit?: string; limit?: number }
): Promise<ToolCatalogEntry[]> {
  log('searchToolCatalog: query=%s toolkit=%s', query, opts?.toolkit ?? '(all)');
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_search_tool_catalog',
    params: { query, toolkit: opts?.toolkit, limit: opts?.limit },
    timeoutMs: 60_000,
  });
  const result = unwrapCliEnvelope<{ tools: ToolCatalogEntry[] }>(response);
  return result.tools ?? [];
}

/** A toolkit a graph needs, with its connected state (Phase 5, item 18). */
interface RequiredConnection {
  toolkit: string;
  status: 'connected' | 'missing';
}

/**
 * Compute which Composio toolkits a candidate graph needs and whether each is
 * connected, via `openhuman.flows_required_connections` — the data behind the
 * "Connect <toolkit>" CTAs. Also surfaced on the workflow_proposal payload.
 *
 * @knipignore Documented tool catalog extension contract.
 */
export async function requiredConnections(graph: unknown): Promise<RequiredConnection[]> {
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_required_connections',
    params: { graph },
  });
  const result = unwrapCliEnvelope<{ required_connections: RequiredConnection[] }>(response);
  return result.required_connections ?? [];
}

// ── Save-time approval manifest (consolidated pre-authorization card) ───────

/** One row of the save+enable approval manifest. */
export interface ApprovalManifestEntry {
  /**
   * approvable — will park a run; pre-approving `tool_name` clears it.
   * blocked — refused outright by the autonomy tier; informational only.
   * dynamic — tool chosen at run time (`=` slug); cannot be pre-approved.
   * agent — AI step whose inner tool calls are unknown at save time.
   */
  kind: 'approvable' | 'blocked' | 'dynamic' | 'agent';
  node_id: string;
  /** The ApprovalGate trust key. Present for approvable/blocked rows. */
  tool_name?: string;
  label: string;
  class?: string;
}

/** Result of `openhuman.flows_approval_manifest`. */
export interface ApprovalManifest {
  entries: ApprovalManifestEntry[];
  /** Approvable trust keys the flow does not yet hold — what the card asks for. */
  missing: string[];
  /**
   * Approvable trust keys this flow already holds a grant for. Empty whenever
   * `gate_installed` is false: with no gate no grant was ever made, so nothing
   * can be reported as authorized.
   */
  already_trusted: string[];
  /** False when the approval gate is disabled — nothing ever prompts. */
  gate_installed: boolean;
}

/**
 * Compute the approval manifest for a saved flow (by id) or candidate graph
 * via `openhuman.flows_approval_manifest` — every permission a run will
 * prompt for, joined against the flow's existing per-flow trust grants. The
 * data behind the consolidated save+enable pre-authorization card.
 */
export async function getApprovalManifest(
  target: { id: string } | { graph: unknown }
): Promise<ApprovalManifest> {
  log('getApprovalManifest: %s', 'id' in target ? `id=${target.id}` : 'candidate graph');
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_approval_manifest',
    params: 'id' in target ? { id: target.id } : { graph: target.graph },
  });
  const result = unwrapCliEnvelope<ApprovalManifest>(response);
  return {
    entries: result.entries ?? [],
    missing: result.missing ?? [],
    already_trusted: result.already_trusted ?? [],
    gate_installed: result.gate_installed ?? true,
  };
}

/**
 * Fetch one action's full contract via `openhuman.flows_get_tool_contract`.
 *
 * @knipignore Documented tool catalog extension contract.
 */
export async function getToolContract(slug: string): Promise<unknown> {
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_get_tool_contract',
    params: { slug },
    timeoutMs: 60_000,
  });
  const result = unwrapCliEnvelope<{ contract: unknown }>(response);
  return result.contract;
}

// ── Core-managed drafts (F5) ─────────────────────────────────────────────────

/**
 * Create a durable draft via `openhuman.flows_draft_create`.
 *
 * @knipignore Documented durable draft extension contract.
 */
export async function createDraft(params: {
  name: string;
  graph: unknown;
  flowId?: string;
  origin?: DraftOrigin;
}): Promise<FlowDraft> {
  log('createDraft: request origin=%s', params.origin ?? 'canvas');
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_draft_create',
    params: {
      name: params.name,
      graph: params.graph,
      flow_id: params.flowId,
      origin: params.origin,
    },
  });
  return unwrapCliEnvelope<FlowDraft>(response);
}

/**
 * Fetch a draft by id via `openhuman.flows_draft_get`.
 *
 * @knipignore Documented durable draft extension contract.
 */
export async function getDraft(id: string): Promise<FlowDraft> {
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_draft_get',
    params: { id },
  });
  return unwrapCliEnvelope<FlowDraft>(response);
}

/**
 * Patch a draft's name/graph/flow_id via `openhuman.flows_draft_update`.
 *
 * @knipignore Documented durable draft extension contract.
 */
export async function updateDraft(
  id: string,
  patch: { name?: string; graph?: unknown; flowId?: string }
): Promise<FlowDraft> {
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_draft_update',
    params: { id, name: patch.name, graph: patch.graph, flow_id: patch.flowId },
  });
  return unwrapCliEnvelope<FlowDraft>(response);
}

/**
 * List all drafts (newest-updated first) via `openhuman.flows_draft_list`.
 *
 * @knipignore Documented durable draft extension contract.
 */
export async function listDrafts(): Promise<FlowDraft[]> {
  const response = await callCoreRpc<unknown>({ method: 'openhuman.flows_draft_list', params: {} });
  const result = unwrapCliEnvelope<{ drafts: FlowDraft[] }>(response);
  return result.drafts ?? [];
}

/**
 * Delete a draft via `openhuman.flows_draft_delete`.
 *
 * @knipignore Documented durable draft extension contract.
 */
export async function deleteDraft(id: string): Promise<boolean> {
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_draft_delete',
    params: { id },
  });
  const result = unwrapCliEnvelope<{ id: string; deleted: boolean }>(response);
  return result.deleted;
}

/**
 * Promote a draft into a saved flow via `openhuman.flows_draft_promote` (runs
 * the normal create/update gates, then removes the draft). Returns the Flow.
 *
 * @knipignore Documented durable draft extension contract.
 */
export async function promoteDraft(id: string, requireApproval?: boolean): Promise<Flow> {
  log('promoteDraft: request id=%s', id);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_draft_promote',
    params: { id, require_approval: requireApproval },
  });
  return unwrapCliEnvelope<Flow>(response);
}

/**
 * `openhuman.flows_discover` runs the read-only Flow Scout agent, which reasons
 * over the user's memory/threads/connections/flows and can take up to ~600s
 * server-side (`FLOW_DISCOVER_TIMEOUT_SECS` in `crates/openhuman-core/src/flows/ops.rs`,
 * raised to match `FLOW_BUILD_TIMEOUT_SECS` for the same iteration cap). Give
 * the client a matching budget (mirrors {@link FLOW_BUILD_TIMEOUT_MS}) so a
 * slow discovery run doesn't time out client-side while the agent is still
 * thinking.
 */
const FLOW_DISCOVER_TIMEOUT_MS = 610_000;

/**
 * Run the Flow Scout discovery agent via `openhuman.flows_discover` and return
 * the active (new) suggestions it produced. Read-only server-side — it never
 * creates, enables, or runs a flow. Returns the `FlowSuggestion[]` directly
 * (same no-wrapper shape as `flows_list`).
 */
export async function discoverWorkflows(threadId?: string | null): Promise<FlowSuggestion[]> {
  log('discoverWorkflows: request thread=%s', threadId ?? '<none>');
  // When a caller passes a chat thread id, the server streams the Flow Scout
  // turn's text/tool events onto that thread (Phase B) so a shared chat pane can
  // render them live. The param name matches the `thread_id` convention in
  // `crates/openhuman-core/src/flows/schemas.rs` (a per-turn `request_id` is minted
  // server-side when omitted). Omitting it keeps the headless behaviour.
  const params: Record<string, unknown> = {};
  if (threadId) params.thread_id = threadId;
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_discover',
    params,
    timeoutMs: FLOW_DISCOVER_TIMEOUT_MS,
  });
  const suggestions = unwrapCliEnvelope<FlowSuggestion[]>(response);
  log('discoverWorkflows: response count=%d', suggestions.length);
  return suggestions;
}

/**
 * List persisted workflow suggestions via `openhuman.flows_list_suggestions`.
 * `status` filters to one lifecycle state (`new` for the active cards); omit
 * for all. Returns the `FlowSuggestion[]` directly.
 */
export async function listSuggestions(status?: SuggestionStatus): Promise<FlowSuggestion[]> {
  log('listSuggestions: request status=%s', status ?? 'all');
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_list_suggestions',
    params: status === undefined ? {} : { status },
  });
  const suggestions = unwrapCliEnvelope<FlowSuggestion[]>(response);
  log('listSuggestions: response count=%d', suggestions.length);
  return suggestions;
}

// ─────────────────────────────────────────────────────────────────────────────
// flows_build — run the workflow_builder agent for one authoring turn.
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Which authoring turn to run (mirrors the Rust `BuildMode`). The server renders
 * the agent's natural-language brief from this — the frontend no longer crafts
 * delegate prompts.
 */
export type BuilderTurnMode = 'create' | 'revise' | 'repair' | 'build';

/** A structured workflow-builder turn request. */
export interface BuilderTurnRequest {
  /** Which kind of turn to run. */
  mode: BuilderTurnMode;
  /** The user's ask: description (create/build) or change instruction (revise). */
  instruction: string;
  /** The current draft graph, injected as context for revise/repair/build. */
  graph?: WorkflowGraph | null;
  /** Saved flow id (required for `build`; optional elsewhere for run-to-test). */
  flowId?: string | null;
  /** Failed run id (== thread id) for `repair`. */
  runId?: string | null;
  /** Run-level error message for `repair`, if known. */
  error?: string | null;
  /** Node ids implicated in the failure, for `repair`. */
  failingNodeIds?: string[];
}

/** The result of one builder turn. */
export interface BuilderTurnResult {
  /** The proposal the agent produced (mapped to the store shape), or null. */
  proposal: WorkflowProposal | null;
  /** The agent's final assistant text (rendered as its chat turn). */
  assistantText: string;
  /** A run error, if the turn failed but a prior proposal was still captured. */
  error: string | null;
  /**
   * `true` when the turn paused because it hit the agent's tool-call budget
   * (`max_tool_iterations`) with no proposal yet — as opposed to the agent
   * voluntarily asking a clarifying question or finishing. `assistantText` is
   * a "Done so far / Next steps" checkpoint in this case; the UI should offer
   * a "Continue building" action rather than rendering it as a normal reply.
   */
  capped: boolean;
}

/**
 * The `workflow_builder` agent can take up to ~600s server-side
 * (`FLOW_BUILD_TIMEOUT_SECS` in `crates/openhuman-core/src/flows/ops.rs`); match it so a slow
 * authoring turn doesn't time out client-side while the agent is still working.
 */
const FLOW_BUILD_TIMEOUT_MS = 610_000;

/**
 * Run one `workflow_builder` authoring turn via `openhuman.flows_build`. The
 * server renders the agent's brief from `request`, runs the agent to completion,
 * and returns its proposal + final assistant text. This is the backend-agent
 * path that replaces the frontend's old "craft a delegate prompt and route it
 * through the chat orchestrator" approach.
 */
export async function buildWorkflow(
  request: BuilderTurnRequest,
  threadId?: string | null
): Promise<BuilderTurnResult> {
  log(
    'buildWorkflow: request mode=%s flowId=%s thread=%s',
    request.mode,
    request.flowId ?? '<none>',
    threadId ?? '<none>'
  );
  const params: Record<string, unknown> = {
    mode: request.mode,
    instruction: request.instruction,
    graph: request.graph ?? null,
    flow_id: request.flowId ?? null,
    run_id: request.runId ?? null,
    error: request.error ?? null,
    failing_node_ids: request.failingNodeIds ?? [],
  };
  // When the copilot passes its dedicated chat thread id, the server streams the
  // builder turn's text/thinking/tool events onto that thread (Phase B) so the
  // shared chat pane renders them live and `ChatRuntimeProvider` appends the
  // final assistant message on `chat_done`. Param name matches the `thread_id`
  // convention in `crates/openhuman-core/src/flows/schemas.rs`; a per-turn `request_id` is
  // minted server-side when omitted. Omitting it keeps the headless behaviour.
  if (threadId) params.thread_id = threadId;
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_build',
    params,
    timeoutMs: FLOW_BUILD_TIMEOUT_MS,
  });
  const result = unwrapCliEnvelope<{
    proposal: unknown;
    assistant_text: string;
    error: string | null;
    capped?: boolean;
  }>(response);
  log(
    'buildWorkflow: response hasProposal=%s capped=%s',
    result.proposal != null,
    result.capped ?? false
  );
  return {
    proposal: coerceWorkflowProposal(result.proposal),
    assistantText: result.assistant_text ?? '',
    error: result.error ?? null,
    capped: result.capped ?? false,
  };
}

/**
 * Cancel the in-flight `flows_build` (Workflow Copilot) turn streaming into
 * `threadId` via `openhuman.flows_build_cancel` — the real cancellation
 * behind the composer's Stop button (the RPC actually signals the running
 * `workflow_builder` agent turn to stop, unlike the shared `chatCancel`
 * primitive, which only ever tore down a spawned interactive chat turn and
 * silently no-ops for a `flows_build` turn since it runs inline and was never
 * registered anywhere `channel_web_cancel` looks).
 *
 * `requestId`, when given, scopes the cancel so a stale Stop click for a
 * superseded/earlier request can't kill a newer turn that has since started
 * on the same thread (mirrors the server's `cancel_build_turn_scoped`).
 * Returns the server's `cancelled` field — `false` is not an error, it just
 * means nothing was in flight to cancel.
 */
export async function flowsBuildCancel(threadId: string, requestId?: string): Promise<boolean> {
  log('flowsBuildCancel: request thread=%s requestId=%s', threadId, requestId ?? '<none>');
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_build_cancel',
    params: { thread_id: threadId, request_id: requestId ?? null },
  });
  const result = unwrapCliEnvelope<{ cancelled: boolean }>(response);
  log('flowsBuildCancel: response cancelled=%s', result.cancelled);
  return result.cancelled ?? false;
}

/**
 * Dismiss a suggestion via `openhuman.flows_dismiss_suggestion` (the user
 * rejected the card). The row is kept server-side so a later discovery run
 * dedupes against it and won't re-surface the idea.
 */
export async function dismissSuggestion(id: string): Promise<boolean> {
  log('dismissSuggestion: request id=%s', id);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_dismiss_suggestion',
    params: { id },
  });
  const result = unwrapCliEnvelope<{ id: string; dismissed: boolean }>(response);
  log('dismissSuggestion: response dismissed=%s', result.dismissed);
  return result.dismissed;
}

/**
 * Mark a suggestion as built via `openhuman.flows_mark_suggestion_built` —
 * called after the user saves a flow authored from it, so it drops out of the
 * active cards.
 */
export async function markSuggestionBuilt(id: string): Promise<boolean> {
  log('markSuggestionBuilt: request id=%s', id);
  const response = await callCoreRpc<unknown>({
    method: 'openhuman.flows_mark_suggestion_built',
    params: { id },
  });
  const result = unwrapCliEnvelope<{ id: string; built: boolean }>(response);
  log('markSuggestionBuilt: response built=%s', result.built);
  return result.built;
}