@neotx/core 0.1.0-alpha.15 → 0.1.0-alpha.19

package/README.md

@@ -5,9 +5,9 @@ Orchestration engine for autonomous developer agents. This is the programmatic A
 ## Installation
 
 ```bash
-npm install @neotx/core
-# or
 pnpm add @neotx/core
+# or
+npm install @neotx/core
 ```
 
 Requires Node.js >= 22 and the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated.
@@ -15,9 +15,9 @@ Requires Node.js >= 22 and the [Claude Code CLI](https://docs.anthropic.com/en/d
 ## Quick Start
 
 ```typescript
-import { AgentRegistry, loadConfig, Orchestrator } from "@neotx/core";
+import { AgentRegistry, loadGlobalConfig, Orchestrator } from "@neotx/core";
 
-const config = await loadConfig("~/.neo/config.yml");
+const config = await loadGlobalConfig();
 
 const orchestrator = new Orchestrator(config, {
   journalDir: ".neo/journals",
@@ -34,21 +34,12 @@ for (const agent of registry.list()) {
   orchestrator.registerAgent(agent);
 }
 
-// Register a workflow
-orchestrator.registerWorkflow({
-  name: "implement",
-  steps: {
-    code: { agent: "developer" },
-    review: { agent: "reviewer-quality", dependsOn: ["code"] },
-  },
-});
-
 // Start the orchestrator
 await orchestrator.start();
 
 // Dispatch a task
 const result = await orchestrator.dispatch({
-  workflow: "implement",
+  agent: "developer",
   repo: "/path/to/repo",
   prompt: "Add rate limiting to the API",
   priority: "high",
@@ -87,8 +78,6 @@ import { Orchestrator } from "@neotx/core";
 const orchestrator = new Orchestrator(config, {
   middleware: [...],           // Optional middleware array
   journalDir: ".neo/journals", // Directory for JSONL journals
-  builtInWorkflowDir: "...",   // Path to built-in workflow YAML files
-  customWorkflowDir: "...",    // Path to custom workflow YAML files
 });
 ```
 
@@ -122,27 +111,17 @@ orchestrator.registerAgent({
   sandbox: "writable",
   source: "built-in",
 });
-
-// Register a workflow
-orchestrator.registerWorkflow({
-  name: "implement",
-  steps: {
-    code: { agent: "developer" },
-    review: { agent: "reviewer-quality", dependsOn: ["code"] },
-  },
-});
 ```
 
 #### Dispatch
 
 ```typescript
 const result = await orchestrator.dispatch({
-  workflow: "implement",      // Workflow name (required)
+  agent: "developer",         // Agent name (required)
   repo: "/path/to/repo",      // Repository path (required)
   prompt: "Add feature X",    // Task prompt (required)
   runId: "custom-id",         // Optional custom run ID
   priority: "high",           // "critical" | "high" | "medium" | "low"
-  step: "review",             // Start from a specific step
   metadata: { ticket: "123" }, // Arbitrary metadata (passed through events)
 });
 ```
@@ -152,10 +131,9 @@ Returns a `TaskResult`:
 ```typescript
 interface TaskResult {
   runId: string;
-  workflow: string;
+  agent: string;
   repo: string;
   status: "success" | "failure" | "timeout" | "cancelled";
-  steps: Record<string, StepResult>;
   branch?: string;
   costUsd: number;
   durationMs: number;
@@ -179,7 +157,7 @@ const status = orchestrator.status;
 // }
 
 const sessions = orchestrator.activeSessions;
-// [{ sessionId, runId, workflow, step, agent, repo, status, startedAt }]
+// [{ sessionId, runId, agent, repo, status, startedAt }]
 ```
 
 ### `AgentRegistry`
@@ -217,7 +195,7 @@ The orchestrator emits typed events for real-time monitoring:
 
 ```typescript
 orchestrator.on("session:start", (event) => {
-  // { type, sessionId, runId, workflow, step, agent, repo, metadata, timestamp }
+  // { type, sessionId, runId, agent, repo, metadata, timestamp }
 });
 
 orchestrator.on("session:complete", (event) => {
@@ -293,7 +271,7 @@ const customMiddleware: Middleware = {
   match: "Bash",            // Optional: only match specific tools
   async handler(event, context) {
     // event: { hookEvent, sessionId, toolName, input, output, message }
-    // context: { runId, workflow, step, agent, repo, get, set }
+    // context: { runId, agent, repo, get, set }
 
     const costToday = context.get("costToday");
 
@@ -421,8 +399,6 @@ const journal = new CostJournal({ dir: ".neo/journals" });
 await journal.append({
   timestamp: new Date().toISOString(),
   runId: "...",
-  workflow: "implement",
-  step: "code",
   sessionId: "...",
   agent: "developer",
   costUsd: 0.0842,
@@ -450,7 +426,7 @@ repos:
     defaultBranch: main
     branchPrefix: feat
     pushRemote: origin
-    autoCreatePr: false
+    gitStrategy: branch  # or "pr"
 
 concurrency:
   maxSessions: 5
@@ -482,6 +458,19 @@ mcpServers:
     headers:
       Authorization: "Bearer ${LINEAR_API_KEY}"
 
+supervisor:
+  port: 7777
+  heartbeatTimeoutMs: 300000
+  maxConsecutiveFailures: 3
+  maxEventsPerSec: 10
+  dailyCapUsd: 50
+  consolidationIntervalMs: 300000
+  compactionIntervalMs: 3600000
+  eventTimeoutMs: 300000
+
+memory:
+  embeddings: true              # Enable local vector embeddings
+
 idempotency:
   enabled: true
   key: metadata  # or "prompt"
@@ -511,6 +500,65 @@ await removeRepoFromGlobalConfig("/path/to/repo");
 const repos = await listReposFromGlobalConfig();
 ```
 
+## Supervisor Daemon
+
+The supervisor daemon runs as a long-lived process that monitors orchestrator health, processes events, and maintains memory.
+
+```typescript
+import { SupervisorDaemon, loadGlobalConfig } from "@neotx/core";
+
+const config = await loadGlobalConfig();
+
+const daemon = new SupervisorDaemon({
+  name: "supervisor",
+  config,
+  defaultInstructionsPath: "path/to/SUPERVISOR.md",
+});
+
+await daemon.start(); // Blocks until stopped
+await daemon.stop();
+```
+
+Components:
+- **WebhookServer** — receives events from orchestrator instances
+- **EventQueue** — rate-limited event processing with disk replay
+- **HeartbeatLoop** — periodic health checks and consolidation
+- **ActivityLog** — structured logging of supervisor actions
+
+## Memory Store
+
+Persistent memory with full-text search (FTS5) and optional vector search (sqlite-vec).
+
+```typescript
+import { MemoryStore } from "@neotx/core";
+
+const store = new MemoryStore("path/to/memory.sqlite");
+
+// Write a memory
+await store.write({
+  type: "fact",           // "fact" | "procedure" | "episode" | "focus" | "feedback" | "task"
+  scope: "/path/to/repo", // or "global"
+  content: "CI requires pnpm build before push",
+  source: "developer",
+});
+
+// Query by type and scope
+const memories = store.query({
+  scope: "/path/to/repo",
+  types: ["fact", "procedure"],
+  limit: 25,
+  sortBy: "relevance",    // "relevance" | "createdAt" | "accessCount"
+});
+
+// Semantic search (uses local embeddings via transformers.js)
+const results = await store.search("CI pipeline", { scope: "/path/to/repo" });
+
+// Lifecycle
+store.decay(30, 3);       // Remove stale low-access memories
+store.expireEphemeral();  // Remove expired focus entries
+store.close();
+```
+
 ## Types
 
 Key types exported from the package:
@@ -527,10 +575,6 @@ import type {
   AgentConfig,
   AgentDefinition,
 
-  // Workflows
-  WorkflowDefinition,
-  WorkflowStepDef,
-
   // Dispatch
   DispatchInput,
   TaskResult,