@dcyfr/ai 3.4.0 → 3.5.1
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/CHANGELOG.md +428 -0
- package/README.md +181 -213
- package/dist/.tsbuildinfo +1 -1
- package/dist/ai/delegation/execution-mode-dashboard.d.ts.map +1 -1
- package/dist/ai/delegation/execution-mode-dashboard.js +4 -5
- package/dist/ai/delegation/execution-mode-dashboard.js.map +1 -1
- package/dist/ai/delegation/resolve-log-root.d.ts +38 -0
- package/dist/ai/delegation/resolve-log-root.d.ts.map +1 -0
- package/dist/ai/delegation/resolve-log-root.js +73 -0
- package/dist/ai/delegation/resolve-log-root.js.map +1 -0
- package/dist/ai/delegation/session-checkpoint.d.ts +1 -1
- package/dist/ai/delegation/session-checkpoint.d.ts.map +1 -1
- package/dist/ai/delegation/session-checkpoint.js +5 -8
- package/dist/ai/delegation/session-checkpoint.js.map +1 -1
- package/dist/ai/delegation/session-manager.d.ts.map +1 -1
- package/dist/ai/delegation/session-manager.js +4 -5
- package/dist/ai/delegation/session-manager.js.map +1 -1
- package/dist/ai/generated/version.d.ts +1 -1
- package/dist/ai/generated/version.js +1 -1
- package/dist/ai/mcp/index.d.ts +2 -0
- package/dist/ai/mcp/index.d.ts.map +1 -1
- package/dist/ai/mcp/index.js +1 -0
- package/dist/ai/mcp/index.js.map +1 -1
- package/package.json +13 -7
package/README.md
CHANGED
|
@@ -9,10 +9,10 @@
|
|
|
9
9
|
status: active
|
|
10
10
|
name: dcyfr-ai
|
|
11
11
|
description: Portable AI agent harness with plugin architecture
|
|
12
|
-
last_validated: 2026-
|
|
12
|
+
last_validated: 2026-07-11
|
|
13
13
|
-->
|
|
14
14
|
|
|
15
|
-
[](https://deepwiki.com/dcyfr/dcyfr-ai)
|
|
15
|
+
[](https://deepwiki.com/dcyfr-labs/dcyfr-ai)
|
|
16
16
|
[](https://peerlist.io/dcyfr/project/dcyfr-ai)
|
|
17
17
|
|
|
18
18
|
[](https://www.npmjs.com/package/@dcyfr/ai)
|
|
@@ -55,7 +55,7 @@ Portable AI agent harness with plugin architecture for managing multiple AI prov
|
|
|
55
55
|
[](https://bundlephobia.com/package/@dcyfr/ai)
|
|
56
56
|
|
|
57
57
|
- **Weekly Downloads:** Check [npm stats](https://www.npmjs.com/package/@dcyfr/ai)
|
|
58
|
-
- **Dependencies:**
|
|
58
|
+
- **Dependencies:** 27 production dependencies
|
|
59
59
|
- **Bundle Size:** See badge above ([](https://bundlephobia.com/package/@dcyfr/ai))
|
|
60
60
|
- **TypeScript:** Full type definitions included
|
|
61
61
|
- **ESM Support:** ✅ Full ESM modules with tree shaking
|
|
@@ -190,17 +190,27 @@ const model = new ChatOpenAI({ temperature: 0.9 });
|
|
|
190
190
|
const response = await model.call([new HumanMessage("Hello")]);
|
|
191
191
|
|
|
192
192
|
// @dcyfr/ai (after)
|
|
193
|
-
import {
|
|
193
|
+
import {
|
|
194
|
+
AgentRuntime,
|
|
195
|
+
ProviderRegistry,
|
|
196
|
+
TelemetryEngine,
|
|
197
|
+
getMemory,
|
|
198
|
+
} from "@dcyfr/ai";
|
|
194
199
|
|
|
195
|
-
const runtime = new AgentRuntime(
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
+
const runtime = new AgentRuntime(
|
|
201
|
+
"assistant",
|
|
202
|
+
new ProviderRegistry({
|
|
203
|
+
primaryProvider: "anthropic",
|
|
204
|
+
fallbackChain: ["anthropic", "ollama"],
|
|
205
|
+
autoReturn: true,
|
|
206
|
+
healthCheckInterval: 60_000,
|
|
207
|
+
}),
|
|
208
|
+
getMemory(),
|
|
209
|
+
new TelemetryEngine(),
|
|
210
|
+
);
|
|
200
211
|
|
|
201
|
-
const
|
|
202
|
-
|
|
203
|
-
});
|
|
212
|
+
const result = await runtime.execute({ task: "Hello" });
|
|
213
|
+
console.log(result.output);
|
|
204
214
|
```
|
|
205
215
|
|
|
206
216
|
**Key Differences:**
|
|
@@ -226,21 +236,33 @@ const { text } = await generateText({
|
|
|
226
236
|
});
|
|
227
237
|
|
|
228
238
|
// @dcyfr/ai (after)
|
|
229
|
-
import {
|
|
239
|
+
import {
|
|
240
|
+
AgentRuntime,
|
|
241
|
+
ProviderRegistry,
|
|
242
|
+
TelemetryEngine,
|
|
243
|
+
ValidationFramework,
|
|
244
|
+
getMemory,
|
|
245
|
+
} from "@dcyfr/ai";
|
|
230
246
|
|
|
231
|
-
const runtime = new AgentRuntime(
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
247
|
+
const runtime = new AgentRuntime(
|
|
248
|
+
"assistant",
|
|
249
|
+
new ProviderRegistry({
|
|
250
|
+
primaryProvider: "anthropic",
|
|
251
|
+
fallbackChain: ["anthropic", "ollama"],
|
|
252
|
+
autoReturn: true,
|
|
253
|
+
healthCheckInterval: 60_000,
|
|
254
|
+
}),
|
|
255
|
+
getMemory(),
|
|
256
|
+
new TelemetryEngine(),
|
|
257
|
+
);
|
|
235
258
|
|
|
236
|
-
const
|
|
237
|
-
|
|
238
|
-
});
|
|
259
|
+
const result = await runtime.execute({ task: "Hello" });
|
|
260
|
+
console.log(result.output);
|
|
239
261
|
|
|
240
262
|
// Bonus: Built-in validation
|
|
241
263
|
const validator = new ValidationFramework();
|
|
242
264
|
const report = await validator.validate({
|
|
243
|
-
/*
|
|
265
|
+
/* ValidationContext */
|
|
244
266
|
});
|
|
245
267
|
```
|
|
246
268
|
|
|
@@ -256,172 +278,154 @@ const report = await validator.validate({
|
|
|
256
278
|
|
|
257
279
|
---
|
|
258
280
|
|
|
259
|
-
## Getting Started with AgentRuntime
|
|
281
|
+
## Getting Started with AgentRuntime
|
|
282
|
+
|
|
283
|
+
`AgentRuntime` executes multi-step tasks against the provider registry, with memory retrieval, tool execution, and telemetry built in.
|
|
260
284
|
|
|
261
285
|
### Prerequisites
|
|
262
286
|
|
|
263
287
|
```bash
|
|
264
|
-
# Node.js
|
|
288
|
+
# Node.js 20+ required (package.json engines; CI tests on Node 24)
|
|
265
289
|
node --version
|
|
266
290
|
|
|
267
291
|
# Install @dcyfr/ai
|
|
268
292
|
npm install @dcyfr/ai
|
|
269
293
|
|
|
270
|
-
# Optional:
|
|
271
|
-
export
|
|
272
|
-
export
|
|
294
|
+
# Optional: enable remote providers
|
|
295
|
+
export ANTHROPIC_API_KEY=your_anthropic_key # enables the "anthropic" provider
|
|
296
|
+
export GITHUB_TOKEN=your_github_token # enables the "github-models" provider
|
|
273
297
|
```
|
|
274
298
|
|
|
275
299
|
### 1. Basic AgentRuntime Setup
|
|
276
300
|
|
|
301
|
+
`AgentRuntime` takes positional arguments: an agent name, a `ProviderRegistry`, a memory instance, a `TelemetryEngine`, and an optional `RuntimeConfig`.
|
|
302
|
+
|
|
277
303
|
```typescript
|
|
278
304
|
import {
|
|
279
305
|
AgentRuntime,
|
|
280
306
|
ProviderRegistry,
|
|
281
307
|
TelemetryEngine,
|
|
282
|
-
|
|
308
|
+
getMemory,
|
|
283
309
|
} from "@dcyfr/ai";
|
|
284
310
|
|
|
285
311
|
// Initialize components
|
|
286
|
-
const
|
|
287
|
-
|
|
288
|
-
|
|
312
|
+
const providers = new ProviderRegistry({
|
|
313
|
+
primaryProvider: "anthropic",
|
|
314
|
+
fallbackChain: ["anthropic", "github-models", "ollama"],
|
|
315
|
+
autoReturn: true,
|
|
316
|
+
healthCheckInterval: 60_000,
|
|
317
|
+
});
|
|
289
318
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
memory,
|
|
294
|
-
telemetry: telemetryEngine,
|
|
319
|
+
const telemetry = new TelemetryEngine({
|
|
320
|
+
storage: "file",
|
|
321
|
+
basePath: "./data/telemetry",
|
|
295
322
|
});
|
|
296
323
|
|
|
297
|
-
//
|
|
298
|
-
|
|
324
|
+
const memory = getMemory(); // shared DCYFRMemoryImpl singleton (mem0 backend)
|
|
325
|
+
|
|
326
|
+
// Create runtime
|
|
327
|
+
const runtime = new AgentRuntime("assistant", providers, memory, telemetry, {
|
|
328
|
+
maxIterations: 10, // optional RuntimeConfig
|
|
329
|
+
timeout: 120_000,
|
|
330
|
+
});
|
|
299
331
|
```
|
|
300
332
|
|
|
301
|
-
|
|
333
|
+
> **Memory:** `DCYFRMemory` is exported as an interface *type* only. The
|
|
334
|
+
> concrete class is `DCYFRMemoryImpl` (no constructor options), and
|
|
335
|
+
> `getMemory()` returns a shared singleton. The mem0 backend (vector DB, LLM,
|
|
336
|
+
> embedder) is configured via environment/config — see
|
|
337
|
+
> [docs/MEMORY_SETUP.md](./docs/MEMORY_SETUP.md).
|
|
338
|
+
|
|
339
|
+
### 2. Execute a Task
|
|
302
340
|
|
|
303
341
|
```typescript
|
|
304
|
-
|
|
305
|
-
|
|
342
|
+
const result = await runtime.execute({
|
|
343
|
+
task: "Explain quantum computing briefly",
|
|
344
|
+
userId: "user-123", // optional: scopes memory retrieval
|
|
345
|
+
sessionId: "session-456", // optional: telemetry correlation
|
|
346
|
+
});
|
|
306
347
|
|
|
307
348
|
if (result.success) {
|
|
308
349
|
console.log("Output:", result.output);
|
|
309
|
-
console.log(
|
|
350
|
+
console.log(`${result.iterations} iteration(s), $${result.cost.toFixed(4)}`);
|
|
310
351
|
} else {
|
|
311
|
-
console.error(
|
|
352
|
+
console.error(`Failed (${result.outcome}):`, result.error);
|
|
312
353
|
}
|
|
313
354
|
```
|
|
314
355
|
|
|
315
|
-
|
|
356
|
+
`execute()` takes a `TaskContext` (`task`, plus optional `userId`, `sessionId`, `agentId`, `traceId`, `metadata`, `tools`) and returns an `AgentExecutionResult` (`success`, `output`, `error`, `outcome`, `executionTime`, `cost`, `iterations`).
|
|
316
357
|
|
|
317
|
-
|
|
318
|
-
// Task with memory context
|
|
319
|
-
const result = await runtime.executeTask(
|
|
320
|
-
"Continue the quantum computing explanation",
|
|
321
|
-
{
|
|
322
|
-
timeout: 30000,
|
|
323
|
-
memoryConfig: {
|
|
324
|
-
maxResults: 10, // Maximum context entries
|
|
325
|
-
minScore: 0.7, // Relevance threshold (0.0-1.0)
|
|
326
|
-
},
|
|
327
|
-
},
|
|
328
|
-
);
|
|
358
|
+
Memory retrieval, injection, and persistence happen automatically when `memoryEnabled` is on (the default); tune it via `RuntimeConfig` (`memoryTimeout`, `memoryRelevanceThreshold`, `workingMemoryEnabled`, `persistWorkingMemory`).
|
|
329
359
|
|
|
330
|
-
|
|
331
|
-
console.log("Previous context used:", result.memoryRetrievalUsed);
|
|
332
|
-
```
|
|
360
|
+
### 3. Tools
|
|
333
361
|
|
|
334
|
-
|
|
362
|
+
Pass tools in the task context; the runtime invokes them during its reasoning loop. Each tool's `execute` receives the input plus a `ToolExecutionContext` with shared working memory and a `queryMemory` helper.
|
|
335
363
|
|
|
336
364
|
```typescript
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
);
|
|
351
|
-
|
|
352
|
-
console.log("Working memory keys:", Array.from(workingMemory.keys()));
|
|
365
|
+
import { readFile } from "node:fs/promises";
|
|
366
|
+
import { z } from "zod";
|
|
367
|
+
|
|
368
|
+
const result = await runtime.execute({
|
|
369
|
+
task: "Summarize the project README",
|
|
370
|
+
tools: [
|
|
371
|
+
{
|
|
372
|
+
name: "read_file",
|
|
373
|
+
description: "Read a UTF-8 file from disk",
|
|
374
|
+
schema: z.object({ path: z.string() }),
|
|
375
|
+
execute: async (input) => readFile((input as { path: string }).path, "utf8"),
|
|
376
|
+
},
|
|
377
|
+
],
|
|
378
|
+
});
|
|
353
379
|
```
|
|
354
380
|
|
|
355
|
-
###
|
|
381
|
+
### 4. Hooks
|
|
382
|
+
|
|
383
|
+
Register hooks with `beforeExecute()` / `afterExecute()`. A before-hook receives a `HookContext` (`agentName`, `task`, `userId`, `sessionId`, `timestamp`) and rejects execution by throwing; after-hooks additionally receive the final `AgentExecutionResult`.
|
|
356
384
|
|
|
357
385
|
```typescript
|
|
358
|
-
//
|
|
359
|
-
runtime.
|
|
360
|
-
console.log(`🚀 Starting task: ${task}`);
|
|
386
|
+
// Before-execution hook: throw to reject the task
|
|
387
|
+
runtime.beforeExecute(async (context) => {
|
|
388
|
+
console.log(`🚀 Starting task: ${context.task}`);
|
|
361
389
|
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
return { approved: false, reason: "Sensitive content detected" };
|
|
390
|
+
if (context.task.includes("sensitive")) {
|
|
391
|
+
throw new Error("Sensitive content detected");
|
|
365
392
|
}
|
|
366
|
-
|
|
367
|
-
return { approved: true };
|
|
368
393
|
});
|
|
369
394
|
|
|
370
|
-
//
|
|
371
|
-
runtime.
|
|
372
|
-
console.log(
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
if (success) {
|
|
376
|
-
await customAnalytics.track({
|
|
377
|
-
task: task.substring(0, 50),
|
|
378
|
-
duration: result.duration,
|
|
379
|
-
memoryUsed: result.memoryRetrievalUsed,
|
|
380
|
-
});
|
|
381
|
-
}
|
|
395
|
+
// After-execution hook: observe the result
|
|
396
|
+
runtime.afterExecute(async (context, result) => {
|
|
397
|
+
console.log(
|
|
398
|
+
`✅ "${context.task}" → ${result.outcome} in ${result.executionTime}ms`,
|
|
399
|
+
);
|
|
382
400
|
});
|
|
383
401
|
```
|
|
384
402
|
|
|
385
|
-
###
|
|
403
|
+
### 5. Runtime Events
|
|
386
404
|
|
|
387
|
-
|
|
388
|
-
// Multi-provider setup with fallback
|
|
389
|
-
const runtime = new AgentRuntime({
|
|
390
|
-
providerRegistry: new ProviderRegistry(),
|
|
391
|
-
memory,
|
|
392
|
-
telemetry,
|
|
393
|
-
});
|
|
405
|
+
Subscribe to lifecycle events (task start/finish, LLM calls, tool executions, memory retrieval):
|
|
394
406
|
|
|
395
|
-
|
|
396
|
-
const
|
|
407
|
+
```typescript
|
|
408
|
+
const listener = (event: unknown) => console.log("runtime event:", event);
|
|
397
409
|
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
console.log("Provider used:", lastExecution?.provider);
|
|
410
|
+
runtime.on(listener);
|
|
411
|
+
// ... later
|
|
412
|
+
runtime.off(listener);
|
|
402
413
|
```
|
|
403
414
|
|
|
404
|
-
###
|
|
415
|
+
### 6. Telemetry Monitoring & Analysis
|
|
405
416
|
|
|
406
|
-
|
|
407
|
-
// Get telemetry engine for analytics
|
|
408
|
-
const telemetry = runtime.getTelemetryEngine();
|
|
417
|
+
Use the `TelemetryEngine` instance you constructed the runtime with:
|
|
409
418
|
|
|
410
|
-
|
|
419
|
+
```typescript
|
|
420
|
+
// Recent execution events recorded by the engine
|
|
411
421
|
const events = await telemetry.getEvents();
|
|
412
422
|
console.log(`Total events: ${events.length}`);
|
|
413
423
|
|
|
414
|
-
//
|
|
415
|
-
const
|
|
416
|
-
const hitRate =
|
|
417
|
-
memoryEvents.length > 0
|
|
418
|
-
? memoryEvents.filter((e) => e.memoriesRelevant > 0).length /
|
|
419
|
-
memoryEvents.length
|
|
420
|
-
: 0;
|
|
421
|
-
console.log(`Memory hit rate: ${(hitRate * 100).toFixed(1)}%`);
|
|
424
|
+
// Aggregate per-agent stats over a period
|
|
425
|
+
const stats = await telemetry.getAgentStats("anthropic", "30d");
|
|
422
426
|
```
|
|
423
427
|
|
|
424
|
-
###
|
|
428
|
+
### 7. CLI Dashboard Commands
|
|
425
429
|
|
|
426
430
|
```bash
|
|
427
431
|
# View telemetry dashboard (cost summary + recent activity)
|
|
@@ -443,87 +447,71 @@ npx dcyfr-ai validate-runtime
|
|
|
443
447
|
npx dcyfr-ai telemetry --export usage_data.csv
|
|
444
448
|
```
|
|
445
449
|
|
|
446
|
-
###
|
|
447
|
-
|
|
448
|
-
**OpenAI:**
|
|
450
|
+
### 8. Provider Setup
|
|
449
451
|
|
|
450
|
-
|
|
451
|
-
export OPENAI_API_KEY=sk-your-key-here
|
|
452
|
-
# Supports: gpt-4, gpt-4o, gpt-3.5-turbo
|
|
453
|
-
```
|
|
452
|
+
Providers register automatically inside `ProviderRegistry`; remote providers are enabled when their credentials/endpoints are present:
|
|
454
453
|
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
454
|
+
| Provider | Tier | Enabled by |
|
|
455
|
+
| --------------- | ------------------------------------- | ----------------------------------------------------------------- |
|
|
456
|
+
| `local` | 0 — local OpenAI-compatible endpoint | always (default `LOCAL_LLM_BASE_URL` = `http://localhost:11973/v1`) |
|
|
457
|
+
| `ollama` | 0 — local Ollama | always (default `OLLAMA_HOST` = `http://localhost:11434`) |
|
|
458
|
+
| `workbench` | 1 — private GPU node | `WORKBENCH_BASE_URL` set |
|
|
459
|
+
| `github-models` | 2 — GitHub Models | `GITHUB_TOKEN` set |
|
|
460
|
+
| `anthropic` | 3 — Anthropic API | `ANTHROPIC_API_KEY` set |
|
|
461
461
|
|
|
462
|
-
|
|
462
|
+
Fallback order follows the `fallbackChain` you pass to `ProviderRegistry`; with `autoReturn: true` the registry returns to the primary provider when it recovers.
|
|
463
463
|
|
|
464
464
|
```bash
|
|
465
|
-
#
|
|
465
|
+
# Ollama (local)
|
|
466
466
|
curl -fsSL https://ollama.ai/install.sh | sh
|
|
467
|
+
ollama pull llama3.2
|
|
468
|
+
export OLLAMA_HOST=http://localhost:11434 # optional custom host
|
|
467
469
|
|
|
468
|
-
#
|
|
469
|
-
|
|
470
|
-
# OR: ollama pull codellama, qwen2.5, etc.
|
|
470
|
+
# Anthropic
|
|
471
|
+
export ANTHROPIC_API_KEY=sk-ant-your-key-here
|
|
471
472
|
|
|
472
|
-
#
|
|
473
|
-
export
|
|
473
|
+
# GitHub Models
|
|
474
|
+
export GITHUB_TOKEN=your_github_token
|
|
474
475
|
```
|
|
475
476
|
|
|
476
|
-
###
|
|
477
|
+
### 9. Configuration Examples
|
|
477
478
|
|
|
478
|
-
**Development:**
|
|
479
|
+
**Development (no persistence):**
|
|
479
480
|
|
|
480
481
|
```typescript
|
|
481
|
-
const
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
storage: "memory", // No persistence for dev
|
|
482
|
+
const runtime = new AgentRuntime(
|
|
483
|
+
"dev-assistant",
|
|
484
|
+
new ProviderRegistry({
|
|
485
|
+
primaryProvider: "ollama",
|
|
486
|
+
fallbackChain: ["ollama", "local"],
|
|
487
|
+
autoReturn: false,
|
|
488
|
+
healthCheckInterval: 60_000,
|
|
489
489
|
}),
|
|
490
|
-
|
|
490
|
+
getMemory(),
|
|
491
|
+
new TelemetryEngine(), // defaults to in-memory storage
|
|
492
|
+
);
|
|
491
493
|
```
|
|
492
494
|
|
|
493
|
-
**Production:**
|
|
495
|
+
**Production (file-backed telemetry):**
|
|
494
496
|
|
|
495
497
|
```typescript
|
|
496
|
-
const
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
storage: "sqlite",
|
|
504
|
-
dbPath: "./data/telemetry.db",
|
|
498
|
+
const runtime = new AgentRuntime(
|
|
499
|
+
"prod-assistant",
|
|
500
|
+
new ProviderRegistry({
|
|
501
|
+
primaryProvider: "anthropic",
|
|
502
|
+
fallbackChain: ["anthropic", "github-models", "ollama"],
|
|
503
|
+
autoReturn: true,
|
|
504
|
+
healthCheckInterval: 60_000,
|
|
505
505
|
}),
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
See our comprehensive example: **[Autonomous Research Agent](https://github.com/dcyfr-labs/dcyfr-ai-agents/tree/main/examples/autonomous-research-agent)**
|
|
512
|
-
|
|
513
|
-
```bash
|
|
514
|
-
cd dcyfr-ai-agents/examples/autonomous-research-agent
|
|
515
|
-
npm run demo -- --topic "quantum computing applications"
|
|
506
|
+
getMemory(),
|
|
507
|
+
new TelemetryEngine({ storage: "file", basePath: "./data/telemetry" }),
|
|
508
|
+
{ persistWorkingMemory: true },
|
|
509
|
+
);
|
|
516
510
|
```
|
|
517
511
|
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
- Memory context integration
|
|
522
|
-
- Working memory coordination
|
|
523
|
-
- Hook system extensions
|
|
524
|
-
- Telemetry monitoring
|
|
525
|
-
- Provider fallback handling
|
|
526
|
-
- Configuration management
|
|
512
|
+
> Telemetry storage supports the `"memory"` and `"file"` adapters (or pass your
|
|
513
|
+
> own `StorageAdapter`). Database-backed storage is not implemented yet — see
|
|
514
|
+
> [Known Limitations](#️-known-limitations).
|
|
527
515
|
|
|
528
516
|
---
|
|
529
517
|
|
|
@@ -646,12 +634,11 @@ Framework Defaults → Project Config → Environment Variables
|
|
|
646
634
|
|
|
647
635
|
### Environment Overrides
|
|
648
636
|
|
|
649
|
-
Override any config value with environment variables:
|
|
637
|
+
Override any config value with environment variables. `DCYFR_<PATH>` maps to the lowercased dot-path in the config (e.g. `DCYFR_TELEMETRY_ENABLED` → `telemetry.enabled`):
|
|
650
638
|
|
|
651
639
|
```bash
|
|
652
640
|
DCYFR_TELEMETRY_ENABLED=false
|
|
653
|
-
|
|
654
|
-
DCYFR_AGENTS_DESIGNTOKENS_COMPLIANCE=0.95
|
|
641
|
+
DCYFR_VALIDATION_PARALLEL=true
|
|
655
642
|
```
|
|
656
643
|
|
|
657
644
|
## Plugin System
|
|
@@ -665,7 +652,7 @@ DCYFR comes with specialized validation agents:
|
|
|
665
652
|
- **PageLayout Enforcer** - Validates layout usage patterns
|
|
666
653
|
- **Test Data Guardian** - Prevents production data in tests
|
|
667
654
|
|
|
668
|
-
See `@dcyfr/agents` for specialized DCYFR agents.
|
|
655
|
+
See `@dcyfr/workspace-agents` for specialized DCYFR agents.
|
|
669
656
|
|
|
670
657
|
### Custom Plugins
|
|
671
658
|
|
|
@@ -897,9 +884,9 @@ export const myPlugin = {
|
|
|
897
884
|
|
|
898
885
|
See [docs/PLUGINS.md](./docs/PLUGINS.md) and [examples/plugin-system.ts](./examples/plugin-system.ts) for complete guide.
|
|
899
886
|
|
|
900
|
-
**Q: What's the difference between @dcyfr/ai and @dcyfr/agents?**
|
|
887
|
+
**Q: What's the difference between @dcyfr/ai and @dcyfr/workspace-agents?**
|
|
901
888
|
|
|
902
|
-
A: `@dcyfr/ai` is the **public harness** (plugin architecture, config management, telemetry engine, validation harness). `@dcyfr/agents` is a **private package** with DCYFR-specific validation agents (design tokens, barrel exports, PageLayout enforcement). Think of @dcyfr/ai as the engine, @dcyfr/agents as pre-built plugins.
|
|
889
|
+
A: `@dcyfr/ai` is the **public harness** (plugin architecture, config management, telemetry engine, validation harness). `@dcyfr/workspace-agents` is a **private package** with DCYFR-specific validation agents (design tokens, barrel exports, PageLayout enforcement). Think of @dcyfr/ai as the engine, @dcyfr/workspace-agents as pre-built plugins.
|
|
903
890
|
|
|
904
891
|
**Q: Can I use this with other AI providers (non-Claude)?**
|
|
905
892
|
|
|
@@ -1002,7 +989,7 @@ Found a security issue? Report it privately:
|
|
|
1002
989
|
### Platform-Specific Issues
|
|
1003
990
|
|
|
1004
991
|
- **Windows:** Path separators handled automatically but some plugins may have issues
|
|
1005
|
-
- **Node.js version:** Requires ≥
|
|
992
|
+
- **Node.js version:** Requires ≥20.0.0 per `package.json` engines (uses native fetch, modern APIs); CI tests on Node 24
|
|
1006
993
|
- **ESM-only:** Package is ESM (ECMAScript Modules) - CommonJS require() not supported
|
|
1007
994
|
|
|
1008
995
|
### Planned Improvements
|
|
@@ -1022,30 +1009,11 @@ See [GitHub Issues](https://github.com/dcyfr-labs/dcyfr-ai/issues) for tracked f
|
|
|
1022
1009
|
|
|
1023
1010
|
## 📄 License & Sponsorship
|
|
1024
1011
|
|
|
1025
|
-
**License:** MIT
|
|
1026
|
-
|
|
1027
|
-
### Commercial Use
|
|
1028
|
-
|
|
1029
|
-
This package is dual-licensed:
|
|
1030
|
-
|
|
1031
|
-
- **MIT License** for personal, educational, and non-commercial use (free)
|
|
1032
|
-
- **Commercial License** for business and revenue-generating use (paid)
|
|
1033
|
-
|
|
1034
|
-
**Commercial use includes:**
|
|
1035
|
-
|
|
1036
|
-
- Using @dcyfr/ai in SaaS products or revenue-generating services
|
|
1037
|
-
- Deploying in companies with >5 employees
|
|
1038
|
-
- Providing paid consulting/services using @dcyfr/ai
|
|
1039
|
-
- Distributing as part of commercial products
|
|
1012
|
+
**License:** [MIT](./LICENSE). The [LICENSE](./LICENSE) file is the canonical statement of this package's licensing terms.
|
|
1040
1013
|
|
|
1041
|
-
### Sponsorship
|
|
1014
|
+
### Sponsorship
|
|
1042
1015
|
|
|
1043
|
-
|
|
1044
|
-
- 💚 **Sponsors** ($10/mo) - Bio on dcyfr.ai website + private channels
|
|
1045
|
-
- 👨💻 **Developer** ($20/mo) - Limited commercial license + pre-release builds + portfolio support
|
|
1046
|
-
- 🚀 **Founder** ($2,400/yr) - Full commercial license + 1hr consultation/mo
|
|
1047
|
-
- 💼 **Executive** ($4,800/yr) - Business license + 2hr consultation/mo + 50 employees
|
|
1048
|
-
- 🏢 **Enterprise** ($9,600/yr) - Enterprise license + 4hr consultation/mo + unlimited scale
|
|
1016
|
+
Development is supported through sponsorship — if @dcyfr/ai is useful to you or your business, consider sponsoring.
|
|
1049
1017
|
|
|
1050
1018
|
**Join:** [GitHub Sponsors](https://github.com/sponsors/dcyfr)
|
|
1051
1019
|
**Contact:** licensing@dcyfr.ai
|