@wildo-ai/saas-backend-lib 1.0.1

package/src/flows-actors/utils/__tests__/cli-runtime-operation-support.backend.utils.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  CLIRuntime_AuthMode,
+  CLIRuntime_ExecutionProfile,
+  CLIRuntime_OutputParserMode,
+  CLIRuntime_Profile,
+  CLIRuntime_RunnerHost,
+  LLMProvider_OperationKey,
+} from '@wildo-ai/external-connectors-models';
+import { assessCLIRuntimeOperationSupport } from '../cli-runtime-operation-support.backend.utils';
+
+const baseExecutionProfile: CLIRuntime_ExecutionProfile = {
+  runnerHost: CLIRuntime_RunnerHost.BACKEND_SUBPROCESS,
+  command: 'claude',
+  authMode: CLIRuntime_AuthMode.HOST_MANAGED,
+  allowedApplicationEnvironments: ['production'],
+  workspaceRootPath: '/app',
+  outputParserMode: CLIRuntime_OutputParserMode.TEXT,
+};
+
+describe('cli-runtime-operation-support.backend.utils', () => {
+  it('accepts generateText when the profile declares it', () => {
+    const profile = {
+      supportedRunnerHosts: [CLIRuntime_RunnerHost.BACKEND_SUBPROCESS],
+      supportedOperationKeys: [LLMProvider_OperationKey.GENERATE_TEXT],
+      supportedModels: ['claude-sonnet-4-5'],
+      supportedAuthModes: [CLIRuntime_AuthMode.HOST_MANAGED],
+      supportedOutputParserModes: [CLIRuntime_OutputParserMode.TEXT],
+      modelBinding: {
+        argumentTemplate: ['--model', '{model}'],
+      },
+    } satisfies CLIRuntime_Profile;
+
+    expect(
+      assessCLIRuntimeOperationSupport(
+        profile,
+        baseExecutionProfile,
+        LLMProvider_OperationKey.GENERATE_TEXT,
+      ),
+    ).toEqual({ supported: true });
+  });
+
+  it('rejects generateStructured when the profile omits the required operation binding', () => {
+    const profile = {
+      supportedRunnerHosts: [CLIRuntime_RunnerHost.BACKEND_SUBPROCESS],
+      supportedOperationKeys: [LLMProvider_OperationKey.GENERATE_STRUCTURED],
+      supportedModels: ['claude-sonnet-4-5'],
+      supportedAuthModes: [CLIRuntime_AuthMode.HOST_MANAGED],
+      supportedOutputParserModes: [CLIRuntime_OutputParserMode.TEXT, CLIRuntime_OutputParserMode.JSON],
+      modelBinding: {
+        argumentTemplate: ['--model', '{model}'],
+      },
+    } satisfies CLIRuntime_Profile;
+
+    expect(
+      assessCLIRuntimeOperationSupport(
+        profile,
+        baseExecutionProfile,
+        LLMProvider_OperationKey.GENERATE_STRUCTURED,
+      ),
+    ).toEqual({
+      supported: false,
+      message: 'CLI runtime structured output requires an operation binding',
+    });
+  });
+
+  it('accepts generateStructured once JSON schema binding and JSON output extraction are configured', () => {
+    const profile = {
+      supportedRunnerHosts: [CLIRuntime_RunnerHost.BACKEND_SUBPROCESS],
+      supportedOperationKeys: [LLMProvider_OperationKey.GENERATE_STRUCTURED],
+      supportedModels: ['claude-sonnet-4-5'],
+      supportedAuthModes: [CLIRuntime_AuthMode.HOST_MANAGED],
+      supportedOutputParserModes: [CLIRuntime_OutputParserMode.TEXT, CLIRuntime_OutputParserMode.JSON],
+      modelBinding: {
+        argumentTemplate: ['--model', '{model}'],
+      },
+      operationBindings: {
+        [LLMProvider_OperationKey.GENERATE_STRUCTURED]: {
+          argumentTemplate: ['--output-format', 'json'],
+          outputParserMode: CLIRuntime_OutputParserMode.JSON,
+          jsonOutputPath: ['result'],
+        },
+      },
+    } satisfies CLIRuntime_Profile;
+
+    expect(
+      assessCLIRuntimeOperationSupport(
+        profile,
+        baseExecutionProfile,
+        LLMProvider_OperationKey.GENERATE_STRUCTURED,
+      ),
+    ).toEqual({ supported: true });
+  });
+});

package/src/flows-actors/utils/cli-runtime-operation-support.backend.utils.ts

@@ -0,0 +1,87 @@
+import {
+  CLIRuntime_ExecutionProfile,
+  CLIRuntime_OperationBinding,
+  CLIRuntime_OutputParserMode,
+  CLIRuntime_Profile,
+  LLMProvider_OperationKey,
+} from '@wildo-ai/external-connectors-models';
+
+export interface CLIRuntimeOperationSupportAssessment {
+  supported: boolean;
+  message?: string;
+}
+
+export function getCLIRuntimeOperationBinding(
+  profile: CLIRuntime_Profile,
+  operationKey: string,
+): CLIRuntime_OperationBinding | undefined {
+  return profile.operationBindings?.[operationKey];
+}
+
+export function getEffectiveCLIRuntimeOutputParserMode(
+  profile: CLIRuntime_Profile,
+  executionProfile: CLIRuntime_ExecutionProfile,
+  operationKey: string,
+): CLIRuntime_OutputParserMode {
+  return getCLIRuntimeOperationBinding(profile, operationKey)?.outputParserMode
+    ?? executionProfile.outputParserMode;
+}
+
+/**
+ * The CLI runtime profile declares provider-owned transport capabilities, but
+ * the backend still needs one shared truth source for which semantic
+ * operations the executor can honor without collapsing distinctions like text,
+ * structured output, chat, and streaming.
+ */
+export function assessCLIRuntimeOperationSupport(
+  profile: CLIRuntime_Profile,
+  executionProfile: CLIRuntime_ExecutionProfile,
+  operationKey: string,
+): CLIRuntimeOperationSupportAssessment {
+  if (!profile.supportedOperationKeys.includes(operationKey)) {
+    return {
+      supported: false,
+      message: 'CLI runtime profile does not declare support for the selected semantic LLM operation',
+    };
+  }
+
+  switch (operationKey) {
+    case LLMProvider_OperationKey.GENERATE_TEXT:
+      return { supported: true };
+
+    case LLMProvider_OperationKey.GENERATE_STRUCTURED: {
+      const binding = getCLIRuntimeOperationBinding(profile, operationKey);
+      if (!binding) {
+        return {
+          supported: false,
+          message: 'CLI runtime structured output requires an operation binding',
+        };
+      }
+
+      if (
+        getEffectiveCLIRuntimeOutputParserMode(profile, executionProfile, operationKey)
+        !== CLIRuntime_OutputParserMode.JSON
+      ) {
+        return {
+          supported: false,
+          message: 'CLI runtime structured output requires JSON parsing',
+        };
+      }
+
+      if (!binding.jsonOutputPath?.length) {
+        return {
+          supported: false,
+          message: 'CLI runtime structured output requires a configured JSON output path',
+        };
+      }
+
+      return { supported: true };
+    }
+
+    default:
+      return {
+        supported: false,
+        message: 'CLI runtime does not implement truthful request/response semantics for this operation yet',
+      };
+  }
+}

package/src/flows-actors/utils/cli-runtime-runner.backend.utils.ts

@@ -0,0 +1,171 @@
+import { spawn } from 'node:child_process';
+import { isAbsolute, relative, resolve } from 'node:path';
+import {
+  CLIRuntime_ExecutionProfile,
+  CLIRuntime_WorkingDirectoryPolicy,
+} from '@wildo-ai/external-connectors-models';
+
+export interface CLIRuntimeCommandExecutionResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+}
+
+export class CLIRuntimeRunnerError extends Error {
+  constructor(
+    message: string,
+    public readonly details: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'CLIRuntimeRunnerError';
+  }
+}
+
+export function resolveCLIRuntimeWorkingDirectory(
+  profile: Pick<CLIRuntime_ExecutionProfile, 'workspaceRootPath' | 'workingDirectoryPolicy' | 'workingDirectoryRelativePath'>,
+): string {
+  if (!isAbsolute(profile.workspaceRootPath)) {
+    throw new CLIRuntimeRunnerError('CLI runtime workspaceRootPath must be an absolute path', {
+      workspaceRootPath: profile.workspaceRootPath,
+    });
+  }
+
+  const normalizedWorkspaceRoot = resolve(profile.workspaceRootPath);
+  const workingDirectory = profile.workingDirectoryPolicy === CLIRuntime_WorkingDirectoryPolicy.WORKSPACE_RELATIVE_PATH
+    ? resolve(normalizedWorkspaceRoot, profile.workingDirectoryRelativePath ?? '')
+    : normalizedWorkspaceRoot;
+
+  const relativePathFromRoot = relative(normalizedWorkspaceRoot, workingDirectory);
+  if (
+    relativePathFromRoot.startsWith('..')
+    || relativePathFromRoot.includes('/../')
+    || relativePathFromRoot.includes('\\..\\')
+  ) {
+    throw new CLIRuntimeRunnerError('CLI runtime working directory escaped the trusted workspace root', {
+      workspaceRootPath: normalizedWorkspaceRoot,
+      workingDirectory,
+    });
+  }
+
+  return workingDirectory;
+}
+
+export async function executeCLIRuntimeCommand(options: {
+  command: string;
+  args?: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  stdinPayload?: string;
+  timeoutMs: number;
+  maxCapturedBytes?: number;
+}): Promise<CLIRuntimeCommandExecutionResult> {
+  const maxCapturedBytes = options.maxCapturedBytes ?? 1024 * 1024;
+
+  return new Promise<CLIRuntimeCommandExecutionResult>((resolvePromise, rejectPromise) => {
+    const child = spawn(options.command, options.args ?? [], {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+
+    const settle = (error?: unknown, result?: CLIRuntimeCommandExecutionResult): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeoutHandle);
+      if (error) {
+        rejectPromise(error);
+        return;
+      }
+      resolvePromise(result ?? { stdout, stderr, exitCode: 0, signal: null });
+    };
+
+    const terminateProcessTree = (signal: NodeJS.Signals): void => {
+      if (child.pid && process.platform !== 'win32') {
+        try {
+          process.kill(-child.pid, signal);
+          return;
+        } catch {
+          // Fall through to child.kill for platforms/processes that do not
+          // support group signalling.
+        }
+      }
+
+      try {
+        child.kill(signal);
+      } catch {
+        // Best effort termination only.
+      }
+    };
+
+    const failForCapturedOutputLimit = (): void => {
+      terminateProcessTree('SIGTERM');
+      settle(new CLIRuntimeRunnerError('CLI runtime output exceeded the allowed capture limit', {
+        maxCapturedBytes,
+      }));
+    };
+
+    const timeoutHandle = setTimeout(() => {
+      terminateProcessTree('SIGTERM');
+      setTimeout(() => terminateProcessTree('SIGKILL'), 2_000);
+      settle(new CLIRuntimeRunnerError('CLI runtime command timed out', {
+        timeoutMs: options.timeoutMs,
+      }));
+    }, options.timeoutMs);
+
+    child.on('error', (error) => {
+      settle(new CLIRuntimeRunnerError(`Failed to start CLI runtime command: ${error.message}`, {
+        originalError: error.message,
+      }));
+    });
+
+    child.stdout.on('data', (chunk: Buffer | string) => {
+      stdout += chunk.toString();
+      if ((Buffer.byteLength(stdout) + Buffer.byteLength(stderr)) > maxCapturedBytes) {
+        failForCapturedOutputLimit();
+      }
+    });
+
+    child.stderr.on('data', (chunk: Buffer | string) => {
+      stderr += chunk.toString();
+      if ((Buffer.byteLength(stdout) + Buffer.byteLength(stderr)) > maxCapturedBytes) {
+        failForCapturedOutputLimit();
+      }
+    });
+
+    child.on('close', (exitCode, signal) => {
+      if (settled) {
+        return;
+      }
+
+      if (exitCode !== 0) {
+        settle(new CLIRuntimeRunnerError('CLI runtime command failed', {
+          exitCode,
+          signal,
+          stderr,
+          stdout,
+        }));
+        return;
+      }
+
+      settle(undefined, {
+        stdout,
+        stderr,
+        exitCode,
+        signal,
+      });
+    });
+
+    if (options.stdinPayload !== undefined) {
+      child.stdin.write(options.stdinPayload);
+    }
+    child.stdin.end();
+  });
+}

package/src/flows-actors/utils/flows-actors-frontend-extractor.utils.ts

@@ -0,0 +1,63 @@
+import {
+  FlowActorSystem,
+  FlowActorSystem_FrontendInfo,
+  FlowActorSystem_FrontendRelevantConfig,
+  FlowActorSystem_Visibility,
+  ResourceOperationRiskLevel,
+  ResourcePrimaryScope,
+} from '@wildo-ai/saas-models';
+
+/**
+ * Extract frontend-relevant information from a FlowActorSystem.
+ * This filters the full system configuration to only what the frontend needs.
+ */
+export function extractFlowActorSystemFrontendInfo(
+  system: FlowActorSystem
+): FlowActorSystem_FrontendInfo {
+  const config = system.config;
+  
+  // Extract relevant config from accessControl, executionRestrictions, etc.
+  // Note: accessControl is an array, we take the first entry for primary scope info
+  const primaryAccessControl = config.accessControl[0];
+  
+  const frontendRelevantConfig: FlowActorSystem_FrontendRelevantConfig = {
+    primaryScope: primaryAccessControl?.primaryScope ?? ResourcePrimaryScope.ORGANIZATIONS,
+    requiresApproval: primaryAccessControl?.requiresApproval ?? false,
+    approverRoles: primaryAccessControl?.approverRoles,
+    riskLevel: config.riskLevel, // riskLevel is directly on config, not under executionRestrictions
+    hasBudgetLimits: !!(config.executionRestrictions?.budgetLimits?.maxCost),
+  };
+
+  return {
+    ref: system.ref,
+    displayName: system.displayName,
+    description: system.description,
+    kind: system.kind,
+    status: system.status,
+    category: system.category,
+    tags: system.tags,
+    metadata: system.metadata,
+    frontendRelevantConfig,
+  };
+}
+
+/**
+ * Filter systems to only those with frontend visibility
+ */
+export function filterFrontendVisibleSystems(
+  systems: FlowActorSystem[]
+): FlowActorSystem[] {
+  return systems.filter(
+    system => system.visibility === FlowActorSystem_Visibility.FRONTEND
+  );
+}
+
+/**
+ * Extract frontend info for all frontend-visible systems
+ */
+export function extractAllFrontendVisibleSystemsInfo(
+  systems: FlowActorSystem[]
+): FlowActorSystem_FrontendInfo[] {
+  return filterFrontendVisibleSystems(systems)
+    .map(extractFlowActorSystemFrontendInfo);
+}

package/src/flows-actors/utils/prompt-ir-adapters.backend.utils.ts

@@ -0,0 +1,257 @@
+import 'reflect-metadata';
+import {
+  PromptIR_ContextItem,
+  PromptIR_TrustLevel,
+  PromptIR_ContextSourceKind,
+  Actors_Memory_Context,
+  Actors_Memory_Entry,
+  Actors_Memory_Scope,
+  ArtifactInstance,
+  RAG_RetrievalResult,
+  FlowsActors_IO_PartKind,
+} from '@wildo-ai/saas-models';
+
+//===============================================================
+// Prompt IR Adapters
+// --------
+// Utility functions to convert existing Wildo types into
+// PromptIR_ContextItem format for prompt compilation.
+// These adapters bridge the gap between domain types and
+// the unified context representation used by the compiler.
+//===============================================================
+
+
+/**
+ * Map memory scope to trust level
+ * - Long-term memory: HIGH (verified, persistent knowledge)
+ * - Short-term memory: MEDIUM (recent but unverified)
+ * - Working memory: MEDIUM (active processing state)
+ */
+function memoryTrustLevel(scope: Actors_Memory_Scope): PromptIR_TrustLevel {
+  switch (scope) {
+    case Actors_Memory_Scope.LONG_TERM:
+      return PromptIR_TrustLevel.HIGH;
+    case Actors_Memory_Scope.SHORT_TERM:
+    case Actors_Memory_Scope.WORKING:
+    default:
+      return PromptIR_TrustLevel.MEDIUM;
+  }
+}
+
+/**
+ * Convert a single memory entry to PromptIR_ContextItem
+ * 
+ * Temporal awareness: Always populates timestamp for context ordering
+ * and recency-aware curation. Falls back to current time if not set.
+ */
+function memoryEntryToContextItem(
+  entry: Actors_Memory_Entry,
+  scope: Actors_Memory_Scope,
+  prefix: string
+): PromptIR_ContextItem {
+  // Serialize value based on type
+  let content: string;
+  if (entry.type === 'text') {
+    content = String(entry.value);
+  } else if (entry.type === 'json') {
+    content = JSON.stringify(entry.value, null, 2);
+  } else {
+    content = `[Binary data: ${entry.key}]`;
+  }
+
+  return {
+    id: `${prefix}_${entry.key}`,
+    content,
+    trust: memoryTrustLevel(scope),
+    sourceKind: PromptIR_ContextSourceKind.MEMORY,
+    // Temporal awareness: always populate timestamp
+    timestamp: entry.timestamp ?? new Date().toISOString(),
+    metadata: {
+      scope,
+      key: entry.key,
+      type: entry.type,
+      expiresAt: entry.expiresAt,
+      ...entry.metadata,
+    },
+  };
+}
+
+/**
+ * Convert Actors_Memory_Context to PromptIR_ContextItem[]
+ * 
+ * Flattens all memory scopes (short-term, long-term, working) into
+ * a single array of context items with appropriate trust levels.
+ * 
+ * @param memory - The actor's memory context
+ * @param actorRef - Optional actor reference for ID prefixing
+ * @returns Array of context items
+ */
+export function memoryToContextItems(
+  memory: Actors_Memory_Context,
+  actorRef?: string
+): PromptIR_ContextItem[] {
+  const items: PromptIR_ContextItem[] = [];
+  const prefix = actorRef ? `mem_${actorRef}` : 'mem';
+
+  // Process short-term memory
+  for (const entry of memory.shortTerm.entries) {
+    items.push(memoryEntryToContextItem(entry, Actors_Memory_Scope.SHORT_TERM, `${prefix}_st`));
+  }
+
+  // Process long-term memory
+  for (const entry of memory.longTerm.entries) {
+    items.push(memoryEntryToContextItem(entry, Actors_Memory_Scope.LONG_TERM, `${prefix}_lt`));
+  }
+
+  // Process working memory
+  for (const entry of memory.working.entries) {
+    items.push(memoryEntryToContextItem(entry, Actors_Memory_Scope.WORKING, `${prefix}_wk`));
+  }
+
+  return items;
+}
+
+/**
+ * Convert ArtifactInstance to PromptIR_ContextItem
+ * 
+ * Artifacts from previous steps are considered MEDIUM trust
+ * (they were generated by agents, not verified by humans).
+ * 
+ * Temporal awareness: Always populates timestamp for context ordering
+ * and recency-aware curation. Falls back to current time if not set.
+ * 
+ * @param artifact - The artifact instance
+ * @returns Context item representation
+ */
+export function artifactToContextItem(artifact: ArtifactInstance): PromptIR_ContextItem {
+  let content: string;
+
+  switch (artifact.type) {
+    case FlowsActors_IO_PartKind.TEXT:
+      content = (artifact.content as any).text || '';
+      break;
+    case FlowsActors_IO_PartKind.STRUCTURED:
+    case FlowsActors_IO_PartKind.RAW_DATA:
+      content = JSON.stringify((artifact.content as any).data, null, 2);
+      break;
+    case FlowsActors_IO_PartKind.FILE:
+      // For files, include reference info but not binary data
+      const fileContent = artifact.content as any;
+      content = `[File: ${artifact.name}]\nPath: ${fileContent.storage?.path || fileContent.storage?.url || 'N/A'}`;
+      break;
+  }
+
+  return {
+    id: `artifact_${artifact.ref}`,
+    content,
+    trust: PromptIR_TrustLevel.MEDIUM,
+    sourceKind: PromptIR_ContextSourceKind.ARTIFACT,
+    // Temporal awareness: always populate timestamp
+    timestamp: artifact.createdAt ?? new Date().toISOString(),
+    metadata: {
+      name: artifact.name,
+      type: artifact.type,
+      definitionRef: artifact.definitionRef,
+      origin: artifact.origin,
+      ...artifact.metadata,
+    },
+  };
+}
+
+/**
+ * Convert multiple ArtifactInstance[] to PromptIR_ContextItem[]
+ * 
+ * @param artifacts - Array of artifact instances
+ * @returns Array of context items
+ */
+export function artifactsToContextItems(artifacts: ArtifactInstance[]): PromptIR_ContextItem[] {
+  return artifacts.map(artifactToContextItem);
+}
+
+/**
+ * Convert RAG_RetrievalResult to PromptIR_ContextItem[]
+ * 
+ * RAG results are considered MEDIUM trust (from owned docs but
+ * may be incomplete or outdated).
+ * 
+ * Temporal awareness: Always populates timestamp for context ordering
+ * and recency-aware curation. Uses document indexedAt if available,
+ * falls back to retrieval timestamp, then current time.
+ * 
+ * @param result - The RAG retrieval result
+ * @returns Array of context items
+ */
+export function ragToContextItems(result: RAG_RetrievalResult): PromptIR_ContextItem[] {
+  const retrievalTimestamp = result.timestamp ?? new Date().toISOString();
+  
+  return result.results.map((item, index) => ({
+    id: `rag_${item.documentId}_${item.chunkId || index}`,
+    content: item.content,
+    trust: PromptIR_TrustLevel.MEDIUM,
+    sourceKind: PromptIR_ContextSourceKind.RAG,
+    relevance: item.score,
+    // Temporal awareness: prefer document timestamp, fallback to retrieval time
+    timestamp: (item.metadata as any)?.indexedAt ?? (item.metadata as any)?.updatedAt ?? retrievalTimestamp,
+    metadata: {
+      query: result.query,
+      documentId: item.documentId,
+      chunkId: item.chunkId,
+      retrievalStrategy: result.retrievalStrategy,
+      duration: result.duration,
+      retrievedAt: retrievalTimestamp, // Track when retrieval happened
+      ...item.metadata,
+    },
+  }));
+}
+
+/**
+ * Convert user input to PromptIR_ContextItem
+ * 
+ * User inputs are considered LOW trust (untrusted source).
+ * 
+ * @param input - The user input (string or object)
+ * @param inputId - Unique identifier for this input
+ * @returns Context item representation
+ */
+export function userInputToContextItem(
+  input: string | Record<string, unknown>,
+  inputId: string
+): PromptIR_ContextItem {
+  const content = typeof input === 'string' 
+    ? input 
+    : JSON.stringify(input, null, 2);
+
+  return {
+    id: `user_input_${inputId}`,
+    content,
+    trust: PromptIR_TrustLevel.LOW,
+    sourceKind: PromptIR_ContextSourceKind.USER_INPUT,
+    timestamp: new Date().toISOString(),
+    metadata: {
+      inputType: typeof input,
+    },
+  };
+}
+
+/**
+ * Merge multiple context item arrays
+ * Removes duplicates by id (first occurrence wins)
+ * 
+ * @param arrays - Arrays of context items to merge
+ * @returns Merged array with duplicates removed
+ */
+export function mergeContextItems(...arrays: PromptIR_ContextItem[][]): PromptIR_ContextItem[] {
+  const seen = new Set<string>();
+  const result: PromptIR_ContextItem[] = [];
+
+  for (const items of arrays) {
+    for (const item of items) {
+      if (!seen.has(item.id)) {
+        seen.add(item.id);
+        result.push(item);
+      }
+    }
+  }
+
+  return result;
+}