@openparachute/agent 0.1.0

package/web/ui/src/components/ScopeGrants.tsx

@@ -0,0 +1,74 @@
+import type { VaultScope } from "../lib/api.ts";
+
+const READ_TOOLS = ["query-notes", "list-tags", "find-path", "vault-info"] as const;
+const WRITE_TOOLS = ["create-note", "update-note", "delete-note", "update-tag", "delete-tag"] as const;
+
+export const SCOPE_OPTIONS: { value: VaultScope; label: string }[] = [
+  { value: "vault:read", label: "vault:read — query, can't modify" },
+  { value: "vault:write", label: "vault:write — capture and update notes" },
+  { value: "vault:admin", label: "vault:admin — full access (use sparingly)" },
+];
+
+export function scopeGrants(scope: VaultScope): {
+  summary: string;
+  granted: readonly string[];
+  withheld: readonly string[];
+  adminNote?: string;
+} {
+  if (scope === "vault:read") {
+    return {
+      summary: "Read-only access. The agent can query the vault but cannot create, modify, or delete anything.",
+      granted: READ_TOOLS,
+      withheld: WRITE_TOOLS,
+    };
+  }
+  if (scope === "vault:write") {
+    return {
+      summary: "Read + write. The agent can capture and update notes and tags, but cannot manage vault config or tokens.",
+      granted: [...READ_TOOLS, ...WRITE_TOOLS],
+      withheld: [],
+    };
+  }
+  return {
+    summary: "Full access including vault config (/.parachute/config*) and token management. Use sparingly.",
+    granted: [...READ_TOOLS, ...WRITE_TOOLS],
+    withheld: [],
+    adminNote: "Admin tokens can read and write any path including vault config — only grant when the agent genuinely needs it.",
+  };
+}
+
+export function ScopeGrants({ scope }: { scope: VaultScope }) {
+  const grants = scopeGrants(scope);
+  return (
+    <div className="scope-grants">
+      <p className="scope-grants-summary">{grants.summary}</p>
+      <div className="scope-grants-tools">
+        <div>
+          <span className="scope-grants-label">Allows</span>
+          <ul>
+            {grants.granted.map((t) => (
+              <li key={t}>
+                <code>{t}</code>
+              </li>
+            ))}
+          </ul>
+        </div>
+        {grants.withheld.length > 0 && (
+          <div>
+            <span className="scope-grants-label">Blocks</span>
+            <ul>
+              {grants.withheld.map((t) => (
+                <li key={t} className="dim">
+                  <code>{t}</code>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </div>
+      {grants.adminNote && (
+        <p className="scope-grants-warn">{grants.adminNote}</p>
+      )}
+    </div>
+  );
+}

package/web/ui/src/components/StatusDot.tsx

@@ -0,0 +1,43 @@
+import type { GroupStatus } from "../lib/api.ts";
+
+export function StatusDot({ status }: { status: GroupStatus | null }) {
+  if (!status) {
+    return <span className="status-dot status-dot-unknown" title="status unavailable" aria-label="status unavailable" />;
+  }
+  if (status.containerRunning) {
+    const lastActive = status.lastHeartbeatAt
+      ? `last heartbeat ${formatRelative(status.lastHeartbeatAt)}`
+      : "alive";
+    return (
+      <span
+        className="status-dot status-dot-alive"
+        title={`${status.activeSessionCount} session${status.activeSessionCount === 1 ? "" : "s"} alive — ${lastActive}`}
+        aria-label="alive"
+      />
+    );
+  }
+  const idleTitle = status.lastHeartbeatAt
+    ? `idle — last heartbeat ${formatRelative(status.lastHeartbeatAt)}`
+    : "idle — never started";
+  return (
+    <span
+      className="status-dot status-dot-idle"
+      title={idleTitle}
+      aria-label="idle"
+    />
+  );
+}
+
+export function formatRelative(iso: string, nowMs: number = Date.now()): string {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return iso;
+  const diffSec = Math.max(0, Math.floor((nowMs - t) / 1000));
+  if (diffSec < 5) return "just now";
+  if (diffSec < 60) return `${diffSec}s ago`;
+  const diffMin = Math.floor(diffSec / 60);
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.floor(diffMin / 60);
+  if (diffHr < 24) return `${diffHr}h ago`;
+  const diffDay = Math.floor(diffHr / 24);
+  return `${diffDay}d ago`;
+}

package/web/ui/src/components/VaultPicker.tsx

@@ -0,0 +1,127 @@
+import { useEffect, useRef, useState } from 'react';
+import { listVaults, type VaultListing } from '../lib/api.ts';
+
+interface VaultPickerProps {
+  value: string;
+  onChange: (next: string) => void;
+  disabled?: boolean;
+  inputId?: string;
+  /** Fires with the picked vault's display name (or null when "Other" is selected / no match). */
+  onPickedName?: (name: string | null) => void;
+}
+
+const OTHER_SENTINEL = '__other__';
+
+export function VaultPicker({ value, onChange, disabled, inputId, onPickedName }: VaultPickerProps) {
+  const [vaults, setVaults] = useState<VaultListing[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [useCustomUrl, setUseCustomUrl] = useState(false);
+  const initializedRef = useRef(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    listVaults()
+      .then((vs) => {
+        if (cancelled) return;
+        setVaults(vs);
+        if (initializedRef.current) return;
+        initializedRef.current = true;
+        if (vs.length === 0) {
+          setUseCustomUrl(true);
+          onPickedName?.(null);
+          return;
+        }
+        const match = vs.find((v) => v.url === value);
+        if (!match) onChange(vs[0].url);
+      })
+      .catch((e) => {
+        if (cancelled) return;
+        setLoadError(e instanceof Error ? e.message : String(e));
+        setUseCustomUrl(true);
+        initializedRef.current = true;
+        onPickedName?.(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Notify parent when the picked-name changes (selection or value flip).
+  useEffect(() => {
+    if (!onPickedName) return;
+    if (useCustomUrl) {
+      onPickedName(null);
+      return;
+    }
+    if (!vaults) return;
+    const match = vaults.find((v) => v.url === value);
+    onPickedName(match ? match.name : null);
+  }, [vaults, value, useCustomUrl, onPickedName]);
+
+  const trimmed = value.replace(/\/+$/, '');
+  const reachLine = (
+    <p className="dim">
+      The agent will reach this at <code>{trimmed || '…'}/mcp</code>.
+    </p>
+  );
+
+  if (vaults === null && !loadError) {
+    return <p className="dim">Loading vaults…</p>;
+  }
+
+  const customInput = (
+    <input
+      id={vaults && vaults.length > 0 ? undefined : inputId}
+      type="text"
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      disabled={disabled}
+      placeholder="https://parachute.example/vault/default"
+      style={vaults && vaults.length > 0 ? { marginTop: '0.5rem' } : undefined}
+    />
+  );
+
+  if (!vaults || vaults.length === 0) {
+    return (
+      <>
+        {customInput}
+        {reachLine}
+        {loadError && <p className="dim">(could not list registered vaults: {loadError})</p>}
+      </>
+    );
+  }
+
+  return (
+    <>
+      <select
+        id={inputId}
+        value={useCustomUrl ? OTHER_SENTINEL : value}
+        onChange={(e) => {
+          if (e.target.value === OTHER_SENTINEL) {
+            setUseCustomUrl(true);
+          } else {
+            setUseCustomUrl(false);
+            onChange(e.target.value);
+          }
+        }}
+        disabled={disabled}
+      >
+        {vaults.map((v) => (
+          <option key={v.url} value={v.url}>
+            {v.name} — {v.url}
+          </option>
+        ))}
+        <option value={OTHER_SENTINEL}>Other (paste URL)…</option>
+      </select>
+      {useCustomUrl && customInput}
+      {reachLine}
+    </>
+  );
+}
+
+export function vaultLabelForUrl(vaults: VaultListing[] | null, url: string): string | null {
+  if (!vaults) return null;
+  const match = vaults.find((v) => v.url === url.replace(/\/+$/, ''));
+  return match ? match.name : null;
+}

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

@@ -0,0 +1,178 @@
+/**
+ * Step 4 — Adapter install.
+ *
+ * Triggers POST /setup/install-channel with the chosen adapter, then polls
+ * GET /tasks/:id every second until the task lands in a terminal state.
+ * Renders the per-step checklist live as the orchestrator advances.
+ *
+ * Per-channel step counts: discord = 5, telegram = 6 (extra
+ * register-setup-step that wires the pair-telegram setup script).
+ *
+ * Idempotency: if the chosen adapter is already installed (status check
+ * before dispatch shows channels.<adapter>.installed=true), we skip
+ * kicking off the task and let the user advance immediately. The
+ * dirty-tree 409 surfaces as an inline error with the offending file
+ * list — operator commits/stashes and re-clicks.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  getSetupStatus,
+  getTask,
+  startInstallChannel,
+  type TaskRecord,
+  type SetupStatus,
+} from '../../lib/api.ts';
+import { ADAPTER_LABELS, type StepProps } from './types.ts';
+
+const POLL_MS = 1000;
+
+export function AdapterInstallStep({ state, patchState, next, back }: StepProps) {
+  const [status, setStatus] = useState<SetupStatus | null>(null);
+  const [task, setTask] = useState<TaskRecord | null>(null);
+  const [starting, setStarting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [dirtyFiles, setDirtyFiles] = useState<string[] | null>(null);
+  const pollTimer = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const adapter = state.adapter;
+
+  useEffect(() => {
+    getSetupStatus()
+      .then(setStatus)
+      .catch((err) => setError(err instanceof Error ? err.message : String(err)));
+  }, []);
+
+  const startPolling = useCallback((taskId: string) => {
+    if (pollTimer.current) clearInterval(pollTimer.current);
+    pollTimer.current = setInterval(() => {
+      getTask(taskId)
+        .then((t) => {
+          setTask(t);
+          if (t.status === 'completed' || t.status === 'failed') {
+            if (pollTimer.current) clearInterval(pollTimer.current);
+            pollTimer.current = null;
+          }
+        })
+        .catch((err) => {
+          setError(err instanceof Error ? err.message : String(err));
+          if (pollTimer.current) clearInterval(pollTimer.current);
+          pollTimer.current = null;
+        });
+    }, POLL_MS);
+  }, []);
+
+  useEffect(() => {
+    if (state.installTaskId && !task) {
+      getTask(state.installTaskId).then(setTask).catch(() => {
+        patchState({ installTaskId: null });
+      });
+      startPolling(state.installTaskId);
+    }
+    return () => {
+      if (pollTimer.current) clearInterval(pollTimer.current);
+    };
+  }, [state.installTaskId, task, startPolling, patchState]);
+
+  if (!adapter) {
+    return (
+      <>
+        <h3>Install adapter</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 onStart = async () => {
+    setStarting(true);
+    setError(null);
+    setDirtyFiles(null);
+    try {
+      const res = await startInstallChannel(adapter);
+      patchState({ installTaskId: res.taskId });
+      startPolling(res.taskId);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('uncommitted changes')) {
+        setDirtyFiles([msg]);
+      }
+      setError(msg);
+    } finally {
+      setStarting(false);
+    }
+  };
+
+  const installed = status?.channels[adapter]?.installed ?? false;
+  const taskTerminal = task?.status === 'completed' || task?.status === 'failed';
+  const adapterLabel = ADAPTER_LABELS[adapter];
+
+  return (
+    <>
+      <h3>Install {adapterLabel} adapter</h3>
+      {installed && !task && (
+        <div className="empty empty-rich" style={{ marginTop: '0.5rem' }}>
+          <p className="empty-headline" style={{ margin: 0 }}>{adapterLabel} adapter is already installed.</p>
+          <p className="muted" style={{ marginTop: '0.4rem' }}>
+            Move on to test the connection.
+          </p>
+        </div>
+      )}
+
+      {!installed && !task && (
+        <p className="muted">
+          {adapter === 'discord' ? (
+            <>
+              We'll fetch the adapter from the <code>channels</code> branch, copy it into <code>src/channels/discord.ts</code>,
+              register the import, run <code>pnpm install @chat-adapter/discord</code>, and rebuild. Takes ~1–3 min depending on cache.
+            </>
+          ) : (
+            <>
+              We'll fetch the adapter from the <code>channels</code> branch, copy 6 files into <code>src/channels/</code> + <code>setup/</code>,
+              register the import + setup step, run <code>pnpm install @chat-adapter/telegram</code>, and rebuild.
+              Takes ~1–3 min depending on cache.
+            </>
+          )}
+        </p>
+      )}
+
+      {task && (
+        <ol style={{ listStyle: 'none', padding: 0, marginTop: '0.5rem' }}>
+          {task.steps.map((s) => (
+            <li key={s.name} style={{ padding: '0.4rem 0', display: 'flex', gap: '0.5rem' }}>
+              <span aria-hidden style={{ width: '1.2rem' }}>
+                {s.status === 'completed' ? '✓' : s.status === 'running' ? '…' : s.status === 'failed' ? '✗' : '○'}
+              </span>
+              <code>{s.name}</code>
+              {s.error && <span className="dim" style={{ color: 'var(--error)' }}>— {s.error}</span>}
+            </li>
+          ))}
+        </ol>
+      )}
+
+      {error && (
+        <div className="error-banner" style={{ marginTop: '0.75rem' }}>
+          {error}
+          {dirtyFiles && (
+            <p style={{ marginTop: '0.4rem' }}>
+              Commit or stash the listed files, then click <strong>Retry</strong>.
+            </p>
+          )}
+        </div>
+      )}
+
+      <div className="actions" style={{ marginTop: '1rem' }}>
+        <button className="secondary" onClick={back}>Back</button>
+        {!installed && (
+          <button onClick={onStart} disabled={starting || (!!task && !taskTerminal)}>
+            {starting ? 'Starting…' : task && !taskTerminal ? 'Installing…' : task?.status === 'failed' ? 'Retry install' : 'Start install'}
+          </button>
+        )}
+        <button onClick={next} disabled={!installed && task?.status !== 'completed'}>
+          Next: test connection
+        </button>
+      </div>
+    </>
+  );
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Step 6 — Agent group.
+ *
+ * Two paths:
+ *
+ *   (a) Pick an existing group. If the operator already has groups, list
+ *       them and let them select one — the wire-channel step works the
+ *       same way regardless of how the group was created.
+ *
+ *   (b) Create a new group inline. Vault attach is offered on the group
+ *       detail page after setup, not here, to keep the wizard fast.
+ *
+ * The picker UI is shared with /channels/new — both are thin wrappers
+ * around <AgentGroupPicker />. Once a group is picked / created, we
+ * stamp `agentGroupFolder` and `agentGroupName` on the wizard state and
+ * advance.
+ */
+import { AgentGroupPicker, type PickedGroup } from '../AgentGroupPicker.tsx';
+import type { StepProps } from './types.ts';
+
+export function AgentGroupStep({ patchState, next, back }: StepProps) {
+  const onPicked = (g: PickedGroup) => {
+    patchState({ agentGroupFolder: g.folder, agentGroupName: g.name });
+    next();
+  };
+
+  return (
+    <>
+      <h3>Agent group</h3>
+      <p className="muted">
+        The agent group is the entity your bot represents. Pick an existing one or create a new one.
+      </p>
+
+      <AgentGroupPicker onPicked={onPicked} />
+
+      <div className="actions" style={{ marginTop: '1rem' }}>
+        <button className="secondary" onClick={back}>
+          Back
+        </button>
+      </div>
+    </>
+  );
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Step 2 — Channel pick.
+ *
+ * Phase 1 ships Discord + Telegram. Slack/WhatsApp/Teams render disabled
+ * with a "coming soon" badge so the operator sees the trajectory — when
+ * those phases land, the UI shape doesn't change, only the disabled flag
+ * flips.
+ */
+import { useEffect } from 'react';
+import type { ChannelAdapter, StepProps } from './types.ts';
+
+interface AdapterCard {
+  key: ChannelAdapter | 'slack' | 'whatsapp';
+  name: string;
+  blurb: string;
+  available: boolean;
+}
+
+const ADAPTERS: AdapterCard[] = [
+  { key: 'telegram', name: 'Telegram', blurb: 'Easiest first run — BotFather + @userinfobot, ~1 minute.', available: true },
+  { key: 'discord', name: 'Discord', blurb: 'DM your bot or @-mention it in a server.', available: true },
+  { key: 'slack', name: 'Slack', blurb: 'Workspace bot.', available: false },
+  { key: 'whatsapp', name: 'WhatsApp', blurb: 'Cloud API.', available: false },
+];
+
+export function ChannelPickStep({ state, patchState, next, back }: StepProps) {
+  // If the user re-enters this step without an adapter set, default to telegram
+  // (the lower-friction onboarding path).
+  useEffect(() => {
+    if (!state.adapter) patchState({ adapter: 'telegram' });
+  }, [state.adapter, patchState]);
+
+  return (
+    <>
+      <h3>Pick a channel</h3>
+      <p className="muted">Telegram is the lowest-friction setup; Discord is the production target. Slack + WhatsApp arrive in Phase 3.</p>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))', gap: '0.75rem', marginTop: '0.75rem' }}>
+        {ADAPTERS.map((a) => {
+          const selected = state.adapter === a.key;
+          return (
+            <button
+              key={a.key}
+              type="button"
+              disabled={!a.available}
+              onClick={() => a.available && patchState({ adapter: a.key as ChannelAdapter })}
+              className="secondary"
+              style={{
+                textAlign: 'left',
+                padding: '1rem',
+                border: selected ? '2px solid var(--accent)' : '1px solid var(--border)',
+                background: selected ? 'var(--accent-soft)' : 'white',
+                opacity: a.available ? 1 : 0.5,
+                cursor: a.available ? 'pointer' : 'not-allowed',
+              }}
+            >
+              <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+                <strong>{a.name}</strong>
+                {!a.available && <span className="tag muted">coming soon</span>}
+              </div>
+              <p className="dim" style={{ margin: '0.4rem 0 0', fontSize: '0.85rem' }}>{a.blurb}</p>
+            </button>
+          );
+        })}
+      </div>
+
+      <div className="actions" style={{ marginTop: '1rem' }}>
+        <button className="secondary" onClick={back}>Back</button>
+        <button onClick={next} disabled={state.adapter !== 'discord' && state.adapter !== 'telegram'}>
+          Next: install adapter
+        </button>
+      </div>
+    </>
+  );
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Step 9 — Done.
+ *
+ * Terminal state. Links to the agent group's detail page so the operator
+ * can see the live session and inspect status. Does NOT clear the
+ * localStorage state — re-opening /setup just lands here, which is the
+ * desired behavior (you can revisit any step via the indicator).
+ */
+import { Link } from 'react-router-dom';
+import { ADAPTER_LABELS, SETUP_STORAGE_KEY, type StepProps } from './types.ts';
+
+export function DoneStep({ state }: StepProps) {
+  const folder = state.agentGroupFolder;
+  const channel = state.adapter ? ADAPTER_LABELS[state.adapter] : 'your channel';
+  return (
+    <>
+      <h3>Done.</h3>
+      <p>
+        <code>{state.agentGroupName ?? folder}</code> is wired to {channel} and your first inbound has round-tripped.
+      </p>
+
+      <div className="actions" style={{ marginTop: '1rem' }}>
+        {folder && (
+          <Link to={`/groups/${encodeURIComponent(folder)}`}>
+            <button>Open group</button>
+          </Link>
+        )}
+        <Link to="/">
+          <button className="secondary">All groups</button>
+        </Link>
+        <button
+          className="secondary"
+          onClick={() => {
+            if (
+              confirm(
+                'Clear local wizard state? Returning to /agent/setup later will restart from step 1 (your installed adapters / agent groups / wired channels are unaffected).',
+              )
+            ) {
+              localStorage.removeItem(SETUP_STORAGE_KEY);
+              window.location.href = '/';
+            }
+          }}
+        >
+          Clear wizard state
+        </button>
+      </div>
+    </>
+  );
+}