@barnum/barnum 0.0.0-main-94079f39 → 0.0.0-main-68fd94ca

package/index.ts

@@ -1,6 +1,7 @@
 export * from "./barnum-config-schema.zod.js";
 export * from "./barnum-cli-schema.zod.js";
 export { BarnumConfig, type RunOptions } from "./run.js";
+export { Handler, createHandler, isHandler } from "./types.js";
 export type {
   HandlerDefinition,
   HandlerContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barnum/barnum",
-  "version": "0.0.0-main-94079f39",
+  "version": "0.0.0-main-68fd94ca",
   "type": "module",
   "description": "Barnum CLI - workflow engine for agents.",
   "main": "index.ts",

package/run.ts

@@ -32,7 +32,7 @@ function spawnBarnum(args: string[], cwd?: string): ChildProcess {
 }
 
 export interface RunOptions {
-  entrypointValue?: string;
+  entrypointValue?: unknown;
   resumeFrom?: string;
   logLevel?: string;
   logFile?: string;
@@ -157,8 +157,8 @@ export class BarnumConfig {
     const args = opts?.resumeFrom
       ? ["run", "--resume-from", opts.resumeFrom]
       : ["run", "--config", JSON.stringify(config)];
-    if (opts?.entrypointValue)
-      args.push("--entrypoint-value", opts.entrypointValue);
+    if (opts?.entrypointValue != null)
+      args.push("--entrypoint-value", JSON.stringify(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

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import { fileURLToPath } from "node:url";
 
 export interface HandlerDefinition<C = unknown, V = unknown> {
   stepConfigValidator: z.ZodType<C>;
@@ -17,3 +18,65 @@ export interface FollowUpTask {
   kind: string;
   value: unknown;
 }
+
+// ==================== Opaque Handler ====================
+
+const HANDLER_BRAND = Symbol.for("barnum:handler");
+
+export class Handler<C = unknown, V = unknown> {
+  readonly [HANDLER_BRAND] = true as const;
+  /** @internal */ readonly __filePath: string;
+  /** @internal */ readonly __definition: HandlerDefinition<C, V>;
+
+  /** @internal */
+  constructor(definition: HandlerDefinition<C, V>, filePath: string) {
+    this.__definition = definition;
+    this.__filePath = filePath;
+  }
+
+  handle(context: HandlerContext<C, V>): Promise<FollowUpTask[]> {
+    return this.__definition.handle(context);
+  }
+}
+
+export function isHandler(x: unknown): x is Handler {
+  return typeof x === "object" && x !== null && HANDLER_BRAND in x;
+}
+
+function getCallerFilePath(): string {
+  const original = Error.prepareStackTrace;
+  let callerFile: string | undefined;
+
+  Error.prepareStackTrace = (_err, stack) => {
+    // Frame 0: getCallerFilePath
+    // Frame 1: createHandler
+    // Frame 2: the file that called createHandler
+    const frame = stack[2];
+    callerFile = frame?.getFileName() ?? undefined;
+    return "";
+  };
+
+  const err = new Error();
+  void err.stack;
+  Error.prepareStackTrace = original;
+
+  if (!callerFile) {
+    throw new Error(
+      "createHandler: could not determine caller file path from stack trace. " +
+        "Pass the path explicitly: createHandler(definition, { path: import.meta.filename })",
+    );
+  }
+
+  if (callerFile.startsWith("file://")) {
+    return fileURLToPath(callerFile);
+  }
+  return callerFile;
+}
+
+export function createHandler<C, V>(
+  definition: HandlerDefinition<C, V>,
+  opts?: { path?: string },
+): Handler<C, V> {
+  const filePath = opts?.path ?? getCallerFilePath();
+  return new Handler(definition, filePath);
+}