opc-agent 5.0.0-rc.13 → 5.0.0-rc.15

package/CHANGELOG.md

@@ -1,59 +1,140 @@
-# Changelog
-
-## [4.2.0] - 2026-04-21
-
-### New Features
-- **Priority Queue / Fast Mode** — Priority-aware request routing with per-session `/fast` toggle. Fast-mode requests are processed first and routed through provider priority endpoints (OpenAI, Anthropic, Google). Includes concurrency control, batch tier, and custom provider endpoint registration.
-- **Gateway Registry** — Advanced multi-gateway tool provider pattern. Register multiple remote tool gateways with subscription-based access, per-tool quota tracking, auto-retry with backoff, and unified invocation routing across gateways. Complements the existing single-gateway `ToolGateway`.
-
-### Improvements
-- New `FastModeManager` for per-session priority state management
-- `PriorityQueue` with weighted dequeue, provider concurrency limits, and drain support
-- `ToolGatewayRegistry` for routing tool calls across multiple gateway providers
-
-## [2.0.0] - 2026-04-18
-
-### Major Features
-- **Interactive CLI** (`opc chat`) — Full TUI with streaming, slash commands, history
-- **Daemon Mode** (`opc start/stop/status`) — Run agents as background processes
-- **Cron Scheduler** — Built-in job scheduling with cron expressions
-- **Autonomous Skill Learning** — Agents create and improve skills from experience
-- **Sub-Agent System** — Spawn parallel sub-agents for task delegation
-- **Built-in Tools** — File operations, web fetch, shell exec, datetime
-- **MCP Client** — Connect to external MCP servers via JSON-RPC
-- **Telegram Channel** — Dual-mode (polling + webhook) with Markdown support
-- **Discord Channel** — Gateway WebSocket with auto-reconnect
-- **Slack Channel** — Real Events API + chat.postMessage
-- **SOUL.md + CONTEXT.md** — Agent personality and project context files
-- **Analytics** — Wired into runtime for message tracking, skill usage, errors
-
-### Enhanced
-- `/health` endpoint returns comprehensive agent info
-- `opc init` generates SOUL.md, CONTEXT.md, and richer project templates
-- OAD config supports scheduler, learning, and tools sections
-- 204 tests passing
-
-### CLI Commands
-init, chat, run, dev, start, stop, status, jobs, skills, info, build, test, analytics, brain, logs, score, search, deploy, publish, install, plugin, tool, workflow, migrate
-
-## 1.4.0 (2026-04-18)
-- feat: wire Analytics into AgentRuntime (message timing, skill usage, error tracking)
-- feat: expose analytics snapshot on /health and /api/dashboard endpoints
-- feat: enhanced /health endpoint with agent name, version, uptime, memory type, skills, channels
-- feat: Slack channel — real Events API webhook server + chat.postMessage via fetch
-- feat: WebChannel metadata setters (version, memory type, skills, channels, analytics provider)
-- feat: AgentRuntime.getAnalytics() and getConfig() accessors
-
-## 1.3.1 (2026-04-17)
-- fix: remove residual DTV/marketplace references
-- fix: duplicate WatchPattern export
-
-## 1.3.0 (2026-04-17)
-- feat: Traces collection (OpenTelemetry-style)
-- feat: DeepBrain exporter
-- feat: brain/logs/score CLI commands
-
-## 1.2.0
-- Initial public release
-- 11 channels, plugins, analytics
-- Declarative OAD configuration
+# Changelog
+
+## [5.0.0-rc.14] - 2026-04-23
+
+### New Features
+- **OutputGuard** — Unified output sanitization pipeline with 6 rules: PII scrubbing, prompt-injection echo suppression, `<think>` reasoning block stripping, model identity self-disclosure detection (Claude/GPT/Gemini/etc.), jailbreak echo filtering, and sensitive-key redaction. Integrated into all 6 active channels (Telegram, Web, WeChat, Feishu, Discord, Slack) with full streaming support.
+
+## [5.0.0-rc.13] - 2026-04-23
+
+### New Features
+- **Hybrid FTS5 + Semantic Search** — DeepBrain now combines SQLite FTS5 full-text search with vector embeddings for higher-recall recall queries
+- **Skill Platform Filter** — Skills declare supported platforms; runtime skips unsupported tools automatically
+- **TUI LogStream** — Live structured log panel inside the terminal chat UI
+- **MCPClient stub** — MCP client interface wired into runtime (server connectivity TBD)
+- **WorkflowEngine** — DAG-based task orchestration with step dependencies and parallel branches
+- **SandboxManager** — Isolated execution environment for untrusted code steps
+- **Workstation Template system** — `opc init --template <id>` scaffolds a complete agent workspace (e.g. `opc init --template ceo-coach-socratic`)
+- **7-layer System Prompt Assembly** — Layered prompt construction: base identity → EGO.md → SOUL.md → CONTEXT.md → memory → skills → conversation history
+- **DeepBrain Auto-import** — Knowledge base is automatically populated on `opc brain learn`
+- **DeepBrain Recall in Conversations** — Every conversation turn runs a semantic prefetch against DeepBrain and injects relevant memories into context
+
+## [5.0.0-rc.12] - 2026-04-22
+
+### New Features
+- **FailoverProvider** — Automatic LLM provider failover with configurable priority order and circuit-breaker
+- **HeartbeatMonitor** — Per-provider liveness probes; removes unhealthy providers from rotation
+- **`create_skill` tool** — Agent self-writes new skills at runtime; persisted to disk and hot-reloaded
+- **InsightsExtractor** — Structured extraction of entities, decisions, and action items from conversation turns
+- **SubAgentManager** — Spawn, track, and aggregate results from parallel sub-agents
+- **SessionEventEmitter** — Internal event bus for session lifecycle hooks (start, turn, end, error)
+- **InjectionDetector** — Heuristic + pattern-based prompt injection detection layer
+- **ProgressiveDisclosure** — Truncates lengthy tool outputs; exposes `show more` expansion in TUI
+- **ContextCompressor V2** — Token-aware summarisation with configurable compression ratio and anchor preservation
+
+## [5.0.0-rc.11] - 2026-04-22
+
+### New Features
+- **Provider Failover** — LLM provider switching on transient errors; retries with exponential back-off
+- **Prompt Injection Detection** — Early-stage detection of adversarial inputs before they reach the model
+
+## [5.0.0-rc.10]
+
+### New Features
+- **P1 Orchestration** — Memory prefetch/sync, context window guard (auto-truncation before overflow), cron job delivery to channels, DeepBrain recall wired into every turn
+
+## [5.0.0-rc.9]
+
+### New Features
+- **P0 Orchestration** — SQLite conversation history persistence, context compaction (summarise-and-truncate), isolated cron scheduler
+- **Pipe Mode Tool Loop** — `opc run --pipe` accepts newline-delimited JSON tasks; agent executes tool loop and writes JSON results to stdout
+- **Skill Loader Integration** — Runtime discovers and loads skills from `~/.opc/skills/` and project-local `skills/` on startup
+
+## [5.0.0-rc.5]
+
+### Improvements
+- **Banner v2** — High-fidelity ASCII-art splash with version and hardware stats
+- **TUI Markdown Enhancement** — Tables, code fences, and inline styles rendered natively in terminal
+
+## [5.0.0-rc.3]
+
+### New Features
+- **TUI Markdown Rendering** — Full CommonMark rendering in `opc chat` terminal UI
+
+## [5.0.0-rc.2]
+
+### New Features
+- **Interactive Tool Calling** — Tools are confirmed and displayed live inside the TUI before execution
+
+## [5.0.0-rc.1] - 2026-04-20
+
+### Major Release — Complete v5 Rewrite
+- All-in-one architecture merging **DeepBrain** (knowledge) + **AgentKits** (model routing) + **Workstation** (templates) into a single package
+- 1114 tests passing
+- TypeScript 5.x, CommonJS module format, Node.js 18+ required
+- Declarative `oad.yaml` agent definition replaces legacy JSON config
+- New self-evolution engine: L1 Experience Compile → L2 Memory Consolidate → L3 Skill Discovery → L4 Group Evolution
+
+## [5.0.0-alpha.1]
+
+- Initial v5 alpha — early preview of the rewritten architecture
+
+---
+
+## [4.2.0] - 2026-04-21
+
+### New Features
+- **Priority Queue / Fast Mode** — Priority-aware request routing with per-session `/fast` toggle. Fast-mode requests are processed first and routed through provider priority endpoints (OpenAI, Anthropic, Google). Includes concurrency control, batch tier, and custom provider endpoint registration.
+- **Gateway Registry** — Advanced multi-gateway tool provider pattern. Register multiple remote tool gateways with subscription-based access, per-tool quota tracking, auto-retry with backoff, and unified invocation routing across gateways. Complements the existing single-gateway `ToolGateway`.
+
+### Improvements
+- New `FastModeManager` for per-session priority state management
+- `PriorityQueue` with weighted dequeue, provider concurrency limits, and drain support
+- `ToolGatewayRegistry` for routing tool calls across multiple gateway providers
+
+## [2.0.0] - 2026-04-18
+
+### Major Features
+- **Interactive CLI** (`opc chat`) — Full TUI with streaming, slash commands, history
+- **Daemon Mode** (`opc start/stop/status`) — Run agents as background processes
+- **Cron Scheduler** — Built-in job scheduling with cron expressions
+- **Autonomous Skill Learning** — Agents create and improve skills from experience
+- **Sub-Agent System** — Spawn parallel sub-agents for task delegation
+- **Built-in Tools** — File operations, web fetch, shell exec, datetime
+- **MCP Client** — Connect to external MCP servers via JSON-RPC
+- **Telegram Channel** — Dual-mode (polling + webhook) with Markdown support
+- **Discord Channel** — Gateway WebSocket with auto-reconnect
+- **Slack Channel** — Real Events API + chat.postMessage
+- **SOUL.md + CONTEXT.md** — Agent personality and project context files
+- **Analytics** — Wired into runtime for message tracking, skill usage, errors
+
+### Enhanced
+- `/health` endpoint returns comprehensive agent info
+- `opc init` generates SOUL.md, CONTEXT.md, and richer project templates
+- OAD config supports scheduler, learning, and tools sections
+- 204 tests passing
+
+### CLI Commands
+init, chat, run, dev, start, stop, status, jobs, skills, info, build, test, analytics, brain, logs, score, search, deploy, publish, install, plugin, tool, workflow, migrate
+
+## [1.4.0] - 2026-04-18
+- feat: wire Analytics into AgentRuntime (message timing, skill usage, error tracking)
+- feat: expose analytics snapshot on /health and /api/dashboard endpoints
+- feat: enhanced /health endpoint with agent name, version, uptime, memory type, skills, channels
+- feat: Slack channel — real Events API webhook server + chat.postMessage via fetch
+- feat: WebChannel metadata setters (version, memory type, skills, channels, analytics provider)
+- feat: AgentRuntime.getAnalytics() and getConfig() accessors
+
+## [1.3.1] - 2026-04-17
+- fix: remove residual DTV/marketplace references
+- fix: duplicate WatchPattern export
+
+## [1.3.0] - 2026-04-17
+- feat: Traces collection (OpenTelemetry-style)
+- feat: DeepBrain exporter
+- feat: brain/logs/score CLI commands
+
+## [1.2.0]
+- Initial public release
+- 11 channels, plugins, analytics
+- Declarative OAD configuration

package/CONTRIBUTING.md

@@ -1,36 +1,175 @@
-# Contributing
-
-Thanks for your interest in contributing!
-
-## Getting Started
-
-1. Fork the repo
-2. Clone your fork
-3. Install dependencies: `npm install`
-4. Create a branch: `git checkout -b feat/my-feature`
-5. Make your changes
-6. Run tests: `npm test`
-7. Commit: `git commit -m "feat: description"`
-8. Push and open a PR
-
-## Commit Convention
-
-- `feat:` New feature
-- `fix:` Bug fix
-- `docs:` Documentation
-- `test:` Tests
-- `refactor:` Refactoring
-- `chore:` Build/tooling
-
-## Code Style
-
-- TypeScript
-- Run `npm run lint` before committing (if available)
-
-## Questions?
-
-Open a Discussion or Issue.
-
-## License
-
-By contributing, you agree that your contributions will be licensed under Apache-2.0.
+# Contributing to OPC Agent
+
+Thanks for your interest in contributing! This guide covers everything you need to get started.
+
+---
+
+## Development Setup
+
+```bash
+# 1. Fork and clone
+git clone https://github.com/Deepleaper/opc-agent.git
+cd opc-agent
+
+# 2. Install dependencies
+npm install
+
+# 3. Build (TypeScript → CommonJS)
+npx tsc
+
+# 4. Run tests
+npx vitest run
+```
+
+> **Note:** This is a **CommonJS** project (not ESM). All output goes to `dist/`. TypeScript 5.x is required. There are **no native dependencies** — the project uses `sql.js` (WASM) instead of `better-sqlite3` so it works on all platforms without compilation.
+
+---
+
+## Project Structure
+
+```
+src/
+  core/          # Agent loop, runtime, session management, OutputGuard
+  channels/      # One file per channel: telegram.ts, web.ts, slack.ts, …
+  memory/        # DeepBrainMemoryStore, InMemoryStore, vector search
+  tools/         # Built-in tools (file ops, web fetch, shell exec, etc.)
+  schema/        # Zod schemas and shared TypeScript types
+  skills/        # Skill loader, BaseSkill, SkillPlatformFilter
+  evolution/     # L1–L4 self-evolution engine
+  workflow/      # WorkflowEngine, SandboxManager, SubAgentManager
+  cli/           # CLI entry point and command handlers
+
+examples/        # Runnable usage examples
+test/            # Test files, co-located with source or in test/
+```
+
+---
+
+## Testing
+
+The project has **1114+ tests** covering unit, integration, and end-to-end scenarios.
+
+```bash
+# Run all tests
+npx vitest run
+
+# Run in watch mode during development
+npx vitest
+
+# Run a specific test file
+npx vitest run src/core/output-guard.test.ts
+```
+
+**Conventions:**
+- Test files live next to the code they test (`foo.ts` → `foo.test.ts`) or under `test/`.
+- Use `describe` / `it` / `expect` from Vitest — no Jest imports.
+- Mock at the boundary: stub external HTTP calls and file I/O, but don't mock internal modules unless unavoidable.
+- Every new feature or bug fix must include a corresponding test.
+
+---
+
+## Adding a Channel
+
+Channels live in `src/channels/`. Each channel extends `BaseChannel` and plugs into the `AgentRuntime`.
+
+1. **Create the file**: `src/channels/my-channel.ts`
+
+```typescript
+import { BaseChannel, type OutboundMessage } from '../core/base-channel';
+
+export class MyChannel extends BaseChannel {
+  readonly name = 'my-channel';
+
+  async start(): Promise<void> {
+    // Connect to the external service
+  }
+
+  async stop(): Promise<void> {
+    // Disconnect cleanly
+  }
+
+  protected async send(message: OutboundMessage): Promise<void> {
+    // Deliver the message — OutputGuard has already run at this point
+  }
+}
+```
+
+2. **Register it** in `src/core/runtime.ts` alongside existing channels.
+
+3. **Add a test** in `src/channels/my-channel.test.ts`.
+
+4. **Document it** in the CLI table in `README.md` and `README.zh-CN.md`.
+
+> OutputGuard runs automatically on every message before `send()` is called — you do not need to add sanitization logic in your channel.
+
+---
+
+## Adding a Built-in Tool
+
+Built-in tools live in `src/tools/`. Each tool implements the `BuiltinTool` interface and is auto-discovered at runtime.
+
+1. **Create the file**: `src/tools/my-tool.ts`
+
+```typescript
+import { type BuiltinTool, type ToolResult } from '../schema/tool';
+
+export const myTool: BuiltinTool = {
+  name: 'my_tool',
+  description: 'What this tool does, for the model to read',
+  parameters: {
+    type: 'object',
+    properties: {
+      input: { type: 'string', description: 'The input value' },
+    },
+    required: ['input'],
+  },
+  async execute(args: { input: string }): Promise<ToolResult> {
+    return { content: `Result: ${args.input}` };
+  },
+};
+```
+
+2. **Export it** from `src/tools/index.ts`.
+
+3. **Add a test** in `src/tools/my-tool.test.ts`.
+
+---
+
+## Commit Convention
+
+| Prefix | Use for |
+|--------|---------|
+| `feat:` | New feature |
+| `fix:` | Bug fix |
+| `docs:` | Documentation only |
+| `test:` | Tests only |
+| `refactor:` | Code restructuring without behavior change |
+| `chore:` | Build, tooling, dependencies |
+
+Examples:
+```
+feat: add WeChat Work channel
+fix: OutputGuard false-positive on base64 strings
+docs: add channel mini-guide to CONTRIBUTING
+```
+
+---
+
+## Pull Request Checklist
+
+- [ ] `npx tsc` passes with no errors
+- [ ] `npx vitest run` — all tests pass, new tests added
+- [ ] No `.js` output files committed (build artifacts are gitignored)
+- [ ] Docs updated if you added or changed a public API or CLI command
+
+---
+
+## Questions?
+
+Open a [Discussion](https://github.com/Deepleaper/opc-agent/discussions) for design questions or [Issues](https://github.com/Deepleaper/opc-agent/issues) for bugs.
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under **Apache-2.0**.