@graph8/sdk 0.370.0 → 0.373.0

package/blocks/_foundation/hooks/use-url-filters.ts

@@ -0,0 +1,93 @@
+"use client";
+
+/**
+ * useUrlFilters: the filter state of a list screen, kept in the URL so a filtered view survives reload, Back and sharing.
+ *
+ *   const f = useUrlFilters(["email", "city"] as const, { prefix: "c_" });
+ *   <input value={f.draft.email} onChange={(e) => f.set("email", e.target.value)} />
+ *   g8Get("/contacts", { page, ...f.query });      // f.query holds only the filters that are set, debounced
+ *
+ * Typing is local (`draft`, instant); the debounced `filters` are what the list reads, and they are written to the URL as
+ * `<prefix><key>=...`. A URL that already carries filters is the starting value, with no flash of an unfiltered list and
+ * no wipe at mount. It is read through `useSyncExternalStore` (like useUrlState), so it is hydration-safe: the server and
+ * the first hydration render both see empty filters, React then re-renders with the URL's. In that first hydration render
+ * `ready` is false: hold the list read until it is true (`enabled: filters.ready`), so no unfiltered read goes out. On a
+ * client-only render `ready` is true from the start. `clear()` empties everything. Params of other hooks (id, view, tab)
+ * are never touched.
+ *
+ * SDK operations: none.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { readUrlParam, writeUrlParam } from "./use-url-state";
+
+export interface UseUrlFiltersOptions {
+  /** URL param prefix, so two screens on one page do not share names. Default "". */
+  prefix?: string;
+  /** Milliseconds of quiet typing before the list reads the new filters. Default 300. */
+  debounceMs?: number;
+}
+
+export interface UseUrlFilters<K extends string> {
+  /** What the inputs show (instant). */
+  draft: Record<K, string>;
+  /** What the list reads (debounced after an edit). */
+  filters: Record<K, string>;
+  /** Only the filters that are set, ready to spread into a query. */
+  query: Partial<Record<K, string>>;
+  set: (key: K, value: string) => void;
+  clear: () => void;
+  /** Some filter is set (draft). */
+  active: boolean;
+  /** How many of `keys` are set (draft). */
+  count: number;
+  /** The URL's filters have been read (false only in the first hydration render): hold the list read until true. */
+  ready: boolean;
+}
+
+const noSubscribe = (): (() => void) => () => {};
+
+export function useUrlFilters<K extends string>(keys: readonly K[], options: UseUrlFiltersOptions = {}): UseUrlFilters<K> {
+  const prefix = options.prefix ?? "";
+  const ms = options.debounceMs ?? 300;
+  const sig = keys.join(",");
+  const empty = useCallback((): Record<K, string> => Object.fromEntries(keys.map((k) => [k, ""])) as Record<K, string>, [sig]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // The URL's filters as one string, frozen at the first client read. The server (and the first hydration render) sees "".
+  const frozen = useRef<string | null>(null);
+  const urlSnap = useSyncExternalStore(
+    noSubscribe,
+    () => (frozen.current ??= JSON.stringify(keys.map((k) => readUrlParam(prefix + k) ?? ""))),
+    () => JSON.stringify(keys.map(() => "")),
+  );
+  const ready = useSyncExternalStore(noSubscribe, () => true, () => false);
+  const fromUrl = useMemo(() => {
+    const values = JSON.parse(urlSnap) as string[];
+    return Object.fromEntries(keys.map((k, i) => [k, values[i] ?? ""])) as Record<K, string>;
+  }, [urlSnap, sig]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // `edited` is null until the person types: until then the filters ARE the URL's (no debounce lag, nothing to write back).
+  const [edited, setEdited] = useState<Record<K, string> | null>(null);
+  const [settled, setSettled] = useState<Record<K, string> | null>(null);
+  const draft = edited ?? fromUrl;
+  const filters = settled ?? fromUrl;
+  const latest = useRef(draft);
+  latest.current = draft;
+
+  useEffect(() => {
+    if (edited === null) return;
+    const t = setTimeout(() => setSettled(edited), ms);
+    return () => clearTimeout(t);
+  }, [edited, ms]);
+
+  // The settled filters are the URL's value; writeUrlParam skips an unchanged value, so mounting writes nothing.
+  useEffect(() => {
+    if (!ready) return;
+    for (const k of keys) writeUrlParam(prefix + k, filters[k] || null);
+  }, [ready, filters]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const set = useCallback((key: K, value: string) => setEdited({ ...latest.current, [key]: value }), []);
+  const clear = useCallback(() => setEdited(empty()), [empty]);
+  const query = Object.fromEntries(keys.filter((k) => filters[k]).map((k) => [k, filters[k]])) as Partial<Record<K, string>>;
+  const count = keys.filter((k) => draft[k]).length;
+  return { draft, filters, query, set, clear, active: count > 0, count, ready };
+}

package/blocks/_foundation/lib/paging.ts

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * Paging helpers: adapt the API's several paging dialects (`page`, `offset`, `cursor`) to the one shape
+ * `usePaginated` loads ("load more" appends the next page). No operation is called here; the caller's component
+ * performs and declares the read.
+ *
+ *   const list = usePaginated(byOffset(PAGE, async (offset, signal) => {
+ *     const env = await g8Get("/landing-pages", { limit: PAGE, offset }, { signal });
+ *     return { rows: listOf(env.data), hasNext: hasNextOf(env, PAGE) };
+ *   }), [status]);
+ */
+import type { PaginatedResponse } from "@graph8/sdk";
+
+/** One page of rows and whether another follows (omit `hasNext` and a full page is taken to mean "maybe more"). */
+export interface RowsPage<T> {
+  rows: T[];
+  hasNext?: boolean;
+}
+
+type Fetcher<T> = (cursor: string | undefined, signal: AbortSignal) => Promise<PaginatedResponse<T>>;
+
+/**
+ * `trustHasNext`: when the page says `hasNext: true` believe it even if it carries no rows (a page-number list whose rows
+ * were filtered client-side can be empty while the server still has more). Offset lists cannot: an empty page does not
+ * advance the offset, so they stop on an empty page.
+ */
+function toResponse<T>(page: RowsPage<T>, size: number, next: number, trustHasNext = false): PaginatedResponse<T> {
+  const more = page.hasNext ?? page.rows.length >= size;
+  const go = more && (page.rows.length > 0 || (trustHasNext && page.hasNext === true));
+  return { data: page.rows, pagination: { next_cursor: go ? String(next) : null } } as unknown as PaginatedResponse<T>;
+}
+
+/** `?page=N` lists: the cursor carries the next page number. */
+export function byPage<T>(size: number, read: (page: number, signal: AbortSignal) => Promise<RowsPage<T>>): Fetcher<T> {
+  return async (cursor, signal) => {
+    const page = cursor ? Number(cursor) || 1 : 1;
+    return toResponse(await read(page, signal), size, page + 1, true);
+  };
+}
+
+/** `?offset=N` (or skip) lists: the cursor carries the next offset. */
+export function byOffset<T>(size: number, read: (offset: number, signal: AbortSignal) => Promise<RowsPage<T>>): Fetcher<T> {
+  return async (cursor, signal) => {
+    const offset = cursor ? Number(cursor) || 0 : 0;
+    const page = await read(offset, signal);
+    return toResponse(page, size, offset + page.rows.length);
+  };
+}
+
+/** Whether an API envelope says another page follows: `pagination.has_next`, then `next_cursor`, then a full page. */
+export function hasNextOf(env: unknown, size: number, rows?: number): boolean | undefined {
+  const p = (env as { pagination?: { has_next?: boolean; next_cursor?: string | null; total?: number; page?: number } } | null)?.pagination;
+  if (typeof p?.has_next === "boolean") return p.has_next;
+  if (p && "next_cursor" in p && p.next_cursor !== undefined) return Boolean(p.next_cursor);
+  return rows === undefined ? undefined : rows >= size;
+}

package/blocks/_foundation/lib/use-debounced-value.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** `value`, but only after it has stopped changing for `ms` (foundation-local: the pickers block has its own copy). */
+export function useDebounced<T>(value: T, ms = 250): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}

package/blocks/agents/README.md

@@ -13,8 +13,15 @@ to it, and follow the runs agents do for you.
   **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:*`.
+- **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`.
 
@@ -29,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
 
@@ -39,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,
@@ -77,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.
 
@@ -101,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.
 
@@ -145,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 |