@dcyfr/ai 2.1.3 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## 3.0.0
+
+### Major Changes
+
+- [`4dd858f`](https://github.com/dcyfr/dcyfr-ai/commit/4dd858f9da64be2b1700332606046908b8f9748b) Thanks [@dcyfr](https://github.com/dcyfr)! - feat!: Session handoff chain protocol, requires-confirmation workflow, user context files API (v3.0)
+
+  ### Breaking Changes
+
+  **DelegationContract** now requires `handoff_context?: HandoffContext` in the type definition.
+  Existing contracts without this field remain valid (optional), but downstream TypeScript consumers
+  using strict type checking may see new optional property warnings.
+
+  **SessionHandoffChain** replaces single-session handoff with a chain protocol supporting
+  multi-hop handoffs with full context preservation across agent sessions.
+
+  ### New Features
+
+  #### Session Handoff Chain (`@dcyfr/ai/session`)
+
+  - `SessionHandoffChain` class: chain multiple session handoffs without losing conversation history
+  - `HandoffContext` type: structured context snapshot passed between sessions
+  - `createHandoffChain(sessions)`: factory for creating handoff chains from session arrays
+  - Full integration test coverage (14 tests, `session-handoff-chain.integration.test.ts`)
+
+  #### Requires-Confirmation Workflow (`@dcyfr/ai/delegation`)
+
+  - `requiresConfirmation: boolean` flag on `DelegationContract`
+  - `ConfirmationWorkflow` class: structured pause-and-log confirmation protocol
+  - `pendingConfirmation` contract status for tasks awaiting human approval
+  - Confirmation timestamp logging for audit trails
+
+  #### User Context Files API (`@dcyfr/ai/context`)
+
+  - `UserContextFiles` class: progressive disclosure loader for workspace user context files
+  - `loadContextFile(name)`: lazy-load individual context files (about-me, brand-voice, etc.)
+  - `getAvailableContextFiles()`: list available context files without loading content
+  - Template validation against `nexus/context/user/templates/`
+
+  ### Summary
+
+  These additions implement the cowork-inspired improvements inspired by validated practices
+  from human-AI collaboration research (January–February 2026 cowork sessions). The session
+  handoff chain prevents context loss during long-running multi-agent workflows. The confirmation
+  workflow enforces human oversight for destructive or high-stakes operations. User context files
+  enable personalized agent behavior without hardcoding user preferences.
+
+  All new APIs are fully tested. No existing APIs removed.
+
+### Minor Changes
+
+- [`096f9d4`](https://github.com/dcyfr/dcyfr-ai/commit/096f9d4e6a2f519d1389f0579b90c758b7dfbd1d) Thanks [@dcyfr](https://github.com/dcyfr)! - feat: Autonomous Agent Runtime — persistent memory, messaging, sessions, skills, scheduling
+
+  New subpath exports bring autonomous agent capabilities to @dcyfr/ai:
+
+  **@dcyfr/ai/memory** — File-first persistent memory with Markdown files, SHA-256 dedup,
+  optional SQLite FTS5 hybrid search (BM25 + vector RRF), and working memory persistence.
+
+  **@dcyfr/ai/compaction** — LLM-powered context compaction (pre-flush summarization),
+  plus memory compaction (cross-backend dedup, monthly conversation summarization,
+  stale fact archival).
+
+  **@dcyfr/ai/skills** — Dynamic skill injection with BM25 search over .md skill files,
+  YAML frontmatter parsing, and trust-level filtering.
+
+  **@dcyfr/ai/mcp** — MCP Tool Bridge that discovers tools from MCP servers and converts
+  them to AgentRuntime-compatible tool definitions with retry and timeout support.
+
+  **@dcyfr/ai/session** — Session manager with trust-level tool policies (full/sandboxed/
+  readonly), overlay memory, idle session tracking, and configurable middleware.
+
+  **@dcyfr/ai/scheduler** — Agent scheduler with built-in cron parser, webhook endpoints,
+  event subscriptions, quiet hours, and concurrent execution limits.
+
+  **@dcyfr/ai/gateway** — Platform-agnostic messaging gateway with Telegram, CLI, and HTTP
+  adapters, input sanitization, rate limiting, and trust-based access control.
+
+  All modules are tree-shakeable, fully tested (420+ new tests), and backward compatible
+  with existing AgentRuntime usage.
+
+- [`af15831`](https://github.com/dcyfr/dcyfr-ai/commit/af158311943bf658b791de40fb6de7161d4fb2e5) Thanks [@dcyfr](https://github.com/dcyfr)! - Repositioned @dcyfr/ai as 'AI agent harness' (infrastructure layer) rather than 'framework' (application structure) for accurate market positioning. Updated package.json, README, AGENTS.md, CONTRIBUTING.md with consistent terminology.
+
 ## 2.1.3
 
 ### Patch Changes

package/README.md

@@ -2,7 +2,7 @@
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dcyfr/dcyfr-ai)
 
-> Portable AI agent framework with plugin architecture for multi-provider integration, telemetry tracking, and quality validation.
+> Portable AI agent harness with plugin architecture for multi-provider integration, telemetry tracking, and quality validation.
 
 [![npm](https://img.shields.io/npm/v/@dcyfr/ai?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@dcyfr/ai)
 [![Downloads](https://img.shields.io/npm/dm/@dcyfr/ai?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@dcyfr/ai)
@@ -10,7 +10,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Bundle Size](https://img.shields.io/badge/Bundle%20Size-~200KB%20gzipped-28a745?style=flat-square&logo=webpack)](https://bundlephobia.com/package/@dcyfr/ai)
 
-Portable AI agent framework with plugin architecture for managing multiple AI providers, tracking telemetry, and ensuring quality compliance.
+Portable AI agent harness with plugin architecture for managing multiple AI providers, tracking telemetry, and ensuring quality compliance.
 
 ## 🔍 @dcyfr/ai vs. Alternatives
 
@@ -82,7 +82,7 @@ Portable AI agent framework with plugin architecture for managing multiple AI pr
 - 🎯 **Msty Vibe Integration** - Unified multi-model routing with local OpenAI-compatible endpoint
 - ⚙️ **Configuration System** - YAML/JSON config with three-layer merge
 - 📊 **Comprehensive Telemetry** - Track usage, costs, quality metrics, performance
-- ✅ **Validation Framework** - Quality gates with parallel/serial execution
+- ✅ **Validation Harness** - Quality gates with parallel/serial execution
 - 💾 **Pluggable Storage** - Memory, file-based, or custom adapters
 - ⚡ **Type-Safe** - Full TypeScript support with Zod validation
 - 📦 **Lightweight** - ~200KB gzipped bundle size
@@ -192,7 +192,7 @@ const response = await runtime.chat({ messages: [{ role: 'user', content: 'Hello
 
 ### Migrating from Vercel AI SDK
 
-**Why migrate:** Quality gates, telemetry, multi-provider validation framework
+**Why migrate:** Quality gates, telemetry, multi-provider validation harness
 
 ```typescript
 // Vercel AI SDK (before)
@@ -223,7 +223,7 @@ const report = await validator.validate({ /* config */ });
 
 **Key Differences:**
 - Configuration system (YAML/JSON files)
-- Validation framework with quality gates
+- Validation harness with quality gates
 - Comprehensive telemetry tracking
 - Plugin system for custom validators
 - Zero-config startup option
@@ -492,9 +492,67 @@ This example demonstrates:
 
 ---
 
+## Autonomous Agent Runtime
+
+Build agents that operate independently with persistent memory, scheduled execution, platform messaging, and dynamic skill injection.
+
+### Subpath Imports
+
+```typescript
+import { FileMemoryAdapter, SQLiteIndex, flushWorkingMemory } from '@dcyfr/ai/memory';
+import { ContextCompactor, MemoryCompaction } from '@dcyfr/ai/compaction';
+import { SkillRegistry } from '@dcyfr/ai/skills';
+import { MCPToolBridge } from '@dcyfr/ai/mcp';
+import { SessionManager } from '@dcyfr/ai/session';
+import { AgentScheduler } from '@dcyfr/ai/scheduler';
+import { MessageGateway, TelegramAdapter, CLIAdapter } from '@dcyfr/ai/gateway';
+```
+
+### Key Capabilities
+
+| Module | Description |
+|--------|-------------|
+| **File Memory** | Markdown-based persistent memory with SHA-256 dedup and optional SQLite FTS5 hybrid search |
+| **Context Compaction** | LLM-powered pre-flush summarization to prevent context overflow |
+| **Skill Injection** | BM25-powered matching of `.md` skill files to inject relevant knowledge |
+| **MCP Tool Bridge** | Bridges MCP server tool discovery → AgentRuntime tools |
+| **Session Management** | Trust-level tool policies (full/sandboxed/readonly), session lifecycle |
+| **Agent Scheduler** | Built-in cron parser, webhooks, event subscriptions, quiet hours |
+| **Messaging Gateway** | Telegram/CLI/HTTP adapters, input sanitization, rate limiting |
+| **Memory Compaction** | Cross-backend dedup, monthly conversation summarization, stale fact archival |
+| **Working Memory** | Persist `Map<string, unknown>` as human-readable Markdown |
+
+### Quick Example
+
+```typescript
+import { MessageGateway, TelegramAdapter } from '@dcyfr/ai/gateway';
+import { SessionManager } from '@dcyfr/ai/session';
+import { AgentScheduler } from '@dcyfr/ai/scheduler';
+
+// Create a messaging gateway with platform adapters
+const gateway = new MessageGateway({
+  adapters: [new TelegramAdapter({ sendFn: telegramBot.sendMessage })],
+  trustRules: [
+    { name: 'admin', userIds: ['admin-id'], trustLevel: 'full', priority: 10 },
+  ],
+});
+
+// Schedule daily tasks
+const scheduler = new AgentScheduler({
+  executor: async (task) => runAgent(task),
+});
+scheduler.schedule('0 9 * * *', { name: 'morning-report' });
+scheduler.start();
+```
+
+> **Full guide:** See [docs/guides/autonomous-agent-guide.md](docs/guides/autonomous-agent-guide.md)  
+> **Complete example:** See [examples/autonomous-agent.ts](examples/autonomous-agent.ts)
+
+---
+
 ## Architecture
 
-The DCYFR AI framework follows a layered architecture with clear separation of concerns:
+The DCYFR AI harness follows a layered architecture with clear separation of concerns:
 
 ```mermaid
 graph TB
@@ -640,6 +698,13 @@ See [examples/](./examples/) directory:
 - [Release Management](./docs/RELEASE_MANAGEMENT.md) - Publishing and versioning
 - [Quick Release Guide](./docs/RELEASE_QUICK_START.md) - TL;DR for releases
 
+### Plugin Marketplace Security
+- [GVISOR_SETUP.md](./docs/guides/GVISOR_SETUP.md) - gVisor runtime sandboxing for untrusted plugins
+- [BEHAVIORAL_ANOMALY_DETECTION.md](./docs/guides/BEHAVIORAL_ANOMALY_DETECTION.md) - Behavioral anomaly detection system
+- [CERTIFICATION_PROGRAM.md](./docs/guides/CERTIFICATION_PROGRAM.md) - Plugin Certification Program (Bronze/Silver/Gold tiers)
+- [WASM_PLUGIN_STARTER.md](./docs/guides/WASM_PLUGIN_STARTER.md) - WebAssembly plugin starter template
+- [WASM_MIGRATION_GUIDE.md](./docs/guides/WASM_MIGRATION_GUIDE.md) - Migrate Docker plugins to WASM
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
@@ -757,7 +822,7 @@ A: Yes, it's published as a public package on npm. Install with `npm install @dc
 
 **Q: Can I use @dcyfr/ai with JavaScript (no TypeScript)?**
 
-A: Yes, but TypeScript is strongly recommended for better type safety and IDE support. The framework provides full TypeScript support with Zod validation for runtime type checking. If using JavaScript, you'll miss compile-time type checking but runtime validation still works.
+A: Yes, but TypeScript is strongly recommended for better type safety and IDE support. The harness provides full TypeScript support with Zod validation for runtime type checking. If using JavaScript, you'll miss compile-time type checking but runtime validation still works.
 
 **Q: How do I create a custom validation plugin?**
 
@@ -779,11 +844,11 @@ See [docs/plugins.md](./docs/plugins.md) and [examples/plugin-system.ts](./examp
 
 **Q: What's the difference between @dcyfr/ai and @dcyfr/agents?**
 
-A: `@dcyfr/ai` is the **public framework** (plugin architecture, config management, telemetry engine, validation framework). `@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.
+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.
 
 **Q: Can I use this with other AI providers (non-Claude)?**
 
-A: Yes! The framework supports multi-provider integration including Claude, GitHub Copilot, Groq, Ollama, OpenAI, Anthropic. Configure providers in `.dcyfr.yaml`:
+A: Yes! The harness supports multi-provider integration including Claude, GitHub Copilot, Groq, Ollama, OpenAI, Anthropic. Configure providers in `.dcyfr.yaml`:
 ```yaml
 providers:
   - name: openai
@@ -803,7 +868,7 @@ const telemetry = new TelemetryEngine({
 ```
 Telemetry tracks: API calls, token usage, costs, latency, quality scores.
 
-**Q: Is this framework production-ready?**
+**Q: Is this harness production-ready?**
 
 A: Yes! @dcyfr/ai is used in production at dcyfr-labs and other projects. It has comprehensive test coverage, semantic versioning, automated releases via Changesets, and follows best practices for package publishing.
 

package/config/default.json

@@ -12,15 +12,24 @@
   "providers": {
     "enabled": true,
     "primary": "claude",
-    "fallback": ["groq", "ollama", "copilot"],
+    "fallback": ["copilot", "github-models", "groq", "ollama"],
     "timeout": 30000,
     "retries": 3,
     "providers": {
       "claude": {
         "enabled": true,
-        "model": "claude-3-5-sonnet-20241022",
+        "model": "claude-sonnet-4.5",
         "maxTokens": 8192
       },
+      "copilot": {
+        "enabled": true,
+        "baseUrl": "http://localhost:8317/v1",
+        "model": "claude-sonnet-4.5"
+      },
+      "github-models": {
+        "enabled": true,
+        "model": "gpt-4o"
+      },
       "groq": {
         "enabled": true,
         "model": "llama-3.3-70b-versatile"
@@ -29,9 +38,6 @@
         "enabled": true,
         "baseUrl": "http://localhost:11434",
         "model": "llama3.2"
-      },
-      "copilot": {
-        "enabled": true
       }
     }
   },

package/config/default.yaml

@@ -21,17 +21,28 @@ providers:
   enabled: true
   primary: claude
   fallback:
+    - copilot
+    - github-models
     - groq
     - ollama
-    - copilot
   timeout: 30000
   retries: 3
   providers:
     claude:
       enabled: true
       # apiKey: ${ANTHROPIC_API_KEY}
-      model: claude-3-5-sonnet-20241022
+      model: claude-sonnet-4.5
       maxTokens: 8192
+    copilot:
+      enabled: true
+      baseUrl: http://localhost:8317/v1
+      model: claude-sonnet-4.5
+      # Uses GitHub Copilot via Msty Vibe CLI Proxy
+    github-models:
+      enabled: true
+      # apiKey: ${GITHUB_TOKEN}
+      model: gpt-4o
+      # Endpoint: https://models.github.ai/inference (no Claude)
     groq:
       enabled: true
       # apiKey: ${GROQ_API_KEY}
@@ -40,9 +51,6 @@ providers:
       enabled: true
       baseUrl: http://localhost:11434
       model: llama3.2
-    copilot:
-      enabled: true
-      # Uses GitHub Copilot authentication
 
 # Validation configuration
 validation: