@framers/agentos 0.1.68 → 0.1.70

package/dist/orchestration/compiler/MissionCompiler.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @file MissionCompiler.ts
+ * @description Bridges PlanningEngine output (or the stub planner) to a
+ * `CompiledExecutionGraph` IR, enabling goal-oriented mission authoring via
+ * the `mission()` builder API.
+ *
+ * Compilation pipeline:
+ *   1. Run stub planner → `SimplePlan` (real PlanningEngine wired later)
+ *   2. Map plan steps to `GraphNode` objects via `stepToNode()`
+ *   3. Splice declared anchors into the phase-ordered node sequence
+ *   4. Build a linear edge chain (START → … → END)
+ *   5. Apply mission-level guardrail policies to all nodes
+ *   6. Lower to `CompiledExecutionGraph` via `GraphCompiler` + `GraphValidator`
+ */
+import type { GraphNode, CompiledExecutionGraph, MemoryConsistencyMode } from '../ir/types.js';
+/**
+ * Top-level configuration object consumed by `MissionCompiler.compile()`.
+ * Produced internally by `MissionBuilder.compile()`.
+ */
+export interface MissionConfig {
+    /** Human-readable mission name; becomes the compiled graph's display name. */
+    name: string;
+    /** Zod schema (or plain JSON-Schema object) describing the mission's input payload. */
+    inputSchema: any;
+    /**
+     * Goal prompt template.  Supports `{{variable}}` interpolation (e.g. `{{topic}}`).
+     * Injected as the system instruction for the stub planner and `gmi` reasoning nodes.
+     */
+    goalTemplate: string;
+    /** Zod schema (or plain JSON-Schema object) describing the mission's output artifacts. */
+    returnsSchema: any;
+    /** Planner configuration controlling step generation and execution budgets. */
+    plannerConfig: {
+        /** Routing/planning strategy identifier (e.g. `'linear'`, `'react'`, `'tree-of-thought'`). */
+        strategy: string;
+        /** Hard cap on the total number of plan steps the planner may emit. */
+        maxSteps: number;
+        /**
+         * Maximum LLM iterations a single `gmi` node may consume per invocation.
+         * Forwarded to `gmiNode` as `maxInternalIterations`.
+         */
+        maxIterationsPerNode?: number;
+        /**
+         * When `true`, `gmi` nodes are configured to issue multiple tool calls per turn.
+         * Forwarded to `gmiNode` as `parallelTools`.
+         */
+        parallelTools?: boolean;
+    };
+    /**
+     * Optional mission-level policy overrides.
+     * When set, they are applied to all compiled nodes unless a node already declares
+     * its own policy.
+     */
+    policyConfig?: {
+        memory?: {
+            consistency?: MemoryConsistencyMode;
+            read?: any;
+            write?: any;
+        };
+        discovery?: {
+            kind?: string;
+            fallback?: string;
+        };
+        personality?: {
+            traitRouting?: boolean;
+            adaptStyle?: boolean;
+            mood?: string;
+        };
+        /** Guardrail identifiers applied as output guardrails on every node. */
+        guardrails?: string[];
+    };
+    /**
+     * Declarative anchor nodes that must be spliced into the execution order at specific phases.
+     * Anchors allow callers to inject pre-built `GraphNode` objects (e.g. specialised tools or
+     * human-in-the-loop checkpoints) without modifying the planner output.
+     */
+    anchors: Array<{
+        /** Node id assigned to the anchor inside the compiled graph. */
+        id: string;
+        /** Pre-built `GraphNode` to splice in. The compiler overwrites `node.id` with `anchor.id`. */
+        node: GraphNode;
+        /** Placement constraints that control where in the phase sequence the anchor is inserted. */
+        constraints: {
+            /** When `true` the compiler will throw if the anchor cannot be placed. */
+            required: boolean;
+            /**
+             * Execution phase the anchor belongs to.  Phases are ordered:
+             * `gather` → `process` → `validate` → `deliver`.
+             */
+            phase?: 'gather' | 'process' | 'validate' | 'deliver';
+            /**
+             * Insert the anchor *after* this node id (sibling anchor id or plan step id).
+             * When the referenced id is not found the anchor is appended to the phase tail.
+             */
+            after?: any;
+            /**
+             * Insert the anchor *before* this node id.
+             * Currently reserved for future use; has no effect in this compiler version.
+             */
+            before?: any;
+        };
+    }>;
+}
+/**
+ * Minimal plan structure produced by the stub planner (and, eventually, by the
+ * real `PlanningEngine`).  Each step maps 1-to-1 to a `GraphNode` in the compiled IR.
+ */
+export interface SimplePlan {
+    steps: Array<{
+        /** Unique step id; becomes the compiled `GraphNode.id`. */
+        id: string;
+        /**
+         * Step action type, used to select the correct node builder:
+         * - `'reasoning'`   → `gmiNode`
+         * - `'tool_call'`   → `toolNode`
+         * - `'human_input'` → `humanNode`
+         * - `'validation'`  → `guardrailNode`
+         */
+        action: string;
+        /** Human-readable description injected as the node's instructions or prompt. */
+        description: string;
+        /** Execution phase this step belongs to (governs ordering alongside anchors). */
+        phase: 'gather' | 'process' | 'validate' | 'deliver';
+        /** Required when `action` is `'tool_call'`; the registered tool name. */
+        toolName?: string;
+    }>;
+}
+/**
+ * Static compiler that transforms a `MissionConfig` into a `CompiledExecutionGraph`.
+ *
+ * The compiler is intentionally stateless — call `MissionCompiler.compile()` as many
+ * times as needed; each invocation is fully isolated.
+ *
+ * @example
+ * ```ts
+ * const ir = MissionCompiler.compile({
+ *   name: 'research-mission',
+ *   inputSchema: z.object({ topic: z.string() }),
+ *   goalTemplate: 'Research {{topic}} and produce a summary',
+ *   returnsSchema: z.object({ summary: z.string() }),
+ *   plannerConfig: { strategy: 'linear', maxSteps: 5 },
+ *   anchors: [],
+ * });
+ * ```
+ */
+export declare class MissionCompiler {
+    /**
+     * Compile a mission config into a `CompiledExecutionGraph`.
+     *
+     * Uses a stub planner that generates a simple linear plan based on the goal template.
+     * Real `PlanningEngine` integration will be wired in a future task once the planner
+     * interface is stable.
+     *
+     * @param config - Fully-populated `MissionConfig` object produced by `MissionBuilder`.
+     * @returns A validated `CompiledExecutionGraph` ready for `GraphRuntime`.
+     * @throws {Error} When `GraphValidator.validate()` reports structural errors.
+     */
+    static compile(config: MissionConfig): CompiledExecutionGraph;
+    /**
+     * Stub planner: emits a fixed 3-step linear plan derived from the goal template.
+     *
+     * This is intentionally minimal — its only job is to prove the compilation pipeline
+     * works end-to-end.  The real `PlanningEngine` (Task 16+) will replace this method.
+     *
+     * @param config - Mission configuration providing the goal template and planner settings.
+     * @returns A `SimplePlan` with steps distributed across `gather`, `process`, and `deliver` phases.
+     */
+    private static generateStubPlan;
+    /**
+     * Convert a single `SimplePlan` step to its corresponding `GraphNode`.
+     *
+     * The returned node's `id` is immediately overwritten by the caller with `step.id`,
+     * so the auto-generated id from the node builders is discarded.
+     *
+     * @param step   - Plan step descriptor.
+     * @param config - Parent mission configuration (provides planner and policy settings).
+     * @returns A fully-initialised `GraphNode` whose `id` will be overwritten by the caller.
+     */
+    private static stepToNode;
+}
+//# sourceMappingURL=MissionCompiler.d.ts.map

package/dist/orchestration/compiler/MissionCompiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MissionCompiler.d.ts","sourceRoot":"","sources":["../../../src/orchestration/compiler/MissionCompiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,SAAS,EAET,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAUxB;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,WAAW,EAAE,GAAG,CAAC;IACjB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,aAAa,EAAE,GAAG,CAAC;IACnB,+EAA+E;IAC/E,aAAa,EAAE;QACb,8FAA8F;QAC9F,QAAQ,EAAE,MAAM,CAAC;QACjB,uEAAuE;QACvE,QAAQ,EAAE,MAAM,CAAC;QACjB;;;WAGG;QACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B;;;WAGG;QACH,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;IACF;;;;OAIG;IACH,YAAY,CAAC,EAAE;QACb,MAAM,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE,qBAAqB,CAAC;YAAC,IAAI,CAAC,EAAE,GAAG,CAAC;YAAC,KAAK,CAAC,EAAE,GAAG,CAAA;SAAE,CAAC;QAC1E,SAAS,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACjD,WAAW,CAAC,EAAE;YAAE,YAAY,CAAC,EAAE,OAAO,CAAC;YAAC,UAAU,CAAC,EAAE,OAAO,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC9E,wEAAwE;QACxE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF;;;;OAIG;IACH,OAAO,EAAE,KAAK,CAAC;QACb,gEAAgE;QAChE,EAAE,EAAE,MAAM,CAAC;QACX,8FAA8F;QAC9F,IAAI,EAAE,SAAS,CAAC;QAChB,6FAA6F;QAC7F,WAAW,EAAE;YACX,0EAA0E;YAC1E,QAAQ,EAAE,OAAO,CAAC;YAClB;;;eAGG;YACH,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;YACtD;;;eAGG;YACH,KAAK,CAAC,EAAE,GAAG,CAAC;YACZ;;;eAGG;YACH,MAAM,CAAC,EAAE,GAAG,CAAC;SACd,CAAC;KACH,CAAC,CAAC;CACJ;AAMD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAC;QACX,2DAA2D;QAC3D,EAAE,EAAE,MAAM,CAAC;QACX;;;;;;WAMG;QACH,MAAM,EAAE,MAAM,CAAC;QACf,gFAAgF;QAChF,WAAW,EAAE,MAAM,CAAC;QACpB,iFAAiF;QACjF,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;QACrD,yEAAyE;QACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;CACJ;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAe;IAK1B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,sBAAsB;IAgH7D;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAyB/B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;CAiC1B"}

package/dist/orchestration/compiler/MissionCompiler.js

@@ -0,0 +1,219 @@
+/**
+ * @file MissionCompiler.ts
+ * @description Bridges PlanningEngine output (or the stub planner) to a
+ * `CompiledExecutionGraph` IR, enabling goal-oriented mission authoring via
+ * the `mission()` builder API.
+ *
+ * Compilation pipeline:
+ *   1. Run stub planner → `SimplePlan` (real PlanningEngine wired later)
+ *   2. Map plan steps to `GraphNode` objects via `stepToNode()`
+ *   3. Splice declared anchors into the phase-ordered node sequence
+ *   4. Build a linear edge chain (START → … → END)
+ *   5. Apply mission-level guardrail policies to all nodes
+ *   6. Lower to `CompiledExecutionGraph` via `GraphCompiler` + `GraphValidator`
+ */
+import { START, END } from '../ir/types.js';
+import { gmiNode, toolNode, humanNode, guardrailNode } from '../builders/nodes.js';
+import { GraphCompiler } from './GraphCompiler.js';
+import { GraphValidator } from './Validator.js';
+// ---------------------------------------------------------------------------
+// MissionCompiler
+// ---------------------------------------------------------------------------
+/**
+ * Static compiler that transforms a `MissionConfig` into a `CompiledExecutionGraph`.
+ *
+ * The compiler is intentionally stateless — call `MissionCompiler.compile()` as many
+ * times as needed; each invocation is fully isolated.
+ *
+ * @example
+ * ```ts
+ * const ir = MissionCompiler.compile({
+ *   name: 'research-mission',
+ *   inputSchema: z.object({ topic: z.string() }),
+ *   goalTemplate: 'Research {{topic}} and produce a summary',
+ *   returnsSchema: z.object({ summary: z.string() }),
+ *   plannerConfig: { strategy: 'linear', maxSteps: 5 },
+ *   anchors: [],
+ * });
+ * ```
+ */
+export class MissionCompiler {
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Compile a mission config into a `CompiledExecutionGraph`.
+     *
+     * Uses a stub planner that generates a simple linear plan based on the goal template.
+     * Real `PlanningEngine` integration will be wired in a future task once the planner
+     * interface is stable.
+     *
+     * @param config - Fully-populated `MissionConfig` object produced by `MissionBuilder`.
+     * @returns A validated `CompiledExecutionGraph` ready for `GraphRuntime`.
+     * @throws {Error} When `GraphValidator.validate()` reports structural errors.
+     */
+    static compile(config) {
+        // 1. Generate a linear plan (stub — real planner integration planned for Task 16+)
+        const plan = this.generateStubPlan(config);
+        // 2. Map plan steps to GraphNode objects
+        const nodes = new Map();
+        const edges = [];
+        let edgeCounter = 0;
+        const nextEdgeId = () => `me-${++edgeCounter}`;
+        for (const step of plan.steps) {
+            const node = this.stepToNode(step, config);
+            nodes.set(step.id, node);
+        }
+        // 3. Splice anchors — overwrite their id so the compiled graph uses the declared id
+        for (const anchor of config.anchors) {
+            // Mutate a shallow copy to avoid modifying the caller's object
+            const anchoredNode = { ...anchor.node, id: anchor.id };
+            nodes.set(anchor.id, anchoredNode);
+        }
+        // 4. Build a phase-ordered sequence of node ids
+        const phaseOrder = [
+            'gather',
+            'process',
+            'validate',
+            'deliver',
+        ];
+        const orderedNodeIds = [];
+        for (const phase of phaseOrder) {
+            // Plan steps belonging to this phase
+            const phaseSteps = plan.steps.filter(s => s.phase === phase);
+            for (const step of phaseSteps) {
+                orderedNodeIds.push(step.id);
+            }
+            // Anchors belonging to this phase, respecting `after` constraints
+            const phaseAnchors = config.anchors.filter(a => a.constraints.phase === phase);
+            for (const anchor of phaseAnchors) {
+                if (typeof anchor.constraints.after === 'string') {
+                    const afterIdx = orderedNodeIds.indexOf(anchor.constraints.after);
+                    if (afterIdx >= 0) {
+                        orderedNodeIds.splice(afterIdx + 1, 0, anchor.id);
+                        continue;
+                    }
+                }
+                orderedNodeIds.push(anchor.id);
+            }
+        }
+        // Anchors without a phase constraint are appended at the tail
+        for (const anchor of config.anchors) {
+            if (!anchor.constraints.phase && !orderedNodeIds.includes(anchor.id)) {
+                orderedNodeIds.push(anchor.id);
+            }
+        }
+        // 5. Build linear edge chain: START → n₀ → n₁ → … → END
+        let prev = START;
+        for (const nodeId of orderedNodeIds) {
+            edges.push({ id: nextEdgeId(), source: prev, target: nodeId, type: 'static' });
+            prev = nodeId;
+        }
+        edges.push({ id: nextEdgeId(), source: prev, target: END, type: 'static' });
+        // 6. Apply mission-level guardrail policy to every node that has none yet
+        if (config.policyConfig?.guardrails && config.policyConfig.guardrails.length > 0) {
+            for (const [key, node] of nodes) {
+                if (!node.guardrailPolicy) {
+                    nodes.set(key, {
+                        ...node,
+                        guardrailPolicy: {
+                            output: config.policyConfig.guardrails,
+                            onViolation: 'warn',
+                        },
+                    });
+                }
+            }
+        }
+        // 7. Lower to CompiledExecutionGraph via GraphCompiler
+        const ir = GraphCompiler.compile({
+            name: config.name,
+            nodes,
+            edges,
+            stateSchema: {
+                input: config.inputSchema,
+                scratch: config.inputSchema,
+                artifacts: config.returnsSchema,
+            },
+            reducers: {},
+            memoryConsistency: config.policyConfig?.memory?.consistency ?? 'snapshot',
+            checkpointPolicy: 'every_node',
+        });
+        // 8. Validate structural correctness (acyclicity required for linear missions)
+        const validation = GraphValidator.validate(ir, { requireAcyclic: true });
+        if (!validation.valid) {
+            throw new Error(`Mission compilation failed for "${config.name}": ${validation.errors.join('; ')}`);
+        }
+        return ir;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Stub planner: emits a fixed 3-step linear plan derived from the goal template.
+     *
+     * This is intentionally minimal — its only job is to prove the compilation pipeline
+     * works end-to-end.  The real `PlanningEngine` (Task 16+) will replace this method.
+     *
+     * @param config - Mission configuration providing the goal template and planner settings.
+     * @returns A `SimplePlan` with steps distributed across `gather`, `process`, and `deliver` phases.
+     */
+    static generateStubPlan(config) {
+        return {
+            steps: [
+                {
+                    id: 'gather-info',
+                    action: 'reasoning',
+                    description: `Gather information for: ${config.goalTemplate}`,
+                    phase: 'gather',
+                },
+                {
+                    id: 'process-info',
+                    action: 'reasoning',
+                    description: 'Process and analyse gathered information',
+                    phase: 'process',
+                },
+                {
+                    id: 'deliver-result',
+                    action: 'reasoning',
+                    description: 'Deliver final result',
+                    phase: 'deliver',
+                },
+            ],
+        };
+    }
+    /**
+     * Convert a single `SimplePlan` step to its corresponding `GraphNode`.
+     *
+     * The returned node's `id` is immediately overwritten by the caller with `step.id`,
+     * so the auto-generated id from the node builders is discarded.
+     *
+     * @param step   - Plan step descriptor.
+     * @param config - Parent mission configuration (provides planner and policy settings).
+     * @returns A fully-initialised `GraphNode` whose `id` will be overwritten by the caller.
+     */
+    static stepToNode(step, config) {
+        switch (step.action) {
+            case 'tool_call':
+                return { ...toolNode(step.toolName ?? 'unknown'), id: step.id };
+            case 'human_input':
+                return { ...humanNode({ prompt: step.description }), id: step.id };
+            case 'validation':
+                return {
+                    ...guardrailNode(config.policyConfig?.guardrails ?? [], { onViolation: 'warn' }),
+                    id: step.id,
+                };
+            case 'reasoning':
+            default:
+                return {
+                    ...gmiNode({
+                        instructions: step.description,
+                        executionMode: 'planner_controlled',
+                        maxInternalIterations: config.plannerConfig.maxIterationsPerNode,
+                        parallelTools: config.plannerConfig.parallelTools,
+                    }),
+                    id: step.id,
+                };
+        }
+    }
+}
+//# sourceMappingURL=MissionCompiler.js.map

package/dist/orchestration/compiler/MissionCompiler.js.map

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

package/dist/orchestration/compiler/SchemaLowering.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file SchemaLowering.ts
+ * @description Minimal Zod-to-JSON-Schema converter for the AgentOS orchestration layer.
+ *
+ * Intentionally hand-rolled to avoid adding `zod-to-json-schema` as a dependency.
+ * Handles the subset of Zod types used in node input/output schemas across the codebase:
+ * z.string, z.number, z.boolean, z.null, z.object, z.array, z.enum, z.optional, z.default.
+ *
+ * Targets Zod v4 `_def` internals:
+ * - Discriminant field: `_def.type` (string literal, e.g. `"string"`, `"object"`)
+ * - Array inner schema: `_def.element`
+ * - Object shape: `_def.shape` (plain Record, NOT a function as in Zod v3)
+ * - Enum values: `_def.entries` (Record<string, string> — keys and values are the same)
+ * - Optional/Default inner schema: `_def.innerType`
+ *
+ * Unsupported types fall through to an empty object `{}` — callers should treat that as
+ * an "unknown / untyped" schema rather than an error.
+ */
+import type { ZodType } from 'zod';
+/**
+ * Converts a Zod schema instance to a plain JSON Schema object.
+ *
+ * Recursively descends into ZodObject shapes, ZodArray item types, ZodOptional and
+ * ZodDefault wrappers, transparently unwrapping them so the produced JSON Schema
+ * is clean and does not contain Zod-specific metadata.
+ *
+ * @param schema - Any Zod schema instance.
+ * @returns A JSON Schema-compatible plain object.
+ *
+ * @example
+ * ```ts
+ * const jsonSchema = lowerZodToJsonSchema(z.object({ name: z.string(), age: z.number().optional() }));
+ * // → { type: 'object', properties: { name: { type: 'string' }, age: { type: 'number' } }, required: ['name'] }
+ * ```
+ */
+export declare function lowerZodToJsonSchema(schema: ZodType): Record<string, unknown>;
+//# sourceMappingURL=SchemaLowering.d.ts.map

package/dist/orchestration/compiler/SchemaLowering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaLowering.d.ts","sourceRoot":"","sources":["../../../src/orchestration/compiler/SchemaLowering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyE7E"}

package/dist/orchestration/compiler/SchemaLowering.js

@@ -0,0 +1,95 @@
+/**
+ * @file SchemaLowering.ts
+ * @description Minimal Zod-to-JSON-Schema converter for the AgentOS orchestration layer.
+ *
+ * Intentionally hand-rolled to avoid adding `zod-to-json-schema` as a dependency.
+ * Handles the subset of Zod types used in node input/output schemas across the codebase:
+ * z.string, z.number, z.boolean, z.null, z.object, z.array, z.enum, z.optional, z.default.
+ *
+ * Targets Zod v4 `_def` internals:
+ * - Discriminant field: `_def.type` (string literal, e.g. `"string"`, `"object"`)
+ * - Array inner schema: `_def.element`
+ * - Object shape: `_def.shape` (plain Record, NOT a function as in Zod v3)
+ * - Enum values: `_def.entries` (Record<string, string> — keys and values are the same)
+ * - Optional/Default inner schema: `_def.innerType`
+ *
+ * Unsupported types fall through to an empty object `{}` — callers should treat that as
+ * an "unknown / untyped" schema rather than an error.
+ */
+/**
+ * Converts a Zod schema instance to a plain JSON Schema object.
+ *
+ * Recursively descends into ZodObject shapes, ZodArray item types, ZodOptional and
+ * ZodDefault wrappers, transparently unwrapping them so the produced JSON Schema
+ * is clean and does not contain Zod-specific metadata.
+ *
+ * @param schema - Any Zod schema instance.
+ * @returns A JSON Schema-compatible plain object.
+ *
+ * @example
+ * ```ts
+ * const jsonSchema = lowerZodToJsonSchema(z.object({ name: z.string(), age: z.number().optional() }));
+ * // → { type: 'object', properties: { name: { type: 'string' }, age: { type: 'number' } }, required: ['name'] }
+ * ```
+ */
+export function lowerZodToJsonSchema(schema) {
+    // Access Zod v4 internals via `_def`; the top-level `_def.type` is the discriminant.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const def = schema._def;
+    if (!def)
+        return {};
+    // In Zod v4 the discriminant is `_def.type` (a plain string literal).
+    const typeName = def.type;
+    switch (typeName) {
+        case 'string':
+            return { type: 'string' };
+        case 'number':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'null':
+            return { type: 'null' };
+        case 'enum': {
+            // Zod v4: def.entries is Record<string, string> — extract the values array.
+            const entries = def.entries;
+            return { enum: Object.values(entries) };
+        }
+        case 'array': {
+            // Zod v4: def.element holds the inner schema instance.
+            return {
+                type: 'array',
+                items: lowerZodToJsonSchema(def.element),
+            };
+        }
+        case 'object': {
+            const properties = {};
+            const required = [];
+            // Zod v4: def.shape is a plain Record<string, ZodType> (not a function as in Zod v3).
+            const shape = def.shape;
+            for (const [key, fieldSchema] of Object.entries(shape)) {
+                properties[key] = lowerZodToJsonSchema(fieldSchema);
+                // A field is required unless its outermost wrapper is optional or has a default.
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const fieldType = fieldSchema._def?.type;
+                if (fieldType !== 'optional' && fieldType !== 'default') {
+                    required.push(key);
+                }
+            }
+            return {
+                type: 'object',
+                properties,
+                ...(required.length > 0 ? { required } : {}),
+            };
+        }
+        case 'optional':
+            // Unwrap; optionality is expressed via absence from `required`, not in the field schema.
+            return lowerZodToJsonSchema(def.innerType);
+        case 'default':
+            // Unwrap; defaults are runtime concerns, not JSON Schema concerns for our use case.
+            return lowerZodToJsonSchema(def.innerType);
+        default:
+            // Unknown / unsupported Zod type — return empty schema (treat as untyped).
+            return {};
+    }
+}
+//# sourceMappingURL=SchemaLowering.js.map

package/dist/orchestration/compiler/SchemaLowering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaLowering.js","sourceRoot":"","sources":["../../../src/orchestration/compiler/SchemaLowering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAe;IAClD,qFAAqF;IACrF,8DAA8D;IAC9D,MAAM,GAAG,GAAI,MAAc,CAAC,IAA2C,CAAC;IACxE,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IAEpB,sEAAsE;IACtE,MAAM,QAAQ,GAAG,GAAG,CAAC,IAA0B,CAAC;IAEhD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ;YACX,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAE5B,KAAK,QAAQ;YACX,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAE5B,KAAK,SAAS;YACZ,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAE7B,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAE1B,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,4EAA4E;YAC5E,MAAM,OAAO,GAAG,GAAG,CAAC,OAAiC,CAAC;YACtD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,uDAAuD;YACvD,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,oBAAoB,CAAC,GAAG,CAAC,OAAkB,CAAC;aACpD,CAAC;QACJ,CAAC;QAED,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,UAAU,GAA4B,EAAE,CAAC;YAC/C,MAAM,QAAQ,GAAa,EAAE,CAAC;YAE9B,sFAAsF;YACtF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAgC,CAAC;YAEnD,KAAK,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvD,UAAU,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;gBAEpD,iFAAiF;gBACjF,8DAA8D;gBAC9D,MAAM,SAAS,GAAK,WAAmB,CAAC,IAA4C,EAAE,IAA0B,CAAC;gBACjH,IAAI,SAAS,KAAK,UAAU,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;oBACxD,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC;YAED,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,UAAU;gBACV,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7C,CAAC;QACJ,CAAC;QAED,KAAK,UAAU;YACb,yFAAyF;YACzF,OAAO,oBAAoB,CAAC,GAAG,CAAC,SAAoB,CAAC,CAAC;QAExD,KAAK,SAAS;YACZ,oFAAoF;YACpF,OAAO,oBAAoB,CAAC,GAAG,CAAC,SAAoB,CAAC,CAAC;QAExD;YACE,2EAA2E;YAC3E,OAAO,EAAE,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/orchestration/compiler/Validator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file Validator.ts
+ * @description Static graph validator for `CompiledExecutionGraph` IR objects.
+ *
+ * Validation is split into two severity levels:
+ *   - **errors**   — structural problems that will cause runtime failures (missing entry/exit
+ *     points, dangling edge references, cycles when acyclicity is required).
+ *   - **warnings** — non-fatal issues worth investigating (unreachable nodes).
+ *
+ * The validator delegates cycle detection and reachability analysis to `NodeScheduler`,
+ * which already implements Kahn's algorithm and DFS reachability traversal.
+ */
+import type { CompiledExecutionGraph } from '../ir/types.js';
+/**
+ * The result returned by `GraphValidator.validate()`.
+ *
+ * `valid` is `true` iff `errors` is empty — warnings do not affect validity.
+ */
+export interface ValidationResult {
+    /** `true` when no structural errors were found. */
+    valid: boolean;
+    /** Fatal structural problems that would prevent correct execution. */
+    errors: string[];
+    /** Non-fatal issues that should be reviewed but do not block execution. */
+    warnings: string[];
+}
+/**
+ * Static validator for compiled execution graphs.
+ *
+ * Runs a suite of structural checks against a `CompiledExecutionGraph`:
+ *
+ * 1. **Cycle detection** — rejects cyclic graphs when `requireAcyclic` is not `false`.
+ * 2. **Unreachable nodes** — warns when one or more nodes cannot be reached from `__START__`.
+ * 3. **Edge reference integrity** — errors when an edge's source/target names a non-existent node
+ *    (ignoring the sentinel values `__START__` and `__END__`).
+ * 4. **Entry point** — errors when no edge originates from `__START__`.
+ * 5. **Exit point** — errors when no edge terminates at `__END__`.
+ *
+ * @example
+ * ```ts
+ * const result = GraphValidator.validate(graph, { requireAcyclic: true });
+ * if (!result.valid) {
+ *   throw new Error(result.errors.join('\n'));
+ * }
+ * ```
+ */
+export declare class GraphValidator {
+    /**
+     * Validates a compiled execution graph.
+     *
+     * @param graph   - The `CompiledExecutionGraph` produced by a compiler pass.
+     * @param options - Optional validation flags.
+     * @param options.requireAcyclic - When `true` (the default) any cycle is treated as an error.
+     *   Pass `false` to allow cyclic graphs (e.g. iterative agent loops).
+     * @returns A `ValidationResult` describing errors and warnings found.
+     */
+    static validate(graph: CompiledExecutionGraph, options?: {
+        requireAcyclic?: boolean;
+    }): ValidationResult;
+}
+//# sourceMappingURL=Validator.d.ts.map

package/dist/orchestration/compiler/Validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Validator.d.ts","sourceRoot":"","sources":["../../../src/orchestration/compiler/Validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAO7D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAc;IACzB;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CACb,KAAK,EAAE,sBAAsB,EAC7B,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GACrC,gBAAgB;CA8DpB"}