@dogpile/sdk 0.1.0

package/dist/runtime/engine.js

@@ -0,0 +1,723 @@
+import { DogpileError } from "../types.js";
+import { runBroadcast } from "./broadcast.js";
+import { runCoordinator } from "./coordinator.js";
+import { createReplayTraceFinalOutput, createReplayTraceBudgetStateChanges, canonicalizeRunResult, canonicalizeSerializable, createRunAccounting, createRunEventLog, createRunMetadata, createRunUsage, defaultAgents, normalizeProtocol, orderAgentsForTemperature, tierTemperature } from "./defaults.js";
+import { runSequential } from "./sequential.js";
+import { runShared } from "./shared.js";
+import { createAbortErrorFromSignal, createTimeoutError } from "./cancellation.js";
+import { budget as budgetCondition } from "./termination.js";
+import { validateDogpileOptions, validateEngineOptions, validateMissionIntent } from "./validation.js";
+const defaultHighLevelProtocol = "sequential";
+const defaultHighLevelTier = "balanced";
+/**
+ * Create a reusable low-level protocol engine.
+ *
+ * @remarks
+ * Use this escape hatch to hold protocol, tier, model, agents, and budget caps
+ * constant across repeated missions. Most application code can call
+ * {@link run}, {@link stream}, or {@link Dogpile.pile} directly.
+ *
+ * The returned engine is stateless between calls: each `run()` or `stream()`
+ * invocation produces its own serializable trace, event log, and transcript.
+ */
+export function createEngine(options) {
+    validateEngineOptions(options);
+    const protocol = normalizeProtocol(options.protocol);
+    const tools = options.tools ?? [];
+    const temperature = options.temperature ?? tierTemperature(options.tier);
+    const agents = orderAgentsForTemperature(options.agents ?? defaultAgents(), temperature, options.seed);
+    const terminate = options.terminate ?? (options.budget ? conditionFromBudget(options.budget) : undefined);
+    return {
+        run(intent) {
+            validateMissionIntent(intent);
+            return runNonStreamingProtocol({
+                intent,
+                protocol,
+                tier: options.tier,
+                model: options.model,
+                agents,
+                tools,
+                temperature,
+                ...(options.budget ? { budget: options.budget } : {}),
+                ...(options.seed !== undefined ? { seed: options.seed } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                ...(terminate ? { terminate } : {}),
+                ...(options.evaluate ? { evaluate: options.evaluate } : {})
+            });
+        },
+        stream(intent) {
+            validateMissionIntent(intent);
+            const pendingEvents = [];
+            const pendingResolvers = [];
+            const emittedEvents = [];
+            const subscribers = new Set();
+            const abortController = new AbortController();
+            const timeoutLifecycle = createTimeoutAbortLifecycle({
+                abortController,
+                timeoutMs: runtimeTimeoutMs({ budget: options.budget, terminate }),
+                providerId: options.model.id
+            });
+            const abortRace = createAbortRace(abortController.signal, options.model.id);
+            let complete = false;
+            let lastRunId = "";
+            let pendingFinalEvent;
+            let status = "running";
+            let resolveResult;
+            let rejectResult;
+            let removeCallerAbortListener = () => { };
+            const result = new Promise((resolve, reject) => {
+                resolveResult = resolve;
+                rejectResult = reject;
+            });
+            removeCallerAbortListener = wireCallerAbortSignal(options.signal, abortController, cancelRun);
+            void execute();
+            return {
+                get status() {
+                    return status;
+                },
+                result,
+                cancel() {
+                    cancelRun();
+                },
+                subscribe(subscriber) {
+                    subscribers.add(subscriber);
+                    for (const event of emittedEvents) {
+                        subscriber(event);
+                    }
+                    return {
+                        unsubscribe() {
+                            subscribers.delete(subscriber);
+                        }
+                    };
+                },
+                [Symbol.asyncIterator]() {
+                    return {
+                        next() {
+                            const event = pendingEvents.shift();
+                            if (event) {
+                                return Promise.resolve({ done: false, value: event });
+                            }
+                            if (complete) {
+                                return Promise.resolve({ done: true, value: undefined });
+                            }
+                            return new Promise((resolve) => {
+                                pendingResolvers.push(resolve);
+                            });
+                        }
+                    };
+                }
+            };
+            async function execute() {
+                if (status !== "running") {
+                    return;
+                }
+                try {
+                    const baseResult = await abortRace.run(runProtocol({
+                        intent,
+                        protocol,
+                        tier: options.tier,
+                        model: options.model,
+                        agents,
+                        tools,
+                        temperature,
+                        ...(options.budget ? { budget: options.budget } : {}),
+                        ...(options.seed !== undefined ? { seed: options.seed } : {}),
+                        signal: abortController.signal,
+                        ...(terminate ? { terminate } : {}),
+                        emit(event) {
+                            if (status !== "running") {
+                                return;
+                            }
+                            lastRunId = event.runId;
+                            if (event.type === "final") {
+                                pendingFinalEvent = event;
+                                return;
+                            }
+                            publish(event);
+                        }
+                    }));
+                    if (status !== "running") {
+                        return;
+                    }
+                    const finalizedResult = await abortRace.run(applyRunEvaluation(baseResult, options.evaluate));
+                    if (status !== "running") {
+                        return;
+                    }
+                    const finalEvent = finalizedResult.trace.events.at(-1);
+                    if (finalEvent?.type === "final") {
+                        publish(finalEvent);
+                    }
+                    else if (pendingFinalEvent) {
+                        publish(pendingFinalEvent);
+                    }
+                    status = "completed";
+                    closeStream();
+                    resolveResult(finalizedResult);
+                }
+                catch (error) {
+                    if (isStreamHandleStatus(status, "cancelled")) {
+                        return;
+                    }
+                    const runtimeError = timeoutLifecycle.translateError(error);
+                    status = isCancellationError(runtimeError) ? "cancelled" : "failed";
+                    publish(createStreamErrorEvent(runtimeError, lastRunId));
+                    closeStream();
+                    rejectResult(runtimeError);
+                }
+            }
+            function cancelRun(cause) {
+                if (status !== "running") {
+                    return;
+                }
+                const error = createStreamCancellationError(options.model.id, cause);
+                status = "cancelled";
+                abortController.abort(error);
+                publish(createStreamErrorEvent(error, lastRunId));
+                closeStream();
+                rejectResult(error);
+            }
+            function closeStream() {
+                if (complete) {
+                    return;
+                }
+                complete = true;
+                removeCallerAbortListener();
+                timeoutLifecycle.cleanup();
+                abortRace.cleanup();
+                subscribers.clear();
+                for (const resolver of pendingResolvers.splice(0)) {
+                    resolver({ done: true, value: undefined });
+                }
+            }
+            function publish(event) {
+                if (complete) {
+                    return;
+                }
+                const canonicalEvent = canonicalizeSerializable(event);
+                emittedEvents.push(canonicalEvent);
+                for (const subscriber of subscribers) {
+                    try {
+                        subscriber(canonicalEvent);
+                    }
+                    catch {
+                        // Subscriber failures should not cancel the underlying SDK run.
+                    }
+                }
+                const resolver = pendingResolvers.shift();
+                if (resolver) {
+                    resolver({ done: false, value: canonicalEvent });
+                    return;
+                }
+                pendingEvents.push(canonicalEvent);
+            }
+        }
+    };
+}
+function isStreamHandleStatus(status, expected) {
+    return status === expected;
+}
+function conditionFromBudget(budget) {
+    return budgetCondition({
+        ...(budget.maxUsd !== undefined ? { maxUsd: budget.maxUsd } : {}),
+        ...(budget.maxTokens !== undefined ? { maxTokens: budget.maxTokens } : {}),
+        ...(budget.maxIterations !== undefined ? { maxIterations: budget.maxIterations } : {}),
+        ...(budget.timeoutMs !== undefined ? { timeoutMs: budget.timeoutMs } : {})
+    });
+}
+function createNonStreamingAbortLifecycle(options) {
+    if (options.timeoutMs === undefined) {
+        return {
+            signal: options.callerSignal,
+            async run(operation) {
+                return await operation;
+            },
+            translateError(error) {
+                return error;
+            },
+            cleanup() { }
+        };
+    }
+    const abortController = new AbortController();
+    const timeoutLifecycle = createTimeoutAbortLifecycle({
+        abortController,
+        timeoutMs: options.timeoutMs,
+        providerId: options.providerId
+    });
+    const abortRace = createAbortRace(abortController.signal, options.providerId);
+    const removeCallerAbortListener = wireCallerAbortSignal(options.callerSignal, abortController, () => {
+        abortController.abort(readAbortSignalReason(options.callerSignal));
+    });
+    return {
+        signal: abortController.signal,
+        async run(operation) {
+            return await abortRace.run(operation);
+        },
+        translateError(error) {
+            return timeoutLifecycle.translateError(error);
+        },
+        cleanup() {
+            timeoutLifecycle.cleanup();
+            abortRace.cleanup();
+            removeCallerAbortListener();
+        }
+    };
+}
+function createTimeoutAbortLifecycle(options) {
+    if (options.timeoutMs === undefined) {
+        return {
+            translateError(error) {
+                return error;
+            },
+            cleanup() { }
+        };
+    }
+    const timeoutError = createTimeoutError(options.providerId, options.timeoutMs);
+    const timeoutId = setTimeout(() => {
+        options.abortController.abort(timeoutError);
+    }, options.timeoutMs);
+    return {
+        translateError(error) {
+            return options.abortController.signal.reason === timeoutError ? timeoutError : error;
+        },
+        cleanup() {
+            clearTimeout(timeoutId);
+        }
+    };
+}
+function createAbortRace(signal, providerId) {
+    let cleanupAbortListener = () => { };
+    return {
+        signal,
+        async run(operation) {
+            if (signal.aborted) {
+                throw createAbortErrorFromSignal(signal, providerId);
+            }
+            const abortPromise = new Promise((_, reject) => {
+                const abortHandler = () => {
+                    cleanupAbortListener();
+                    reject(createAbortErrorFromSignal(signal, providerId));
+                };
+                cleanupAbortListener = () => {
+                    signal.removeEventListener("abort", abortHandler);
+                };
+                signal.addEventListener("abort", abortHandler, { once: true });
+            });
+            try {
+                return await Promise.race([operation, abortPromise]);
+            }
+            finally {
+                cleanupAbortListener();
+                cleanupAbortListener = () => { };
+            }
+        },
+        translateError(error) {
+            return error;
+        },
+        cleanup() {
+            cleanupAbortListener();
+            cleanupAbortListener = () => { };
+        }
+    };
+}
+function runtimeTimeoutMs(options) {
+    const budgetTimeoutMs = options.budget?.timeoutMs;
+    const terminationTimeoutMs = timeoutMsFromTermination(options.terminate);
+    if (budgetTimeoutMs === undefined) {
+        return terminationTimeoutMs;
+    }
+    if (terminationTimeoutMs === undefined) {
+        return budgetTimeoutMs;
+    }
+    return Math.min(budgetTimeoutMs, terminationTimeoutMs);
+}
+function timeoutMsFromTermination(condition) {
+    if (!condition) {
+        return undefined;
+    }
+    switch (condition.kind) {
+        case "budget":
+            return condition.timeoutMs;
+        case "firstOf":
+            return condition.conditions.reduce((current, child) => {
+                const childTimeoutMs = timeoutMsFromTermination(child);
+                if (childTimeoutMs === undefined) {
+                    return current;
+                }
+                return current === undefined ? childTimeoutMs : Math.min(current, childTimeoutMs);
+            }, undefined);
+        case "convergence":
+        case "judge":
+            return undefined;
+    }
+}
+function readAbortSignalReason(signal) {
+    return signal?.aborted ? signal.reason : undefined;
+}
+function createStreamErrorEvent(error, runId) {
+    if (DogpileError.isInstance(error)) {
+        return {
+            type: "error",
+            runId,
+            at: new Date().toISOString(),
+            name: error.name,
+            message: error.message,
+            detail: dogpileErrorStreamDetail(error)
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            type: "error",
+            runId,
+            at: new Date().toISOString(),
+            name: error.name,
+            message: error.message
+        };
+    }
+    return {
+        type: "error",
+        runId,
+        at: new Date().toISOString(),
+        name: "Error",
+        message: String(error)
+    };
+}
+function dogpileErrorStreamDetail(error) {
+    const detail = {
+        code: error.code
+    };
+    if (error.providerId !== undefined) {
+        detail.providerId = error.providerId;
+    }
+    if (error.retryable !== undefined) {
+        detail.retryable = error.retryable;
+    }
+    if (error.detail !== undefined) {
+        for (const [key, value] of Object.entries(error.detail)) {
+            detail[key] = value;
+        }
+    }
+    return detail;
+}
+async function runNonStreamingProtocol(options) {
+    const abortLifecycle = createNonStreamingAbortLifecycle({
+        callerSignal: options.signal,
+        timeoutMs: runtimeTimeoutMs(options),
+        providerId: options.model.id
+    });
+    try {
+        const emittedEvents = [];
+        const result = await abortLifecycle.run(runProtocol({
+            ...options,
+            ...(abortLifecycle.signal !== undefined ? { signal: abortLifecycle.signal } : {}),
+            emit(event) {
+                emittedEvents.push(event);
+            }
+        }));
+        const events = emittedEvents.length > 0 ? emittedEvents : result.trace.events;
+        const trace = {
+            ...result.trace,
+            events,
+            budgetStateChanges: createReplayTraceBudgetStateChanges(events),
+            finalOutput: createReplayTraceFinalOutput(result.output, events.at(-1) ?? result.trace.events.at(-1))
+        };
+        const runResult = {
+            ...result,
+            accounting: createRunAccounting({
+                tier: trace.tier,
+                ...(trace.budget.caps ? { budget: trace.budget.caps } : {}),
+                ...(trace.budget.termination ? { termination: trace.budget.termination } : {}),
+                cost: result.cost,
+                events
+            }),
+            eventLog: createRunEventLog(trace.runId, trace.protocol, events),
+            trace
+        };
+        return canonicalizeRunResult(await abortLifecycle.run(applyRunEvaluation(runResult, options.evaluate)));
+    }
+    catch (error) {
+        throw abortLifecycle.translateError(error);
+    }
+    finally {
+        abortLifecycle.cleanup();
+    }
+}
+async function applyRunEvaluation(result, evaluate) {
+    if (!evaluate) {
+        return canonicalizeRunResult(result);
+    }
+    const evaluation = await evaluate(result);
+    const events = result.trace.events.map((event, index) => {
+        if (index !== result.trace.events.length - 1 || event.type !== "final") {
+            return event;
+        }
+        return finalEventWithEvaluation(event, evaluation);
+    });
+    const trace = {
+        ...result.trace,
+        events
+    };
+    return canonicalizeRunResult({
+        ...result,
+        quality: evaluation.quality,
+        evaluation,
+        trace,
+        eventLog: createRunEventLog(trace.runId, trace.protocol, events)
+    });
+}
+function finalEventWithEvaluation(event, evaluation) {
+    return {
+        ...event,
+        quality: evaluation.quality,
+        evaluation
+    };
+}
+function runProtocol(options) {
+    switch (options.protocol.kind) {
+        case "sequential":
+            return runSequential({
+                intent: options.intent,
+                protocol: options.protocol,
+                tier: options.tier,
+                model: options.model,
+                agents: options.agents,
+                tools: options.tools,
+                temperature: options.temperature,
+                ...(options.budget ? { budget: options.budget } : {}),
+                ...(options.seed !== undefined ? { seed: options.seed } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                ...(options.terminate ? { terminate: options.terminate } : {}),
+                ...(options.emit ? { emit: options.emit } : {})
+            });
+        case "broadcast":
+            return runBroadcast({
+                intent: options.intent,
+                protocol: options.protocol,
+                tier: options.tier,
+                model: options.model,
+                agents: options.agents,
+                tools: options.tools,
+                temperature: options.temperature,
+                ...(options.budget ? { budget: options.budget } : {}),
+                ...(options.seed !== undefined ? { seed: options.seed } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                ...(options.terminate ? { terminate: options.terminate } : {}),
+                ...(options.emit ? { emit: options.emit } : {})
+            });
+        case "coordinator":
+            return runCoordinator({
+                intent: options.intent,
+                protocol: options.protocol,
+                tier: options.tier,
+                model: options.model,
+                agents: options.agents,
+                tools: options.tools,
+                temperature: options.temperature,
+                ...(options.budget ? { budget: options.budget } : {}),
+                ...(options.seed !== undefined ? { seed: options.seed } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                ...(options.terminate ? { terminate: options.terminate } : {}),
+                ...(options.emit ? { emit: options.emit } : {})
+            });
+        case "shared":
+            return runShared({
+                intent: options.intent,
+                protocol: options.protocol,
+                tier: options.tier,
+                model: options.model,
+                agents: options.agents,
+                tools: options.tools,
+                temperature: options.temperature,
+                ...(options.budget ? { budget: options.budget } : {}),
+                ...(options.seed !== undefined ? { seed: options.seed } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                ...(options.terminate ? { terminate: options.terminate } : {}),
+                ...(options.emit ? { emit: options.emit } : {})
+            });
+    }
+}
+/**
+ * Run a multi-agent workflow in a single call.
+ *
+ * @remarks
+ * Supply a mission through `intent` and provide a configured model provider.
+ * Omitted high-level controls default to Sequential coordination and the
+ * `balanced` tier. The returned
+ * {@link RunResult} contains the final `output`, a JSON-serializable `trace`,
+ * direct `transcript` access, aggregate `cost`, and optional `quality`.
+ *
+ * Use {@link createEngine} when a research harness needs to reuse normalized
+ * protocol/model/agent settings across many missions.
+ */
+export function run(options) {
+    validateDogpileOptions(options);
+    const { intent, ...engineOptions } = withHighLevelDefaults(options);
+    return createEngine(engineOptions).run(intent);
+}
+/**
+ * Stream a multi-agent workflow and await the final result.
+ *
+ * @remarks
+ * The returned handle is an async iterable of {@link RunEvent} values with a
+ * `result` promise for the same {@link RunResult} shape returned by
+ * {@link run}. This supports live event logs and trace UIs without requiring
+ * SDK-managed storage.
+ *
+ * Streaming and final traces use the same event shapes, so callers can render
+ * progress live and persist the completed trace without translation.
+ */
+export function stream(options) {
+    validateDogpileOptions(options);
+    const { intent, ...engineOptions } = withHighLevelDefaults(options);
+    return createEngine(engineOptions).stream(intent);
+}
+/**
+ * Rehydrate the public result shape from a saved completed trace artifact.
+ *
+ * @remarks
+ * This is the caller-facing replay entrypoint for persisted traces. It does
+ * not call the model provider or require SDK-owned storage; it reconstructs
+ * the ergonomic {@link RunResult} wrapper from the JSON-serializable
+ * {@link Trace} returned by a previous `run()`, `stream()`, or
+ * `Dogpile.pile()` call.
+ */
+export function replay(trace) {
+    const cost = trace.finalOutput.cost;
+    const lastEvent = trace.events.at(-1);
+    const baseResult = {
+        output: trace.finalOutput.output,
+        eventLog: createRunEventLog(trace.runId, trace.protocol, trace.events),
+        trace,
+        transcript: trace.transcript,
+        usage: createRunUsage(cost),
+        metadata: createRunMetadata({
+            runId: trace.runId,
+            protocol: trace.protocol,
+            tier: trace.tier,
+            modelProviderId: trace.modelProviderId,
+            agentsUsed: trace.agentsUsed,
+            events: trace.events
+        }),
+        accounting: createRunAccounting({
+            tier: trace.tier,
+            ...(trace.budget.caps ? { budget: trace.budget.caps } : {}),
+            ...(trace.budget.termination ? { termination: trace.budget.termination } : {}),
+            cost,
+            events: trace.events
+        }),
+        cost
+    };
+    if (lastEvent?.type !== "final") {
+        return baseResult;
+    }
+    return {
+        ...baseResult,
+        ...(lastEvent.quality !== undefined ? { quality: lastEvent.quality } : {}),
+        ...(lastEvent.evaluation !== undefined ? { evaluation: lastEvent.evaluation } : {})
+    };
+}
+/**
+ * Replay a saved completed trace as a stream without invoking a model provider.
+ *
+ * @remarks
+ * This is the streaming counterpart to {@link replay}. It yields the exact
+ * saved {@link Trace.events} in order and resolves {@link StreamHandle.result}
+ * to the rehydrated {@link RunResult}. Since all data comes from the trace,
+ * replay remains storage-free and provider-free.
+ */
+export function replayStream(trace) {
+    const result = Promise.resolve(replay(trace));
+    return {
+        get status() {
+            return "completed";
+        },
+        result,
+        cancel() {
+            // Replay streams are already completed snapshots, so cancellation is a no-op.
+        },
+        subscribe(subscriber) {
+            for (const event of trace.events) {
+                subscriber(event);
+            }
+            return {
+                unsubscribe() {
+                    // Replay subscriptions are finite snapshots; there is no live source to detach from.
+                }
+            };
+        },
+        [Symbol.asyncIterator]() {
+            let index = 0;
+            return {
+                next() {
+                    const event = trace.events[index];
+                    if (event) {
+                        index += 1;
+                        return Promise.resolve({ done: false, value: event });
+                    }
+                    return Promise.resolve({ done: true, value: undefined });
+                }
+            };
+        }
+    };
+}
+function wireCallerAbortSignal(callerSignal, abortController, cancelRun) {
+    if (!callerSignal) {
+        return () => { };
+    }
+    const cancelFromCaller = () => {
+        cancelRun(readAbortSignalReason(callerSignal));
+    };
+    if (callerSignal.aborted) {
+        cancelFromCaller();
+        return () => { };
+    }
+    callerSignal.addEventListener("abort", cancelFromCaller, { once: true });
+    const remove = () => {
+        callerSignal.removeEventListener("abort", cancelFromCaller);
+    };
+    abortController.signal.addEventListener("abort", remove, { once: true });
+    return remove;
+}
+function createStreamCancellationError(providerId, cause) {
+    return new DogpileError({
+        code: "aborted",
+        message: "The operation was aborted.",
+        retryable: false,
+        providerId,
+        ...(cause !== undefined ? { cause } : {}),
+        detail: {
+            status: "cancelled"
+        }
+    });
+}
+function isCancellationError(error) {
+    if (DogpileError.isInstance(error)) {
+        return error.code === "aborted";
+    }
+    return error instanceof Error && error.name === "AbortError";
+}
+function withHighLevelDefaults(options) {
+    return {
+        ...options,
+        protocol: options.protocol ?? defaultHighLevelProtocol,
+        tier: options.tier ?? defaultHighLevelTier
+    };
+}
+/**
+ * Branded high-level SDK namespace.
+ *
+ * `Dogpile.pile()` is the ergonomic caller-facing workflow API. It uses the
+ * non-streaming execution path and resolves only after the protocol completes,
+ * returning `{ output, eventLog, transcript, usage, metadata, trace, cost,
+ * quality }`.
+ */
+function pile(options) {
+    return run(options);
+}
+export const Dogpile = {
+    pile,
+    replay,
+    replayStream,
+    stream,
+    createEngine
+};
+//# sourceMappingURL=engine.js.map