@salesforce/magen-mcp-workflow 0.0.1

package/dist/checkpointing/workflowStateManager.js

@@ -0,0 +1,206 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import * as path from 'path';
+import { MemorySaver } from '@langchain/langgraph';
+import { createComponentLogger } from '../logging/logger.js';
+import { JsonCheckpointSaver } from './jsonCheckpointer.js';
+import { WellKnownDirectoryManager, WELL_KNOWN_FILES } from '../storage/wellKnownDirectory.js';
+import { NodeFileSystemOperations } from '../common/fileSystem.js';
+/**
+ * Manages workflow state persistence and checkpointer lifecycle
+ *
+ * This service encapsulates all workflow state management responsibilities:
+ * - Creating and configuring checkpointers (MemorySaver vs JsonCheckpointSaver)
+ * - Loading existing state from disk
+ * - Saving state to disk
+ * - Managing well-known directory paths
+ *
+ * This separation allows the orchestrator to focus on workflow execution logic
+ * while delegating all state management concerns to this service.
+ */
+export class WorkflowStateManager {
+    logger;
+    environment;
+    wellKnownDirectoryManager;
+    fileSystemOperations;
+    constructor(config = {}) {
+        this.logger = config.logger || createComponentLogger('WorkflowStateManager');
+        this.environment = config.environment || 'production';
+        this.fileSystemOperations = config.fileSystemOperations ?? new NodeFileSystemOperations();
+        this.wellKnownDirectoryManager = new WellKnownDirectoryManager({
+            projectPath: config.projectPath,
+            fileSystemOperations: this.fileSystemOperations,
+        });
+    }
+    /**
+     * Creates a checkpointer configured for the current environment
+     *
+     * For 'test' environment:
+     * - Returns MemorySaver (in-memory, no file I/O)
+     *
+     * For 'production' environment:
+     * - Returns JsonCheckpointSaver
+     * - Automatically loads existing state from disk if available
+     * - Creates fresh checkpointer if no state exists
+     *
+     * @returns A configured checkpointer ready for use
+     */
+    async createCheckpointer() {
+        if (this.environment === 'test') {
+            this.logger.debug('Creating MemorySaver for test environment');
+            return new MemorySaver();
+        }
+        // Production environment: Use JsonCheckpointSaver with state persistence
+        this.logger.debug('Creating JsonCheckpointSaver for production environment');
+        const checkpointer = new JsonCheckpointSaver();
+        // Load existing state if available
+        const serializedState = await this.readState();
+        if (serializedState) {
+            this.logger.info('Importing existing checkpointer state from disk');
+            await checkpointer.importState(serializedState);
+        }
+        else {
+            this.logger.info('No existing state found, starting with fresh checkpointer');
+        }
+        return checkpointer;
+    }
+    /**
+     * Saves checkpointer state to disk (production mode only)
+     *
+     * Only applies to JsonCheckpointSaver. MemorySaver (used in test mode)
+     * intentionally does not persist state.
+     *
+     * @param checkpointer - The checkpointer to save
+     * @throws Error if test environment unexpectedly has JsonCheckpointSaver
+     */
+    async saveCheckpointerState(checkpointer) {
+        // Skip persistence for test environment (uses MemorySaver)
+        if (this.environment === 'test') {
+            // Sanity check: test environment should never have JsonCheckpointSaver
+            if (checkpointer instanceof JsonCheckpointSaver) {
+                throw new Error('Invalid state: test environment should use MemorySaver, not JsonCheckpointSaver');
+            }
+            this.logger.debug('Skipping state persistence in test environment');
+            return;
+        }
+        // Production environment: persist JsonCheckpointSaver state
+        if (!(checkpointer instanceof JsonCheckpointSaver)) {
+            this.logger.warn('Checkpointer is not JsonCheckpointSaver in production environment, skipping persistence');
+            return;
+        }
+        const exportedState = await checkpointer.exportState();
+        await this.writeState(exportedState);
+        this.logger.info('Checkpointer state successfully persisted to disk');
+    }
+    /**
+     * Reads the serialized state from disk if it exists
+     * @returns The serialized state string, or undefined if the file doesn't exist or is invalid
+     */
+    async readState() {
+        const storePath = this.getStatePath();
+        try {
+            // Check if the file exists
+            await this.fileSystemOperations.access(storePath);
+            this.logger.info(`Reading checkpointer state from: ${storePath}`);
+            // Read the file content
+            const content = await this.fileSystemOperations.readFile(storePath, 'utf-8');
+            // Validate that it's valid JSON
+            JSON.parse(content);
+            this.logger.debug('Successfully read and validated checkpointer state', {
+                stateSize: content.length,
+                path: storePath,
+            });
+            return content;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                this.logger.info(`Checkpointer state file not found: ${storePath}. Starting with fresh state.`);
+                return undefined;
+            }
+            else if (error instanceof SyntaxError) {
+                this.logger.warn(`Invalid JSON in state file: ${storePath}. Starting with fresh state.`, error);
+                return undefined;
+            }
+            else {
+                this.logger.error(`Failed to read checkpointer state from: ${storePath}`, error);
+                return undefined;
+            }
+        }
+    }
+    /**
+     * Writes the serialized state to disk
+     * @param serializedState The state to persist
+     */
+    async writeState(serializedState) {
+        const storePath = this.getStatePath();
+        try {
+            // Ensure the directory exists
+            const storeDir = path.dirname(storePath);
+            await this.fileSystemOperations.mkdir(storeDir, { recursive: true });
+            // Validate that the state is valid JSON before writing
+            JSON.parse(serializedState);
+            this.logger.info(`Saving checkpointer state to: ${storePath}`);
+            // Write the state to a temporary file first, then rename for atomicity
+            const tempPath = `${storePath}.tmp`;
+            await this.fileSystemOperations.writeFile(tempPath, serializedState, 'utf-8');
+            await this.fileSystemOperations.rename(tempPath, storePath);
+            this.logger.debug('Successfully saved checkpointer state', {
+                stateSize: serializedState.length,
+                path: storePath,
+            });
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                this.logger.error(`Invalid JSON state provided for persistence. State not saved.`, error);
+                throw new Error(`Invalid serialized state: ${error.message}`);
+            }
+            else {
+                this.logger.error(`Failed to save checkpointer state to: ${storePath}`, error);
+                throw error;
+            }
+        }
+    }
+    /**
+     * Deletes the persisted state file
+     */
+    async clearState() {
+        const storePath = this.getStatePath();
+        try {
+            await this.fileSystemOperations.unlink(storePath);
+            this.logger.info(`Cleared checkpointer state file: ${storePath}`);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                this.logger.debug(`State file already doesn't exist: ${storePath}`);
+            }
+            else {
+                this.logger.error(`Failed to clear state file: ${storePath}`, error);
+                throw error;
+            }
+        }
+    }
+    /**
+     * Checks if a persisted state file exists
+     */
+    async stateExists() {
+        const storePath = this.getStatePath();
+        try {
+            const stat = await this.fileSystemOperations.stat(storePath);
+            return stat.isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Gets the file path for workflow state storage
+     */
+    getStatePath() {
+        return this.wellKnownDirectoryManager.getWellKnownFilePath(WELL_KNOWN_FILES.WORKFLOW_STATE_STORE_FILENAME);
+    }
+}
+//# sourceMappingURL=workflowStateManager.js.map

package/dist/checkpointing/workflowStateManager.js.map

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

package/dist/common/fileSystem.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Filesystem Operations Abstraction
+ *
+ * Provides a dependency injection interface for filesystem operations,
+ * enabling testability and flexibility across the workflow engine.
+ */
+import fs from 'fs';
+/**
+ * Interface for filesystem operations - enables dependency injection for testing
+ * and alternative filesystem implementations
+ *
+ * Provides both synchronous and asynchronous methods to support different use cases:
+ * - Sync methods: For simple, fast operations where blocking is acceptable
+ * - Async methods: For I/O-intensive operations requiring non-blocking behavior
+ */
+export interface FileSystemOperations {
+    /**
+     * Check if a path exists in the filesystem (sync)
+     * @param path Path to check
+     * @returns true if the path exists, false otherwise
+     */
+    existsSync(path: string): boolean;
+    /**
+     * Create a directory (and any necessary parent directories) (sync)
+     * @param path Directory path to create
+     * @param options Options for directory creation (e.g., recursive, mode)
+     */
+    mkdirSync(path: string, options?: fs.MakeDirectoryOptions): void;
+    /**
+     * Create a temporary directory with a given prefix (sync)
+     * @param prefix Prefix for the temp directory name
+     * @returns Full path to the created directory
+     */
+    mkdtempSync(prefix: string): string;
+    /**
+     * Remove a file or directory (sync)
+     * @param path Path to remove
+     * @param options Options for removal (recursive, force, etc.)
+     */
+    rmSync(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): void;
+    /**
+     * Get the OS temp directory path (sync)
+     * @returns Path to the OS temp directory
+     */
+    tmpdir(): string;
+    /**
+     * Check if a path exists and is accessible (async)
+     * @param path Path to check
+     * @throws Error if path doesn't exist or isn't accessible
+     */
+    access(path: string): Promise<void>;
+    /**
+     * Read file contents as string (async)
+     * @param path File path to read
+     * @param encoding Character encoding (e.g., 'utf-8')
+     * @returns File contents as string
+     */
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    /**
+     * Write string data to file (async)
+     * @param path File path to write
+     * @param data String data to write
+     * @param encoding Character encoding (e.g., 'utf-8')
+     */
+    writeFile(path: string, data: string, encoding: BufferEncoding): Promise<void>;
+    /**
+     * Rename/move a file atomically (async)
+     * @param oldPath Current file path
+     * @param newPath New file path
+     */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Delete a file (async)
+     * @param path File path to delete
+     */
+    unlink(path: string): Promise<void>;
+    /**
+     * Create a directory (and any necessary parent directories) (async)
+     * @param path Directory path to create
+     * @param options Options for directory creation (e.g., recursive, mode)
+     */
+    mkdir(path: string, options?: fs.MakeDirectoryOptions): Promise<void>;
+    /**
+     * Get file/directory statistics (async)
+     * @param path Path to stat
+     * @returns File statistics
+     */
+    stat(path: string): Promise<fs.Stats>;
+}
+/**
+ * Production implementation of FileSystemOperations using Node.js fs module
+ * Wraps both sync and async Node.js filesystem operations
+ */
+export declare class NodeFileSystemOperations implements FileSystemOperations {
+    existsSync(path: string): boolean;
+    mkdirSync(path: string, options?: fs.MakeDirectoryOptions): void;
+    mkdtempSync(prefix: string): string;
+    rmSync(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): void;
+    tmpdir(): string;
+    access(path: string): Promise<void>;
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    writeFile(path: string, data: string, encoding: BufferEncoding): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    mkdir(path: string, options?: fs.MakeDirectoryOptions): Promise<void>;
+    stat(path: string): Promise<fs.Stats>;
+}

package/dist/common/fileSystem.js

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+/**
+ * Filesystem Operations Abstraction
+ *
+ * Provides a dependency injection interface for filesystem operations,
+ * enabling testability and flexibility across the workflow engine.
+ */
+import fs from 'fs';
+import fsPromises from 'fs/promises';
+import os from 'os';
+/**
+ * Production implementation of FileSystemOperations using Node.js fs module
+ * Wraps both sync and async Node.js filesystem operations
+ */
+/* c8 ignore start */
+export class NodeFileSystemOperations {
+    // Synchronous operations
+    existsSync(path) {
+        return fs.existsSync(path);
+    }
+    mkdirSync(path, options) {
+        fs.mkdirSync(path, options);
+    }
+    mkdtempSync(prefix) {
+        return fs.mkdtempSync(prefix);
+    }
+    rmSync(path, options) {
+        fs.rmSync(path, options);
+    }
+    tmpdir() {
+        return os.tmpdir();
+    }
+    // Asynchronous operations
+    async access(path) {
+        return fsPromises.access(path);
+    }
+    async readFile(path, encoding) {
+        return fsPromises.readFile(path, encoding);
+    }
+    async writeFile(path, data, encoding) {
+        return fsPromises.writeFile(path, data, encoding);
+    }
+    async rename(oldPath, newPath) {
+        return fsPromises.rename(oldPath, newPath);
+    }
+    async unlink(path) {
+        return fsPromises.unlink(path);
+    }
+    async mkdir(path, options) {
+        await fsPromises.mkdir(path, options);
+    }
+    async stat(path) {
+        return fsPromises.stat(path);
+    }
+}
+/* c8 ignore stop */
+//# sourceMappingURL=fileSystem.js.map

package/dist/common/fileSystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileSystem.js","sourceRoot":"","sources":["../../src/common/fileSystem.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,UAAU,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,IAAI,CAAC;AAkGpB;;;GAGG;AACH,qBAAqB;AACrB,MAAM,OAAO,wBAAwB;IACnC,yBAAyB;IACzB,UAAU,CAAC,IAAY;QACrB,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,OAAiC;QACvD,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,WAAW,CAAC,MAAc;QACxB,OAAO,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,CAAC,IAAY,EAAE,OAAkD;QACrE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC;IACrB,CAAC;IAED,0BAA0B;IAC1B,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,QAAwB;QACnD,OAAO,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,IAAY,EAAE,QAAwB;QAClE,OAAO,UAAU,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAe,EAAE,OAAe;QAC3C,OAAO,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY,EAAE,OAAiC;QACzD,MAAM,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF;AACD,oBAAoB"}

package/dist/common/metadata.d.ts

@@ -0,0 +1,93 @@
+import z from 'zod';
+/**
+ * Workflow state data schema for round-tripping session identity
+ * This lightweight object maintains workflow session continuity across stateless MCP tool invocations
+ */
+export declare const WORKFLOW_STATE_DATA_SCHEMA: z.ZodObject<{
+    thread_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    thread_id: string;
+}, {
+    thread_id: string;
+}>;
+export type WorkflowStateData = z.infer<typeof WORKFLOW_STATE_DATA_SCHEMA>;
+/**
+ * Workflow property names - single source of truth for property naming
+ */
+export declare const WORKFLOW_PROPERTY_NAMES: {
+    readonly workflowStateData: "workflowStateData";
+    readonly userInput: "userInput";
+};
+/**
+ * Base input schema for workflow-aware tools
+ * All tools participating in workflow orchestration should extend this schema
+ */
+export declare const WORKFLOW_TOOL_BASE_INPUT_SCHEMA: z.ZodObject<{
+    workflowStateData: z.ZodObject<{
+        thread_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        thread_id: string;
+    }, {
+        thread_id: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    workflowStateData: {
+        thread_id: string;
+    };
+}, {
+    workflowStateData: {
+        thread_id: string;
+    };
+}>;
+/**
+ * MCP tool invocation data structure used in LangGraph interrupts
+ * Contains all information needed for the orchestrator to create tool invocation instructions
+ *
+ * @template TWorkflowInputSchema - The full workflow input schema (includes workflowStateData)
+ */
+export interface MCPToolInvocationData<TWorkflowInputSchema extends z.ZodObject<z.ZodRawShape>> {
+    /** Metadata about the tool to invoke */
+    llmMetadata: {
+        name: string;
+        description: string;
+        inputSchema: TWorkflowInputSchema;
+    };
+    /** Input parameters for the tool invocation - typed to business logic schema only */
+    input: Omit<z.infer<TWorkflowInputSchema>, 'workflowStateData'>;
+}
+/**
+ * Standard output schema for all workflow MCP tools
+ */
+export declare const MCP_WORKFLOW_TOOL_OUTPUT_SCHEMA: z.ZodObject<{
+    promptForLLM: z.ZodString;
+    resultSchema: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    promptForLLM: string;
+    resultSchema: string;
+}, {
+    promptForLLM: string;
+    resultSchema: string;
+}>;
+export type MCPWorkflowToolOutput = z.infer<typeof MCP_WORKFLOW_TOOL_OUTPUT_SCHEMA>;
+/**
+ * Base tool metadata interface - defines the general structure for tool information
+ */
+export interface ToolMetadata<TInputSchema extends z.ZodObject<z.ZodRawShape>, TOutputSchema extends z.ZodObject<z.ZodRawShape>> {
+    /** Unique tool identifier used for MCP registration and workflow orchestration */
+    readonly toolId: string;
+    /** Extended tool title for detailed display */
+    readonly title: string;
+    /** Tool description for documentation and LLM context */
+    readonly description: string;
+    /** Zod input schema for validation */
+    readonly inputSchema: TInputSchema;
+    /** Zod output schema for validation */
+    readonly outputSchema: TOutputSchema;
+}
+/**
+ * Workflow tool metadata interface - defines the structure for workflow tool information
+ */
+export interface WorkflowToolMetadata<TInputSchema extends typeof WORKFLOW_TOOL_BASE_INPUT_SCHEMA, TResultSchema extends z.ZodObject<z.ZodRawShape>, TOutputSchema extends typeof MCP_WORKFLOW_TOOL_OUTPUT_SCHEMA = typeof MCP_WORKFLOW_TOOL_OUTPUT_SCHEMA> extends ToolMetadata<TInputSchema, TOutputSchema> {
+    /** Holds the shape of the expected result for guidance-based tools */
+    readonly resultSchema: TResultSchema;
+}

package/dist/common/metadata.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import z from 'zod';
+/**
+ * Workflow state data schema for round-tripping session identity
+ * This lightweight object maintains workflow session continuity across stateless MCP tool invocations
+ */
+export const WORKFLOW_STATE_DATA_SCHEMA = z.object({
+    thread_id: z.string().describe('Unique identifier for the workflow session'),
+});
+/**
+ * Workflow property names - single source of truth for property naming
+ */
+export const WORKFLOW_PROPERTY_NAMES = {
+    workflowStateData: 'workflowStateData',
+    userInput: 'userInput',
+};
+/**
+ * Base input schema for workflow-aware tools
+ * All tools participating in workflow orchestration should extend this schema
+ */
+export const WORKFLOW_TOOL_BASE_INPUT_SCHEMA = z.object({
+    [WORKFLOW_PROPERTY_NAMES.workflowStateData]: WORKFLOW_STATE_DATA_SCHEMA.describe('Workflow session state for continuation. Required for all workflow-aware tools, but optional for the orchestrator tool, because it can also start new workflows.'),
+});
+/**
+ * Standard output schema for all workflow MCP tools
+ */
+export const MCP_WORKFLOW_TOOL_OUTPUT_SCHEMA = z.object({
+    promptForLLM: z
+        .string()
+        .describe('Complete prompt with instructions and post-processing guidance'),
+    resultSchema: z
+        .string()
+        .describe("The string-serialized JSON schema of the expected result from the LLM's task"),
+});
+//# sourceMappingURL=metadata.js.map

package/dist/common/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/common/metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;CAC7E,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,iBAAiB,EAAE,mBAAmB;IACtC,SAAS,EAAE,WAAW;CACd,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAC9E,kKAAkK,CACnK;CACF,CAAC,CAAC;AAmBH;;GAEG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,QAAQ,CAAC,gEAAgE,CAAC;IAC7E,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,QAAQ,CAAC,8EAA8E,CAAC;CAC5F,CAAC,CAAC"}

package/dist/common/propertyMetadata.d.ts

@@ -0,0 +1,58 @@
+import z from 'zod';
+/**
+ * Metadata definition for a property that can be extracted from user input.
+ *
+ * This type provides a generalized structure for defining properties that need to be
+ * collected from users, either through extraction from natural language or explicit prompting.
+ *
+ * @template T - The Zod schema type for this property
+ *
+ * @property zodType - Zod schema used for validation and type inference
+ * @property description - Detailed description used by LLMs to identify the property in user input
+ * @property friendlyName - Human-readable name for display and prompting
+ *
+ * @example
+ * const platformProperty: PropertyMetadata<typeof PLATFORM_ENUM> = {
+ *   zodType: PLATFORM_ENUM,
+ *   description: 'Target mobile platform for the mobile app (iOS or Android)',
+ *   friendlyName: 'mobile platform',
+ * };
+ */
+export interface PropertyMetadata<T extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** Zod schema for validation and type inference */
+    readonly zodType: T;
+    /** Detailed description for LLM-based extraction */
+    readonly description: string;
+    /** Human-readable name for display */
+    readonly friendlyName: string;
+}
+/**
+ * Collection of properties with their metadata.
+ * Used to define a set of related properties that can be extracted together.
+ *
+ * @example
+ * const myProperties: PropertyMetadataCollection = {
+ *   platform: {
+ *     zodType: z.enum(['iOS', 'Android']),
+ *     description: 'Target mobile platform',
+ *     friendlyName: 'platform',
+ *   },
+ *   projectName: {
+ *     zodType: z.string(),
+ *     description: 'Name of the project',
+ *     friendlyName: 'project name',
+ *   },
+ * };
+ */
+export type PropertyMetadataCollection = Record<string, PropertyMetadata>;
+/**
+ * Extracts the inferred TypeScript types from a PropertyMetadataCollection.
+ * Useful for creating type-safe objects that match the property definitions.
+ *
+ * @example
+ * type MyProps = InferPropertyTypes<typeof myProperties>;
+ * // Results in: { platform: 'iOS' | 'Android', projectName: string }
+ */
+export type InferPropertyTypes<T extends PropertyMetadataCollection> = {
+    [K in keyof T]: z.infer<T[K]['zodType']>;
+};

package/dist/common/propertyMetadata.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+export {};
+//# sourceMappingURL=propertyMetadata.js.map

package/dist/common/propertyMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propertyMetadata.js","sourceRoot":"","sources":["../../src/common/propertyMetadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/common/types.d.ts

@@ -0,0 +1,16 @@
+import { StateType, StateDefinition } from '@langchain/langgraph';
+/**
+ * Describes the result of checking if a property is fulfilled.
+ *
+ * @property isFulfilled - Boolean indicating if the property is fulfilled.
+ * @property reason - Optional string explaining why the property is not fulfilled.
+ */
+export type PropertyFulfilledResult = {
+    isFulfilled: boolean;
+    reason?: string;
+};
+/**
+ * Function signature for checking if a property is fulfilled in the state.
+ * It can return a boolean or a PropertyFulfilledResult for more detailed feedback.
+ */
+export type IsPropertyFulfilled<TState extends StateType<StateDefinition>> = (state: TState, propertyName: string) => PropertyFulfilledResult;

package/dist/common/types.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/common/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { type FileSystemOperations, NodeFileSystemOperations } from './common/fileSystem.js';
+export { WELL_KNOWN_DIR_NAME, WELL_KNOWN_FILES, type WellKnownDirectoryConfig, WellKnownDirectoryManager, } from './storage/wellKnownDirectory.js';
+export { Logger, PinoLogger, createLogger, createComponentLogger, createWorkflowLogger, } from './logging/logger.js';
+export { WORKFLOW_STATE_DATA_SCHEMA, WORKFLOW_PROPERTY_NAMES, WORKFLOW_TOOL_BASE_INPUT_SCHEMA, MCP_WORKFLOW_TOOL_OUTPUT_SCHEMA, type WorkflowStateData, type MCPToolInvocationData, type MCPWorkflowToolOutput, type ToolMetadata, type WorkflowToolMetadata, } from './common/metadata.js';
+export { type PropertyMetadata, type PropertyMetadataCollection, type InferPropertyTypes, } from './common/propertyMetadata.js';
+export { type PropertyFulfilledResult, type IsPropertyFulfilled } from './common/types.js';
+export { type ToolExecutor, LangGraphToolExecutor } from './nodes/toolExecutor.js';
+export { executeToolWithLogging } from './utils/toolExecutionUtils.js';
+export { AbstractTool, AbstractWorkflowTool } from './tools/base/index.js';
+export { GetInputTool, createGetInputTool, createGetInputMetadata, type GetInputToolOptions, type GetInputToolMetadata, type GetInputWorkflowInput, GET_INPUT_PROPERTY_SCHEMA, GET_INPUT_WORKFLOW_INPUT_SCHEMA, GET_INPUT_WORKFLOW_RESULT_SCHEMA, InputExtractionTool, createInputExtractionTool, createInputExtractionMetadata, type InputExtractionToolOptions, type InputExtractionToolMetadata, type InputExtractionWorkflowInput, INPUT_EXTRACTION_WORKFLOW_INPUT_SCHEMA, INPUT_EXTRACTION_WORKFLOW_RESULT_SCHEMA, } from './tools/utilities/index.js';
+export { BaseNode, AbstractToolNode, createGetUserInputNode, createUserInputExtractionNode, type GetUserInputNodeOptions, type UserInputExtractionNodeOptions, } from './nodes/index.js';
+export { CheckPropertiesFulfilledRouter } from './routers/index.js';
+export { AbstractService } from './services/index.js';
+export { JsonCheckpointSaver, WorkflowStatePersistence, WorkflowStateManager, type WorkflowStateManagerConfig, type WorkflowEnvironment, } from './checkpointing/index.js';
+export { OrchestratorTool, createOrchestratorToolMetadata, type OrchestratorConfig, type OrchestratorInput, type OrchestratorOutput, type OrchestratorToolMetadata, ORCHESTRATOR_INPUT_SCHEMA, ORCHESTRATOR_OUTPUT_SCHEMA, } from './tools/orchestrator/index.js';