@graph8/sdk 0.362.0 → 0.370.0

package/blocks/_foundation/server/local-key.ts

@@ -0,0 +1,70 @@
+/**
+ * The graph8 API key for local preview, kept on the SERVER: the Connect graph8 screen posts a pasted key to
+ * `app/api/g8-connect/route.ts`, which validates it and stores it here, in `.g8/local-key` at the project root
+ * (file mode 0600, folder 0700, with its own `.gitignore` so it is never committed). The browser never holds it.
+ *
+ *   resolveApiKey(): G8_API_KEY from the environment wins; otherwise, outside production, the stored key.
+ *
+ * Node only (reads the file system); the Next route that imports it runs on the Node runtime (the default).
+ * In a production build the file is never read: set G8_API_KEY in the deployment's environment.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/** Where the key lives, relative to the project root (the directory `next dev` runs in). */
+export const LOCAL_KEY_FILE = path.join(".g8", "local-key");
+
+export type KeySource = "env" | "file";
+
+const isProduction = (): boolean => process.env.NODE_ENV === "production";
+
+function keyPath(root: string = process.cwd()): string {
+  return path.join(root, LOCAL_KEY_FILE);
+}
+
+/** The stored key, or undefined (none, unreadable, or a production build). */
+export async function readLocalKey(root?: string): Promise<string | undefined> {
+  if (isProduction()) return undefined;
+  try {
+    const key = (await fs.readFile(keyPath(root), "utf8")).trim();
+    return key || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The key the proxy uses, and where it came from. The environment always wins. */
+export async function currentKey(root?: string): Promise<{ key: string; source: KeySource } | null> {
+  const env = process.env.G8_API_KEY?.trim();
+  if (env) return { key: env, source: "env" };
+  const stored = await readLocalKey(root);
+  return stored ? { key: stored, source: "file" } : null;
+}
+
+/** For `createG8Proxy({ apiKey: resolveApiKey })`. */
+export async function resolveApiKey(): Promise<string | undefined> {
+  return (await currentKey())?.key;
+}
+
+/** Store a key (validated by the caller): 0700 folder, 0600 file, and a `.gitignore` that ignores the folder. */
+export async function writeLocalKey(key: string, root?: string): Promise<void> {
+  const file = keyPath(root);
+  const dir = path.dirname(file);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  await fs.writeFile(path.join(dir, ".gitignore"), "# Written by the graph8 Connect screen: never commit this folder.\n*\n", { mode: 0o644 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, `${key}\n`, { mode: 0o600 });
+  await fs.chmod(tmp, 0o600);
+  await fs.rename(tmp, file);
+}
+
+/** Remove the stored key. Missing is fine. */
+export async function removeLocalKey(root?: string): Promise<void> {
+  await fs.rm(keyPath(root), { force: true });
+}
+
+/** `...wxyz`: enough for a person to recognise which key is in use, never enough to use it. */
+export function keyHint(key: string): string {
+  return key.length > 8 ? `...${key.slice(-4)}` : "...";
+}

package/blocks/_foundation/server/proxy.ts

@@ -14,6 +14,11 @@
  * and `allowedPrefixes` (only the areas the UI needs). The opt-outs
  * `dangerouslyAllowUnauthenticated` and `dangerouslyAllowAllPaths` exist for
  * local prototypes only.
+ *
+ * LOCAL PREVIEW (`localPreview: true`, set in apps made by `graph8-sdk create`):
+ * until `authorize` is set, the route answers ONLY `next dev` requests made
+ * from this machine (see `isLocalPreviewRequest`). A production build refuses
+ * every request (500) until `authorize` is set; the setting then does nothing.
  */
 
 export interface G8ProxyConfig {
@@ -42,6 +47,19 @@ export interface G8ProxyConfig {
    * `targetOrgId` is set.
    */
   allowTargetOrgHeader?: boolean;
+  /**
+   * Local preview, for `npm run dev` before your app has sign-in. Only applies while `authorize` is NOT set:
+   * the proxy then answers a request only when NODE_ENV is not "production" AND the request comes from this
+   * machine (Host localhost, 127.0.0.1 or [::1], same-origin, no forwarding proxy in between). Anything else
+   * gets 403; a production build gets 500 until you set `authorize`. Default false.
+   */
+  localPreview?: boolean;
+  /**
+   * Where the server's graph8 API key comes from. Default: `process.env.G8_API_KEY`, read on every request.
+   * Created apps pass `resolveApiKey` (g8/server/local-key.ts): the environment first, then, in local
+   * preview only, the key pasted in the Connect graph8 screen.
+   */
+  apiKey?: () => string | undefined | Promise<string | undefined>;
   /** Prototype opt-out: run without `authorize`. Anyone who can reach the route can use your key. */
   dangerouslyAllowUnauthenticated?: boolean;
   /** Prototype opt-out: run without `allowedPrefixes` (every /api/v1 path is reachable). */
@@ -158,9 +176,81 @@ async function readBodyCapped(request: Request, max: number): Promise<ArrayBuffe
   return out;
 }
 
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+const LOOPBACK_ADDRESSES = /^(127\.\d{1,3}\.\d{1,3}\.\d{1,3}|::1|::ffff:127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost)$/i;
+
+/** `localhost:3000` -> `localhost`, `[::1]:3000` -> `[::1]`. */
+function hostnameOf(host: string): string {
+  const h = host.trim().toLowerCase();
+  if (h.startsWith("[")) return h.slice(0, h.indexOf("]") + 1);
+  return h.replace(/:\d+$/, "");
+}
+
+function isLoopbackOrigin(value: string): boolean {
+  try {
+    return LOOPBACK_HOSTS.has(new URL(value).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when a request was made on this machine, by this app's own page (or typed in the address bar):
+ *   - Host (and X-Forwarded-Host, if any) is localhost, 127.0.0.1 or [::1], which also blocks DNS rebinding;
+ *   - every X-Forwarded-For hop is a loopback address (tunnels such as ngrok add the real client);
+ *   - the browser's Sec-Fetch-Site is same-origin or none, and Origin (if any) is a loopback origin,
+ *     so another website open in the same browser cannot drive the proxy (CSRF).
+ * Headers can be forged by a client that reaches the dev server directly, so created apps also bind
+ * `next dev` to 127.0.0.1 (package.json). Never rely on this check in production: set `authorize`.
+ */
+export function isLocalPreviewRequest(request: Request): boolean {
+  const host = request.headers.get("host") ?? new URL(request.url).host;
+  if (!LOOPBACK_HOSTS.has(hostnameOf(host))) return false;
+  const fwdHost = request.headers.get("x-forwarded-host");
+  if (fwdHost && !fwdHost.split(",").every((h) => LOOPBACK_HOSTS.has(hostnameOf(h)))) return false;
+  const fwdFor = request.headers.get("x-forwarded-for");
+  if (fwdFor && !fwdFor.split(",").every((a) => LOOPBACK_ADDRESSES.test(a.trim()))) return false;
+  const site = request.headers.get("sec-fetch-site");
+  if (site && site !== "same-origin" && site !== "none") return false;
+  const origin = request.headers.get("origin");
+  if (origin && !isLoopbackOrigin(origin)) return false;
+  return true;
+}
+
+const isProduction = (): boolean => process.env.NODE_ENV === "production";
+
+let previewLogged = false;
+
+/**
+ * The local-preview verdict for a request when `authorize` is unset: null to continue, or the refusal.
+ * Only called when `localPreview` is on and `authorize` is not set.
+ */
+function localPreviewGate(request: Request): Response | null {
+  if (isProduction()) {
+    return json(500, {
+      error: "g8_proxy_misconfigured",
+      message:
+        "Local preview only runs under `next dev`. This is a production build, so set `authorize` (check your app's session) in app/api/g8/[...path]/route.ts before going live. `npx @graph8/sdk doctor --production` lists what is left.",
+    });
+  }
+  if (!isLocalPreviewRequest(request)) {
+    return json(403, {
+      error: "local_preview_only",
+      message: "Local preview only answers requests from this machine (http://localhost). Set `authorize` in app/api/g8/[...path]/route.ts to serve anyone else.",
+    });
+  }
+  if (!previewLogged) {
+    previewLogged = true;
+    console.warn(
+      "[graph8] Local preview: /api/g8 answers requests from this machine only, with no sign-in check. Set `authorize` in app/api/g8/[...path]/route.ts before you deploy.",
+    );
+  }
+  return null;
+}
+
 /** The first reason this config is unsafe to serve, or null. Checked on every request. */
 function configProblem(config: G8ProxyConfig): string | null {
-  if (!config.authorize && !config.dangerouslyAllowUnauthenticated) {
+  if (!config.authorize && !config.dangerouslyAllowUnauthenticated && !config.localPreview) {
     return "Set `authorize` (check your app's session) in app/api/g8/[...path]/route.ts. The proxy refuses to run without it.";
   }
   if (!config.allowedPrefixes && !config.dangerouslyAllowAllPaths) {
@@ -177,11 +267,21 @@ export function createG8Proxy(config: G8ProxyConfig = {}) {
   async function handle(request: Request, context: RouteContext): Promise<Response> {
     const problem = configProblem(config);
     if (problem) return json(500, { error: "g8_proxy_misconfigured", message: problem });
+    const preview = Boolean(config.localPreview && !config.authorize && !config.dangerouslyAllowUnauthenticated);
+    if (preview) {
+      const refused = localPreviewGate(request);
+      if (refused) return refused;
+    }
     const denied = await config.authorize?.(request);
     if (denied) return denied;
 
-    const apiKey = process.env.G8_API_KEY;
-    if (!apiKey) return json(500, { error: "g8_proxy_misconfigured", message: "G8_API_KEY is not set on the server." });
+    const apiKey = config.apiKey ? await config.apiKey() : process.env.G8_API_KEY;
+    if (!apiKey) {
+      const message = preview
+        ? "No graph8 API key yet: open this app in the browser and paste one in the Connect graph8 screen, or set G8_API_KEY in .env.local."
+        : "G8_API_KEY is not set on the server.";
+      return json(500, { error: "g8_proxy_misconfigured", message });
+    }
 
     const params = await (context.params as Promise<{ path?: string[] }> | { path?: string[] });
     const path = normalizePath(params?.path);

package/blocks/_foundation/server/route.ts

@@ -4,18 +4,30 @@
  *
  * Next.js only allows HTTP-method names and a few config exports from a route
  * file, so the proxy configuration is a plain constant here, not an export.
- * Edit it. The proxy REFUSES every request (500) until BOTH `authorize` and
- * `allowedPrefixes` are set, because this route carries the full-power API key.
+ * Edit it. Before you deploy, set `authorize`: a production build refuses every
+ * request (500) until it is set, because this route carries the full-power API key.
+ * `npx @graph8/sdk doctor --production` checks this file for you.
  */
 
 import { createG8Proxy } from "@/g8/server/proxy";
+import { resolveApiKey } from "@/g8/server/local-key";
 
-// 1. Only the API areas this app's UI needs, relative to /api/v1. REQUIRED.
+// 1. The API areas this app's UI may call, relative to /api/v1. REQUIRED.
+// The lines between the graph8:allowed-prefixes markers are GENERATED from the operations the installed blocks
+// declare, and rewritten by `npx @graph8/sdk add <block>` and `npx @graph8/sdk doctor --fix-prefixes`. To own the
+// list yourself, delete both marker lines; the CLI then never touches it.
+// graph8:allowed-prefixes:start
 const allowedPrefixes: string[] | undefined = undefined; // e.g. ["contacts", "companies", "lists"]
+// graph8:allowed-prefixes:end
 
 export const { GET, POST, PUT, PATCH, DELETE } = createG8Proxy({
   allowedPrefixes,
-  // 2. Check YOUR session and return a Response (401/403) to refuse. REQUIRED:
+  // 2. Local preview: until `authorize` is set, answer only `npm run dev` requests from this machine
+  // (http://localhost). Ignored once `authorize` is set; a production build never runs without `authorize`.
+  localPreview: true,
+  // The key: G8_API_KEY from the environment, else (local preview only) the one pasted in the Connect graph8 screen.
+  apiKey: resolveApiKey,
+  // 3. Check YOUR session and return a Response (401/403) to refuse. REQUIRED before you deploy:
   // authorize: async (request) => { if (!(await getSession(request))) return new Response("Unauthorized", { status: 401 }); },
   //
   // Agency keys only: pick the client org from the session, never from the browser:

package/blocks/agents/README.md

@@ -4,6 +4,20 @@ An agent is a persona (how it talks), a voice, knowledge (documents and company
 (single-purpose actions). This block gives you the screens to build one, prove it works before anyone talks
 to it, and follow the runs agents do for you.
 
+## Screens
+
+`AgentsScreen` (`components/agents-screen.tsx`) is the finished agents workspace; mount it as the page.
+
+- **Agents tab**: stat strip (agents, active, inactive), search, status filter, the list, **New agent** (form sheet; the
+  agent starts inactive), activate / deactivate. Opening an agent (deep link `?id=`) shows a detail panel with
+  **Configure** (persona, voice, knowledge, skills, delete), **Test** (free dry runs, saved cases, the activation gate,
+  run a skill live) and **Runs** (this agent's runs).
+- **Runs tab**: every run as a list; opening one (`?run=`) shows `AgentRunDetail` (status, step, credits, times, its approvals to approve or reject, cancel). Start a run here. `&view=full` opens any record as a full page.
+- Uploading documents, running a skill, starting or cancelling a run, approving and deleting an agent are confirmed
+  with `ConfirmSpendDialog` inside the parts. Needs `voice:read|write|delete`, `knowledge:read`, `workflows:*`.
+- Slots: `renderRowActions`, `renderDetailActions`, `extraDetailTabs`, `toolbarActions`. `AgentBuilder` gained
+  `hideList`; `AgentRuns` gained `selectedId`, `onSelectRun`, `hideDetail`, `refreshKey`; new `AgentRunDetail`.
+
 Install: `npx @graph8/sdk add agents` (installs `foundation` first).
 
 ## What you get

package/blocks/agents/block.json

@@ -47,6 +47,37 @@
     "upload_agent_documents_voice_agents__agent_id__documents_upload_post"
   ],
   "components": [
+    {
+      "name": "AgentsScreen",
+      "file": "components/agents-screen.tsx",
+      "purpose": "Finished agents workspace: stats, search, list, create sheet, and a detail panel with configure, test and runs, plus a workspace-wide Runs tab.",
+      "operations": [
+        "create_voice_agent_voice_agents_post",
+        "get_voice_agent_voice_agents__agent_id__get",
+        "list_voice_agents_voice_agents_get",
+        "update_voice_agent_voice_agents__agent_id__put"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "AgentRunDetail",
+      "file": "components/agent-run-detail.tsx",
+      "purpose": "One agent run in full: status, step, credits, times, its pending approvals and cancel.",
+      "operations": [
+        "get_agent_run_agent_runs__run_id__get",
+        "list_agent_approvals_agent_approvals_get",
+        "decide_agent_approval_agent_approvals__approval_id__decide_post",
+        "cancel_agent_run_agent_runs__run_id__cancel_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
     {
       "name": "AgentBuilder",
       "file": "components/agent-builder.tsx",
@@ -218,6 +249,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }

package/blocks/agents/components/agent-builder.tsx

@@ -37,6 +37,8 @@ export interface AgentBuilderProps {
   onSelect?: (agentId: string | null) => void;
   /** Called after a create, update or delete so the host can refresh its own lists. */
   onChanged?: () => void;
+  /** Hide the built-in agent list and "New agent" button when the host (for example AgentsScreen) provides its own. */
+  hideList?: boolean;
   className?: string;
 }
 
@@ -60,7 +62,7 @@ function Dial({ label, value, onChange, low, high }: { label: string; value: num
   );
 }
 
-export function AgentBuilder({ agentId: controlled, onSelect, onChanged, className }: AgentBuilderProps) {
+export function AgentBuilder({ agentId: controlled, onSelect, onChanged, hideList, className }: AgentBuilderProps) {
   const [inner, setInner] = useState<string | null>(null);
   const selected = controlled !== undefined ? controlled : inner;
   const [creating, setCreating] = useState(false);
@@ -70,7 +72,7 @@ export function AgentBuilder({ agentId: controlled, onSelect, onChanged, classNa
   const [deleting, setDeleting] = useState(false);
 
   const choose = (id: string | null) => { setInner(id); setCreating(false); onSelect?.(id); };
-  const agents = useG8Query((signal) => g8Get("/voice/agents", { search: search.trim() || undefined, page_size: 50 }, { signal }), [search]);
+  const agents = useG8Query((signal) => g8Get("/voice/agents", { search: search.trim() || undefined, page_size: 50 }, { signal }), [search], { enabled: !hideList });
   const detail = useG8Query((signal) => g8Get(`/voice/agents/${selected}`, undefined, { signal }), [selected], { enabled: Boolean(selected) && !creating });
   const voices = useG8Query((signal) => g8Get("/voice/voice-library/presets", { limit: 100 }, { signal }), []);
 
@@ -87,7 +89,7 @@ export function AgentBuilder({ agentId: controlled, onSelect, onChanged, classNa
     {
       onSuccess: (res) => {
         const id = bodyOf<{ agent?: { agent_id?: string } }>(res).agent?.agent_id;
-        void agents.refetch();
+        if (!hideList) void agents.refetch();
         // Keep the new id on the draft at once: a second click (or a retry after a later step fails) must update, never create a twin.
         if (!draft?.agent_id && id) { setDraft((d) => d && { ...d, agent_id: id }); choose(id); }
         else void detail.refetch();
@@ -96,17 +98,19 @@ export function AgentBuilder({ agentId: controlled, onSelect, onChanged, classNa
     },
   );
   const remove = useG8Mutation((id: string) => g8Delete(`/voice/agents/${id}`), {
-    onSuccess: () => { setDeleting(false); setDraft(null); choose(null); void agents.refetch(); onChanged?.(); },
+    onSuccess: () => { setDeleting(false); setDraft(null); choose(null); if (!hideList) void agents.refetch(); onChanged?.(); },
   });
 
   const rows = listOf<AgentSummary>(agents.data, "agents");
   const presets = listOf<{ voice_id?: string; id?: string; name?: string; label?: string }>(voices.data, "items");
   const setPersona = (patch: Partial<AgentDetail["persona"]>) => setDraft((d) => d && { ...d, persona: { ...d.persona, ...patch } });
+  // The hook keeps the previous agent's data while the next one loads: until it arrives the old form must not be shown (or saved) as the new agent.
+  const stale = Boolean(draft?.agent_id && selected && draft.agent_id !== selected && !creating);
   const valid = Boolean(draft?.persona.agent_name.trim() && draft?.persona.persona.trim() && draft?.persona.description.trim() && draft?.role.trim());
 
   return (
-    <div className={`grid gap-4 md:grid-cols-[16rem_1fr] ${className ?? ""}`}>
-      <aside className="flex flex-col gap-2">
+    <div className={`grid gap-4 ${hideList ? "" : "md:grid-cols-[16rem_1fr]"} ${className ?? ""}`}>
+      {hideList ? null : <aside className="flex flex-col gap-2">
         <div className="flex gap-2">
           <Input aria-label="Search agents" placeholder="Search agents" value={search} onChange={(e) => setSearch(e.target.value)} />
           <Button size="sm" onClick={() => { setCreating(true); setDraft(blankDraft()); setSection("persona"); onSelect?.(null); }}>New agent</Button>
@@ -127,12 +131,13 @@ export function AgentBuilder({ agentId: controlled, onSelect, onChanged, classNa
         {!agents.loading && !agents.error && rows.length === 0 ? (
           <EmptyState title="No agents yet" description="An agent has a persona, a voice, knowledge and skills." />
         ) : null}
-      </aside>
+      </aside>}
 
       <section className="flex min-w-0 flex-col gap-3">
         {!draft && !creating ? <EmptyState title="Pick an agent" description="Choose one on the left or create a new agent." /> : null}
         {detail.error ? <ApiError error={detail.error} title="Could not load the agent" onRetry={() => void detail.refetch()} /> : null}
-        {draft ? (
+        {stale && !detail.error ? <Skeleton className="h-64 w-full" aria-label="Loading agent" /> : null}
+        {draft && !stale ? (
           <>
             <div role="tablist" className="flex gap-1 border-b">
               {SECTIONS.map((s) => (

package/blocks/agents/components/agent-knowledge-panel.tsx

@@ -25,6 +25,7 @@ import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
 import { listOf } from "../lib/agent-types";
+import { plural } from "@/g8/lib/plural";
 
 export interface AgentKnowledgePanelProps {
   agentId: string;
@@ -132,7 +133,7 @@ export function AgentKnowledgePanel({ agentId, useCompanyKnowledge, onToggleComp
 
       {upload.error ? <ApiError error={upload.error} title="Could not upload" /> : null}
       {remove.error ? <ApiError error={remove.error} title="Could not remove the document" /> : null}
-      <ConfirmSpendDialog open={pending != null} tier="billable" title={`Index ${pending?.length ?? 0} document${pending?.length === 1 ? "" : "s"}`}
+      <ConfirmSpendDialog open={pending != null} tier="billable" title={`Index ${plural(pending?.length ?? 0, "document")}`}
         description="The text is extracted and embedded with a paid model so the agent can search it."
         estimatedCredits={(pending?.length ?? 0) * creditsPerFile} confirmLabel="Upload" confirming={upload.loading}
         onConfirm={() => pending && void upload.mutate(pending)} onCancel={() => setPending(null)} />

package/blocks/agents/components/agent-run-detail.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+/**
+ * AgentRunDetail: one agent run in full. Title, status, agent, current step, next action, credits against the budget,
+ * created and completed times, the approvals this run is waiting on (approve or reject), and Cancel while it is live.
+ * The run is polled until it is terminal (the API has no streams).
+ *
+ * SDK operations, in order:
+ *   1. getAgentRun         GET  /agent/runs/{run_id}                          (read)  polled
+ *   2. listAgentApprovals  GET  /agent/approvals                              (read)  this run's pending ones
+ *   3. decideAgentApproval POST /agent/approvals/{approval_id}/decide { decision }   (write; approving lets the run act: ConfirmSpendDialog, external)
+ *   4. cancelAgentRun      POST /agent/runs/{run_id}/cancel                   (destructive, ConfirmSpendDialog)
+ * Approvals that gate a Work coordination action cannot be decided with an API key: the error is shown as is.
+ */
+import { useEffect, useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { bodyOf, listOf } from "../lib/agent-types";
+import type { AgentRun } from "../lib/agent-types";
+import { isTerminalRun } from "./agent-runs";
+
+export interface AgentRunDetailProps {
+  runId: string;
+  /** Poll interval in ms. Default 3000. */
+  pollMs?: number;
+  /** Called after a cancel or a decision so the host can refresh its run list. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+interface Approval { id: string; summary: string; risk_level: string; work_item_id: string; decision?: string | null; is_expired?: boolean }
+
+const when = (v?: string | null): string => (v ? new Date(v).toLocaleString() : "");
+
+export function AgentRunDetail({ runId, pollMs = 3000, onChanged, className }: AgentRunDetailProps) {
+  const [cancelling, setCancelling] = useState(false);
+  const [approving, setApproving] = useState<Approval | null>(null);
+  const [deciding, setDeciding] = useState<string | null>(null);
+  const poll = useJobPoll<AgentRun>((signal) => g8Get<AgentRun>(`/agent/runs/${encodeURIComponent(runId)}`, undefined, { signal }).then((r) => bodyOf<AgentRun>(r)), {
+    isTerminal: isTerminalRun, intervalMs: pollMs, maxIntervalMs: pollMs * 4, onDone: () => onChanged?.(),
+  });
+  const approvals = useG8Query((signal) => g8Get("/agent/approvals", undefined, { signal }), [runId]);
+  useEffect(() => { poll.start(); setCancelling(false); setApproving(null); }, [runId]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { if (poll.attempts > 0) void approvals.refetch(); }, [poll.attempts]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const cancel = useG8Mutation(() => g8Post(`/agent/runs/${encodeURIComponent(runId)}/cancel`, {}), { onSuccess: () => { setCancelling(false); poll.start(); onChanged?.(); }, onError: () => setCancelling(false) });
+  const decide = useG8Mutation(async (v: { id: string; decision: "approve" | "reject" }) => {
+    setDeciding(v.id);
+    try { return await g8Post(`/agent/approvals/${encodeURIComponent(v.id)}/decide`, { decision: v.decision }); } finally { setDeciding(null); }
+  }, { onSuccess: () => { setApproving(null); void approvals.refetch(); onChanged?.(); }, onError: () => setApproving(null) });
+
+  const run = poll.status?.work_item_id === runId ? poll.status : undefined;
+  const pending = listOf<Approval>(approvals.data).filter((a) => a.work_item_id === runId && !a.decision && !a.is_expired);
+  if (!run) return poll.error ? <ApiError error={poll.error} title="Could not load the run" onRetry={() => poll.start()} /> : <Skeleton className="h-40 w-full" aria-label="Loading run" />;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`} data-testid="run-detail">
+      <div className="flex flex-wrap items-center gap-2">
+        <StatusPill tone={toneForStatus(run.status)} dot>{run.status}</StatusPill>
+        {poll.polling ? <span className="text-xs text-muted-foreground">updating</span> : null}
+        {!isTerminalRun(run) ? <Button className="ml-auto" size="sm" variant="outline" onClick={() => setCancelling(true)}>Cancel run</Button> : null}
+      </div>
+      <KeyValueList columns={2} items={[
+        { label: "Title", value: run.title, wide: true },
+        { label: "Agent", value: run.agent_id, mono: true },
+        { label: "Run id", value: run.work_item_id, mono: true },
+        { label: "Current step", value: run.current_step },
+        { label: "Next action", value: run.next_action },
+        { label: "Credits", value: `${run.credits_spent ?? 0}${run.credit_budget ? ` of ${run.credit_budget}` : ""}` },
+        { label: "Started", value: when(run.created_at) },
+        { label: "Finished", value: when(run.completed_at) },
+      ]} />
+      {pending.length > 0 ? (
+        <section className="space-y-2 rounded-md border p-3" aria-label="Approvals" data-testid="run-approvals">
+          <h4 className="text-sm font-semibold">Waiting for your decision ({pending.length})</h4>
+          {pending.map((a) => (
+            <div key={a.id} className="flex flex-wrap items-center justify-between gap-2 text-sm">
+              <span>{a.summary}<span className="ml-2 text-xs text-muted-foreground">risk: {a.risk_level}</span></span>
+              <span className="flex gap-2">
+                <Button size="sm" variant="outline" loading={deciding === a.id} disabled={deciding != null && deciding !== a.id} onClick={() => void decide.mutate({ id: a.id, decision: "reject" })}>Reject</Button>
+                <Button size="sm" disabled={deciding != null} onClick={() => setApproving(a)}>Approve</Button>
+              </span>
+            </div>
+          ))}
+        </section>
+      ) : null}
+      {decide.error ? <ApiError error={decide.error} title="Could not record the decision" /> : null}
+      {cancel.error ? <ApiError error={cancel.error} title="Could not cancel the run" /> : null}
+      <ConfirmSpendDialog open={cancelling} tier="destructive" title={`Cancel "${run.title}"`} description="Work stops where it is. Steps already taken are not undone."
+        confirmLabel="Cancel run" confirming={cancel.loading} onConfirm={() => void cancel.mutate(undefined)} onCancel={() => setCancelling(false)} />
+      <ConfirmSpendDialog open={approving != null} tier="external" title="Approve this action" description={approving?.summary}
+        confirmLabel="Approve" confirming={decide.loading} onConfirm={() => approving && void decide.mutate({ id: approving.id, decision: "approve" })} onCancel={() => setApproving(null)} />
+    </div>
+  );
+}

package/blocks/agents/components/agent-runs.tsx

@@ -36,6 +36,13 @@ export interface AgentRunsProps {
   pageSize?: number;
   /** Poll interval for the selected run, in ms. Default 3000. */
   pollMs?: number;
+  /** Controlled selection (a run id). With it, the host owns which run is open (for example from the URL). */
+  selectedId?: string | null;
+  onSelectRun?: (runId: string | null) => void;
+  /** Hide the built-in detail box when the host shows the run elsewhere (see AgentRunDetail). */
+  hideDetail?: boolean;
+  /** Change this number to reload the list (for example after AgentRunDetail cancelled a run). */
+  refreshKey?: number;
   className?: string;
 }
 
@@ -46,28 +53,30 @@ const TERMINAL = new Set(["completed", "succeeded", "failed", "cancelled", "canc
 export const isTerminalRun = (r: Pick<AgentRun, "status"> | undefined): boolean => TERMINAL.has(String(r?.status ?? "").toLowerCase());
 const STATUSES = ["running", "queued", "completed", "failed", "cancelled"];
 
-export function AgentRuns({ agentId, pageSize = 20, pollMs = 3000, className }: AgentRunsProps) {
+export function AgentRuns({ agentId, pageSize = 20, pollMs = 3000, selectedId, onSelectRun, hideDetail, refreshKey, className }: AgentRunsProps) {
   const [status, setStatus] = useState("");
   const [limit, setLimit] = useState(pageSize);
-  const [selected, setSelected] = useState<string | null>(null);
+  const [innerSel, setInnerSel] = useState<string | null>(null);
+  const selected = selectedId !== undefined ? selectedId : innerSel;
+  const setSelected = (id: string | null) => { setInnerSel(id); onSelectRun?.(id); };
   const [form, setForm] = useState<{ agent_id: string; title: string; goal: string } | null>(null);
   const [confirmStart, setConfirmStart] = useState(false);
   const [cancelling, setCancelling] = useState<AgentRun | null>(null);
   const [approving, setApproving] = useState<Approval | null>(null);
   const [deciding, setDeciding] = useState<string | null>(null);
 
-  const runs = useG8Query((signal) => g8Get("/agent/runs", { statuses: status || undefined, agent_id: agentId, limit }, { signal }), [status, agentId, limit]);
+  const runs = useG8Query((signal) => g8Get("/agent/runs", { statuses: status || undefined, agent_id: agentId, limit }, { signal }), [status, agentId, limit, refreshKey]);
   const approvals = useG8Query((signal) => g8Get("/agent/approvals", undefined, { signal }), []);
   const specialists = useG8Query((signal) => g8Get("/agent/specialists", undefined, { signal }), [], { enabled: form != null });
   const detail = useJobPoll<AgentRun>((signal) => g8Get<AgentRun>(`/agent/runs/${selected}`, undefined, { signal }).then((r) => bodyOf<AgentRun>(r)), {
-    enabled: selected != null, isTerminal: isTerminalRun, intervalMs: pollMs, maxIntervalMs: pollMs * 4, onDone: () => void runs.refetch(),
+    enabled: selected != null && !hideDetail, isTerminal: isTerminalRun, intervalMs: pollMs, maxIntervalMs: pollMs * 4, onDone: () => void runs.refetch(),
   });
 
   // Switching runs keeps `enabled` true, so restart the poll explicitly.
-  useEffect(() => { if (selected) detail.start(); }, [selected]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { if (selected && !hideDetail) detail.start(); }, [selected]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // A run that stops on an approval keeps polling: refresh the approvals on every poll that lands.
-  useEffect(() => { if (selected && detail.attempts > 0) void approvals.refetch(); }, [detail.attempts]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { if (selected && !hideDetail && detail.attempts > 0) void approvals.refetch(); }, [detail.attempts]); // eslint-disable-line react-hooks/exhaustive-deps
 
   const start = useG8Mutation(() => g8Post<AgentRun>("/agent/runs", { agent_id: form?.agent_id ?? agentId, title: form?.title.trim(), goal: form?.goal.trim() }), {
     onSuccess: (res) => { setConfirmStart(false); setForm(null); setSelected(bodyOf<AgentRun>(res).work_item_id ?? null); void runs.refetch(); },
@@ -147,7 +156,7 @@ export function AgentRuns({ agentId, pageSize = 20, pollMs = 3000, className }:
       {!runs.loading && !runs.error && rows.length === 0 ? <EmptyState title="No runs yet" description="A run is one goal worked on by an agent, step by step, with approvals where it matters." /> : null}
       {rows.length < total ? <Button variant="outline" size="sm" onClick={() => setLimit(limit + pageSize)}>Load more</Button> : null}
 
-      {selected ? (
+      {selected && !hideDetail ? (
         <div className="rounded-md border p-3" data-testid="run-detail">
           {current ? (
             <>