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.
- package/.env.example +2 -0
- package/SDK.md +118 -383
- package/dist/agents/coding.agent.d.ts +2 -2
- package/dist/agents/coding.agent.d.ts.map +1 -1
- package/dist/agents/coding.agent.js +64 -44
- package/dist/agents/coding.agent.js.map +1 -1
- package/dist/agents/finance.agent.d.ts +26 -0
- package/dist/agents/finance.agent.d.ts.map +1 -1
- package/dist/agents/finance.agent.js +2 -1
- package/dist/agents/finance.agent.js.map +1 -1
- package/dist/agents/image.agent.d.ts +42 -0
- package/dist/agents/image.agent.d.ts.map +1 -1
- package/dist/agents/image.agent.js +6 -0
- package/dist/agents/image.agent.js.map +1 -1
- package/dist/agents/manager.d.ts +4 -3
- package/dist/agents/manager.d.ts.map +1 -1
- package/dist/agents/manager.js +76 -17
- package/dist/agents/manager.js.map +1 -1
- package/dist/agents/security.agent.d.ts +1 -1
- package/dist/agents/swarm/registry.d.ts.map +1 -1
- package/dist/agents/swarm/registry.js +7 -4
- package/dist/agents/swarm/registry.js.map +1 -1
- package/dist/cli/confirm.d.ts +3 -1
- package/dist/cli/confirm.d.ts.map +1 -1
- package/dist/cli/confirm.js +9 -2
- package/dist/cli/confirm.js.map +1 -1
- package/dist/cli/doctor.d.ts.map +1 -1
- package/dist/cli/doctor.js +36 -1
- package/dist/cli/doctor.js.map +1 -1
- package/dist/cli/format.d.ts.map +1 -1
- package/dist/cli/format.js +11 -2
- package/dist/cli/format.js.map +1 -1
- package/dist/cli/interactive.d.ts.map +1 -1
- package/dist/cli/interactive.js +69 -8
- package/dist/cli/interactive.js.map +1 -1
- package/dist/cli/jobs.d.ts.map +1 -1
- package/dist/cli/jobs.js +28 -1
- package/dist/cli/jobs.js.map +1 -1
- package/dist/cli/setup.d.ts +7 -0
- package/dist/cli/setup.d.ts.map +1 -1
- package/dist/cli/setup.js +16 -3
- package/dist/cli/setup.js.map +1 -1
- package/dist/cli/tunnel.d.ts +2 -0
- package/dist/cli/tunnel.d.ts.map +1 -1
- package/dist/cli/tunnel.js +1 -1
- package/dist/cli/tunnel.js.map +1 -1
- package/dist/config/env.d.ts +3 -0
- package/dist/config/env.d.ts.map +1 -1
- package/dist/config/env.js +23 -28
- package/dist/config/env.js.map +1 -1
- package/dist/daemon/service.d.ts.map +1 -1
- package/dist/daemon/service.js +808 -11
- package/dist/daemon/service.js.map +1 -1
- package/dist/index.js +94 -9
- package/dist/index.js.map +1 -1
- package/dist/observability/traces.js +7 -6
- package/dist/observability/traces.js.map +1 -1
- package/dist/runtime/confirm.d.ts.map +1 -1
- package/dist/runtime/confirm.js +48 -0
- package/dist/runtime/confirm.js.map +1 -1
- package/dist/runtime/swarm.d.ts.map +1 -1
- package/dist/runtime/swarm.js +9 -0
- package/dist/runtime/swarm.js.map +1 -1
- package/dist/tools/filesystem.tool.d.ts +2 -2
- package/dist/tools/finance.tool.d.ts +57 -0
- package/dist/tools/finance.tool.d.ts.map +1 -1
- package/dist/tools/finance.tool.js +208 -0
- package/dist/tools/finance.tool.js.map +1 -1
- package/dist/tools/osint.tool.d.ts +2 -2
- package/dist/tools/setup-assistant.tool.d.ts +1 -1
- package/dist/tools/shell.tool.d.ts.map +1 -1
- package/dist/tools/shell.tool.js +17 -0
- package/dist/tools/shell.tool.js.map +1 -1
- package/dist/voice/deepgram.d.ts.map +1 -1
- package/dist/voice/deepgram.js +1 -0
- package/dist/voice/deepgram.js.map +1 -1
- package/dist/voice/types.d.ts +1 -0
- package/dist/voice/types.d.ts.map +1 -1
- package/package.json +2 -1
- 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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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: "
|
|
395
|
+
operation: "rename" | "move" | "copy";
|
|
396
396
|
from: string;
|
|
397
397
|
to: string;
|
|
398
398
|
overwrite?: boolean | undefined;
|
|
399
399
|
}, {
|
|
400
|
-
operation: "
|
|
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;
|
|
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"}
|