@gaunt-sloth/batch 2.0.0-alpha.19

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * @packageDocumentation
+ * BATCH-1 — the shapes shared across matrix construction, the concurrency/retry runner, and the
+ * structured output writer. Deliberately independent of any LLM/runner types (`GthConfig`,
+ * `runSingleShot`, …): this package only knows about *cells* and *outcomes*. The production
+ * adapter that turns a cell into an actual `runSingleShot` call lives in
+ * `packages/app/src/commands/batchCommand.ts`, which is what keeps {@link RunCellFn} injectable —
+ * unit tests here fake it, the CLI wires the real one.
+ */
+/** The default concurrency cap when `-j/--concurrency` is not supplied. */
+export const DEFAULT_CONCURRENCY = 4;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+FH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC"}

package/dist/workflow/runWorkflow.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @module workflow/runWorkflow
+ *
+ * BATCH-3 — the `gth workflow` host. Runs a local JS orchestration script (`.mjs`/`.js`) that drives
+ * one or more LLM calls through a small, generic {@link WorkflowContext}. This is the
+ * script-orchestrated sibling of `gth batch` (matrix over a single prompt): a workflow is arbitrary
+ * local code that decides *how* to fan calls out.
+ *
+ * The host provides two agent shapes, both reusing the proven production wiring:
+ * - a **structured** call via {@link askStructured} (`@gaunt-sloth/core`) — a bare, non-agentic
+ *   `withStructuredOutput` model call that returns a schema-validated object;
+ * - a **text** call that mirrors `buildProductionRunCell` (packages/app/src/commands/batchCommand.ts)
+ *   exactly — its own `createResolvers()`, a lean agent factory, `runSingleShot`, and
+ *   `cleanupTools()` on every path.
+ *
+ * Packaging note: the text path pulls in `@gaunt-sloth/agent` (`createResolvers`,
+ * `resolveAgentFactory`), so this package now declares `@gaunt-sloth/agent` as a dependency. That is
+ * a deliberate widening of the batch package (whose matrix runtime was kept LLM/runner-agnostic) to
+ * host the workflow runtime the BATCH-3 brief scopes here; `batch → agent → core` stays a clean DAG
+ * (agent does not depend on batch).
+ */
+import * as z from 'zod';
+import type { CommandLineConfigOverrides, GthConfig } from '@gaunt-sloth/core/config.js';
+import type { GthCommand } from '@gaunt-sloth/core/core/types.js';
+/** Options for a single {@link WorkflowContext.agent} call. */
+export interface WorkflowAgentOptions {
+    /** Zod schema → structured output (via {@link askStructured}). Omit for a plain-text agent run.
+     * Build it with {@link WorkflowContext.z} so it is the exact zod instance the model introspects. */
+    schema?: z.ZodType<unknown>;
+    /** System-message text. Default `''`. */
+    system?: string;
+    /** Model override (e.g. `'google-genai:gemini-3.1-flash-lite'`); omit to use the host's base config. */
+    model?: string;
+    /** Agent mode for the text path's `runSingleShot` (default `'ask'`). Ignored for the schema path. */
+    command?: GthCommand;
+}
+/** The context object a workflow script's default export receives. */
+export interface WorkflowContext {
+    /**
+     * Run one LLM call. With `opts.schema` → returns the schema-validated object (throws `Error(msg)`
+     * on a structured failure). Without a schema → returns the answer text (throws on failure).
+     */
+    agent(prompt: string, opts?: WorkflowAgentOptions): Promise<unknown>;
+    /**
+     * Run thunks concurrently (cap = {@link DEFAULT_CONCURRENCY}), results in input order; a throwing
+     * thunk yields `null` in its slot and never rejects the whole `parallel`.
+     */
+    parallel<T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
+    /** The value passed via `--args <json>` (parsed), or `undefined`. */
+    args: unknown;
+    /** Emit a progress line (via `consoleUtils`, not raw `console.log`). */
+    log(message: string): void;
+    /**
+     * The host's own zod module. Build schemas with `ctx.z` (not a bare `import 'zod'` from the
+     * script's own location) so `agent({ schema })` uses the exact zod instance
+     * `withStructuredOutput` introspects — a foreign copy triggers the dual-zod `instanceof` mismatch.
+     */
+    z: typeof z;
+}
+/** Inputs to {@link runWorkflow}. */
+export interface RunWorkflowOptions {
+    /** The resolved base config (the configured model), respecting `-i <profile>` etc. */
+    baseConfig: GthConfig;
+    /** CLI overrides, threaded into per-`model` `initConfig` calls (see the model resolver). */
+    commandLineConfigOverrides: CommandLineConfigOverrides;
+    /** The parsed `--args` value handed to the script as `ctx.args`. */
+    args: unknown;
+}
+/**
+ * Run a workflow script.
+ *
+ * Resolves `scriptPath` to an absolute path, dynamic-imports it (`.mjs`/`.js`), requires an async
+ * function as its default export, builds the {@link WorkflowContext}, and returns whatever the
+ * script resolves to. Script errors propagate (the CLI surfaces them).
+ *
+ * @param scriptPath Path to the workflow script (`.mjs`/`.js`).
+ * @param options The base config, CLI overrides, and parsed `--args` value.
+ */
+export declare function runWorkflow(scriptPath: string, options: RunWorkflowOptions): Promise<unknown>;

package/dist/workflow/runWorkflow.js

@@ -0,0 +1,142 @@
+/**
+ * @module workflow/runWorkflow
+ *
+ * BATCH-3 — the `gth workflow` host. Runs a local JS orchestration script (`.mjs`/`.js`) that drives
+ * one or more LLM calls through a small, generic {@link WorkflowContext}. This is the
+ * script-orchestrated sibling of `gth batch` (matrix over a single prompt): a workflow is arbitrary
+ * local code that decides *how* to fan calls out.
+ *
+ * The host provides two agent shapes, both reusing the proven production wiring:
+ * - a **structured** call via {@link askStructured} (`@gaunt-sloth/core`) — a bare, non-agentic
+ *   `withStructuredOutput` model call that returns a schema-validated object;
+ * - a **text** call that mirrors `buildProductionRunCell` (packages/app/src/commands/batchCommand.ts)
+ *   exactly — its own `createResolvers()`, a lean agent factory, `runSingleShot`, and
+ *   `cleanupTools()` on every path.
+ *
+ * Packaging note: the text path pulls in `@gaunt-sloth/agent` (`createResolvers`,
+ * `resolveAgentFactory`), so this package now declares `@gaunt-sloth/agent` as a dependency. That is
+ * a deliberate widening of the batch package (whose matrix runtime was kept LLM/runner-agnostic) to
+ * host the workflow runtime the BATCH-3 brief scopes here; `batch → agent → core` stays a clean DAG
+ * (agent does not depend on batch).
+ */
+import * as z from 'zod';
+import { resolve } from 'node:path';
+import { initConfig } from '@gaunt-sloth/core/config.js';
+import { askStructured } from '@gaunt-sloth/core/runtime/askStructured.js';
+import { importExternalFile } from '@gaunt-sloth/core/utils/fileUtils.js';
+import { displayInfo, displayWarning } from '@gaunt-sloth/core/utils/consoleUtils.js';
+import { DEFAULT_CONCURRENCY } from '#src/types.js';
+/**
+ * Build a per-`model` {@link GthConfig} cache — the same idiom as `createCellConfigResolver` in
+ * `batchCommand.ts`: `undefined` model → the base config; a named model → one cached
+ * `initConfig({ ...overrides, model })` call (cached by `Promise` so concurrent requests for the
+ * same not-yet-resolved model share one in-flight build rather than racing).
+ */
+function createModelConfigResolver(baseConfig, commandLineConfigOverrides) {
+    const configForModel = new Map();
+    return (model) => {
+        if (!model) {
+            return Promise.resolve(baseConfig);
+        }
+        let cached = configForModel.get(model);
+        if (!cached) {
+            cached = initConfig({ ...commandLineConfigOverrides, model });
+            configForModel.set(model, cached);
+        }
+        return cached;
+    };
+}
+/**
+ * Run a workflow script.
+ *
+ * Resolves `scriptPath` to an absolute path, dynamic-imports it (`.mjs`/`.js`), requires an async
+ * function as its default export, builds the {@link WorkflowContext}, and returns whatever the
+ * script resolves to. Script errors propagate (the CLI surfaces them).
+ *
+ * @param scriptPath Path to the workflow script (`.mjs`/`.js`).
+ * @param options The base config, CLI overrides, and parsed `--args` value.
+ */
+export async function runWorkflow(scriptPath, options) {
+    const { baseConfig, commandLineConfigOverrides, args } = options;
+    const absolutePath = resolve(scriptPath);
+    const imported = await importExternalFile(absolutePath);
+    const scriptDefault = imported?.default;
+    if (typeof scriptDefault !== 'function') {
+        throw new Error(`Workflow script "${scriptPath}" must export an async function as its default export.`);
+    }
+    const resolveModelConfig = createModelConfigResolver(baseConfig, commandLineConfigOverrides);
+    // The per-call config: the model's config, cloned the way batch does — no interactive ESC
+    // interrupt and no per-call `.md` report file (a workflow's return value is its output).
+    const cellConfigForModel = async (model) => {
+        const modelConfig = await resolveModelConfig(model);
+        return { ...modelConfig, canInterruptInferenceWithEsc: false, writeOutputToFile: false };
+    };
+    const agent = async (prompt, opts = {}) => {
+        const cellConfig = await cellConfigForModel(opts.model);
+        if (opts.schema) {
+            // Structured path — a bare model call (no resolvers/tools); askStructured never throws.
+            const result = await askStructured(opts.schema, {
+                config: cellConfig,
+                system: opts.system ?? '',
+                user: prompt,
+            });
+            if (!result.ok) {
+                throw new Error(result.error);
+            }
+            return result.value;
+        }
+        // Text path — mirrors buildProductionRunCell (batchCommand.ts): own resolvers, lean agent
+        // factory, cleanup on every path.
+        const { runSingleShot } = await import('@gaunt-sloth/core/runtime/singleShot.js');
+        const { createResolvers } = await import('@gaunt-sloth/agent/resolvers.js');
+        const { resolveAgentFactory } = await import('@gaunt-sloth/agent/core/resolveAgentFactory.js');
+        const resolvers = createResolvers();
+        try {
+            const { ok, answer } = await runSingleShot(`WORKFLOW-${Date.now()}`, opts.system ?? '', prompt, cellConfig, resolvers, opts.command ?? 'ask', resolveAgentFactory(cellConfig, 'lean'));
+            if (!ok) {
+                throw new Error('agent run failed');
+            }
+            return answer;
+        }
+        finally {
+            // Guard cleanup so a teardown failure never masks the real return/throw above.
+            try {
+                await resolvers.cleanupTools?.();
+            }
+            catch (cleanupError) {
+                displayWarning(`Failed to clean up workflow agent tools: ` +
+                    `${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+            }
+        }
+    };
+    const parallel = async (thunks) => {
+        const results = new Array(thunks.length).fill(null);
+        let nextIndex = 0;
+        const worker = async () => {
+            for (;;) {
+                const i = nextIndex++;
+                if (i >= thunks.length)
+                    return;
+                try {
+                    results[i] = await thunks[i]();
+                }
+                catch {
+                    // A throwing thunk yields null in its slot and never fails the other thunks.
+                    results[i] = null;
+                }
+            }
+        };
+        const workerCount = Math.min(DEFAULT_CONCURRENCY, thunks.length);
+        await Promise.all(Array.from({ length: workerCount }, () => worker()));
+        return results;
+    };
+    const ctx = {
+        agent,
+        parallel,
+        args,
+        log: (message) => displayInfo(message),
+        z,
+    };
+    return scriptDefault(ctx);
+}
+//# sourceMappingURL=runWorkflow.js.map

package/dist/workflow/runWorkflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runWorkflow.js","sourceRoot":"","sources":["../../src/workflow/runWorkflow.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@gaunt-sloth/batch",
+  "version": "2.0.0-alpha.19",
+  "description": "Batch matrix runtime for Gaunt Sloth (BATCH-1): run a prompt-executable over a matrix of models and/or content-bound inputs",
+  "license": "MIT",
+  "author": "Andrew Kondratev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pukeko-robotics/gaunt-sloth.git",
+    "directory": "packages/batch"
+  },
+  "bugs": {
+    "url": "https://github.com/pukeko-robotics/gaunt-sloth/issues"
+  },
+  "homepage": "https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/batch#readme",
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "batch",
+    "cli"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./*.js": "./dist/*.js"
+  },
+  "imports": {
+    "#src/*.js": "./dist/*.js"
+  },
+  "dependencies": {
+    "@langchain/core": "^1.2.3",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3",
+    "@gaunt-sloth/agent": "2.0.0-alpha.19",
+    "@gaunt-sloth/core": "2.0.0-alpha.19"
+  },
+  "files": [
+    "./dist/*"
+  ],
+  "publishConfig": {
+    "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}