xiaoju
8dd82d99da
Senses trigger shell commands only. Workflows are invoked via CLI.
SenseTrigger is now { command: string } — no discriminated union.
Closes #318
Co-authored-by: Cursor <cursoragent@cursor.com>
56 lines
2.2 KiB
Markdown
56 lines
2.2 KiB
Markdown
# @uncaged/nerve-core
|
|
|
|
Shared types and configuration parser for the [nerve](../../README.md) observation engine.
|
|
|
|
## What's Inside
|
|
|
|
- **Type definitions** — `SenseConfig`, `SenseInfo`, `SenseComputeFn`, `SenseModule`, `SenseTrigger`, `WorkflowConfig`, `NerveConfig`, and related types
|
|
- **Config parser** — `parseNerveConfig(yaml)` validates and parses `nerve.yaml` into `NerveConfig` (top-level `reflexes` is rejected; use `interval` / `on` on each sense)
|
|
- **Sense triggers** — `parseSenseTrigger` validates `{ command: string }` from sense compute results or worker IPC (`trigger` field on `compute-result`)
|
|
- **Daemon IPC protocol** — request/response types (`DaemonIpcRequest`, `DaemonIpcResponse`, …) and `parseDaemonIpcRequest` for newline-delimited JSON on the CLI ↔ daemon socket
|
|
- **Workflow automaton types** — `START` / `END` sentinel constants, `WorkflowMessage`, `StartStep`, `RoleStep`, `ModeratorContext` (`start` + `steps`; empty `steps` on first moderator call), `Moderator` (single `context` argument), `WorkflowDefinition`, `Role`, `RoleResult`, plus `DEFAULT_ENGINE_MAX_ROUNDS`
|
|
- **Result type** — `Result<T>` with `ok()` / `err()` helpers for explicit error handling (no thrown exceptions for parse paths)
|
|
|
|
## Usage
|
|
|
|
```typescript
|
|
import { parseNerveConfig, ok, err } from "@uncaged/nerve-core";
|
|
import type { NerveConfig, Result } from "@uncaged/nerve-core";
|
|
|
|
const result: Result<NerveConfig> = parseNerveConfig(yamlString);
|
|
if (result.ok) {
|
|
console.log(result.value.senses);
|
|
}
|
|
```
|
|
|
|
### Sense trigger validation
|
|
|
|
```typescript
|
|
import { parseSenseTrigger } from "@uncaged/nerve-core";
|
|
|
|
const parsed = parseSenseTrigger({ command: "echo hello" });
|
|
if (parsed.ok) {
|
|
console.log(parsed.value.command);
|
|
}
|
|
```
|
|
|
|
Sense modules return `{ state, trigger }` from `compute(state)`; when `trigger` is non-null it must be exactly `{ command: string }` (non-empty after trim). The daemon validates worker IPC with `parseSenseTrigger`. Workflows are started only via CLI / daemon IPC, not from this field.
|
|
|
|
## 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
|