@lotiai/composer 0.2.0 → 0.2.1

package/dist/internal/async/config/worker-profiles.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * Worker Profile Definitions for Temporal Activity Workers
+ *
+ * This module defines worker profiles that map step performance characteristics
+ * to appropriate infrastructure resources.
+ *
+ * ## Profiles
+ *
+ * - **standard**: General business logic (API calls, DB queries, content acquisition).
+ *   0.5 vCPU / 2GB per container, 15 concurrent activities, scales 2-10.
+ * - **heavy**: CPU-intensive or long-running work (zone ingestion, large data processing).
+ *   2 vCPU / 4GB per container, 5 concurrent activities, starts at 3 containers and scales 1-3 by default.
+ *
+ * Each profile maps to a dedicated Temporal task queue and ECS service.
+ *
+ * ## Configuration
+ *
+ * Defaults are defined here. Users can override via `composer.build-config.ts`:
+ * ```typescript
+ * workerProfiles: {
+ *   standard: { cpu: 1024, memory: 4096 }  // Override just what you need
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WORKER_PROFILE = exports.WORKER_PROFILES = void 0;
+exports.getTaskQueueForProfile = getTaskQueueForProfile;
+exports.isValidWorkerProfile = isValidWorkerProfile;
+exports.getAllTaskQueues = getAllTaskQueues;
+exports.getEffectiveResources = getEffectiveResources;
+exports.getEffectiveProfileConfig = getEffectiveProfileConfig;
+exports.resolveProfilesForEnvironment = resolveProfilesForEnvironment;
+exports.resolveActivityWorkerRuntimeConfig = resolveActivityWorkerRuntimeConfig;
+exports.loadAndResolveActivityWorkerRuntimeConfig = loadAndResolveActivityWorkerRuntimeConfig;
+exports.loadAndResolveCombinedWorkerConfigForLocalDev = loadAndResolveCombinedWorkerConfigForLocalDev;
+const loader_1 = require("../../../build-config/loader");
+/**
+ * Default worker profile configuration defining resource characteristics and task queues.
+ *
+ * These defaults are referenced by:
+ * - Step definitions (via `workerProfile` field - currently all use "standard")
+ * - Activity workers (to register on the "standard-tasks" queue)
+ * - Infrastructure as Code (to create appropriately sized ECS tasks)
+ *
+ * Users can override these defaults via `composer.build-config.ts`.
+ */
+exports.WORKER_PROFILES = {
+    standard: {
+        name: "Standard",
+        taskQueue: "standard-tasks",
+        description: "General business logic: API calls, database queries, content acquisition, moderate computation",
+        resources: {
+            cpu: 512, // 0.5 vCPU (1024 = 1 vCPU)
+            memory: 2048, // 2 GB in MB
+            maxConcurrentActivities: 15,
+            minCount: 2,
+            maxConcurrentWorkflows: 100,
+            initialCount: 2,
+            maxCount: 10,
+        },
+    },
+    heavy: {
+        name: "Heavy",
+        taskQueue: "heavy-tasks",
+        description: "CPU-intensive or long-running work: zone file ingestion (gunzip + metaphone), large data processing",
+        resources: {
+            cpu: 2048, // 2 vCPU
+            memory: 4096, // 4 GB
+            maxConcurrentActivities: 5,
+            minCount: 1,
+            maxConcurrentWorkflows: 100,
+            initialCount: 3,
+            maxCount: 3,
+        },
+    },
+};
+/**
+ * Default worker profile for steps that don't explicitly declare one.
+ *
+ * Using "standard" as the default provides reasonable performance for
+ * typical business logic without over-provisioning resources.
+ */
+exports.DEFAULT_WORKER_PROFILE = "standard";
+/**
+ * Gets the task queue name for a given worker profile.
+ *
+ * @param profile - The worker profile
+ * @returns Temporal task queue name
+ */
+function getTaskQueueForProfile(profile) {
+    return exports.WORKER_PROFILES[profile].taskQueue;
+}
+/**
+ * Validates that a profile string is a valid WorkerProfile.
+ *
+ * @param profile - The profile string to validate
+ * @returns true if valid, false otherwise
+ */
+function isValidWorkerProfile(profile) {
+    return profile in exports.WORKER_PROFILES;
+}
+/**
+ * Gets all task queue names (useful for workers that listen to multiple queues).
+ *
+ * @returns Array of all task queue names
+ */
+function getAllTaskQueues() {
+    return Object.values(exports.WORKER_PROFILES).map((config) => config.taskQueue);
+}
+/**
+ * Gets the effective resources for a worker profile, merging config overrides with defaults.
+ *
+ * @param profile - The worker profile name
+ * @param configOverrides - Optional overrides from composer.build-config.ts
+ * @returns The merged resource configuration
+ *
+ * @example
+ * ```typescript
+ * // With no overrides, returns defaults
+ * getEffectiveResources("standard");
+ * // { cpu: 512, memory: 2048, maxConcurrentActivities: 15, minCount: 2, initialCount: 2, maxCount: 10 }
+ *
+ * // With overrides, merges them
+ * getEffectiveResources("standard", { cpu: 1024 });
+ * // { cpu: 1024, memory: 2048, maxConcurrentActivities: 15, minCount: 2, initialCount: 2, maxCount: 10 }
+ * ```
+ */
+function getEffectiveResources(profile, configOverrides) {
+    const defaults = exports.WORKER_PROFILES[profile].resources;
+    if (!configOverrides) {
+        return defaults;
+    }
+    // Only merge resource fields; configOverrides may include non-resource keys
+    // such as envExclusiveOptIn used for deployment topology decisions.
+    return {
+        cpu: configOverrides.cpu ?? defaults.cpu,
+        memory: configOverrides.memory ?? defaults.memory,
+        maxConcurrentActivities: configOverrides.maxConcurrentActivities ?? defaults.maxConcurrentActivities,
+        minCount: configOverrides.minCount ?? defaults.minCount,
+        maxConcurrentWorkflows: configOverrides.maxConcurrentWorkflows ?? defaults.maxConcurrentWorkflows,
+        initialCount: configOverrides.initialCount ?? defaults.initialCount,
+        maxCount: configOverrides.maxCount ?? defaults.maxCount,
+    };
+}
+/**
+ * Gets the effective worker profile config, merging config overrides with defaults.
+ *
+ * @param profile - The worker profile name
+ * @param config - Optional composer config containing workerProfiles overrides
+ * @returns The full profile config with merged resources
+ */
+function getEffectiveProfileConfig(profile, config) {
+    const baseConfig = exports.WORKER_PROFILES[profile];
+    const overrides = config?.workerProfiles?.[profile];
+    return {
+        ...baseConfig,
+        resources: getEffectiveResources(profile, overrides),
+    };
+}
+/**
+ * Resolves which worker profiles are deployed for an environment and which task
+ * queues should be absorbed by fallback profiles.
+ *
+ * Profiles with no envExclusiveOptIn are always dedicated.
+ * Profiles with envExclusiveOptIn deploy only when environment is listed.
+ */
+function resolveProfilesForEnvironment(environment, config) {
+    const dedicatedProfiles = {};
+    const fallbackQueues = {};
+    const fallbackSources = {};
+    for (const profile of Object.keys(exports.WORKER_PROFILES)) {
+        const overrides = config?.workerProfiles?.[profile];
+        const envExclusiveOptIn = overrides?.envExclusiveOptIn;
+        const isDedicated = !envExclusiveOptIn || envExclusiveOptIn.environments.includes(environment);
+        if (isDedicated) {
+            dedicatedProfiles[profile] = getEffectiveProfileConfig(profile, config);
+            continue;
+        }
+        const fallbackProfile = envExclusiveOptIn.fallbackProfile;
+        if (!isValidWorkerProfile(fallbackProfile)) {
+            throw new Error(`Invalid envExclusiveOptIn.fallbackProfile "${fallbackProfile}" for profile "${profile}".`);
+        }
+        const taskQueue = getTaskQueueForProfile(profile);
+        const existingQueues = fallbackQueues[fallbackProfile] ?? [];
+        if (!existingQueues.includes(taskQueue)) {
+            existingQueues.push(taskQueue);
+        }
+        fallbackQueues[fallbackProfile] = existingQueues;
+        const sources = fallbackSources[fallbackProfile] ?? [];
+        sources.push(profile);
+        fallbackSources[fallbackProfile] = sources;
+    }
+    for (const fallbackProfile of Object.keys(fallbackQueues)) {
+        if (!dedicatedProfiles[fallbackProfile]) {
+            const sourceProfiles = fallbackSources[fallbackProfile]?.join(", ") ?? "unknown";
+            throw new Error(`Profiles [${sourceProfiles}] fall back to "${fallbackProfile}" in environment "${environment}", but "${fallbackProfile}" is not deployed as a dedicated profile.`);
+        }
+    }
+    return {
+        dedicatedProfiles,
+        fallbackQueues,
+    };
+}
+/**
+ * Resolves runtime configuration for a single activity worker process.
+ *
+ * Validates the given profile, resolves the environment topology, and returns
+ * the task queues this worker should listen on plus the profile-derived
+ * max concurrent activities.
+ */
+function resolveActivityWorkerRuntimeConfig(options) {
+    const { environment, workerProfile: rawProfile, config } = options;
+    if (!isValidWorkerProfile(rawProfile)) {
+        throw new Error(`Invalid worker profile: "${rawProfile}".`);
+    }
+    const workerProfile = rawProfile;
+    // Dedicated profiles are profiles that are deployed in the environment. They run activities
+    // from their own task queues. Fallback profiles are profiles that are not deployed in the environment.
+    // Activities that would normally go to that profile (i.e. heavy) are run on the fallback queue.
+    // i.e. In non-prod environments, heavy activities are run on the standard resource activity worker.
+    const { dedicatedProfiles, fallbackQueues } = resolveProfilesForEnvironment(environment, config);
+    const profileConfig = dedicatedProfiles[workerProfile];
+    if (!profileConfig) {
+        throw new Error(`Worker profile "${workerProfile}" is not configured as dedicated in environment "${environment}".`);
+    }
+    const primaryQueue = getTaskQueueForProfile(workerProfile);
+    const absorbedQueues = fallbackQueues[workerProfile] ?? [];
+    const taskQueues = [primaryQueue, ...absorbedQueues];
+    const maxConcurrentActivityTaskExecutions = profileConfig.resources.maxConcurrentActivities;
+    return {
+        workerProfile,
+        taskQueues,
+        maxConcurrentActivityTaskExecutions,
+    };
+}
+/**
+ * Convenience wrapper that loads build config from disk and then resolves
+ * activity worker runtime configuration.
+ */
+async function loadAndResolveActivityWorkerRuntimeConfig(options) {
+    const { environment, workerProfile, buildConfigDir } = options;
+    const { config } = await (0, loader_1.loadBuildConfig)(buildConfigDir ? { searchDir: buildConfigDir } : undefined);
+    return resolveActivityWorkerRuntimeConfig({
+        environment,
+        workerProfile,
+        config,
+    });
+}
+/**
+ * Loads build config and resolves combined worker configuration
+ * across all dedicated profiles for the given environment.
+ *
+ * Designed for local development where a single process handles all
+ * task queues. Collects every dedicated profile's primary queue
+ * plus any absorbed fallback queues, sums maxConcurrentActivities,
+ * and takes the max of maxConcurrentWorkflows across profiles
+ * (since there is only one workflow worker regardless of activity profiles).
+ */
+async function loadAndResolveCombinedWorkerConfigForLocalDev(options) {
+    const { environment, buildConfigDir } = options;
+    const { config } = await (0, loader_1.loadBuildConfig)(buildConfigDir ? { searchDir: buildConfigDir } : undefined);
+    const { dedicatedProfiles, fallbackQueues } = resolveProfilesForEnvironment(environment, config);
+    const taskQueues = [];
+    let maxConcurrentActivityTaskExecutions = 0;
+    let maxConcurrentWorkflowTaskExecutions = 0;
+    for (const profile of Object.keys(dedicatedProfiles)) {
+        const profileConfig = dedicatedProfiles[profile];
+        taskQueues.push(getTaskQueueForProfile(profile), ...(fallbackQueues[profile] ?? []));
+        maxConcurrentActivityTaskExecutions += profileConfig.resources.maxConcurrentActivities;
+        maxConcurrentWorkflowTaskExecutions = Math.max(maxConcurrentWorkflowTaskExecutions, profileConfig.resources.maxConcurrentWorkflows);
+    }
+    return { taskQueues, maxConcurrentActivityTaskExecutions, maxConcurrentWorkflowTaskExecutions };
+}
+//# sourceMappingURL=worker-profiles.js.map

package/dist/internal/async/config/worker-profiles.js.map

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

package/dist/internal/async/execute/temporal-client.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Temporal Client for Workflow Execution
+ *
+ * This module provides the client-side API for starting and managing
+ * Temporal workflows. Use this from your application code (API handlers,
+ * cron jobs, etc.) to initiate workflow executions.
+ *
+ * ## Usage:
+ *
+ * ```typescript
+ * import { executeWorkflow } from "@lotiai/composer/internal/async/execute/temporal-client";
+ *
+ * // Start a workflow
+ * const handle = await executeWorkflow({
+ *   workflowName: "api-prompt-025b323f",  // Versioned name from workflow-bundle
+ *   input: {
+ *     initialData: { promptText: "Hello" },
+ *     workflowId: "prompt-123",
+ *     correlationId: "req-456",
+ *   },
+ *   taskQueue: "workflow-tasks",
+ * });
+ *
+ * // Wait for result
+ * const result = await handle.result();
+ * ```
+ *
+ * @module temporal-client
+ */
+import type { WorkflowHandle } from "@temporalio/client";
+import { Client } from "@temporalio/client";
+import type { VersioningOverride } from "@temporalio/common";
+import type { UUIDV7 } from "../../types";
+import type { WorkflowInput } from "../build/workflow-factory";
+/**
+ * Configuration for connecting to Temporal Server.
+ */
+export interface TemporalClientConfig {
+    /**
+     * Temporal Server address
+     */
+    address: string;
+    /**
+     * Temporal namespace
+     */
+    namespace: string;
+}
+/**
+ * Options for starting a workflow execution.
+ */
+export interface ExecuteWorkflowOptions {
+    /**
+     * Workflow name (e.g., "api-prompt")
+     */
+    workflowName: string;
+    /**
+     * Unique workflow execution ID.
+     * Should be a meaningful business identifier or a generated UUID.
+     * This ID is used for idempotency and workflow reconnection.
+     */
+    workflowId: UUIDV7;
+    /**
+     * Input data for the workflow
+     */
+    input: WorkflowInput;
+    /**
+     * Task queue to execute workflow on
+     * @default "workflow-tasks"
+     */
+    taskQueue?: string;
+    /**
+     * Versioning override for Worker Versioning. When set, pins the workflow
+     * to a specific deployment version (buildId + deploymentName).
+     */
+    versioningOverride?: VersioningOverride;
+    /**
+     * Override Temporal client config for this execution
+     */
+    clientConfig: TemporalClientConfig;
+}
+/**
+ * Creates or returns a cached Temporal client connection.
+ * Caches the connection Promise (not the resolved client) so concurrent
+ * callers with the same config share a single in-flight connection attempt
+ * instead of racing and leaking extra gRPC connections.
+ *
+ * @param config - Client configuration
+ * @returns Temporal Client instance
+ */
+export declare function createTemporalClient(config: TemporalClientConfig): Promise<Client>;
+/**
+ * Starts a Temporal workflow execution.
+ *
+ * This is the primary function for executing workflows asynchronously.
+ * It returns a handle that can be used to query status, wait for results,
+ * cancel the workflow, etc.
+ *
+ * ## Example:
+ *
+ * ```typescript
+ * const handle = await executeWorkflow({
+ *   workflowName: "api-prompt-025b323f",
+ *   input: {
+ *     initialData: { promptText: "Hello", identitiesInput: [...] },
+ *     workflowId: "prompt-abc123",
+ *     correlationId: "req-xyz789",
+ *     environment: "production",
+ *   },
+ * });
+ *
+ * // Option 1: Fire and forget
+ * console.log(`Workflow started: ${handle.workflowId}`);
+ *
+ * // Option 2: Wait for result
+ * const result = await handle.result();
+ * console.log("Workflow completed:", result);
+ * ```
+ *
+ * @param options - Workflow execution options
+ * @returns WorkflowHandle for the started workflow
+ */
+export declare function executeWorkflow(options: ExecuteWorkflowOptions): Promise<WorkflowHandle<any>>;
+/**
+ * Gets a handle to an existing workflow execution.
+ *
+ * Use this to reconnect to a workflow that was started previously,
+ * allowing you to query its status, wait for completion, or send signals.
+ *
+ * @param workflowId - The workflow execution ID
+ * @param config - Optional client configuration
+ * @returns WorkflowHandle for the existing workflow
+ */
+export declare function getWorkflowHandle(workflowId: UUIDV7, config: TemporalClientConfig): Promise<WorkflowHandle<any>>;
+/**
+ * Executes a workflow and waits for its result.
+ *
+ * This is a convenience function that combines starting a workflow
+ * and waiting for its completion. Use this when you need the result
+ * synchronously (e.g., in an API handler that must return the result).
+ *
+ * **Warning:** This will block until the workflow completes, which could
+ * be seconds or minutes depending on the workflow. Consider using
+ * `executeWorkflow` with fire-and-forget for long-running workflows.
+ *
+ * @param options - Workflow execution options
+ * @returns The workflow result
+ */
+export declare function executeWorkflowAndWait<T = any>(options: ExecuteWorkflowOptions): Promise<T>;
+/**
+ * Cancels a running workflow execution.
+ *
+ * @param workflowId - The workflow execution ID
+ * @param config - Optional client configuration
+ */
+export declare function cancelWorkflow(workflowId: UUIDV7, config: TemporalClientConfig): Promise<void>;
+/**
+ * Queries a workflow's status without affecting its execution.
+ *
+ * **Note:** Workflow queries require the workflow to define query handlers.
+ * This is not currently implemented in our workflow-factory, but can be
+ * added in the future.
+ *
+ * @param workflowId - The workflow execution ID
+ * @param queryName - The query to execute
+ * @param config - Optional client configuration
+ * @returns The query result
+ */
+export declare function queryWorkflow<T = any>(workflowId: UUIDV7, queryName: string, config: TemporalClientConfig): Promise<T>;
+/**
+ * Sends a signal to a running workflow.
+ *
+ * **Note:** Workflow signals require the workflow to define signal handlers.
+ * This is not currently implemented in our workflow-factory, but can be
+ * added in the future for interactive workflows.
+ *
+ * @param workflowId - The workflow execution ID
+ * @param signalName - The signal to send
+ * @param data - Signal payload
+ * @param config - Optional client configuration
+ */
+export declare function signalWorkflow(workflowId: UUIDV7, signalName: string, data: any, config: TemporalClientConfig): Promise<void>;
+//# sourceMappingURL=temporal-client.d.ts.map

package/dist/internal/async/execute/temporal-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-client.d.ts","sourceRoot":"","sources":["../../../../src/internal/async/execute/temporal-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,MAAM,EAAc,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,EAAE,aAAa,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IAExC;;OAEG;IACH,YAAY,EAAE,oBAAoB,CAAC;CACpC;AAID;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BlF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAW9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAG9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,GAAG,GAAG,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,CAAC,CAAC,CAGjG;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,CAAC,GAAG,GAAG,EACzC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/internal/async/execute/temporal-client.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Temporal Client for Workflow Execution
+ *
+ * This module provides the client-side API for starting and managing
+ * Temporal workflows. Use this from your application code (API handlers,
+ * cron jobs, etc.) to initiate workflow executions.
+ *
+ * ## Usage:
+ *
+ * ```typescript
+ * import { executeWorkflow } from "@lotiai/composer/internal/async/execute/temporal-client";
+ *
+ * // Start a workflow
+ * const handle = await executeWorkflow({
+ *   workflowName: "api-prompt-025b323f",  // Versioned name from workflow-bundle
+ *   input: {
+ *     initialData: { promptText: "Hello" },
+ *     workflowId: "prompt-123",
+ *     correlationId: "req-456",
+ *   },
+ *   taskQueue: "workflow-tasks",
+ * });
+ *
+ * // Wait for result
+ * const result = await handle.result();
+ * ```
+ *
+ * @module temporal-client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTemporalClient = createTemporalClient;
+exports.executeWorkflow = executeWorkflow;
+exports.getWorkflowHandle = getWorkflowHandle;
+exports.executeWorkflowAndWait = executeWorkflowAndWait;
+exports.cancelWorkflow = cancelWorkflow;
+exports.queryWorkflow = queryWorkflow;
+exports.signalWorkflow = signalWorkflow;
+const client_1 = require("@temporalio/client");
+const cachedClients = new Map();
+/**
+ * Creates or returns a cached Temporal client connection.
+ * Caches the connection Promise (not the resolved client) so concurrent
+ * callers with the same config share a single in-flight connection attempt
+ * instead of racing and leaking extra gRPC connections.
+ *
+ * @param config - Client configuration
+ * @returns Temporal Client instance
+ */
+function createTemporalClient(config) {
+    const cacheKey = `${config.address}:${config.namespace}`;
+    const existing = cachedClients.get(cacheKey);
+    if (existing) {
+        return existing;
+    }
+    const clientPromise = (async () => {
+        const connection = await client_1.Connection.connect({
+            address: config.address,
+        });
+        // TODO: Add OpenTelemetry interceptor for trace context propagation
+        // Once @temporalio/interceptors-opentelemetry is installed, add:
+        // import { OpenTelemetryWorkflowClientCallsInterceptor } from "@temporalio/interceptors-opentelemetry";
+        // Then add to Client options: interceptors: { workflow: [() => new OpenTelemetryWorkflowClientCallsInterceptor()] }
+        return new client_1.Client({
+            connection,
+            namespace: config.namespace,
+        });
+    })();
+    cachedClients.set(cacheKey, clientPromise);
+    clientPromise.catch(() => {
+        cachedClients.delete(cacheKey);
+    });
+    return clientPromise;
+}
+/**
+ * Starts a Temporal workflow execution.
+ *
+ * This is the primary function for executing workflows asynchronously.
+ * It returns a handle that can be used to query status, wait for results,
+ * cancel the workflow, etc.
+ *
+ * ## Example:
+ *
+ * ```typescript
+ * const handle = await executeWorkflow({
+ *   workflowName: "api-prompt-025b323f",
+ *   input: {
+ *     initialData: { promptText: "Hello", identitiesInput: [...] },
+ *     workflowId: "prompt-abc123",
+ *     correlationId: "req-xyz789",
+ *     environment: "production",
+ *   },
+ * });
+ *
+ * // Option 1: Fire and forget
+ * console.log(`Workflow started: ${handle.workflowId}`);
+ *
+ * // Option 2: Wait for result
+ * const result = await handle.result();
+ * console.log("Workflow completed:", result);
+ * ```
+ *
+ * @param options - Workflow execution options
+ * @returns WorkflowHandle for the started workflow
+ */
+async function executeWorkflow(options) {
+    const client = await createTemporalClient(options.clientConfig);
+    const handle = await client.workflow.start(options.workflowName, {
+        taskQueue: options.taskQueue ?? "workflow-tasks",
+        workflowId: options.workflowId,
+        args: [options.input],
+        ...(options.versioningOverride ? { versioningOverride: options.versioningOverride } : {}),
+    });
+    return handle;
+}
+/**
+ * Gets a handle to an existing workflow execution.
+ *
+ * Use this to reconnect to a workflow that was started previously,
+ * allowing you to query its status, wait for completion, or send signals.
+ *
+ * @param workflowId - The workflow execution ID
+ * @param config - Optional client configuration
+ * @returns WorkflowHandle for the existing workflow
+ */
+async function getWorkflowHandle(workflowId, config) {
+    const client = await createTemporalClient(config);
+    return client.workflow.getHandle(workflowId);
+}
+/**
+ * Executes a workflow and waits for its result.
+ *
+ * This is a convenience function that combines starting a workflow
+ * and waiting for its completion. Use this when you need the result
+ * synchronously (e.g., in an API handler that must return the result).
+ *
+ * **Warning:** This will block until the workflow completes, which could
+ * be seconds or minutes depending on the workflow. Consider using
+ * `executeWorkflow` with fire-and-forget for long-running workflows.
+ *
+ * @param options - Workflow execution options
+ * @returns The workflow result
+ */
+async function executeWorkflowAndWait(options) {
+    const handle = await executeWorkflow(options);
+    return (await handle.result());
+}
+/**
+ * Cancels a running workflow execution.
+ *
+ * @param workflowId - The workflow execution ID
+ * @param config - Optional client configuration
+ */
+async function cancelWorkflow(workflowId, config) {
+    const handle = await getWorkflowHandle(workflowId, config);
+    await handle.cancel();
+}
+/**
+ * Queries a workflow's status without affecting its execution.
+ *
+ * **Note:** Workflow queries require the workflow to define query handlers.
+ * This is not currently implemented in our workflow-factory, but can be
+ * added in the future.
+ *
+ * @param workflowId - The workflow execution ID
+ * @param queryName - The query to execute
+ * @param config - Optional client configuration
+ * @returns The query result
+ */
+async function queryWorkflow(workflowId, queryName, config) {
+    const handle = await getWorkflowHandle(workflowId, config);
+    return await handle.query(queryName);
+}
+/**
+ * Sends a signal to a running workflow.
+ *
+ * **Note:** Workflow signals require the workflow to define signal handlers.
+ * This is not currently implemented in our workflow-factory, but can be
+ * added in the future for interactive workflows.
+ *
+ * @param workflowId - The workflow execution ID
+ * @param signalName - The signal to send
+ * @param data - Signal payload
+ * @param config - Optional client configuration
+ */
+async function signalWorkflow(workflowId, signalName, data, config) {
+    const handle = await getWorkflowHandle(workflowId, config);
+    await handle.signal(signalName, data);
+}
+//# sourceMappingURL=temporal-client.js.map

package/dist/internal/async/execute/temporal-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-client.js","sourceRoot":"","sources":["../../../../src/internal/async/execute/temporal-client.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;AAyEH,oDA+BC;AAiCD,0CAaC;AAYD,8CAMC;AAgBD,wDAGC;AAQD,wCAMC;AAcD,sCAOC;AAcD,wCAQC;AAjPD,+CAAwD;AA2DxD,MAAM,aAAa,GAAG,IAAI,GAAG,EAA2B,CAAC;AAEzD;;;;;;;;GAQG;AACH,SAAgB,oBAAoB,CAAC,MAA4B;IAC/D,MAAM,QAAQ,GAAG,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;IAEzD,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,KAAK,IAAI,EAAE;QAChC,MAAM,UAAU,GAAG,MAAM,mBAAU,CAAC,OAAO,CAAC;YAC1C,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC,CAAC;QAEH,oEAAoE;QACpE,iEAAiE;QACjE,wGAAwG;QACxG,oHAAoH;QAEpH,OAAO,IAAI,eAAM,CAAC;YAChB,UAAU;YACV,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;IACL,CAAC,CAAC,EAAE,CAAC;IAEL,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAE3C,aAAa,CAAC,KAAK,CAAC,GAAG,EAAE;QACvB,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACI,KAAK,UAAU,eAAe,CACnC,OAA+B;IAE/B,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAEhE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE;QAC/D,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,gBAAgB;QAChD,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;QACrB,GAAG,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1F,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;GASG;AACI,KAAK,UAAU,iBAAiB,CACrC,UAAkB,EAClB,MAA4B;IAE5B,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,sBAAsB,CAAU,OAA+B;IACnF,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,CAAM,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,cAAc,CAClC,UAAkB,EAClB,MAA4B;IAE5B,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC3D,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,aAAa,CACjC,UAAkB,EAClB,SAAiB,EACjB,MAA4B;IAE5B,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC3D,OAAO,MAAM,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,cAAc,CAClC,UAAkB,EAClB,UAAkB,EAClB,IAAS,EACT,MAA4B;IAE5B,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC3D,MAAM,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC"}