@marktoflow/core 2.0.3 → 2.0.4-alpha.1

package/README.md

@@ -1,10 +1,10 @@
 # @marktoflow/core
 
-> Workflow engine for parsing, executing, and managing markdown-based automations.
+> AI workflow engine — parse, execute, and orchestrate markdown-based automations with tool calling, parallel execution, and structured output.
 
 [![npm](https://img.shields.io/npm/v/@marktoflow/core)](https://www.npmjs.com/package/@marktoflow/core)
 
-Part of [marktoflow](../../README.md) — open-source markdown workflow automation.
+Part of [marktoflow](https://github.com/marktoflow/marktoflow) — open-source AI workflow automation.
 
 ## Quick Start
 
@@ -26,17 +26,34 @@ const result = await engine.execute(workflow, {
 
 ## Features
 
-- **Workflow Parser** — Parse markdown + YAML workflow definitions
+- **Workflow Parser** — Parse markdown + YAML workflow definitions with Zod validation
 - **Execution Engine** — Step-by-step execution with retry, circuit breakers, and error handling
+- **Control Flow** — Conditionals (`if/else`), loops (`for-each`), `try/catch/finally`, `parallel` branches
+- **Parallel Execution** — `parallel.spawn` (multi-agent) and `parallel.map` (batch processing)
+- **Sub-Workflows** — Nested workflow execution with optional AI sub-agent mode
+- **Template Engine** — Nunjucks-based expressions with 50+ built-in filters
 - **State Management** — SQLite-based persistent state tracking
 - **Plugin System** — Extensible architecture with 17 hook types
-- **Cost Tracking** — Monitor and budget API usage per workflow
+- **Cost Tracking** — Monitor and budget API usage per workflow/step
+- **Agent Routing** — Capability-based agent selection with cost optimization and load balancing
 - **Scheduling** — Cron-based workflow scheduling
-- **Security** — RBAC, approval workflows, and audit logging
+- **Security** — RBAC, approval workflows, secret management (Vault, AWS, Azure, env), audit logging
 - **Queue System** — Distributed execution via Redis, RabbitMQ, or in-memory
 
 ## Usage
 
+### Control Flow
+
+```typescript
+// The engine handles conditionals, loops, parallel, and try/catch natively
+const workflow = await parser.parseWorkflow('complex-workflow.md');
+const result = await engine.execute(workflow);
+
+// Access step results
+console.log(result.output);
+console.log(result.stepResults);
+```
+
 ### State Management
 
 ```typescript
@@ -78,6 +95,42 @@ await registry.register({
 });
 ```
 
+### Agent Routing
+
+```typescript
+import { AgentRouter, AgentSelector, BudgetTracker } from '@marktoflow/core';
+
+const selector = new AgentSelector(agentProfiles, 'balanced');
+const budget = new BudgetTracker({ totalBudget: 10.0 });
+const router = new AgentRouter(selector, budget);
+
+const result = router.route({
+  requiredCapabilities: new Set(['tool_calling', 'streaming']),
+  maxCost: 0.05,
+});
+```
+
+## Architecture
+
+```
+@marktoflow/core
+├── engine/              # Workflow execution engine
+│   ├── control-flow     # if/else, for-each, parallel, try/catch
+│   ├── subworkflow      # Sub-workflow and AI sub-agent execution
+│   ├── variable-resolution  # Nunjucks template resolution
+│   ├── conditions       # Condition evaluation
+│   └── retry            # Retry with exponential backoff
+├── operations/          # 9 built-in operation modules
+├── filters/             # 9 Nunjucks filter modules (50+ filters)
+├── parser               # Markdown + YAML parser
+├── routing              # Agent selection and routing
+├── costs                # Cost tracking and budgeting
+├── state-manager        # SQLite-based state persistence
+├── sdk-registry         # Dynamic SDK loading and caching
+├── plugin-registry      # Plugin system with 17 hook types
+└── utils/               # Duration parsing, error handling
+```
+
 ## API Reference
 
 ```typescript
@@ -98,6 +151,16 @@ class StateManager {
   getWorkflowHistory(workflowId: string): Promise<WorkflowRun[]>;
   saveWorkflowState(state: WorkflowState): Promise<void>;
 }
+
+class AgentSelector {
+  select(context: RoutingContext): RoutingResult;
+  registerAgent(profile: AgentProfile): void;
+}
+
+class SDKRegistry {
+  registerTools(tools: Record<string, ToolConfig>): void;
+  load(name: string): Promise<unknown>;
+}
 ```
 
 ## Contributing
@@ -106,4 +169,4 @@ See the [contributing guide](https://github.com/marktoflow/marktoflow/blob/main/
 
 ## License
 
-Apache-2.0
+[AGPL-3.0](https://github.com/marktoflow/marktoflow/blob/main/LICENSE)

package/dist/built-in-operations.d.ts

@@ -1,134 +1,10 @@
 /**
  * Built-in Operations for marktoflow
  *
- * Provides common operations that eliminate the need for verbose script blocks:
- * - core.set: Simple variable assignment
- * - core.transform: Map/filter/reduce transformations
- * - core.extract: Nested path access
- * - core.format: Date/number/string formatting
- * - file.read: Read files with format conversion (docx, pdf, xlsx)
- * - file.write: Write files (text or binary)
+ * Thin dispatcher — all implementations live in ./operations/.
  */
 import { ExecutionContext } from './models.js';
-export interface SetOperationInputs {
-    [key: string]: unknown;
-}
-export interface TransformOperationInputs {
-    input: unknown[];
-    operation: 'map' | 'filter' | 'reduce' | 'find' | 'group_by' | 'unique' | 'sort';
-    expression?: string;
-    condition?: string;
-    initialValue?: unknown;
-    key?: string;
-    reverse?: boolean;
-}
-export interface ExtractOperationInputs {
-    input: unknown;
-    path: string;
-    default?: unknown;
-}
-export interface FormatOperationInputs {
-    value: unknown;
-    type: 'date' | 'number' | 'string' | 'currency' | 'json';
-    format?: string;
-    locale?: string;
-    currency?: string;
-    precision?: number;
-}
-/**
- * Set multiple variables at once with expression resolution.
- *
- * Example:
- * ```yaml
- * action: core.set
- * inputs:
- *   owner: "{{ inputs.repo =~ /^([^\/]+)\// }}"
- *   repo_name: "{{ inputs.repo =~ /\/(.+)$/ }}"
- *   timestamp: "{{ now() }}"
- * ```
- */
-export declare function executeSet(inputs: SetOperationInputs, context: ExecutionContext): Record<string, unknown>;
-/**
- * Transform arrays using common operations like map, filter, reduce.
- *
- * Examples:
- *
- * Map:
- * ```yaml
- * action: core.transform
- * inputs:
- *   input: "{{ oncall_response.data.oncalls }}"
- *   operation: map
- *   expression: "@{{ item.user.name }}"
- * ```
- *
- * Filter:
- * ```yaml
- * action: core.transform
- * inputs:
- *   input: "{{ issues }}"
- *   operation: filter
- *   condition: "item.priority == 'high'"
- * ```
- *
- * Reduce:
- * ```yaml
- * action: core.transform
- * inputs:
- *   input: "{{ numbers }}"
- *   operation: reduce
- *   expression: "{{ accumulator + item }}"
- *   initialValue: 0
- * ```
- */
-export declare function executeTransform(rawInputs: TransformOperationInputs, resolvedInputs: Record<string, unknown>, context: ExecutionContext): unknown;
-/**
- * Extract values from nested objects safely.
- *
- * Example:
- * ```yaml
- * action: core.extract
- * inputs:
- *   input: "{{ api_response }}"
- *   path: "data.users[0].email"
- *   default: "unknown@example.com"
- * ```
- */
-export declare function executeExtract(inputs: ExtractOperationInputs, context: ExecutionContext): unknown;
-/**
- * Format values for display (dates, numbers, strings, currency).
- *
- * Examples:
- *
- * Date:
- * ```yaml
- * action: core.format
- * inputs:
- *   value: "{{ now() }}"
- *   type: date
- *   format: "YYYY-MM-DD HH:mm:ss"
- * ```
- *
- * Number:
- * ```yaml
- * action: core.format
- * inputs:
- *   value: 1234.56
- *   type: number
- *   precision: 2
- * ```
- *
- * Currency:
- * ```yaml
- * action: core.format
- * inputs:
- *   value: 1234.56
- *   type: currency
- *   currency: USD
- *   locale: en-US
- * ```
- */
-export declare function executeFormat(inputs: FormatOperationInputs, context: ExecutionContext): string;
+export { executeSet, type SetOperationInputs, executeTransform, type TransformOperationInputs, executeExtract, type ExtractOperationInputs, executeFormat, type FormatOperationInputs, executeAggregate, executeCompare, executeRenameKeys, executeLimit, executeSortOperation, executeCrypto, executeDatetime, executeParse, executeCompress, executeDecompress, } from './operations/index.js';
 /**
  * Execute a built-in operation based on action name
  */
@@ -137,14 +13,4 @@ export declare function executeBuiltInOperation(action: string, rawInputs: Recor
  * Check if an action is a built-in operation
  */
 export declare function isBuiltInOperation(action: string): boolean;
-export declare function executeAggregate(inputs: Record<string, unknown>, _context: ExecutionContext): unknown;
-export declare function executeCompare(inputs: Record<string, unknown>, _context: ExecutionContext): unknown;
-export declare function executeRenameKeys(inputs: Record<string, unknown>): unknown;
-export declare function executeLimit(inputs: Record<string, unknown>): unknown;
-export declare function executeSortOperation(inputs: Record<string, unknown>): unknown;
-export declare function executeCrypto(inputs: Record<string, unknown>): unknown;
-export declare function executeDatetime(inputs: Record<string, unknown>): unknown;
-export declare function executeParse(inputs: Record<string, unknown>): unknown;
-export declare function executeCompress(inputs: Record<string, unknown>): unknown;
-export declare function executeDecompress(inputs: Record<string, unknown>): unknown;
 //# sourceMappingURL=built-in-operations.d.ts.map

package/dist/built-in-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"built-in-operations.d.ts","sourceRoot":"","sources":["../src/built-in-operations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"built-in-operations.d.ts","sourceRoot":"","sources":["../src/built-in-operations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAM/C,OAAO,EACL,UAAU,EACV,KAAK,kBAAkB,EACvB,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,cAAc,EACd,KAAK,sBAAsB,EAC3B,aAAa,EACb,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,eAAe,EACf,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAsB/B;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,EAAE,gBAAgB,GACxB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAuC5B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAQ1D"}