zubo 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (222) hide show
  1. package/.github/workflows/ci.yml +35 -0
  2. package/README.md +149 -0
  3. package/bun.lock +216 -0
  4. package/desktop/README.md +57 -0
  5. package/desktop/package.json +12 -0
  6. package/desktop/src-tauri/Cargo.toml +25 -0
  7. package/desktop/src-tauri/build.rs +3 -0
  8. package/desktop/src-tauri/icons/README.md +17 -0
  9. package/desktop/src-tauri/icons/icon.png +0 -0
  10. package/desktop/src-tauri/src/main.rs +189 -0
  11. package/desktop/src-tauri/tauri.conf.json +68 -0
  12. package/docs/ROADMAP.md +490 -0
  13. package/migrations/001_init.sql +9 -0
  14. package/migrations/002_memory.sql +33 -0
  15. package/migrations/003_cron.sql +24 -0
  16. package/migrations/004_usage.sql +12 -0
  17. package/migrations/005_secrets.sql +8 -0
  18. package/migrations/006_agents.sql +1 -0
  19. package/migrations/007_workflows.sql +22 -0
  20. package/migrations/008_proactive.sql +24 -0
  21. package/migrations/009_uploads.sql +9 -0
  22. package/migrations/010_observability.sql +22 -0
  23. package/migrations/011_api_keys.sql +7 -0
  24. package/migrations/012_indexes.sql +5 -0
  25. package/migrations/013_budget.sql +11 -0
  26. package/migrations/014_usage_session_idx.sql +2 -0
  27. package/package.json +39 -0
  28. package/site/404.html +156 -0
  29. package/site/CNAME +1 -0
  30. package/site/docs/agents.html +294 -0
  31. package/site/docs/api.html +446 -0
  32. package/site/docs/channels.html +345 -0
  33. package/site/docs/cli.html +238 -0
  34. package/site/docs/config.html +1034 -0
  35. package/site/docs/index.html +433 -0
  36. package/site/docs/integrations.html +381 -0
  37. package/site/docs/memory.html +254 -0
  38. package/site/docs/security.html +375 -0
  39. package/site/docs/skills.html +322 -0
  40. package/site/docs.css +412 -0
  41. package/site/index.html +638 -0
  42. package/site/install.sh +98 -0
  43. package/site/logo.svg +1 -0
  44. package/site/og-image.png +0 -0
  45. package/site/robots.txt +4 -0
  46. package/site/script.js +361 -0
  47. package/site/sitemap.xml +63 -0
  48. package/site/skills.html +532 -0
  49. package/site/style.css +1686 -0
  50. package/src/agent/agents.ts +159 -0
  51. package/src/agent/compaction.ts +53 -0
  52. package/src/agent/context.ts +18 -0
  53. package/src/agent/delegate.ts +118 -0
  54. package/src/agent/loop.ts +318 -0
  55. package/src/agent/prompts.ts +111 -0
  56. package/src/agent/session.ts +87 -0
  57. package/src/agent/teams.ts +116 -0
  58. package/src/agent/workflow-executor.ts +192 -0
  59. package/src/agent/workflow.ts +175 -0
  60. package/src/channels/adapter.ts +21 -0
  61. package/src/channels/dashboard.html.ts +2969 -0
  62. package/src/channels/discord.ts +137 -0
  63. package/src/channels/optional-deps.d.ts +17 -0
  64. package/src/channels/router.ts +199 -0
  65. package/src/channels/signal.ts +133 -0
  66. package/src/channels/slack.ts +101 -0
  67. package/src/channels/telegram.ts +102 -0
  68. package/src/channels/utils.ts +18 -0
  69. package/src/channels/webchat.ts +1797 -0
  70. package/src/channels/whatsapp.ts +119 -0
  71. package/src/config/loader.ts +22 -0
  72. package/src/config/paths.ts +43 -0
  73. package/src/config/schema.ts +121 -0
  74. package/src/db/connection.ts +20 -0
  75. package/src/db/export.ts +148 -0
  76. package/src/db/migrations.ts +42 -0
  77. package/src/index.ts +261 -0
  78. package/src/llm/claude.ts +193 -0
  79. package/src/llm/factory.ts +115 -0
  80. package/src/llm/failover.ts +101 -0
  81. package/src/llm/openai-compat.ts +409 -0
  82. package/src/llm/provider.ts +83 -0
  83. package/src/llm/smart-router.ts +241 -0
  84. package/src/logs.ts +53 -0
  85. package/src/memory/chunker.ts +58 -0
  86. package/src/memory/document-parser.ts +115 -0
  87. package/src/memory/embedder.ts +235 -0
  88. package/src/memory/engine.ts +170 -0
  89. package/src/memory/fts-index.ts +55 -0
  90. package/src/memory/hybrid-search.ts +72 -0
  91. package/src/memory/store.ts +56 -0
  92. package/src/memory/vector-index.ts +72 -0
  93. package/src/model.ts +118 -0
  94. package/src/registry/cli.ts +43 -0
  95. package/src/registry/client.ts +54 -0
  96. package/src/registry/installer.ts +67 -0
  97. package/src/scheduler/briefing.ts +71 -0
  98. package/src/scheduler/cron.ts +258 -0
  99. package/src/scheduler/heartbeat.ts +58 -0
  100. package/src/scheduler/memory-triggers.ts +100 -0
  101. package/src/scheduler/natural-cron.ts +163 -0
  102. package/src/scheduler/proactive.ts +25 -0
  103. package/src/scheduler/recipes.ts +110 -0
  104. package/src/secrets/store.ts +64 -0
  105. package/src/setup.ts +413 -0
  106. package/src/skills.ts +293 -0
  107. package/src/start.ts +373 -0
  108. package/src/status.ts +165 -0
  109. package/src/tools/builtin/connect-service.ts +205 -0
  110. package/src/tools/builtin/cron.ts +126 -0
  111. package/src/tools/builtin/datetime.ts +36 -0
  112. package/src/tools/builtin/delegate-task.ts +81 -0
  113. package/src/tools/builtin/delegate.ts +42 -0
  114. package/src/tools/builtin/diagnose.ts +41 -0
  115. package/src/tools/builtin/google-oauth.ts +379 -0
  116. package/src/tools/builtin/manage-agents.ts +149 -0
  117. package/src/tools/builtin/manage-skills.ts +294 -0
  118. package/src/tools/builtin/manage-teams.ts +89 -0
  119. package/src/tools/builtin/manage-triggers.ts +94 -0
  120. package/src/tools/builtin/manage-workflows.ts +119 -0
  121. package/src/tools/builtin/memory-search.ts +38 -0
  122. package/src/tools/builtin/memory-write.ts +30 -0
  123. package/src/tools/builtin/run-workflow.ts +36 -0
  124. package/src/tools/builtin/secrets.ts +122 -0
  125. package/src/tools/builtin/skill-registry.ts +75 -0
  126. package/src/tools/builtin-integrations/api-helpers.ts +26 -0
  127. package/src/tools/builtin-integrations/github/github_issues/SKILL.md +56 -0
  128. package/src/tools/builtin-integrations/github/github_issues/handler.ts +108 -0
  129. package/src/tools/builtin-integrations/github/github_prs/SKILL.md +57 -0
  130. package/src/tools/builtin-integrations/github/github_prs/handler.ts +113 -0
  131. package/src/tools/builtin-integrations/github/github_repos/SKILL.md +37 -0
  132. package/src/tools/builtin-integrations/github/github_repos/handler.ts +88 -0
  133. package/src/tools/builtin-integrations/google/gmail/SKILL.md +51 -0
  134. package/src/tools/builtin-integrations/google/gmail/handler.ts +125 -0
  135. package/src/tools/builtin-integrations/google/google_calendar/SKILL.md +35 -0
  136. package/src/tools/builtin-integrations/google/google_calendar/handler.ts +105 -0
  137. package/src/tools/builtin-integrations/google/google_docs/SKILL.md +35 -0
  138. package/src/tools/builtin-integrations/google/google_docs/handler.ts +108 -0
  139. package/src/tools/builtin-integrations/google/google_drive/SKILL.md +39 -0
  140. package/src/tools/builtin-integrations/google/google_drive/handler.ts +106 -0
  141. package/src/tools/builtin-integrations/google/google_sheets/SKILL.md +36 -0
  142. package/src/tools/builtin-integrations/google/google_sheets/handler.ts +116 -0
  143. package/src/tools/builtin-integrations/jira/jira_boards/SKILL.md +21 -0
  144. package/src/tools/builtin-integrations/jira/jira_boards/handler.ts +74 -0
  145. package/src/tools/builtin-integrations/jira/jira_issues/SKILL.md +28 -0
  146. package/src/tools/builtin-integrations/jira/jira_issues/handler.ts +140 -0
  147. package/src/tools/builtin-integrations/linear/linear_issues/SKILL.md +30 -0
  148. package/src/tools/builtin-integrations/linear/linear_issues/handler.ts +75 -0
  149. package/src/tools/builtin-integrations/linear/linear_projects/SKILL.md +21 -0
  150. package/src/tools/builtin-integrations/linear/linear_projects/handler.ts +43 -0
  151. package/src/tools/builtin-integrations/notion/notion_databases/SKILL.md +39 -0
  152. package/src/tools/builtin-integrations/notion/notion_databases/handler.ts +83 -0
  153. package/src/tools/builtin-integrations/notion/notion_pages/SKILL.md +43 -0
  154. package/src/tools/builtin-integrations/notion/notion_pages/handler.ts +130 -0
  155. package/src/tools/builtin-integrations/notion/notion_search/SKILL.md +27 -0
  156. package/src/tools/builtin-integrations/notion/notion_search/handler.ts +69 -0
  157. package/src/tools/builtin-integrations/slack/slack_messages/SKILL.md +42 -0
  158. package/src/tools/builtin-integrations/slack/slack_messages/handler.ts +72 -0
  159. package/src/tools/builtin-integrations/twitter/twitter_posts/SKILL.md +24 -0
  160. package/src/tools/builtin-integrations/twitter/twitter_posts/handler.ts +133 -0
  161. package/src/tools/builtin-skills/file-read/SKILL.md +26 -0
  162. package/src/tools/builtin-skills/file-read/handler.ts +66 -0
  163. package/src/tools/builtin-skills/file-write/SKILL.md +30 -0
  164. package/src/tools/builtin-skills/file-write/handler.ts +64 -0
  165. package/src/tools/builtin-skills/http-request/SKILL.md +34 -0
  166. package/src/tools/builtin-skills/http-request/handler.ts +87 -0
  167. package/src/tools/builtin-skills/shell/SKILL.md +26 -0
  168. package/src/tools/builtin-skills/shell/handler.ts +96 -0
  169. package/src/tools/builtin-skills/url-fetch/SKILL.md +26 -0
  170. package/src/tools/builtin-skills/url-fetch/handler.ts +37 -0
  171. package/src/tools/builtin-skills/web-search/SKILL.md +26 -0
  172. package/src/tools/builtin-skills/web-search/handler.ts +50 -0
  173. package/src/tools/executor.ts +205 -0
  174. package/src/tools/integration-installer.ts +106 -0
  175. package/src/tools/permissions.ts +45 -0
  176. package/src/tools/registry.ts +39 -0
  177. package/src/tools/sandbox-runner.ts +56 -0
  178. package/src/tools/sandbox.ts +82 -0
  179. package/src/tools/skill-installer.ts +52 -0
  180. package/src/tools/skill-loader.ts +259 -0
  181. package/src/types/optional-deps.d.ts +23 -0
  182. package/src/util/auth.ts +121 -0
  183. package/src/util/costs.ts +59 -0
  184. package/src/util/error-buffer.ts +32 -0
  185. package/src/util/google-tokens.ts +180 -0
  186. package/src/util/logger.ts +73 -0
  187. package/src/util/perf-collector.ts +35 -0
  188. package/src/util/rate-limiter.ts +70 -0
  189. package/src/util/tokens.ts +17 -0
  190. package/src/voice/stt.ts +57 -0
  191. package/src/voice/tts.ts +103 -0
  192. package/tests/agent/session.test.ts +109 -0
  193. package/tests/agent-loop.test.ts +54 -0
  194. package/tests/auth.test.ts +89 -0
  195. package/tests/channels.test.ts +67 -0
  196. package/tests/compaction.test.ts +44 -0
  197. package/tests/config.test.ts +51 -0
  198. package/tests/costs.test.ts +19 -0
  199. package/tests/cron.test.ts +55 -0
  200. package/tests/db/export.test.ts +219 -0
  201. package/tests/executor.test.ts +144 -0
  202. package/tests/export.test.ts +137 -0
  203. package/tests/helpers/mock-llm.ts +34 -0
  204. package/tests/helpers/test-db.ts +74 -0
  205. package/tests/integration/chat-flow.test.ts +48 -0
  206. package/tests/integrations.test.ts +97 -0
  207. package/tests/memory/engine.test.ts +114 -0
  208. package/tests/memory-engine.test.ts +57 -0
  209. package/tests/permissions.test.ts +21 -0
  210. package/tests/rate-limiter.test.ts +70 -0
  211. package/tests/registry.test.ts +67 -0
  212. package/tests/router.test.ts +36 -0
  213. package/tests/session.test.ts +58 -0
  214. package/tests/skill-loader.test.ts +44 -0
  215. package/tests/tokens.test.ts +30 -0
  216. package/tests/tools/executor.test.ts +130 -0
  217. package/tests/util/auth.test.ts +75 -0
  218. package/tests/util/rate-limiter.test.ts +73 -0
  219. package/tests/voice.test.ts +60 -0
  220. package/tests/webchat.test.ts +88 -0
  221. package/tests/workflow.test.ts +38 -0
  222. package/tsconfig.json +16 -0
package/site/docs/api.html ADDED
@@ -0,0 +1,446 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>API Reference — Zubo Docs</title>
7
+ <meta name="description" content="Complete API reference for Zubo. All REST endpoints with request/response formats, authentication, rate limits, and examples.">
8
+ <meta name="theme-color" content="#060608">
9
+ <link rel="canonical" href="https://zubo.bot/docs/api.html">
10
+ <meta property="og:title" content="API Reference — Zubo Docs">
11
+ <meta property="og:description" content="Complete API reference for Zubo. All REST endpoints with request/response formats, authentication, and examples.">
12
+ <meta property="og:type" content="article">
13
+ <meta property="og:url" content="https://zubo.bot/docs/api.html">
14
+ <meta property="og:image" content="https://zubo.bot/og-image.png">
15
+ <meta property="og:site_name" content="Zubo">
16
+ <meta name="twitter:card" content="summary_large_image">
17
+ <meta name="twitter:title" content="API Reference — Zubo Docs">
18
+ <meta name="twitter:description" content="Complete API reference for Zubo. REST endpoints, authentication, and examples.">
19
+ <meta name="twitter:image" content="https://zubo.bot/og-image.png">
20
+ <meta name="twitter:creator" content="@thomaskanze">
21
+ <link rel="preconnect" href="https://fonts.googleapis.com">
22
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
23
+ <link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,600;12..96,700;12..96,800&family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
24
+ <link rel="stylesheet" href="../style.css">
25
+ <link rel="stylesheet" href="../docs.css">
26
+ <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' rx='20' fill='%237c3aed'/><path d='M50 15C52 37 63 48 85 50C63 52 52 63 50 85C48 63 37 52 15 50C37 48 48 37 50 15Z' fill='white'/></svg>">
27
+ </head>
28
+ <body>
29
+
30
+ <header class="nav scrolled" id="nav">
31
+ <div class="nav-inner">
32
+ <a href="../index.html" class="nav-logo"><span class="logo-wordmark">zubo</span></a>
33
+ <nav class="nav-links" id="nav-links">
34
+ <a href="../index.html#features">Features</a>
35
+ <a href="index.html" style="color:#fff;">Docs</a>
36
+ <a href="../skills.html">Skills</a>
37
+ <a href="../index.html#get-started">Get Started</a>
38
+ </nav>
39
+ <div class="nav-right">
40
+ <a href="https://github.com/apwn/zubo" class="nav-github" aria-label="GitHub"><svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg></a>
41
+ <a href="../index.html#get-started" class="btn btn-primary btn-nav">Get Started</a>
42
+ <button class="nav-toggle" id="nav-toggle" aria-label="Toggle menu"><span></span><span></span><span></span></button>
43
+ </div>
44
+ </div>
45
+ </header>
46
+
47
+ <div class="docs-layout">
48
+ <aside class="docs-sidebar" id="docs-sidebar">
49
+ <div class="docs-sidebar-section">
50
+ <div class="docs-sidebar-heading">Getting Started</div>
51
+ <div class="docs-sidebar-links">
52
+ <a href="index.html">Overview</a>
53
+ <a href="config.html">Configuration</a>
54
+ </div>
55
+ </div>
56
+ <div class="docs-sidebar-section">
57
+ <div class="docs-sidebar-heading">Core Concepts</div>
58
+ <div class="docs-sidebar-links">
59
+ <a href="agents.html">Agents &amp; Workflows</a>
60
+ <a href="memory.html">Memory System</a>
61
+ <a href="skills.html">Skills</a>
62
+ </div>
63
+ </div>
64
+ <div class="docs-sidebar-section">
65
+ <div class="docs-sidebar-heading">Guides</div>
66
+ <div class="docs-sidebar-links">
67
+ <a href="channels.html">Channel Setup</a>
68
+ <a href="integrations.html">Integrations</a>
69
+ <a href="security.html">Security &amp; Auth</a>
70
+ </div>
71
+ </div>
72
+ <div class="docs-sidebar-section">
73
+ <div class="docs-sidebar-heading">Reference</div>
74
+ <div class="docs-sidebar-links">
75
+ <a href="api.html" class="active">API Reference</a>
76
+ <a href="cli.html">CLI Commands</a>
77
+ </div>
78
+ </div>
79
+ </aside>
80
+
81
+ <main class="docs-content">
82
+ <div class="docs-breadcrumb"><a href="../index.html">Home</a><span>/</span><a href="index.html">Docs</a><span>/</span>API Reference</div>
83
+
84
+ <h1>API Reference</h1>
85
+ <p>Zubo exposes a REST API on the webchat port. All endpoints are available at <code>http://localhost:&lt;port&gt;</code>. If authentication is enabled, include <code>Authorization: Bearer &lt;key&gt;</code> on all <code>/api/*</code> requests.</p>
86
+
87
+ <h2>Health Check</h2>
88
+ <pre><code>GET /health</code></pre>
89
+ <p>Returns the current health status and uptime of the Zubo agent. This endpoint does not require authentication, even when <code>auth.enabled</code> is <code>true</code>.</p>
90
+ <p><strong>Response:</strong></p>
91
+ <pre><code>{
92
+ "status": "ok",
93
+ "uptime": 3600
94
+ }</code></pre>
95
+
96
+ <h2>Chat</h2>
97
+
98
+ <h3>Send Message</h3>
99
+ <pre><code>POST /api/chat
100
+ Content-Type: application/json
101
+
102
+ {
103
+ "message": "Hello, how are you?"
104
+ }</code></pre>
105
+ <p>Sends a message to the agent and returns a complete response once the agent has finished processing.</p>
106
+ <p><strong>Response:</strong></p>
107
+ <pre><code>{
108
+ "reply": "I'm doing well! How can I help?"
109
+ }</code></pre>
110
+
111
+ <h3>Stream Message (SSE)</h3>
112
+ <pre><code>POST /api/chat/stream
113
+ Content-Type: application/json
114
+
115
+ {
116
+ "message": "Tell me about AI"
117
+ }</code></pre>
118
+ <p>Sends a message and receives the response as a Server-Sent Events stream. This allows the UI to display partial responses as they are generated. The stream emits the following event types:</p>
119
+ <table>
120
+ <thead><tr><th>Event</th><th>Data</th><th>Description</th></tr></thead>
121
+ <tbody>
122
+ <tr><td><code>delta</code></td><td><code>{ "text": "partial text" }</code></td><td>A chunk of the response text as it is generated.</td></tr>
123
+ <tr><td><code>tool</code></td><td><code>{ "name": "web_search", "status": "start" }</code></td><td>Indicates a tool call has started. Status is <code>"start"</code> or <code>"end"</code>.</td></tr>
124
+ <tr><td><code>done</code></td><td><code>{ "reply": "full response text" }</code></td><td>The complete response. Sent once at the end of the stream.</td></tr>
125
+ <tr><td><code>error</code></td><td><code>{ "error": "error message" }</code></td><td>An error occurred during processing.</td></tr>
126
+ </tbody>
127
+ </table>
128
+
129
+ <h3>Chat History</h3>
130
+ <pre><code>GET /api/chat/history?limit=50</code></pre>
131
+ <p>Returns the recent conversation history. Tool calls are filtered out &mdash; only user and assistant text messages are returned.</p>
132
+ <p><strong>Query parameters:</strong></p>
133
+ <table>
134
+ <thead><tr><th>Parameter</th><th>Default</th><th>Description</th></tr></thead>
135
+ <tbody>
136
+ <tr><td><code>limit</code></td><td>50</td><td>Number of messages to return. Maximum 200.</td></tr>
137
+ </tbody>
138
+ </table>
139
+ <p><strong>Response:</strong></p>
140
+ <pre><code>{
141
+ "messages": [
142
+ { "role": "user", "content": "Hello" },
143
+ { "role": "assistant", "content": "Hi! How can I help?" }
144
+ ]
145
+ }</code></pre>
146
+
147
+ <h3>Voice Chat</h3>
148
+ <pre><code>POST /api/chat/voice
149
+ Content-Type: multipart/form-data
150
+
151
+ audio: &lt;audio file&gt;
152
+ tts: "true" (optional)</code></pre>
153
+ <p>Send an audio file for speech-to-text transcription, then process the transcribed text through the agent. Requires an STT provider to be configured. If <code>tts=true</code> is included and a TTS provider is configured, the response will include base64-encoded audio of the agent's reply.</p>
154
+ <p><strong>Response:</strong></p>
155
+ <pre><code>{
156
+ "transcript": "What's the weather?",
157
+ "reply": "Currently 72&deg;F and sunny.",
158
+ "audio": "&lt;base64 audio&gt;",
159
+ "audioFormat": "mp3"
160
+ }</code></pre>
161
+
162
+ <h2>File Upload</h2>
163
+ <pre><code>POST /api/upload
164
+ Content-Type: multipart/form-data
165
+
166
+ file: &lt;document&gt;</code></pre>
167
+ <p>Upload a document for memory indexing. The file is parsed, chunked, embedded, and stored in the memory database. The agent will be able to recall information from uploaded documents in future conversations.</p>
168
+ <p><strong>Limits:</strong> 50MB maximum file size.</p>
169
+ <p><strong>Allowed extensions:</strong> <code>.pdf</code>, <code>.docx</code>, <code>.txt</code>, <code>.md</code>, <code>.csv</code>, <code>.json</code>, <code>.html</code>, <code>.xml</code>, <code>.yaml</code>, <code>.yml</code>, <code>.ts</code>, <code>.js</code>, <code>.py</code>, <code>.sh</code></p>
170
+ <p><strong>Response:</strong></p>
171
+ <pre><code>{
172
+ "uploaded": true,
173
+ "filename": "report.pdf",
174
+ "size": 245760,
175
+ "chunks": 12,
176
+ "wordCount": 5430
177
+ }</code></pre>
178
+
179
+ <h2>Dashboard API</h2>
180
+ <p>All dashboard endpoints are under <code>/api/dashboard/</code>. These power the built-in web UI and can also be used by external tools and integrations.</p>
181
+
182
+ <h3>Status</h3>
183
+ <pre><code>GET /api/dashboard/status</code></pre>
184
+ <p>Returns an overview of the agent's current state, including the active provider, connected channels, message count, memory count, and running status.</p>
185
+ <pre><code>{
186
+ "Provider": "anthropic/claude-sonnet-4-5",
187
+ "Channels": "webchat, telegram",
188
+ "Messages": "1234",
189
+ "Memories": "567",
190
+ "Status": "running"
191
+ }</code></pre>
192
+
193
+ <h3>System Prompt</h3>
194
+ <pre><code>GET /api/dashboard/system</code></pre>
195
+ <p>Retrieve the current system prompt.</p>
196
+ <pre><code>PUT /api/dashboard/system
197
+ Content-Type: application/json
198
+
199
+ {
200
+ "content": "You are a helpful assistant named Zubo."
201
+ }</code></pre>
202
+ <p>Update the system prompt. The new prompt takes effect on the next message.</p>
203
+
204
+ <h3>Memory</h3>
205
+ <pre><code>GET /api/dashboard/memory</code></pre>
206
+ <p>Get the current contents of <code>MEMORY.md</code>, the always-loaded memory file.</p>
207
+ <pre><code>PUT /api/dashboard/memory
208
+ Content-Type: application/json
209
+
210
+ {
211
+ "content": "User's name is Thomas. Prefers concise answers."
212
+ }</code></pre>
213
+ <p>Update the contents of <code>MEMORY.md</code>. Changes take effect on the next message.</p>
214
+ <pre><code>GET /api/dashboard/memory/recent</code></pre>
215
+ <p>Returns the last 20 memory chunks with their source, timestamp, and content.</p>
216
+ <pre><code>GET /api/dashboard/memory/search?q=programming</code></pre>
217
+ <p>Search memory chunks using full-text search. Returns matching chunks ranked by relevance.</p>
218
+
219
+ <h3>Skills</h3>
220
+ <pre><code>GET /api/dashboard/skills</code></pre>
221
+ <p>List all installed skills with their metadata.</p>
222
+ <p><strong>Response:</strong></p>
223
+ <pre><code>{
224
+ "skills": [
225
+ {
226
+ "name": "weather",
227
+ "description": "Get current weather for a location",
228
+ "status": "active",
229
+ "path": "~/.zubo/skills/weather"
230
+ }
231
+ ]
232
+ }</code></pre>
233
+
234
+ <h3>Cron Jobs</h3>
235
+ <pre><code>GET /api/dashboard/cron</code></pre>
236
+ <p>List all configured cron jobs and their status.</p>
237
+ <p><strong>Response:</strong></p>
238
+ <pre><code>{
239
+ "jobs": [
240
+ {
241
+ "name": "daily-summary",
242
+ "schedule": "0 9 * * *",
243
+ "task": "Send a daily briefing",
244
+ "enabled": true,
245
+ "last_run": "2026-02-12T09:00:00Z"
246
+ }
247
+ ]
248
+ }</code></pre>
249
+
250
+ <h3>Logs</h3>
251
+ <pre><code>GET /api/dashboard/logs</code></pre>
252
+ <p>Returns the last 100 log lines from the agent's log output.</p>
253
+
254
+ <h3>Config</h3>
255
+ <pre><code>GET /api/dashboard/config</code></pre>
256
+ <p>Returns the current configuration (sensitive values are masked).</p>
257
+ <pre><code>PUT /api/dashboard/config/model
258
+ Content-Type: application/json
259
+
260
+ {
261
+ "provider": "anthropic",
262
+ "model": "claude-sonnet-4-5-20250929"
263
+ }</code></pre>
264
+ <p>Update the active LLM provider and model. The change takes effect on the next message.</p>
265
+
266
+ <h3>Settings</h3>
267
+ <pre><code>GET /api/dashboard/settings/heartbeat</code></pre>
268
+ <p>Get the current heartbeat interval.</p>
269
+ <pre><code>PUT /api/dashboard/settings/heartbeat
270
+ Content-Type: application/json
271
+
272
+ {
273
+ "minutes": 60
274
+ }</code></pre>
275
+ <p>Update the heartbeat interval. Set to <code>0</code> to disable.</p>
276
+
277
+ <h3>Channel Status</h3>
278
+ <pre><code>GET /api/dashboard/channel-status</code></pre>
279
+ <p>Returns the configuration and connection status for each channel (webchat, Telegram, Discord, Slack, WhatsApp, Signal). Each channel reports whether it is configured and whether it is currently enabled.</p>
280
+
281
+ <h3>Secrets Management</h3>
282
+ <pre><code>GET /api/dashboard/secrets</code></pre>
283
+ <p>List all stored secrets. Values are masked in the response for security.</p>
284
+ <pre><code>GET /api/dashboard/secrets/:name</code></pre>
285
+ <p>Reveal the full value of a single secret by name.</p>
286
+ <pre><code>POST /api/dashboard/secrets
287
+ Content-Type: application/json
288
+
289
+ {
290
+ "name": "OPENWEATHER_API_KEY",
291
+ "value": "abc123...",
292
+ "service": "weather"
293
+ }</code></pre>
294
+ <p>Create or update a secret. The optional <code>service</code> field associates the secret with a specific integration or skill.</p>
295
+ <pre><code>DELETE /api/dashboard/secrets/:name</code></pre>
296
+ <p>Delete a secret by name.</p>
297
+
298
+ <h2>Analytics API</h2>
299
+ <p>Analytics endpoints provide insight into usage, cost, performance, and tool activity.</p>
300
+ <pre><code>GET /api/dashboard/analytics/summary</code></pre>
301
+ <p>Returns aggregate statistics: total tokens used, estimated cost in USD, average response time in milliseconds, and total session count.</p>
302
+ <pre><code>GET /api/dashboard/analytics/usage-over-time</code></pre>
303
+ <p>Token usage broken down by day for the last 7 days.</p>
304
+ <pre><code>GET /api/dashboard/analytics/tools</code></pre>
305
+ <p>Tool call counts and average duration for each tool.</p>
306
+ <pre><code>GET /api/dashboard/analytics/sessions</code></pre>
307
+ <p>Top 20 sessions ranked by token usage, with provider and model information.</p>
308
+ <pre><code>GET /api/dashboard/analytics/perf-snapshots</code></pre>
309
+ <p>System performance snapshots over time, including RSS memory, heap usage, and database file size.</p>
310
+ <pre><code>GET /api/dashboard/analytics/cost-breakdown</code></pre>
311
+ <p>Cost aggregated by provider and model, including total tokens, total cost, and request count for each.</p>
312
+ <pre><code>GET /api/dashboard/analytics/response-time-trend</code></pre>
313
+ <p>Average, minimum, and maximum response times by day over the last 7 days.</p>
314
+ <pre><code>GET /api/dashboard/analytics/top-models</code></pre>
315
+ <p>Top 10 models ranked by total token usage.</p>
316
+
317
+ <h2>Data Management</h2>
318
+ <pre><code>POST /api/dashboard/export</code></pre>
319
+ <p>Download a full JSON export of the database, including conversations, memory, settings, and analytics.</p>
320
+ <pre><code>POST /api/dashboard/backup</code></pre>
321
+ <p>Create a SQLite backup file of the database.</p>
322
+ <pre><code>POST /api/dashboard/import
323
+ Content-Type: multipart/form-data</code></pre>
324
+ <p>Upload a JSON export file to import data. Maximum file size is 100MB.</p>
325
+ <pre><code>GET /api/dashboard/db-stats</code></pre>
326
+ <p>Returns row counts for each table in the database and the total database file size.</p>
327
+
328
+ <h2>Workflows &amp; Agents</h2>
329
+ <pre><code>GET /api/dashboard/workflows</code></pre>
330
+ <p>List all configured workflows with their steps and status.</p>
331
+ <pre><code>GET /api/dashboard/agents</code></pre>
332
+ <p>List all configured agents (sub-agents) with their names, descriptions, and tool assignments.</p>
333
+
334
+ <h2>Uploads</h2>
335
+ <pre><code>GET /api/dashboard/uploads</code></pre>
336
+ <p>List all uploaded files with their filenames, sizes, chunk counts, and upload timestamps.</p>
337
+
338
+ <h2>Skill Registry</h2>
339
+ <pre><code>GET /api/dashboard/registry/search?q=weather</code></pre>
340
+ <p>Search the community skill registry by name or keyword. Returns matching skills with their names, descriptions, and install commands.</p>
341
+ <pre><code>POST /api/dashboard/registry/install
342
+ Content-Type: application/json
343
+
344
+ {
345
+ "name": "weather"
346
+ }</code></pre>
347
+ <p>Install a skill from the registry by name. The skill is downloaded and placed in <code>~/.zubo/skills/</code>.</p>
348
+
349
+ <h2>API Keys</h2>
350
+ <pre><code>POST /api/keys
351
+ Content-Type: application/json
352
+
353
+ {
354
+ "label": "my-integration"
355
+ }</code></pre>
356
+ <p>Create a new API key. The <code>label</code> field is optional. The full key is returned once at creation time and cannot be retrieved again.</p>
357
+ <p><strong>Response:</strong></p>
358
+ <pre><code>{
359
+ "id": "k_abc123",
360
+ "key": "zb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
361
+ }</code></pre>
362
+ <pre><code>GET /api/keys</code></pre>
363
+ <p>List all API keys. Keys are shown with their IDs, labels, creation dates, and last-used timestamps. The full key value is not included.</p>
364
+ <pre><code>DELETE /api/keys/:id</code></pre>
365
+ <p>Delete an API key by its ID. The key is immediately revoked and can no longer be used for authentication.</p>
366
+
367
+ <h2>Server-Sent Events</h2>
368
+ <pre><code>GET /api/events</code></pre>
369
+ <p>Opens a long-lived SSE connection for receiving real-time events from the agent. The connection emits the following event types:</p>
370
+ <table>
371
+ <thead><tr><th>Event</th><th>Data</th><th>Description</th></tr></thead>
372
+ <tbody>
373
+ <tr><td><code>connected</code></td><td><code>{ "timestamp": "2026-02-12T10:00:00Z" }</code></td><td>Sent once when the connection is established.</td></tr>
374
+ <tr><td><code>ping</code></td><td><code>{ "timestamp": "2026-02-12T10:00:30Z" }</code></td><td>Sent every 30 seconds to keep the connection alive.</td></tr>
375
+ </tbody>
376
+ </table>
377
+
378
+ <h2>Onboarding</h2>
379
+ <pre><code>GET /api/dashboard/onboarding</code></pre>
380
+ <p>Returns the current onboarding state, including whether setup has been completed and the last completed step.</p>
381
+ <pre><code>PUT /api/dashboard/onboarding
382
+ Content-Type: application/json
383
+
384
+ {
385
+ "completed": true,
386
+ "step": 4
387
+ }</code></pre>
388
+ <p>Update the onboarding state. Used by the dashboard to track setup progress.</p>
389
+
390
+ <h2>Test LLM</h2>
391
+ <pre><code>POST /api/dashboard/test-llm</code></pre>
392
+ <p>Send a test request to the configured LLM provider to verify connectivity and credentials. Returns a simple confirmation with the model name.</p>
393
+ <p><strong>Response:</strong></p>
394
+ <pre><code>{
395
+ "ok": true,
396
+ "response": "OK",
397
+ "model": "claude-sonnet-4-5-20250929"
398
+ }</code></pre>
399
+
400
+ <h2>Rate Limits</h2>
401
+ <p>Rate limiting is applied per IP address. When a client exceeds the limit, the endpoint returns <code>429 Too Many Requests</code> with a <code>Retry-After</code> header indicating how many seconds to wait before retrying.</p>
402
+ <table>
403
+ <thead><tr><th>Endpoint</th><th>Default Limit</th><th>Config Key</th></tr></thead>
404
+ <tbody>
405
+ <tr><td>All <code>/api/chat*</code> endpoints</td><td>60 requests/min per IP</td><td><code>rateLimit.chatPerMinute</code></td></tr>
406
+ <tr><td><code>/api/upload</code></td><td>10 requests/min per IP</td><td><code>rateLimit.uploadPerMinute</code></td></tr>
407
+ </tbody>
408
+ </table>
409
+ <p>Rate limits are configurable via <code>zubo config set</code> or the config file.</p>
410
+
411
+ <h2>Authentication</h2>
412
+ <p>When <code>auth.enabled</code> is <code>true</code> in your configuration:</p>
413
+ <ul>
414
+ <li>All <code>/api/*</code> endpoints require an <code>Authorization: Bearer &lt;key&gt;</code> header.</li>
415
+ <li>Create keys using the CLI: <code>zubo auth create-key [label]</code></li>
416
+ <li>Keys can also be created via the <code>POST /api/keys</code> endpoint (requires an existing valid key).</li>
417
+ <li>The <code>/health</code> endpoint does <strong>not</strong> require authentication, even when auth is enabled.</li>
418
+ </ul>
419
+ <p>Requests without a valid key receive a <code>401 Unauthorized</code> response:</p>
420
+ <pre><code>{
421
+ "error": "Unauthorized",
422
+ "message": "Valid API key required"
423
+ }</code></pre>
424
+
425
+ <div class="docs-page-nav">
426
+ <a href="security.html"><span class="nav-dir">Previous</span><span class="nav-label">&larr; Security &amp; Auth</span></a>
427
+ <a href="cli.html"><span class="nav-dir">Next</span><span class="nav-label">CLI Commands &rarr;</span></a>
428
+ </div>
429
+ </main>
430
+ </div>
431
+
432
+ <button class="docs-sidebar-toggle" id="docs-sidebar-toggle" aria-label="Toggle sidebar">&#9776;</button>
433
+ <script src="../script.js"></script>
434
+ <script type="application/ld+json">
435
+ {
436
+ "@context": "https://schema.org",
437
+ "@type": "BreadcrumbList",
438
+ "itemListElement": [
439
+ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://zubo.bot/" },
440
+ { "@type": "ListItem", "position": 2, "name": "Docs", "item": "https://zubo.bot/docs/" },
441
+ { "@type": "ListItem", "position": 3, "name": "API Reference", "item": "https://zubo.bot/docs/api.html" }
442
+ ]
443
+ }
444
+ </script>
445
+ </body>
446
+ </html>