@framers/agentos 0.1.69 → 0.1.71

package/dist/orchestration/compiler/Validator.js

@@ -0,0 +1,96 @@
+/**
+ * @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 { NodeScheduler } from '../runtime/NodeScheduler.js';
+// ---------------------------------------------------------------------------
+// GraphValidator
+// ---------------------------------------------------------------------------
+/**
+ * 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 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, options) {
+        const errors = [];
+        const warnings = [];
+        // Delegate cycle detection and reachability analysis to NodeScheduler.
+        const scheduler = new NodeScheduler(graph.nodes, graph.edges);
+        // -----------------------------------------------------------------------
+        // 1. Cycle detection
+        // -----------------------------------------------------------------------
+        // Default behaviour: acyclicity is required.  Authors opt into cycles by
+        // explicitly passing { requireAcyclic: false }.
+        if (options?.requireAcyclic !== false && scheduler.hasCycles()) {
+            errors.push('Graph contains a cycle — cycles are not allowed when requireAcyclic is true');
+        }
+        // -----------------------------------------------------------------------
+        // 2. Unreachable nodes
+        // -----------------------------------------------------------------------
+        const unreachable = scheduler.getUnreachableNodes();
+        if (unreachable.length > 0) {
+            warnings.push(`Unreachable nodes detected: ${unreachable.join(', ')}`);
+        }
+        // -----------------------------------------------------------------------
+        // 3. Edge reference integrity
+        // -----------------------------------------------------------------------
+        // Build a fast-lookup set of declared node ids.
+        const nodeIds = new Set(graph.nodes.map((n) => n.id));
+        for (const edge of graph.edges) {
+            // __START__ and __END__ are virtual sentinels — they are never in graph.nodes.
+            if (edge.source !== '__START__' && !nodeIds.has(edge.source)) {
+                errors.push(`Edge ${edge.id} references unknown source node: ${edge.source}`);
+            }
+            if (edge.target !== '__END__' && !nodeIds.has(edge.target)) {
+                errors.push(`Edge ${edge.id} references unknown target node: ${edge.target}`);
+            }
+        }
+        // -----------------------------------------------------------------------
+        // 4. Entry point check
+        // -----------------------------------------------------------------------
+        if (!graph.edges.some((e) => e.source === '__START__')) {
+            errors.push('No edges from START — graph has no entry point');
+        }
+        // -----------------------------------------------------------------------
+        // 5. Exit point check
+        // -----------------------------------------------------------------------
+        if (!graph.edges.some((e) => e.target === '__END__')) {
+            errors.push('No edges to END — graph has no exit point');
+        }
+        return { valid: errors.length === 0, errors, warnings };
+    }
+}
+//# sourceMappingURL=Validator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Validator.js","sourceRoot":"","sources":["../../../src/orchestration/compiler/Validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAoB5D,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,cAAc;IACzB;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CACb,KAA6B,EAC7B,OAAsC;QAEtC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAE9B,uEAAuE;QACvE,MAAM,SAAS,GAAG,IAAI,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAE9D,0EAA0E;QAC1E,qBAAqB;QACrB,0EAA0E;QAC1E,yEAAyE;QACzE,gDAAgD;QAChD,IAAI,OAAO,EAAE,cAAc,KAAK,KAAK,IAAI,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC;YAC/D,MAAM,CAAC,IAAI,CACT,6EAA6E,CAC9E,CAAC;QACJ,CAAC;QAED,0EAA0E;QAC1E,uBAAuB;QACvB,0EAA0E;QAC1E,MAAM,WAAW,GAAG,SAAS,CAAC,mBAAmB,EAAE,CAAC;QACpD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,+BAA+B,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,0EAA0E;QAC1E,8BAA8B;QAC9B,0EAA0E;QAC1E,gDAAgD;QAChD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEtD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC/B,+EAA+E;YAC/E,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7D,MAAM,CAAC,IAAI,CACT,QAAQ,IAAI,CAAC,EAAE,oCAAoC,IAAI,CAAC,MAAM,EAAE,CACjE,CAAC;YACJ,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3D,MAAM,CAAC,IAAI,CACT,QAAQ,IAAI,CAAC,EAAE,oCAAoC,IAAI,CAAC,MAAM,EAAE,CACjE,CAAC;YACJ,CAAC;QACH,CAAC;QAED,0EAA0E;QAC1E,uBAAuB;QACvB,0EAA0E;QAC1E,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,EAAE,CAAC;YACvD,MAAM,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;QAChE,CAAC;QAED,0EAA0E;QAC1E,sBAAsB;QACtB,0EAA0E;QAC1E,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,EAAE,CAAC;YACrD,MAAM,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;QAC3D,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC1D,CAAC;CACF"}

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

@@ -0,0 +1,16 @@
+/**
+ * @file index.ts
+ * @description Barrel export for the orchestration compiler sub-package.
+ *
+ * Exposes schema lowering utilities and the static graph validator used during
+ * the compilation pipeline that transforms author-facing graph/workflow/mission
+ * definitions into `CompiledExecutionGraph` IR objects.
+ */
+export { lowerZodToJsonSchema } from './SchemaLowering.js';
+export { GraphValidator } from './Validator.js';
+export type { ValidationResult } from './Validator.js';
+export { GraphCompiler } from './GraphCompiler.js';
+export type { GraphCompilerInput } from './GraphCompiler.js';
+export { MissionCompiler } from './MissionCompiler.js';
+export type { MissionConfig, SimplePlan } from './MissionCompiler.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/orchestration/compiler/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/orchestration/compiler/index.js

@@ -0,0 +1,13 @@
+/**
+ * @file index.ts
+ * @description Barrel export for the orchestration compiler sub-package.
+ *
+ * Exposes schema lowering utilities and the static graph validator used during
+ * the compilation pipeline that transforms author-facing graph/workflow/mission
+ * definitions into `CompiledExecutionGraph` IR objects.
+ */
+export { lowerZodToJsonSchema } from './SchemaLowering.js';
+export { GraphValidator } from './Validator.js';
+export { GraphCompiler } from './GraphCompiler.js';
+export { MissionCompiler } from './MissionCompiler.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/orchestration/compiler/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/orchestration/events/GraphEvent.d.ts

@@ -0,0 +1,233 @@
+/**
+ * @file GraphEvent.ts
+ * @description Discriminated union of all runtime events emitted during an AgentOS graph run,
+ * plus a `GraphEventEmitter` that supports both listener-based and async-iterable consumption.
+ *
+ * Events are emitted in strict causal order within a single run. Consumers may subscribe via
+ * `on()` / `off()` for push-based handling, or via `stream()` for pull-based async iteration.
+ */
+import type { GraphState } from '../ir/types.js';
+/**
+ * All runtime events emitted by the graph executor.
+ *
+ * Every variant carries a `type` discriminant so consumers can narrow with a
+ * simple `switch (event.type)` or exhaustive-check library.
+ */
+export type GraphEvent = 
+/** Emitted once when the executor accepts a new run request. */
+{
+    type: 'run_start';
+    runId: string;
+    graphId: string;
+}
+/** Emitted immediately before a node's executor is called. */
+ | {
+    type: 'node_start';
+    nodeId: string;
+    state: Partial<GraphState>;
+}
+/**
+ * Emitted after a node's executor returns successfully.
+ * `durationMs` is wall-clock time from `node_start` to `node_end`.
+ */
+ | {
+    type: 'node_end';
+    nodeId: string;
+    output: unknown;
+    durationMs: number;
+}
+/** Emitted when the executor resolves a routing condition and moves to the next node. */
+ | {
+    type: 'edge_transition';
+    sourceId: string;
+    targetId: string;
+    edgeType: string;
+}
+/**
+ * Streaming token delta from an LLM (GMI) node.
+ * Multiple deltas are emitted per node; concatenate `content` to reconstruct the full response.
+ */
+ | {
+    type: 'text_delta';
+    nodeId: string;
+    content: string;
+}
+/** Emitted when a node issues a tool call to the tool catalogue. */
+ | {
+    type: 'tool_call';
+    nodeId: string;
+    toolName: string;
+    args: unknown;
+}
+/** Emitted when a tool call returns (whether success or structured error). */
+ | {
+    type: 'tool_result';
+    nodeId: string;
+    toolName: string;
+    result: unknown;
+}
+/**
+ * Emitted after each guardrail evaluation.
+ * `passed: false` indicates a violation; `action` mirrors `GuardrailPolicy.onViolation`.
+ */
+ | {
+    type: 'guardrail_result';
+    nodeId: string;
+    guardrailId: string;
+    passed: boolean;
+    action: string;
+}
+/** Emitted after the runtime successfully persists a checkpoint snapshot. */
+ | {
+    type: 'checkpoint_saved';
+    checkpointId: string;
+    nodeId: string;
+}
+/**
+ * Emitted when graph execution is suspended mid-run.
+ * - `human_approval`     — node requires operator sign-off before proceeding.
+ * - `error`              — unrecoverable error after exhausting retry budget.
+ * - `guardrail_violation` — a `block` guardrail fired, halting the run.
+ */
+ | {
+    type: 'interrupt';
+    nodeId: string;
+    reason: 'human_approval' | 'error' | 'guardrail_violation';
+}
+/** Emitted after memory traces are loaded into `GraphState.memory` for a node. */
+ | {
+    type: 'memory_read';
+    nodeId: string;
+    traceCount: number;
+}
+/** Emitted after a memory trace is staged or committed for a node. */
+ | {
+    type: 'memory_write';
+    nodeId: string;
+    traceType: string;
+}
+/** Emitted after `DiscoveryPolicy`-triggered capability discovery completes. */
+ | {
+    type: 'discovery_result';
+    nodeId: string;
+    toolsFound: string[];
+}
+/**
+ * Emitted once when the graph run concludes normally.
+ * `totalDurationMs` is wall-clock time from `run_start` to `run_end`.
+ */
+ | {
+    type: 'run_end';
+    runId: string;
+    finalOutput: unknown;
+    totalDurationMs: number;
+}
+/** Emitted when a node's wall-clock execution time exceeds `GraphNode.timeout`. */
+ | {
+    type: 'node_timeout';
+    nodeId: string;
+    timeoutMs: number;
+}
+/**
+ * Emitted for unhandled exceptions or structured runtime errors.
+ * `nodeId` is absent for graph-level errors that occur outside any node's scope.
+ */
+ | {
+    type: 'error';
+    nodeId?: string;
+    error: {
+        message: string;
+        code: string;
+    };
+};
+/**
+ * Lightweight event emitter for `GraphEvent` values.
+ *
+ * Supports both:
+ * - **Push-based** consumption via `on()` / `off()` callbacks.
+ * - **Pull-based** consumption via the `stream()` async generator.
+ *
+ * The emitter is single-use: once `close()` is called it is permanently closed
+ * and subsequent `emit()` calls are silently ignored.
+ *
+ * @example
+ * ```ts
+ * const emitter = new GraphEventEmitter();
+ *
+ * // Pull-based — collect events in order
+ * async function consume() {
+ *   for await (const event of emitter.stream()) {
+ *     console.log(event.type);
+ *   }
+ * }
+ *
+ * emitter.emit({ type: 'run_start', runId: 'r1', graphId: 'g1' });
+ * emitter.close();
+ * await consume(); // logs 'run_start'
+ * ```
+ */
+export declare class GraphEventEmitter {
+    /** Registered push-based listener callbacks. */
+    private readonly listeners;
+    /**
+     * `true` after `close()` has been called. Once closed, `emit()` becomes a no-op
+     * and all active `stream()` generators are drained and terminated.
+     */
+    private closed;
+    /**
+     * Registers a callback that is invoked synchronously for every subsequent `emit()` call.
+     *
+     * @param listener - Function to call with each emitted `GraphEvent`.
+     */
+    on(listener: (event: GraphEvent) => void): void;
+    /**
+     * Removes a previously registered listener.
+     * If the listener was not registered, this is a no-op.
+     *
+     * @param listener - The exact function reference passed to `on()`.
+     */
+    off(listener: (event: GraphEvent) => void): void;
+    /**
+     * Dispatches `event` to all registered listeners and any active `stream()` generators.
+     * If `close()` has already been called, this method is a no-op.
+     *
+     * @param event - The `GraphEvent` to dispatch.
+     */
+    emit(event: GraphEvent): void;
+    /**
+     * Permanently closes the emitter.
+     *
+     * - Future `emit()` calls are silently ignored.
+     * - Active `stream()` generators are signalled to drain their queues and return.
+     */
+    close(): void;
+    /**
+     * Internal set of per-stream event dispatch functions.
+     * Each active `stream()` generator registers one entry here.
+     */
+    private readonly streamDispatchers;
+    /**
+     * Internal set of per-stream close signals.
+     * Each active `stream()` generator registers one entry here.
+     */
+    private readonly streamCompleters;
+    /**
+     * Returns an `AsyncGenerator` that yields every `GraphEvent` emitted after the
+     * call to `stream()`, in the exact order they were emitted.
+     *
+     * The generator completes (returns) when `close()` is called on the emitter
+     * and any queued events have been yielded.
+     *
+     * Multiple concurrent `stream()` calls are supported; each gets an independent
+     * copy of the event stream.
+     *
+     * @example
+     * ```ts
+     * for await (const event of emitter.stream()) {
+     *   if (event.type === 'run_end') break;
+     * }
+     * ```
+     */
+    stream(): AsyncGenerator<GraphEvent>;
+}
+//# sourceMappingURL=GraphEvent.d.ts.map

package/dist/orchestration/events/GraphEvent.d.ts.map

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

package/dist/orchestration/events/GraphEvent.js

@@ -0,0 +1,203 @@
+/**
+ * @file GraphEvent.ts
+ * @description Discriminated union of all runtime events emitted during an AgentOS graph run,
+ * plus a `GraphEventEmitter` that supports both listener-based and async-iterable consumption.
+ *
+ * Events are emitted in strict causal order within a single run. Consumers may subscribe via
+ * `on()` / `off()` for push-based handling, or via `stream()` for pull-based async iteration.
+ */
+// ---------------------------------------------------------------------------
+// GraphEventEmitter
+// ---------------------------------------------------------------------------
+/**
+ * Lightweight event emitter for `GraphEvent` values.
+ *
+ * Supports both:
+ * - **Push-based** consumption via `on()` / `off()` callbacks.
+ * - **Pull-based** consumption via the `stream()` async generator.
+ *
+ * The emitter is single-use: once `close()` is called it is permanently closed
+ * and subsequent `emit()` calls are silently ignored.
+ *
+ * @example
+ * ```ts
+ * const emitter = new GraphEventEmitter();
+ *
+ * // Pull-based — collect events in order
+ * async function consume() {
+ *   for await (const event of emitter.stream()) {
+ *     console.log(event.type);
+ *   }
+ * }
+ *
+ * emitter.emit({ type: 'run_start', runId: 'r1', graphId: 'g1' });
+ * emitter.close();
+ * await consume(); // logs 'run_start'
+ * ```
+ */
+export class GraphEventEmitter {
+    constructor() {
+        /** Registered push-based listener callbacks. */
+        this.listeners = [];
+        /**
+         * `true` after `close()` has been called. Once closed, `emit()` becomes a no-op
+         * and all active `stream()` generators are drained and terminated.
+         */
+        this.closed = false;
+        // ---------------------------------------------------------------------------
+        // Pull-based API (async iterable)
+        // ---------------------------------------------------------------------------
+        /**
+         * Internal set of per-stream event dispatch functions.
+         * Each active `stream()` generator registers one entry here.
+         */
+        this.streamDispatchers = new Set();
+        /**
+         * Internal set of per-stream close signals.
+         * Each active `stream()` generator registers one entry here.
+         */
+        this.streamCompleters = new Set();
+    }
+    // ---------------------------------------------------------------------------
+    // Push-based API
+    // ---------------------------------------------------------------------------
+    /**
+     * Registers a callback that is invoked synchronously for every subsequent `emit()` call.
+     *
+     * @param listener - Function to call with each emitted `GraphEvent`.
+     */
+    on(listener) {
+        this.listeners.push(listener);
+    }
+    /**
+     * Removes a previously registered listener.
+     * If the listener was not registered, this is a no-op.
+     *
+     * @param listener - The exact function reference passed to `on()`.
+     */
+    off(listener) {
+        const index = this.listeners.indexOf(listener);
+        if (index !== -1) {
+            this.listeners.splice(index, 1);
+        }
+    }
+    /**
+     * Dispatches `event` to all registered listeners and any active `stream()` generators.
+     * If `close()` has already been called, this method is a no-op.
+     *
+     * @param event - The `GraphEvent` to dispatch.
+     */
+    emit(event) {
+        if (this.closed)
+            return;
+        // Notify all push-based listeners synchronously.
+        for (const listener of this.listeners) {
+            listener(event);
+        }
+        // Notify all active stream generators via their internal dispatch functions.
+        for (const dispatch of this.streamDispatchers) {
+            dispatch(event);
+        }
+    }
+    /**
+     * Permanently closes the emitter.
+     *
+     * - Future `emit()` calls are silently ignored.
+     * - Active `stream()` generators are signalled to drain their queues and return.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Signal each active stream generator to complete.
+        for (const complete of this.streamCompleters) {
+            complete();
+        }
+    }
+    /**
+     * Returns an `AsyncGenerator` that yields every `GraphEvent` emitted after the
+     * call to `stream()`, in the exact order they were emitted.
+     *
+     * The generator completes (returns) when `close()` is called on the emitter
+     * and any queued events have been yielded.
+     *
+     * Multiple concurrent `stream()` calls are supported; each gets an independent
+     * copy of the event stream.
+     *
+     * @example
+     * ```ts
+     * for await (const event of emitter.stream()) {
+     *   if (event.type === 'run_end') break;
+     * }
+     * ```
+     */
+    async *stream() {
+        // Per-generator queue of events waiting to be yielded.
+        const queue = [];
+        // When non-null, a pending `await next` in the generator loop is resolved here.
+        let pendingResolve = null;
+        /**
+         * Called by `emit()` — either resolves a waiting generator or enqueues the event.
+         */
+        const dispatch = (event) => {
+            if (pendingResolve !== null) {
+                const resolve = pendingResolve;
+                pendingResolve = null;
+                resolve({ value: event, done: false });
+            }
+            else {
+                queue.push(event);
+            }
+        };
+        /** Called by `close()` — wakes up a waiting generator so it can drain and exit. */
+        const complete = () => {
+            if (pendingResolve !== null) {
+                const resolve = pendingResolve;
+                pendingResolve = null;
+                // Signal the generator loop to re-check the closed flag.
+                resolve({ value: undefined, done: true });
+            }
+        };
+        this.streamDispatchers.add(dispatch);
+        this.streamCompleters.add(complete);
+        try {
+            // If the emitter was already closed before stream() was called, drain nothing.
+            while (!this.closed || queue.length > 0) {
+                if (queue.length > 0) {
+                    // There are queued events — yield them immediately without suspending.
+                    yield queue.shift();
+                }
+                else if (this.closed) {
+                    // Queue is empty and emitter is closed — we are done.
+                    break;
+                }
+                else {
+                    // Queue is empty and emitter is still open — suspend until the next event.
+                    const result = await new Promise((resolve) => {
+                        pendingResolve = resolve;
+                    });
+                    if (result.done) {
+                        // `complete()` was called — drain remaining queue items then exit.
+                        while (queue.length > 0) {
+                            yield queue.shift();
+                        }
+                        break;
+                    }
+                    yield result.value;
+                }
+            }
+        }
+        finally {
+            // Always clean up registrations, even if the caller breaks out of the for-await loop.
+            this.streamDispatchers.delete(dispatch);
+            this.streamCompleters.delete(complete);
+            if (pendingResolve !== null) {
+                // Resolve any dangling promise to avoid memory leaks.
+                const resolve = pendingResolve;
+                pendingResolve = null;
+                resolve({ value: undefined, done: true });
+            }
+        }
+    }
+}
+//# sourceMappingURL=GraphEvent.js.map

package/dist/orchestration/events/GraphEvent.js.map

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

package/dist/orchestration/events/index.d.ts

@@ -0,0 +1,2 @@
+export * from './GraphEvent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/orchestration/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/orchestration/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/orchestration/events/index.js

@@ -0,0 +1,2 @@
+export * from './GraphEvent.js';
+//# sourceMappingURL=index.js.map

package/dist/orchestration/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/orchestration/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/orchestration/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file index.ts
+ * @description Barrel re-exports for the AgentOS orchestration layer.
+ *
+ * The orchestration subsystem provides:
+ * - **IR**: Intermediate representation types and utilities for graph-based workflows
+ * - **Events**: Event definitions and infrastructure for orchestration runtime
+ * - **Checkpoint**: Checkpoint persistence and recovery for long-running workflows
+ * - **Runtime**: State management, scheduling, execution, and graph runtime engines
+ *
+ * Consumers should import from this module rather than from individual subdirectories
+ * to keep import paths stable across internal refactors.
+ */
+export * from './ir/index.js';
+export * from './events/index.js';
+export * from './checkpoint/index.js';
+export * from './runtime/index.js';
+export * from './builders/index.js';
+export * from './compiler/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/orchestration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/orchestration/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,cAAc,eAAe,CAAC;AAE9B,cAAc,mBAAmB,CAAC;AAElC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,qBAAqB,CAAC"}

package/dist/orchestration/index.js

@@ -0,0 +1,26 @@
+/**
+ * @file index.ts
+ * @description Barrel re-exports for the AgentOS orchestration layer.
+ *
+ * The orchestration subsystem provides:
+ * - **IR**: Intermediate representation types and utilities for graph-based workflows
+ * - **Events**: Event definitions and infrastructure for orchestration runtime
+ * - **Checkpoint**: Checkpoint persistence and recovery for long-running workflows
+ * - **Runtime**: State management, scheduling, execution, and graph runtime engines
+ *
+ * Consumers should import from this module rather than from individual subdirectories
+ * to keep import paths stable across internal refactors.
+ */
+// IR types
+export * from './ir/index.js';
+// Events
+export * from './events/index.js';
+// Checkpoint
+export * from './checkpoint/index.js';
+// Runtime
+export * from './runtime/index.js';
+// Builders (public API)
+export * from './builders/index.js';
+// Compiler (advanced use)
+export * from './compiler/index.js';
+//# sourceMappingURL=index.js.map

package/dist/orchestration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/orchestration/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,WAAW;AACX,cAAc,eAAe,CAAC;AAC9B,SAAS;AACT,cAAc,mBAAmB,CAAC;AAClC,aAAa;AACb,cAAc,uBAAuB,CAAC;AACtC,UAAU;AACV,cAAc,oBAAoB,CAAC;AACnC,wBAAwB;AACxB,cAAc,qBAAqB,CAAC;AACpC,0BAA0B;AAC1B,cAAc,qBAAqB,CAAC"}

package/dist/orchestration/ir/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map