docs: add comprehensive README for root and all packages
This commit is contained in:
@@ -1,3 +1,165 @@
|
||||
# nerve
|
||||
|
||||
Observation engine — Sense, Reflex, Workflow
|
||||
**Observation engine for autonomous agents** — sense the world, react to changes, run workflows.
|
||||
|
||||
Nerve is a lightweight daemon that continuously observes external state through **Senses**, reacts via declarative **Reflexes**, and orchestrates multi-step **Workflows**. Built for the [Uncaged](https://github.com/uncaged) agent framework.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
```
|
||||
External World → Sense → Signal → Reflex → Workflow → Log
|
||||
↑ ↑
|
||||
"what to observe" "what to do"
|
||||
```
|
||||
|
||||
| Concept | Metaphor | Role |
|
||||
|---------|----------|------|
|
||||
| **Sense** | 👁️ Perception | A `compute()` function that samples or derives data. Each sense has its own SQLite database. |
|
||||
| **Reflex** | ⚡ Reaction | Declarative trigger — interval-based, event-driven, or both. Connects senses to actions. |
|
||||
| **Signal** | 📡 Notification | Emitted when a sense returns non-null. Other reflexes can listen for signals. |
|
||||
| **Workflow** | 🔧 Action | Stateful multi-step execution with Roles (actors) and a Moderator (coordinator). |
|
||||
| **Log** | 📝 Record | Immutable audit trail. Queryable by senses, but **cannot** trigger reflexes (prevents feedback loops). |
|
||||
|
||||
Three extension points, fully orthogonal — a Sense doesn't know when it runs, a Reflex doesn't know what it computes, a Workflow doesn't know why it was triggered.
|
||||
|
||||
## Packages
|
||||
|
||||
| Package | Description |
|
||||
|---------|-------------|
|
||||
| [`@uncaged/nerve-core`](./packages/core) | Shared types and config parser |
|
||||
| [`@uncaged/nerve-daemon`](./packages/daemon) | The observation engine — kernel, sense runtime, reflex scheduler, workflow manager |
|
||||
| [`@uncaged/nerve-cli`](./packages/cli) | CLI tool (`nerve`) — init, start, stop, logs, query |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Requirements: Node.js ≥ 22.5, pnpm
|
||||
pnpm add -g @uncaged/nerve-cli
|
||||
|
||||
# Initialize a workspace
|
||||
mkdir my-agent && cd my-agent
|
||||
nerve init
|
||||
|
||||
# Write a sense
|
||||
cat > senses/cpu-usage/compute.ts << 'EOF'
|
||||
export async function compute() {
|
||||
const [load] = (await import("node:os")).loadavg();
|
||||
return load > 2.0 ? { load } : null; // signal only when load is high
|
||||
}
|
||||
EOF
|
||||
|
||||
# Configure reflexes in nerve.yaml
|
||||
cat > nerve.yaml << 'EOF'
|
||||
senses:
|
||||
cpu-usage:
|
||||
group: system
|
||||
throttle: 10s
|
||||
|
||||
reflexes:
|
||||
- kind: sense
|
||||
sense: cpu-usage
|
||||
interval: 30s
|
||||
EOF
|
||||
|
||||
# Run
|
||||
nerve dev # foreground (development)
|
||||
nerve daemon start # background (production)
|
||||
nerve status # check health
|
||||
nerve logs # view logs
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
`nerve.yaml` declares senses, reflexes, and workflows:
|
||||
|
||||
```yaml
|
||||
senses:
|
||||
cpu-usage:
|
||||
group: system # senses in the same group share a worker process
|
||||
throttle: 10s # min interval between computes
|
||||
timeout: 30s # max compute duration
|
||||
gracePeriod: 5s # wait before first compute after startup
|
||||
|
||||
reflexes:
|
||||
- kind: sense
|
||||
sense: cpu-usage
|
||||
interval: 30s # periodic trigger
|
||||
on: [disk-pressure] # also trigger on signals from other senses
|
||||
|
||||
- kind: workflow
|
||||
workflow: cleanup
|
||||
on: [disk-pressure] # start a workflow when signal fires
|
||||
|
||||
workflows:
|
||||
cleanup:
|
||||
concurrency: 1
|
||||
overflow: drop # discard if already running
|
||||
code-review:
|
||||
concurrency: 3
|
||||
overflow: queue
|
||||
maxQueue: 20
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Kernel │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Worker │ │ Worker │ │ Worker │ (1 per │
|
||||
│ │ (group A)│ │ (group B)│ │ (group C)│ group) │
|
||||
│ │ sense-1 │ │ sense-3 │ │ sense-5 │ │
|
||||
│ │ sense-2 │ │ sense-4 │ │ │ │
|
||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||||
│ │ │ │ │
|
||||
│ └──────────────┼──────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────┐ │
|
||||
│ │ Signal Bus │ │
|
||||
│ └──────┬───────┘ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────┐ │
|
||||
│ │ Reflex Scheduler │ │
|
||||
│ └────────┬─────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌───────────────────┐ │
|
||||
│ │ Workflow Manager │──→ Log Store (SQLite) │
|
||||
│ └───────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- **Worker processes** — one per sense group, forked by the kernel. Isolated compute execution.
|
||||
- **Signal Bus** — in-memory pub/sub for signal distribution.
|
||||
- **Reflex Scheduler** — interval timers + signal subscriptions, with throttle/coalesce.
|
||||
- **Workflow Manager** — concurrency control (drop/queue), thread lifecycle tracking.
|
||||
- **Log Store** — WAL-mode SQLite via `node:sqlite`, with archival and retention policies.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Zero native addons** — uses Node.js built-in `node:sqlite` (DatabaseSync)
|
||||
- **Drizzle ORM** v1.0 for sense databases
|
||||
- **rslib** (rspack) for building
|
||||
- **Biome** for formatting/linting
|
||||
- **Vitest** for testing
|
||||
- **pnpm** workspaces for monorepo management
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
git clone https://git.shazhou.work/uncaged/nerve.git
|
||||
cd nerve
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm -r test # run all tests
|
||||
```
|
||||
|
||||
## Design Documents
|
||||
|
||||
- [RFC-001: Observation Engine](./docs/rfc-001-observation-engine.md) — Sense, Signal, Reflex model
|
||||
- [RFC-002: Workflow Engine](./docs/rfc-002-workflow-engine.md) — Stateful workflow execution
|
||||
- [Coding Conventions](./docs/coding-conventions.md)
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# @uncaged/nerve-cli
|
||||
|
||||
Command-line interface for the [nerve](../../README.md) observation engine.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pnpm add -g @uncaged/nerve-cli
|
||||
# or
|
||||
npx @uncaged/nerve-cli
|
||||
```
|
||||
|
||||
Requires Node.js ≥ 22.5.
|
||||
|
||||
## Commands
|
||||
|
||||
### Workspace
|
||||
|
||||
```bash
|
||||
nerve init # Initialize a nerve workspace (installs deps, scaffolds config)
|
||||
nerve validate # Validate nerve.yaml configuration
|
||||
```
|
||||
|
||||
### Daemon Management
|
||||
|
||||
```bash
|
||||
nerve daemon start # Start the daemon (background)
|
||||
nerve daemon stop # Stop the daemon
|
||||
nerve daemon status # Check daemon health
|
||||
nerve daemon restart # Restart the daemon
|
||||
nerve daemon logs # Tail daemon logs
|
||||
```
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
nerve dev # Run in foreground mode (no daemon, Ctrl+C to stop)
|
||||
```
|
||||
|
||||
### Querying
|
||||
|
||||
```bash
|
||||
nerve logs # View structured logs
|
||||
nerve sense query <name> # Query a sense's SQLite database
|
||||
nerve sense schema <name> # Show a sense's database schema
|
||||
nerve status # Daemon health summary
|
||||
```
|
||||
|
||||
### Workflows
|
||||
|
||||
```bash
|
||||
nerve workflow list # List workflow runs
|
||||
nerve workflow show <runId> # Show workflow run details
|
||||
```
|
||||
|
||||
### Top-level Aliases
|
||||
|
||||
For convenience, these aliases are available:
|
||||
|
||||
```bash
|
||||
nerve start → nerve daemon start
|
||||
nerve stop → nerve daemon stop
|
||||
nerve status → nerve daemon status
|
||||
nerve logs → nerve daemon logs
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
@@ -0,0 +1,39 @@
|
||||
# @uncaged/nerve-core
|
||||
|
||||
Shared types and configuration parser for the [nerve](../../README.md) observation engine.
|
||||
|
||||
## What's Inside
|
||||
|
||||
- **Type definitions** — `Signal`, `SenseConfig`, `ReflexConfig`, `WorkflowConfig`, `NerveConfig`, and all related types
|
||||
- **Config parser** — `parseNerveConfig(yaml)` validates and parses `nerve.yaml` into a typed `NerveConfig`
|
||||
- **Result type** — `Result<T>` with `ok()` / `err()` helpers for explicit error handling (no thrown exceptions)
|
||||
|
||||
## Usage
|
||||
|
||||
```typescript
|
||||
import { parseNerveConfig, ok, err } from "@uncaged/nerve-core";
|
||||
import type { NerveConfig, Signal, Result } from "@uncaged/nerve-core";
|
||||
|
||||
const result: Result<NerveConfig> = parseNerveConfig(yamlString);
|
||||
if (result.ok) {
|
||||
console.log(result.value.senses);
|
||||
}
|
||||
```
|
||||
|
||||
## Duration Format
|
||||
|
||||
Config fields like `throttle`, `timeout`, and `interval` accept human-readable durations:
|
||||
|
||||
- `5s` — 5 seconds
|
||||
- `10m` — 10 minutes
|
||||
- `1h` — 1 hour
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pnpm add @uncaged/nerve-core
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
@@ -0,0 +1,57 @@
|
||||
# @uncaged/nerve-daemon
|
||||
|
||||
The observation engine runtime for [nerve](../../README.md) — runs senses, routes signals, schedules reflexes, and manages workflows.
|
||||
|
||||
## Architecture
|
||||
|
||||
| Module | Responsibility |
|
||||
|--------|---------------|
|
||||
| **Kernel** | Top-level orchestrator — spawns workers, wires up signal bus, scheduler, and workflow manager. Supports hot reload and graceful shutdown. |
|
||||
| **Sense Runtime** | Per-sense SQLite database (via `node:sqlite` + Drizzle ORM), migration runner, peer DB read access. |
|
||||
| **Sense Worker** | Forked child process — one per sense group. Runs compute functions in isolation. |
|
||||
| **Signal Bus** | In-memory pub/sub. Sense computes emit signals; reflexes and workflows subscribe. |
|
||||
| **Reflex Scheduler** | Drives compute triggers — interval timers, signal-based events, throttle/coalesce logic. |
|
||||
| **Workflow Manager** | Concurrency control (drop/queue), thread lifecycle, worker process management (RFC-002). |
|
||||
| **Log Store** | Structured log storage in WAL-mode SQLite. Supports retention policies, archival to JSONL, and workflow run tracking. |
|
||||
| **Blob Store** | Binary artifact storage for workflow outputs. |
|
||||
| **File Watcher** | Watches `nerve.yaml` and sense files for hot reload. |
|
||||
| **Daemon IPC** | Unix socket server for CLI ↔ daemon communication. |
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
- **One worker process per sense group** — isolation between groups, shared compute within a group
|
||||
- **`node:sqlite` (DatabaseSync)** — zero native addons, WAL mode, built into Node.js ≥ 22.5
|
||||
- **Throttle + coalesce** — if compute is in-flight, at most one pending trigger is queued (no unbounded accumulation)
|
||||
- **Log ≠ Signal** — logs are queryable data assets but cannot trigger reflexes (prevents feedback loops)
|
||||
|
||||
## Usage
|
||||
|
||||
The daemon is typically started via the CLI (`nerve daemon start`), but can be used programmatically:
|
||||
|
||||
```typescript
|
||||
import { createKernel } from "@uncaged/nerve-daemon";
|
||||
|
||||
const kernel = await createKernel(nerveRoot);
|
||||
await kernel.ready;
|
||||
|
||||
// Trigger a sense manually
|
||||
kernel.triggerSense("cpu-usage");
|
||||
|
||||
// Check health
|
||||
const health = kernel.getHealth();
|
||||
|
||||
// Graceful shutdown
|
||||
await kernel.stop();
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pnpm add @uncaged/nerve-daemon
|
||||
```
|
||||
|
||||
Requires Node.js ≥ 22.5 (for `node:sqlite`).
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user