@barnum/barnum 0.0.0-main-45fcbab9 → 0.0.0-main-94079f39

package/barnum-config-schema.json

@@ -89,6 +89,10 @@
             "stepConfig": {
               "description": "Step configuration passed through to the handler. Rust stores this as-is and includes it in the envelope.",
               "default": null
+            },
+            "valueSchema": {
+              "description": "JSON Schema for this step's input value. Produced by JS from Zod. Used to validate transition values targeting this step.",
+              "default": null
             }
           }
         }

package/barnum-config-schema.zod.ts

@@ -10,6 +10,7 @@ const ActionKind = z.discriminatedUnion("kind", [
     kind: z.literal("TypeScript"),
     path: z.string().describe("Path to the handler file (absolute — JS layer resolves before passing to Rust)."),
     stepConfig: z.any().optional().default(null).describe("Step configuration passed through to the handler. Rust stores this as-is and includes it in the envelope."),
+    valueSchema: z.any().optional().default(null).describe("JSON Schema for this step's input value. Produced by JS from Zod. Used to validate transition values targeting this step."),
   }).describe("Run a TypeScript handler."),
 ]).describe("How a step processes tasks.");
 

package/index.ts

@@ -1,3 +1,8 @@
 export * from "./barnum-config-schema.zod.js";
 export * from "./barnum-cli-schema.zod.js";
 export { BarnumConfig, type RunOptions } from "./run.js";
+export type {
+  HandlerDefinition,
+  HandlerContext,
+  FollowUpTask,
+} from "./types.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barnum/barnum",
-  "version": "0.0.0-main-45fcbab9",
+  "version": "0.0.0-main-94079f39",
   "type": "module",
   "description": "Barnum CLI - workflow engine for agents.",
   "main": "index.ts",
@@ -40,13 +40,15 @@
     "barnum-config-schema.zod.ts",
     "barnum-cli-schema.zod.ts",
     "run.ts",
+    "types.ts",
     "actions/**/*.ts"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "zod": "^3.0.0"
+    "zod": "^3.0.0",
+    "zod-to-json-schema": "^3.25.1"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",

package/run.ts

@@ -4,7 +4,8 @@ import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { configSchema } from "./barnum-config-schema.zod.js";
-import type { z } from "zod";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -40,6 +41,67 @@ export interface RunOptions {
   cwd?: string;
 }
 
+// ==================== Zod subset validation ====================
+
+const UNSUPPORTED_ZOD_TYPES = new Set([
+  "ZodEffects", // .transform(), .refine(), .superRefine(), .preprocess()
+  "ZodPipeline", // .pipe()
+  "ZodBranded", // .brand()
+]);
+
+function assertSerializableZod(schema: z.ZodType, stepName: string): void {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const def = (schema as any)._def;
+  if (!def) return;
+
+  const typeName: string | undefined = def.typeName;
+
+  if (typeName && UNSUPPORTED_ZOD_TYPES.has(typeName)) {
+    throw new Error(
+      `Step "${stepName}": Zod schema uses unsupported type "${typeName}". ` +
+        `Only JSON-Schema-representable types are allowed. ` +
+        `Remove .transform(), .refine(), .preprocess(), .pipe(), or .brand().`,
+    );
+  }
+
+  // Recurse into compound types
+  if (def.innerType) assertSerializableZod(def.innerType, stepName);
+  if (def.schema) assertSerializableZod(def.schema, stepName);
+  if (def.left) assertSerializableZod(def.left, stepName);
+  if (def.right) assertSerializableZod(def.right, stepName);
+
+  // z.object() — check each value
+  if (def.shape) {
+    const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+    for (const value of Object.values(shape)) {
+      assertSerializableZod(value as z.ZodType, stepName);
+    }
+  }
+
+  // z.array(), z.set()
+  if (def.type) assertSerializableZod(def.type, stepName);
+
+  // z.union(), z.discriminatedUnion()
+  if (def.options) {
+    for (const option of def.options) {
+      assertSerializableZod(option as z.ZodType, stepName);
+    }
+  }
+
+  // z.tuple()
+  if (def.items) {
+    for (const item of def.items) {
+      assertSerializableZod(item as z.ZodType, stepName);
+    }
+  }
+
+  // z.record()
+  if (def.keyType) assertSerializableZod(def.keyType, stepName);
+  if (def.valueType) assertSerializableZod(def.valueType, stepName);
+}
+
+// ==================== BarnumConfig ====================
+
 export class BarnumConfig {
   private readonly config: z.output<typeof configSchema>;
 
@@ -51,11 +113,52 @@ export class BarnumConfig {
     return new BarnumConfig(configSchema.parse(config));
   }
 
-  run(opts?: RunOptions): ChildProcess {
+  private async resolveConfig(): Promise<z.output<typeof configSchema>> {
+    const config = structuredClone(this.config);
+
+    for (const step of config.steps) {
+      if (step.action.kind !== "TypeScript") continue;
+      const action = step.action;
+
+      // Import the handler module
+      const mod = await import(action.path);
+      const handler = mod[action.exportedAs ?? "default"];
+
+      if (!handler?.stepConfigValidator || !handler?.getStepValueValidator) {
+        throw new Error(
+          `Step "${step.name}": handler at "${action.path}" is missing required ` +
+            `"stepConfigValidator" or "getStepValueValidator". ` +
+            `See HandlerDefinition interface.`,
+        );
+      }
+
+      // Validate step config
+      const parsedStepConfig = handler.stepConfigValidator.parse(
+        action.stepConfig ?? {},
+      );
+
+      // Get value validator
+      const valueValidator = handler.getStepValueValidator(parsedStepConfig);
+
+      // Reject non-serializable Zod features
+      assertSerializableZod(valueValidator, step.name);
+
+      // Convert Zod → JSON Schema and embed in config
+      action.valueSchema = zodToJsonSchema(valueValidator, {
+        target: "jsonSchema7",
+      });
+    }
+
+    return config;
+  }
+
+  async run(opts?: RunOptions): Promise<ChildProcess> {
+    const config = await this.resolveConfig();
     const args = opts?.resumeFrom
       ? ["run", "--resume-from", opts.resumeFrom]
-      : ["run", "--config", JSON.stringify(this.config)];
-    if (opts?.entrypointValue) args.push("--entrypoint-value", opts.entrypointValue);
+      : ["run", "--config", JSON.stringify(config)];
+    if (opts?.entrypointValue)
+      args.push("--entrypoint-value", opts.entrypointValue);
     if (opts?.logLevel) args.push("--log-level", opts.logLevel);
     if (opts?.logFile) args.push("--log-file", opts.logFile);
     if (opts?.stateLog) args.push("--state-log", opts.stateLog);

package/types.ts

@@ -0,0 +1,19 @@
+import type { z } from "zod";
+
+export interface HandlerDefinition<C = unknown, V = unknown> {
+  stepConfigValidator: z.ZodType<C>;
+  getStepValueValidator: (stepConfig: C) => z.ZodType<V>;
+  handle: (context: HandlerContext<C, V>) => Promise<FollowUpTask[]>;
+}
+
+export interface HandlerContext<C, V> {
+  stepConfig: C;
+  value: V;
+  config: unknown;
+  stepName: string;
+}
+
+export interface FollowUpTask {
+  kind: string;
+  value: unknown;
+}