@hexabot-ai/api 3.3.1 → 3.3.3

package/src/extensions/actions/ai/ai-prompt.helpers.ts

@@ -0,0 +1,299 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  IncomingMessageType,
+  Message,
+  StdIncomingMessage,
+  StdOutgoingMessage,
+  Thread,
+} from '@hexabot-ai/types';
+import { ModelMessage } from 'ai';
+
+import { RuntimeBindings } from '@/bindings/runtime-bindings';
+import { WorkflowRuntimeContext } from '@/workflow/contexts/workflow-runtime.context';
+
+import {
+  AiPromptInput,
+  DEFAULT_AI_MESSAGES_LIMIT,
+  DEFAULT_AI_PROMPT,
+} from './ai-schemas';
+
+/**
+ * Shared prompt + working-memory builders used by every AI-flavored action
+ * (`ai_agent`, `generate_*`, and the sandboxed `ai_coding_agent`) so they build
+ * the model request from a direct prompt or conversation history, and inject
+ * selected memory, in exactly the same way. `AiBaseAction` delegates to these;
+ * actions that do not extend it (the coding agent runs on a different engine)
+ * import them directly.
+ */
+
+export type PromptPayload =
+  | { prompt: string; system?: string }
+  | { messages: ModelMessage[]; system?: string };
+
+export function resolveMessageContent(
+  payload: StdOutgoingMessage | StdIncomingMessage,
+): string | undefined {
+  if (!payload) {
+    return undefined;
+  }
+
+  const data = payload.data as Record<string, unknown>;
+
+  if (typeof data.text === 'string') {
+    return data.text;
+  }
+
+  if (typeof data.serializedText === 'string') {
+    return data.serializedText;
+  }
+
+  if (
+    payload.type === IncomingMessageType.location &&
+    typeof data.coordinates === 'object' &&
+    data.coordinates !== null &&
+    'lat' in data.coordinates &&
+    'lon' in data.coordinates
+  ) {
+    const { lat, lon } = data.coordinates as { lat: number; lon: number };
+
+    return `location:${lat},${lon}`;
+  }
+
+  try {
+    return JSON.stringify(data);
+  } catch {
+    return String(payload);
+  }
+}
+
+export function normalizeMessagesForModel(
+  messages: Message[],
+  subscriberId: string,
+): ModelMessage[] {
+  type ConversationMessage = {
+    role: Extract<ModelMessage['role'], 'user' | 'assistant'>;
+    content: string;
+    createdAt: Date;
+  };
+
+  const normalized: ConversationMessage[] = messages
+    .map((message) => {
+      const content = resolveMessageContent(message.message);
+
+      if (!content) {
+        return undefined;
+      }
+
+      const role: ConversationMessage['role'] =
+        message.sender === subscriberId ? 'user' : 'assistant';
+
+      return {
+        role,
+        content,
+        createdAt: message.createdAt,
+      };
+    })
+    .filter((message): message is ConversationMessage => Boolean(message));
+
+  return normalized
+    .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+    .map(({ role, content }) => ({ role, content }));
+}
+
+export function formatMemoryValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+
+  if (value === null) {
+    return 'null';
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export function buildMemoryPrompt(
+  context: WorkflowRuntimeContext,
+  selectedMemorySlugs: string[] = [],
+): string | undefined {
+  if (selectedMemorySlugs.length === 0) {
+    return undefined;
+  }
+
+  const memoryStore = context.memoryStore;
+  if (!memoryStore) {
+    return undefined;
+  }
+
+  const { definitionCache, instances } = memoryStore;
+  if (!definitionCache || definitionCache.size === 0) {
+    return undefined;
+  }
+
+  const sections: string[] = [];
+  const selectedSlugSet = new Set(selectedMemorySlugs);
+  for (const [slug, definition] of definitionCache.entries()) {
+    if (!selectedSlugSet.has(slug)) {
+      continue;
+    }
+
+    const instance = instances[slug];
+    if (!instance) {
+      continue;
+    }
+
+    const lines: string[] = [];
+    for (const field of instance.fields({ includeAdditional: true })) {
+      if (field.value === undefined) {
+        continue;
+      }
+
+      const label = (field.title ?? field.name).trim();
+      const value = formatMemoryValue(field.value);
+      lines.push(`- ${label}: ${value}`);
+    }
+
+    if (lines.length === 0) {
+      continue;
+    }
+
+    sections.push(`## ${definition.name}\n${lines.join('\n')}`);
+  }
+
+  if (sections.length === 0) {
+    return undefined;
+  }
+
+  return `# Working Memory\n${sections.join('\n\n')}`;
+}
+
+export function resolveMemoryBindingSlugs(
+  context: WorkflowRuntimeContext,
+  memoryBindings?: RuntimeBindings['memory'],
+): string[] {
+  if (!memoryBindings || Object.keys(memoryBindings).length === 0) {
+    return [];
+  }
+
+  const memoryStore = context.memoryStore;
+  if (!memoryStore) {
+    return [];
+  }
+
+  const idToSlug = new Map<string, string>();
+  for (const [slug, definition] of memoryStore.definitionCache.entries()) {
+    if (definition.id) {
+      idToSlug.set(definition.id, slug);
+    }
+  }
+
+  const selectedSlugs = new Set<string>();
+  for (const [defName, binding] of Object.entries(memoryBindings)) {
+    const definitionId = binding.settings?.definition_id;
+    const slug =
+      typeof definitionId === 'string' ? idToSlug.get(definitionId) : undefined;
+    if (!slug) {
+      throw new Error(
+        `Unable to resolve memory definition "${String(definitionId)}" from bindings.memory.${defName}.settings.definition_id.`,
+      );
+    }
+
+    selectedSlugs.add(slug);
+  }
+
+  return Array.from(selectedSlugs);
+}
+
+/**
+ * Merge an optional working-memory section into the system prompt so selected
+ * memory is presented consistently regardless of the action's input mode.
+ */
+export function mergeMemoryIntoSystem(
+  context: WorkflowRuntimeContext,
+  system: string | undefined,
+  selectedMemorySlugs: string[] = [],
+): string | undefined {
+  const memoryPrompt = buildMemoryPrompt(context, selectedMemorySlugs);
+  if (!memoryPrompt) {
+    return system;
+  }
+
+  return system ? `${system}\n\n${memoryPrompt}` : memoryPrompt;
+}
+
+export async function buildPrompt(
+  input: AiPromptInput,
+  context: WorkflowRuntimeContext,
+  selectedMemorySlugs: string[] = [],
+): Promise<PromptPayload> {
+  const system = mergeMemoryIntoSystem(
+    context,
+    input.system,
+    selectedMemorySlugs,
+  );
+
+  if (input.input_mode === 'prompt') {
+    const prompt = input.prompt ?? DEFAULT_AI_PROMPT;
+
+    return { prompt, system };
+  }
+
+  if (input.input_mode === 'history') {
+    const messagesLimit = input.messages_limit ?? DEFAULT_AI_MESSAGES_LIMIT;
+
+    if (messagesLimit < 1) {
+      throw new Error(
+        'Input mode "history" requires a positive "messages_limit" value.',
+      );
+    }
+
+    const subscriberId = context.initiatorId;
+    if (!subscriberId) {
+      throw new Error(
+        'A subscriber id is required to load previous messages for this action.',
+      );
+    }
+    const threadId = context.threadId;
+    if (!threadId) {
+      throw new Error(
+        'A thread id is required to load previous messages for this action.',
+      );
+    }
+
+    const messageService = context.services.message;
+    if (!messageService) {
+      throw new Error(
+        'Message service is unavailable in the workflow context.',
+      );
+    }
+
+    const history = await messageService.findLastMessages(
+      { id: threadId } as Thread,
+      messagesLimit,
+    );
+    const messages = normalizeMessagesForModel(history, subscriberId);
+
+    return { messages, system };
+  }
+
+  throw new Error(
+    'An "input_mode" of either "prompt" or "history" is required to build the model request.',
+  );
+}

package/src/extensions/actions/workflow/call-workflow.action.ts

@@ -10,7 +10,10 @@ import { z } from 'zod';
 import { createAction } from '@/actions/create-action';
 import { WorkflowRuntimeContext } from '@/workflow/contexts/workflow-runtime.context';
 import { workflowResourceRef } from '@/workflow/resource-refs';
-import { CallWorkflowResult } from '@/workflow/types';
+import {
+  AWAITING_CHILD_WORKFLOW_REASON,
+  CallWorkflowResult,
+} from '@/workflow/types';
 
 const callWorkflowInputSchema = z.object({
   workflow_id: z.uuid().meta({
@@ -81,6 +84,18 @@ export const CallWorkflowAction = createAction<
   inputSchema: callWorkflowInputSchema,
   outputSchema: callWorkflowFinishedSchema,
   async execute({ input, context }) {
+    // Deterministic replay re-executes this action when the parent resumes
+    // after the child completed. The child was already spawned by the original
+    // execution, so skip the spawn and let suspend() return the recorded
+    // child payload immediately.
+    if (context.workflow.hasRecordedResult()) {
+      const resumeData = await context.workflow.suspend<unknown>({
+        reason: AWAITING_CHILD_WORKFLOW_REASON,
+      });
+
+      return assertFinishedResult(callWorkflowResumeSchema.parse(resumeData));
+    }
+
     // AgenticService owns workflow resolution and run creation because the
     // target workflow is an API-persisted entity, not an agentic DSL primitive.
     const result = await context.services.agentic.callWorkflow({
@@ -97,7 +112,7 @@ export const CallWorkflowAction = createAction<
     // A future event resumes the child leaf first; AgenticService then resumes
     // this parent action with the final child payload.
     const resumeData = await context.workflow.suspend<unknown>({
-      reason: 'awaiting_child_workflow',
+      reason: AWAITING_CHILD_WORKFLOW_REASON,
       data: {
         workflow_id: result.workflow_id,
         workflow_run_id: result.workflow_run_id,

package/src/extensions/index.ts

@@ -20,6 +20,10 @@ export * from './channels/web/inbound';
 
 export * from './helpers/local-storage/index.helper';
 
+export * from './actions/ai/ai-prompt.helpers';
+
+export * from './actions/ai/ai-schemas';
+
 export * from './actions/ai/model.binding';
 
 export * from './actions/ai/tools.binding';

package/src/i18n/controllers/translation.controller.ts

@@ -15,7 +15,7 @@ import {
   Post,
   Query,
 } from '@nestjs/common';
-import { FindManyOptions, In, Not } from 'typeorm';
+import { FindManyOptions } from 'typeorm';
 import { DeleteResult } from 'typeorm/driver/mongodb/typings';
 
 import { UuidParam } from '@/utils';
@@ -85,10 +85,9 @@ export class TranslationController extends BaseOrmController<TranslationOrmEntit
 
   /**
    * Refresh translations : Add new strings and remove old ones
-   * @returns {Promise<any>}
    */
   @Post('refresh')
-  async refresh(): Promise<any> {
+  async refresh(): Promise<DeleteResult> {
     const defaultLanguage = await this.languageService.getDefaultLanguage();
     const languages = await this.languageService.getLanguages();
     const defaultTrans: TranslationOrmEntity['translations'] = Object.keys(
@@ -103,25 +102,10 @@ export class TranslationController extends BaseOrmController<TranslationOrmEntit
         },
         {} as { [key: string]: string },
       );
-    // Scan workflows
-    let strings = await this.translationService.getAllWorkflowStrings();
-    // Filter unique and not empty messages
-    strings = strings.filter((str, pos) => {
-      return str && strings.indexOf(str) == pos;
-    });
-    // Perform refresh
-    const queue = strings.map((str) =>
-      this.translationService.findOneOrCreate(
-        { where: { str } },
-        { str, translations: defaultTrans },
-      ),
-    );
-    await Promise.all(queue);
-    // Purge non existing translations
-    const deleteOptions: FindManyOptions<TranslationOrmEntity> =
-      strings.length > 0 ? { where: { str: Not(In(strings)) } } : {};
 
-    return await this.translationService.deleteMany(deleteOptions);
+    return await this.translationService.refreshWorkflowTranslations(
+      defaultTrans,
+    );
   }
 
   /**

package/src/i18n/services/translation.service.ts

@@ -14,6 +14,8 @@ import { extractTaskDefinitions as extractTaskDefinitionsFromDefs } from '@hexab
 import { Injectable } from '@nestjs/common';
 import { OnEvent } from '@nestjs/event-emitter';
 import jsonata from 'jsonata';
+import { FindManyOptions, In, Not } from 'typeorm';
+import { DeleteResult } from 'typeorm/driver/mongodb/typings';
 
 import { I18nService } from '@/i18n/services/i18n.service';
 import { BaseOrmService } from '@/utils/generics/base-orm.service';
@@ -24,6 +26,9 @@ import { TranslationRepository } from '../repositories/translation.repository';
 
 @Injectable()
 export class TranslationService extends BaseOrmService<TranslationOrmEntity> {
+  /** Number of in-flight batch operations deferring the i18n refresh. */
+  private i18nRefreshDeferrals = 0;
+
   constructor(
     repository: TranslationRepository,
     private readonly workflowService: WorkflowService,
@@ -38,6 +43,38 @@ export class TranslationService extends BaseOrmService<TranslationOrmEntity> {
     this.i18n.refreshDynamicTranslations(translations);
   }
 
+  /**
+   * Synchronize stored translations with the strings currently used by
+   * workflows: create missing ones and purge those no longer referenced.
+   *
+   * Writes run sequentially with the per-event i18n refresh deferred to a
+   * single reload at the end, so a large refresh cannot exhaust the DB pool.
+   *
+   * @param defaultTranslations - Empty translations map seeded on new strings.
+   * @returns The result of purging stale translations.
+   */
+  async refreshWorkflowTranslations(
+    defaultTranslations: TranslationOrmEntity['translations'],
+  ): Promise<DeleteResult> {
+    return await this.deferI18nRefresh(async () => {
+      const strings = [
+        ...new Set((await this.getAllWorkflowStrings()).filter(Boolean)),
+      ];
+
+      for (const str of strings) {
+        await this.findOneOrCreate(
+          { where: { str } },
+          { str, translations: { ...defaultTranslations } },
+        );
+      }
+
+      const deleteOptions: FindManyOptions<TranslationOrmEntity> =
+        strings.length > 0 ? { where: { str: Not(In(strings)) } } : {};
+
+      return await this.deleteMany(deleteOptions);
+    });
+  }
+
   /**
    * Return workflow strings marked for translation via $t() inside task
    * JSONata expressions.
@@ -73,8 +110,29 @@ export class TranslationService extends BaseOrmService<TranslationOrmEntity> {
    * Updates the in-memory translations
    */
   @OnEvent('hook:translation:*')
-  handleTranslationsUpdate() {
-    this.resetI18nTranslations();
+  async handleTranslationsUpdate(): Promise<void> {
+    if (this.i18nRefreshDeferrals > 0) {
+      return;
+    }
+
+    await this.resetI18nTranslations();
+  }
+
+  /**
+   * Run a batch of translation writes with the event-driven i18n refresh
+   * deferred, then reload the in-memory translations once at the end.
+   */
+  private async deferI18nRefresh<T>(operation: () => Promise<T>): Promise<T> {
+    this.i18nRefreshDeferrals++;
+
+    try {
+      return await operation();
+    } finally {
+      this.i18nRefreshDeferrals--;
+      if (this.i18nRefreshDeferrals === 0) {
+        await this.resetI18nTranslations();
+      }
+    }
   }
 
   /**

package/src/license/types/license-quota.ts

@@ -45,7 +45,7 @@ export const LICENSE_QUOTA_LIMITS: Record<
     unlimited: 25,
   },
   workflows: {
-    community: 3,
+    community: 10,
     starter: 25,
     pro: 150,
     unlimited: null,

package/src/workflow/index.ts

@@ -54,6 +54,10 @@ export * from './repositories/mcp-server.repository';
 
 export * from './contexts/conversational-workflow.context';
 
+export * from './contexts/workflow-runtime.context';
+
+export * from './types';
+
 export * from './services/workflow.service';
 
 export * from './services/workflow-version.service';

package/src/workflow/services/agentic.service.ts

@@ -32,6 +32,7 @@ import type {
   WorkflowCallService,
   WorkflowResult,
 } from '../types';
+import { AWAITING_CHILD_WORKFLOW_REASON } from '../types';
 
 import { WorkflowRunService } from './workflow-run.service';
 import { WorkflowService } from './workflow.service';
@@ -167,6 +168,27 @@ export class AgenticService implements WorkflowCallService {
       );
     }
 
+    // Defense in depth against deterministic replay: if the parent is
+    // re-executing an already-resolved `call_workflow` suspension, reuse the
+    // child run it originally spawned instead of creating a duplicate.
+    const replayedChildRun = await this.findReplayedChildRun(
+      parentRun,
+      workflowId,
+      parentContext,
+    );
+    if (replayedChildRun) {
+      this.logger.log(
+        'Reusing recorded child workflow run during parent replay',
+        {
+          parentRunId: parentRun.id,
+          childRunId: replayedChildRun.id,
+          workflowId,
+        },
+      );
+
+      return this.toPersistedCallWorkflowResult(replayedChildRun);
+    }
+
     const workflow = await this.workflowService.findOneAndPopulate(workflowId);
     if (!workflow) {
       throw new Error(`Workflow with ID ${workflowId} not found`);
@@ -498,6 +520,101 @@ export class AgenticService implements WorkflowCallService {
     };
   }
 
+  /**
+   * Detect a deterministic replay of a `call_workflow` suspension and return
+   * the child run originally spawned by that call, if any.
+   *
+   * Replay is identified by the parent runtime control reporting a recorded
+   * resume result for the upcoming suspension; the persisted parent
+   * suspension metadata then pins which child run the original call created.
+   * The runtime signal is required because suspension bookkeeping is not
+   * cleared on resume, so metadata alone would also match a later sequential
+   * call to the same workflow.
+   */
+  private async findReplayedChildRun(
+    parentRun: WorkflowRunFull,
+    workflowId: string,
+    parentContext: WorkflowRuntimeContext,
+  ): Promise<WorkflowRunFull | null> {
+    if (!this.isReplayingRecordedSuspension(parentContext)) {
+      return null;
+    }
+
+    if (parentRun.suspensionReason !== AWAITING_CHILD_WORKFLOW_REASON) {
+      return null;
+    }
+
+    const suspensionData = parentRun.suspensionData as
+      | { workflow_id?: unknown; workflow_run_id?: unknown }
+      | null
+      | undefined;
+    if (
+      suspensionData?.workflow_id !== workflowId ||
+      typeof suspensionData.workflow_run_id !== 'string'
+    ) {
+      return null;
+    }
+
+    const childRun = await this.workflowRunService.findOneAndPopulate(
+      suspensionData.workflow_run_id,
+    );
+    if (
+      !childRun ||
+      this.resolveRunId(childRun.parentRun) !== parentRun.id ||
+      childRun.workflow.id !== workflowId
+    ) {
+      return null;
+    }
+
+    return childRun;
+  }
+
+  /**
+   * Report whether the parent context is replaying a suspension whose resume
+   * result is already recorded.
+   */
+  private isReplayingRecordedSuspension(
+    parentContext: WorkflowRuntimeContext,
+  ): boolean {
+    try {
+      return parentContext.workflow.hasRecordedResult();
+    } catch {
+      // The context may not be attached to a running workflow runtime.
+      return false;
+    }
+  }
+
+  /**
+   * Build the `call_workflow` contract payload from a persisted child run.
+   */
+  private toPersistedCallWorkflowResult(
+    run: WorkflowRunFull,
+  ): CallWorkflowResult {
+    if (run.status === 'finished') {
+      return {
+        status: 'finished',
+        workflow_id: run.workflow.id,
+        workflow_run_id: run.id,
+        output: run.output ?? {},
+      };
+    }
+
+    if (run.status === 'failed') {
+      return {
+        status: 'failed',
+        workflow_id: run.workflow.id,
+        workflow_run_id: run.id,
+        error: run.error ?? 'Child workflow run failed',
+      };
+    }
+
+    return {
+      status: 'suspended',
+      workflow_id: run.workflow.id,
+      workflow_run_id: run.id,
+    };
+  }
+
   /**
    * Resume a suspended parent run after its child run completes or fails.
    *

package/src/workflow/types.ts

@@ -37,6 +37,12 @@ export type MemoryValue = Record<string, unknown>;
 
 export type WorkflowResult = WorkflowStartResult | WorkflowResumeResult;
 
+/**
+ * Suspension reason used by the `call_workflow` action while its parent run
+ * waits for a spawned child run to reach a terminal state.
+ */
+export const AWAITING_CHILD_WORKFLOW_REASON = 'awaiting_child_workflow';
+
 /**
  * Payload passed from a child workflow back to the suspended `call_workflow`
  * action in its parent. Only `finished` is exposed as the action output; the