nerve/packages/core/README.md

@uncaged/nerve-core

Shared types and configuration parser for the nerve observation engine.

What's Inside

• Type definitions — SenseConfig, SenseInfo, SenseComputeFn, SenseModule, WorkflowConfig, NerveConfig, WorkflowTrigger, 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)
• Workflow triggers — parseWorkflowTrigger validates structured workflow launch objects from Sense compute results or IPC
• 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

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);
}

Workflow trigger validation

import { parseWorkflowTrigger } from "@uncaged/nerve-core";

const directive = parseWorkflowTrigger({
  name: "my-workflow",
  maxRounds: 8,
  prompt: "Hello from sense",
  dryRun: false,
});
if (directive.ok) {
  console.log(directive.value.name, directive.value.maxRounds, directive.value.prompt);
}

Sense modules return { state, workflow } from compute(state); when workflow is non-null it must satisfy the shape validated by parseWorkflowTrigger (the daemon validates before starting a run).

Duration Format

Config fields like throttle, timeout, and interval accept human-readable durations:

• 5s — 5 seconds
• 10m — 10 minutes
• 1h — 1 hour

Install

pnpm add @uncaged/nerve-core

License

MIT