@rigkit/engine 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigkit/engine",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "type": "module",
   "repository": {
     "type": "git",

package/src/authoring.ts

@@ -17,6 +17,7 @@ import type {
   WorkflowNodeDefinition,
   WorkflowProviderDefinition,
   WorkflowProviderMap,
+  WorkflowCacheScope,
   WorkflowSequenceBuilder,
   WorkflowTaskHandler,
   WorkflowTaskNode,
@@ -25,9 +26,14 @@ import type {
   WorkflowWorkspaceDefinition,
 } from "./types.ts";
 
-const reservedTaskContextKeys = new Set(["ctx", "runtime", "providers", "step"]);
+const reservedTaskContextKeys = new Set(["config", "ctx", "runtime", "providers", "step"]);
 const reservedHostOperationIds = new Set<string>(RESERVED_WORKFLOW_OPERATION_IDS);
 
+type WorkflowNodeAuthoringOptions = {
+  cacheScope?: WorkflowCacheScope;
+  config?: JsonObject;
+};
+
 const readEnv = (name: string, fallback?: string): string => {
   const value = process.env[name];
   if (value !== undefined && value !== "") return value;
@@ -136,6 +142,7 @@ function createSequence<
   OperationIds extends string = never,
   WorkspaceOperationIds extends string = never,
   PreviousTaskIds extends string = never,
+  Config extends JsonObject = {},
 >(
   app: WorkflowDefinition<string, Providers>,
   name: string,
@@ -143,6 +150,7 @@ function createSequence<
   workspace?: WorkflowWorkspaceDefinition<Providers, OutputContext, any>,
   operations: readonly WorkflowOperationDefinition<Providers, any>[] = [],
   workspaceOperations: readonly WorkflowWorkspaceOperationDefinition<Providers, OutputContext, WorkspaceData, any>[] = [],
+  nodeOptions: WorkflowNodeAuthoringOptions = {},
 ): WorkflowSequenceBuilder<
   Providers,
   InputContext,
@@ -150,13 +158,16 @@ function createSequence<
   WorkspaceData,
   OperationIds,
   WorkspaceOperationIds,
-  PreviousTaskIds
+  PreviousTaskIds,
+  Config
 > {
   const node = {
     kind: "rigkit.workflow-node" as const,
     nodeKind: "sequence" as const,
     name,
     workflow: app,
+    cacheScope: nodeOptions.cacheScope,
+    config: nodeOptions.config,
     children,
     workspaceDefinition: workspace,
     operations,
@@ -167,7 +178,7 @@ function createSequence<
       maybeHandler?: WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, any>,
     ) => {
       const task = createTask(app, taskName, optionsOrHandler as any, maybeHandler as any);
-      return createSequence(app, name, [...children, task], workspace, operations, workspaceOperations);
+      return createSequence(app, name, [...children, task], workspace, operations, workspaceOperations, nodeOptions);
     },
     step: (
       taskName: string,
@@ -175,42 +186,56 @@ function createSequence<
       maybeHandler?: WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, any>,
     ) => {
       const task = createTask(app, taskName, optionsOrHandler as any, maybeHandler as any);
-      return createSequence(app, name, [...children, task], workspace, operations, workspaceOperations);
+      return createSequence(app, name, [...children, task], workspace, operations, workspaceOperations, nodeOptions);
     },
     add: (child: WorkflowNodeDefinition<Providers, any, any>) => {
-      assertSameWorkflow(app, child);
-      return createSequence(app, name, [...children, child], workspace, operations, workspaceOperations);
+      return createSequence(
+        app,
+        name,
+        [...children, attachWorkflowForAuthoring(app, child)],
+        workspace,
+        operations,
+        workspaceOperations,
+        nodeOptions,
+      );
     },
     parallel: (branches: Record<string, WorkflowNodeDefinition<Providers, any, any>>) => {
+      const attachedBranches: Record<string, WorkflowNodeDefinition<Providers, any, any>> = {};
       for (const [branchName, branch] of Object.entries(branches)) {
-        assertSameWorkflow(app, branch);
         if (!branchName) throw new Error(`Parallel branch names must be non-empty`);
+        attachedBranches[branchName] = attachWorkflowForAuthoring(app, branch);
       }
 
-      const parallelNode: WorkflowNodeDefinition<Providers, OutputContext, any> & {
-        nodeKind: "parallel";
-        branches: Record<string, WorkflowNodeDefinition<Providers, any, any>>;
-      } = {
-        kind: "rigkit.workflow-node",
-        nodeKind: "parallel",
-        name: "parallel",
-        workflow: app,
-        branches,
-      };
-      return createSequence(app, name, [...children, parallelNode], workspace, operations, workspaceOperations);
+      const parallelNode = createParallel(app, "parallel", attachedBranches);
+      return createSequence(app, name, [...children, parallelNode], workspace, operations, workspaceOperations, nodeOptions);
     },
     workspace: (definition: WorkflowWorkspaceDefinition<Providers, OutputContext, any>) =>
-      createSequence(app, name, children, definition, operations, workspaceOperations),
+      createSequence(app, name, children, definition, operations, workspaceOperations, nodeOptions),
     operation: (id: string, options: WorkflowOperationOptions<Providers, any>) => {
       const operation = createOperation(id, options);
       assertUniqueOperationId(operations, operation.id, "Operation");
-      return createSequence(app, name, children, workspace, [...operations, operation], workspaceOperations);
+      return createSequence(app, name, children, workspace, [...operations, operation], workspaceOperations, nodeOptions);
     },
     workspaceOperation: (id: string, options: WorkflowWorkspaceOperationOptions<Providers, OutputContext, any, any>) => {
       const operation = createWorkspaceOperation(id, options);
       assertUniqueOperationId(workspaceOperations, operation.id, "Workspace operation");
-      return createSequence(app, name, children, workspace, operations, [...workspaceOperations, operation]);
+      return createSequence(app, name, children, workspace, operations, [...workspaceOperations, operation], nodeOptions);
     },
+    global: () =>
+      createSequence(app, name, children, workspace, operations, workspaceOperations, {
+        ...nodeOptions,
+        cacheScope: "global",
+      }),
+    local: () =>
+      createSequence(app, name, children, workspace, operations, workspaceOperations, {
+        ...nodeOptions,
+        cacheScope: "local",
+      }),
+    configure: (config: JsonObject) =>
+      createSequence(app, name, children, workspace, operations, workspaceOperations, {
+        ...nodeOptions,
+        config: mergeConfig(nodeOptions.config, config),
+      }),
   };
 
   return node as unknown as WorkflowSequenceBuilder<
@@ -220,7 +245,8 @@ function createSequence<
     WorkspaceData,
     OperationIds,
     WorkspaceOperationIds,
-    PreviousTaskIds
+    PreviousTaskIds,
+    Config
   >;
 }
 
@@ -339,6 +365,7 @@ function createTask<
   name: string,
   optionsOrHandler: WorkflowTaskOptions | WorkflowTaskHandler<Providers, InputContext, PreviousTaskIds, any>,
   maybeHandler?: WorkflowTaskHandler<Providers, InputContext, PreviousTaskIds, any>,
+  nodeOptions: WorkflowNodeAuthoringOptions = {},
 ): WorkflowTaskNode<Providers, InputContext, any> {
   const options = typeof optionsOrHandler === "function" ? undefined : optionsOrHandler;
   const handler = (typeof optionsOrHandler === "function" ? optionsOrHandler : maybeHandler) as
@@ -351,11 +378,100 @@ function createTask<
     nodeKind: "task",
     name,
     workflow: app,
+    cacheScope: nodeOptions.cacheScope,
+    config: nodeOptions.config,
     options,
     handler,
+    global: (() => createTask(app, name, options ?? handler, options ? handler : undefined, {
+      ...nodeOptions,
+      cacheScope: "global",
+    })) as WorkflowTaskNode<Providers, InputContext, any>["global"],
+    local: (() => createTask(app, name, options ?? handler, options ? handler : undefined, {
+      ...nodeOptions,
+      cacheScope: "local",
+    })) as WorkflowTaskNode<Providers, InputContext, any>["local"],
+    configure: ((config: JsonObject) => createTask(app, name, options ?? handler, options ? handler : undefined, {
+      ...nodeOptions,
+      config: mergeConfig(nodeOptions.config, config),
+    })) as WorkflowTaskNode<Providers, InputContext, any>["configure"],
+  };
+}
+
+function createParallel<Providers extends WorkflowProviderMap, InputContext extends JsonObject>(
+  app: WorkflowDefinition<string, Providers>,
+  name: string,
+  branches: Record<string, WorkflowNodeDefinition<Providers, any, any>>,
+  nodeOptions: WorkflowNodeAuthoringOptions = {},
+): WorkflowNodeDefinition<Providers, InputContext, any> & {
+  nodeKind: "parallel";
+  branches: Record<string, WorkflowNodeDefinition<Providers, any, any>>;
+} {
+  const node = {
+    kind: "rigkit.workflow-node" as const,
+    nodeKind: "parallel" as const,
+    name,
+    workflow: app,
+    cacheScope: nodeOptions.cacheScope,
+    config: nodeOptions.config,
+    branches,
+    global: () => createParallel(app, name, branches, {
+      ...nodeOptions,
+      cacheScope: "global",
+    }),
+    local: () => createParallel(app, name, branches, {
+      ...nodeOptions,
+      cacheScope: "local",
+    }),
+    configure: (config: JsonObject) => createParallel(app, name, branches, {
+      ...nodeOptions,
+      config: mergeConfig(nodeOptions.config, config),
+    }),
+  };
+  return node as unknown as WorkflowNodeDefinition<Providers, InputContext, any> & {
+    nodeKind: "parallel";
+    branches: Record<string, WorkflowNodeDefinition<Providers, any, any>>;
   };
 }
 
+function mergeConfig(previous: JsonObject | undefined, next: JsonObject): JsonObject {
+  assertJsonObject(next, "configure input");
+  return previous ? { ...previous, ...next } : { ...next };
+}
+
+function assertJsonObject(value: JsonObject, label: string): void {
+  try {
+    JSON.stringify(value);
+  } catch (cause) {
+    throw new Error(`${label} must be JSON-serializable`, { cause });
+  }
+  assertJsonValue(value, label);
+}
+
+function assertJsonValue(value: unknown, label: string): void {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    typeof value === "number"
+  ) {
+    if (typeof value === "number" && !Number.isFinite(value)) {
+      throw new Error(`${label} must be JSON-serializable`);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertJsonValue(item, `${label}[${index}]`));
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, item] of Object.entries(value)) {
+      assertJsonValue(item, `${label}.${key}`);
+    }
+    return;
+  }
+  throw new Error(`${label} must be JSON-serializable`);
+}
+
 function validateProviders(providers: WorkflowProviderMap): void {
   for (const [name, provider] of Object.entries(providers)) {
     if (reservedTaskContextKeys.has(name)) {
@@ -367,13 +483,46 @@ function validateProviders(providers: WorkflowProviderMap): void {
   }
 }
 
-function assertSameWorkflow(
-  app: WorkflowDefinition<string, any>,
-  node: WorkflowNodeDefinition<any, any, any>,
-): void {
-  if (node.workflow !== app) {
-    throw new Error(`Node ${node.name} belongs to a different workflow`);
+function attachWorkflowForAuthoring<Providers extends WorkflowProviderMap>(
+  app: WorkflowDefinition<string, Providers>,
+  node: WorkflowNodeDefinition<Providers, any, any>,
+): WorkflowNodeDefinition<Providers, any, any> {
+  if (node.workflow === app) return node;
+  if (node.nodeKind === "parallel") {
+    return {
+      ...node,
+      workflow: app,
+      branches: Object.fromEntries(
+        Object.entries(parallelBranchesForAuthoring(node)).map(([name, branch]) => [
+          name,
+          attachWorkflowForAuthoring(app, branch),
+        ]),
+      ),
+    } as WorkflowNodeDefinition<Providers, any, any>;
   }
+  if (node.nodeKind === "sequence") {
+    return {
+      ...node,
+      workflow: app,
+      children: sequenceChildrenForAuthoring(node).map((child) => attachWorkflowForAuthoring(app, child)),
+    } as WorkflowNodeDefinition<Providers, any, any>;
+  }
+  return {
+    ...node,
+    workflow: app,
+  } as WorkflowNodeDefinition<Providers, any, any>;
+}
+
+function sequenceChildrenForAuthoring(
+  node: WorkflowNodeDefinition<any, any, any>,
+): readonly WorkflowNodeDefinition<any, any, any>[] {
+  return (node as { children?: readonly WorkflowNodeDefinition<any, any, any>[] }).children ?? [];
+}
+
+function parallelBranchesForAuthoring(
+  node: WorkflowNodeDefinition<any, any, any>,
+): Record<string, WorkflowNodeDefinition<any, any, any>> {
+  return (node as { branches?: Record<string, WorkflowNodeDefinition<any, any, any>> }).branches ?? {};
 }
 
 function getKind(value: object): unknown {

package/src/authoring.typecheck.ts

@@ -59,6 +59,33 @@ sequence("typed-step-invalidation-targets")
     return step.invalidate("missing-auth");
   });
 
+sequence("typed-config")
+  .configure({
+    nodeMajor: 22,
+    tools: {
+      codex: true,
+      claude: false,
+    },
+  })
+  .step("read-config", async ({ config }) => {
+    const nodeMajor: number = config.nodeMajor;
+    const codex: boolean = config.tools.codex;
+    void nodeMajor;
+    void codex;
+    // @ts-expect-error missing config keys are rejected
+    config.missing;
+    return { ctx: { ready: true } };
+  })
+  .configure({
+    tools: {
+      claude: true,
+    },
+  })
+  .step("merged-config", async ({ config }) => {
+    const claude: boolean = config.tools.claude;
+    void claude;
+  });
+
 sequence("duplicate-step-id")
   .step("prepare" as const, async () => ({ ctx: { snapshotId: "snap-1" } }))
   // @ts-expect-error duplicate task ids are rejected for literal ids

package/src/console-intercept.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  __resetConsoleInterceptForTests,
+  runWithStepConsole,
+  type ConsoleLevel,
+  type StepConsoleSink,
+} from "./console-intercept.ts";
+
+type Captured = { level: ConsoleLevel; message: string };
+
+function collector(): { sink: StepConsoleSink; entries: Captured[] } {
+  const entries: Captured[] = [];
+  return { sink: (input) => entries.push(input), entries };
+}
+
+afterEach(() => {
+  __resetConsoleInterceptForTests();
+  delete process.env.RIGKIT_NO_CONSOLE_INTERCEPT;
+});
+
+describe("runWithStepConsole", () => {
+  test("captures console.{log,info,debug,warn,error} with the right level", async () => {
+    const { sink, entries } = collector();
+    await runWithStepConsole(sink, async () => {
+      console.log("a log line");
+      console.info("an info line");
+      console.debug("a debug line");
+      console.warn("a warn line");
+      console.error("an error line");
+    });
+
+    expect(entries).toEqual([
+      { level: "log", message: "a log line" },
+      { level: "info", message: "an info line" },
+      { level: "debug", message: "a debug line" },
+      { level: "warn", message: "a warn line" },
+      { level: "error", message: "an error line" },
+    ]);
+  });
+
+  test("formats objects and printf args like the real console", async () => {
+    const { sink, entries } = collector();
+    await runWithStepConsole(sink, async () => {
+      console.log("counts:", { a: 1, b: 2 });
+      console.log("user %s scored %d", "alice", 42);
+    });
+
+    expect(entries[0]!.message).toBe("counts: { a: 1, b: 2 }");
+    expect(entries[1]!.message).toBe("user alice scored 42");
+  });
+
+  test("preserves the scope across async boundaries", async () => {
+    const { sink, entries } = collector();
+    const inner = async () => {
+      await Promise.resolve();
+      console.log("inside async helper");
+    };
+    await runWithStepConsole(sink, async () => {
+      await inner();
+    });
+
+    expect(entries).toEqual([{ level: "log", message: "inside async helper" }]);
+  });
+
+  test("isolates concurrent step contexts", async () => {
+    const a = collector();
+    const b = collector();
+    await Promise.all([
+      runWithStepConsole(a.sink, async () => {
+        await Promise.resolve();
+        console.log("from A");
+      }),
+      runWithStepConsole(b.sink, async () => {
+        await Promise.resolve();
+        console.warn("from B");
+      }),
+    ]);
+
+    expect(a.entries).toEqual([{ level: "log", message: "from A" }]);
+    expect(b.entries).toEqual([{ level: "warn", message: "from B" }]);
+  });
+
+  test("RIGKIT_NO_CONSOLE_INTERCEPT=1 disables capture", async () => {
+    process.env.RIGKIT_NO_CONSOLE_INTERCEPT = "1";
+    const { sink, entries } = collector();
+    const consoleLogSpy: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => consoleLogSpy.push(String(args[0] ?? ""));
+    try {
+      await runWithStepConsole(sink, async () => {
+        console.log("should fall through to original");
+      });
+    } finally {
+      console.log = originalLog;
+    }
+
+    expect(entries).toEqual([]);
+    expect(consoleLogSpy).toEqual(["should fall through to original"]);
+  });
+
+  test("outside the scope, console.* falls through to its original implementation", async () => {
+    const { sink, entries } = collector();
+    // Install the patch by running a scoped call once.
+    await runWithStepConsole(sink, async () => {
+      console.log("inside");
+    });
+
+    // Now call outside — should not show up in entries.
+    const originalLog = console.log;
+    const outsideCalls: unknown[][] = [];
+    console.log = (...args: unknown[]) => outsideCalls.push(args);
+    try {
+      console.log("outside");
+    } finally {
+      console.log = originalLog;
+    }
+
+    expect(entries).toEqual([{ level: "log", message: "inside" }]);
+    expect(outsideCalls).toEqual([["outside"]]);
+  });
+});

package/src/console-intercept.ts

@@ -0,0 +1,75 @@
+// Captures `console.log` / `info` / `debug` / `warn` / `error` invoked inside a
+// step handler and routes the output through that step's logger. This lets
+// users write `console.log("foo")` instead of threading `step.log` through
+// every helper, and surfaces third-party SDK output for free.
+//
+// Scoped via AsyncLocalStorage so:
+//   - Engine/runtime code that itself uses `console.*` is never touched.
+//   - Concurrent step executions each get their own logger.
+//
+// Disabled by `RIGKIT_NO_CONSOLE_INTERCEPT=1`.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { formatWithOptions } from "node:util";
+
+export type ConsoleLevel = "debug" | "info" | "log" | "warn" | "error";
+
+export type StepConsoleSink = (input: { level: ConsoleLevel; message: string }) => void;
+
+type ConsoleMethod = "debug" | "info" | "log" | "warn" | "error";
+
+const METHODS: readonly ConsoleMethod[] = ["debug", "info", "log", "warn", "error"] as const;
+const STORAGE = new AsyncLocalStorage<StepConsoleSink>();
+
+let installed = false;
+const originalMethods: Partial<Record<ConsoleMethod, (...args: unknown[]) => void>> = {};
+
+export function runWithStepConsole<T>(sink: StepConsoleSink, fn: () => Promise<T> | T): Promise<T> | T {
+  if (process.env.RIGKIT_NO_CONSOLE_INTERCEPT === "1") return fn();
+  ensureInstalled();
+  return STORAGE.run(sink, fn);
+}
+
+function ensureInstalled(): void {
+  if (installed) return;
+  installed = true;
+
+  // util.formatWithOptions colors based on the second arg. We disable colors so
+  // the captured output is plain (the CLI presenter colors it on the render
+  // side based on level, which is the right place for terminal styling).
+  const formatOptions = { colors: false, depth: 4, breakLength: 80 } as const;
+
+  for (const method of METHODS) {
+    const original = console[method].bind(console);
+    originalMethods[method] = original;
+    console[method] = (...args: unknown[]) => {
+      const sink = STORAGE.getStore();
+      if (!sink) {
+        original(...args);
+        return;
+      }
+      try {
+        const message = formatWithOptions(formatOptions, ...args);
+        sink({ level: methodToLevel(method), message });
+      } catch {
+        // If formatting fails, fall back to the original so users at least see
+        // something instead of swallowing their log.
+        original(...args);
+      }
+    };
+  }
+}
+
+function methodToLevel(method: ConsoleMethod): ConsoleLevel {
+  return method;
+}
+
+// Test-only: restore the original console methods. Not exported from the
+// package's public surface but used by engine.test.ts.
+export function __resetConsoleInterceptForTests(): void {
+  for (const method of METHODS) {
+    const original = originalMethods[method];
+    if (original) console[method] = original;
+  }
+  installed = false;
+}