@hugex/ai 3.2.0 → 3.4.0

package/dist/common/flow-graph/schema.d.ts

@@ -0,0 +1,570 @@
+export type NodeTypeName = 'startNode' | 'classifierNode' | 'memoNode' | 'llmNode' | 'answerNode' | 'apiNode' | 'toolNode' | 'workerNode' | 'crawlNode';
+export interface AuthoringNode {
+    id: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: Record<string, unknown>;
+    [ui: string]: unknown;
+}
+export interface AuthoringEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string | null;
+    [ui: string]: unknown;
+}
+export interface WorkerGraph {
+    schemaVersion: 3;
+    nodes: AuthoringNode[];
+    edges: AuthoringEdge[];
+}
+export type IssueSeverity = 'error' | 'warning';
+export type CredentialKind = 'bearer_token' | 'basic_auth' | 'known_token' | 'url_userinfo' | 'url_query' | 'sensitive_key' | 'high_entropy';
+export type IssueCode = 'missing_state' | 'schema_version' | 'var_mapping' | 'classifier_invalid' | 'classifier_edge_missing' | 'out_vars_invalid' | 'start_count' | 'answer_missing' | 'dead_end' | 'unknown_node_type' | 'duplicate_node_id' | 'invalid_node_id' | 'node_id_collides_with_input' | 'edge_unknown_node' | 'edge_bad_handle' | 'edge_duplicate' | 'start_has_input' | 'answer_has_output' | 'multiple_outgoing' | 'field_type' | 'field_required' | 'field_range' | 'field_enum' | 'ref_syntax' | 'ref_unknown_node' | 'ref_out_of_scope' | 'ref_unknown_output' | 'ref_binary_not_allowed' | 'start_input_invalid' | 'answer_mapping_invalid' | 'worker_self_reference' | 'classifier_error_unrouted' | 'classifier_handle_inactive' | 'unreachable_node' | 'graph_cycle' | 'crawl_prompt_literal' | 'model_unknown' | 'param_unsupported' | 'reasoning_effort_unsupported' | 'tool_unavailable' | 'tool_kind_mismatch' | 'skill_unavailable' | 'builtin_unknown' | 'tool_args_invalid' | 'tool_args_unknown' | 'composio_slug_disabled' | 'composio_schema_missing' | 'memo_unavailable' | 'worker_unavailable' | 'worker_child_no_output' | 'worker_inputs_mismatch' | 'worker_child_inactive_forbidden' | 'worker_child_inactive' | 'secret_unknown' | 'secret_check_skipped' | 'inline_credential' | 'op_invalid' | 'op_unknown_node' | 'already_connected' | 'edge_not_found' | 'edge_ambiguous' | 'cannot_remove_start';
+export interface GraphIssue {
+    code: IssueCode;
+    severity: IssueSeverity;
+    message: string;
+    nodeId?: string;
+    edgeId?: string;
+    field?: string;
+    ref?: string;
+    op?: number;
+    hint?: string;
+    kind?: CredentialKind;
+    suggestedSecret?: string;
+}
+export type InsertNodeType = 'memoNode' | 'llmNode' | 'apiNode' | 'toolNode' | 'workerNode' | 'crawlNode';
+export type WorkerOp = {
+    op: 'add_node';
+    type: NodeTypeName;
+    id?: string;
+    data?: Record<string, unknown>;
+    position?: {
+        x: number;
+        y: number;
+    };
+    from?: {
+        node: string;
+        handle?: string;
+    };
+    to?: {
+        node: string;
+        handle?: string;
+    };
+} | {
+    op: 'insert_node';
+    type: InsertNodeType;
+    id?: string;
+    data?: Record<string, unknown>;
+    between: {
+        from: string;
+        to: string;
+        handle?: string;
+    };
+} | {
+    op: 'update_node';
+    id: string;
+    data: Record<string, unknown>;
+} | {
+    op: 'rename_node';
+    id: string;
+    newId: string;
+} | {
+    op: 'remove_node';
+    id: string;
+    reconnect?: boolean;
+} | {
+    op: 'connect';
+    from: string;
+    to: string;
+    handle?: string;
+    replace?: boolean;
+} | {
+    op: 'disconnect';
+    from: string;
+    to?: string;
+    handle?: string;
+} | {
+    op: 'move_node';
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+};
+export interface JsonSchema {
+    $schema?: string;
+    $id?: string;
+    $ref?: string;
+    $defs?: Record<string, JsonSchema>;
+    type?: string | readonly string[];
+    enum?: readonly unknown[];
+    const?: unknown;
+    properties?: Record<string, JsonSchema>;
+    required?: readonly string[];
+    additionalProperties?: boolean | JsonSchema;
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    minimum?: number;
+    maximum?: number;
+    maxProperties?: number;
+    items?: JsonSchema;
+    oneOf?: readonly JsonSchema[];
+    anyOf?: readonly JsonSchema[];
+    not?: JsonSchema;
+    dependentRequired?: Record<string, readonly string[]>;
+    description?: string;
+}
+/** Six definitions merged into any tool schema that accepts `graph` (N3). */
+export declare const WORKER_GRAPH_DEFS: {
+    nodeType: {
+        readonly enum: readonly ['startNode', 'classifierNode', 'memoNode', 'llmNode', 'answerNode', 'apiNode', 'toolNode', 'workerNode', 'crawlNode'];
+    };
+    nodeId: {
+        readonly type: 'string';
+        readonly pattern: '^[A-Za-z0-9_-]{1,128}$';
+    };
+    position: {
+        readonly type: 'object';
+        readonly additionalProperties: false;
+        readonly required: readonly ['x', 'y'];
+        readonly properties: {
+            readonly x: {
+                readonly type: 'number';
+            };
+            readonly y: {
+                readonly type: 'number';
+            };
+        };
+    };
+    node: {
+        readonly type: 'object';
+        readonly additionalProperties: false;
+        readonly required: readonly ['id', 'type', 'position', 'data'];
+        readonly properties: {
+            readonly id: {
+                readonly $ref: '#/$defs/nodeId';
+            };
+            readonly type: {
+                readonly $ref: '#/$defs/nodeType';
+            };
+            readonly position: {
+                readonly $ref: '#/$defs/position';
+            };
+            readonly data: {
+                readonly type: 'object';
+                readonly maxProperties: 100;
+            };
+        };
+    };
+    edge: {
+        readonly type: 'object';
+        readonly additionalProperties: false;
+        readonly required: readonly ['source', 'target'];
+        readonly properties: {
+            readonly id: {
+                readonly type: 'string';
+                readonly minLength: 1;
+                readonly maxLength: 300;
+            };
+            readonly source: {
+                readonly $ref: '#/$defs/nodeId';
+            };
+            readonly target: {
+                readonly $ref: '#/$defs/nodeId';
+            };
+            readonly sourceHandle: {
+                readonly type: readonly ['string', 'null'];
+                readonly pattern: '^source-[A-Za-z0-9_.-]{1,100}$';
+            };
+        };
+    };
+    graph: {
+        readonly type: 'object';
+        readonly additionalProperties: false;
+        readonly required: readonly ['schemaVersion', 'nodes', 'edges'];
+        readonly properties: {
+            readonly schemaVersion: {
+                readonly const: 3;
+            };
+            readonly nodes: {
+                readonly type: 'array';
+                readonly maxItems: 200;
+                readonly items: {
+                    readonly $ref: '#/$defs/node';
+                };
+            };
+            readonly edges: {
+                readonly type: 'array';
+                readonly maxItems: 400;
+                readonly items: {
+                    readonly $ref: '#/$defs/edge';
+                };
+            };
+        };
+    };
+};
+export declare const WORKER_GRAPH_SCHEMA: {
+    readonly $schema: 'https://json-schema.org/draft/2020-12/schema';
+    readonly $defs: {
+        nodeType: {
+            readonly enum: readonly ['startNode', 'classifierNode', 'memoNode', 'llmNode', 'answerNode', 'apiNode', 'toolNode', 'workerNode', 'crawlNode'];
+        };
+        nodeId: {
+            readonly type: 'string';
+            readonly pattern: '^[A-Za-z0-9_-]{1,128}$';
+        };
+        position: {
+            readonly type: 'object';
+            readonly additionalProperties: false;
+            readonly required: readonly ['x', 'y'];
+            readonly properties: {
+                readonly x: {
+                    readonly type: 'number';
+                };
+                readonly y: {
+                    readonly type: 'number';
+                };
+            };
+        };
+        node: {
+            readonly type: 'object';
+            readonly additionalProperties: false;
+            readonly required: readonly ['id', 'type', 'position', 'data'];
+            readonly properties: {
+                readonly id: {
+                    readonly $ref: '#/$defs/nodeId';
+                };
+                readonly type: {
+                    readonly $ref: '#/$defs/nodeType';
+                };
+                readonly position: {
+                    readonly $ref: '#/$defs/position';
+                };
+                readonly data: {
+                    readonly type: 'object';
+                    readonly maxProperties: 100;
+                };
+            };
+        };
+        edge: {
+            readonly type: 'object';
+            readonly additionalProperties: false;
+            readonly required: readonly ['source', 'target'];
+            readonly properties: {
+                readonly id: {
+                    readonly type: 'string';
+                    readonly minLength: 1;
+                    readonly maxLength: 300;
+                };
+                readonly source: {
+                    readonly $ref: '#/$defs/nodeId';
+                };
+                readonly target: {
+                    readonly $ref: '#/$defs/nodeId';
+                };
+                readonly sourceHandle: {
+                    readonly type: readonly ['string', 'null'];
+                    readonly pattern: '^source-[A-Za-z0-9_.-]{1,100}$';
+                };
+            };
+        };
+        graph: {
+            readonly type: 'object';
+            readonly additionalProperties: false;
+            readonly required: readonly ['schemaVersion', 'nodes', 'edges'];
+            readonly properties: {
+                readonly schemaVersion: {
+                    readonly const: 3;
+                };
+                readonly nodes: {
+                    readonly type: 'array';
+                    readonly maxItems: 200;
+                    readonly items: {
+                        readonly $ref: '#/$defs/node';
+                    };
+                };
+                readonly edges: {
+                    readonly type: 'array';
+                    readonly maxItems: 400;
+                    readonly items: {
+                        readonly $ref: '#/$defs/edge';
+                    };
+                };
+            };
+        };
+    };
+    readonly $ref: '#/$defs/graph';
+};
+export declare const WORKER_OP_SCHEMA: {
+    readonly type: 'object';
+    readonly additionalProperties: false;
+    readonly required: readonly ['flowId', 'baseVersion', 'ops'];
+    readonly properties: {
+        readonly flowId: {
+            readonly type: 'string';
+            readonly pattern: '^[A-Za-z0-9_-]{1,128}$';
+        };
+        readonly baseVersion: {
+            readonly type: 'integer';
+            readonly minimum: 0;
+        };
+        readonly ops: {
+            readonly type: 'array';
+            readonly minItems: 1;
+            readonly maxItems: 50;
+            readonly items: {
+                readonly $ref: '#/$defs/op';
+            };
+        };
+        readonly dryRun: {
+            readonly type: 'boolean';
+        };
+        readonly acknowledgeInlineCredentials: {
+            readonly type: 'boolean';
+        };
+        readonly returnGraph: {
+            readonly type: 'boolean';
+        };
+    };
+    readonly $defs: {
+        readonly nodeType: {
+            readonly enum: readonly ['startNode', 'classifierNode', 'memoNode', 'llmNode', 'answerNode', 'apiNode', 'toolNode', 'workerNode', 'crawlNode'];
+        };
+        readonly existingId: {
+            readonly type: 'string';
+            readonly pattern: '^[A-Za-z0-9_-]{1,128}$';
+        };
+        readonly newId: {
+            readonly type: 'string';
+            readonly pattern: '^[A-Za-z][A-Za-z0-9_-]{0,63}$';
+        };
+        readonly handle: {
+            readonly type: 'string';
+            readonly pattern: '^(source-)?[A-Za-z0-9_.-]{1,100}$';
+        };
+        readonly position: {
+            readonly type: 'object';
+            readonly additionalProperties: false;
+            readonly required: readonly ['x', 'y'];
+            readonly properties: {
+                readonly x: {
+                    readonly type: 'number';
+                };
+                readonly y: {
+                    readonly type: 'number';
+                };
+            };
+        };
+        readonly data: {
+            readonly type: 'object';
+            readonly maxProperties: 100;
+        };
+        readonly op: {
+            readonly oneOf: readonly [{
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['op', 'type'];
+                readonly properties: {
+                    readonly op: {
+                        readonly const: 'add_node';
+                    };
+                    readonly type: {
+                        readonly $ref: '#/$defs/nodeType';
+                    };
+                    readonly id: {
+                        readonly $ref: '#/$defs/newId';
+                    };
+                    readonly data: {
+                        readonly $ref: '#/$defs/data';
+                    };
+                    readonly position: {
+                        readonly $ref: '#/$defs/position';
+                    };
+                    readonly from: {
+                        readonly type: 'object';
+                        readonly additionalProperties: false;
+                        readonly required: readonly ['node'];
+                        readonly properties: {
+                            readonly node: {
+                                readonly $ref: '#/$defs/existingId';
+                            };
+                            readonly handle: {
+                                readonly $ref: '#/$defs/handle';
+                            };
+                        };
+                    };
+                    readonly to: {
+                        readonly type: 'object';
+                        readonly additionalProperties: false;
+                        readonly required: readonly ['node'];
+                        readonly properties: {
+                            readonly node: {
+                                readonly $ref: '#/$defs/existingId';
+                            };
+                            readonly handle: {
+                                readonly $ref: '#/$defs/handle';
+                            };
+                        };
+                    };
+                };
+            }, {
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['op', 'type', 'between'];
+                readonly properties: {
+                    readonly op: {
+                        readonly const: 'insert_node';
+                    };
+                    readonly type: {
+                        readonly enum: readonly ['memoNode', 'llmNode', 'apiNode', 'toolNode', 'workerNode', 'crawlNode'];
+                    };
+                    readonly id: {
+                        readonly $ref: '#/$defs/newId';
+                    };
+                    readonly data: {
+                        readonly $ref: '#/$defs/data';
+                    };
+                    readonly between: {
+                        readonly type: 'object';
+                        readonly additionalProperties: false;
+                        readonly required: readonly ['from', 'to'];
+                        readonly properties: {
+                            readonly from: {
+                                readonly $ref: '#/$defs/existingId';
+                            };
+                            readonly to: {
+                                readonly $ref: '#/$defs/existingId';
+                            };
+                            readonly handle: {
+                                readonly $ref: '#/$defs/handle';
+                            };
+                        };
+                    };
+                };
+            }, {
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['op', 'id', 'data'];
+                readonly properties: {
+                    readonly op: {
+                        readonly const: 'update_node';
+                    };
+                    readonly id: {
+                        readonly $ref: '#/$defs/existingId';
+                    };
+                    readonly data: {
+                        readonly $ref: '#/$defs/data';
+                    };
+                };
+            }, {
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['op', 'id', 'newId'];
+                readonly properties: {
+                    readonly op: {
+                        readonly const: 'rename_node';
+                    };
+                    readonly id: {
+                        readonly $ref: '#/$defs/existingId';
+                    };
+                    readonly newId: {
+                        readonly $ref: '#/$defs/newId';
+                    };
+                };
+            }, {
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['op', 'id'];
+                readonly properties: {
+                    readonly op: {
+                        readonly const: 'remove_node';
+                    };
+                    readonly id: {
+                        readonly $ref: '#/$defs/existingId';
+                    };
+                    readonly reconnect: {
+                        readonly type: 'boolean';
+                    };
+                };
+            }, {
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['op', 'from', 'to'];
+                readonly properties: {
+                    readonly op: {
+                        readonly const: 'connect';
+                    };
+                    readonly from: {
+                        readonly $ref: '#/$defs/existingId';
+                    };
+                    readonly to: {
+                        readonly $ref: '#/$defs/existingId';
+                    };
+                    readonly handle: {
+                        readonly $ref: '#/$defs/handle';
+                    };
+                    readonly replace: {
+                        readonly type: 'boolean';
+                    };
+                };
+            }, {
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['op', 'from'];
+                readonly properties: {
+                    readonly op: {
+                        readonly const: 'disconnect';
+                    };
+                    readonly from: {
+                        readonly $ref: '#/$defs/existingId';
+                    };
+                    readonly to: {
+                        readonly $ref: '#/$defs/existingId';
+                    };
+                    readonly handle: {
+                        readonly $ref: '#/$defs/handle';
+                    };
+                };
+            }, {
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['op', 'id', 'position'];
+                readonly properties: {
+                    readonly op: {
+                        readonly const: 'move_node';
+                    };
+                    readonly id: {
+                        readonly $ref: '#/$defs/existingId';
+                    };
+                    readonly position: {
+                        readonly $ref: '#/$defs/position';
+                    };
+                };
+            }];
+        };
+    };
+};
+/** Hand-written JSON Schema subset used by the parsers. No Ajv. */
+export declare function schemaErrors(schema: object, value: unknown, root?: object): string[];
+export declare function parseWorkerGraph(input: unknown): {
+    ok: true;
+    graph: WorkerGraph;
+} | {
+    ok: false;
+    issues: GraphIssue[];
+};
+export declare function parseWorkerOps(input: unknown): {
+    ok: true;
+    ops: WorkerOp[];
+} | {
+    ok: false;
+    issues: GraphIssue[];
+};

package/dist/common/flow-graph/templates.d.ts

@@ -0,0 +1,2 @@
+import type { WorkerGraph } from './schema';
+export declare const WORKER_TEMPLATES: Readonly<Record<'chat' | 'extract', WorkerGraph>>;

package/dist/common/flow-graph/validate.d.ts

@@ -0,0 +1,77 @@
+import type { GraphIssue, WorkerGraph } from './schema';
+export declare const ISSUE_SEVERITY: {
+    readonly missing_state: 'blocking';
+    readonly schema_version: 'blocking';
+    readonly var_mapping: 'blocking';
+    readonly classifier_invalid: 'blocking';
+    readonly classifier_edge_missing: 'blocking';
+    readonly out_vars_invalid: 'blocking';
+    readonly start_count: 'blocking';
+    readonly answer_missing: 'blocking';
+    readonly dead_end: 'blocking';
+    readonly unknown_node_type: 'blocking';
+    readonly duplicate_node_id: 'blocking';
+    readonly invalid_node_id: 'blocking';
+    readonly node_id_collides_with_input: 'blocking';
+    readonly edge_unknown_node: 'blocking';
+    readonly edge_bad_handle: 'blocking';
+    readonly edge_duplicate: 'blocking';
+    readonly start_has_input: 'blocking';
+    readonly answer_has_output: 'blocking';
+    readonly multiple_outgoing: 'blocking';
+    readonly field_type: 'blocking';
+    readonly field_required: 'blocking';
+    readonly field_range: 'blocking';
+    readonly field_enum: 'blocking';
+    readonly ref_syntax: 'blocking';
+    readonly ref_unknown_node: 'blocking';
+    readonly ref_out_of_scope: 'blocking';
+    readonly ref_unknown_output: 'blocking';
+    readonly ref_binary_not_allowed: 'blocking';
+    readonly start_input_invalid: 'blocking';
+    readonly answer_mapping_invalid: 'blocking';
+    readonly worker_self_reference: 'blocking';
+    readonly classifier_error_unrouted: 'advisory';
+    readonly classifier_handle_inactive: 'advisory';
+    readonly unreachable_node: 'advisory';
+    readonly graph_cycle: 'advisory';
+    readonly crawl_prompt_literal: 'advisory';
+    readonly model_unknown: 'blocking';
+    readonly param_unsupported: 'advisory';
+    readonly reasoning_effort_unsupported: 'advisory';
+    readonly tool_unavailable: 'blocking';
+    readonly tool_kind_mismatch: 'blocking';
+    readonly skill_unavailable: 'blocking';
+    readonly builtin_unknown: 'blocking';
+    readonly tool_args_invalid: 'blocking';
+    readonly tool_args_unknown: 'advisory';
+    readonly composio_slug_disabled: 'blocking';
+    readonly composio_schema_missing: 'advisory';
+    readonly memo_unavailable: 'blocking';
+    readonly worker_unavailable: 'blocking';
+    readonly worker_child_no_output: 'blocking';
+    readonly worker_inputs_mismatch: 'blocking';
+    readonly worker_child_inactive_forbidden: 'blocking';
+    readonly worker_child_inactive: 'advisory';
+    readonly secret_unknown: 'advisory';
+    readonly secret_check_skipped: 'advisory';
+    readonly inline_credential: 'blocking';
+    readonly op_invalid: 'blocking';
+    readonly op_unknown_node: 'blocking';
+    readonly already_connected: 'blocking';
+    readonly edge_not_found: 'blocking';
+    readonly edge_ambiguous: 'blocking';
+    readonly cannot_remove_start: 'blocking';
+};
+/** L1, same order and same messages as FlowEngine.validateFlowStart. */
+export declare function validateFlowStructure(graph: unknown): GraphIssue[];
+/** L2 authoring issues, with intrinsic severity. Final severity is classifyIssues. */
+export declare function validateAuthoring(graph: WorkerGraph): GraphIssue[];
+/** Fingerprint of code, node, field, ref, and credential kind. Message and op are excluded. */
+export declare function issueFingerprint(issue: GraphIssue): string;
+export declare function classifyIssues(before: GraphIssue[], after: GraphIssue[], opts?: {
+    acknowledgeInlineCredentials?: boolean;
+}): {
+    errors: GraphIssue[];
+    warnings: GraphIssue[];
+};