@vertesia/common 1.5.0-dev.20260722.120446Z → 1.5.0-dev.20260804.124748Z

package/src/store/process-schema.test.ts

@@ -69,6 +69,49 @@ describe('process definition JSON schema', () => {
         expect(validate(validDefinition())).toBe(true);
     });
 
+    it('accepts inline script sources and script nodes', () => {
+        const validate = new Ajv.default({ allErrors: true, strict: false }).compile(ProcessDefinitionBodyJsonSchema);
+        const definition = validDefinition();
+        definition.resources = {
+            scripts: {
+                normalize: {
+                    language: 'typescript',
+                    entrypoint: 'main.ts',
+                    source: {
+                        type: 'inline',
+                        files: {
+                            'main.ts': 'console.log("ok");',
+                        },
+                    },
+                    packages: ['zod@4.0.0'],
+                },
+            },
+        };
+        definition.nodes.fanout.node = {
+            type: 'script',
+            script: 'normalize',
+            timeout: 120,
+        };
+
+        expect(validate(definition)).toBe(true);
+    });
+
+    it('rejects legacy script resources without a source discriminator', () => {
+        const validate = new Ajv.default({ allErrors: true, strict: false }).compile(ProcessDefinitionBodyJsonSchema);
+        const definition = validDefinition() as unknown as Record<string, unknown>;
+        definition.resources = {
+            scripts: {
+                normalize: {
+                    language: 'typescript',
+                    entrypoint: 'main.ts',
+                    files: { 'main.ts': 'console.log("ok");' },
+                },
+            },
+        };
+
+        expect(validate(definition)).toBe(false);
+    });
+
     it('rejects malformed process definition shape for editor diagnostics', () => {
         const validate = new Ajv.default({ allErrors: true, strict: false }).compile(ProcessDefinitionBodyJsonSchema);
         const invalidDefinition = {

package/src/store/process-schema.ts

@@ -32,6 +32,9 @@ export const ProcessDefinitionBodyJsonSchema = {
             nullable: true,
             description: 'Optional default model for agent and interaction nodes.',
         },
+        resources: {
+            $ref: '#/$defs/processResourcesDefinition',
+        },
         context: {
             $ref: '#/$defs/processContextDefinition',
         },
@@ -91,6 +94,7 @@ export const ProcessDefinitionBodyJsonSchema = {
                         'tool',
                         'interaction',
                         'agent',
+                        'script',
                         'process',
                         'human_task',
                         'foreach',
@@ -105,6 +109,18 @@ export const ProcessDefinitionBodyJsonSchema = {
                     nullable: true,
                     description: 'Builtin or remote tool name for tool nodes.',
                 },
+                script: {
+                    type: 'string',
+                    nullable: true,
+                    description: 'Named process script resource for script nodes.',
+                },
+                timeout: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 600,
+                    nullable: true,
+                    description: 'Script execution timeout in seconds.',
+                },
                 interaction: {
                     type: 'string',
                     nullable: true,
@@ -294,6 +310,69 @@ export const ProcessDefinitionBodyJsonSchema = {
             required: ['to'],
             additionalProperties: false,
         },
+        processResourcesDefinition: {
+            type: 'object',
+            nullable: true,
+            properties: {
+                scripts: {
+                    type: 'object',
+                    nullable: true,
+                    description: 'Named script resources available to script nodes.',
+                    required: [],
+                    additionalProperties: {
+                        $ref: '#/$defs/processScriptResource',
+                    },
+                },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+        processScriptResource: {
+            type: 'object',
+            properties: {
+                language: {
+                    type: 'string',
+                    enum: ['python', 'javascript', 'typescript'],
+                },
+                entrypoint: {
+                    type: 'string',
+                    minLength: 1,
+                },
+                source: {
+                    $ref: '#/$defs/processScriptSource',
+                },
+                packages: {
+                    type: 'array',
+                    nullable: true,
+                    items: { type: 'string' },
+                },
+            },
+            required: ['language', 'entrypoint', 'source'],
+            additionalProperties: false,
+        },
+        processScriptSource: {
+            $ref: '#/$defs/processScriptInlineSource',
+        },
+        processScriptInlineSource: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    const: 'inline',
+                    description: 'Source discriminator. Additional source types may be added in future versions.',
+                },
+                files: {
+                    type: 'object',
+                    minProperties: 1,
+                    required: [],
+                    additionalProperties: {
+                        type: 'string',
+                    },
+                },
+            },
+            required: ['type', 'files'],
+            additionalProperties: false,
+        },
         branchDefinition: {
             type: 'object',
             properties: {

package/src/store/process-validation.test.ts

@@ -52,6 +52,147 @@ describe('process definition validation', () => {
         expect(() => validateProcessDefinitionBody(validDefinition())).not.toThrow();
     });
 
+    it('accepts inline script sources and script fanout children', () => {
+        const definition = validDefinition();
+        definition.resources = {
+            scripts: {
+                score_contract: {
+                    language: 'python',
+                    entrypoint: 'main.py',
+                    source: {
+                        type: 'inline',
+                        files: {
+                            'main.py': 'print("ok")',
+                            'lib/helpers.py': 'def score(value): return value',
+                        },
+                    },
+                    packages: ['pandas>=2.0'],
+                },
+                normalize_json: {
+                    language: 'javascript',
+                    entrypoint: 'main.js',
+                    source: {
+                        type: 'inline',
+                        files: { 'main.js': 'console.log("ok")' },
+                    },
+                    packages: ['zod@4.0.0'],
+                },
+                reshape_types: {
+                    language: 'typescript',
+                    entrypoint: 'main.ts',
+                    source: {
+                        type: 'inline',
+                        files: { 'main.ts': 'console.log("ok")' },
+                    },
+                    packages: ['@types/node', '@vertesia/client@latest'],
+                },
+            },
+        };
+        definition.initial = 'score';
+        definition.nodes.score = {
+            type: 'script',
+            script: 'score_contract',
+            timeout: 60,
+            writes: ['approved'],
+            transitions: [{ to: 'approved' }],
+        };
+        definition.nodes.fanout = {
+            type: 'foreach',
+            foreach: 'items',
+            node: {
+                type: 'script',
+                script: 'score_contract',
+            },
+            transitions: [{ to: 'approved' }],
+        };
+        definition.nodes.parallel = {
+            type: 'branch',
+            branches: [
+                {
+                    id: 'normalize',
+                    node: {
+                        type: 'script',
+                        script: 'normalize_json',
+                    },
+                },
+            ],
+            transitions: [{ to: 'approved' }],
+        };
+
+        expect(() => validateProcessDefinitionBody(definition)).not.toThrow();
+    });
+
+    it('rejects invalid script resources and references', () => {
+        const definition = validDefinition();
+        definition.resources = {
+            scripts: {
+                'bad resource': {
+                    language: 'python',
+                    entrypoint: 'missing.py',
+                    source: {
+                        type: 'inline',
+                        files: {
+                            '../escape.py': 'print("no")',
+                        },
+                    },
+                    packages: ['--index-url=evil', 'zod@latest`whoami`'],
+                },
+            },
+        };
+        definition.nodes.review = {
+            type: 'script',
+            script: 'missing',
+            timeout: 601,
+            transitions: [{ to: 'approved' }],
+        };
+
+        const result = getProcessDefinitionValidationResult(definition);
+
+        expect(result.errors).toContain('script resource "bad resource" has an invalid name');
+        expect(result.errors).toContain('script resource "bad resource" has unsafe file path "../escape.py"');
+        expect(result.errors).toContain(
+            'script resource "bad resource" entrypoint "missing.py" is not present in files',
+        );
+        expect(result.errors).toContain(
+            'script resource "bad resource" has unsafe package specification "--index-url=evil"',
+        );
+        expect(result.errors).toContain(
+            'script resource "bad resource" has unsafe package specification "zod@latest`whoami`"',
+        );
+        expect(result.errors).toContain('script node "review" references unknown script resource "missing"');
+        expect(result.errors).toContain('script node "review" timeout must be an integer between 1 and 600');
+    });
+
+    it('rejects script-only fields on other node types', () => {
+        const definition = validDefinition();
+        Object.assign(definition.nodes.review, { script: 'score', timeout: 30 });
+
+        const result = getProcessDefinitionValidationResult(definition);
+
+        expect(result.errors).toContain('node "review" defines script but has type "human_task"');
+        expect(result.errors).toContain('node "review" defines timeout but has type "human_task"');
+    });
+
+    it('counts inline script sources against the process definition size cap', () => {
+        const definition = validDefinition();
+        definition.resources = {
+            scripts: {
+                oversized: {
+                    language: 'typescript',
+                    entrypoint: 'main.ts',
+                    source: {
+                        type: 'inline',
+                        files: { 'main.ts': 'x'.repeat(1024 * 1024) },
+                    },
+                },
+            },
+        };
+
+        expect(() => validateProcessDefinitionBody(definition)).toThrow(
+            'process definition, including embedded resources, exceeds',
+        );
+    });
+
     it('rejects missing transition targets', () => {
         const definition = validDefinition();
         definition.nodes.review.transitions = [{ to: 'missing' }];

package/src/store/process-validation.ts

@@ -43,6 +43,10 @@ export function getProcessInteractionValidationSelectors(interactions: Iterable<
 export const MAX_PROCESS_DEFINITION_BYTES = 1024 * 1024;
 export const MAX_PROCESS_GUARD_DEPTH = 64;
 export const MAX_PROCESS_GUARD_NODES = 4096;
+const PROCESS_SCRIPT_RESOURCE_NAME = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+const PROCESS_SCRIPT_FILE_PATH = /^[a-zA-Z0-9._-]+(\/[a-zA-Z0-9._-]+)*$/;
+const PROCESS_SCRIPT_PACKAGE =
+    /^(?:@[a-zA-Z0-9][a-zA-Z0-9._-]*\/[a-zA-Z0-9][a-zA-Z0-9._-]*|[a-zA-Z0-9][a-zA-Z0-9._-]*)(?:\[[a-zA-Z0-9,._-]+\])?(?:(?:@|[<>=!~^])[^\s;|&$`]*)?$/;
 
 export function validateProcessDefinitionBody(
     definition: ProcessDefinitionBody,
@@ -62,7 +66,7 @@ export function getProcessDefinitionValidationResult(
     const context = createValidationContext(options);
     const size = new TextEncoder().encode(JSON.stringify(definition)).length;
     if (size > MAX_PROCESS_DEFINITION_BYTES) {
-        errors.push(`process definition exceeds ${MAX_PROCESS_DEFINITION_BYTES} bytes`);
+        errors.push(`process definition, including embedded resources, exceeds ${MAX_PROCESS_DEFINITION_BYTES} bytes`);
     }
 
     if (!definition.process) {
@@ -85,6 +89,7 @@ export function getProcessDefinitionValidationResult(
     if (!definition.context?.initial) {
         errors.push('context.initial is missing');
     }
+    validateProcessResources(definition, errors);
 
     for (const [nodeId, node] of Object.entries(definition.nodes ?? {})) {
         validateNodeDefinition(definition, nodeId, node, errors, context);
@@ -136,6 +141,16 @@ function validateNodeDefinition(
     if (node.type === 'tool') {
         validateToolNodeDefinition(nodeId, node, errors, context);
     }
+    if (node.type === 'script') {
+        validateScriptNodeDefinition(definition, nodeId, node, errors);
+    } else {
+        if (node.script !== undefined) {
+            errors.push(`node "${nodeId}" defines script but has type "${node.type}"`);
+        }
+        if (node.timeout !== undefined) {
+            errors.push(`node "${nodeId}" defines timeout but has type "${node.type}"`);
+        }
+    }
     if ((node.type === 'interaction' || node.type === 'agent') && node.interaction && context.knownInteractions) {
         if (!isKnownSelector(node.interaction, context.knownInteractions)) {
             errors.push(`${node.type} node "${nodeId}" references unknown interaction "${node.interaction}"`);
@@ -306,6 +321,68 @@ function validateToolNodeDefinition(
     }
 }
 
+function validateProcessResources(definition: ProcessDefinitionBody, errors: string[]) {
+    for (const [name, resource] of Object.entries(definition.resources?.scripts ?? {})) {
+        const label = `script resource "${name}"`;
+        if (!PROCESS_SCRIPT_RESOURCE_NAME.test(name)) {
+            errors.push(`${label} has an invalid name`);
+        }
+        if (
+            resource.language !== 'python' &&
+            resource.language !== 'javascript' &&
+            resource.language !== 'typescript'
+        ) {
+            errors.push(`${label} has invalid language "${String(resource.language)}"`);
+        }
+        if (resource.source?.type !== 'inline') {
+            errors.push(`${label} has unsupported source type "${String(resource.source?.type)}"`);
+            continue;
+        }
+        const files = resource.source.files;
+        if (!files || Object.keys(files).length === 0) {
+            errors.push(`${label} must define at least one file`);
+            continue;
+        }
+        for (const [path, content] of Object.entries(files)) {
+            if (!PROCESS_SCRIPT_FILE_PATH.test(path) || path.split('/').includes('..')) {
+                errors.push(`${label} has unsafe file path "${path}"`);
+            }
+            if (typeof content !== 'string') {
+                errors.push(`${label} file "${path}" must contain text`);
+            }
+        }
+        if (!Object.hasOwn(files, resource.entrypoint)) {
+            errors.push(`${label} entrypoint "${resource.entrypoint}" is not present in files`);
+        }
+        for (const packageSpec of resource.packages ?? []) {
+            if (
+                typeof packageSpec !== 'string' ||
+                !packageSpec ||
+                packageSpec.startsWith('-') ||
+                !PROCESS_SCRIPT_PACKAGE.test(packageSpec)
+            ) {
+                errors.push(`${label} has unsafe package specification "${String(packageSpec)}"`);
+            }
+        }
+    }
+}
+
+function validateScriptNodeDefinition(
+    definition: ProcessDefinitionBody,
+    nodeId: string,
+    node: NodeDefinition,
+    errors: string[],
+) {
+    if (!node.script) {
+        errors.push(`script node "${nodeId}" is missing script`);
+    } else if (!definition.resources?.scripts?.[node.script]) {
+        errors.push(`script node "${nodeId}" references unknown script resource "${node.script}"`);
+    }
+    if (node.timeout !== undefined && (!Number.isInteger(node.timeout) || node.timeout < 1 || node.timeout > 600)) {
+        errors.push(`script node "${nodeId}" timeout must be an integer between 1 and 600`);
+    }
+}
+
 function validateSetContextNode(nodeId: string, node: NodeDefinition, errors: string[]) {
     const input = node.input;
     if (!isRecord(input)) {
@@ -379,6 +456,7 @@ function isProcessNodeType(value: string): boolean {
         value === 'tool' ||
         value === 'interaction' ||
         value === 'agent' ||
+        value === 'script' ||
         value === 'process' ||
         value === 'human_task' ||
         value === 'foreach' ||
@@ -401,7 +479,9 @@ function isParallelFailurePolicy(value: string): boolean {
 }
 
 function isFanoutChildNodeType(value: string): boolean {
-    return value === 'tool' || value === 'interaction' || value === 'agent' || value === 'process';
+    return (
+        value === 'tool' || value === 'interaction' || value === 'agent' || value === 'script' || value === 'process'
+    );
 }
 
 function validateFanoutChildNodeDefinition(