@recombine-ai/engine 0.7.1 → 0.8.0

package/.github/workflows/linting.yml

@@ -0,0 +1,32 @@
+name: lint & typecheck
+
+on:
+    push:
+        branches: [main]
+    pull_request:
+
+jobs:
+    checks:
+        runs-on: ubuntu-latest
+        timeout-minutes: 10
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 24
+                  cache: 'yarn'
+
+            - name: Install dependencies
+              run: yarn install --frozen-lockfile
+
+            - name: Run lint
+              run: yarn -s lint --quiet
+
+            - name: Run formatter check
+              run: yarn -s format:check
+
+            - name: Run typecheck
+              run: yarn -s typecheck

package/.husky/post-merge

@@ -0,0 +1,5 @@
+# If package.json changed, install dependencies
+if git diff --name-only HEAD@{1} HEAD | grep -E '(^package.json$|^yarn.lock$)'; then
+  echo "package.json changed — running yarn install"
+  yarn install
+fi

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+# Run lint-staged (this will run format & eslint --fix for staged files)
+yarn -s lint-staged

package/.husky/pre-push

@@ -0,0 +1,5 @@
+# Build and typecheck
+yarn -s typecheck || {
+  echo "Typecheck failed — aborting push."
+  exit 1
+}

package/build/lib/ai.d.ts

@@ -7,20 +7,25 @@ import { Tracer } from './bosun';
 /**
  * Represents a basic model name for LLMs.
  */
-export type BasicModel = 'o3-mini-2025-01-31' | 'o1-preview-2024-09-12' | 'gpt-4o-2024-11-20' | 'o1-2024-12-17' | (string & {});
-export interface ProgrammaticStep<CTX> {
-    /** Step name for debugging */
+export type BasicModel = 'o3-mini-2025-01-31' | 'o1-preview-2024-09-12' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-11-20' | 'gpt-4.1-2025-04-14' | 'o1-2024-12-17' | (string & {});
+export interface BasicStep<CTX> {
+    /** Step name  */
     name: string;
     /** Determines if the step should be run or not */
     runIf?: (messages: Conversation, ctx: CTX) => boolean | Promise<boolean>;
-    /** Content of the step */
-    execute: (messages: Conversation, ctx: CTX) => Promise<unknown>;
+    /**
+     * When provided, throws an error if the step is invoked more times than `maxAttempts`.
+     * Number of attempts taken is reset when the flow passed the step that was rewinding.
+     */
+    maxAttempts?: number;
     /** Error handler called if an error occurred during in `execute` function */
     onError?: (error: string, ctx: CTX) => Promise<unknown>;
 }
-export interface LLMStep<CTX> {
-    /** Step name for debugging */
-    name: string;
+export interface ProgrammaticStep<CTX> extends BasicStep<CTX> {
+    /** Content of the step */
+    execute: (messages: Conversation, ctx: CTX, workflow: WorkflowControls) => Promise<unknown>;
+}
+export interface LLMStep<CTX> extends BasicStep<CTX> {
     /** Determines if the step should be run or not */
     runIf?: (messages: Conversation, ctx: CTX) => boolean | Promise<boolean>;
     /** LLM to use. Defaults to gpt-4o */
@@ -34,14 +39,17 @@ export interface LLMStep<CTX> {
      * Do not put messages that were added via {@link Conversation.addMessage} into the prompt.
      */
     ignoreAddedMessages?: boolean;
+}
+export interface WorkflowControls {
     /**
-     * When provided, throws an error if the step is invoked more times than `maxAttempts`.
-     * Number of attempts taken is reset when `shouldExecute` returns `false`. Useful to limit
-     * rewinds by reviewers. NOTE that it doesn't work on steps without `shouldExecute` method.
+     * Terminates the workflow, preventing further steps from being executed.
      */
-    maxAttempts?: number;
-    /** Error handler called if an error occurred during LLM API call or in `execute` function */
-    onError?: (error: string, ctx: CTX) => Promise<unknown>;
+    terminate: () => void;
+    /**
+     * Rewinds the workflow execution to a specific step.
+     * @param step - The name of the step to rewind to
+     */
+    rewindTo: (step: string) => void;
 }
 export interface JsonLLMStep<CTX, Schema extends ZodTypeAny> extends LLMStep<CTX> {
     /**
@@ -65,13 +73,7 @@ export interface JsonLLMStep<CTX, Schema extends ZodTypeAny> extends LLMStep<CTX
      * }
      * ```
      */
-    execute: (reply: Zod.infer<Schema>, conversation: Conversation, ctx: CTX) => Promise<unknown>;
-    /**
-     * Check a condition, whether the `execute` function should run or not
-     * @deprecated use `runIf` to check if the step should be run, use if in `execute` to check
-     * if it should be executed
-     **/
-    shouldExecute?: (reply: Schema, ctx: CTX) => boolean | Promise<boolean>;
+    execute: (reply: Zod.infer<Schema>, conversation: Conversation, ctx: CTX, workflowControls: WorkflowControls) => Promise<unknown>;
 }
 export interface StringLLMStep<CTX> extends LLMStep<CTX> {
     /**
@@ -89,39 +91,22 @@ export interface StringLLMStep<CTX> extends LLMStep<CTX> {
      * }
      * ```
      */
-    execute: (reply: string, conversation: Conversation, ctx: CTX) => Promise<unknown>;
-    /**
-     * Check a condition, whether the `execute` function should run or not
-     * @deprecated use `runIf` to check if the step should be run, use if in `execute` to check
-     * if it should be executed
-     **/
-    shouldExecute?: (reply: string, ctx: CTX) => boolean | Promise<boolean>;
+    execute: (reply: string, conversation: Conversation, ctx: CTX, workflowControls?: WorkflowControls) => Promise<unknown>;
 }
+type BeforeEachStep<CTX> = (conversation: Conversation, ctx: CTX, workflowControls?: WorkflowControls) => Promise<void>;
 /**
  * An AI workflow composed of steps.
  */
 export interface Workflow<CTX> {
-    /**
-     * Terminates the workflow, preventing further steps from being executed.
-     */
-    terminate: () => void;
     /**
      * Runs the workflow with a given conversation context.
      * Executes steps sequentially until completion or termination.
-     * @param messages - The conversation context for the workflow
+     * @param conversation - The conversation context for the workflow
+     * @param context – Context that will be passed to all steps and to all prompts in those steps
+     * @param beforeEach – A callback, that runs before each step
      * @returns The proposed reply if workflow completes, or null if terminated
      */
-    run: (messages: Conversation, ctx?: CTX) => Promise<string | null>;
-    /**
-     * Rewinds the workflow execution to a specific step.
-     * @param step - The step to rewind to
-     */
-    rewindTo: (step: LLMStep<CTX> | ProgrammaticStep<CTX>) => void;
-    /**
-     * Registers a callback to be executed before each step.
-     * @param callback - Async function to execute before each step
-     */
-    beforeEach: (callback: () => Promise<unknown>) => void;
+    run: (conversation: Conversation, context?: CTX, beforeEach?: BeforeEachStep<CTX>) => Promise<string | null>;
     /**
      * Add a step to workflow
      */
@@ -129,8 +114,11 @@ export interface Workflow<CTX> {
     addStep(step: StringLLMStep<CTX>): void;
     addStep(step: ProgrammaticStep<CTX>): void;
 }
+type WorkflowStep<CTX> = StringLLMStep<CTX> | JsonLLMStep<CTX, any> | ProgrammaticStep<CTX>;
 export interface WorkflowConfig<CTX> {
     onError: (error: string, ctx: CTX) => Promise<unknown>;
+    steps?: WorkflowStep<CTX>[];
+    beforeEachCallback?: () => Promise<unknown>;
 }
 interface StepBuilder<CTX> {
     <Schema extends ZodTypeAny>(step: JsonLLMStep<CTX, Schema>): JsonLLMStep<CTX, Schema>;
@@ -194,7 +182,7 @@ export interface AIEngine {
      * @param config - common parameters for a workflow
      * @returns A Promise that resolves to the created Workflow.
      */
-    createWorkflow: <CTX>(config: WorkflowConfig<CTX>) => Workflow<CTX>;
+    createWorkflow: <CTX extends object>(config: WorkflowConfig<CTX>) => Workflow<CTX>;
     /**
      * Creates a new conversation instance.
      * @param messages - Optional initial messages for the conversation.
@@ -250,7 +238,7 @@ export interface Conversation {
      */
     setAgentName(name: string): void;
     /**
-     * Sets the default formatter for stringifying messages when toString is called.
+     * Sets the default formatter to stringify messages when toString is called.
      * @param formatter - A function that takes a message and returns a formatted string.
      */
     setDefaultFormatter: (formatter: (message: Message) => string) => void;
@@ -341,7 +329,6 @@ export interface EngineConfig {
  * ```ts
  * const engine = createAIEngine({
  *   logger: customLogger,
- *   basePath: '/path/to/prompts'
  * });
  *
  * const workflow = await engine.createWorkflow(
@@ -356,7 +343,7 @@ export interface EngineConfig {
  * ```
  */
 export declare function createAIEngine(cfg?: EngineConfig): AIEngine;
-declare function renderPrompt(prompt: string, context?: Record<string, unknown>): string;
+declare function renderPrompt(prompt: string, context?: object): string;
 export declare function createConversation(initialMessages?: Message[]): Conversation;
 export declare function getStepBuilder<CTX = unknown>(): StepBuilder<CTX>;
 export {};

package/build/lib/ai.d.ts.map

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

package/build/lib/ai.js

@@ -7,7 +7,7 @@ exports.createAIEngine = createAIEngine;
 exports.createConversation = createConversation;
 exports.getStepBuilder = getStepBuilder;
 // cspell:words lstripBlocks
-const openai_1 = __importDefault(require("openai"));
+const openai_1 = require("openai");
 const nunjucks_1 = __importDefault(require("nunjucks"));
 const zod_1 = require("zod");
 const action_1 = require("./bosun/action");
@@ -26,7 +26,6 @@ const zod_to_json_schema_1 = require("zod-to-json-schema");
  * ```ts
  * const engine = createAIEngine({
  *   logger: customLogger,
- *   basePath: '/path/to/prompts'
  * });
  *
  * const workflow = await engine.createWorkflow(
@@ -53,22 +52,15 @@ function createAIEngine(cfg = {}) {
             throw new Error('OpenAI API key is not set');
         },
     };
-    function createWorkflow({ onError }) {
-        let shouldRun = true;
-        let currentStep = 0;
-        let beforeEachCallback = async () => Promise.resolve(null);
-        const attempts = new Map();
-        const steps = [];
+    function createWorkflow({ onError, steps = [], }) {
+        steps.forEach(addStepToTracer);
         return {
-            terminate: () => {
-                logger.debug('AI Engine: Terminating conversation...');
-                shouldRun = false;
-            },
-            run: async (messages, ctx) => {
-                for (; currentStep < steps.length; currentStep++) {
-                    await beforeEachCallback();
-                    const step = steps[currentStep];
-                    if (!shouldRun) {
+            run: async (messages, ctx, beforeEach) => {
+                const state = new WorkflowState(logger, steps);
+                do {
+                    await beforeEach?.(messages, ctx, state);
+                    const step = state.getStep();
+                    if (state.isTerminated()) {
                         logger.debug('AI Engine: run terminated');
                         break;
                     }
@@ -77,43 +69,32 @@ function createAIEngine(cfg = {}) {
                         await action('started');
                         logger.debug(`AI Engine: Step: ${step.name}`);
                         if ('prompt' in step) {
-                            await runStep(step, messages, ctx, onError);
+                            await runStep(step, messages, ctx, state);
                         }
                         else {
-                            await runProgrammaticStep(step, messages, ctx);
+                            await runProgrammaticStep(step, messages, ctx, state);
                         }
                         await action('completed');
                     }
-                }
-                currentStep = 0;
-                return shouldRun ? messages.getProposedReply() : null;
-            },
-            rewindTo: (step) => {
-                const index = steps.indexOf(step);
-                if (index === -1) {
-                    throw new Error(`Step ${step.name} not found`);
-                }
-                if (index > currentStep) {
-                    throw new Error(`Cannot rewind to a step ahead of the current step`);
-                }
-                currentStep = index - 1; // -1 because it will be incremented in the loop definition
-            },
-            beforeEach(callback) {
-                beforeEachCallback = callback;
+                } while (state.next());
+                return state.isTerminated() ? null : messages.getProposedReply();
             },
             addStep(step) {
-                if ('prompt' in step) {
-                    tracer.addStep({
-                        name: step.name,
-                        prompt: (0, tracer_1.stdPrompt)(step.prompt),
-                        type: 'text',
-                        schema: 'schema' in step ? step.schema : undefined,
-                    });
-                }
+                addStepToTracer(step);
                 steps.push(step);
             },
         };
-        async function runStep(step, conversation, ctx, onError) {
+        function addStepToTracer(step) {
+            if ('prompt' in step) {
+                tracer.addStep({
+                    name: step.name,
+                    prompt: (0, tracer_1.stdPrompt)(step.prompt),
+                    type: 'text',
+                    schema: 'schema' in step ? step.schema : undefined,
+                });
+            }
+        }
+        async function runStep(step, conversation, ctx, state) {
             if (!apiKey) {
                 apiKey = await tokenStorage.getToken();
             }
@@ -141,6 +122,7 @@ function createAIEngine(cfg = {}) {
                 const stringifiedMessages = conversation.toString({
                     ignoreAddedMessages: step.ignoreAddedMessages,
                 });
+                logger.debug('AI Engine stringified: ' + stringifiedMessages);
                 stepTrace.stringifiedConversation = stringifiedMessages;
                 stepTracer?.addStepTrace(stepTrace);
                 if ('schema' in step) {
@@ -153,22 +135,8 @@ function createAIEngine(cfg = {}) {
                 if (!response) {
                     throw new Error('No response from OpenAI');
                 }
-                logger.debug(`AI Engine: response:`, response);
-                if (typeof step.shouldExecute === 'function') {
-                    if (await step.shouldExecute(response, ctx)) {
-                        logger.debug(`AI Engine: executing`);
-                        checkAttempts(step);
-                        await step.execute(response, conversation, ctx);
-                    }
-                    else {
-                        resetAttempts(step);
-                        logger.debug(`AI Engine: skipping`);
-                    }
-                }
-                else {
-                    logger.debug(`AI Engine: replying`);
-                    await step.execute(response, conversation, ctx);
-                }
+                logger.debug(`AI Engine: executing ${step.name}, LLM response`, response);
+                await step.execute(response, conversation, ctx, state);
             }
             catch (error) {
                 await (step.onError
@@ -176,37 +144,23 @@ function createAIEngine(cfg = {}) {
                     : onError(error.message, ctx));
                 // FIXME: this doesn't terminate the workflow
                 stepTracer?.addStepTrace(stepTrace);
-                shouldRun = false;
+                state.terminate();
             }
         }
-        async function runProgrammaticStep(step, messages, ctx) {
+        async function runProgrammaticStep(step, messages, ctx, state) {
             try {
                 if (!step.runIf || (await step.runIf(messages, ctx))) {
-                    await step.execute(messages, ctx);
+                    await step.execute(messages, ctx, state);
                 }
             }
             catch (error) {
-                console.error(`AI Engine: error in dumb step ${step.name}: ${error.message}`);
+                logger.error(`AI Engine: error in dumb step ${step.name}: ${error.message}`);
                 await (step.onError
                     ? step.onError(error.message, ctx)
                     : onError(error.message, ctx));
-                shouldRun = false;
+                state.terminate();
             }
         }
-        function checkAttempts(step) {
-            if (step.maxAttempts) {
-                if (!attempts.has(step)) {
-                    attempts.set(step, 0);
-                }
-                attempts.set(step, attempts.get(step) + 1);
-                if (attempts.get(step) > step.maxAttempts) {
-                    throw new Error(`Max attempts reached for step ${step.name}`);
-                }
-            }
-        }
-        function resetAttempts(step) {
-            attempts.set(step, 0);
-        }
     }
     async function runLLM(apiKey, systemPrompt, messages, schema, model = 'gpt-4o-2024-08-06') {
         logger.debug('AI Engine: model:', model);
@@ -220,7 +174,7 @@ function createAIEngine(cfg = {}) {
             }
             return JSON.stringify({ message: 'canned response', reasons: [] });
         }
-        const client = new openai_1.default({ apiKey });
+        const client = new openai_1.OpenAI({ apiKey });
         const response = await client.chat.completions.create({
             messages: [
                 { role: 'system', content: systemPrompt },
@@ -242,6 +196,54 @@ function createAIEngine(cfg = {}) {
         },
     };
 }
+class WorkflowState {
+    logger;
+    steps;
+    shouldRun = true;
+    currentStep = 0;
+    /** map, step index to number of attempts */
+    attempts = new Map();
+    rewinder = 0;
+    lastRewindTo = 0;
+    constructor(logger, steps) {
+        this.logger = logger;
+        this.steps = steps;
+    }
+    terminate() {
+        this.logger.debug('AI Engine: Terminating conversation...');
+        this.shouldRun = false;
+    }
+    isTerminated() {
+        return !this.shouldRun;
+    }
+    getStep() {
+        return this.steps[this.currentStep] || null;
+    }
+    next() {
+        this.currentStep++;
+        if (this.rewinder < this.currentStep) {
+            this.attempts.delete(this.lastRewindTo);
+        }
+        return this.currentStep < this.steps.length;
+    }
+    rewindTo(stepName) {
+        this.rewinder = this.currentStep;
+        const index = this.steps.findIndex((s) => s.name === stepName);
+        if (index < 0) {
+            const names = this.steps.map((s) => s.name).join(', ');
+            throw new Error(`Tried to rewind to ${stepName}, steps: [${names}]`);
+        }
+        this.currentStep = index - 1; // -1 because .next() will be called right after
+        this.lastRewindTo = this.currentStep;
+        const step = this.steps[index];
+        const max = step.maxAttempts || 10;
+        const attempt = this.attempts.get(this.currentStep) ?? 1;
+        if (attempt >= max) {
+            throw new Error(`Max attempts reached for step ${step.name}`);
+        }
+        this.attempts.set(this.currentStep, attempt + 1);
+    }
+}
 function getOpenAiOptions(model, schema) {
     const options = {
         model,

package/build/lib/bosun/action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/action.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAA;IACzC,OAAO,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1D,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,aAEvC,MAAM,QACT,MAAM,UACJ,MAAM,OAAO,CAAC,OAAO,CAAC,mBAiBrC;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAM1D,MAAM,CAAC,OAAO,CAAC,mBAQhD"}
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/action.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAA;IACzC,OAAO,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1D,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,IAEhD,SAAS,MAAM,EACf,MAAM,MAAM,EACZ,QAAQ,MAAM,OAAO,CAAC,OAAO,CAAC,mBAiBrC;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAM1D,MAAM,CAAC,OAAO,CAAC,mBAQhD"}

package/build/lib/bosun/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/context.ts"],"names":[],"mappings":"AAAA,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAC9B,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GAC1B;KACK,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5C,CAAC,MAAM,CAAC,CAAC,GACV,KAAK,CAAA;AAEX,KAAK,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,GACrE,KAAK,SAAS,MAAM,CAAC,GACjB,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,GACpB,CAAC,CAAC,KAAK,CAAC,GACR,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,GAC7B,KAAK,GACT,KAAK,CAAA;AAEX,cAAM,OAAO,CAAC,CAAC,SAAS,GAAG;;gBAGX,OAAO,EAAE,CAAC;IAItB,GAAG,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,SAAS,GAAG,EAAE,GAAG,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IACxF,GAAG,CAAC,UAAU,EAAE,CAAC,GAAG,IAAI;IAgBxB,GAAG;IAIH,gCAAgC;IAChC,IAAI,CAAC,UAAU,EAAE,CAAC;IAIlB,SAAS,aAAc,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,mBAG1C;CACJ;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,GAAG,EAAE,OAAO,EAAE,CAAC,cAEtD;AAED,KAAK,MAAM,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA;AAEzC,KAAK,aAAa,CAAC,CAAC,SAAS,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;AAEtD,YAAY,EAAE,aAAa,IAAI,OAAO,EAAE,CAAA"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/context.ts"],"names":[],"mappings":"AAAA,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAC9B,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GAC1B;KACK,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5C,CAAC,MAAM,CAAC,CAAC,GACV,KAAK,CAAA;AAEX,KAAK,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,GACrE,KAAK,SAAS,MAAM,CAAC,GACjB,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,GACpB,CAAC,CAAC,KAAK,CAAC,GACR,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,GAC7B,KAAK,GACT,KAAK,CAAA;AAEX,cAAM,OAAO,CAAC,CAAC,SAAS,GAAG;;gBAGX,OAAO,EAAE,CAAC;IAItB,GAAG,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,SAAS,GAAG,EAAE,GAAG,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IACxF,GAAG,CAAC,UAAU,EAAE,CAAC,GAAG,IAAI;IAgBxB,GAAG;IAIH,gCAAgC;IAChC,IAAI,CAAC,UAAU,EAAE,CAAC;IAIlB,SAAS,GAAI,UAAU,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,mBAG1C;CACJ;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,GAAG,EAAE,OAAO,EAAE,CAAC,cAEtD;AAED,KAAK,MAAM,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA;AAEzC,KAAK,aAAa,CAAC,CAAC,SAAS,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;AAEtD,YAAY,EAAE,aAAa,IAAI,OAAO,EAAE,CAAA"}

package/build/lib/bosun/registry.d.ts

@@ -0,0 +1,25 @@
+import { ZodSchema } from 'zod';
+import { PromptFile } from '../prompt-fs';
+import { Logger } from '../interfaces';
+export interface PromptString {
+    type: 'string';
+    content: () => Promise<string>;
+}
+export interface StepDef {
+    name: string;
+    workflow: string;
+    type: 'streaming-response' | 'streaming-detect' | 'text';
+    prompt?: PromptFile | PromptString;
+    schema?: ZodSchema;
+}
+export interface WorkflowDef {
+    name: string;
+    type: 'stream' | 'text';
+}
+export interface Registry {
+    addStep(def: StepDef): void;
+    addWorkflow(def: WorkflowDef): void;
+}
+export declare function createConsoleRegistry(logger: Logger): Registry;
+export declare function stdPrompt(prompt: PromptFile | string): PromptString | PromptFile;
+//# sourceMappingURL=registry.d.ts.map

package/build/lib/bosun/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAEtC,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,QAAQ,CAAA;IACd,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,OAAO;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,oBAAoB,GAAG,kBAAkB,GAAG,MAAM,CAAA;IACxD,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CAAA;IAClC,MAAM,CAAC,EAAE,SAAS,CAAA;CACrB;AACD,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,QAAQ;IACrB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;CACtC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAoB9D;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,6BAQpD"}

package/build/lib/bosun/registry.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConsoleRegistry = createConsoleRegistry;
+exports.stdPrompt = stdPrompt;
+function createConsoleRegistry(logger) {
+    return {
+        addStep(def) {
+            let msg = `Registry, step added: ${def.name} (${def.type}) to ${def.workflow}`;
+            if (def.prompt) {
+                if (def.prompt.type === 'string') {
+                    msg += ' with inline prompt';
+                }
+                else if (def.prompt.type === 'file') {
+                    msg += ` with prompt ${def.prompt.path}`;
+                }
+            }
+            if (def.schema) {
+                msg += ' with schema';
+            }
+            logger.debug(msg + '.');
+        },
+        addWorkflow(def) {
+            logger.debug('Registry, workflow added:', def.name, `(${def.type})`);
+        },
+    };
+}
+function stdPrompt(prompt) {
+    if (typeof prompt === 'string') {
+        return {
+            type: 'string',
+            content: async () => prompt,
+        };
+    }
+    return prompt;
+}

package/build/lib/bosun/stepTracer.d.ts

@@ -1,9 +1,10 @@
 import { ZodSchema } from 'zod';
+import { PromptFile } from '../prompt-fs';
 export type StepTrace = {
     name: string;
     renderedPrompt?: string;
-    receivedContext?: Record<string, unknown>;
-    receivedPrompt?: string | File;
+    receivedContext?: unknown;
+    receivedPrompt?: string | PromptFile;
     stringifiedConversation?: string;
     schema?: ZodSchema;
     model?: string;

package/build/lib/bosun/stepTracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stepTracer.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/stepTracer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AAG/B,MAAM,MAAM,SAAS,GAAG;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,WAAW,UAAU;IACvB,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;CAC3C"}
+{"version":3,"file":"stepTracer.d.ts","sourceRoot":"","sources":["../../../src/lib/bosun/stepTracer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,MAAM,MAAM,SAAS,GAAG;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IACpC,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,WAAW,UAAU;IACvB,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;CAC3C"}

package/build/lib/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/lib/interfaces.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACnB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC7B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAC1E,MAAM,WAAW,SAAS;IACtB;;;;;OAKG;IACH,cAAc,EAAE,CACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,KAC1C,cAAc,CAAA;IAEnB;;OAEG;IACH,sBAAsB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9D"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/lib/interfaces.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACnB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC7B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1E,MAAM,WAAW,SAAS;IACtB;;;;;OAKG;IACH,cAAc,EAAE,CACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,KAC1C,cAAc,CAAA;IAEnB;;OAEG;IACH,sBAAsB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9D"}

package/build/lib/platform.d.ts

@@ -0,0 +1,16 @@
+import { AIEngine } from './ai';
+import { Logger } from './interfaces';
+import { PromptFS } from './prompt-fs';
+export interface Platform<TConf = {}> {
+    /** Streaming AI engine, used to create streaming workflows to be used in voice agents */
+    streamAi: any;
+    /** String-base AI engine, used in text agents or for analysis of the conversation */
+    ai: AIEngine;
+    /** File system, used to load prompt files */
+    fs: PromptFS;
+    /** Handles to mange calls, e.g. re-run stream response, hangup, etc. */
+    rcVoice: any;
+    /** Platform and agent-specific configuration variables, e.g. trunk setup, voice settings etc. */
+    logger: Logger;
+}
+//# sourceMappingURL=platform.d.ts.map

package/build/lib/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/lib/platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAA;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,MAAM,WAAW,QAAQ,CAAC,KAAK,GAAG,EAAE;IAChC,yFAAyF;IAEzF,QAAQ,EAAE,GAAG,CAAA;IACb,qFAAqF;IACrF,EAAE,EAAE,QAAQ,CAAA;IACZ,6CAA6C;IAC7C,EAAE,EAAE,QAAQ,CAAA;IACZ,wEAAwE;IAExE,OAAO,EAAE,GAAG,CAAA;IACZ,iGAAiG;IAEjG,MAAM,EAAE,MAAM,CAAA;CACjB"}

package/build/lib/platform.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/lib/schedule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/lib/schedule.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,WACH,KAAK,KAAG,IAAI,CAGvD;AAED;;GAEG;AACH,qBAAa,aAAa;IACV,OAAO,CAAC,QAAQ;gBAAR,QAAQ,EAAE,QAAQ;IAEtC;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAEjC;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAuC/B,0DAA0D;IAC1D,IAAI;IAIJ;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI;CAIrB;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,iBAErD;AAiFD,KAAK,KAAK,GACJ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC,GACtC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,GACpC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,GACjC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAA;AAE1D,KAAK,SAAS,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AACtD,KAAK,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAC/D,KAAK,IAAI,GAAG,GAAG,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,CAAA;AAC3D,KAAK,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAA;AAClG,KAAK,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAC1D,KAAK,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAE9F,KAAK,OAAO,GAAG,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,CAAA;AAE9D,UAAU,SAAS;IACf,IAAI,EAAE,QAAQ,EAAE,CAAA;IAChB,IAAI,EAAE,IAAI,CAAA;IACV,EAAE,EAAE,IAAI,CAAA;CACX;AAED,MAAM,WAAW,QAAQ;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,SAAS,EAAE,CAAA;IAC1B,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CACvB"}
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/lib/schedule.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,IACV,OAAO,KAAK,KAAG,IAAI,CAGvD;AAED;;GAEG;AACH,qBAAa,aAAa;IACV,OAAO,CAAC,QAAQ;gBAAR,QAAQ,EAAE,QAAQ;IAEtC;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAEjC;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAuC/B,0DAA0D;IAC1D,IAAI;IAIJ;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI;CAIrB;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,iBAErD;AAiFD,KAAK,KAAK,GACJ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC,GACtC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,GACpC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,GACjC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAA;AAE1D,KAAK,SAAS,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AACtD,KAAK,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAC/D,KAAK,IAAI,GAAG,GAAG,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,CAAA;AAC3D,KAAK,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAA;AAClG,KAAK,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAC1D,KAAK,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAE9F,KAAK,OAAO,GAAG,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,CAAA;AAE9D,UAAU,SAAS;IACf,IAAI,EAAE,QAAQ,EAAE,CAAA;IAChB,IAAI,EAAE,IAAI,CAAA;IACV,EAAE,EAAE,IAAI,CAAA;CACX;AAED,MAAM,WAAW,QAAQ;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,SAAS,EAAE,CAAA;IAC1B,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CACvB"}

package/changelog.md

@@ -1,6 +1,24 @@
 # Changelog
 
-### 0.6.0 → 0.7.1 (unstable)
+### 0.7.1 → 0.8.0 (unstable)
+
+Breaking changes:
+
+-   `WorkflowControls` parameter added to step `execute` methods - all `ProgrammaticStep`,
+    `StringLLMStep`, and `JsonLLMStep` execute functions now receive workflow controls as the last
+    parameter,
+-   `Workflow.terminate()` and `Workflow.rewindTo()` methods removed - use
+    `WorkflowControls.terminate()` and `WorkflowControls.rewindTo()` from within step execution
+    instead, note that `WorkflowControls.rewindTo()` accept step name, rather then link to a step,
+-   `shouldExecute` property removed from `StringLLMStep` and `JsonLLMStep` interfaces - use
+    conditional logic within the `execute` function.
+-   `beforeEach` callback also moved into `Workflow.run` as third parameter
+
+Other changes:
+
+-   Added support for additional OpenAI models: `gpt-4o-2024-08-06` and `gpt-4.1-2025-04-14`.
+
+### 0.7.0 → 0.7.1 (unstable)
 
 -   fixed multiple runs on static workflows
 

package/eslint.config.mjs

@@ -39,6 +39,8 @@ export default tseslint.config(
             'vitest.config.ts',
             'deploy/cdk.out/**',
             'drafts/**',
+            'build/**',
+            '**/*.spec.ts',
         ],
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@recombine-ai/engine",
-    "version": "0.7.1",
+    "version": "0.8.0",
     "description": "Recombine AI engine for creating conversational AI agents",
     "main": "build/index.js",
     "types": "build/index.d.ts",
@@ -10,12 +10,15 @@
     "scripts": {
         "dev": "tsc -w",
         "build": "tsc",
+        "typecheck": "tsc --noEmit",
         "prepublishOnly": "npm run build",
         "test": "vitest",
         "docs": "cd docusaurus && yarn build --out-dir ../docs && cd ..",
         "lint": "eslint",
         "lint:fix": "eslint --fix",
-        "format": "prettier --write ."
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "prepare": "husky"
     },
     "devDependencies": {
         "@eslint/js": "^9.26.0",
@@ -23,6 +26,8 @@
         "@types/nunjucks": "^3.2.6",
         "@typescript-eslint/eslint-plugin": "^8.32.0",
         "eslint": "^9.26.0",
+        "husky": "^9.1.7",
+        "lint-staged": "^16.2.4",
         "prettier": "^3.3.3",
         "typescript": "^5.8.3",
         "typescript-eslint": "^8.32.0",
@@ -33,5 +38,14 @@
         "openai": "^4.68.4",
         "zod": "3.23.8",
         "zod-to-json-schema": "^3.24.6"
+    },
+    "husky": {
+        "hooks": {}
+    },
+    "lint-staged": {
+        "*.{ts,tsx,js,jsx,json,md}": [
+            "pnpm format",
+            "pnpm lint:fix"
+        ]
     }
 }

package/readme.md

@@ -101,3 +101,50 @@ workflow.terminate() // usually used in kill-switch or error handlers: terminate
 workflow.rewind(step) // restart workflow from a particular step
 workflow.beforeEach(callback) // a callback to run before each step, e.g. to terminate workflow due to some external reasons
 ```
+
+## Development
+
+### Setting Up the Development Environment
+
+To contribute to this project, you'll need to set up your local development environment:
+
+1. **Install dependencies:**
+
+    ```sh
+    yarn install
+    ```
+
+    This project uses `yarn` as its package manager. If you don't have it installed, you can install it with:
+
+    ```sh
+    npm install -g yarn
+    ```
+
+2. **Set up Git hooks with Husky:**
+
+    Git hooks are automatically installed when you run `yarn install` (via the `prepare` script). The project uses Husky to manage the following Git hooks:
+
+    - **`pre-commit`**: Runs `lint-staged` to format and lint only staged files using Prettier and ESLint
+    - **`pre-push`**: Runs TypeScript type checking to ensure no type errors before pushing
+    - **`post-merge`**: Automatically runs `yarn install` if `package.json` or `yarn.yaml` changed after a merge
+
+### Available Scripts
+
+-   **`yarn dev`** - Start TypeScript compiler in watch mode
+-   **`yarn build`** - Build the project
+-   **`yarn typecheck`** - Run TypeScript type checking without emitting files
+-   **`yarn test`** - Run tests with Vitest
+-   **`yarn lint`** - Lint code with ESLint
+-   **`yarn lint:fix`** - Lint and automatically fix issues
+-   **`yarn format`** - Format code with Prettier
+-   **`yarn format:check`** - Check code formatting without making changes
+
+### Code Quality
+
+The project maintains code quality through:
+
+-   **TypeScript** for type safety
+-   **ESLint** for code linting
+-   **Prettier** for consistent code formatting
+-   **Vitest** for testing
+-   **Husky + lint-staged** for automated pre-commit checks