@graph8/sdk 0.362.0 → 0.373.0

package/blocks/_foundation/server/connect.ts

@@ -0,0 +1,127 @@
+/**
+ * Server side of the Connect graph8 screen (local preview only), mounted at `app/api/g8-connect/route.ts`:
+ *
+ *   GET    -> { localPreview: true, connected, source: "env" | "file" | null, keyHint, account }
+ *   POST   { key } -> validates the key with a cheap read (GET /api/v1/me) and stores it in .g8/local-key
+ *   DELETE -> removes the stored key
+ *
+ * It answers ONLY `next dev` requests from this machine (same check as the proxy's local preview). In a
+ * production build every method is 404, as if the route did not exist. The key is never echoed back: the
+ * answer carries only a hint (`...wxyz`) and the key's account (name, workspace, scopes) from /me.
+ * When G8_API_KEY is set in the environment it wins, so POST and DELETE refuse (409) and say where to change it.
+ */
+
+import { DEFAULT_API_URL, isLocalPreviewRequest } from "./proxy";
+import { currentKey, keyHint, removeLocalKey, writeLocalKey, LOCAL_KEY_FILE } from "./local-key";
+
+export interface G8ConnectConfig {
+  /** Replace `fetch` (tests). */
+  fetch?: typeof fetch;
+  /** Project root holding `.g8/` (tests). Default: process.cwd(). */
+  root?: string;
+}
+
+export interface ConnectedAccount {
+  name?: string;
+  workspace?: string;
+  scopes?: string[];
+}
+
+function json(status: number, body: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", "cache-control": "no-store" } });
+}
+
+const str = (v: unknown): string | undefined => (typeof v === "string" && v ? v : undefined);
+
+/** The safe, human facts about a key from GET /me (never the key itself). */
+export function accountFromMe(body: unknown): ConnectedAccount {
+  const root = (body ?? {}) as Record<string, unknown>;
+  const d = ((root.data as Record<string, unknown> | undefined) ?? root) as Record<string, unknown>;
+  const org = d.organization as Record<string, unknown> | undefined;
+  const scopes = Array.isArray(d.scopes) ? d.scopes.filter((s): s is string => typeof s === "string") : undefined;
+  return { name: str(d.name) ?? str(d.key_name) ?? str(d.label), workspace: str(org?.name) ?? str(d.org_name) ?? str(d.organization_name), scopes };
+}
+
+/** A pasted key that is plausibly a key: printable, no spaces, 8 to 512 characters. */
+export function plausibleKey(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const key = value.trim();
+  return key.length >= 8 && key.length <= 512 && /^[\x21-\x7e]+$/.test(key) ? key : null;
+}
+
+type Checked = { ok: true; account: ConnectedAccount } | { ok: false; status: number; error: string; message: string };
+
+/** Ask graph8 who the key is: GET /api/v1/me (free, read-only). */
+export async function checkKey(key: string, doFetch: typeof fetch): Promise<Checked> {
+  const base = (process.env.G8_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, "");
+  let res: Response;
+  try {
+    res = await doFetch(`${base}/api/v1/me`, { headers: { authorization: `Bearer ${key}`, accept: "application/json" }, cache: "no-store", redirect: "manual" });
+  } catch {
+    return { ok: false, status: 502, error: "upstream_unreachable", message: "Could not reach the graph8 API to check the key." };
+  }
+  const body = await res.json().catch(() => ({}));
+  if (res.ok) return { ok: true, account: accountFromMe(body) };
+  if (res.status === 401 || res.status === 403) {
+    return { ok: false, status: 400, error: "key_rejected", message: "graph8 did not accept this key. Copy it again from graph8 (Settings > Developers > API keys)." };
+  }
+  return { ok: false, status: 502, error: "upstream_error", message: `graph8 answered HTTP ${res.status} while checking the key. Try again.` };
+}
+
+/** Build the GET/POST/DELETE handlers for `app/api/g8-connect/route.ts`. */
+export function createG8ConnectRoute(config: G8ConnectConfig = {}) {
+  const doFetch = (): typeof fetch => config.fetch ?? globalThis.fetch;
+
+  function refuse(request: Request): Response | null {
+    if (process.env.NODE_ENV === "production") return json(404, { error: "not_found" });
+    if (!isLocalPreviewRequest(request)) {
+      return json(403, { error: "local_preview_only", message: "The Connect graph8 screen only works from this machine (http://localhost)." });
+    }
+    return null;
+  }
+
+  async function status(): Promise<Record<string, unknown>> {
+    const current = await currentKey(config.root);
+    if (!current) return { localPreview: true, connected: false, source: null, keyFile: LOCAL_KEY_FILE };
+    const checked = await checkKey(current.key, doFetch());
+    return {
+      localPreview: true,
+      connected: checked.ok,
+      source: current.source,
+      keyHint: keyHint(current.key),
+      keyFile: LOCAL_KEY_FILE,
+      ...(checked.ok ? { account: checked.account } : { problem: checked.message }),
+    };
+  }
+
+  async function GET(request: Request): Promise<Response> {
+    return refuse(request) ?? json(200, await status());
+  }
+
+  async function POST(request: Request): Promise<Response> {
+    const refused = refuse(request);
+    if (refused) return refused;
+    if ((await currentKey(config.root))?.source === "env") {
+      return json(409, { error: "key_in_environment", message: "G8_API_KEY is set in the server environment (.env.local), and it wins. Change it there, then restart `npm run dev`." });
+    }
+    const body = (await request.json().catch(() => ({}))) as { key?: unknown };
+    const key = plausibleKey(body.key);
+    if (!key) return json(400, { error: "invalid_key", message: "Paste a graph8 API key: one line, no spaces." });
+    const checked = await checkKey(key, doFetch());
+    if (!checked.ok) return json(checked.status, { error: checked.error, message: checked.message });
+    await writeLocalKey(key, config.root);
+    return json(200, { localPreview: true, connected: true, source: "file", keyHint: keyHint(key), keyFile: LOCAL_KEY_FILE, account: checked.account });
+  }
+
+  async function DELETE(request: Request): Promise<Response> {
+    const refused = refuse(request);
+    if (refused) return refused;
+    if ((await currentKey(config.root))?.source === "env") {
+      return json(409, { error: "key_in_environment", message: "G8_API_KEY is set in the server environment (.env.local). Remove it there, then restart `npm run dev`." });
+    }
+    await removeLocalKey(config.root);
+    return json(200, { localPreview: true, connected: false, source: null, keyFile: LOCAL_KEY_FILE });
+  }
+
+  return { GET, POST, DELETE };
+}

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,27 @@ 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.
+- **Approvals tab**: everything agents ask permission for: the oversight summary, pending approvals (approve, reject, **request changes** with feedback) and the decided history with each approval's signed receipts.
+- **Skill library tab**: every skill (yours plus graph8's), search, filter by kind and state, open one to edit it (**SkillEditor**: loaded first, only the changed fields are saved, placeholders, template check, enable/disable, delete), write a new LLM or API skill, or start from a template.
+- **Company knowledge tab**: the entries agents draw on. Status strip, meaning-based search or browse by type and lifecycle, open an entry (content, history, sources, related), **New entry**, edit a draft, propose a new version of a published one, verify, deprecate; **Export** downloads everything.
+- **Operators tab**: the autonomous monitors in your workspace: turn each on or off, set the trust dial per skill (off, detect, propose, auto), read findings, activity, health and scorecard.
+- **Assistant tab**: your sessions with the graph8 assistant (list, open, rename, pin, delete, add a note) and **Ask** for one live turn; if the assistant starts a run, open it from here.
+- An open agent also has **Conversations** (its chat history, rename, hand over to a human, delete, and a message box), **Activity** (calls, skill runs, chats, skill performance over 7, 30 or 90 days) and **Test history** (saved cases: edit, delete; every run). Its header has **Duplicate** and **Save as template**; the screen header has **From a template** and **Receptionist**.
+- Lists never stop silently: agents load 100 at a time with "Load more"; conversations, sessions, runs and knowledge say when the API's own maximum is reached.
+- Uploading documents, running a skill, starting or cancelling a run, approving, sending a chat message or an assistant turn, turning an operator or its trust dial up, switching the receptionist, and deleting anything are confirmed
+  with `ConfirmSpendDialog` inside the parts. Needs `voice:read|write|delete|run`, `knowledge:read|write`, `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
@@ -15,6 +36,16 @@ Install: `npx @graph8/sdk add agents` (installs `foundation` first).
 | `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` |
+| `AgentRunDetail` | One run in full, its approvals, cancel, and **steer** it with an instruction while it is live | `runId`, `pollMs`, `onChanged` |
+| `AgentActivity` | An agent's calls, skill runs, workflow runs, chats and skill performance | `agentId` |
+| `AgentConversations` | An agent's chat history: open, rename, hand over to a human, delete, message it (billable) | `agentId`, `contactId` |
+| `AgentTestHistory` | Saved test cases (edit, delete) and every run | `agentId` |
+| `DuplicateAgentButton`, `SaveAsTemplateButton`, `FromTemplateButton`, `ReceptionistButton` | Copy an agent, keep it as a template, start from a template, set up the receptionist | `agent`, `onDuplicated` / `onCreated` |
+| `SkillLibrary`, `SkillEditor` | Every skill in one list, and create / edit / delete one | `target`, `onClose`, `onChanged` |
+| `KnowledgeBrowser`, `KnowledgeDetail`, `KnowledgeForm` | Company knowledge: browse, search, read, author, amend, verify, deprecate | `conceptId`, `mode`, `onChanged` |
+| `AgentApprovals` | The approvals inbox with history and receipts | `onOpenRun` |
+| `AgentOperators` | Autonomous operators: on/off, trust dials, findings, activity, health, scorecard | none |
+| `AssistantSessions` | Sessions with the graph8 assistant | `onOpenRun` |
 
 ## The flow, with the ids that pass between steps
 
@@ -25,7 +56,7 @@ Install: `npx @graph8/sdk add agents` (installs `foundation` first).
 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
+4. **Skills**: `POST /skills { name, runtime_type: "llm", llm_config: { model, prompt_template } }` (voice requires `prompt_template`) 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,
@@ -63,13 +94,15 @@ export function AgentStudio() {
   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).
+- Sending a chat message to an agent and asking the assistant are `billable` (they run a model and may run skills or start a job). Turning an operator on and raising a trust dial are `billable` (they start work that proceeds on its own).
+- Duplicating, saving a template, renaming, editing a skill or a test case, writing knowledge and verifying are writes (free). Deprecating a knowledge entry, deleting a skill, a conversation, a session or a test case are `destructive`. Switching the receptionist on or off and approving are confirmed as `external`.
 - 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`.
+- `api-key-scopes` (api): `voice:read|write|delete|run`, `knowledge:read|write`, `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.
 
@@ -87,6 +120,8 @@ Ask the person: who may approve agent actions and run skills live (decide it in
 
 - 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.
+- Not offered on purpose: live voice sessions (they need a WebSocket), the first-run onboarding discovery wizard, the operating model and operator recipients (organisation policy), agent global settings (an open body with no schema), twins (a multipart upload plus LinkedIn lookups, a product decision), and deciding an operator's proposed fix (it changes your data; do it in graph8).
+- Knowledge entries that graph8 generates from your records are read only; only authored entries can be edited, amended, verified or deprecated.
 - 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.
 
@@ -131,3 +166,59 @@ Ask the person: who may approve agent actions and run skills live (decide it in
 | 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 |
+| cloneAgent | POST /voice/agents/clone | write | DuplicateAgentButton, FromTemplateButton |
+| createAgentSession | POST /agent/sessions | write | AssistantSessions |
+| createAuthoredKnowledge | POST /knowledge/authored | write | KnowledgeForm |
+| createAuthoredKnowledgeAmendment | POST /knowledge/authored/{concept_id}/amendments | write | KnowledgeForm |
+| createFromTemplate | POST /skills/from-template | write | SkillLibrary |
+| deleteAgentSession | DELETE /agent/sessions/{session_id} | destructive | AssistantSessions |
+| deleteAgentTestCase | DELETE /voice/agents/{agent_id}/test-cases/{test_case_id} | destructive | AgentTestHistory |
+| deleteChatAgentConversation | DELETE /voice/chat-agent/conversations/{chat_id} | destructive | AgentConversations |
+| deleteSkill | DELETE /skills/{action_id} | destructive | SkillEditor |
+| deprecateAuthoredKnowledge | POST /knowledge/authored/{concept_id}/deprecate | write | KnowledgeDetail |
+| ensureReceptionistAgent | POST /voice/agents/receptionist | write | ReceptionistButton |
+| exportKnowledge | GET /knowledge/export | read | KnowledgeBrowser |
+| extractVariables | GET /skills/{action_id}/variables | read | SkillEditor |
+| getAgentActivity | GET /voice/agents/{agent_id}/activity | read | AgentActivity |
+| getAgentApprovalReceipts | GET /agent/approvals/{approval_id}/receipts | read | AgentApprovals |
+| getAgentOperatorsSummary | GET /agent/operators/summary | read | AgentOperators |
+| getAgentOversight | GET /agent/oversight | read | AgentApprovals |
+| getAgentSessionState | GET /agent/sessions/{session_id}/state | read | AssistantSessions |
+| getAgentSkillStats | GET /voice/agents/{agent_id}/skill-stats | read | AgentActivity |
+| getChatAgentHistory | POST /voice/chat-agent/history | read | AgentConversations |
+| getKnowledge | GET /knowledge/{concept_id} | read | KnowledgeDetail |
+| getKnowledgeHistory | GET /knowledge/{concept_id}/history | read | KnowledgeDetail |
+| getKnowledgeStatus | GET /knowledge/status | read | KnowledgeBrowser |
+| getSkill | GET /skills/{action_id} | read | SkillEditor |
+| knowledgeSources | GET /knowledge/{concept_id}/sources | read | KnowledgeDetail |
+| listAgentApprovalHistory | GET /agent/approvals/history | read | AgentApprovals |
+| listAgentOperatorActivity | GET /agent/operators/{operator}/activity | read | AgentOperators |
+| listAgentOperatorFindings | GET /agent/operators/{operator}/findings | read | AgentOperators |
+| listAgentOperatorSkills | GET /agent/operators/{operator}/skills | read | AgentOperators |
+| listAgentOperators | GET /agent/operators | read | AgentOperators |
+| listAgentSessions | GET /agent/sessions | read | AssistantSessions |
+| listAgentTemplates | GET /voice/agent-templates | read | FromTemplateButton |
+| listAgentTestRuns | GET /voice/agents/{agent_id}/test-runs | read | AgentTestHistory |
+| listChatAgentConversations | POST /voice/chat-agent/conversations | read | AgentConversations |
+| listKnowledge | GET /knowledge | read | KnowledgeBrowser |
+| listTemplates | GET /skills/templates | read | SkillLibrary |
+| markAgentSessionRead | PUT /agent/sessions/{session_id}/read | write | AssistantSessions |
+| pinAgentSession | POST /agent/sessions/{session_id}/pin | write | AssistantSessions |
+| postAgentChat | POST /agent/chat | billable | AssistantSessions |
+| postAgentSessionMessage | POST /agent/sessions/{session_id}/messages | write | AssistantSessions |
+| relatedKnowledge | GET /knowledge/{concept_id}/related | read | KnowledgeDetail |
+| renameAgentSession | POST /agent/sessions/{session_id}/rename | write | AssistantSessions |
+| renameChatAgentConversation | PUT /voice/chat-agent/conversations/{chat_id}/name | write | AgentConversations |
+| requestAgentApprovalChanges | POST /agent/approvals/{approval_id}/request-changes | write | AgentApprovals |
+| saveAgentAsTemplate | POST /voice/agents/{agent_id}/save-as-template | write | SaveAsTemplateButton |
+| sendChatAgentMessage | POST /voice/chat-agent/messages | billable | AgentConversations |
+| setAgentOperatorEnabled | PUT /agent/operators/{operator}/enabled | billable | AgentOperators |
+| setAgentOperatorTrustDial | PUT /agent/operators/{operator}/skills/{skill_key} | billable | AgentOperators |
+| steerAgentWorkItem | POST /agent/work-items/{work_item_id}/steer | write | AgentRunDetail |
+| toggleReceptionistAgent | PATCH /voice/agents/receptionist | write | ReceptionistButton |
+| transferChatAgentConversation | POST /voice/chat-agent/conversations/{chat_id}/transfer-to-human | write | AgentConversations |
+| updateAgentTestCase | PUT /voice/agents/{agent_id}/test-cases/{test_case_id} | write | AgentTestHistory |
+| updateAuthoredKnowledgeDraft | PATCH /knowledge/authored/{concept_id} | write | KnowledgeForm |
+| updateSkill | PUT /skills/{action_id} | write | SkillEditor |
+| validateTemplate | POST /skills/validate | write | SkillEditor |
+| verifyAuthoredKnowledge | POST /knowledge/authored/{concept_id}/verify | write | KnowledgeDetail |