@graph8/sdk 0.370.0 → 0.374.0

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 |

package/blocks/agents/block.json

@@ -18,33 +18,89 @@
   "operations": [
     "attach_skills_to_agent_voice_agents__agent_id__skills_post",
     "cancel_agent_run_agent_runs__run_id__cancel_post",
+    "clone_agent_voice_agents_clone_post",
     "create_agent_run_agent_runs_post",
+    "create_agent_session_agent_sessions_post",
     "create_agent_test_case_voice_agents__agent_id__test_cases_post",
+    "create_authored_knowledge_amendment_knowledge_authored__concept_id__amendments_post",
+    "create_authored_knowledge_knowledge_authored_post",
+    "create_from_template_skills_from_template_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_agent_session_agent_sessions__session_id__delete",
+    "delete_agent_test_case_voice_agents__agent_id__test_cases__test_case_id__delete",
+    "delete_chat_agent_conversation_voice_chat_agent_conversations__chat_id__delete",
+    "delete_skill_skills__action_id__delete",
     "delete_voice_agent_voice_agents__agent_id__delete",
+    "deprecate_authored_knowledge_knowledge_authored__concept_id__deprecate_post",
     "detach_skill_from_agent_voice_agents__agent_id__skills__action_id__delete",
+    "ensure_receptionist_agent_voice_agents_receptionist_post",
     "execute_skill_skills__action_id__execute_post",
+    "export_knowledge_knowledge_export_get",
+    "extract_variables_skills__action_id__variables_get",
+    "get_agent_activity_voice_agents__agent_id__activity_get",
+    "get_agent_approval_receipts_agent_approvals__approval_id__receipts_get",
+    "get_agent_operators_summary_agent_operators_summary_get",
+    "get_agent_oversight_agent_oversight_get",
     "get_agent_run_agent_runs__run_id__get",
+    "get_agent_session_state_agent_sessions__session_id__state_get",
+    "get_agent_skill_stats_voice_agents__agent_id__skill_stats_get",
     "get_agent_test_suite_status_voice_agents__agent_id__test_suite_status_get",
+    "get_chat_agent_history_voice_chat_agent_history_post",
+    "get_knowledge_history_knowledge__concept_id__history_get",
+    "get_knowledge_knowledge__concept_id__get",
+    "get_knowledge_status_knowledge_status_get",
+    "get_skill_skills__action_id__get",
     "get_voice_agent_voice_agents__agent_id__get",
+    "knowledge_sources_knowledge__concept_id__sources_get",
+    "list_agent_approval_history_agent_approvals_history_get",
     "list_agent_approvals_agent_approvals_get",
     "list_agent_documents_voice_agents__agent_id__documents_get",
+    "list_agent_operator_activity_agent_operators__operator__activity_get",
+    "list_agent_operator_findings_agent_operators__operator__findings_get",
+    "list_agent_operator_skills_agent_operators__operator__skills_get",
+    "list_agent_operators_agent_operators_get",
     "list_agent_runs_agent_runs_get",
+    "list_agent_sessions_agent_sessions_get",
     "list_agent_skills_voice_agents__agent_id__skills_get",
     "list_agent_specialists_agent_specialists_get",
+    "list_agent_templates_voice_agent_templates_get",
     "list_agent_test_cases_voice_agents__agent_id__test_cases_get",
+    "list_agent_test_runs_voice_agents__agent_id__test_runs_get",
+    "list_chat_agent_conversations_voice_chat_agent_conversations_post",
+    "list_knowledge_knowledge_get",
     "list_models_skills_models_get",
     "list_preset_voices_voice_voice_library_presets_get",
     "list_skills_skills_get",
+    "list_templates_skills_templates_get",
     "list_voice_agents_voice_agents_get",
+    "mark_agent_session_read_agent_sessions__session_id__read_put",
+    "pin_agent_session_agent_sessions__session_id__pin_post",
+    "post_agent_chat_agent_chat_post",
+    "post_agent_session_message_agent_sessions__session_id__messages_post",
+    "related_knowledge_knowledge__concept_id__related_get",
+    "rename_agent_session_agent_sessions__session_id__rename_post",
+    "rename_chat_agent_conversation_voice_chat_agent_conversations__chat_id__name_put",
+    "request_agent_approval_changes_agent_approvals__approval_id__request_changes_post",
     "run_agent_test_voice_agents__agent_id__test_post",
     "run_all_agent_tests_voice_agents__agent_id__test_run_all_post",
+    "save_agent_as_template_voice_agents__agent_id__save_as_template_post",
     "search_knowledge_knowledge_search_get",
+    "send_chat_agent_message_voice_chat_agent_messages_post",
+    "set_agent_operator_enabled_agent_operators__operator__enabled_put",
+    "set_agent_operator_trust_dial_agent_operators__operator__skills__skill_key__put",
+    "steer_agent_work_item_agent_work_items__work_item_id__steer_post",
+    "toggle_receptionist_agent_voice_agents_receptionist_patch",
+    "transfer_chat_agent_conversation_voice_chat_agent_conversations__chat_id__transfer_to_human_post",
+    "update_agent_test_case_voice_agents__agent_id__test_cases__test_case_id__put",
+    "update_authored_knowledge_draft_knowledge_authored__concept_id__patch",
+    "update_skill_skills__action_id__put",
     "update_voice_agent_voice_agents__agent_id__put",
-    "upload_agent_documents_voice_agents__agent_id__documents_upload_post"
+    "upload_agent_documents_voice_agents__agent_id__documents_upload_post",
+    "validate_template_skills_validate_post",
+    "verify_authored_knowledge_knowledge_authored__concept_id__verify_post"
   ],
   "components": [
     {
@@ -70,7 +126,8 @@
         "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"
+        "cancel_agent_run_agent_runs__run_id__cancel_post",
+        "steer_agent_work_item_agent_work_items__work_item_id__steer_post"
       ],
       "tiers": [
         "read",
@@ -169,6 +226,241 @@
         "write",
         "destructive"
       ]
+    },
+    {
+      "name": "AgentActivity",
+      "file": "components/agent-activity.tsx",
+      "purpose": "An agent's recent calls, skill runs, workflow runs and chats over 7, 30 or 90 days, with how its skills performed.",
+      "operations": [
+        "get_agent_activity_voice_agents__agent_id__activity_get",
+        "get_agent_skill_stats_voice_agents__agent_id__skill_stats_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "AgentConversations",
+      "file": "components/agent-conversations.tsx",
+      "purpose": "An agent's chat history: conversations, their messages, rename, hand over to a human, delete, and a message box (billable, confirmed).",
+      "operations": [
+        "get_chat_agent_history_voice_chat_agent_history_post",
+        "list_chat_agent_conversations_voice_chat_agent_conversations_post",
+        "rename_chat_agent_conversation_voice_chat_agent_conversations__chat_id__name_put",
+        "transfer_chat_agent_conversation_voice_chat_agent_conversations__chat_id__transfer_to_human_post",
+        "delete_chat_agent_conversation_voice_chat_agent_conversations__chat_id__delete",
+        "send_chat_agent_message_voice_chat_agent_messages_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AgentTestHistory",
+      "file": "components/agent-test-history.tsx",
+      "purpose": "Saved test cases (edit, delete) and every test run of one agent.",
+      "operations": [
+        "update_agent_test_case_voice_agents__agent_id__test_cases__test_case_id__put",
+        "list_agent_test_cases_voice_agents__agent_id__test_cases_get",
+        "list_agent_test_runs_voice_agents__agent_id__test_runs_get",
+        "delete_agent_test_case_voice_agents__agent_id__test_cases__test_case_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "NameDialog",
+      "file": "components/name-dialog.tsx",
+      "purpose": "A small dialog that asks for one name; used by the duplicate and save-as-template buttons.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "DuplicateAgentButton",
+      "file": "components/duplicate-agent-button.tsx",
+      "purpose": "Copy an agent under a new name (retry-safe).",
+      "operations": [
+        "clone_agent_voice_agents_clone_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "SaveAsTemplateButton",
+      "file": "components/save-as-template-button.tsx",
+      "purpose": "Keep an agent as a reusable workspace template.",
+      "operations": [
+        "save_agent_as_template_voice_agents__agent_id__save_as_template_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "FromTemplateButton",
+      "file": "components/from-template-button.tsx",
+      "purpose": "Start a new agent from a graph8 or workspace template.",
+      "operations": [
+        "list_agent_templates_voice_agent_templates_get",
+        "clone_agent_voice_agents_clone_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "ReceptionistButton",
+      "file": "components/receptionist-button.tsx",
+      "purpose": "Set up the workspace receptionist and switch it on or off (confirmed).",
+      "operations": [
+        "ensure_receptionist_agent_voice_agents_receptionist_post",
+        "toggle_receptionist_agent_voice_agents_receptionist_patch"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "SkillLibrary",
+      "file": "components/skill-library.tsx",
+      "purpose": "Every skill in one list: search, filter by kind and state, open to edit, write a new LLM or API skill, or start from a template.",
+      "operations": [
+        "list_templates_skills_templates_get",
+        "create_from_template_skills_from_template_post",
+        "list_skills_skills_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SkillEditor",
+      "file": "components/skill-editor.tsx",
+      "purpose": "Create or edit one skill in a side sheet: loaded first, only changed fields saved, placeholders, template check, enable/disable, delete (confirmed).",
+      "operations": [
+        "get_skill_skills__action_id__get",
+        "extract_variables_skills__action_id__variables_get",
+        "list_models_skills_models_get",
+        "create_skill_skills_post",
+        "update_skill_skills__action_id__put",
+        "delete_skill_skills__action_id__delete",
+        "validate_template_skills_validate_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "KnowledgeBrowser",
+      "file": "components/knowledge-browser.tsx",
+      "purpose": "Company knowledge agents draw on: status, search or browse by type and lifecycle, open an entry, write a new one, export.",
+      "operations": [
+        "get_knowledge_status_knowledge_status_get",
+        "list_knowledge_knowledge_get",
+        "search_knowledge_knowledge_search_get",
+        "export_knowledge_knowledge_export_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "KnowledgeDetail",
+      "file": "components/knowledge-detail.tsx",
+      "purpose": "One knowledge entry: content, history, sources, related; edit a draft, propose a new version, verify, deprecate (confirmed).",
+      "operations": [
+        "get_knowledge_history_knowledge__concept_id__history_get",
+        "get_knowledge_knowledge__concept_id__get",
+        "knowledge_sources_knowledge__concept_id__sources_get",
+        "related_knowledge_knowledge__concept_id__related_get",
+        "verify_authored_knowledge_knowledge_authored__concept_id__verify_post",
+        "deprecate_authored_knowledge_knowledge_authored__concept_id__deprecate_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "KnowledgeForm",
+      "file": "components/knowledge-form.tsx",
+      "purpose": "Write a knowledge entry in a side sheet: new, edit a draft, or propose an amendment.",
+      "operations": [
+        "create_authored_knowledge_knowledge_authored_post",
+        "update_authored_knowledge_draft_knowledge_authored__concept_id__patch",
+        "create_authored_knowledge_amendment_knowledge_authored__concept_id__amendments_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "AgentApprovals",
+      "file": "components/agent-approvals.tsx",
+      "purpose": "The approvals inbox: oversight, pending approvals (approve, reject, request changes) and decided history with receipts.",
+      "operations": [
+        "get_agent_approval_receipts_agent_approvals__approval_id__receipts_get",
+        "get_agent_oversight_agent_oversight_get",
+        "list_agent_approvals_agent_approvals_get",
+        "list_agent_approval_history_agent_approvals_history_get",
+        "decide_agent_approval_agent_approvals__approval_id__decide_post",
+        "request_agent_approval_changes_agent_approvals__approval_id__request_changes_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "AgentOperators",
+      "file": "components/agent-operators.tsx",
+      "purpose": "Autonomous operators: summary, turn each on or off, trust dials per skill, findings, activity, health and scorecard (billable actions confirmed).",
+      "operations": [
+        "list_agent_operator_skills_agent_operators__operator__skills_get",
+        "list_agent_operator_activity_agent_operators__operator__activity_get",
+        "list_agent_operator_findings_agent_operators__operator__findings_get",
+        "get_agent_operators_summary_agent_operators_summary_get",
+        "list_agent_operators_agent_operators_get",
+        "set_agent_operator_enabled_agent_operators__operator__enabled_put",
+        "set_agent_operator_trust_dial_agent_operators__operator__skills__skill_key__put"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "AssistantSessions",
+      "file": "components/assistant-sessions.tsx",
+      "purpose": "Sessions with the graph8 assistant: list, open, rename, pin, delete, add a note, and ask a live turn (billable, confirmed).",
+      "operations": [
+        "get_agent_session_state_agent_sessions__session_id__state_get",
+        "mark_agent_session_read_agent_sessions__session_id__read_put",
+        "list_agent_sessions_agent_sessions_get",
+        "create_agent_session_agent_sessions_post",
+        "rename_agent_session_agent_sessions__session_id__rename_post",
+        "pin_agent_session_agent_sessions__session_id__pin_post",
+        "delete_agent_session_agent_sessions__session_id__delete",
+        "post_agent_session_message_agent_sessions__session_id__messages_post",
+        "post_agent_chat_agent_chat_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
     }
   ],
   "hooks": [],
@@ -176,6 +468,22 @@
     {
       "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."
+    },
+    {
+      "file": "lib/load-more.tsx",
+      "purpose": "Paging helpers (useLoadMoreList, useGrowingList, LoadMore) so no list stops silently at a cap."
+    },
+    {
+      "file": "lib/skill-utils.ts",
+      "purpose": "Skill shapes, form drafts and the changed-fields-only update body."
+    },
+    {
+      "file": "lib/knowledge-utils.ts",
+      "purpose": "Knowledge entry shapes and the body helpers for authoring."
+    },
+    {
+      "file": "lib/facts.tsx",
+      "purpose": "FactList: renders an open-shaped API object as labelled facts."
     }
   ],
   "recipes": [
@@ -217,6 +525,7 @@
   ],
   "scopes": [
     "knowledge:read",
+    "knowledge:write",
     "voice:delete",
     "voice:read",
     "voice:run",

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

@@ -0,0 +1,112 @@
+"use client";
+
+/**
+ * AgentActivity: what an agent has done lately. A time window (7, 30, 90 days), the headline numbers (calls, skill runs,
+ * workflow runs, chats), how its skills performed (executions, success rate, speed, cost) and the latest rows of each kind.
+ * Every list says how many exist when it shows fewer, and "Show more" fetches a longer feed (up to the API's 200 per kind).
+ * All reads are free.
+ *
+ * SDK operations, in order:
+ *   1. getAgentActivity   GET /voice/agents/{agent_id}/activity?days&limit   (read)  calls, skill runs, workflow runs, chats + summary
+ *   2. getAgentSkillStats GET /voice/agents/{agent_id}/skill-stats?days      (read)  executions, success rate, duration, tokens, cost
+ */
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { bodyOf } from "../lib/agent-types";
+
+export interface AgentActivityProps {
+  agentId: string;
+  className?: string;
+}
+
+interface Row { id?: string | number; execution_id?: string; [k: string]: unknown }
+interface Feed { calls?: Row[]; actions?: Row[]; workflows?: Row[]; chats?: Row[]; summary?: Record<string, number> }
+interface Stats { total_actions?: number; total_executions?: number; completed?: number; failed?: number; success_rate?: number; avg_duration_ms?: number; total_cost_usd?: number }
+
+const WINDOWS = [7, 30, 90];
+const LIMITS = [50, 100, 200];
+const when = (v: unknown): string => { const d = typeof v === "string" ? new Date(v) : null; return d && !Number.isNaN(d.getTime()) ? d.toLocaleString() : ""; };
+const ms = (v: unknown): string => (typeof v === "number" ? (v >= 1000 ? `${(v / 1000).toFixed(1)}s` : `${Math.round(v)}ms`) : "");
+const rowKey = (r: Row, i: number): string => String(r.execution_id ?? r.id ?? i);
+
+function Feeds({ title, rows, total, empty, children }: { title: string; rows: Row[]; total?: number; empty: string; children: (r: Row) => React.ReactNode }) {
+  return (
+    <SectionCard title={title} description={total != null && total > rows.length ? `Showing the latest ${rows.length} of ${total}` : undefined} flush>
+      {rows.length === 0 ? <p className="px-4 py-3 text-sm text-muted-foreground">{empty}</p> : (
+        <ul className="divide-y">{rows.map((r, i) => <li key={rowKey(r, i)} className="flex flex-wrap items-center justify-between gap-2 px-4 py-2 text-sm">{children(r)}</li>)}</ul>
+      )}
+    </SectionCard>
+  );
+}
+
+export function AgentActivity({ agentId, className }: AgentActivityProps) {
+  const [days, setDays] = useState(30);
+  const [limitIx, setLimitIx] = useState(0);
+  const limit = LIMITS[limitIx];
+  const feed = useG8Query((signal) => g8Get(`/voice/agents/${encodeURIComponent(agentId)}/activity`, { days, limit }, { signal }), [agentId, days, limit]);
+  const stats = useG8Query((signal) => g8Get(`/voice/agents/${encodeURIComponent(agentId)}/skill-stats`, { days }, { signal }), [agentId, days]);
+  const f = bodyOf<Feed>(feed.data);
+  const s = bodyOf<Stats>(stats.data);
+  const sum = f.summary ?? {};
+  const calls = f.calls ?? [], actions = f.actions ?? [], workflows = f.workflows ?? [], chats = f.chats ?? [];
+  const truncated = [[calls.length, sum.total_calls], [actions.length, sum.total_actions], [workflows.length, sum.total_workflows]].some(([n, t]) => t != null && (t as number) > (n as number)) && limitIx < LIMITS.length - 1;
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <div role="group" aria-label="Time window" className="flex items-center gap-1">
+        {WINDOWS.map((d) => <Button key={d} size="sm" variant={days === d ? "default" : "outline"} onClick={() => { setDays(d); setLimitIx(0); }}>{d} days</Button>)}
+      </div>
+      {feed.error ? <ApiError error={feed.error} title="Could not load the activity" onRetry={() => void feed.refetch()} /> : null}
+      {feed.loading && !feed.data ? <Skeleton className="h-24 w-full" aria-label="Loading activity" /> : null}
+      {feed.data ? (
+        <>
+          <StatStrip items={[
+            { label: "Calls", value: String(sum.total_calls ?? calls.length), hint: `${sum.inbound_calls ?? 0} inbound, ${sum.outbound_calls ?? 0} outbound` },
+            { label: "Skill runs", value: String(sum.total_actions ?? actions.length), hint: `${sum.successful_actions ?? 0} succeeded, ${sum.failed_actions ?? 0} failed` },
+            { label: "Workflow runs", value: String(sum.total_workflows ?? workflows.length) },
+            { label: "Chats", value: String(sum.total_chats ?? chats.length) },
+          ]} />
+          <Feeds title="Calls" rows={calls} total={sum.total_calls} empty="No calls in this window.">
+            {(r) => <>
+              <span>{[r.first_name, r.last_name].filter(Boolean).join(" ") || String(r.to ?? r.from ?? "Call")}<span className="ml-2 text-xs text-muted-foreground">{String(r.call_type ?? "")} {ms(typeof r.call_duration === "number" ? r.call_duration * 1000 : undefined)}</span></span>
+              <span className="flex items-center gap-2">{r.disposition ? <StatusPill tone="neutral">{String(r.disposition)}</StatusPill> : null}{r.recording_url ? <a className="text-xs underline" href={String(r.recording_url)} target="_blank" rel="noreferrer">Recording</a> : null}<span className="text-xs text-muted-foreground">{when(r.created_at)}</span></span>
+            </>}
+          </Feeds>
+          <Feeds title="Skill runs" rows={actions} total={sum.total_actions} empty="No skill runs in this window.">
+            {(r) => <>
+              <span>{String(r.action_name ?? "Skill")}{r.error_message ? <span className="block text-xs text-error-foreground">{String(r.error_message)}</span> : null}</span>
+              <span className="flex items-center gap-2"><StatusPill tone={toneForStatus(String(r.status ?? ""))} dot>{String(r.status ?? "")}</StatusPill><span className="text-xs text-muted-foreground">{ms(r.duration_ms)} {when(r.created_at)}</span></span>
+            </>}
+          </Feeds>
+          <Feeds title="Workflow runs" rows={workflows} total={sum.total_workflows} empty="No workflow runs in this window.">
+            {(r) => <><span>{String(r.action_name ?? "Workflow")}</span><span className="flex items-center gap-2"><StatusPill tone={toneForStatus(String(r.status ?? ""))} dot>{String(r.status ?? "")}</StatusPill><span className="text-xs text-muted-foreground">{when(r.created_at)}</span></span></>}
+          </Feeds>
+          <Feeds title="Chats" rows={chats} empty="No chats in this window.">
+            {(r) => <><span>{String(r.name ?? "Chat")}</span><span className="text-xs text-muted-foreground">{String(r.message_count ?? 0)} messages, {when(r.updated_at ?? r.created_at)}</span></>}
+          </Feeds>
+          {truncated ? <Button size="sm" variant="outline" className="self-center" onClick={() => setLimitIx((i) => i + 1)}>Show more</Button> : null}
+          {!calls.length && !actions.length && !workflows.length && !chats.length ? <EmptyState compact title="No activity yet" description="Calls, skill runs and chats appear here once the agent is in use." /> : null}
+        </>
+      ) : null}
+      <SectionCard title="Skill performance" description={`Across every attached skill, last ${days} days`}>
+        {stats.error ? <ApiError error={stats.error} title="Could not load skill statistics" onRetry={() => void stats.refetch()} /> : null}
+        {stats.loading && !stats.data ? <Skeleton className="h-10 w-full" /> : null}
+        {stats.data ? (
+          <dl className="grid grid-cols-2 gap-3 text-sm sm:grid-cols-4" data-testid="skill-stats">
+            <div><dt className="text-xs text-muted-foreground">Executions</dt><dd>{s.total_executions ?? 0}</dd></div>
+            <div><dt className="text-xs text-muted-foreground">Success rate</dt><dd>{Math.round(s.success_rate ?? 0)}%</dd></div>
+            <div><dt className="text-xs text-muted-foreground">Average time</dt><dd>{ms(s.avg_duration_ms) || "n/a"}</dd></div>
+            <div><dt className="text-xs text-muted-foreground">Cost</dt><dd>${(s.total_cost_usd ?? 0).toFixed(2)}</dd></div>
+          </dl>
+        ) : null}
+      </SectionCard>
+    </div>
+  );
+}