@avakado.ai/schemas 1.1.18 → 1.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avakado.ai/schemas",
-  "version": "1.1.18",
+  "version": "1.1.20",
   "description": "Canonical Mongo schemas, models, enums and index declarations shared by the Avakado services.",
   "license": "UNLICENSED",
   "type": "module",

package/src/enums/index.js

@@ -3,6 +3,12 @@
 // missing from a validator, a partial index filtering on a status list that had fallen behind.
 // Anything that validates or filters on these values must read them from here.
 
+export const LEAD_STATUS = ["new", "contacted", "qualified", "converted", "lost", "spam"];
+export const CONVERSATION_STATUS = ["open", "pending", "snoozed", "completed", "closed", "archived", "spam"];
+export const CAMPAIGN_STATUS = ["pending", "active", "completed", "failed", "partial"];
+export const TASK_STATUS = ["pending", "in-progress", "completed", "failed", "skipped"];
+export const WORKFLOW_TRIGGERS = [...LEAD_STATUS.map(status => `lead_${status}`), ...CONVERSATION_STATUS.map(status => `conversation_${status}`), ...CAMPAIGN_STATUS.map(status => `campaign_${status}`), ...TASK_STATUS.map(status => `task_${status}`)];
+export const CONVERSATION_PRIORITY = ["low", "normal", "high", "urgent"];
 export const SUBSCRIPTION_STATUS = [
     "created",
     "pending_payment",
@@ -55,11 +61,7 @@ export const LEDGER_CATEGORY = {
     THIRD_PARTY: "third_party",
 };
 
-export const CONVERSATION_STATUS = ["open", "pending", "snoozed", "completed", "closed", "archived", "spam"];
-export const CONVERSATION_PRIORITY = ["low", "normal", "high", "urgent"];
 
-export const CAMPAIGN_STATUS = ["pending", "active", "completed", "failed", "partial"];
-export const TASK_STATUS = ["pending", "in-progress", "completed", "failed", "skipped"];
 export const TASK_TYPES = ["quick", "webhook"];
 export const TASK_REFERENCE_TYPES = ["Message", "CallSession"];
 

package/src/models/Campaign.js

@@ -1,6 +1,7 @@
 import { Schema } from "mongoose";
 import { defineModel } from "../runtime.js";
 import { CAMPAIGN_STATUS, TASK_REFERENCE_TYPES, TASK_STATUS, TASK_TYPES } from "../enums/index.js";
+import { attachStatusChangeTrigger } from "../statusTrigger.js";
 
 const TaskSchema = new Schema({
     business: { type: Schema.Types.ObjectId, ref: 'Businesses', required: true },
@@ -62,6 +63,9 @@ CampaignSchema.methods.updateTimeLine = async function (timeLine, currentStatus)
     return this.save();
 };
 
+attachStatusChangeTrigger(TaskSchema, "task");
+attachStatusChangeTrigger(CampaignSchema, "campaign");
+
 export { CampaignSchema, TaskSchema };
 export const Campaign = defineModel('Campaign', CampaignSchema, 'Campaign');
 export const Task = defineModel('Task', TaskSchema, 'Tasks');

package/src/models/Conversations.js

@@ -1,6 +1,7 @@
 import { Schema } from "mongoose";
 import { defineModel, requireDep } from "../runtime.js";
 import { CONVERSATION_PRIORITY, CONVERSATION_STATUS } from "../enums/index.js";
+import { attachStatusChangeTrigger } from "../statusTrigger.js";
 const ConversationSchema = new Schema({
     agent: { type: Schema.Types.ObjectId, ref: 'Agent' },  // the AI agent
     business: { type: Schema.Types.ObjectId, ref: 'Businesses' },
@@ -76,20 +77,10 @@ ConversationSchema.methods.updateStatus = async function (status) {
             acks: -1
         });
     }
-
-    // if (businessId) {
-    //     const trigger = await Trigger.findOne({ business: businessId, name: "conversationStatusUpdated", type: status });
-    //     for (const workflow of trigger?.workflows ?? []) {
-    //         await sendKafkaMessage({
-    //             topic: 'workflow-execution-trigger',
-    //             message: { key: workflow.toString(), value: JSON.stringify({ conversationId }) },
-    //             acks: -1
-    //         });
-    //     }
-    // }
-
     return saved;
 };
 
+attachStatusChangeTrigger(ConversationSchema, "conversation");
+
 export { ConversationSchema };
 export const Conversation = defineModel('Conversation', ConversationSchema, "Conversations");

package/src/models/Leads.js

@@ -1,6 +1,7 @@
 import { Schema } from "mongoose";
 import { defineModel } from "../runtime.js";
-const leadStatusEnum = ["new", "contacted", "qualified", "converted", "lost"];
+import { LEAD_STATUS } from "../enums/index.js";
+import { attachStatusChangeTrigger } from "../statusTrigger.js";
 const platformEntrySchema = new Schema({
     platform: { type: String, required: true },   // Phone,'Twitter', 'Instagram', 'Whatsapp', etc.
     handle: { type: String, trim: true },
@@ -49,7 +50,7 @@ const LeadSchema = new Schema({
     tags: [String],
     //evaluation
     leadScore: { type: Number, default: 0 },
-    status: { type: String, enum: leadStatusEnum, default: 'new' },
+    status: { type: String, enum: LEAD_STATUS, default: 'new' },
     notes: { type: [String], trim: true },
     // operations
     lastInteractedAt: Date,
@@ -80,5 +81,7 @@ const LeadTemplateSchema = new Schema({
     isActive: { type: Boolean, default: true }
 }, { timestamps: true });
 
+attachStatusChangeTrigger(LeadSchema, "lead");
+
 export const Lead = defineModel('Lead', LeadSchema, 'Leads');
 export const LeadTemplate = defineModel('LeadTemplate', LeadTemplateSchema, 'LeadTemplates');

package/src/models/Workflow.js

@@ -1,9 +1,13 @@
+import { randomUUID } from "node:crypto";
 import { Schema } from "mongoose";
 import { defineModel } from "../runtime.js";
 import { Task_Tree } from "./Action.js";
+import { WORKFLOW_TRIGGERS } from "../enums/index.js";
+import { WorkflowLogs } from "./WorkflowLogs.js";
+import { runTaskTree, stored } from "../workflowRunner.js";
 const WorkflowSchema = new Schema({
     name: { type: String, default: "Untitled Workflow" },
-    trigger: { type: String, required: true },
+    trigger: { type: String, required: true, enum: WORKFLOW_TRIGGERS },
     business: { type: Schema.Types.ObjectId, ref: "Businesses" },
     status: { type: String, enum: ["active", "disabled"], default: "active" },
     task: Task_Tree,
@@ -17,6 +21,55 @@ WorkflowSchema.methods.updateStatus = function (status) {
     this.status = status;
     return this.save();
 };
+WorkflowSchema.methods.execute = async function (payload, meta = {}) {
+    if (this.status === "disabled") return { skipped: true };
+    const businessId = String(this.business?._id ?? this.business ?? "");
+    const executionId = randomUUID();
+    const startedAt = new Date();
+    const log = await WorkflowLogs.create({
+        workflow: this._id,
+        business: this.business?._id ?? this.business,
+        executionId,
+        eventId: meta.eventId,
+        name: this.name,
+        trigger: this.trigger,
+        status: "running",
+        summary: `Workflow "${this.name}" started for ${this.trigger}.`,
+        input: stored(payload),
+        steps: [],
+        startedAt,
+    });
+
+    const record = async (step) => {
+        log.steps.push(step);
+        log.summary = [`Workflow "${this.name}" ran for ${this.trigger}.`, ...log.steps.map((item) => item.summary)].join("\n");
+        await log.save();
+    };
+
+    try {
+        const outputs = await runTaskTree(this.task, {
+            runtime: payload ?? {},
+            trigger: this.trigger,
+            businessId,
+            onStep: record,
+        });
+        log.status = "completed";
+        log.outputs = stored(outputs);
+        log.finishedAt = new Date();
+        log.summary = [`Workflow "${this.name}" completed for ${this.trigger}.`, ...log.steps.map((item) => item.summary)].join("\n");
+        await log.save();
+        return { executionId, outputs };
+    } catch (error) {
+        log.status = "failed";
+        log.error = { message: error?.message || String(error), stack: error?.stack };
+        log.outputs = stored(error.workflowOutputs ?? []);
+        log.finishedAt = new Date();
+        log.summary = [`Workflow "${this.name}" failed for ${this.trigger}.`, ...log.steps.map((item) => item.summary)].filter(Boolean).join("\n");
+        if (!log.steps.some((step) => step.status === "failed")) log.summary += `\n${error?.message || error}`;
+        await log.save();
+        throw error;
+    }
+};
 // WorkflowSchema.methods.getNextNode = function ({ currentNode = "", outputPortsOfCurentNode = [] } = {}) {
 //     const nextNodes = [];
 //     if (!currentNode) return [Object.keys(this.nodes).find((ele) => this.nodes[ele].type === "trigger")];

package/src/models/WorkflowLogs.js

@@ -1,22 +1,45 @@
 import { Schema } from "mongoose";
 import { defineModel } from "../runtime.js";
 
-const WorkflowLogsSchema = new Schema({
-    workflowId: String,
-    trigger: {
-        conversationId: String,
-    },
-    executionId: String,
+// One document per workflow run. `steps` is the order the task tree actually ran,
+// including the input and output of each step, so a person can read what happened.
+const workflowStepSchema = new Schema({
     nodeId: String,
-    lable: String,
-    nodeInput: Schema.Types.Mixed,
-    nodeInputError: Schema.Types.Mixed,
-    nodeOutput: Schema.Types.Mixed,
-    nodeError: Schema.Types.Mixed,
-    nodeStatus: { type: String, enum: ["pending", "in-progress", "completed", "failed", "skipped"], default: "pending" },
+    label: String,
+    type: { type: String, enum: ["task", "conditional"] },
+    status: { type: String, enum: ["completed", "failed"], required: true },
+    summary: String,
+    input: Schema.Types.Mixed,
+    output: Schema.Types.Mixed,
+    error: { message: String, stack: String },
+    startedAt: Date,
+    finishedAt: Date,
+}, { _id: false });
+
+const WorkflowLogsSchema = new Schema({
+    workflow: { type: Schema.Types.ObjectId, ref: "Workflow", required: true },
+    business: { type: Schema.Types.ObjectId, ref: "Businesses" },
+    executionId: { type: String, required: true },
+    eventId: String,
+    name: String,
+    trigger: String,
+    status: { type: String, enum: ["running", "completed", "failed"], default: "running" },
+    summary: String,
+    input: Schema.Types.Mixed,
+    outputs: Schema.Types.Mixed,
+    error: { message: String, stack: String },
+    steps: [workflowStepSchema],
+    startedAt: Date,
+    finishedAt: Date,
 }, {
-    timestamps: true
-}
-);
+    timestamps: true,
+});
+
+WorkflowLogsSchema.index({ executionId: 1 }, { unique: true });
+WorkflowLogsSchema.index({ workflow: 1, createdAt: -1 });
+WorkflowLogsSchema.index({ business: 1, createdAt: -1 });
+WorkflowLogsSchema.index({ trigger: 1, createdAt: -1 });
+WorkflowLogsSchema.index({ status: 1, createdAt: -1 });
 
-export const WorkflowLogs = defineModel('WorkflowLogs', WorkflowLogsSchema, 'WorkflowLogs');
+export { WorkflowLogsSchema };
+export const WorkflowLogs = defineModel("WorkflowLogs", WorkflowLogsSchema, "WorkflowLogs");

package/src/statusTrigger.js

@@ -0,0 +1,217 @@
+import { randomUUID } from "node:crypto";
+import { CAMPAIGN_STATUS, CONVERSATION_STATUS, LEAD_STATUS, TASK_STATUS } from "./enums/index.js";
+import { requireDep } from "./runtime.js";
+
+// Status is not written in one place. Conversations go through updateStatus, but also
+// findOneAndUpdate. Leads are created and patched with findOneAndUpdate / findByIdAndUpdate.
+// Campaigns and tasks change status inside updateTimeLine, and tasks are also insertMany'd
+// and updateMany'd to "skipped". These hooks run after the write, so a status that fails
+// validation never publishes a trigger for a change that did not persist.
+
+export const WORKFLOW_TRIGGER_TOPIC = "workflow-execution-trigger";
+
+const STATUS_BY_ENTITY = {
+    lead: new Set(LEAD_STATUS),
+    conversation: new Set(CONVERSATION_STATUS),
+    campaign: new Set(CAMPAIGN_STATUS),
+    task: new Set(TASK_STATUS),
+};
+
+const UPDATE_HOOKS = ["findOneAndUpdate", "updateOne", "updateMany", "replaceOne", "findOneAndReplace"];
+const pendingWrites = new WeakMap();
+const BATCH_SIZE = 50;
+
+function allowed(entity, status) {
+    return typeof status === "string" && STATUS_BY_ENTITY[entity]?.has(status);
+}
+
+function businessIdOf(doc) {
+    const business = doc?.business;
+    if (business == null || business === "") return "";
+    if (typeof business === "object" && business._id != null) return String(business._id);
+    return String(business);
+}
+
+function serializeDocument(doc) {
+    if (doc == null) return null;
+    try {
+        const plain = typeof doc.toObject === "function" ? doc.toObject({ virtuals: false }) : doc;
+        const seen = new WeakSet();
+        return JSON.parse(JSON.stringify(plain, (_key, value) => {
+            if (typeof value === "bigint") return value.toString();
+            if (typeof value === "object" && value !== null) {
+                if (seen.has(value)) return undefined;
+                seen.add(value);
+            }
+            return value;
+        }));
+    } catch {
+        return {
+            _id: doc._id != null ? String(doc._id) : null,
+            status: doc.status ?? null,
+            business: businessIdOf(doc) || null,
+        };
+    }
+}
+
+function readNextStatus(entity, update) {
+    if (update == null || typeof update !== "object") return null;
+    let status;
+    // Timestamps middleware adds `$set.updatedAt` without moving the caller's fields,
+    // so a plain update arrives as `{ status, $set: { updatedAt } }`.
+    if (Array.isArray(update)) {
+        for (const stage of update) {
+            if (typeof stage?.$set?.status === "string") status = stage.$set.status;
+        }
+    } else if (typeof update.$set?.status === "string") {
+        status = update.$set.status;
+    } else if (typeof update.status === "string") {
+        status = update.status;
+    }
+    return allowed(entity, status) ? status : null;
+}
+
+function statusTriggerMessage({ entity, status, previousStatus, businessId, document }) {
+    if (!allowed(entity, status) || previousStatus === status) return null;
+    const eventId = randomUUID();
+    const entityId = document?._id != null ? String(document._id) : "";
+    const resolvedBusinessId = businessId ? String(businessId) : businessIdOf(document);
+    const trigger = `${entity}_${status}`;
+    const body = {
+        eventId,
+        businessId: resolvedBusinessId,
+        trigger,
+        payload: {
+            entity,
+            entityId,
+            status,
+            previousStatus: previousStatus ?? null,
+            changedAt: new Date().toISOString(),
+            document: serializeDocument(document),
+        },
+    };
+    return {
+        key: resolvedBusinessId || entityId || eventId,
+        value: JSON.stringify(body),
+        headers: {
+            eventId,
+            businessId: resolvedBusinessId,
+            trigger,
+            entity,
+        },
+    };
+}
+
+async function publishStatusChanges(changes) {
+    const messages = changes.map(statusTriggerMessage).filter(Boolean);
+    if (!messages.length) return;
+    const sendKafkaMessage = requireDep("sendKafkaMessage", "workflow status trigger");
+    for (let i = 0; i < messages.length; i += BATCH_SIZE) {
+        const batch = messages.slice(i, i + BATCH_SIZE);
+        try {
+            await sendKafkaMessage({ topic: WORKFLOW_TRIGGER_TOPIC, messages: batch, acks: -1 });
+        } catch (error) {
+            console.error(
+                `@avakado.ai/schemas: failed to publish ${batch.length} workflow status trigger(s) on ${WORKFLOW_TRIGGER_TOPIC}`,
+                error?.message || error
+            );
+        }
+    }
+}
+
+function writeApplied(result) {
+    if (result == null || typeof result !== "object") return false;
+    if ("matchedCount" in result || "modifiedCount" in result || "upsertedCount" in result) {
+        return (result.matchedCount || 0) > 0 || (result.modifiedCount || 0) > 0 || (result.upsertedCount || 0) > 0;
+    }
+    return result._id != null;
+}
+
+export function attachStatusChangeTrigger(schema, entity) {
+    schema.post("init", function recordLoadedStatus() {
+        this.$locals.loadedStatus = this.status;
+    });
+
+    schema.pre("save", function captureStatusChange() {
+        const status = this.status;
+        if (this.isNew) {
+            this.$locals.statusEmit = allowed(entity, status) ? { status, previousStatus: null } : null;
+            return;
+        }
+        if (!this.isModified("status") || !allowed(entity, status)) {
+            this.$locals.statusEmit = null;
+            return;
+        }
+        const previousStatus = Object.prototype.hasOwnProperty.call(this.$locals, "loadedStatus")
+            ? this.$locals.loadedStatus
+            : null;
+        this.$locals.statusEmit = previousStatus === status ? null : { status, previousStatus };
+    });
+
+    schema.post("save", async function publishSavedStatus() {
+        const emit = this.$locals.statusEmit;
+        this.$locals.loadedStatus = this.status;
+        this.$locals.statusEmit = null;
+        if (!emit) return;
+        await publishStatusChanges([{
+            entity,
+            status: emit.status,
+            previousStatus: emit.previousStatus,
+            businessId: businessIdOf(this),
+            document: this,
+        }]);
+    });
+
+    schema.pre(UPDATE_HOOKS, async function captureQueryStatusChange() {
+        const status = readNextStatus(entity, this.getUpdate());
+        if (!status) return;
+        const session = this.getOptions()?.session;
+        let finder = this.model.find(this.getFilter()).select("_id status");
+        if (session) finder = finder.session(session);
+        const rows = await finder.lean();
+        const changed = rows.filter((row) => row.status !== status);
+        if (!changed.length) return;
+        pendingWrites.set(this, {
+            status,
+            previousById: new Map(changed.map((row) => [String(row._id), row.status ?? null])),
+        });
+    });
+
+    schema.post(UPDATE_HOOKS, async function publishQueryStatusChange(result) {
+        const pending = pendingWrites.get(this);
+        pendingWrites.delete(this);
+        if (!pending || !writeApplied(result)) return;
+
+        let docs = [];
+        if (result?._id && pending.previousById.has(String(result._id)) && result.status === pending.status) {
+            docs = [result];
+        } else {
+            const session = this.getOptions()?.session;
+            let finder = this.model.find({
+                _id: { $in: [...pending.previousById.keys()] },
+                status: pending.status,
+            });
+            if (session) finder = finder.session(session);
+            docs = await finder.lean();
+        }
+
+        await publishStatusChanges(docs.map((doc) => ({
+            entity,
+            status: doc.status,
+            previousStatus: pending.previousById.get(String(doc._id)) ?? null,
+            businessId: businessIdOf(doc),
+            document: doc,
+        })));
+    });
+
+    schema.post("insertMany", async function publishInsertedStatus(docs) {
+        if (!Array.isArray(docs) || !docs.length) return;
+        await publishStatusChanges(docs.map((doc) => ({
+            entity,
+            status: doc?.status,
+            previousStatus: null,
+            businessId: businessIdOf(doc),
+            document: doc,
+        })));
+    });
+}

package/src/workflowRunner.js

@@ -0,0 +1,190 @@
+// Walks a workflow task the same way tool_utils.executeTool does: each node reads
+// `context.runtime`, `context.preset`, and `context.outputs`, then a task runs its
+// compiled instructions. Conditionals take the first child when the mapped value is
+// truthy and the second child otherwise.
+
+const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+
+export function plainValue(value) {
+    if (value == null) return value;
+    if (typeof value.toObject === "function") return value.toObject({ virtuals: false });
+    return value;
+}
+
+export function getTreeMap(tree) {
+    const plain = plainValue(tree) ?? {};
+    const nodes = new Map((plain.nodes ?? []).map((node) => [node.id, node]));
+    return { rootId: plain.rootId, rootKey: plain.rootKey, nodes };
+}
+
+function evaluateExpression(expression, context) {
+    return new Function("context", `return (${expression});`)(context);
+}
+
+// tool_utils.evaluateToolInput
+export function evaluateMapper(mapper, context) {
+    const treeMap = getTreeMap(mapper);
+    const evaluate = (node) => {
+        if (!node) return undefined;
+        const expression = node.core?.mapper?.expression;
+        if (expression) return evaluateExpression(expression, context);
+        switch (node.core?.flattenedSchema?.type) {
+            case "object":
+                return Object.fromEntries((node.children ?? []).map((child) => {
+                    const childNode = treeMap.nodes.get(child.id);
+                    return [child.key, childNode ? evaluate(childNode) : undefined];
+                }));
+            case "array":
+                return (node.children ?? []).map((child) => {
+                    const childNode = treeMap.nodes.get(child.id);
+                    return childNode ? evaluate(childNode) : undefined;
+                });
+            default:
+                return undefined;
+        }
+    };
+    const root = treeMap.nodes.get(treeMap.rootId);
+    return root ? evaluate(root) : undefined;
+}
+
+export function nodeInput(node, context) {
+    const compiled = node.core?.input?.compiledMapper;
+    if (typeof compiled === "string" && compiled.trim()) return evaluateExpression(compiled, context);
+    if (node.core?.input?.mapper) return evaluateMapper(node.core.input.mapper, context);
+    return undefined;
+}
+
+export function nodeLabel(node) {
+    return node?.meta?.label || node?.core?.meta?.label || node?.id || "Untitled step";
+}
+
+export async function runInstructions(node, input) {
+    const instructions = node.core?.coreExecution?.compiledInstructions;
+    if (typeof instructions !== "string" || !instructions.trim()) return undefined;
+    return new AsyncFunction("input", instructions)(input);
+}
+
+export function stored(value) {
+    if (value instanceof Error) return { message: value.message, stack: value.stack };
+    const seen = new WeakSet();
+    try {
+        return JSON.parse(JSON.stringify(value, (_key, item) => {
+            if (typeof item === "bigint") return item.toString();
+            if (typeof item === "object" && item !== null) {
+                if (seen.has(item)) return undefined;
+                seen.add(item);
+            }
+            return item;
+        }));
+    } catch {
+        return undefined;
+    }
+}
+
+function childNode(treeMap, child) {
+    if (!child?.id) return undefined;
+    const node = treeMap.nodes.get(child.id);
+    if (!node) throw new Error(`Invalid tree: referenced node "${child.id}" does not exist`);
+    return node;
+}
+
+/**
+ * Runs the task tree from its root. `onStep` is awaited with each step once that
+ * step has finished (completed or failed) so the caller can persist it.
+ * A failed step rejects after `onStep` returns.
+ */
+export async function runTaskTree(task, { runtime, trigger, businessId, onStep }) {
+    const treeMap = getTreeMap(task);
+    const outputs = [];
+    const root = treeMap.nodes.get(treeMap.rootId);
+    if (!root) throw new Error("Workflow task has no root node");
+
+    const execute = async (node) => {
+        const startedAt = new Date();
+        const label = nodeLabel(node);
+        const context = {
+            runtime: runtime ?? {},
+            preset: node.core?.input?.preset ?? {},
+            outputs,
+            trigger,
+            businessId,
+            payload: runtime ?? {},
+        };
+        let completed;
+        try {
+            if (node.core?.type === "task") {
+                if ((node.children ?? []).length > 1) {
+                    throw new Error(`Task "${label}" has multiple outgoing edges`);
+                }
+                const input = nodeInput(node, context);
+                const output = await runInstructions(node, input);
+                outputs.push(output);
+                const next = (node.children ?? []).length ? childNode(treeMap, node.children[0]) : undefined;
+                completed = {
+                    step: {
+                        nodeId: node.id,
+                        label,
+                        type: "task",
+                        status: "completed",
+                        input: stored(input),
+                        output: stored(output),
+                        summary: `Completed "${label}".`,
+                        startedAt,
+                        finishedAt: new Date(),
+                    },
+                    next,
+                };
+            } else if (node.core?.type === "conditional") {
+                if ((node.children ?? []).length > 2) {
+                    throw new Error(`Condition "${label}" cannot have more than 2 outgoing edges`);
+                }
+                const condition = nodeInput(node, context);
+                outputs.push(condition);
+                const nextChild = condition ? node.children?.[0] : node.children?.[1];
+                const next = nextChild ? childNode(treeMap, nextChild) : undefined;
+                const nextLabel = next ? nodeLabel(next) : "";
+                const summary = condition
+                    ? `Condition "${label}" was true${nextLabel ? `, continued to "${nextLabel}"` : ""}.`
+                    : `Condition "${label}" was false${nextLabel ? `, continued to "${nextLabel}"` : ", so the workflow stopped"}.`;
+                completed = {
+                    step: {
+                        nodeId: node.id,
+                        label,
+                        type: "conditional",
+                        status: "completed",
+                        input: stored(condition),
+                        output: stored({ condition: Boolean(condition), nextNodeId: next?.id ?? null }),
+                        summary,
+                        startedAt,
+                        finishedAt: new Date(),
+                    },
+                    next,
+                };
+            } else {
+                throw new Error(`Unknown step type on "${label}"`);
+            }
+        } catch (error) {
+            try {
+                await onStep?.({
+                    nodeId: node.id,
+                    label,
+                    ...(node.core?.type === "task" || node.core?.type === "conditional" ? { type: node.core.type } : {}),
+                    status: "failed",
+                    error: { message: error?.message || String(error), stack: error?.stack },
+                    summary: `Failed at "${label}": ${error?.message || error}`,
+                    startedAt,
+                    finishedAt: new Date(),
+                });
+            } catch (logError) {
+                console.error("@avakado.ai/schemas: failed to record workflow step", logError?.message || logError);
+            }
+            error.workflowOutputs = outputs;
+            throw error;
+        }
+        await onStep?.(completed.step);
+        if (completed.next) await execute(completed.next);
+    };
+
+    await execute(root);
+    return outputs;
+}