@framers/agentos 0.1.69 → 0.1.70

package/dist/orchestration/builders/MissionBuilder.js

@@ -0,0 +1,321 @@
+/**
+ * @file MissionBuilder.ts
+ * @description Fluent builder API for goal-oriented mission authoring.
+ *
+ * The `mission()` factory function returns a `MissionBuilder` that collects
+ * configuration through a chainable interface before compiling the mission into
+ * a `CompiledMission` — the execution-ready wrapper that exposes `invoke()`,
+ * `stream()`, `resume()`, `explain()`, and `toIR()`.
+ *
+ * Typical usage:
+ * ```ts
+ * const researchMission = mission('research')
+ *   .input(z.object({ topic: z.string() }))
+ *   .goal('Research {{topic}} and produce a concise summary')
+ *   .returns(z.object({ summary: z.string() }))
+ *   .planner({ strategy: 'linear', maxSteps: 6 })
+ *   .policy({ guardrails: ['content-safety'] })
+ *   .compile();
+ *
+ * const result = await researchMission.invoke({ topic: 'quantum computing' });
+ * ```
+ */
+import { InMemoryCheckpointStore } from '../checkpoint/InMemoryCheckpointStore.js';
+import { MissionCompiler } from '../compiler/MissionCompiler.js';
+import { GraphRuntime } from '../runtime/GraphRuntime.js';
+import { NodeExecutor } from '../runtime/NodeExecutor.js';
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Create a new `MissionBuilder` for the named mission.
+ *
+ * @param name - Human-readable mission name; used as the compiled graph's display name
+ *               and as a stable slug prefix for run ids and checkpoint keys.
+ * @returns A fresh `MissionBuilder` instance ready to be configured.
+ *
+ * @example
+ * ```ts
+ * const m = mission('summarise-article')
+ *   .input(inputSchema)
+ *   .goal('Summarise {{url}} in three bullet points')
+ *   .returns(outputSchema)
+ *   .planner({ strategy: 'linear', maxSteps: 4 })
+ *   .compile();
+ * ```
+ */
+export function mission(name) {
+    return new MissionBuilder(name);
+}
+// ---------------------------------------------------------------------------
+// MissionBuilder
+// ---------------------------------------------------------------------------
+/**
+ * Fluent builder that collects mission configuration and validates it at `.compile()` time.
+ *
+ * All setter methods return `this` for chaining.  No compilation work is performed until
+ * `.compile()` is called, ensuring fast construction of mission objects at module load time.
+ */
+export class MissionBuilder {
+    /**
+     * @param name - Display name for this mission; passed through to the compiled graph.
+     */
+    constructor(name) {
+        this.name = name;
+        /** @internal Goal prompt template with optional `{{variable}}` placeholders. */
+        this._goalTemplate = '';
+        /** @internal Declarative anchor node splice descriptors. */
+        this._anchors = [];
+    }
+    // -------------------------------------------------------------------------
+    // Builder setters
+    // -------------------------------------------------------------------------
+    /**
+     * Declare the input schema for this mission.
+     *
+     * Accepts a Zod schema object or a plain JSON-Schema `Record<string, unknown>`.
+     * The schema is stored in the compiled graph's `stateSchema.input` field and used
+     * by the runtime for optional input validation.
+     *
+     * @param schema - Zod or JSON-Schema object describing the expected input payload.
+     */
+    input(schema) {
+        this._inputSchema = schema;
+        return this;
+    }
+    /**
+     * Set the goal template for this mission.
+     *
+     * The template is a free-form string that describes what the mission should achieve.
+     * It may include `{{variable}}` placeholders that will be interpolated with values
+     * from the input payload at plan generation time.
+     *
+     * Example: `'Research {{topic}} and produce a concise summary'`
+     *
+     * @param template - Goal prompt template string.
+     */
+    goal(template) {
+        this._goalTemplate = template;
+        return this;
+    }
+    /**
+     * Declare the output (return) schema for this mission.
+     *
+     * Accepts a Zod schema object or a plain JSON-Schema `Record<string, unknown>`.
+     * The schema is stored in the compiled graph's `stateSchema.artifacts` field.
+     *
+     * @param schema - Zod or JSON-Schema object describing the expected artifact payload.
+     */
+    returns(schema) {
+        this._returnsSchema = schema;
+        return this;
+    }
+    /**
+     * Configure the planner used to decompose the goal into execution steps.
+     *
+     * @param config - Planner settings including strategy name, step budget, and
+     *                 per-node iteration and tool-parallelism caps.
+     */
+    planner(config) {
+        this._plannerConfig = config;
+        return this;
+    }
+    /**
+     * Apply mission-level policy overrides.
+     *
+     * Policies declared here are applied to **all** compiled nodes unless a node already
+     * carries its own policy declaration.  This is the preferred mechanism for setting
+     * blanket guardrails, memory consistency modes, or persona settings across a mission.
+     *
+     * @param config - Policy configuration object.
+     */
+    policy(config) {
+        this._policyConfig = config;
+        return this;
+    }
+    /**
+     * Declare an anchor node that will be spliced into the execution order.
+     *
+     * Anchors let callers inject pre-built `GraphNode` objects (e.g. specialised tool
+     * invocations, human-in-the-loop checkpoints, or validation guardrails) at precise
+     * positions within the phase-ordered plan without modifying the planner output.
+     *
+     * @param id          - Unique node id assigned to the anchor in the compiled graph.
+     * @param node        - Pre-built `GraphNode` (from `gmiNode`, `toolNode`, etc.).
+     * @param constraints - Placement constraints: phase, `after` / `before` ordering.
+     */
+    anchor(id, node, constraints) {
+        this._anchors.push({ id, node, constraints });
+        return this;
+    }
+    // -------------------------------------------------------------------------
+    // Compile
+    // -------------------------------------------------------------------------
+    /**
+     * Validate configuration and compile this mission into a `CompiledMission`.
+     *
+     * Required fields: `input`, `goal`, `returns`, `planner`.
+     * Throws with a descriptive message if any required field is missing.
+     *
+     * @param options                - Optional compilation overrides.
+     * @param options.checkpointStore - Custom checkpoint store; defaults to `InMemoryCheckpointStore`.
+     * @returns A `CompiledMission` ready to `invoke()`, `stream()`, or `explain()`.
+     * @throws {Error} When required builder fields are missing.
+     */
+    compile(options) {
+        if (!this._inputSchema) {
+            throw new Error('mission() requires .input() — input schema is required');
+        }
+        if (!this._goalTemplate) {
+            throw new Error('mission() requires .goal() — goal template is required');
+        }
+        if (!this._returnsSchema) {
+            throw new Error('mission() requires .returns() — returns schema is required');
+        }
+        if (!this._plannerConfig) {
+            throw new Error('mission() requires .planner() — planner config is required');
+        }
+        const config = {
+            name: this.name,
+            inputSchema: this._inputSchema,
+            goalTemplate: this._goalTemplate,
+            returnsSchema: this._returnsSchema,
+            plannerConfig: this._plannerConfig,
+            policyConfig: this._policyConfig,
+            anchors: this._anchors,
+        };
+        const store = options?.checkpointStore ?? new InMemoryCheckpointStore();
+        return new CompiledMission(config, store);
+    }
+}
+// ---------------------------------------------------------------------------
+// CompiledMission
+// ---------------------------------------------------------------------------
+/**
+ * Execution wrapper for a compiled mission.
+ *
+ * Lazily re-compiles the IR on each call so that changes to the underlying
+ * config are reflected without needing to rebuild the mission object.  In
+ * production callers typically compile once and reuse the `CompiledMission`
+ * for many invocations.
+ */
+export class CompiledMission {
+    /**
+     * @param config          - Frozen mission configuration snapshot.
+     * @param checkpointStore - Checkpoint persistence backend.
+     */
+    constructor(config, checkpointStore) {
+        this.config = config;
+        this.checkpointStore = checkpointStore;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Run `MissionCompiler.compile()` to produce a fresh `CompiledExecutionGraph`.
+     * Called lazily by each execution method so the IR is always up-to-date.
+     */
+    compileIR() {
+        return MissionCompiler.compile(this.config);
+    }
+    /**
+     * Create a new `GraphRuntime` bound to this mission's checkpoint store.
+     * A fresh runtime is created per invocation to ensure full call isolation.
+     */
+    createRuntime() {
+        return new GraphRuntime({
+            checkpointStore: this.checkpointStore,
+            nodeExecutor: new NodeExecutor({}),
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Execution API
+    // -------------------------------------------------------------------------
+    /**
+     * Execute the mission to completion and return the final artifacts.
+     *
+     * @param input - Input payload conforming to the mission's `inputSchema`.
+     * @returns The final `GraphState.artifacts` value once all nodes have completed.
+     */
+    async invoke(input) {
+        const ir = this.compileIR();
+        return this.createRuntime().invoke(ir, input);
+    }
+    /**
+     * Execute the mission while yielding `GraphEvent` values at each step.
+     *
+     * Useful for streaming progress updates to a UI or logging pipeline.
+     *
+     * @param input - Input payload conforming to the mission's `inputSchema`.
+     * @yields `GraphEvent` objects emitted by the runtime at each node lifecycle point.
+     */
+    async *stream(input) {
+        const ir = this.compileIR();
+        yield* this.createRuntime().stream(ir, input);
+    }
+    /**
+     * Resume a previously interrupted run from its latest checkpoint.
+     *
+     * @param checkpointId - Id of the checkpoint to restore (from `GraphState.checkpointId`).
+     * @param _patch       - Optional partial `GraphState` to merge before resuming (reserved).
+     * @returns The final `GraphState.artifacts` value once execution completes.
+     */
+    async resume(checkpointId, _patch) {
+        const ir = this.compileIR();
+        return this.createRuntime().resume(ir, checkpointId);
+    }
+    /**
+     * Retrieve a diagnostic snapshot of a completed or in-progress run.
+     *
+     * @param _runId - Run id assigned by the runtime at invocation time.
+     * @returns A `RunInspection`-shaped object (stub — full implementation in Task 17+).
+     */
+    async inspect(_runId) {
+        // Stub — RunInspection API wired in a future task
+        return {};
+    }
+    // -------------------------------------------------------------------------
+    // Introspection utilities
+    // -------------------------------------------------------------------------
+    /**
+     * Return a human-readable execution plan without actually running the mission.
+     *
+     * Useful for debugging, testing, and displaying "what will happen" summaries in UIs.
+     *
+     * @param _input - Input payload (currently unused; reserved for future goal interpolation).
+     * @returns An object containing:
+     *   - `steps`: flat array of `{ id, type, config }` descriptors for each node.
+     *   - `ir`: the full `CompiledExecutionGraph` for deeper inspection.
+     */
+    async explain(_input) {
+        const ir = this.compileIR();
+        return {
+            steps: ir.nodes.map(n => ({
+                id: n.id,
+                type: n.type,
+                config: n.executorConfig,
+            })),
+            ir,
+        };
+    }
+    /**
+     * Export the compiled plan as a static `CompiledExecutionGraph`.
+     *
+     * Allows callers to "graduate" a dynamically-planned mission to a fixed workflow or
+     * graph for performance-sensitive deployments where replanning is not desired.
+     *
+     * @returns The compiled IR, suitable for passing directly to `GraphRuntime`.
+     */
+    toWorkflow() {
+        return this.compileIR();
+    }
+    /**
+     * Alias of `toWorkflow()` — returns the compiled `CompiledExecutionGraph` IR.
+     *
+     * @returns The compiled IR.
+     */
+    toIR() {
+        return this.compileIR();
+    }
+}
+//# sourceMappingURL=MissionBuilder.js.map

package/dist/orchestration/builders/MissionBuilder.js.map

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

package/dist/orchestration/builders/WorkflowBuilder.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @file WorkflowBuilder.ts
+ * @description Fluent DSL for authoring deterministic, acyclic workflow graphs.
+ *
+ * `workflow()` is the sequential/pipeline-oriented authoring API in the AgentOS
+ * Unified Orchestration Layer. Unlike `AgentGraph` (which allows arbitrary directed
+ * graphs including cycles), every workflow is a strict DAG — cycles are detected and
+ * rejected at compile time.
+ *
+ * Supported step primitives:
+ * - `step()` / `then()` — a single named node (tool, GMI, or human).
+ * - `branch()` — a router + fan-out; branches rejoin at the next step.
+ * - `parallel()` — fan-out to N concurrent nodes that rejoin via merge reducers.
+ *
+ * All GMI steps default to `executionMode: 'single_turn'` to keep workflows
+ * deterministic and cost-bounded.
+ *
+ * @example
+ * ```ts
+ * const wf = workflow('summarize-and-tag')
+ *   .input(z.object({ text: z.string() }))
+ *   .returns(z.object({ summary: z.string(), tags: z.array(z.string()) }))
+ *   .step('fetch', { tool: 'web_fetch' })
+ *   .step('summarize', { gmi: { instructions: 'Summarize the document.' } })
+ *   .compile();
+ *
+ * const result = await wf.invoke({ text: 'hello world' });
+ * ```
+ */
+import type { CompiledExecutionGraph, MemoryPolicy, DiscoveryPolicy, GuardrailPolicy, BuiltinReducer, ReducerFn } from '../ir/types.js';
+import type { ICheckpointStore } from '../checkpoint/ICheckpointStore.js';
+import type { GraphEvent } from '../events/GraphEvent.js';
+/**
+ * Configuration for a single workflow step node.
+ *
+ * Exactly one of `tool`, `gmi`, `human`, `extension`, or `subgraph` must be provided
+ * to specify the execution strategy.  All remaining fields are optional policies.
+ */
+export interface StepConfig {
+    /** Name of a registered `ITool` to invoke. */
+    tool?: string;
+    /**
+     * General Model Invocation config. `executionMode` is always overridden to
+     * `'single_turn'` inside a workflow to keep execution deterministic.
+     */
+    gmi?: {
+        instructions: string;
+        /** Ignored at runtime — always coerced to `'single_turn'` by the workflow compiler. */
+        executionMode?: 'single_turn';
+        /** Hard cap on LLM output tokens for this step. */
+        maxTokens?: number;
+    };
+    /** Human-in-the-loop step; suspends the run until a human provides a response. */
+    human?: {
+        prompt: string;
+    };
+    /** Call a method on a registered extension. */
+    extension?: {
+        extensionId: string;
+        method: string;
+    };
+    /** Delegate to a previously compiled sub-workflow or agent graph. */
+    subgraph?: CompiledExecutionGraph;
+    /** Memory read/write policy for this step. */
+    memory?: MemoryPolicy;
+    /** Capability discovery policy applied before execution. */
+    discovery?: DiscoveryPolicy;
+    /** Declarative guardrail policy applied to input and/or output. */
+    guardrails?: GuardrailPolicy;
+    /** When `true`, execution suspends and waits for human approval before proceeding. */
+    requiresApproval?: boolean;
+    /** What to do when the step fails. */
+    onFailure?: 'abort' | 'skip' | 'retry';
+    /** Automatic retry configuration. Only used when `onFailure` is `'retry'`. */
+    retryPolicy?: {
+        maxAttempts: number;
+        backoff: 'fixed' | 'linear' | 'exponential';
+        backoffMs: number;
+    };
+    /** Maximum wall-clock execution time in milliseconds. */
+    timeout?: number;
+    /** Side-effect classification used by the runtime for scheduling decisions. */
+    effectClass?: 'pure' | 'read' | 'write' | 'external' | 'human';
+}
+/**
+ * Create a new `WorkflowBuilder` with the given human-readable name.
+ *
+ * @param name - Display name embedded in the compiled `CompiledExecutionGraph`.
+ * @returns A fresh `WorkflowBuilder` instance.
+ *
+ * @example
+ * ```ts
+ * const wf = workflow('my-pipeline')
+ *   .input(z.object({ query: z.string() }))
+ *   .returns(z.object({ answer: z.string() }))
+ *   .step('search', { tool: 'web_search' })
+ *   .step('answer', { gmi: { instructions: 'Answer the question.' } })
+ *   .compile();
+ * ```
+ */
+export declare function workflow(name: string): WorkflowBuilder;
+/**
+ * Fluent builder for deterministic DAG workflows.
+ *
+ * Steps are appended in declaration order and connected sequentially. Branch and
+ * parallel primitives fan out and automatically rejoin at the next declared step.
+ *
+ * Call `.compile()` to validate the graph (must be acyclic) and obtain a
+ * `CompiledWorkflow` ready for `invoke()`, `stream()`, or `resume()`.
+ */
+export declare class WorkflowBuilder {
+    /** Zod schema (or any plain object) representing `GraphState.input`. */
+    private inputSchema;
+    /** Zod schema (or any plain object) representing `GraphState.artifacts`. */
+    private returnsSchema;
+    /** Ordered list of steps declared by the author. */
+    private steps;
+    /** Human-readable name forwarded to the compiled graph. */
+    private readonly name;
+    /**
+     * @param name - Human-readable workflow name.
+     */
+    constructor(name: string);
+    /**
+     * Declare the input schema for this workflow.
+     *
+     * Accepts a Zod schema or any plain object; the value is forwarded to
+     * `GraphCompiler` which lowers it to JSON Schema via `lowerZodToJsonSchema`.
+     *
+     * @param schema - Input schema (Zod instance or plain JSON Schema object).
+     */
+    input(schema: any): this;
+    /**
+     * Declare the return (output artifacts) schema for this workflow.
+     *
+     * @param schema - Output schema (Zod instance or plain JSON Schema object).
+     */
+    returns(schema: any): this;
+    /**
+     * Append a single named step to the workflow.
+     *
+     * The step is connected from all current tail nodes and becomes the new
+     * single-element tail after it is added.
+     *
+     * @param id     - Unique step identifier within this workflow.
+     * @param config - Execution and policy configuration for the step.
+     */
+    step(id: string, config: StepConfig): this;
+    /**
+     * Alias for `step()` — reads more naturally when chaining sequential steps.
+     *
+     * @param id     - Unique step identifier.
+     * @param config - Execution and policy configuration.
+     */
+    then(id: string, config: StepConfig): this;
+    /**
+     * Append a conditional branch to the workflow.
+     *
+     * The `condition` function is evaluated at runtime against `GraphState` and must
+     * return one of the keys of `routes`. Each route becomes its own branch node; all
+     * branches become the collective tail that the next declared step connects from.
+     *
+     * @param condition - Routing function; return value must match a key in `routes`.
+     * @param routes    - Map of route key → step config for each branch arm.
+     */
+    branch(condition: (state: any) => string, routes: Record<string, StepConfig>): this;
+    /**
+     * Append a parallel fan-out to the workflow.
+     *
+     * All `steps` execute concurrently (subject to runtime scheduling). After all
+     * branches complete, their outputs are merged using the `join.merge` reducers.
+     * The parallel branch nodes collectively become the new tail.
+     *
+     * @param steps - Array of step configs to execute concurrently.
+     * @param join  - Fan-in configuration including merge strategy and reducers.
+     */
+    parallel(steps: StepConfig[], join: {
+        strategy: 'all' | 'any' | 'quorum';
+        quorumCount?: number;
+        merge: Record<string, BuiltinReducer | ReducerFn>;
+        timeout?: number;
+    }): this;
+    /**
+     * Compile the workflow into an executable `CompiledWorkflow`.
+     *
+     * Compilation steps:
+     * 1. Validate that `.input()` and `.returns()` schemas were declared.
+     * 2. Lower each `InternalStep` into `GraphNode` + `GraphEdge` IR objects,
+     *    threading `tailNodeIds` to connect steps sequentially.
+     * 3. Connect all final tail nodes to `END`.
+     * 4. Run `GraphCompiler.compile()` to produce a `CompiledExecutionGraph`.
+     * 5. Run `GraphValidator.validate()` with `{ requireAcyclic: true }` — throws on cycle.
+     * 6. Wrap in a `CompiledWorkflow` with a `GraphRuntime` backed by the given store.
+     *
+     * @param options - Optional compilation options.
+     * @param options.checkpointStore - Custom checkpoint backend; defaults to `InMemoryCheckpointStore`.
+     * @throws {Error} When `.input()` or `.returns()` was not called.
+     * @throws {Error} When the compiled graph contains a cycle (should never happen via this API).
+     */
+    compile(options?: {
+        checkpointStore?: ICheckpointStore;
+    }): CompiledWorkflow;
+    /**
+     * Lower a `StepConfig` into a `GraphNode` with the given `id`.
+     *
+     * Priority order for executor type selection:
+     * `tool` → `gmi` → `human` → `extension` → `subgraph` → fallback tool node.
+     *
+     * GMI nodes always receive `executionMode: 'single_turn'` regardless of what
+     * the author specified in `config.gmi.executionMode`.
+     *
+     * @param id     - Node id to assign.
+     * @param config - Caller-supplied step configuration.
+     * @returns A fully constructed `GraphNode` ready for the IR.
+     */
+    private configToNode;
+}
+/**
+ * An execution-ready workflow produced by `WorkflowBuilder.compile()`.
+ *
+ * Wraps a `CompiledExecutionGraph` and a `GraphRuntime`, exposing the same
+ * three execution modes as the raw runtime:
+ *
+ * - `invoke(input)` — run to completion and return final artifacts.
+ * - `stream(input)` — run while yielding `GraphEvent` values at each step.
+ * - `resume(checkpointId)` — restore an interrupted run from a checkpoint.
+ */
+export declare class CompiledWorkflow {
+    private readonly ir;
+    /** Underlying execution runtime. */
+    private readonly runtime;
+    /**
+     * @param ir              - The compiled execution graph (produced by `GraphCompiler`).
+     * @param checkpointStore - Checkpoint persistence backend.
+     */
+    constructor(ir: CompiledExecutionGraph, checkpointStore: ICheckpointStore);
+    /**
+     * Execute the workflow to completion and return the final `artifacts` payload.
+     *
+     * @param input - Must conform to the schema declared via `.input()`.
+     * @returns The `GraphState.artifacts` value after all nodes complete.
+     */
+    invoke(input: unknown): Promise<unknown>;
+    /**
+     * Execute the workflow while yielding `GraphEvent` values at each step boundary.
+     *
+     * @param input - Must conform to the schema declared via `.input()`.
+     * @yields {GraphEvent} Runtime events in causal order.
+     */
+    stream(input: unknown): AsyncIterable<GraphEvent>;
+    /**
+     * Resume a previously interrupted workflow run from its latest checkpoint.
+     *
+     * @param checkpointId - The run identifier returned when the original run was interrupted.
+     * @returns The final `GraphState.artifacts` value after resumption completes.
+     */
+    resume(checkpointId: string): Promise<unknown>;
+    /**
+     * Expose the compiled IR for inspection, serialisation, or subgraph composition.
+     *
+     * @returns The underlying `CompiledExecutionGraph`.
+     */
+    toIR(): CompiledExecutionGraph;
+}
+//# sourceMappingURL=WorkflowBuilder.d.ts.map

package/dist/orchestration/builders/WorkflowBuilder.d.ts.map

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