@acpfx/core 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @acpfx/core
+
+## 0.2.0
+
+### Minor Changes
+
+- d757640: Initial release: type-safe contracts, Rust orchestrator, manifest-driven event filtering
+
+  - Rust schema crate as canonical event type source of truth with codegen to TypeScript + Zod
+  - Node manifests (manifest.yaml) declaring consumes/emits contracts
+  - Orchestrator event filtering: nodes only receive declared events
+  - Rust orchestrator with ratatui TUI (--ui flag)
+  - node-sdk with structured logging helpers
+  - CI/CD with GitHub Actions and changesets
+  - Platform-specific npm packages for Rust binaries (esbuild-style distribution)

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@acpfx/core",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "yaml": "^2.8.3"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external"
+  }
+}

package/src/config.ts

@@ -0,0 +1,130 @@
+/**
+ * YAML config loader and validator for acpfx v2 pipeline configs.
+ *
+ * Config format:
+ * ```yaml
+ * nodes:
+ *   <name>:
+ *     use: "@acpfx/<impl>"
+ *     settings: { ... }
+ *     outputs: [<name>, ...]
+ * env:
+ *   KEY: value
+ * ```
+ */
+
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+
+// ---- Config types ----
+
+export type NodeConfig = {
+  use: string;
+  settings?: Record<string, unknown>;
+  outputs?: string[];
+};
+
+export type PipelineConfig = {
+  nodes: Record<string, NodeConfig>;
+  env?: Record<string, string>;
+};
+
+// ---- Validation errors ----
+
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+// ---- Loader ----
+
+/** Load and validate a YAML config file. */
+export function loadConfig(path: string): PipelineConfig {
+  const raw = readFileSync(path, "utf-8");
+  return parseConfig(raw);
+}
+
+/** Parse and validate a YAML string. */
+export function parseConfig(yaml: string): PipelineConfig {
+  const doc = parseYaml(yaml);
+  return validateConfig(doc);
+}
+
+// ---- Validation ----
+
+function validateConfig(doc: unknown): PipelineConfig {
+  if (!doc || typeof doc !== "object") {
+    throw new ConfigError("Config must be a YAML object");
+  }
+
+  const obj = doc as Record<string, unknown>;
+
+  if (!obj.nodes || typeof obj.nodes !== "object") {
+    throw new ConfigError("Config must have a 'nodes' object");
+  }
+
+  const nodes = obj.nodes as Record<string, unknown>;
+  const nodeNames = new Set(Object.keys(nodes));
+
+  if (nodeNames.size === 0) {
+    throw new ConfigError("Config must have at least one node");
+  }
+
+  const validatedNodes: Record<string, NodeConfig> = {};
+
+  for (const [name, raw] of Object.entries(nodes)) {
+    if (!raw || typeof raw !== "object") {
+      throw new ConfigError(`Node '${name}' must be an object`);
+    }
+
+    const node = raw as Record<string, unknown>;
+
+    if (typeof node.use !== "string" || node.use.length === 0) {
+      throw new ConfigError(`Node '${name}' must have a 'use' string`);
+    }
+
+    let outputs: string[] | undefined;
+    if (node.outputs !== undefined) {
+      if (!Array.isArray(node.outputs)) {
+        throw new ConfigError(`Node '${name}'.outputs must be an array`);
+      }
+      outputs = [];
+      for (const out of node.outputs) {
+        if (typeof out !== "string") {
+          throw new ConfigError(
+            `Node '${name}'.outputs must contain strings`,
+          );
+        }
+        if (!nodeNames.has(out)) {
+          throw new ConfigError(
+            `Node '${name}' outputs to undefined node '${out}'`,
+          );
+        }
+        outputs.push(out);
+      }
+    }
+
+    const settings =
+      node.settings && typeof node.settings === "object"
+        ? (node.settings as Record<string, unknown>)
+        : undefined;
+
+    validatedNodes[name] = { use: node.use, settings, outputs };
+  }
+
+  // Validate env
+  let env: Record<string, string> | undefined;
+  if (obj.env !== undefined) {
+    if (typeof obj.env !== "object" || obj.env === null) {
+      throw new ConfigError("'env' must be an object");
+    }
+    env = {};
+    for (const [k, v] of Object.entries(obj.env as Record<string, unknown>)) {
+      env[k] = String(v);
+    }
+  }
+
+  return { nodes: validatedNodes, env };
+}

package/src/dag.ts

@@ -0,0 +1,152 @@
+/**
+ * Directed graph construction from a PipelineConfig.
+ *
+ * - Builds an adjacency list from node outputs
+ * - Produces a topological ordering (nodes in cycles are appended in config declaration order)
+ * - Computes downstream sets for interrupt propagation
+ */
+
+import { PipelineConfig } from "./config.js";
+
+export class DagError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DagError";
+  }
+}
+
+export type DagNode = {
+  name: string;
+  use: string;
+  settings?: Record<string, unknown>;
+  outputs: string[];
+  /** Event types this node declares it consumes (from manifest). Empty = accepts all. */
+  consumes: string[];
+  /** Event types this node declares it emits (from manifest). Empty = emits any. */
+  emits: string[];
+};
+
+export type Dag = {
+  /** All nodes keyed by name. */
+  nodes: Map<string, DagNode>;
+  /** Topological order (sources first). */
+  order: string[];
+  /** For a given node, all nodes downstream (transitive). Used for interrupt propagation. */
+  downstream: Map<string, Set<string>>;
+};
+
+/** Build and validate a DAG from a pipeline config. */
+export function buildDag(config: PipelineConfig): Dag {
+  const nodes = new Map<string, DagNode>();
+
+  for (const [name, nc] of Object.entries(config.nodes)) {
+    nodes.set(name, {
+      name,
+      use: nc.use,
+      settings: nc.settings,
+      outputs: nc.outputs ?? [],
+      consumes: [],
+      emits: [],
+    });
+  }
+
+  // Validate all output references exist (config.ts already does this, but belt-and-suspenders)
+  for (const node of nodes.values()) {
+    for (const out of node.outputs) {
+      if (!nodes.has(out)) {
+        throw new DagError(
+          `Node '${node.name}' outputs to undefined node '${out}'`,
+        );
+      }
+    }
+  }
+
+  const order = topologicalSort(nodes);
+  const downstream = computeDownstream(nodes);
+
+  return { nodes, order, downstream };
+}
+
+/**
+ * Check if a node accepts a given event type based on its manifest.
+ * If the node has no consumes list (empty), it accepts everything (permissive mode).
+ */
+export function nodeConsumesEvent(node: DagNode, eventType: string): boolean {
+  if (node.consumes.length === 0) return true; // permissive: no manifest or empty consumes
+  return node.consumes.includes(eventType);
+}
+
+// ---- Topological sort (Kahn's algorithm, cycles allowed) ----
+
+function topologicalSort(nodes: Map<string, DagNode>): string[] {
+  // Compute in-degrees
+  const inDegree = new Map<string, number>();
+  for (const name of nodes.keys()) {
+    inDegree.set(name, 0);
+  }
+  for (const node of nodes.values()) {
+    for (const out of node.outputs) {
+      inDegree.set(out, (inDegree.get(out) ?? 0) + 1);
+    }
+  }
+
+  // Start with zero in-degree nodes
+  const queue: string[] = [];
+  for (const [name, deg] of inDegree) {
+    if (deg === 0) queue.push(name);
+  }
+  // Sort for deterministic order
+  queue.sort();
+
+  const result: string[] = [];
+  while (queue.length > 0) {
+    const name = queue.shift()!;
+    result.push(name);
+    const node = nodes.get(name)!;
+    for (const out of node.outputs) {
+      const newDeg = (inDegree.get(out) ?? 1) - 1;
+      inDegree.set(out, newDeg);
+      if (newDeg === 0) {
+        // Insert sorted for deterministic order
+        const idx = queue.findIndex((q) => q > out);
+        if (idx === -1) queue.push(out);
+        else queue.splice(idx, 0, out);
+      }
+    }
+  }
+
+  if (result.length !== nodes.size) {
+    // Nodes in cycles: append in config declaration order
+    const sorted = new Set(result);
+    for (const name of nodes.keys()) {
+      if (!sorted.has(name)) result.push(name);
+    }
+  }
+
+  return result;
+}
+
+// ---- Downstream computation (transitive closure) ----
+
+function computeDownstream(nodes: Map<string, DagNode>): Map<string, Set<string>> {
+  const downstream = new Map<string, Set<string>>();
+
+  for (const name of nodes.keys()) {
+    const visited = new Set<string>();
+    const stack = [...(nodes.get(name)?.outputs ?? [])];
+    while (stack.length > 0) {
+      const cur = stack.pop()!;
+      if (visited.has(cur)) continue;
+      visited.add(cur);
+      const curNode = nodes.get(cur);
+      if (curNode) {
+        for (const out of curNode.outputs) {
+          if (!visited.has(out)) stack.push(out);
+        }
+      }
+    }
+    downstream.set(name, visited);
+  }
+
+  return downstream;
+}

package/src/generated-types.ts

@@ -0,0 +1,253 @@
+/**
+ * AUTO-GENERATED by acpfx-codegen from packages/schema (Rust).
+ * DO NOT EDIT — re-run `cargo run -p acpfx-schema --bin acpfx-codegen`.
+ */
+
+/** Fields added by the orchestrator to every routed event. */
+export type OrchestratorStamp = {
+  ts?: number;
+  _from?: string;
+};
+
+// ---- Audio ----
+
+export type AudioChunkEvent = OrchestratorStamp & {
+  type: "audio.chunk";
+  trackId: string;
+  format: string;
+  sampleRate: number;
+  channels: number;
+  data: string;
+  durationMs: number;
+  kind?: "speech" | "sfx";
+};
+
+export type AudioLevelEvent = OrchestratorStamp & {
+  type: "audio.level";
+  trackId: string;
+  rms: number;
+  peak: number;
+  dbfs: number;
+};
+
+// ---- Speech Recognition ----
+
+export type SpeechPartialEvent = OrchestratorStamp & {
+  type: "speech.partial";
+  trackId: string;
+  text: string;
+};
+
+export type SpeechDeltaEvent = OrchestratorStamp & {
+  type: "speech.delta";
+  trackId: string;
+  text: string;
+  replaces?: string;
+};
+
+export type SpeechFinalEvent = OrchestratorStamp & {
+  type: "speech.final";
+  trackId: string;
+  text: string;
+  confidence?: number;
+};
+
+export type SpeechPauseEvent = OrchestratorStamp & {
+  type: "speech.pause";
+  trackId: string;
+  pendingText: string;
+  silenceMs: number;
+};
+
+// ---- Agent/LLM ----
+
+export type AgentSubmitEvent = OrchestratorStamp & {
+  type: "agent.submit";
+  requestId: string;
+  text: string;
+};
+
+export type AgentDeltaEvent = OrchestratorStamp & {
+  type: "agent.delta";
+  requestId: string;
+  delta: string;
+  seq: number;
+};
+
+export type AgentCompleteEvent = OrchestratorStamp & {
+  type: "agent.complete";
+  requestId: string;
+  text: string;
+  tokenUsage?: { input: number; output: number };
+};
+
+export type AgentThinkingEvent = OrchestratorStamp & {
+  type: "agent.thinking";
+  requestId: string;
+};
+
+export type AgentToolStartEvent = OrchestratorStamp & {
+  type: "agent.tool_start";
+  requestId: string;
+  toolCallId: string;
+  title?: string;
+};
+
+export type AgentToolDoneEvent = OrchestratorStamp & {
+  type: "agent.tool_done";
+  requestId: string;
+  toolCallId: string;
+  status: string;
+};
+
+// ---- Control ----
+
+export type ControlInterruptEvent = OrchestratorStamp & {
+  type: "control.interrupt";
+  reason: string;
+};
+
+export type ControlStateEvent = OrchestratorStamp & {
+  type: "control.state";
+  component: string;
+  state: string;
+};
+
+export type ControlErrorEvent = OrchestratorStamp & {
+  type: "control.error";
+  component: string;
+  message: string;
+  fatal: boolean;
+};
+
+// ---- Lifecycle ----
+
+export type LifecycleReadyEvent = OrchestratorStamp & {
+  type: "lifecycle.ready";
+  component: string;
+};
+
+export type LifecycleDoneEvent = OrchestratorStamp & {
+  type: "lifecycle.done";
+  component: string;
+};
+
+// ---- Log ----
+
+export type LogEvent = OrchestratorStamp & {
+  type: "log";
+  level: "info" | "warn" | "error" | "debug";
+  component: string;
+  message: string;
+};
+
+// ---- Player ----
+
+export type PlayerStatusEvent = OrchestratorStamp & {
+  type: "player.status";
+  playing: unknown;
+  agentState: unknown;
+  sfxActive: boolean;
+};
+
+// ---- Union types ----
+
+export type AudioEvent = AudioChunkEvent | AudioLevelEvent;
+
+export type SpeechEvent =
+  | SpeechPartialEvent
+  | SpeechDeltaEvent
+  | SpeechFinalEvent
+  | SpeechPauseEvent;
+
+export type AgentEvent =
+  | AgentSubmitEvent
+  | AgentDeltaEvent
+  | AgentCompleteEvent
+  | AgentThinkingEvent
+  | AgentToolStartEvent
+  | AgentToolDoneEvent;
+
+export type ControlEvent =
+  | ControlInterruptEvent
+  | ControlStateEvent
+  | ControlErrorEvent;
+
+export type LifecycleEvent = LifecycleReadyEvent | LifecycleDoneEvent;
+export type LogEventType = LogEvent;
+
+export type PlayerEvent = PlayerStatusEvent;
+
+export type PipelineEvent =
+  | AudioEvent
+  | SpeechEvent
+  | AgentEvent
+  | ControlEvent
+  | LifecycleEvent
+  | LogEvent
+  | PlayerEvent;
+
+/** An event with a `type` field that doesn't match a known type. Forwarded unchanged. */
+export type UnknownEvent = OrchestratorStamp & {
+  type: string;
+  [key: string]: unknown;
+};
+
+export type AnyEvent = PipelineEvent | UnknownEvent;
+
+// ---- Type discrimination ----
+
+const KNOWN_TYPES = new Set([
+  "audio.chunk",
+  "audio.level",
+  "speech.partial",
+  "speech.delta",
+  "speech.final",
+  "speech.pause",
+  "agent.submit",
+  "agent.delta",
+  "agent.complete",
+  "agent.thinking",
+  "agent.tool_start",
+  "agent.tool_done",
+  "control.interrupt",
+  "control.state",
+  "control.error",
+  "lifecycle.ready",
+  "lifecycle.done",
+  "log",
+  "player.status",
+]);
+
+export function isKnownEventType(type: string): boolean {
+  return KNOWN_TYPES.has(type);
+}
+
+// ---- Serialization ----
+
+export function parseEvent(json: string): AnyEvent {
+  const obj = JSON.parse(json);
+  if (!obj || typeof obj !== "object" || typeof obj.type !== "string") {
+    throw new Error("Invalid event: missing 'type' field");
+  }
+  return obj as AnyEvent;
+}
+
+export function serializeEvent(event: AnyEvent): string {
+  return JSON.stringify(event);
+}
+
+// ---- Helpers ----
+
+/** Create an event with the given type and payload. */
+export function createEvent<T extends AnyEvent>(event: T): T {
+  return event;
+}
+
+/** Stamp an event with orchestrator metadata. */
+export function stampEvent<T extends AnyEvent>(
+  event: T,
+  from: string,
+): T & Required<OrchestratorStamp> {
+  return { ...event, ts: Date.now(), _from: from };
+}

package/src/generated-zod.ts

@@ -0,0 +1,160 @@
+/**
+ * AUTO-GENERATED by acpfx-codegen from packages/schema (Rust).
+ * DO NOT EDIT — re-run `cargo run -p acpfx-schema --bin acpfx-codegen`.
+ */
+
+import { z } from "zod";
+
+export const OrchestratorStampSchema = z.object({
+  ts: z.number().optional(),
+  _from: z.string().optional(),
+});
+
+export const AudioChunkEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("audio.chunk"),
+  trackId: z.string(),
+  format: z.string(),
+  sampleRate: z.number(),
+  channels: z.number(),
+  data: z.string(),
+  durationMs: z.number(),
+  kind: z.enum(["speech", "sfx"]).optional(),
+});
+
+export const AudioLevelEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("audio.level"),
+  trackId: z.string(),
+  rms: z.number(),
+  peak: z.number(),
+  dbfs: z.number(),
+});
+
+export const SpeechPartialEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("speech.partial"),
+  trackId: z.string(),
+  text: z.string(),
+});
+
+export const SpeechDeltaEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("speech.delta"),
+  trackId: z.string(),
+  text: z.string(),
+  replaces: z.string().optional(),
+});
+
+export const SpeechFinalEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("speech.final"),
+  trackId: z.string(),
+  text: z.string(),
+  confidence: z.number().optional(),
+});
+
+export const SpeechPauseEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("speech.pause"),
+  trackId: z.string(),
+  pendingText: z.string(),
+  silenceMs: z.number(),
+});
+
+export const AgentSubmitEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("agent.submit"),
+  requestId: z.string(),
+  text: z.string(),
+});
+
+export const AgentDeltaEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("agent.delta"),
+  requestId: z.string(),
+  delta: z.string(),
+  seq: z.number(),
+});
+
+export const AgentCompleteEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("agent.complete"),
+  requestId: z.string(),
+  text: z.string(),
+  tokenUsage: z.object({ input: z.number(), output: z.number() }).optional(),
+});
+
+export const AgentThinkingEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("agent.thinking"),
+  requestId: z.string(),
+});
+
+export const AgentToolStartEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("agent.tool_start"),
+  requestId: z.string(),
+  toolCallId: z.string(),
+  title: z.string().optional(),
+});
+
+export const AgentToolDoneEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("agent.tool_done"),
+  requestId: z.string(),
+  toolCallId: z.string(),
+  status: z.string(),
+});
+
+export const ControlInterruptEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("control.interrupt"),
+  reason: z.string(),
+});
+
+export const ControlStateEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("control.state"),
+  component: z.string(),
+  state: z.string(),
+});
+
+export const ControlErrorEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("control.error"),
+  component: z.string(),
+  message: z.string(),
+  fatal: z.boolean(),
+});
+
+export const LifecycleReadyEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("lifecycle.ready"),
+  component: z.string(),
+});
+
+export const LifecycleDoneEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("lifecycle.done"),
+  component: z.string(),
+});
+
+export const LogEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("log"),
+  level: z.enum(["info", "warn", "error", "debug"]),
+  component: z.string(),
+  message: z.string(),
+});
+
+export const PlayerStatusEventSchema = OrchestratorStampSchema.extend({
+  type: z.literal("player.status"),
+  playing: z.unknown(),
+  agentState: z.unknown(),
+  sfxActive: z.boolean(),
+});
+
+export const PipelineEventSchema = z.discriminatedUnion("type", [
+  AudioChunkEventSchema,
+  AudioLevelEventSchema,
+  SpeechPartialEventSchema,
+  SpeechDeltaEventSchema,
+  SpeechFinalEventSchema,
+  SpeechPauseEventSchema,
+  AgentSubmitEventSchema,
+  AgentDeltaEventSchema,
+  AgentCompleteEventSchema,
+  AgentThinkingEventSchema,
+  AgentToolStartEventSchema,
+  AgentToolDoneEventSchema,
+  ControlInterruptEventSchema,
+  ControlStateEventSchema,
+  ControlErrorEventSchema,
+  LifecycleReadyEventSchema,
+  LifecycleDoneEventSchema,
+  LogEventSchema,
+  PlayerStatusEventSchema,
+]);

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./generated-types.js";
+export * from "./config.js";
+export * from "./dag.js";
+export * from "./manifest.js";

package/src/manifest.ts

@@ -0,0 +1,60 @@
+/**
+ * Manifest utilities for acpfx nodes.
+ *
+ * Call `handleManifestFlag()` at the top of your node's entry point.
+ * If `--manifest` is in argv, it prints the manifest as JSON and exits.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export interface NodeManifest {
+  name: string;
+  description?: string;
+  consumes: string[];
+  emits: string[];
+}
+
+/**
+ * If `--manifest` is in process.argv, read the co-located manifest.json,
+ * print it to stdout, and exit(0).
+ *
+ * Resolution order:
+ * 1. Explicit `manifestPath` if provided
+ * 2. `<script-base>.manifest.json` (bundled: dist/nodes/foo.js -> foo.manifest.json)
+ * 3. `manifest.json` in the script's directory
+ */
+export function handleManifestFlag(manifestPath?: string): void {
+  if (!process.argv.includes("--manifest")) return;
+
+  if (!manifestPath) {
+    const script = process.argv[1];
+    const scriptDir = dirname(script);
+    const scriptBase = script.replace(/\.[^.]+$/, "");
+    const colocated = `${scriptBase}.manifest.json`;
+    try {
+      readFileSync(colocated);
+      manifestPath = colocated;
+    } catch {
+      manifestPath = join(scriptDir, "manifest.json");
+    }
+  }
+
+  try {
+    const content = readFileSync(manifestPath, "utf8");
+    // Already JSON — just write it out
+    process.stdout.write(content.trim() + "\n");
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Failed to read manifest: ${err}\n`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Load a manifest from a JSON file.
+ */
+export function loadManifestJson(path: string): NodeManifest {
+  const content = readFileSync(path, "utf8");
+  return JSON.parse(content) as NodeManifest;
+}