@openparachute/agent 0.1.2 → 0.2.2

package/web/ui/src/components/setup/PrereqStep.tsx

@@ -1,129 +0,0 @@
-/**
- * Step 1 — Prereqs (post-rebirth: navigator).
- *
- * Calls GET /api/setup/status, renders one row per check (secrets backend,
- * hub discovery, vault attached, channel-token presence) with the {ok,
- * detail, fix} the server returns. Each blocker links out to the right
- * fix surface — credential issues route to /secrets (paraclaw-native),
- * vault issues route to the agent group create flow, hub issues link to
- * the parachute hub docs.
- *
- * The wizard's credential-capture step is gone (night/ui rebirth) — this
- * page is now the navigator. If the operator needs to add a token, the
- * "Add credential" button takes them to /secrets pre-filled with the
- * pinned secret name; they come back to /setup and click "Re-check".
- *
- * Why we render `fix` verbatim from the server: the hint is canonical (it
- * knows which env var is missing, which subcommand to run); inventing a
- * UI-side version would drift over time.
- */
-import { useEffect, useState } from 'react';
-import { Link } from 'react-router-dom';
-import { getSetupStatus, type SetupStatus } from '../../lib/api.ts';
-import type { StepProps } from './types.ts';
-
-export function PrereqStep({ next }: StepProps) {
-  const [state, setState] = useState<
-    { kind: 'loading' } | { kind: 'ok'; status: SetupStatus } | { kind: 'error'; message: string }
-  >({ kind: 'loading' });
-  const [reloadKey, setReloadKey] = useState(0);
-
-  useEffect(() => {
-    let cancelled = false;
-    getSetupStatus()
-      .then((status) => !cancelled && setState({ kind: 'ok', status }))
-      .catch((err) => !cancelled && setState({ kind: 'error', message: err instanceof Error ? err.message : String(err) }));
-    return () => {
-      cancelled = true;
-    };
-  }, [reloadKey]);
-
-  if (state.kind === 'loading') {
-    return (
-      <>
-        <h3>Prerequisites</h3>
-        <ul className="skeleton-list" aria-busy="true">
-          <li className="skeleton skeleton-line" />
-          <li className="skeleton skeleton-line" />
-          <li className="skeleton skeleton-line" />
-        </ul>
-      </>
-    );
-  }
-
-  if (state.kind === 'error') {
-    return (
-      <>
-        <h3>Prerequisites</h3>
-        <div className="error-banner">Couldn't fetch status: <code>{state.message}</code></div>
-        <div className="actions" style={{ marginTop: '1rem' }}>
-          <button onClick={() => setReloadKey((k) => k + 1)}>Retry</button>
-        </div>
-      </>
-    );
-  }
-
-  type Check = { ok: boolean; detail: string; fix: string | null };
-  type Row = { label: string; check: Check; fixHref?: string; fixLabel?: string };
-
-  const rows: Row[] = [
-    {
-      label: 'Secrets backend',
-      check: state.status.secrets,
-      // No deep-link — this is paraclaw's own backend; if it's broken the
-      // server log is the right place to look.
-    },
-    {
-      label: 'Hub discovery',
-      check: state.status.hub,
-    },
-    {
-      label: 'Vault attached',
-      check: state.status.vaultAttached,
-      fixHref: '/groups/new',
-      fixLabel: 'Create an agent group with a vault',
-    },
-  ];
-  const blockers = rows.filter((r) => !r.check.ok);
-
-  return (
-    <>
-      <h3>Prerequisites</h3>
-      <p className="muted">parachute-agent needs these in place before we can wire a channel.</p>
-      <ul style={{ listStyle: 'none', padding: 0, marginTop: '0.75rem' }}>
-        {rows.map(({ label, check, fixHref, fixLabel }) => (
-          <li key={label} style={{ padding: '0.5rem 0', borderBottom: '1px solid var(--border)' }}>
-            <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
-              <span aria-hidden style={{ fontSize: '1.1rem' }}>{check.ok ? '✓' : '✗'}</span>
-              <strong>{label}</strong>
-              <span className="dim" style={{ marginLeft: 'auto' }}>{check.detail}</span>
-            </div>
-            {!check.ok && (check.fix || fixHref) && (
-              <div style={{ margin: '0.4rem 0 0 1.6rem', display: 'flex', gap: '0.75rem', alignItems: 'baseline' }}>
-                {check.fix && <span className="dim">{check.fix}</span>}
-                {fixHref && (
-                  <Link to={fixHref} className="muted">{fixLabel ?? 'Fix →'}</Link>
-                )}
-              </div>
-            )}
-          </li>
-        ))}
-      </ul>
-
-      <p className="dim" style={{ marginTop: '1rem' }}>
-        Channel tokens (Discord / Telegram bot tokens, API keys) live on the{' '}
-        <Link to="/secrets">/secrets</Link> page now — add them there, come back, and click <em>Re-check</em>. The wizard
-        no longer captures credentials inline.
-      </p>
-
-      <div className="actions" style={{ marginTop: '1rem' }}>
-        <button onClick={() => setReloadKey((k) => k + 1)} className="secondary">
-          Re-check
-        </button>
-        <button onClick={next} disabled={blockers.length > 0}>
-          {blockers.length > 0 ? `Resolve ${blockers.length} item${blockers.length === 1 ? '' : 's'} above` : 'Next: pick channel'}
-        </button>
-      </div>
-    </>
-  );
-}

package/web/ui/src/components/setup/TestConnectionStep.tsx

@@ -1,108 +0,0 @@
-/**
- * Step 4 — Test connection.
- *
- * Validates the bot token by hitting POST /channels/<adapter>/test and
- * captures the bot's identity (id + username) for the wire-channel step.
- * The operator pastes the token here once — paraclaw's secrets store is
- * write-only by design (values are encrypted at rest and never returned
- * to the UI), so we can't pull the token back from /api/secrets.
- *
- * Since the night/ui rebirth dropped the wizard's credential-capture
- * step, this is the first place the wizard sees the actual token bytes.
- * The operator should have already added the secret via /secrets — we
- * use this paste only to fetch the live identity, not to save anything.
- */
-import { useState } from 'react';
-import { testDiscordToken, testTelegramToken } from '../../lib/api.ts';
-import { ADAPTER_LABELS, type StepProps } from './types.ts';
-
-export function TestConnectionStep({ state, patchState, next, back }: StepProps) {
-  const adapter = state.adapter;
-  const [token, setToken] = useState('');
-  const [testing, setTesting] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [result, setResult] = useState<{ id: string; username: string } | null>(
-    state.botUserId && state.botUsername ? { id: state.botUserId, username: state.botUsername } : null,
-  );
-
-  if (!adapter) {
-    return (
-      <>
-        <h3>Test connection</h3>
-        <div className="error-banner">No channel selected — go back to step 2.</div>
-        <div className="actions" style={{ marginTop: '1rem' }}>
-          <button className="secondary" onClick={back}>Back</button>
-        </div>
-      </>
-    );
-  }
-
-  const onTest = async () => {
-    if (!token.trim()) return;
-    setTesting(true);
-    setError(null);
-    try {
-      if (adapter === 'discord') {
-        const r = await testDiscordToken(token.trim());
-        setResult({ id: r.identity.id, username: r.identity.username });
-        patchState({ botUserId: r.identity.id, botUsername: r.identity.username });
-      } else {
-        const r = await testTelegramToken(token.trim());
-        const id = String(r.identity.id);
-        setResult({ id, username: r.identity.username });
-        patchState({ botUserId: id, botUsername: r.identity.username });
-      }
-      setToken('');
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err));
-    } finally {
-      setTesting(false);
-    }
-  };
-
-  const adapterLabel = ADAPTER_LABELS[adapter];
-  const apiPath = adapter === 'discord' ? '/users/@me' : '/getMe';
-
-  return (
-    <>
-      <h3>Test connection</h3>
-      <p className="muted">
-        Confirm {adapterLabel} accepts the token by hitting <code>{apiPath}</code>. Paste the token once — parachute-agent's
-        secrets store is write-only by design, so we can't read it back from <code>/api/secrets</code>.
-      </p>
-
-      {result && (
-        <div className="empty empty-rich" style={{ marginTop: '0.5rem' }}>
-          <p className="empty-headline" style={{ margin: 0 }}>
-            Bot identified: <code>@{result.username}</code> <span className="dim">(id <code>{result.id}</code>)</span>
-          </p>
-          <p className="muted" style={{ marginTop: '0.4rem' }}>
-            You can re-test below, or move on.
-          </p>
-        </div>
-      )}
-
-      <div className="row" style={{ marginTop: '0.75rem' }}>
-        <label htmlFor="recheckToken">Bot token</label>
-        <input
-          id="recheckToken"
-          type="password"
-          autoComplete="off"
-          value={token}
-          onChange={(e) => setToken(e.target.value)}
-          placeholder="paste again to re-test"
-        />
-      </div>
-
-      {error && <div className="error-banner">{error}</div>}
-
-      <div className="actions" style={{ marginTop: '1rem' }}>
-        <button className="secondary" onClick={back}>Back</button>
-        <button className="secondary" onClick={onTest} disabled={!token.trim() || testing}>
-          {testing ? 'Testing…' : 'Test'}
-        </button>
-        <button onClick={next} disabled={!result}>Next: agent group</button>
-      </div>
-    </>
-  );
-}

package/web/ui/src/components/setup/TestMessageStep.tsx

@@ -1,104 +0,0 @@
-/**
- * Step 8 — Test message round-trip.
- *
- * Polls GET /api/groups/:folder every 3 seconds and advances when
- * status.lastMessageInAt > lastInboundBaseline. The baseline was captured
- * at wire-channel time precisely so a stale prior inbound (from another
- * agent group on the same DB) doesn't short-circuit the wait.
- *
- * Operator copy is verbatim from issue #27 §user journey: "DM your bot at
- * @<bot-name> now." Surfacing the exact bot username (captured by
- * test-connection) is the trick that converts a generic "DM your bot"
- * banner into something the operator can act on without context-switching
- * to Discord's user search.
- */
-import { useEffect, useState } from 'react';
-import { getGroup, type AgentGroupView } from '../../lib/api.ts';
-import { ADAPTER_LABELS, type StepProps } from './types.ts';
-
-const POLL_MS = 3000;
-
-export function TestMessageStep({ state, next, back }: StepProps) {
-  const [group, setGroup] = useState<AgentGroupView | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [received, setReceived] = useState(false);
-
-  useEffect(() => {
-    if (!state.agentGroupFolder) return;
-    let cancelled = false;
-    const poll = () => {
-      if (!state.agentGroupFolder) return;
-      getGroup(state.agentGroupFolder)
-        .then((g) => {
-          if (cancelled) return;
-          setGroup(g);
-          const ts = g.status?.lastMessageInAt ?? null;
-          if (ts && (!state.lastInboundBaseline || ts > state.lastInboundBaseline)) {
-            setReceived(true);
-          }
-        })
-        .catch((err) => !cancelled && setError(err instanceof Error ? err.message : String(err)));
-    };
-    poll();
-    const t = setInterval(poll, POLL_MS);
-    return () => {
-      cancelled = true;
-      clearInterval(t);
-    };
-  }, [state.agentGroupFolder, state.lastInboundBaseline]);
-
-  return (
-    <>
-      <h3>Test message</h3>
-      <p>
-        Open {state.adapter ? ADAPTER_LABELS[state.adapter] : 'your chat app'} and DM your bot. The wizard advances
-        as soon as parachute-agent records the inbound.
-      </p>
-      <p className="muted">
-        Bot: <code>@{state.botUsername ?? '(unknown — re-run test connection)'}</code>
-        {state.adapter === 'discord' && state.botUserId && (
-          <>
-            {' · '}user id <code>{state.botUserId}</code>
-          </>
-        )}
-        {state.adapter === 'telegram' && state.operatorUserId && (
-          <>
-            {' · '}wired to your user id <code>{state.operatorUserId}</code>
-          </>
-        )}
-      </p>
-
-      <div className="empty empty-rich" style={{ marginTop: '0.75rem' }}>
-        {received ? (
-          <>
-            <p className="empty-headline" style={{ margin: 0 }}>✓ Inbound received.</p>
-            <p className="muted" style={{ marginTop: '0.4rem' }}>
-              Last inbound at <code>{group?.status?.lastMessageInAt}</code>. The agent should be replying — check Discord.
-            </p>
-          </>
-        ) : (
-          <>
-            <p className="empty-headline" style={{ margin: 0 }}>Waiting for first inbound DM…</p>
-            <p className="muted" style={{ marginTop: '0.4rem' }}>
-              Polling <code>{state.agentGroupFolder}</code> every 3s.{' '}
-              {state.lastInboundBaseline ? (
-                <>Baseline: <code>{state.lastInboundBaseline}</code> (we'll advance on any newer inbound).</>
-              ) : (
-                <>No prior inbound recorded — any DM will trigger advance.</>
-              )}
-            </p>
-          </>
-        )}
-      </div>
-
-      {error && <div className="error-banner">{error}</div>}
-
-      <div className="actions" style={{ marginTop: '1rem' }}>
-        <button className="secondary" onClick={back}>Back</button>
-        <button onClick={next} disabled={!received}>
-          {received ? 'Next: done' : 'Waiting for inbound…'}
-        </button>
-      </div>
-    </>
-  );
-}

package/web/ui/src/components/setup/WireChannelStep.tsx

@@ -1,166 +0,0 @@
-/**
- * Step 7 — Wire channel.
- *
- * POST /api/groups/:folder/wire-channel with the right id for the chosen
- * adapter:
- *   - discord  : `botUserId` is the BOT's snowflake (DMs land on @me).
- *   - telegram : `botUserId` carries the OPERATOR's user id (DMs are
- *     chat-routed; chat_id == sender user_id in DMs).
- *
- * The server inserts messaging_groups + messaging_group_agents rows so
- * the first inbound DM doesn't get silently dropped by
- * channel-approval.ts:73-77 (see PR A body).
- *
- * Idempotent: re-clicking returns the same IDs with
- * `created.{messagingGroup,wiring}=false`. Safe to retry.
- *
- * Before advancing we capture `lastInboundBaseline` from the group's
- * status — the test-message step polls /api/groups/:folder and advances
- * when status.lastMessageInAt > this baseline. Without a baseline a
- * stale prior inbound would short-circuit the round-trip wait and lie
- * to the operator.
- */
-import { useEffect, useState } from 'react';
-import { getGroup, wireChannelToGroup, type WireChannelResult } from '../../lib/api.ts';
-import { ADAPTER_LABELS, type StepProps } from './types.ts';
-
-export function WireChannelStep({ state, patchState, next, back }: StepProps) {
-  const adapter = state.adapter;
-  const [submitting, setSubmitting] = useState(false);
-  const [result, setResult] = useState<WireChannelResult | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [missingPrereq, setMissingPrereq] = useState<string | null>(null);
-
-  // Per-channel: which captured id do we use for wiring?
-  const wireId =
-    adapter === 'telegram' ? state.operatorUserId : adapter === 'discord' ? state.botUserId : null;
-
-  // Telegram needs the OPERATOR's user id (DMs are chat-routed). Captured
-  // inline here since the rebirth dropped the credentials step that used
-  // to ask for it. Discord doesn't need this — its botUserId comes from
-  // test-connection's getMe call.
-  const [operatorIdInput, setOperatorIdInput] = useState(state.operatorUserId ?? '');
-
-  useEffect(() => {
-    if (!adapter) {
-      setMissingPrereq('channel (re-run step 2)');
-      return;
-    }
-    const missing: string[] = [];
-    if (adapter === 'discord' && !state.botUserId) missing.push('bot user id (re-run test-connection)');
-    if (adapter === 'telegram' && !state.operatorUserId) missing.push('your Telegram user id (paste below)');
-    if (!state.agentGroupFolder) missing.push('agent group (re-run step 5)');
-    setMissingPrereq(missing.length > 0 ? missing.join(', ') : null);
-  }, [adapter, state.botUserId, state.operatorUserId, state.agentGroupFolder]);
-
-  if (!adapter) {
-    return (
-      <>
-        <h3>Wire channel</h3>
-        <div className="error-banner">No channel selected — go back to step 2.</div>
-        <div className="actions" style={{ marginTop: '1rem' }}>
-          <button className="secondary" onClick={back}>Back</button>
-        </div>
-      </>
-    );
-  }
-
-  const onWire = async () => {
-    if (!state.agentGroupFolder || !wireId) return;
-    setSubmitting(true);
-    setError(null);
-    try {
-      const r = await wireChannelToGroup(state.agentGroupFolder, {
-        channel: adapter,
-        // The bot's identity from test-connection's getMe; for both
-        // adapters this is the bot's user/application id and forms the
-        // bot dimension of the v2 platform_id.
-        botId: state.botUserId ?? '',
-        botUserId: wireId,
-        operatorUserId: state.operatorUserId ?? undefined,
-        displayName: state.agentGroupName ? `${state.agentGroupName} DM` : undefined,
-      });
-      setResult(r);
-      const grp = await getGroup(state.agentGroupFolder);
-      patchState({ lastInboundBaseline: grp.status?.lastMessageInAt ?? null });
-    } catch (err) {
-      setError(err instanceof Error ? err.message : String(err));
-    } finally {
-      setSubmitting(false);
-    }
-  };
-
-  const adapterLabel = ADAPTER_LABELS[adapter];
-  const previewPlatformId =
-    adapter === 'discord' ? `discord:@me:${wireId ?? '(no bot id)'}` : `telegram:${wireId ?? '(no user id)'}`;
-
-  return (
-    <>
-      <h3>
-        Wire {adapterLabel} DM to <code>{state.agentGroupName ?? state.agentGroupFolder ?? '(no group)'}</code>
-      </h3>
-      <p className="muted">
-        We synthesize the DM platform id <code>{previewPlatformId}</code> and insert the messaging_groups +
-        messaging_group_agents rows. After this, the {adapterLabel === 'Telegram' ? "operator's first DM" : "bot's first DM"}{' '}
-        lands in your group instead of being silently dropped by the unwired-channel guard.
-      </p>
-
-      {adapter === 'telegram' && !state.operatorUserId && (
-        <div className="row" style={{ marginTop: '0.75rem' }}>
-          <label htmlFor="operatorUserId">Your Telegram user id</label>
-          <input
-            id="operatorUserId"
-            type="text"
-            inputMode="numeric"
-            pattern="[0-9]+"
-            value={operatorIdInput}
-            onChange={(e) => setOperatorIdInput(e.target.value)}
-            placeholder="123456789  (from @userinfobot)"
-          />
-          <p className="dim" style={{ marginTop: '0.25rem', fontSize: '0.8rem' }}>
-            Telegram routes DMs by chat id (= your user id). Get yours by DMing{' '}
-            <a href="https://t.me/userinfobot" target="_blank" rel="noreferrer">@userinfobot</a>.
-          </p>
-          <button
-            type="button"
-            className="secondary"
-            disabled={!/^[0-9]+$/.test(operatorIdInput.trim())}
-            onClick={() => patchState({ operatorUserId: operatorIdInput.trim() })}
-            style={{ marginTop: '0.5rem' }}
-          >
-            Save user id
-          </button>
-        </div>
-      )}
-
-      {missingPrereq && (
-        <div className="error-banner">
-          Missing prerequisites: {missingPrereq}.
-        </div>
-      )}
-
-      {result && (
-        <div className="empty empty-rich" style={{ marginTop: '0.5rem' }}>
-          <p className="empty-headline" style={{ margin: 0 }}>
-            {result.created.wiring ? 'Wired.' : 'Already wired — kept existing rows.'}
-          </p>
-          <p className="muted" style={{ marginTop: '0.4rem', fontSize: '0.85rem' }}>
-            messaging_group_id: <code>{result.messagingGroupId}</code><br />
-            messaging_group_agent_id: <code>{result.messagingGroupAgentId}</code><br />
-            platform_id: <code>{result.platformId}</code>
-          </p>
-        </div>
-      )}
-
-      {error && <div className="error-banner">{error}</div>}
-
-      <div className="actions" style={{ marginTop: '1rem' }}>
-        <button className="secondary" onClick={back}>Back</button>
-        <button onClick={onWire} disabled={submitting || !!missingPrereq}>
-          {submitting ? 'Wiring…' : result ? 'Re-wire' : 'Wire DM channel'}
-        </button>
-        <button onClick={next} disabled={!result}>Next: test message</button>
-      </div>
-    </>
-  );
-}

package/web/ui/src/components/setup/types.ts

@@ -1,105 +0,0 @@
-/**
- * Shared types for the setup wizard step components.
- *
- * The wizard's state is the union of:
- *   - what we've collected from the operator (agent group folder, bot user
- *     id from /channels/discord/test, messaging_group_id from wire-channel)
- *   - which steps have been confirmed done (so a refresh resumes mid-flow
- *     rather than restarting at step 1)
- *
- * We persist `SetupState` to localStorage under SETUP_STORAGE_KEY so a tab
- * close mid-install survives. The state is intentionally NOT durable on the
- * server — the server's state is the canonical filesystem and DB, and the
- * wizard re-derives readiness from /api/setup/status on every load.
- * localStorage is purely a UX aid for the in-flight session.
- *
- * Tokens are NEVER persisted here. Credential capture moved out of the
- * wizard to the /secrets page (night/ui rebirth) — the wizard now reads
- * names of saved secrets via /api/setup/status to decide whether to
- * prompt the operator to add one.
- */
-export type SetupStepKey =
-  | 'prereqs'
-  | 'channel-pick'
-  | 'install'
-  | 'test-connection'
-  | 'agent-group'
-  | 'wire-channel'
-  | 'test-message'
-  | 'done';
-
-export const SETUP_STEPS: { key: SetupStepKey; label: string }[] = [
-  { key: 'prereqs', label: '1. Prerequisites' },
-  { key: 'channel-pick', label: '2. Pick channel' },
-  { key: 'install', label: '3. Install adapter' },
-  { key: 'test-connection', label: '4. Test connection' },
-  { key: 'agent-group', label: '5. Agent group' },
-  { key: 'wire-channel', label: '6. Wire channel' },
-  { key: 'test-message', label: '7. Test message' },
-  { key: 'done', label: '8. Done' },
-];
-
-export type ChannelAdapter = 'discord' | 'telegram';
-
-export interface SetupState {
-  /** Latest step the wizard has reached (resume point on reload). */
-  furthestStep: SetupStepKey;
-  /** Active step the user is currently viewing (may differ if they backed up). */
-  currentStep: SetupStepKey;
-  /** Channel adapter selected (Phase 1: discord OR telegram). */
-  adapter: ChannelAdapter | null;
-  /** Bot identity captured from POST /channels/<adapter>/test.
-   *  - discord : the bot's snowflake (used directly to synthesize discord:@me:<id>)
-   *  - telegram: the bot's user id (used for the "DM @<botUsername>" copy only;
-   *              telegram wiring uses operatorUserId, not this) */
-  botUserId: string | null;
-  /** Username of the bot — used in 'DM @<bot> now' copy on test-message step. */
-  botUsername: string | null;
-  /** Telegram-only: the OPERATOR's Telegram user id (from @userinfobot). This
-   *  is what wire-channel uses to synthesize telegram:<id> — DMs are
-   *  chat-routed in Telegram so per-operator wiring is required. Captured in
-   *  the credentials step alongside the bot token. */
-  operatorUserId: string | null;
-  /** Folder slug of the agent group created in step 6 (or selected if pre-existing). */
-  agentGroupFolder: string | null;
-  /** Display name of that agent group — for confirmation copy. */
-  agentGroupName: string | null;
-  /** ISO timestamp of the most recent inbound message at wire-channel time.
-   * test-message step polls /api/groups/:folder and advances when
-   * status.lastMessageInAt > this baseline. */
-  lastInboundBaseline: string | null;
-  /** Background install task we're polling, if any. */
-  installTaskId: string | null;
-}
-
-export const DEFAULT_SETUP_STATE: SetupState = {
-  furthestStep: 'prereqs',
-  currentStep: 'prereqs',
-  adapter: null,
-  botUserId: null,
-  botUsername: null,
-  operatorUserId: null,
-  agentGroupFolder: null,
-  agentGroupName: null,
-  lastInboundBaseline: null,
-  installTaskId: null,
-};
-
-export const ADAPTER_LABELS: Record<ChannelAdapter, string> = {
-  discord: 'Discord',
-  telegram: 'Telegram',
-};
-
-export const SETUP_STORAGE_KEY = 'parachute-agent.setupWizard.v2';
-
-export interface StepProps {
-  state: SetupState;
-  /** Patch state and persist. Caller should treat this as "save what I learned." */
-  patchState: (patch: Partial<SetupState>) => void;
-  /** Advance to the next step (stamping furthestStep). */
-  next: () => void;
-  /** Go back one step (no state mutation). */
-  back: () => void;
-  /** Jump directly to a step by key. */
-  goto: (step: SetupStepKey) => void;
-}