@executioncontrolprotocol/runtime 0.3.0

package/dist/engine/context-loader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Context loader — reads and validates ECP Context manifests from
+ * YAML or JSON files.
+ *
+ * @category Engine
+ */
+import type { ECPContext } from "@executioncontrolprotocol/spec";
+/**
+ * Load an ECP Context manifest from a YAML or JSON file.
+ *
+ * @param filePath - Absolute or relative path to the manifest.
+ * @returns The parsed Context object.
+ * @throws If the file cannot be read or parsed.
+ *
+ * @category Engine
+ */
+export declare function loadContext(filePath: string): ECPContext;
+/**
+ * Resolve input values for a Context run. Applies defaults for
+ * missing optional inputs and validates that all required inputs
+ * are provided.
+ *
+ * @param context - The loaded Context.
+ * @param supplied - Input values supplied by the caller.
+ * @returns Fully resolved input values.
+ * @throws If a required input is missing.
+ *
+ * @category Engine
+ */
+export declare function resolveInputs(context: ECPContext, supplied: Record<string, string | number | boolean>): Record<string, string | number | boolean>;
+//# sourceMappingURL=context-loader.d.ts.map

package/dist/engine/context-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-loader.d.ts","sourceRoot":"","sources":["../../src/engine/context-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAcjE;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAyCxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAClD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAe3C"}

package/dist/engine/context-loader.js

@@ -0,0 +1,90 @@
+/**
+ * Context loader — reads and validates ECP Context manifests from
+ * YAML or JSON files.
+ *
+ * @category Engine
+ */
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import yaml from "js-yaml";
+function hasExecutionObjects(ctx) {
+    if (ctx.executors && ctx.executors.length > 0) {
+        return true;
+    }
+    if (ctx.orchestrator) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Load an ECP Context manifest from a YAML or JSON file.
+ *
+ * @param filePath - Absolute or relative path to the manifest.
+ * @returns The parsed Context object.
+ * @throws If the file cannot be read or parsed.
+ *
+ * @category Engine
+ */
+export function loadContext(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    const ext = extname(filePath).toLowerCase();
+    let parsed;
+    if (ext === ".yaml" || ext === ".yml") {
+        parsed = yaml.load(raw);
+    }
+    else if (ext === ".json") {
+        parsed = JSON.parse(raw);
+    }
+    else {
+        parsed = yaml.load(raw);
+    }
+    const ctx = parsed;
+    if (!ctx || typeof ctx !== "object") {
+        throw new Error(`Failed to parse Context from ${filePath}: not an object`);
+    }
+    if (ctx.kind !== "Context") {
+        throw new Error(`Invalid Context: expected kind "Context", got "${ctx.kind}"`);
+    }
+    if (!ctx.metadata?.name) {
+        throw new Error("Invalid Context: missing metadata.name");
+    }
+    if (!ctx.orchestration?.entrypoint && !ctx.orchestrator?.name) {
+        throw new Error("Invalid Context: missing entrypoint (orchestrator.name or orchestration.entrypoint)");
+    }
+    if (!hasExecutionObjects(ctx)) {
+        throw new Error("Invalid Context: no execution objects defined");
+    }
+    if (!ctx.orchestration?.strategy && !ctx.orchestrator?.strategy) {
+        throw new Error("Invalid Context: missing strategy (orchestration.strategy or orchestrator.strategy)");
+    }
+    return ctx;
+}
+/**
+ * Resolve input values for a Context run. Applies defaults for
+ * missing optional inputs and validates that all required inputs
+ * are provided.
+ *
+ * @param context - The loaded Context.
+ * @param supplied - Input values supplied by the caller.
+ * @returns Fully resolved input values.
+ * @throws If a required input is missing.
+ *
+ * @category Engine
+ */
+export function resolveInputs(context, supplied) {
+    const resolved = {};
+    const definitions = context.inputs ?? {};
+    for (const [name, def] of Object.entries(definitions)) {
+        if (name in supplied) {
+            resolved[name] = supplied[name];
+        }
+        else if (def.default !== undefined) {
+            resolved[name] = def.default;
+        }
+        else if (def.required) {
+            throw new Error(`Missing required input: "${name}"`);
+        }
+    }
+    return resolved;
+}
+//# sourceMappingURL=context-loader.js.map

package/dist/engine/context-loader.js.map

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

package/dist/engine/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./context-loader.js";
+export * from "./system-config-loader.js";
+export * from "./schema-validator.js";
+export * from "./runner.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC"}

package/dist/engine/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./context-loader.js";
+export * from "./system-config-loader.js";
+export * from "./schema-validator.js";
+export * from "./runner.js";
+//# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC"}

package/dist/engine/runner.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ECP Execution Engine — the core runner that orchestrates a Context
+ * execution from start to finish.
+ *
+ * Slice 1: Single executor, seed mounts, model generation, schema validation.
+ * Slice 2 (added in Milestone 7): Controller-specialist delegation.
+ *
+ * @category Engine
+ */
+import type { ECPContext } from "@executioncontrolprotocol/spec";
+import type { ModelProvider } from "../providers/model-provider.js";
+import type { ToolInvoker } from "../protocols/tool-invoker.js";
+import type { AgentTransport } from "../protocols/agent-transport.js";
+import type { EngineConfig, ExecutionResult } from "./types.js";
+import type { TraceCollector } from "../tracing/collector.js";
+/**
+ * Options for a single Context execution.
+ *
+ * @category Engine
+ */
+export interface RunOptions {
+    /** Path to the Context manifest (YAML or JSON). */
+    contextPath?: string;
+    /** Pre-loaded Context object (alternative to `contextPath`). */
+    context?: ECPContext;
+    /** Input values for the Context. */
+    inputs?: Record<string, string | number | boolean>;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * The ECP execution engine.
+ *
+ * Wires together the model provider, tool invoker, and agent transport
+ * to execute a Context manifest end-to-end.
+ *
+ * @category Engine
+ */
+export declare class ECPEngine {
+    private readonly modelProvider;
+    private readonly extensionRegistry?;
+    private readonly modelProviderCache;
+    private readonly toolInvoker;
+    private readonly agentTransport;
+    private readonly config;
+    private readonly hydrator;
+    private traceCollector?;
+    constructor(modelProvider: ModelProvider, toolInvoker: ToolInvoker, agentTransport: AgentTransport, config?: EngineConfig);
+    /**
+     * Attach a trace collector to the engine.
+     * When attached, the engine emits structured trace spans during execution.
+     */
+    setTraceCollector(collector: TraceCollector): void;
+    /**
+     * Execute a Context manifest end-to-end.
+     *
+     * @param options - Run configuration.
+     * @returns The execution result.
+     */
+    run(options: RunOptions): Promise<ExecutionResult>;
+    private runSingleExecutor;
+    private runControllerSpecialist;
+    private delegateViaA2A;
+    private mergeOutputs;
+    private runExecutor;
+    private executeToolCalls;
+    private initRunState;
+    private emitProgress;
+    private nextStep;
+    /** Return the next completion step number (1, 2, 3...) for step_complete events. */
+    private nextCompleteStep;
+    /** Return the next executor step number (1, 2, 3...) for executor step_complete only. */
+    private nextExecutorStep;
+    private connectToolServers;
+    private hydrateMounts;
+    private buildMessages;
+    private getAvailableTools;
+    private getOutputSchema;
+    private schemaToJsonSchema;
+    private tryParseJson;
+    private parseToolName;
+    private log;
+    private buildResult;
+    private getEntrypointName;
+    private getStrategy;
+    private getExecutionObjects;
+    private resolveModelProvider;
+    private normalizeProviderSelector;
+    private assertModelProviderAllowed;
+    private getEffectiveExtensionSecurity;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/engine/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/engine/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,UAAU,EAOX,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAyC,MAAM,gCAAgC,CAAC;AAC3G,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,iCAAiC,CAAC;AAC/F,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EAOhB,MAAM,YAAY,CAAC;AAMpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAG9D;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,gEAAgE;IAChE,OAAO,CAAC,EAAE,UAAU,CAAC;IAErB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAEnD,qCAAqC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAoB;IACvD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoC;IACvE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAGtC,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,cAAc,EAC9B,MAAM,GAAE,YAAiB;IAU3B;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI;IAIlD;;;;;OAKG;IACG,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC;YAsD1C,iBAAiB;YAyBjB,uBAAuB;YAiFvB,cAAc;YAoDd,YAAY;YAyCZ,WAAW;YAiMX,gBAAgB;YAyGhB,YAAY;YAoCZ,YAAY;IAe1B,OAAO,CAAC,QAAQ;IAKhB,oFAAoF;IACpF,OAAO,CAAC,gBAAgB;IAKxB,yFAAyF;IACzF,OAAO,CAAC,gBAAgB;YAKV,kBAAkB;YAclB,aAAa;IAkD3B,OAAO,CAAC,aAAa;YAqCP,iBAAiB;IAiC/B,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,GAAG;IAcX,OAAO,CAAC,WAAW;IA+CnB,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,mBAAmB;IA6B3B,OAAO,CAAC,oBAAoB;IAyC5B,OAAO,CAAC,yBAAyB;IAWjC,OAAO,CAAC,0BAA0B;IA4DlC,OAAO,CAAC,6BAA6B;CAqBtC"}