actoviq-agent-sdk 0.4.0 → 0.4.2

package/dist/src/workflow/workflowScriptRuntime.js

@@ -0,0 +1,655 @@
+/**
+ * WorkflowScriptRuntime — executes dynamic workflow JavaScript scripts
+ * in a sandboxed vm.Module with Host Bridge for agent()/parallel()/pipeline().
+ *
+ * The script VM has ZERO fs/net/process access. All external calls go
+ * through the Host Bridge via message-passing.
+ */
+import vm from 'node:vm';
+import { randomUUID } from 'node:crypto';
+// ═══════════════════════════════════════════════════════════════════
+//  StructuredOutput tool for schema enforcement (append mode)
+// ═══════════════════════════════════════════════════════════════════
+const STRUCTURED_OUTPUT_TOOL_NAME = 'StructuredOutput';
+function createStructuredOutputTool(schema) {
+    return {
+        kind: 'local',
+        name: STRUCTURED_OUTPUT_TOOL_NAME,
+        description: 'Return your final structured result. You MUST call this tool with your answer ' +
+            'when you have completed the task. All fields in the schema are required unless marked optional.',
+        inputSchema: {
+            parse: (input) => input,
+            _type: undefined,
+        },
+        inputJsonSchema: schema,
+        async execute(input) {
+            return JSON.stringify(input);
+        },
+        interruptBehavior: 'block',
+        isConcurrencySafe: () => true,
+    };
+}
+function validateAgainstSchema(data, schema) {
+    if (!schema.properties)
+        return { valid: true };
+    if (typeof data !== 'object' || data === null) {
+        return { valid: false, errors: ['Output must be a JSON object.'] };
+    }
+    const errors = [];
+    const props = schema.properties;
+    const required = schema.required ?? [];
+    const dataObj = data;
+    // Check required fields
+    for (const field of required) {
+        if (!(field in dataObj) || dataObj[field] === undefined) {
+            errors.push(`Missing required field: ${field}`);
+        }
+    }
+    // Type check known fields
+    for (const [key, propSchema] of Object.entries(props)) {
+        if (key in dataObj && dataObj[key] !== undefined) {
+            const type = propSchema.type;
+            const value = dataObj[key];
+            if (type === 'string' && typeof value !== 'string') {
+                errors.push(`Field "${key}" must be a string, got ${typeof value}`);
+            }
+            else if (type === 'number' && typeof value !== 'number') {
+                errors.push(`Field "${key}" must be a number, got ${typeof value}`);
+            }
+            else if (type === 'boolean' && typeof value !== 'boolean') {
+                errors.push(`Field "${key}" must be a boolean, got ${typeof value}`);
+            }
+            else if (type === 'array' && !Array.isArray(value)) {
+                errors.push(`Field "${key}" must be an array, got ${typeof value}`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors: errors.length > 0 ? errors : undefined };
+}
+function tryParseStructuredOutput(text) {
+    // Try to find JSON in the response (model may wrap it in text)
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (!jsonMatch)
+        return null;
+    try {
+        return { parsed: JSON.parse(jsonMatch[0]), json: jsonMatch[0] };
+    }
+    catch {
+        return null;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Cache key normalization
+// ═══════════════════════════════════════════════════════════════════
+function sortedJson(obj) {
+    if (obj === null || obj === undefined)
+        return String(obj);
+    if (typeof obj !== 'object')
+        return JSON.stringify(obj);
+    if (Array.isArray(obj))
+        return JSON.stringify(obj.map(sortedJson));
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        sorted[key] = obj[key];
+    }
+    return JSON.stringify(sorted);
+}
+function canonicalAgentKey(prompt, opts, phase) {
+    return `${prompt}|${sortedJson(opts)}|${phase ?? ''}`;
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Script syntax check
+// ═══════════════════════════════════════════════════════════════════
+const BANNED_GLOBALS = ['Date', 'Math.random', 'process', 'require', 'import', 'fs', 'net', 'child_process'];
+function validateScript(script) {
+    // Ban Date.now(), Math.random(), new Date() — break determinism for resume
+    if (/Date\.now\s*\(/.test(script)) {
+        throw new Error('Date.now() is not allowed in workflow scripts (breaks resume determinism).');
+    }
+    if (/Math\.random\s*\(/.test(script)) {
+        throw new Error('Math.random() is not allowed in workflow scripts (breaks resume determinism).');
+    }
+    if (/new\s+Date\s*\(/.test(script)) {
+        throw new Error('new Date() is not allowed in workflow scripts (breaks resume determinism).');
+    }
+    // Must have export const meta
+    if (!/export\s+const\s+meta\s*=/.test(script)) {
+        throw new Error('Workflow script must export const meta = { name, description, phases }.');
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Meta extraction
+// ═══════════════════════════════════════════════════════════════════
+function extractMeta(script) {
+    const metaMatch = script.match(/export\s+const\s+meta\s*=\s*(\{[\s\S]*?\});/);
+    if (!metaMatch) {
+        throw new Error('Could not extract meta from workflow script.');
+    }
+    // Validate pure literal (no variables, function calls, template strings)
+    const metaBlock = metaMatch[1];
+    if (/[a-zA-Z_$]\s*\(/.test(metaBlock.replace(/"([^"\\]|\\.)*"|'([^'\\]|\\.)*'/g, '').replace(/`[\s\S]*?`/g, ''))) {
+        throw new Error('Workflow meta must be a pure literal — no function calls or computed values.');
+    }
+    // Evaluate the meta object in a sandbox
+    try {
+        const sandbox = {};
+        vm.createContext(sandbox);
+        const metaObj = vm.runInContext(`(${metaBlock})`, sandbox);
+        if (!metaObj.name || !metaObj.description) {
+            throw new Error('Workflow meta must include name and description.');
+        }
+        return metaObj;
+    }
+    catch (err) {
+        if (err.message?.includes('name') || err.message?.includes('description'))
+            throw err;
+        throw new Error(`Failed to parse workflow meta: ${err.message}`);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Host Bridge
+// ═══════════════════════════════════════════════════════════════════
+class HostBridge {
+    agentQueue = [];
+    activeAgents = 0;
+    maxConcurrent;
+    totalAgents = 0;
+    maxTotal = 1000;
+    signal;
+    sdk;
+    cache;
+    resumeCompleted;
+    agentRecords;
+    onEvent;
+    runId;
+    // Budget tracking
+    budgetTotal;
+    totalSpentTokens = 0;
+    // Phase tracking
+    currentPhase = null;
+    phases = new Map();
+    phaseOrder = [];
+    _logMessages = [];
+    _errors = [];
+    constructor(options) {
+        this.sdk = options.sdk;
+        this.maxConcurrent = options.maxConcurrent ?? 16;
+        this.budgetTotal = options.budgetTotal ?? null;
+        this.signal = options.signal;
+        this.onEvent = options.onEvent;
+        this.runId = randomUUID();
+        this.agentRecords = [];
+        // Resume state
+        this.cache = options.resumeState?.cache ?? new Map();
+        this.resumeCompleted = options.resumeState?.completedAgentIds ?? new Set();
+        // Restore phases from resume
+        if (options.resumeState?.phases) {
+            for (const phase of options.resumeState.phases) {
+                this.phases.set(phase.title, phase);
+                this.phaseOrder.push(phase.title);
+            }
+        }
+    }
+    // ── Budget ─────────────────────────────────────────────────────
+    createBudget() {
+        return {
+            total: this.budgetTotal,
+            spent: () => this.totalSpentTokens,
+            remaining: () => {
+                if (this.budgetTotal === null)
+                    return Infinity;
+                return Math.max(0, this.budgetTotal - this.totalSpentTokens);
+            },
+        };
+    }
+    // ── Phase ──────────────────────────────────────────────────────
+    setPhase(title) {
+        this.currentPhase = title;
+        if (!this.phases.has(title)) {
+            const pp = {
+                title,
+                agentCount: 0,
+                completedCount: 0,
+                failedCount: 0,
+                totalTokens: 0,
+                startedAt: new Date().toISOString(),
+            };
+            this.phases.set(title, pp);
+            this.phaseOrder.push(title);
+        }
+        this.onEvent?.({
+            type: 'workflow.phase.start',
+            runId: this.runId,
+            phase: title,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    // ── Log ────────────────────────────────────────────────────────
+    log(message) {
+        this._logMessages.push(message);
+        this.onEvent?.({
+            type: 'workflow.log',
+            runId: this.runId,
+            message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    // ── Agent ──────────────────────────────────────────────────────
+    async agent(prompt, opts = {}) {
+        const phase = opts.phase ?? this.currentPhase ?? undefined;
+        const key = canonicalAgentKey(prompt, opts, phase);
+        // Cache hit?
+        const cached = this.cache.get(key);
+        if (cached) {
+            const record = {
+                id: randomUUID(),
+                prompt,
+                opts,
+                phase,
+                result: cached.result,
+                tokens: cached.tokens,
+                durationMs: cached.durationMs,
+                startedAt: cached.cachedAt,
+                completedAt: cached.cachedAt,
+                cached: true,
+            };
+            this.agentRecords.push(record);
+            if (phase) {
+                const pp = this.phases.get(phase);
+                if (pp) {
+                    pp.agentCount++;
+                    pp.completedCount++;
+                    if (cached.tokens)
+                        pp.totalTokens += cached.tokens.input + cached.tokens.output;
+                }
+            }
+            this.onEvent?.({
+                type: 'workflow.agent.start',
+                runId: this.runId,
+                agentId: record.id,
+                label: opts.label,
+                phase,
+                cached: true,
+                timestamp: new Date().toISOString(),
+            });
+            this.onEvent?.({
+                type: 'workflow.agent.done',
+                runId: this.runId,
+                agentId: record.id,
+                phase,
+                cached: true,
+                durationMs: cached.durationMs,
+                tokens: cached.tokens,
+                timestamp: new Date().toISOString(),
+            });
+            return cached.result;
+        }
+        // Check budget
+        if (this.budgetTotal !== null && this.totalSpentTokens >= this.budgetTotal) {
+            throw new Error('Budget exhausted — cannot spawn more agents.');
+        }
+        // Check total cap
+        if (this.totalAgents >= this.maxTotal) {
+            throw new Error('Agent cap reached (1000 total per run).');
+        }
+        // Wait for concurrency slot
+        while (this.activeAgents >= this.maxConcurrent) {
+            if (this.signal?.aborted)
+                throw new Error('Aborted.');
+            await delay(50);
+        }
+        this.activeAgents++;
+        this.totalAgents++;
+        const record = {
+            id: randomUUID(),
+            prompt,
+            opts,
+            phase,
+            startedAt: new Date().toISOString(),
+            cached: false,
+        };
+        this.agentRecords.push(record);
+        if (phase) {
+            const pp = this.phases.get(phase);
+            if (pp)
+                pp.agentCount++;
+        }
+        this.onEvent?.({
+            type: 'workflow.agent.start',
+            runId: this.runId,
+            agentId: record.id,
+            label: opts.label,
+            phase,
+            cached: false,
+            timestamp: record.startedAt,
+        });
+        try {
+            // Execute via SDK
+            const session = await this.sdk.createSession({
+                title: opts.label ?? `workflow-agent-${record.id.slice(0, 8)}`,
+            });
+            // Build tool list: user tools + optional StructuredOutput for schema enforcement
+            const userTools = opts.tools?.map((t) => this.sdk.getTool(t)).filter((t) => t !== undefined) ?? [];
+            const allTools = opts.schema
+                ? [...userTools, createStructuredOutputTool(opts.schema)]
+                : userTools;
+            const maxRetries = 3;
+            let lastResult;
+            let finalTokens;
+            let execResult = await session.send(prompt, {
+                systemPrompt: undefined,
+                model: opts.model,
+                tools: allTools.length > 0 ? allTools : undefined,
+                signal: this.signal,
+                permissionMode: 'acceptEdits',
+            });
+            finalTokens = (execResult.usage?.input_tokens != null && execResult.usage?.output_tokens != null)
+                ? { input: execResult.usage.input_tokens, output: execResult.usage.output_tokens }
+                : undefined;
+            if (!opts.schema) {
+                lastResult = execResult.text;
+            }
+            else {
+                // Schema enforcement with retry
+                let validated = false;
+                for (let attempt = 0; attempt < maxRetries && !validated; attempt++) {
+                    if (attempt > 0) {
+                        // Re-prompt on same session to fix output
+                        execResult = await session.send('Your previous output did not match the required schema. ' +
+                            'Please call the StructuredOutput tool with the correct format.', {
+                            systemPrompt: undefined,
+                            model: opts.model,
+                            tools: allTools.length > 0 ? allTools : undefined,
+                            signal: this.signal,
+                            permissionMode: 'acceptEdits',
+                        });
+                        const retryTokens = (execResult.usage?.input_tokens != null && execResult.usage?.output_tokens != null)
+                            ? { input: execResult.usage.input_tokens, output: execResult.usage.output_tokens }
+                            : undefined;
+                        if (retryTokens && finalTokens) {
+                            finalTokens.input += retryTokens.input;
+                            finalTokens.output += retryTokens.output;
+                        }
+                    }
+                    const parsed = tryParseStructuredOutput(execResult.text);
+                    if (parsed) {
+                        const validation = validateAgainstSchema(parsed.parsed, opts.schema);
+                        if (validation.valid) {
+                            lastResult = parsed.parsed;
+                            validated = true;
+                            break;
+                        }
+                        if (attempt < maxRetries - 1) {
+                            this.log(`Schema validation failed (attempt ${attempt + 1}): ${validation.errors?.join(', ')}`);
+                        }
+                    }
+                    else if (attempt < maxRetries - 1) {
+                        this.log(`No structured output found (attempt ${attempt + 1}), retrying...`);
+                    }
+                }
+                if (!validated) {
+                    lastResult = execResult.text; // Last attempt: return raw text
+                }
+            }
+            record.result = lastResult;
+            record.tokens = finalTokens;
+            record.completedAt = new Date().toISOString();
+            record.durationMs = new Date(record.completedAt).getTime() - new Date(record.startedAt).getTime();
+            // Cache
+            if (record.tokens) {
+                this.totalSpentTokens += record.tokens.input + record.tokens.output;
+            }
+            this.cache.set(key, {
+                key,
+                result: record.result,
+                tokens: record.tokens,
+                durationMs: record.durationMs ?? 0,
+                cachedAt: new Date().toISOString(),
+            });
+            if (phase && record.tokens) {
+                const pp = this.phases.get(phase);
+                if (pp) {
+                    pp.completedCount++;
+                    pp.totalTokens += record.tokens.input + record.tokens.output;
+                }
+            }
+            this.onEvent?.({
+                type: 'workflow.agent.done',
+                runId: this.runId,
+                agentId: record.id,
+                phase,
+                cached: false,
+                durationMs: record.durationMs,
+                tokens: record.tokens,
+                timestamp: record.completedAt,
+            });
+            return record.result;
+        }
+        catch (err) {
+            record.error = err.message;
+            record.completedAt = new Date().toISOString();
+            record.durationMs = new Date(record.completedAt).getTime() - new Date(record.startedAt).getTime();
+            if (phase) {
+                const pp = this.phases.get(phase);
+                if (pp)
+                    pp.failedCount++;
+            }
+            this._errors.push({ agentId: record.id, phase, error: err.message });
+            this.log(`Agent "${opts.label ?? record.id}" failed: ${err.message}`);
+            this.onEvent?.({
+                type: 'workflow.agent.done',
+                runId: this.runId,
+                agentId: record.id,
+                phase,
+                cached: false,
+                durationMs: record.durationMs,
+                error: err.message,
+                timestamp: record.completedAt,
+            });
+            throw err;
+        }
+        finally {
+            this.activeAgents = Math.max(0, this.activeAgents - 1);
+        }
+    }
+    // ── Parallel ───────────────────────────────────────────────────
+    async parallel(thunks) {
+        if (thunks.length > 4096) {
+            throw new Error('parallel() supports at most 4096 items.');
+        }
+        return Promise.all(thunks.map(async (thunk) => {
+            try {
+                return await thunk();
+            }
+            catch {
+                return null;
+            }
+        }));
+    }
+    // ── Pipeline ───────────────────────────────────────────────────
+    async pipeline(items, ...stages) {
+        if (items.length > 4096) {
+            throw new Error('pipeline() supports at most 4096 items.');
+        }
+        const results = new Array(items.length).fill(null);
+        const errors = [];
+        // Process each item through all stages independently (no barrier)
+        const itemPromises = items.map(async (item, index) => {
+            let current = null;
+            for (let si = 0; si < stages.length; si++) {
+                const stage = stages[si];
+                try {
+                    const result = await stage(current, item, index);
+                    if (result === null) {
+                        // Item skipped
+                        return null;
+                    }
+                    current = result;
+                }
+                catch (err) {
+                    errors.push({ itemIndex: index, stageIndex: si, error: err.message });
+                    this._errors.push({
+                        agentId: `pipeline-${index}-${si}`,
+                        error: err.message,
+                        itemIndex: index,
+                        stageIndex: si,
+                    });
+                    return null; // Item dropped, other items continue
+                }
+            }
+            results[index] = current;
+            return current;
+        });
+        await Promise.all(itemPromises);
+        // Auto-report failure stats
+        if (errors.length > 0) {
+            this.log(`${errors.length}/${items.length} items failed across pipeline stages.`);
+        }
+        return results;
+    }
+    // ── State snapshot for resume ──────────────────────────────────
+    getResumeState() {
+        return {
+            runId: this.runId,
+            cache: this.cache,
+            agentCallIds: this.agentRecords.map((r) => r.id),
+            completedAgentIds: new Set(this.agentRecords.filter((r) => r.completedAt).map((r) => r.id)),
+            phases: [...this.phases.values()],
+            errors: [...this._errors],
+        };
+    }
+    getRunState() {
+        return {
+            runId: this.runId,
+            meta: { name: '', description: '' },
+            status: 'running',
+            phases: [...this.phases.values()],
+            agentCalls: this.agentRecords,
+            errors: [...this._errors],
+            startedAt: '',
+            totalTokens: this.totalSpentTokens,
+            estimatedCost: null,
+        };
+    }
+    getLogMessages() {
+        return [...this._logMessages];
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Script Runtime
+// ═══════════════════════════════════════════════════════════════════
+export class WorkflowScriptRuntime {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async execute(script) {
+        // Validate
+        validateScript(script);
+        // Extract meta
+        const meta = extractMeta(script);
+        // Create Host Bridge
+        const bridge = new HostBridge(this.options);
+        // Build sandbox context
+        const sandbox = {
+            agent: (prompt, opts) => bridge.agent(prompt, opts),
+            parallel: (thunks) => bridge.parallel(thunks),
+            pipeline: (items, ...stages) => bridge.pipeline(items, ...stages),
+            phase: (title) => bridge.setPhase(title),
+            log: (message) => bridge.log(message),
+            budget: bridge.createBudget(),
+            args: this.options.args,
+            meta,
+        };
+        // Strip the `export const meta = ...` block and execute the script body
+        const body = script.replace(/export\s+const\s+meta\s*=\s*\{[\s\S]*?\};/, '').trim();
+        // Wrap in async IIFE (vm.runInContext doesn't support top-level await).
+        // Store the result in __sandbox__.__result so we can read it after execution.
+        const wrappedScript = [
+            `(async () => {`,
+            `const { agent, parallel, pipeline, phase, log, budget, args, meta } = __sandbox__;`,
+            body,
+            `}).call(null);`,
+        ].join('\n');
+        this.options.onEvent?.({
+            type: 'workflow.script.start',
+            runId: bridge.getRunState().runId,
+            workflowName: meta.name,
+            phases: meta.phases,
+            timestamp: new Date().toISOString(),
+        });
+        const startedAt = Date.now();
+        try {
+            // Execute in vm.Script (not vm.Module since we handle modules differently)
+            const vmContext = vm.createContext({
+                __sandbox__: sandbox,
+                console: {
+                    log: (...args) => bridge.log(args.map(String).join(' ')),
+                    error: (...args) => bridge.log(`[ERROR] ${args.map(String).join(' ')}`),
+                },
+                setTimeout: () => { throw new Error('setTimeout is not available in workflow scripts.'); },
+                setInterval: () => { throw new Error('setInterval is not available in workflow scripts.'); },
+                clearTimeout: () => { },
+                clearInterval: () => { },
+                process: undefined,
+                require: undefined,
+                import: undefined,
+                fs: undefined,
+                net: undefined,
+                child_process: undefined,
+            });
+            const result = await vm.runInContext(wrappedScript, vmContext, {
+                filename: `workflow-${meta.name}.js`,
+                timeout: 600_000, // 10 min max
+            });
+            const durationMs = Date.now() - startedAt;
+            const state = bridge.getRunState();
+            state.meta = meta;
+            state.startedAt = new Date(startedAt).toISOString();
+            state.completedAt = new Date().toISOString();
+            state.status = 'completed';
+            this.options.onEvent?.({
+                type: 'workflow.script.done',
+                runId: state.runId,
+                workflowName: meta.name,
+                status: 'completed',
+                durationMs,
+                agentCount: state.agentCalls.length,
+                totalTokens: state.totalTokens,
+                errors: state.errors.length > 0 ? state.errors : undefined,
+                timestamp: new Date().toISOString(),
+            });
+            return {
+                result,
+                state,
+                resumeState: bridge.getResumeState(),
+                logs: bridge.getLogMessages(),
+            };
+        }
+        catch (err) {
+            const durationMs = Date.now() - startedAt;
+            const state = bridge.getRunState();
+            state.meta = meta;
+            state.startedAt = new Date(startedAt).toISOString();
+            state.completedAt = new Date().toISOString();
+            state.status = 'failed';
+            state.errors.push({ agentId: 'script', error: err.message });
+            this.options.onEvent?.({
+                type: 'workflow.script.done',
+                runId: state.runId,
+                workflowName: meta.name,
+                status: 'failed',
+                durationMs,
+                agentCount: state.agentCalls.length,
+                totalTokens: state.totalTokens,
+                errors: state.errors,
+                timestamp: new Date().toISOString(),
+            });
+            throw err;
+        }
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=workflowScriptRuntime.js.map