zilmate 1.10.4 → 1.10.5

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 (80) hide show
  1. package/.env.example +2 -0
  2. package/SDK.md +118 -383
  3. package/dist/agents/coding.agent.d.ts +2 -2
  4. package/dist/agents/coding.agent.d.ts.map +1 -1
  5. package/dist/agents/coding.agent.js +64 -44
  6. package/dist/agents/coding.agent.js.map +1 -1
  7. package/dist/agents/finance.agent.d.ts +26 -0
  8. package/dist/agents/finance.agent.d.ts.map +1 -1
  9. package/dist/agents/finance.agent.js +2 -1
  10. package/dist/agents/finance.agent.js.map +1 -1
  11. package/dist/agents/image.agent.d.ts +42 -0
  12. package/dist/agents/image.agent.d.ts.map +1 -1
  13. package/dist/agents/image.agent.js +6 -0
  14. package/dist/agents/image.agent.js.map +1 -1
  15. package/dist/agents/manager.d.ts +4 -3
  16. package/dist/agents/manager.d.ts.map +1 -1
  17. package/dist/agents/manager.js +76 -17
  18. package/dist/agents/manager.js.map +1 -1
  19. package/dist/agents/security.agent.d.ts +1 -1
  20. package/dist/agents/swarm/registry.d.ts.map +1 -1
  21. package/dist/agents/swarm/registry.js +7 -4
  22. package/dist/agents/swarm/registry.js.map +1 -1
  23. package/dist/cli/confirm.d.ts +3 -1
  24. package/dist/cli/confirm.d.ts.map +1 -1
  25. package/dist/cli/confirm.js +9 -2
  26. package/dist/cli/confirm.js.map +1 -1
  27. package/dist/cli/doctor.d.ts.map +1 -1
  28. package/dist/cli/doctor.js +36 -1
  29. package/dist/cli/doctor.js.map +1 -1
  30. package/dist/cli/format.d.ts.map +1 -1
  31. package/dist/cli/format.js +11 -2
  32. package/dist/cli/format.js.map +1 -1
  33. package/dist/cli/interactive.d.ts.map +1 -1
  34. package/dist/cli/interactive.js +69 -8
  35. package/dist/cli/interactive.js.map +1 -1
  36. package/dist/cli/jobs.d.ts.map +1 -1
  37. package/dist/cli/jobs.js +28 -1
  38. package/dist/cli/jobs.js.map +1 -1
  39. package/dist/cli/setup.d.ts +7 -0
  40. package/dist/cli/setup.d.ts.map +1 -1
  41. package/dist/cli/setup.js +16 -3
  42. package/dist/cli/setup.js.map +1 -1
  43. package/dist/cli/tunnel.d.ts +2 -0
  44. package/dist/cli/tunnel.d.ts.map +1 -1
  45. package/dist/cli/tunnel.js +1 -1
  46. package/dist/cli/tunnel.js.map +1 -1
  47. package/dist/config/env.d.ts +3 -0
  48. package/dist/config/env.d.ts.map +1 -1
  49. package/dist/config/env.js +23 -28
  50. package/dist/config/env.js.map +1 -1
  51. package/dist/daemon/service.d.ts.map +1 -1
  52. package/dist/daemon/service.js +808 -11
  53. package/dist/daemon/service.js.map +1 -1
  54. package/dist/index.js +94 -9
  55. package/dist/index.js.map +1 -1
  56. package/dist/observability/traces.js +7 -6
  57. package/dist/observability/traces.js.map +1 -1
  58. package/dist/runtime/confirm.d.ts.map +1 -1
  59. package/dist/runtime/confirm.js +48 -0
  60. package/dist/runtime/confirm.js.map +1 -1
  61. package/dist/runtime/swarm.d.ts.map +1 -1
  62. package/dist/runtime/swarm.js +9 -0
  63. package/dist/runtime/swarm.js.map +1 -1
  64. package/dist/tools/filesystem.tool.d.ts +2 -2
  65. package/dist/tools/finance.tool.d.ts +57 -0
  66. package/dist/tools/finance.tool.d.ts.map +1 -1
  67. package/dist/tools/finance.tool.js +208 -0
  68. package/dist/tools/finance.tool.js.map +1 -1
  69. package/dist/tools/osint.tool.d.ts +2 -2
  70. package/dist/tools/setup-assistant.tool.d.ts +1 -1
  71. package/dist/tools/shell.tool.d.ts.map +1 -1
  72. package/dist/tools/shell.tool.js +17 -0
  73. package/dist/tools/shell.tool.js.map +1 -1
  74. package/dist/voice/deepgram.d.ts.map +1 -1
  75. package/dist/voice/deepgram.js +1 -0
  76. package/dist/voice/deepgram.js.map +1 -1
  77. package/dist/voice/types.d.ts +1 -0
  78. package/dist/voice/types.d.ts.map +1 -1
  79. package/package.json +2 -1
  80. package/scripts/test-expansions.ts +150 -0
package/.env.example CHANGED
@@ -22,6 +22,8 @@ ZILMATE_VOICE_PLAYBACK_MODE=stream
22
22
  ZILMATE_VOICE_DEBUG=false
23
23
  ZILMATE_VOICE_INPUT_DEVICE=
24
24
  ZILMATE_SCREENSHOT_MODEL=google/gemini-3.1-flash-lite
25
+ # Bypasses petty/repetitive interactive confirmations. Options: false (default), read-only, all/true, or comma-separated lists of tools/toolkits.
26
+ ZILMATE_AUTO_APPROVE=false
25
27
  ZILMATE_CAMERA_DEVICE=
26
28
  ZILMATE_FILE_ROOTS=
27
29
  ZILMATE_WORKSPACE=
package/SDK.md CHANGED
@@ -1,383 +1,118 @@
1
- # ZilMate SDK
2
-
3
- Use ZilMate as a programmable agent layer in Next.js, server routes, background workers, and automation scripts. The SDK wraps the same manager, subagents, memory, jobs, and voice stack as the CLI.
4
-
5
- ## Install
6
-
7
- ```bash
8
- npm install zilmate
9
- ```
10
-
11
- Set environment variables (see `.env.example`):
12
-
13
- ```env
14
- AI_GATEWAY_API_KEY=...
15
- ZILMATE_USER_ID=zilmate-your-id
16
- ```
17
-
18
- ### Environment Variables Reference
19
-
20
- | Variable | Description | Required / Optional |
21
- |---|---|---|
22
- | `AI_GATEWAY_API_KEY` | Model gateway authentication token. Required if not using Vercel OIDC. | Required |
23
- | `ZILMATE_USER_ID` | Session/User identification for persistent tracking. | Required |
24
- | `COMPOSIO_API_KEY` | Access key for system integrations and browser automation. | Optional |
25
- | `TAVILY_API_KEY` | Enable advanced multi-source web-search research. | Optional |
26
- | `DEEPGRAM_API_KEY` | Deepgram speech-to-text / real-time voice sessions API key. | Optional |
27
- | `UPSTASH_REDIS_REST_URL` / `TOKEN` | Enables remote multi-instance Redis memory & scheduling. | Optional |
28
- | `AWS_ACCESS_KEY_ID` / `SECRET` / `REGION` | AWS S3 credentials for high-performance cloud backups. | Optional |
29
- | `GOOGLE_APPLICATION_CREDENTIALS` | Path to Google Cloud Service Account json for GCS tools. | Optional |
30
- | `BLOB_READ_WRITE_TOKEN` | Vercel Blob read/write credentials. | Optional |
31
- | `CORPORATE_WIKI_PROVIDER` | Set to `supermemory` or `upstash` (vector store engine fallback). | Optional |
32
- | `SUPERMEMORY_API_KEY` | Integrates corporate wiki to your SuperMemory dashboard. | Optional |
33
- | `UPSTASH_VECTOR_REST_URL` / `TOKEN` | Upstash Vector credentials for semantic blackboard wiki index. | Optional |
34
-
35
- ## Quick start (Node / Next.js server)
36
-
37
- ```ts
38
- import { createZilMate } from 'zilmate/server';
39
-
40
- const zilmate = createZilMate({
41
- sessionId: 'dashboard-user-123',
42
- onProgress: (event) => console.log(event.type, event.label),
43
- });
44
-
45
- const { text } = await zilmate.manager({ message: 'Summarize my open jobs and suggest next steps.' });
46
- console.log(text);
47
- ```
48
-
49
- ## Next.js App Router streaming chat route
50
-
51
- Create `app/api/zilmate/route.ts`:
52
-
53
- ```ts
54
- import { createZilMate } from 'zilmate/server';
55
-
56
- export const runtime = 'nodejs';
57
- export const maxDuration = 120;
58
-
59
- export async function POST(request: Request) {
60
- const { message, sessionId = 'web-default' } = await request.json();
61
-
62
- const encoder = new TextEncoder();
63
- const stream = new ReadableStream({
64
- async start(controller) {
65
- const send = (payload: unknown) => {
66
- controller.enqueue(encoder.encode(`${JSON.stringify(payload)}\n`));
67
- };
68
-
69
- const zilmate = createZilMate({
70
- sessionId,
71
- onProgress: (event) => send({ type: 'progress', event }),
72
- });
73
-
74
- try {
75
- const { text } = await zilmate.manager({ message });
76
- send({ type: 'done', text });
77
- } catch (error) {
78
- send({
79
- type: 'error',
80
- message: error instanceof Error ? error.message : String(error),
81
- });
82
- } finally {
83
- controller.close();
84
- }
85
- },
86
- });
87
-
88
- return new Response(stream, {
89
- headers: {
90
- 'Content-Type': 'application/x-ndjson',
91
- 'Cache-Control': 'no-cache',
92
- },
93
- });
94
- }
95
- ```
96
-
97
- Client hook (React):
98
-
99
- ```tsx
100
- 'use client';
101
-
102
- import { useState } from 'react';
103
-
104
- export function ZilMateChat() {
105
- const [input, setInput] = useState('');
106
- const [reply, setReply] = useState('');
107
- const [progress, setProgress] = useState<string[]>([]);
108
-
109
- async function send() {
110
- setProgress([]);
111
- const res = await fetch('/api/zilmate', {
112
- method: 'POST',
113
- headers: { 'Content-Type': 'application/json' },
114
- body: JSON.stringify({ message: input, sessionId: 'web-1' }),
115
- });
116
-
117
- const reader = res.body!.getReader();
118
- const decoder = new TextDecoder();
119
- let buffer = '';
120
-
121
- while (true) {
122
- const { done, value } = await reader.read();
123
- if (done) break;
124
- buffer += decoder.decode(value, { stream: true });
125
- const lines = buffer.split('\n');
126
- buffer = lines.pop() ?? '';
127
- for (const line of lines) {
128
- if (!line.trim()) continue;
129
- const chunk = JSON.parse(line);
130
- if (chunk.type === 'progress') setProgress((p) => [...p, chunk.event.label]);
131
- if (chunk.type === 'done') setReply(chunk.text);
132
- }
133
- }
134
- }
135
-
136
- return (
137
- <div>
138
- <textarea value={input} onChange={(e) => setInput(e.target.value)} />
139
- <button onClick={send}>Ask ZilMate</button>
140
- <ul>{progress.map((p) => <li key={p}>{p}</li>)}</ul>
141
- <pre>{reply}</pre>
142
- </div>
143
- );
144
- }
145
- ```
146
-
147
- ## Subagents
148
-
149
- The manager orchestrates specialized subagents. Call them directly when you do not need full orchestration.
150
-
151
- | Method | Agent | Best for |
152
- |--------|-------|----------|
153
- | `manager()` | Main orchestrator | General tasks, routing, tools, memory |
154
- | `coding()` | Coding agent + appBuilder + qaIntegration | Repo edits, builds, tests, patches |
155
- | `imageAgent()` | Image director | Prompt refinement + generation/editing |
156
- | `goalManager()` | Goal planner | Break goals into steps and schedules |
157
- | `research()` | Docs/web research | Sourced answers |
158
- | `help()` | Quick help | Usage and troubleshooting |
159
- | `post()` | Copywriter | Short social/status posts |
160
-
161
- ### Coding agent with sub-coders
162
-
163
- ```ts
164
- const zilmate = createZilMate({ sessionId: 'repo-session' });
165
-
166
- const { text } = await zilmate.coding({
167
- prompt: [
168
- 'In this Next.js repo:',
169
- '1) Add a /api/health route',
170
- '2) Run typecheck',
171
- '3) Return files changed and test output',
172
- ].join('\n'),
173
- });
174
- ```
175
-
176
- Internally, the coding agent can delegate to:
177
-
178
- - **appBuilder** — full app/game/UI implementation
179
- - **qaIntegration** — tests, build fixes, release checks
180
-
181
- It also uses **code intelligence tools**: `grepCodebase`, `reviewWorkingTree`, `explainSymbol`, `scaffoldFiles`, `runProjectChecks`.
182
-
183
- ### Image director
184
-
185
- ```ts
186
- const { text } = await zilmate.imageAgent({
187
- prompt: 'Product hero image: dark SaaS dashboard on laptop, cyan accent, no text gibberish, 16:9',
188
- });
189
- ```
190
-
191
- The image agent runs `enhanceImagePrompt` then `generateImage` for precise visuals.
192
-
193
- ## Agentic features (10x differentiators)
194
-
195
- ### 1. Situational awareness
196
-
197
- Before major work, the manager can call `getSituationBrief` (cwd, git, workspace, models, jobs, memory, projects). Use directly:
198
-
199
- ```ts
200
- const brief = await zilmate.situation({ sessionId: 'default' });
201
- console.log(brief.git, brief.recentJobs, brief.models);
202
- ```
203
-
204
- ### 2. Session continuity (handoffs)
205
-
206
- Resume work across sessions:
207
-
208
- ```ts
209
- const handoff = await zilmate.handoff({ sessionId: 'default' });
210
- if (handoff) {
211
- await zilmate.manager({
212
- message: `Continue from handoff:\n${handoff.summary}\nNext: ${handoff.nextActions.join(', ')}`,
213
- });
214
- }
215
- ```
216
-
217
- The manager can also call `generateSessionHandoff` / `saveSessionHandoff` before ending a long task.
218
-
219
- ### 3. Decentralized Swarm (Joint War Rooms)
220
-
221
- ZilMate organizes 30+ specialized AI agents (such as `frontendArchitect`, `aiSeoStrategist`, `croSpecialist`) across 6 core corporate divisions. Rather than routing all sub-tasks through a central orchestrator, specialists coordinate horizontally:
222
-
223
- - **Joint War Rooms (`collaborateWithPeer`)**: Specialists can directly instantiate peer specialists, pass context, and negotiate schemas, payloads, or creatives in-session.
224
-
225
- ```ts
226
- const { text } = await zilmate.swarm({
227
- role: 'frontendArchitect',
228
- prompt: 'Collaborate with backendArchitect to define the lead payload contract.',
229
- });
230
- ```
231
-
232
- ### 4. Semantic Corporate Wiki (Shared Blackboard)
233
-
234
- Every strategic design document, finalized deliverable, and API contract is indexed into a shared knowledge base, serving as a semantic blackboard:
235
-
236
- - **Multi-Provider Backend**: Supports `supermemory`, `upstash` (Vector DB), or auto-falls back to a local keyword-search JSON database in the workspace.
237
- - **Methods**: `queryCorporateWiki(query, limit)` / `publishToCorporateWiki(title, content, tags)`.
238
-
239
- ```ts
240
- await zilmate.publishToWiki({
241
- title: 'Lead Schema',
242
- content: 'id: string, email: string, source: string',
243
- tags: ['api', 'schema']
244
- });
245
-
246
- const results = await zilmate.queryWiki({ query: 'Lead Schema' });
247
- ```
248
-
249
- ### 5. Autonomous Sandbox Dev Loops
250
-
251
- The coding and QA specialists utilize a self-healing sandbox execution loop to run verification checks on local edits:
252
-
253
- - Compiles local code and executes automated test suites (`npx playwright test` or custom runners).
254
- - Captures compiler diagnostics and assertion stack traces, automatically self-repairing local patches iteratively in-place until the build is fully clean.
255
-
256
- ### 6. High-Performance Host Utility Tool Suites
257
-
258
- The agent manager registers robust, secure, and fully sandboxed cross-platform utility suites to run system-level diagnostic and file operations directly:
259
-
260
- - **⚙️ DevOps Suite**: Explores docker containers, fetches live logs, and manages service nodes (`listDockerContainers`, `getDockerContainerLogs`, `controlDockerContainer`). Safely checks configuration integrity (`validateEnv`).
261
- - **🛡️ SysOps Suite**: Probes open ports, resolves pings, runs trace-routing hops, and securely inspects local SQLite schemas (`listOpenPorts`, `pingHost`, `traceRoute`, `getDatabaseSchema`).
262
- - **☁️ Multi-Cloud Storage**: Seamlessly uploads large payloads, dumps, and reports to AWS S3, GCS, or Vercel Blob using a tiered SDK client, CLI native commands, or custom instructions fallback.
263
- - **🎥 Multimedia Processing**: Invokes local FFmpeg utilities to transcode videos, extract audio tracks, and run AI speech-to-text transcription fallback-layers (`transcodeVideo`, `extractAudio`, `speechToText`).
264
-
265
- ## Model selection
266
-
267
- CLI users run `/model pick`. In code, persist selections to the workspace:
268
-
269
- ```ts
270
- import { applyStoredModelSelections, saveModelSelection } from 'zilmate/server';
271
-
272
- await applyStoredModelSelections();
273
- await saveModelSelection('manager', 'anthropic/claude-sonnet-4');
274
- await saveModelSelection('coding', 'openai/gpt-5.4-mini');
275
- ```
276
-
277
- Models are stored in `~/Downloads/ZilMate/config/models.json` (or `ZILMATE_WORKSPACE`).
278
-
279
- ## Memory
280
-
281
- ```ts
282
- await zilmate.remember({ text: 'User prefers pnpm and App Router', tags: ['prefs'] });
283
- const hits = await zilmate.recall({ query: 'package manager', limit: 5 });
284
- ```
285
-
286
- ## Background jobs
287
-
288
- ```ts
289
- const job = await zilmate.createJob({
290
- task: 'Weekly summary of GitHub PRs',
291
- schedule: '0 9 * * 1',
292
- });
293
-
294
- await zilmate.runDueJobs();
295
- const logs = await zilmate.getJobLogs(job.id);
296
- ```
297
-
298
- Expose webhooks for QStash:
299
-
300
- ```ts
301
- // app/api/jobs/webhook/route.ts
302
- import { createZilMate } from 'zilmate/server';
303
-
304
- export async function POST(req: Request) {
305
- const body = await req.json();
306
- const zilmate = createZilMate();
307
- const job = await zilmate.handleJobWebhook(body, process.env.ZILMATE_JOB_WEBHOOK_SECRET);
308
- return Response.json({ ok: true, jobId: job.id });
309
- }
310
- ```
311
-
312
- Use `zilmate jobs listen --tunnel` (Cloudflare quick tunnel) during local development.
313
-
314
- ## Voice (Deepgram)
315
-
316
- ```ts
317
- const session = await zilmate.startVoiceSession({
318
- onProgress: (e) => console.log(e.label),
319
- });
320
-
321
- // session exposes Deepgram agent wiring — see src/voice/deepgram.ts
322
- console.log(session.config.listenModel);
323
- await session.close?.();
324
- ```
325
-
326
- ## Confirmation in server contexts
327
-
328
- Destructive tools require explicit approval. Provide a handler:
329
-
330
- ```ts
331
- import type { ConfirmationHandler } from 'zilmate/server';
332
-
333
- const confirm: ConfirmationHandler = async (request) => {
334
- // In a web app, push to UI and await user click
335
- console.log('Approve?', request.message);
336
- return true;
337
- };
338
-
339
- const zilmate = createZilMate({ confirm });
340
- ```
341
-
342
- ## Exports reference
343
-
344
- ```ts
345
- import {
346
- createZilMate,
347
- chat,
348
- help,
349
- post,
350
- research,
351
- image,
352
- applyStoredModelSelections,
353
- buildSituationBrief,
354
- loadSessionHandoff,
355
- clearSessionApprovals,
356
- } from 'zilmate/server';
357
- ```
358
-
359
- ## CLI parity
360
-
361
- | CLI | SDK |
362
- |-----|-----|
363
- | `zilmate talk` | `createZilMate().manager()` |
364
- | `zilmate coding "..."` | `createZilMate().coding()` |
365
- | `zilmate heal` | manager + heal tools (via manager) |
366
- | `zilmate jobs worker` | `runDueJobs()` + worker process |
367
- | `/model pick` | `saveModelSelection()` |
368
- | `zilmate doctor` | Runs diagnostics CLI locally |
369
- | `zilmate setup` | Runs interactive setup CLI locally |
370
-
371
- ## Production checklist
372
-
373
- 1. Run `zilmate setup` once per environment (merge-safe).
374
- 2. Set `ZILMATE_WORKSPACE` for durable notebook/knowledge/skills.
375
- 3. Enable Redis for multi-instance memory and jobs.
376
- 4. Use QStash + Cloudflare tunnel for hosted schedules.
377
- 5. Never expose `AI_GATEWAY_API_KEY` to the browser — keep SDK calls on the server.
378
-
379
- ## Learn more
380
-
381
- - Repository: https://github.com/zester4/zilmate
382
- - Agent skill: `plugins/zilmate/skills/zilmate/SKILL.md`
383
- - AI SDK patterns: https://sdk.vercel.ai/docs
1
+ # 🌌 ZilMate SDK Master Portal
2
+
3
+ Welcome to the **ZilMate SDK**—the production-grade agentic engineering middleware. Expose autonomous AI software engineers, parallel decentralized swarms, semantic blackboard systems, durable background schedulers, and sandboxed host utilities inside your Node.js, Next.js, and backend server runtimes.
4
+
5
+ ```
6
+ ┌──────────────────────────────────────┐
7
+ │ ZilMate Master Core SDK │
8
+ └──────────────────┬───────────────────┘
9
+
10
+ ┌─────────────────────────────┼─────────────────────────────┐
11
+ ▼ ▼ ▼
12
+ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
13
+ │ Introduction │ │ Quickstart & UI │ │ The Swarm │
14
+ │ [introduction] │ │ [quickstart] │ │ [swarm] │
15
+ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘
16
+ │ │ │
17
+ ├─────────────────────────────┼─────────────────────────────┤
18
+ ▼ ▼ ▼
19
+ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
20
+ │ Orchestration │ │ Coding Suite │ │ Semantic Wiki │
21
+ │ [orchestrator] │ │ [coding-agent] │ │ [wiki-memory] │
22
+ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘
23
+ │ │ │
24
+ └─────────────────────────────┼─────────────────────────────┘
25
+
26
+ ┌──────────────────┐ ┌──────────────────┐
27
+ │ Host Utilities │ │ Cron Schedulers│
28
+ [host-utilities] │ │[jobs-scheduling]
29
+ └──────────────────┘ └──────────────────┘
30
+ ```
31
+
32
+ ---
33
+
34
+ ## 📚 Complete SDK Documentation
35
+
36
+ The SDK documentation is split into specialized, deep-dive chapters. Explore each module to see copy-pasteable TypeScript code, design directives, and execution telemetry.
37
+
38
+ 1. **[🌌 1. Architectural Introduction](file:///c:/Users/mseyy/Downloads/zilo-manager/sdk/introduction.md)**
39
+ - High-level multi-agent flow, system dependencies, core engines, and complete `.env` variables reference table.
40
+ 2. **[⚡ 2. 3-Minute Quickstart & React UI](file:///c:/Users/mseyy/Downloads/zilo-manager/sdk/quickstart.md)**
41
+ - Package install instructions, server initialization, typed Next.js App Router streaming endpoints (SSE/NDJSON), and glassmorphic Chat UI.
42
+ 3. **[🎯 3. Manager Orchestrator & Safety Approvals](file:///c:/Users/mseyy/Downloads/zilo-manager/sdk/orchestrator.md)**
43
+ - Manager `.manager()` vs `.chat()`, situational awareness diagnostics, session handoffs, and intercepting restricted tools with asynchronous human-in-the-loop approvals.
44
+ 4. **[🛠️ 4. Autonomous Engineering & Coding Loops](file:///c:/Users/mseyy/Downloads/zilo-manager/sdk/coding-agent.md)**
45
+ - Programmatic repo refactoring via `.coding()`, App Builder styling directives (HSL palettes, bento layouts), and QA's self-healing compilation loops.
46
+ 5. **[🐝 5. Decentralized Swarms & Joint War Rooms](file:///c:/Users/mseyy/Downloads/zilo-manager/sdk/swarm.md)**
47
+ - Running 30+ specialists in parallel, Joint War Room Horizontal Collaboration (`collaborateWithPeer`), and exporting glassmorphic trace dashboards.
48
+ 6. **[💾 6. Semantic Wiki & Long-Term Memory](file:///c:/Users/mseyy/Downloads/zilo-manager/sdk/wiki-memory.md)**
49
+ - Long-term episodic memory (`remember`/`recall`), the Shared Blackboard Wiki pattern, and configuring SuperMemory, Upstash, or Local JSON vector stores.
50
+ 7. **[⚙️ 7. Sandboxed Host Utilities](file:///c:/Users/mseyy/Downloads/zilo-manager/sdk/host-utilities.md)**
51
+ - Safety sandbox system calls: DevOps Docker container logs, SysOps networking pings/ports, tiered AWS S3/GCS/Vercel Cloud Storage, and FFmpeg transcoder engines.
52
+ 8. **[📅 8. Durable Jobs & Background Scheduling](file:///c:/Users/mseyy/Downloads/zilo-manager/sdk/jobs-scheduling.md)**
53
+ - Registering recurring background jobs, enqueuing delayed tasks, setting up serverless QStash webhook endpoints, and running local developer tunnels.
54
+ 9. **[💸 9. Swarm Capability Expansions](file:///c:/Users/mseyy/Downloads/zilo-manager/sdk/expansions.md)**
55
+ - Swarm Virtual Treasury budget controls, proactive incoming webhooks listener routing, and automated trace-driven prompt self-learning (RLAIH).
56
+
57
+ ---
58
+
59
+ ## 📦 Core Server Exports Reference
60
+
61
+ Initialize the SDK by importing the server layer. The primary export is `createZilMate`.
62
+
63
+ ```typescript
64
+ import {
65
+ createZilMate,
66
+ chat,
67
+ help,
68
+ post,
69
+ research,
70
+ image,
71
+ applyStoredModelSelections,
72
+ buildSituationBrief,
73
+ loadSessionHandoff,
74
+ clearSessionApprovals,
75
+ } from 'zilmate/server';
76
+ ```
77
+
78
+ ### Options Object (`ZilMateOptions`)
79
+
80
+ When calling `createZilMate(options)`, pass the following parameters:
81
+
82
+ ```typescript
83
+ export type ZilMateOptions = {
84
+ sessionId?: string; // Isolates conversational threads, memories, and job tracking
85
+ onProgress?: (event: ProgressEvent) => void; // Captures thinking states and tool calls in real-time
86
+ confirm?: ConfirmationHandler; // Attaches a custom interceptor for restricted system tools
87
+ };
88
+ ```
89
+
90
+ ---
91
+
92
+ ## 🔄 CLI Parity Reference
93
+
94
+ The SDK exposes programmatic parity for every core CLI feature, enabling developers to easily migrate CLI routines to server routes:
95
+
96
+ | CLI Command | SDK Equivalent Call | Primary Focus |
97
+ |:---|:---|:---|
98
+ | `zilmate talk` | `createZilMate().manager({ message })` | General planning and open-ended tool loops |
99
+ | `zilmate coding "..."` | `createZilMate().coding({ prompt })` | Full-stack implementation and self-healing builds |
100
+ | `zilmate jobs worker` | `createZilMate().runDueJobs()` | Triggers background cron tasks |
101
+ | `zilmate optimize` | `runPostSessionOptimization()` | Executes trace-guided prompt self-tuning and harvesting |
102
+ | `/model pick` | `saveModelSelection(agent, model)` | Persists custom LLM routing settings |
103
+ | `zilmate doctor` | (Diagnostics built-in to `situation()`) | Validates environment, folders, and networks |
104
+ | `zilmate setup` | (Automatic on `createZilMate()` initialization) | Bootstraps configuration files and path trees |
105
+
106
+ ---
107
+
108
+ ## 🛡️ Production Security Checklist
109
+
110
+ When deploying ZilMate in highly-available, production-facing systems, ensure you adhere to the following best practices:
111
+
112
+ > [!CAUTION]
113
+ > **Keep Credentials Safe**: Never import or invoke the server-level ZilMate SDK inside client-side components (React/Next.js client code). Always route requests through secure Next.js API Routes, Express nodes, or serverless functions to avoid exposing your model gateway keys or system tokens to the browser console.
114
+
115
+ 1. **Verify Environment Sandbox**: Ensure that commands executed by agents are run inside sandboxed containers or restricted-user environments to avoid shell injections.
116
+ 2. **Leverage Persistent Redis**: For stateless, horizontally-scaled environments (like AWS Lambda or Vercel Serverless), configure `UPSTASH_REDIS_REST_URL` to handle distributed lock states, scheduler crons, and thread histories.
117
+ 3. **Register Custom Confirmation Interceptors**: Always attach a `confirm` handler when exposing system-level Docker, file modification, or shell tools to end-users.
118
+ 4. **Setup Secure Tunneling**: During local webhook testing (with QStash), run `npx zilmate jobs listen --tunnel` to securely proxy requests through Cloudflare tunnels instead of exposing raw router ports.
@@ -392,12 +392,12 @@ export declare function createCodingAgent(runId?: string): Promise<ToolLoopAgent
392
392
  created: boolean;
393
393
  }>;
394
394
  moveCopyRename: import("ai").Tool<{
395
- operation: "move" | "copy" | "rename";
395
+ operation: "rename" | "move" | "copy";
396
396
  from: string;
397
397
  to: string;
398
398
  overwrite?: boolean | undefined;
399
399
  }, {
400
- operation: "move" | "copy" | "rename";
400
+ operation: "rename" | "move" | "copy";
401
401
  from: string;
402
402
  to: string;
403
403
  }>;
@@ -1 +1 @@
1
- {"version":3,"file":"coding.agent.d.ts","sourceRoot":"","sources":["../../src/agents/coding.agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,aAAa,EAAQ,MAAM,IAAI,CAAC;AAwItD,wBAAsB,iBAAiB,CAAC,KAAK,SAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA2CxD"}
1
+ {"version":3,"file":"coding.agent.d.ts","sourceRoot":"","sources":["../../src/agents/coding.agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,aAAa,EAAQ,MAAM,IAAI,CAAC;AAoJtD,wBAAsB,iBAAiB,CAAC,KAAK,SAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAmDxD"}