@graph8/sdk 0.303.0 → 0.357.0

package/blocks/_foundation/server/proxy.ts

@@ -0,0 +1,233 @@
+/**
+ * Server-side proxy that lets the browser call graph8 without ever seeing the
+ * API key. Used by `app/api/g8/[...path]/route.ts` (see ./route.ts).
+ *
+ *   browser -> /api/g8/contacts?limit=10 -> THIS -> https://be.graph8.com/api/v1/contacts?limit=10
+ *                                                    Authorization: Bearer $G8_API_KEY
+ *
+ * Plain Web `Request`/`Response`, no framework imports, so it runs on the Node
+ * and Edge runtimes and is unit-testable. The key is read from the environment
+ * on every request and is never logged, echoed or put in a response.
+ *
+ * SECURITY: this route is exactly as powerful as the key. It therefore REFUSES
+ * every request (500) until you set BOTH `authorize` (check your own session)
+ * and `allowedPrefixes` (only the areas the UI needs). The opt-outs
+ * `dangerouslyAllowUnauthenticated` and `dangerouslyAllowAllPaths` exist for
+ * local prototypes only.
+ */
+
+export interface G8ProxyConfig {
+  /**
+   * Path prefixes (relative to /api/v1, no leading slash) the browser may call,
+   * for example `["contacts", "companies", "lists"]`. `/contacts` and
+   * `/contacts/42` match "contacts"; "contactsX" does not. Omit to allow every
+   * path (fine for prototypes, not for production).
+   */
+  allowedPrefixes?: readonly string[];
+  /**
+   * Your own gate, run before anything is forwarded. Return a `Response`
+   * (usually 401/403) to refuse, or nothing to continue. REQUIRED unless
+   * `dangerouslyAllowUnauthenticated` is true.
+   */
+  authorize?: (request: Request) => Response | void | Promise<Response | void>;
+  /**
+   * Agency keys: decide the client org ON THE SERVER, from your session, for
+   * example `(req) => orgForUser(req)`. Sent as `X-Target-Org-Id`; whatever the
+   * browser sends is ignored. Return undefined to act on the key's own org.
+   */
+  targetOrgId?: (request: Request) => string | undefined | Promise<string | undefined>;
+  /**
+   * Forward the BROWSER's own `X-Target-Org-Id`. Default false: a signed-in user
+   * of your app must not be able to switch to another client org. Ignored when
+   * `targetOrgId` is set.
+   */
+  allowTargetOrgHeader?: boolean;
+  /** 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). */
+  dangerouslyAllowAllPaths?: boolean;
+  /** Largest request body forwarded, in bytes. Default 5 MiB. */
+  maxBodyBytes?: number;
+  /** Replace `fetch` (tests). */
+  fetch?: typeof fetch;
+}
+
+export const DEFAULT_API_URL = "https://be.graph8.com";
+const DEFAULT_MAX_BODY = 5 * 1024 * 1024;
+
+/** Hop-by-hop headers (RFC 9110 7.6.1) plus the ones fetch re-computes. Never copied either way. */
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+  "content-length",
+  "content-encoding",
+]);
+
+/** Request headers the browser may influence. Everything else is dropped. */
+const FORWARDED_REQUEST_HEADERS = ["content-type", "accept", "accept-language", "idempotency-key"];
+
+function json(status: number, body: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+
+function cleanPrefix(prefix: string): string {
+  return prefix.replace(/^\/+|\/+$/g, "");
+}
+
+/** The validated, re-encoded path under /api/v1, or null when a segment is unsafe. */
+export function normalizePath(segments: readonly string[] | undefined): string | null {
+  if (!segments || segments.length === 0) return null;
+  const out: string[] = [];
+  for (const raw of segments) {
+    let seg: string;
+    try {
+      seg = decodeURIComponent(raw);
+    } catch {
+      return null;
+    }
+    if (seg === "" || seg === "." || seg === ".." || /[\\/\0]/.test(seg)) return null;
+    out.push(encodeURIComponent(seg));
+  }
+  return out.join("/");
+}
+
+export function isAllowed(path: string, prefixes: readonly string[] | undefined): boolean {
+  if (!prefixes) return true;
+  const decoded = decodeURIComponent(path);
+  return prefixes.map(cleanPrefix).some((p) => p !== "" && (decoded === p || decoded.startsWith(`${p}/`)));
+}
+
+function buildUpstreamHeaders(request: Request, apiKey: string, org: string | undefined): Headers {
+  const headers = new Headers();
+  for (const name of FORWARDED_REQUEST_HEADERS) {
+    const value = request.headers.get(name);
+    if (value) headers.set(name, value);
+  }
+  if (org) headers.set("X-Target-Org-Id", org);
+  headers.set("Authorization", `Bearer ${apiKey}`);
+  headers.set("X-G8-Client", "g8-blocks-proxy");
+  return headers;
+}
+
+function buildResponseHeaders(upstream: Response): Headers {
+  const headers = new Headers();
+  upstream.headers.forEach((value, name) => {
+    const lower = name.toLowerCase();
+    if (HOP_BY_HOP.has(lower) || lower === "set-cookie" || lower === "location") return;
+    headers.set(name, value);
+  });
+  return headers;
+}
+
+/**
+ * Read the body with a running byte count and stop as soon as it passes `max`,
+ * so an oversized upload never sits whole in memory. Null means "too large".
+ */
+async function readBodyCapped(request: Request, max: number): Promise<ArrayBuffer | null> {
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > max) return null;
+  if (!request.body) return new ArrayBuffer(0);
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > max) {
+      await reader.cancel().catch(() => undefined);
+      return null;
+    }
+    chunks.push(value);
+  }
+  const out = new ArrayBuffer(total);
+  const view = new Uint8Array(out);
+  let at = 0;
+  for (const c of chunks) {
+    view.set(c, at);
+    at += c.byteLength;
+  }
+  return out;
+}
+
+/** 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) {
+    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) {
+    return "Set `allowedPrefixes` (the API areas the UI needs) in app/api/g8/[...path]/route.ts. The proxy refuses to run without it.";
+  }
+  return null;
+}
+
+/** Next.js 15 requires exactly this shape; Next 14 passes a plain object, which `await` below also accepts. */
+type RouteContext = { params: Promise<{ path: string[] }> };
+
+/** Build the five App Router handlers. */
+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 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 params = await (context.params as Promise<{ path?: string[] }> | { path?: string[] });
+    const path = normalizePath(params?.path);
+    if (!path) return json(400, { error: "bad_path", message: "Invalid API path." });
+    if (!isAllowed(path, config.allowedPrefixes)) {
+      return json(403, { error: "path_not_allowed", message: "This path is not available from the browser." });
+    }
+
+    const method = request.method.toUpperCase();
+    let body: ArrayBuffer | undefined;
+    if (method !== "GET" && method !== "HEAD") {
+      const read = await readBodyCapped(request, config.maxBodyBytes ?? DEFAULT_MAX_BODY);
+      if (!read) return json(413, { error: "body_too_large", message: "Request body is too large." });
+      body = read;
+    }
+    const org = config.targetOrgId
+      ? await config.targetOrgId(request)
+      : config.allowTargetOrgHeader
+        ? (request.headers.get("x-target-org-id") ?? undefined)
+        : undefined;
+
+    const base = (process.env.G8_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, "");
+    const url = `${base}/api/v1/${path}${new URL(request.url).search}`;
+    const doFetch = config.fetch ?? globalThis.fetch;
+    let upstream: Response;
+    try {
+      upstream = await doFetch(url, {
+        method,
+        headers: buildUpstreamHeaders(request, apiKey, org),
+        body: body && body.byteLength > 0 ? body : undefined,
+        redirect: "manual",
+        cache: "no-store",
+      });
+    } catch {
+      return json(502, { error: "upstream_unreachable", message: "Could not reach the graph8 API." });
+    }
+    // redirect: "manual" hands back the 3xx itself; its Location would expose backend URLs.
+    if (upstream.status >= 300 && upstream.status < 400) {
+      return json(502, { error: "upstream_redirect", message: "The graph8 API answered with a redirect." });
+    }
+    return new Response(upstream.body, {
+      status: upstream.status,
+      statusText: upstream.statusText,
+      headers: buildResponseHeaders(upstream),
+    });
+  }
+
+  return { GET: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle };
+}

package/blocks/_foundation/server/route.ts

@@ -0,0 +1,30 @@
+/**
+ * Install as `app/api/g8/[...path]/route.ts` (the CLI copies it there and
+ * copies ./proxy.ts to `g8/server/proxy.ts`, matching the `@/g8/*` import).
+ *
+ * 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.
+ */
+
+import { createG8Proxy } from "@/g8/server/proxy";
+
+// 1. Only the API areas this app's UI needs, relative to /api/v1. REQUIRED.
+const allowedPrefixes: string[] | undefined = undefined; // e.g. ["contacts", "companies", "lists"]
+
+export const { GET, POST, PUT, PATCH, DELETE } = createG8Proxy({
+  allowedPrefixes,
+  // 2. Check YOUR session and return a Response (401/403) to refuse. REQUIRED:
+  // 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:
+  // targetOrgId: async (request) => (await getSession(request))?.g8OrgId,
+  //
+  // Local prototypes ONLY (anyone who can reach the route can use your key):
+  // dangerouslyAllowUnauthenticated: true,
+  // dangerouslyAllowAllPaths: true,
+});
+
+// Never cache proxied API responses.
+export const dynamic = "force-dynamic";

package/blocks/agents/README.md

@@ -0,0 +1,133 @@
+# agents: build, test and run AI agents
+
+An agent is a persona (how it talks), a voice, knowledge (documents and company knowledge) and skills
+(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.
+
+Install: `npx @graph8/sdk add agents` (installs `foundation` first).
+
+## What you get
+
+| Component | Use it for | Embed props |
+|---|---|---|
+| `AgentBuilder` | Agent list plus editor: persona dials, voice, inbound / outbound / voicemail instructions, active toggle, delete. Tabs for knowledge and skills | `agentId`, `onSelect`, `onChanged` |
+| `AgentKnowledgePanel` | The agent's own documents (billable upload, remove) and company knowledge search | `agentId`, `useCompanyKnowledge`, `onToggleCompanyKnowledge`, `creditsPerFile` |
+| `AgentSkillsPanel` | Attach / detach skills, write a new LLM skill | `agentId`, `onChanged` |
+| `AgentTestConsole` | Free dry runs, saved cases, regression sweep, the activation gate; run an attached skill live | `agentId` |
+| `AgentRuns` | Start a run, follow it (polled), cancel it, decide its approvals | `agentId`, `pageSize`, `pollMs` |
+
+## The flow, with the ids that pass between steps
+
+1. **Create**: `POST /voice/agents { role, persona, identity }` returns `agent.agent_id`. Create it
+   `agent_status: "inactive"`. `persona` needs `agent_name`, `persona`, `description` and the three dials
+   (0 to 1). `persona`, `identity` and `knowledge` are replaced whole on `PUT /voice/agents/{agent_id}`.
+2. **Voice**: `GET /voice/voice-library/presets` lists voices; put the chosen id in `identity.voice`.
+3. **Knowledge**: `POST /voice/agents/{agent_id}/documents/upload` (multipart field `files`, 5 MiB total per upload through the proxy,
+   billable) and `GET .../documents`. `use_company_knowledge` is a plain field on the agent; company
+   knowledge itself is read with `GET /knowledge/search?query=`.
+4. **Skills**: `POST /skills { name, runtime_type: "llm", llm_config: { prompt, model } }` returns an
+   `action_id`; `POST /voice/agents/{agent_id}/skills { action_ids }` attaches it. Models come from
+   `GET /skills/models`.
+5. **Test**: `POST /voice/agents/{agent_id}/test { input_message | test_case_id, channel, assertion_type,
+   expected_output }` is a dry run: no model call, no message sent. Save good ones with
+   `POST .../test-cases`, sweep with `POST .../test/run-all`, read the gate with `GET .../test-suite-status`.
+6. **Activate**: `PUT /voice/agents/{agent_id} { agent_status: "active" }` once the gate is satisfied.
+7. **Runs**: `GET /agent/specialists` gives the `agent_id` a run accepts; `POST /agent/runs { agent_id,
+   title, goal }` returns `work_item_id`; poll `GET /agent/runs/{run_id}` until `status` is terminal.
+   Approvals a run stops on: `GET /agent/approvals`, then `POST /agent/approvals/{approval_id}/decide
+   { decision: "approve" | "reject" }`.
+
+```tsx
+"use client";
+import { useState } from "react";
+import { AgentBuilder } from "@/components/g8/agents/components/agent-builder";
+import { AgentTestConsole } from "@/components/g8/agents/components/agent-test-console";
+
+export function AgentStudio() {
+  const [id, setId] = useState<string | null>(null);
+  return (
+    <>
+      <AgentBuilder agentId={id} onSelect={setId} />
+      {id ? <AgentTestConsole agentId={id} /> : null}
+    </>
+  );
+}
+```
+
+(`add` installs under `components/g8/agents/`, or `src/components/g8/agents/`; adjust the alias.)
+
+## Tiers and confirmations
+
+- Create, edit, attach, dry runs and saved cases are writes (free); they run directly.
+- Deleting an agent, removing a document, detaching a skill and cancelling a run are `destructive` and go
+  through `ConfirmSpendDialog`.
+- Uploading documents is `billable` (they are embedded with a paid model): the dialog shows the file count
+  and an estimate (`creditsPerFile`, default 5; there is no balance or price read, so it is an estimate).
+- Running a skill live is `external` (it may call an API or message someone). Starting a run is a write that
+  spends credits as it works, so it is confirmed as `billable`. Approving an action is confirmed as `external`.
+
+## Prerequisites
+
+- `foundation-installed` (app): the proxy `allowedPrefixes` include `voice`, `skills`, `knowledge`, `agent`.
+- `api-key-scopes` (api): `voice:read|write|delete`, `knowledge:read`, `workflows:read|write|run|delete`.
+- Agents that place calls need a phone number and a dialer session: see the `dialer` block. Nothing here
+  places a call.
+
+## Defaults the agent can use without asking
+
+| Decision | Default |
+|---|---|
+| Status of a new agent | `inactive` until a dry run passes |
+| Persona dials | 0.5 each |
+| Use company knowledge | on |
+
+Ask the person: who may approve agent actions and run skills live (decide it in the proxy's `authorize`).
+
+## Known limits
+
+- Runs and approvals that gate a Work coordination action cannot be decided with an API key
+  (`COORDINATION_APPROVAL_NOT_DECIDABLE_BY_KEY`): the screen shows the error; decide those in the graph8 app.
+- No streaming: `AgentRuns` polls every `pollMs` (backoff up to 4x).
+- A dry run never calls a model, so `llm_judge` assertions are saved but skipped.
+
+## Recipes
+
+| File | Does |
+|---|---|
+| `recipes/create-agent-and-attach-skill.ts` | Create an agent, create and attach a skill, list its documents |
+| `recipes/test-agent-before-activating.ts` | Save a case, run the sweep, read the activation gate, one ad-hoc dry run |
+| `recipes/run-and-follow-agent-run.ts` | Pick a specialist, start a run, poll to the end, list and decide approvals, cancel |
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| listAgentApprovals | GET /agent/approvals | read | AgentRuns |
+| decideAgentApproval | POST /agent/approvals/{approval_id}/decide | write | AgentRuns |
+| listAgentRuns | GET /agent/runs | read | AgentRuns |
+| createAgentRun | POST /agent/runs | write | AgentRuns |
+| getAgentRun | GET /agent/runs/{run_id} | read | AgentRuns |
+| cancelAgentRun | POST /agent/runs/{run_id}/cancel | destructive | AgentRuns |
+| listAgentSpecialists | GET /agent/specialists | read | AgentRuns |
+| searchKnowledge | GET /knowledge/search | read | AgentKnowledgePanel |
+| listSkills | GET /skills | read | AgentSkillsPanel |
+| createSkill | POST /skills | write | AgentSkillsPanel |
+| listModels | GET /skills/models | read | AgentSkillsPanel |
+| executeSkill | POST /skills/{action_id}/execute | external | AgentTestConsole |
+| deleteAgentDocument | DELETE /voice/agent-documents/{document_id} | destructive | AgentKnowledgePanel |
+| listVoiceAgents | GET /voice/agents | read | AgentBuilder |
+| createVoiceAgent | POST /voice/agents | write | AgentBuilder |
+| getVoiceAgent | GET /voice/agents/{agent_id} | read | AgentBuilder |
+| updateVoiceAgent | PUT /voice/agents/{agent_id} | write | AgentBuilder, AgentKnowledgePanel |
+| deleteVoiceAgent | DELETE /voice/agents/{agent_id} | destructive | AgentBuilder |
+| listAgentDocuments | GET /voice/agents/{agent_id}/documents | read | AgentKnowledgePanel |
+| uploadAgentDocuments | POST /voice/agents/{agent_id}/documents/upload | billable | AgentKnowledgePanel |
+| listAgentSkills | GET /voice/agents/{agent_id}/skills | read | AgentSkillsPanel, AgentTestConsole |
+| attachSkillsToAgent | POST /voice/agents/{agent_id}/skills | write | AgentSkillsPanel |
+| detachSkillFromAgent | DELETE /voice/agents/{agent_id}/skills/{action_id} | destructive | AgentSkillsPanel |
+| runAgentTest | POST /voice/agents/{agent_id}/test | write | AgentTestConsole |
+| listAgentTestCases | GET /voice/agents/{agent_id}/test-cases | read | AgentTestConsole |
+| createAgentTestCase | POST /voice/agents/{agent_id}/test-cases | write | AgentTestConsole |
+| getAgentTestSuiteStatus | GET /voice/agents/{agent_id}/test-suite-status | read | AgentTestConsole |
+| runAllAgentTests | POST /voice/agents/{agent_id}/test/run-all | write | AgentTestConsole |
+| listPresetVoices | GET /voice/voice-library/presets | read | AgentBuilder |

package/blocks/agents/block.json

@@ -0,0 +1,223 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "agents",
+  "title": "AI agents",
+  "summary": "Build and test AI agents (voice and chat): persona, voice, knowledge, skills, dry-run test console and live agent runs with approvals.",
+  "features": [
+    "agent list with create, edit, activate and delete",
+    "persona dials, voice choice and per-call-type instructions",
+    "agent documents (billable upload) and company knowledge search",
+    "attach, detach and write skills",
+    "dry-run test console with saved cases and an activation gate",
+    "run a skill live behind a confirmation",
+    "agent runs with polling, cancel and approvals"
+  ],
+  "dependsOn": [
+    "foundation"
+  ],
+  "operations": [
+    "attach_skills_to_agent_voice_agents__agent_id__skills_post",
+    "cancel_agent_run_agent_runs__run_id__cancel_post",
+    "create_agent_run_agent_runs_post",
+    "create_agent_test_case_voice_agents__agent_id__test_cases_post",
+    "create_skill_skills_post",
+    "create_voice_agent_voice_agents_post",
+    "decide_agent_approval_agent_approvals__approval_id__decide_post",
+    "delete_agent_document_voice_agent_documents__document_id__delete",
+    "delete_voice_agent_voice_agents__agent_id__delete",
+    "detach_skill_from_agent_voice_agents__agent_id__skills__action_id__delete",
+    "execute_skill_skills__action_id__execute_post",
+    "get_agent_run_agent_runs__run_id__get",
+    "get_agent_test_suite_status_voice_agents__agent_id__test_suite_status_get",
+    "get_voice_agent_voice_agents__agent_id__get",
+    "list_agent_approvals_agent_approvals_get",
+    "list_agent_documents_voice_agents__agent_id__documents_get",
+    "list_agent_runs_agent_runs_get",
+    "list_agent_skills_voice_agents__agent_id__skills_get",
+    "list_agent_specialists_agent_specialists_get",
+    "list_agent_test_cases_voice_agents__agent_id__test_cases_get",
+    "list_models_skills_models_get",
+    "list_preset_voices_voice_voice_library_presets_get",
+    "list_skills_skills_get",
+    "list_voice_agents_voice_agents_get",
+    "run_agent_test_voice_agents__agent_id__test_post",
+    "run_all_agent_tests_voice_agents__agent_id__test_run_all_post",
+    "search_knowledge_knowledge_search_get",
+    "update_voice_agent_voice_agents__agent_id__put",
+    "upload_agent_documents_voice_agents__agent_id__documents_upload_post"
+  ],
+  "components": [
+    {
+      "name": "AgentBuilder",
+      "file": "components/agent-builder.tsx",
+      "purpose": "List, create, edit and delete agents: persona, voice, instructions, active toggle, with the knowledge and skills panels as tabs.",
+      "operations": [
+        "list_voice_agents_voice_agents_get",
+        "get_voice_agent_voice_agents__agent_id__get",
+        "create_voice_agent_voice_agents_post",
+        "update_voice_agent_voice_agents__agent_id__put",
+        "delete_voice_agent_voice_agents__agent_id__delete",
+        "list_preset_voices_voice_voice_library_presets_get"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AgentKnowledgePanel",
+      "file": "components/agent-knowledge-panel.tsx",
+      "purpose": "An agent's own documents (billable upload, delete) plus company knowledge search and the use-company-knowledge switch.",
+      "operations": [
+        "update_voice_agent_voice_agents__agent_id__put",
+        "list_agent_documents_voice_agents__agent_id__documents_get",
+        "upload_agent_documents_voice_agents__agent_id__documents_upload_post",
+        "delete_agent_document_voice_agent_documents__document_id__delete",
+        "search_knowledge_knowledge_search_get"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AgentSkillsPanel",
+      "file": "components/agent-skills-panel.tsx",
+      "purpose": "Attach and detach skills for an agent, or write a new LLM skill in place.",
+      "operations": [
+        "list_agent_skills_voice_agents__agent_id__skills_get",
+        "list_skills_skills_get",
+        "attach_skills_to_agent_voice_agents__agent_id__skills_post",
+        "detach_skill_from_agent_voice_agents__agent_id__skills__action_id__delete",
+        "list_models_skills_models_get",
+        "create_skill_skills_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AgentTestConsole",
+      "file": "components/agent-test-console.tsx",
+      "purpose": "Free dry runs (ad-hoc or saved cases), regression sweep and activation gate; run an attached skill live behind an external confirmation.",
+      "operations": [
+        "list_agent_test_cases_voice_agents__agent_id__test_cases_get",
+        "get_agent_test_suite_status_voice_agents__agent_id__test_suite_status_get",
+        "run_agent_test_voice_agents__agent_id__test_post",
+        "create_agent_test_case_voice_agents__agent_id__test_cases_post",
+        "run_all_agent_tests_voice_agents__agent_id__test_run_all_post",
+        "list_agent_skills_voice_agents__agent_id__skills_get",
+        "execute_skill_skills__action_id__execute_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    },
+    {
+      "name": "AgentRuns",
+      "file": "components/agent-runs.tsx",
+      "purpose": "Start, follow (polled), cancel agent runs and approve or reject the actions a run stops on.",
+      "operations": [
+        "list_agent_runs_agent_runs_get",
+        "list_agent_specialists_agent_specialists_get",
+        "create_agent_run_agent_runs_post",
+        "get_agent_run_agent_runs__run_id__get",
+        "cancel_agent_run_agent_runs__run_id__cancel_post",
+        "list_agent_approvals_agent_approvals_get",
+        "decide_agent_approval_agent_approvals__approval_id__decide_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/agent-types.ts",
+      "purpose": "Response shapes (agent, persona, skill, run) and small readers for the enveloped and un-enveloped bodies voice and skills return."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-agent-and-attach-skill.ts",
+      "title": "Create an agent, give it a skill and knowledge",
+      "when": "Building an agent from code or a seed script instead of the AgentBuilder screen."
+    },
+    {
+      "file": "recipes/test-agent-before-activating.ts",
+      "title": "Save test cases, sweep, read the activation gate",
+      "when": "Before setting an agent active; dry runs are free."
+    },
+    {
+      "file": "recipes/run-and-follow-agent-run.ts",
+      "title": "Start an agent run, poll it, decide approvals",
+      "when": "Handing a goal to an agent and following it to the end."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "foundation-installed",
+      "description": "The foundation block is installed and the /api/g8 proxy allows the agent, skills, knowledge and voice prefixes.",
+      "where": "app",
+      "verify": "allowedPrefixes includes \"voice\", \"skills\", \"knowledge\" and \"agent\"."
+    },
+    {
+      "id": "api-key-scopes",
+      "description": "The API key carries the block's scopes (voice, knowledge, workflows).",
+      "where": "api",
+      "verify": "describeCurrentKey lists voice:read, voice:write, voice:delete, knowledge:read, workflows:read, workflows:write, workflows:run, workflows:delete."
+    },
+    {
+      "id": "company-knowledge",
+      "description": "Company knowledge exists in the workspace if agents should draw on it (optional).",
+      "where": "api",
+      "verify": "GET /knowledge/status returns concepts."
+    }
+  ],
+  "scopes": [
+    "knowledge:read",
+    "voice:delete",
+    "voice:read",
+    "voice:run",
+    "voice:write",
+    "workflows:delete",
+    "workflows:read",
+    "workflows:run",
+    "workflows:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Status of a new agent",
+      "default": "inactive until a dry run passes, then a person turns it active",
+      "askHuman": false
+    },
+    {
+      "decision": "Persona dials (formality, conciseness, assertiveness)",
+      "default": "0.5 each",
+      "askHuman": false
+    },
+    {
+      "decision": "Use company knowledge",
+      "default": "on",
+      "askHuman": false
+    },
+    {
+      "decision": "Who may approve agent actions and run skills live",
+      "default": "decided in the proxy's authorize hook; the screens always confirm first",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}