@barnum/barnum 0.2.3 → 0.3.0

package/src/recursive.ts

@@ -0,0 +1,112 @@
+import {
+  type Action,
+  type Pipeable,
+  type TypedAction,
+  typedAction,
+  branch,
+} from "./ast.js";
+import { all } from "./all.js";
+import { chain } from "./chain.js";
+import {
+  constant,
+  identity,
+  extractField,
+  extractIndex,
+  tag,
+} from "./builtins.js";
+import { allocateResumeHandlerId } from "./effect-id.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type FunctionDef = [input: unknown, output: unknown];
+
+type FunctionRefs<TDefs extends FunctionDef[]> = {
+  [K in keyof TDefs]: TypedAction<TDefs[K][0], TDefs[K][1]>;
+};
+
+/**
+ * Constraint for the entry-point callback return type. Only requires the
+ * output phantom fields — omits __in and __in_co so that actions with
+ * In = never (e.g. pipelines starting from a call token) are assignable.
+ */
+type BodyResult<TOut> = Action & {
+  __out?: () => TOut;
+  __out_contra?: (output: TOut) => void;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const UNUSED_STATE: any = undefined;
+
+// ---------------------------------------------------------------------------
+// defineRecursiveFunctions
+// ---------------------------------------------------------------------------
+
+/**
+ * Define mutually recursive functions that can call each other.
+ *
+ * The type parameter is an array of [In, Out] tuples — one per function.
+ * TypeScript can't infer these from circular definitions, so they must be
+ * explicit.
+ *
+ * Returns a curried combinator: the first callback defines function bodies,
+ * the second receives the same call tokens and returns the workflow entry
+ * point.
+ *
+ * Desugars to a ResumeHandle with a Branch-based handler. Each call token
+ * is Chain(Tag("CallN"), ResumePerform(id)). The handler dispatches to the
+ * correct function body by tag. The caller's pipeline is preserved as a
+ * ResumePerformFrame across each call.
+ */
+export function defineRecursiveFunctions<TDefs extends FunctionDef[]>(
+  bodiesFn: (...fns: FunctionRefs<TDefs>) => {
+    [K in keyof TDefs]: Pipeable<TDefs[K][0], TDefs[K][1]>;
+  },
+): <TOut>(
+  entryFn: (...fns: FunctionRefs<TDefs>) => BodyResult<TOut>,
+) => TypedAction<any, TOut> {
+  const resumeHandlerId = allocateResumeHandlerId();
+
+  const resumePerform: Action = {
+    kind: "ResumePerform",
+    resume_handler_id: resumeHandlerId,
+  };
+
+  // Call tokens: Chain(Tag("CallN"), ResumePerform(resumeHandlerId))
+  const fnCount = bodiesFn.length;
+  const callTokens = Array.from({ length: fnCount }, (_, i) =>
+    typedAction(chain(tag(`Call${i}`), resumePerform as any) as Action),
+  );
+
+  // Get function body ASTs
+  const bodyActions = bodiesFn(
+    ...(callTokens as FunctionRefs<TDefs>),
+  ) as Action[];
+
+  // Branch cases: CallN → ExtractField("value") → bodyN
+  const cases: Record<string, Action> = {};
+  for (let i = 0; i < bodyActions.length; i++) {
+    cases[`Call${i}`] = chain(
+      extractField("value"),
+      bodyActions[i] as any,
+    ) as Action;
+  }
+
+  // Return curried entry-point combinator
+  return <TOut>(entryFn: (...fns: FunctionRefs<TDefs>) => BodyResult<TOut>) => {
+    const userBody = entryFn(...(callTokens as FunctionRefs<TDefs>)) as Action;
+
+    return typedAction<any, TOut>(
+      chain(all(identity, constant(UNUSED_STATE)), {
+        kind: "ResumeHandle",
+        resume_handler_id: resumeHandlerId,
+        body: chain(extractIndex(0), userBody as any) as Action,
+        handler: all(
+          chain(extractIndex(0), branch(cases) as any),
+          constant(UNUSED_STATE),
+        ) as Action,
+      } as Action) as Action,
+    );
+  };
+}

package/src/run.ts

@@ -0,0 +1,181 @@
+/**
+ * Workflow execution: resolves the barnum binary, tsx executor, and worker
+ * script, then spawns the workflow as a subprocess.
+ */
+
+import { execFileSync, spawn as nodeSpawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { Action, Config, ExtractOutput, Pipeable } from "./ast.js";
+import { chain } from "./chain.js";
+import { constant } from "./builtins.js";
+
+const __dirname = import.meta.dirname;
+
+/** Resolve the TypeScript executor. Uses bun if the workflow was launched with bun, otherwise tsx. */
+function resolveExecutor(): string {
+  if (process.versions.bun) {
+    return "bun";
+  }
+  const callerRequire = createRequire(process.argv[1] || import.meta.url);
+  const tsxPath = callerRequire.resolve("tsx/cli");
+  return `node ${tsxPath}`;
+}
+
+/** Resolve the platform-specific binary from the @barnum/barnum package artifacts. */
+function resolveInstalledBinary(): string | undefined {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  let artifactDir: string;
+  let binaryName = "barnum";
+
+  if (platform === "darwin" && arch === "arm64") {
+    artifactDir = "macos-arm64";
+  } else if (platform === "darwin") {
+    artifactDir = "macos-x64";
+  } else if (platform === "linux" && arch === "arm64") {
+    artifactDir = "linux-arm64";
+  } else if (platform === "linux") {
+    artifactDir = "linux-x64";
+  } else if (platform === "win32") {
+    artifactDir = "win-x64";
+    binaryName = "barnum.exe";
+  } else {
+    return undefined;
+  }
+
+  const callerRequire = createRequire(process.argv[1] || import.meta.url);
+  try {
+    const packageDir = path.dirname(
+      callerRequire.resolve("@barnum/barnum/package.json"),
+    );
+    const binaryPath = path.join(
+      packageDir,
+      "artifacts",
+      artifactDir,
+      binaryName,
+    );
+    if (existsSync(binaryPath)) {
+      return binaryPath;
+    }
+  } catch {
+    // Package not installed
+  }
+  return undefined;
+}
+
+type BinaryResolution =
+  | { kind: "Env"; path: string }
+  | { kind: "NodeModules"; path: string }
+  | { kind: "Local"; path: string };
+
+/** Resolve the barnum binary. Checks: BARNUM env var, local repo, node_modules. */
+function resolveBinary(): BinaryResolution {
+  if (process.env.BARNUM) {
+    return { kind: "Env", path: process.env.BARNUM };
+  }
+
+  const repoRoot = path.resolve(__dirname, "../../..");
+  if (existsSync(path.join(repoRoot, "Cargo.toml"))) {
+    return {
+      kind: "Local",
+      path: path.join(repoRoot, "target/debug/barnum"),
+    };
+  }
+
+  const installedBinaryPath = resolveInstalledBinary();
+  if (installedBinaryPath) {
+    return { kind: "NodeModules", path: installedBinaryPath };
+  }
+
+  throw new Error(
+    "Could not find barnum binary. Set BARNUM env var or install @barnum/barnum.",
+  );
+}
+
+/** Resolve worker.ts relative to this package. */
+function resolveWorker(): string {
+  return path.resolve(__dirname, "../src/worker.ts");
+}
+
+/** Build the barnum binary if using the local dev path. */
+function buildBinary(): void {
+  const repoRoot = path.resolve(__dirname, "../../..");
+  execFileSync("cargo", ["build", "-p", "barnum_cli"], {
+    cwd: repoRoot,
+    stdio: "ignore",
+  });
+}
+
+/** Run a pipeline to completion. Returns the workflow's final output value. */
+export function runPipeline<TPipeline extends Action>(
+  pipeline: TPipeline,
+  input?: unknown,
+): Promise<ExtractOutput<TPipeline>> {
+  const workflow =
+    input === undefined
+      ? pipeline
+      : (chain(constant(input) as Pipeable, pipeline as Pipeable) as Action);
+  return spawnBarnum({ workflow });
+}
+
+/** Spawn the barnum CLI with the given config. Returns the parsed final value from stdout. */
+function spawnBarnum<TOut>(config: Config): Promise<TOut> {
+  const binaryResolution = resolveBinary();
+  if (binaryResolution.kind === "Local") {
+    buildBinary();
+  }
+  const executor = resolveExecutor();
+  const worker = resolveWorker();
+  const configJson = JSON.stringify(config);
+
+  return new Promise<TOut>((resolve, reject) => {
+    const child = nodeSpawn(
+      binaryResolution.path,
+      [
+        "run",
+        "--config",
+        configJson,
+        "--executor",
+        executor,
+        "--worker",
+        worker,
+      ],
+      {
+        stdio: ["inherit", "pipe", "inherit"],
+      },
+    );
+
+    const stdoutChunks: Buffer[] = [];
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdoutChunks.push(chunk);
+    });
+
+    child.on("error", (error) => {
+      reject(new Error(`Failed to spawn barnum: ${error.message}`));
+    });
+
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`barnum exited with code ${code}`));
+        return;
+      }
+      const stdout = Buffer.concat(stdoutChunks).toString("utf8").trim();
+      if (!stdout) {
+        resolve(undefined as TOut);
+        return;
+      }
+      try {
+        resolve(JSON.parse(stdout) as TOut);
+      } catch {
+        reject(
+          new Error(`barnum produced non-JSON output on stdout: ${stdout}`),
+        );
+      }
+    });
+  });
+}

package/src/schema.ts

@@ -0,0 +1,118 @@
+import type { JSONSchema7 } from "json-schema";
+import { type z, toJSONSchema } from "zod";
+
+// Zod v4 schema def types that have child schemas.
+// Verified against Zod 4.3.6 internals — every compound type's def
+// shape and child property name is listed here.
+const CHILD_ACCESSORS: Record<string, (def: any) => z.ZodType[]> = {
+  object: (def) => Object.values(def.shape),
+  array: (def) => [def.element],
+  tuple: (def) => [...def.items, ...(def.rest ? [def.rest] : [])],
+  union: (def) => def.options,
+  intersection: (def) => [def.left, def.right],
+  record: (def) => [def.keyType, def.valueType],
+  // Wrappers with a single inner type
+  nullable: (def) => [def.innerType],
+  optional: (def) => [def.innerType],
+  nonoptional: (def) => [def.innerType],
+  default: (def) => [def.innerType],
+  catch: (def) => [def.innerType],
+  readonly: (def) => [def.innerType],
+  promise: (def) => [def.innerType],
+  // Pipe has two children
+  pipe: (def) => [def.in, def.out],
+  // Lazy resolves to inner schema
+  lazy: (def) => [def.getter()],
+};
+
+/**
+ * Walk the Zod schema tree and reject patterns that `toJSONSchema()`
+ * handles incorrectly or silently drops:
+ *
+ * - `z.intersection()` — produces `allOf` with `additionalProperties: false`
+ *   on both sides (from `io: "output"`), making the intersection unmatchable
+ *   on Draft 7.
+ *
+ * - `.refine()` / `.superRefine()` — silently stripped from JSON Schema
+ *   output, so the Rust side would accept values that fail the refinement.
+ *   Detected by checking for custom checks (`check._zod.def.check === "custom"`)
+ *   in the schema's checks array.
+ */
+function assertNoUnsupportedPatterns(
+  schema: z.ZodType,
+  label: string,
+  visited = new WeakSet<z.ZodType>(),
+): void {
+  if (visited.has(schema)) {
+    return;
+  }
+  visited.add(schema);
+
+  const def = (schema as any)._zod.def;
+
+  // Reject intersections
+  if (def.type === "intersection") {
+    throw new Error(
+      `Handler "${label}": z.intersection() is not supported. ` +
+        `It produces broken JSON Schema on Draft 7 because both sides ` +
+        `get additionalProperties: false. Use z.object().extend() or ` +
+        `z.object().merge() instead.`,
+    );
+  }
+
+  // Reject custom checks (from .refine() and .superRefine())
+  const checks: any[] | undefined = def.checks;
+  if (checks) {
+    for (const check of checks) {
+      if (check._zod.def.check === "custom") {
+        throw new Error(
+          `Handler "${label}": .refine() and .superRefine() are not ` +
+            `supported. Custom validations cannot be expressed in JSON ` +
+            `Schema and would be silently dropped.`,
+        );
+      }
+    }
+  }
+
+  // Recurse into children
+  const getChildren = CHILD_ACCESSORS[def.type];
+  if (getChildren) {
+    for (const child of getChildren(def)) {
+      assertNoUnsupportedPatterns(child, label, visited);
+    }
+  }
+}
+
+/**
+ * Convert a Zod schema to a JSON Schema document suitable for embedding
+ * in the serialized AST. Throws if the schema contains types that can't
+ * survive the TS → JSON → Rust boundary.
+ */
+export function zodToCheckedJsonSchema(
+  schema: z.ZodType,
+  label: string,
+): JSONSchema7 {
+  // Pre-validate: catch patterns that toJSONSchema() handles incorrectly
+  assertNoUnsupportedPatterns(schema, label);
+
+  let raw: Record<string, unknown>;
+  try {
+    raw = toJSONSchema(schema, {
+      target: "draft-07",
+      unrepresentable: "throw",
+      io: "output",
+      cycles: "throw",
+      reused: "inline",
+    }) as Record<string, unknown>;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Handler "${label}": Zod schema cannot be converted to JSON Schema: ${message}`,
+      { cause: error },
+    );
+  }
+
+  // Strip $schema — embedded schemas don't need the draft URI.
+  const { $schema: _, ...rest } = raw;
+  return rest as JSONSchema7;
+}

package/src/try-catch.ts

@@ -0,0 +1,53 @@
+import {
+  type Action,
+  type Pipeable,
+  type TypedAction,
+  typedAction,
+  buildRestartBranchAction,
+  TAG_BREAK,
+} from "./ast.js";
+import { allocateRestartHandlerId } from "./effect-id.js";
+
+// ---------------------------------------------------------------------------
+// tryCatch — type-level error handling via restart+Branch
+// ---------------------------------------------------------------------------
+
+/**
+ * HOAS combinator for type-level error handling. The body callback receives
+ * a `throwError` token — a `TypedAction<TError, never>` that, when placed
+ * in the pipeline, tags the error as Break, performs to the handler, which
+ * restarts the body. The body-level Branch routes to the recovery arm.
+ *
+ * This handles **type-level errors only** — values returned by handlers via
+ * the `Result` type. If a handler panics, throws a JavaScript exception, or
+ * the runtime crashes, the existing error propagation path handles it.
+ * tryCatch does not catch those. Analogous to Rust's `Result` vs `panic!`.
+ *
+ * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
+ *   `Chain(Tag("Continue"),`
+ *     `RestartHandle(id, ExtractIndex(0),`
+ *       `Branch({ Continue: body, Break: recovery })))`
+ *
+ * throwError = `Chain(Tag("Break"), RestartPerform(id))`
+ *
+ * When throwError fires: error tagged Break → `RestartPerform` → handler extracts
+ * payload → body restarts → Branch takes Break arm → recovery receives error.
+ */
+export function tryCatch<TIn, TOut, TError>(
+  body: (throwError: TypedAction<TError, never>) => Pipeable<TIn, TOut>,
+  recovery: Pipeable<TError, TOut>,
+): TypedAction<TIn, TOut> {
+  const restartHandlerId = allocateRestartHandlerId();
+
+  const throwError = typedAction<TError, never>({
+    kind: "Chain",
+    first: TAG_BREAK,
+    rest: { kind: "RestartPerform", restart_handler_id: restartHandlerId },
+  });
+
+  const bodyAction = body(throwError) as Action;
+
+  return typedAction(
+    buildRestartBranchAction(restartHandlerId, bodyAction, recovery as Action),
+  );
+}

package/src/worker.ts

@@ -0,0 +1,56 @@
+/**
+ * Worker script: invoked as `tsx worker.ts <module> <export>`.
+ *
+ * Protocol:
+ *   Rust → stdin:  JSON `{ "value": <any> }`
+ *   stdout → Rust: JSON result (handler return value)
+ *
+ * If the handler throws or the module/export can't be resolved, the
+ * process exits non-zero. Rust interprets that as a fatal workflow error.
+ */
+
+// Suppress EPIPE — when the Rust binary exits (e.g., a race was resolved),
+// orphan workers get broken pipe on stdout. This is expected, not an error.
+process.stdout.on("error", (error: NodeJS.ErrnoException) => {
+  if (error.code === "EPIPE") {
+    process.exit(0);
+  }
+  throw error;
+});
+
+async function main(): Promise<void> {
+  const [modulePath, exportName = "default"] = process.argv.slice(2);
+
+  if (!modulePath) {
+    process.stderr.write("worker: missing module path argument\n");
+    process.exit(1);
+  }
+
+  // Read entire stdin
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const input = JSON.parse(Buffer.concat(chunks).toString());
+
+  // Import handler, call it
+  const mod = await import(modulePath);
+  const handler = mod[exportName];
+
+  if (!handler?.__definition?.handle) {
+    process.stderr.write(
+      `worker: ${modulePath}:${exportName} is not a barnum handler\n`,
+    );
+    process.exit(1);
+  }
+
+  const result = await handler.__definition.handle({ value: input.value });
+
+  // Write result to stdout
+  process.stdout.write(JSON.stringify(result) ?? "null");
+}
+
+main().catch((error) => {
+  process.stderr.write(`worker: ${error}\n`);
+  process.exit(1);
+});

package/README.md

@@ -1,19 +0,0 @@
-# @barnum/barnum
-
-Barnum CLI - workflow engine for agents.
-
-## Installation
-
-```bash
-npm install -g @barnum/barnum
-```
-
-## Usage
-
-```bash
-barnum --help
-```
-
-## About
-
-Barnum is a task automation tool that orchestrates AI agents to execute multi-step workflows defined in configuration files.