@dogpile/sdk 0.4.0 → 0.6.0

package/src/runtime/tracing.ts

@@ -0,0 +1,35 @@
+/**
+ * Duck-typed OTEL tracing bridge surface (Phase 9 / OTEL-01..OTEL-03).
+ *
+ * The SDK does not import `@opentelemetry/*` anywhere in `src/runtime/`,
+ * `src/browser/`, or `src/providers/`. Callers wire a real OTEL Tracer to
+ * the SDK by providing an object that structurally matches `DogpileTracer`.
+ * See `docs/developer-usage.md` for the WeakMap-based bridge pattern.
+ *
+ * `replay()` and `replayStream()` ignore any tracer on engine options —
+ * historical timestamps would confuse OTEL backends.
+ */
+
+export interface DogpileSpan {
+  end(): void;
+  setAttribute(key: string, value: string | number | boolean): void;
+  setStatus(code: "ok" | "error", message?: string): void;
+}
+
+export interface DogpileSpanOptions {
+  readonly parent?: DogpileSpan;
+  readonly attributes?: Readonly<Record<string, string | number | boolean>>;
+}
+
+export interface DogpileTracer {
+  startSpan(name: string, options?: DogpileSpanOptions): DogpileSpan;
+}
+
+export const DOGPILE_SPAN_NAMES = {
+  RUN: "dogpile.run",
+  SUB_RUN: "dogpile.sub-run",
+  AGENT_TURN: "dogpile.agent-turn",
+  MODEL_CALL: "dogpile.model-call"
+} as const;
+
+export type DogpileSpanName = (typeof DOGPILE_SPAN_NAMES)[keyof typeof DOGPILE_SPAN_NAMES];

package/src/runtime/validation.ts

@@ -73,6 +73,7 @@ export function validateDogpileOptions(options: DogpileOptions): void {
   validateOptionalAbortSignal(options.signal, "signal");
   validateOptionalNonNegativeInteger(options.maxDepth, "maxDepth");
   validateOptionalPositiveInteger(options.maxConcurrentChildren, "maxConcurrentChildren");
+  validateOptionalPositiveInteger(options.maxConcurrentAgentTurns, "maxConcurrentAgentTurns");
   validateOptionalPositiveFiniteNumber(options.defaultSubRunTimeoutMs, "defaultSubRunTimeoutMs");
   validateOptionalOnChildFailure(options.onChildFailure, "onChildFailure");
 }
@@ -91,6 +92,7 @@ export function validateRunCallOptions(options: unknown, path = "options"): void
   const record = requireRecord(options, path);
   validateOptionalNonNegativeInteger(record.maxDepth, `${path}.maxDepth`);
   validateOptionalPositiveInteger(record.maxConcurrentChildren, `${path}.maxConcurrentChildren`);
+  validateOptionalPositiveInteger(record.maxConcurrentAgentTurns, `${path}.maxConcurrentAgentTurns`);
   validateOptionalOnChildFailure(record.onChildFailure, `${path}.onChildFailure`);
 }
 
@@ -113,6 +115,7 @@ export function validateEngineOptions(options: EngineOptions): void {
   validateOptionalAbortSignal(options.signal, "signal");
   validateOptionalNonNegativeInteger(options.maxDepth, "maxDepth");
   validateOptionalPositiveInteger(options.maxConcurrentChildren, "maxConcurrentChildren");
+  validateOptionalPositiveInteger(options.maxConcurrentAgentTurns, "maxConcurrentAgentTurns");
   validateOptionalPositiveFiniteNumber(options.defaultSubRunTimeoutMs, "defaultSubRunTimeoutMs");
   validateOptionalOnChildFailure(options.onChildFailure, "onChildFailure");
 }

package/src/types/events.ts

@@ -71,12 +71,14 @@ export interface ModelRequestEvent {
   readonly runId: string;
   /** Root-first ancestry chain when bubbled through a parent stream. */
   readonly parentRunIds?: readonly string[];
-  /** ISO-8601 event timestamp. */
-  readonly at: string;
+  /** ISO-8601 timestamp immediately before the provider call began. */
+  readonly startedAt: string;
   /** Stable provider call id within the run. */
   readonly callId: string;
   /** Configured model provider id receiving the request. */
   readonly providerId: string;
+  /** Resolved model identifier; falls back to provider id when adapter does not set modelId. */
+  readonly modelId: string;
   /** Agent requesting the model call. */
   readonly agentId: string;
   /** Agent role for the active model call. */
@@ -101,12 +103,16 @@ export interface ModelResponseEvent {
   readonly runId: string;
   /** Root-first ancestry chain when bubbled through a parent stream. */
   readonly parentRunIds?: readonly string[];
-  /** ISO-8601 event timestamp. */
-  readonly at: string;
+  /** ISO-8601 timestamp when the provider call started (same value as the paired ModelRequestEvent). */
+  readonly startedAt: string;
+  /** ISO-8601 timestamp after the provider call completed. Duration = completedAt minus startedAt. */
+  readonly completedAt: string;
   /** Stable provider call id within the run. */
   readonly callId: string;
   /** Configured model provider id that produced the response. */
   readonly providerId: string;
+  /** Resolved model identifier; falls back to provider id when adapter does not set modelId. */
+  readonly modelId: string;
   /** Agent that requested the model call. */
   readonly agentId: string;
   /** Agent role for the completed model call. */
@@ -134,7 +140,7 @@ export interface ModelResponseEvent {
  * - `input`: prompt text visible to that agent for this turn.
  * - `chunkIndex`: zero-based chunk index within this model turn.
  * - `text`: text delta from the provider.
- * - `output`: accumulated output for this turn after applying the chunk.
+ * - `outputLength`: accumulated output character length after applying the chunk.
  */
 export interface ModelOutputChunkEvent {
   /** Discriminant for event rendering and exhaustive switches. */
@@ -155,8 +161,8 @@ export interface ModelOutputChunkEvent {
   readonly chunkIndex: number;
   /** Text delta produced by the model provider. */
   readonly text: string;
-  /** Accumulated output for this turn after applying this chunk. */
-  readonly output: string;
+  /** Accumulated output character length after applying this chunk. */
+  readonly outputLength: number;
 }
 
 /**

package/src/types/replay.ts

@@ -163,8 +163,10 @@ export interface ReplayTraceProtocolDecision {
   readonly contributionCount?: number;
   /** Prompt/input associated with turn decisions. */
   readonly input?: string;
-  /** Output associated with turn or final decisions. */
+  /** Output associated with turn/final decisions, or a streaming text delta. */
   readonly output?: string;
+  /** Accumulated output character length for streaming output observations. */
+  readonly outputLength?: number;
   /** Cumulative cost visible at this decision point. */
   readonly cost?: CostSummary;
   /** Normalized budget stop reason for budget-stop decisions. */
@@ -181,6 +183,8 @@ export interface ReplayTraceProviderCall {
   readonly callId: string;
   /** Configured model provider id. */
   readonly providerId: string;
+  /** Resolved model identifier (same fallback as provenance events). */
+  readonly modelId: string;
   /** ISO-8601 timestamp before the provider call started. */
   readonly startedAt: string;
   /** ISO-8601 timestamp after the provider call completed. */

package/src/types.ts

@@ -1,3 +1,7 @@
+import type { DogpileTracer } from "./runtime/tracing.js";
+import type { Logger } from "./runtime/logger.js";
+import type { MetricsHook } from "./runtime/metrics.js";
+
 /**
  * Primitive JSON value accepted in serializable trace metadata.
  */
@@ -884,6 +888,8 @@ export interface ModelOutputChunk {
 export interface ConfiguredModelProvider {
   /** Stable provider id recorded in traces. */
   readonly id: string;
+  /** Optional resolved model identifier. When set, provenance events carry this value; when absent, the SDK falls back to `id`. */
+  readonly modelId?: string;
   /** Generate a response for one protocol-managed model request. */
   generate(request: ModelRequest): Promise<ModelResponse>;
   /**
@@ -1652,7 +1658,7 @@ export interface RunMetadata {
  * Result returned by high-level single-call APIs.
  *
  * The returned shape is
- * `{ output, eventLog, transcript, usage, metadata, accounting, trace, cost, quality, evaluation }`.
+ * `{ output, eventLog, transcript, usage, metadata, accounting, trace, cost, quality, evaluation, health }`.
  * `output` is the final synthesized answer, `eventLog` is the complete ordered
  * coordination log, `transcript` is the complete agent-turn transcript,
  * `usage` reports token and dollar accounting, and `metadata` exposes stable
@@ -1661,6 +1667,7 @@ export interface RunMetadata {
  * serializable replay artifact, `cost` is retained as a compatibility alias
  * for `usage`, and `quality` and `evaluation` are present when a judge or
  * benchmark supplies a normalized score and serializable evaluation payload.
+ * `health` exposes machine-readable diagnostics once computed by the runtime.
  */
 export interface RunResult {
   /** Final synthesized answer for the supplied intent. */
@@ -1688,6 +1695,15 @@ export interface RunResult {
   readonly quality?: NormalizedQualityScore;
   /** Optional serializable evaluation data supplied by a caller-owned evaluator. */
   readonly evaluation?: RunEvaluation;
+  /**
+   * Machine-readable health summary for the run, auto-computed from trace events.
+   *
+   * Always present. Re-computed identically by `replay()` from the same trace —
+   * contains no information beyond what the trace events carry. Use
+   * `computeHealth(trace, thresholds)` from `@dogpile/sdk/runtime/health` to
+   * re-compute with custom thresholds on a stored trace.
+   */
+  readonly health: RunHealthSummary;
 }
 
 /**
@@ -1696,6 +1712,69 @@ export interface RunResult {
  */
 export type RunEvaluator = (result: Omit<RunResult, "quality" | "evaluation">) => RunEvaluation | Promise<RunEvaluation>;
 
+/**
+ * Machine-readable code identifying a health anomaly detected in a completed run.
+ *
+ * - `"runaway-turns"`: an agent exceeded the configured per-agent turn threshold.
+ * - `"budget-near-miss"`: budget utilization exceeded the configured near-miss threshold.
+ * - `"empty-contribution"`: an agent produced an empty (blank/whitespace) output turn.
+ * - `"provider-error-recovered"`: a provider call failed and was retried successfully.
+ *   Detection is deferred — computeHealth never emits this code in Phase 7 because no
+ *   trace signal exists without an event-shape change. The code is reserved for future use.
+ */
+export type AnomalyCode =
+  | "runaway-turns"
+  | "budget-near-miss"
+  | "empty-contribution"
+  | "provider-error-recovered";
+
+/**
+ * A single health anomaly detected in a completed run trace.
+ *
+ * All fields are required except `agentId`, which is present for per-agent anomalies
+ * (`"runaway-turns"`, `"empty-contribution"`, `"provider-error-recovered"`) and absent
+ * for global anomalies (`"budget-near-miss"`).
+ */
+export interface HealthAnomaly {
+  /** Machine-readable anomaly identifier. */
+  readonly code: AnomalyCode;
+  /** Severity level: `"error"` for runaway turns and empty contributions; `"warning"` for near-miss and recovered patterns. */
+  readonly severity: "warning" | "error";
+  /** Actual measured value that triggered the anomaly (turn count, utilization %, etc.). */
+  readonly value: number;
+  /** Threshold value that was exceeded (for comparison in UIs and alerting). */
+  readonly threshold: number;
+  /** Agent that triggered the anomaly, present for per-agent anomaly codes. */
+  readonly agentId?: string;
+}
+
+/**
+ * Machine-readable health summary for a completed run, auto-computed from trace events.
+ *
+ * Always present on {@link RunResult}. Re-computed identically by `replay()` from the
+ * same trace — no information is stored beyond what the trace events contain.
+ *
+ * Use `computeHealth(trace, thresholds)` from `@dogpile/sdk/runtime/health` to re-compute
+ * with custom thresholds.
+ */
+export interface RunHealthSummary {
+  /** Detected health anomalies. Empty array when no anomalies are found. */
+  readonly anomalies: readonly HealthAnomaly[];
+  /** Derived stats computed from trace events. */
+  readonly stats: {
+    /** Total number of agent-turn events in the trace. */
+    readonly totalTurns: number;
+    /** Number of unique agents that produced at least one turn. */
+    readonly agentCount: number;
+    /**
+     * Budget utilization as a percentage (0–100+).
+     * `null` when no USD cap was configured for the run.
+     * Computed as `(finalCost / maxUsd) * 100`.
+     */
+    readonly budgetUtilizationPct: number | null;
+  };
+}
+
 /**
  * Mission supplied to a high-level Dogpile workflow call.
  *
@@ -1807,6 +1886,32 @@ export interface DogpileOptions extends BudgetCostTierOptions {
   readonly seed?: string | number;
   /** Optional caller cancellation signal passed to provider-facing model requests. */
   readonly signal?: AbortSignal;
+  /**
+   * Optional duck-typed OTEL-compatible tracer. When provided, the SDK emits
+   * spans for run start/end, sub-run start/end, agent-turn start/end, and
+   * model-call start/end with correct parent-child ancestry. When absent the
+   * run completes with zero span overhead — no allocations, no branch cost.
+   * `replay()` and `replayStream()` ignore this field entirely.
+   * See {@link DogpileTracer} in `@dogpile/sdk/runtime/tracing`.
+   */
+  readonly tracer?: DogpileTracer;
+  /**
+   * Optional callback object for run-completion metrics. When provided,
+   * `onRunComplete` fires with a `RunMetricsSnapshot` at every terminal state
+   * (completed, budget-stopped, or aborted). `onSubRunComplete` fires for each
+   * coordinator-dispatched child run that completes. Hook errors are routed to
+   * `logger.error` (or `console.error` when no logger is provided) and never
+   * propagate into the run result. When absent, zero overhead — no allocations.
+   * See `@dogpile/sdk/runtime/metrics` for the interface.
+   */
+  readonly metricsHook?: MetricsHook;
+  /**
+   * Optional structured logger for SDK-internal diagnostics (hook errors and
+   * future debug/info events). Implement against pino, winston, or any other
+   * logger by satisfying the `Logger` interface from `@dogpile/sdk/runtime/logger`.
+   * When absent, hook errors fall back to `console.error`.
+   */
+  readonly logger?: Logger;
   /**
    * Maximum coordinator → sub-run recursion depth.
    *
@@ -1824,6 +1929,14 @@ export interface DogpileOptions extends BudgetCostTierOptions {
    * ceiling; the effective value is `min(engine, run ?? Infinity, decision ?? Infinity)`.
    */
   readonly maxConcurrentChildren?: number;
+  /**
+   * Maximum agent model turns that may execute in parallel for shared,
+   * broadcast, and coordinator worker fan-out.
+   *
+   * Defaults to 4. Per-run values can only lower the engine ceiling.
+   * This is independent from delegated child-run concurrency.
+   */
+  readonly maxConcurrentAgentTurns?: number;
   /**
    * Fallback timeout (milliseconds) applied to delegated sub-runs when neither
    * the parent's `budget.timeoutMs` nor the decision-level
@@ -1911,6 +2024,32 @@ export interface EngineOptions {
   readonly seed?: string | number;
   /** Optional caller cancellation signal passed to provider-facing model requests. */
   readonly signal?: AbortSignal;
+  /**
+   * Optional duck-typed OTEL-compatible tracer. When provided, the SDK emits
+   * spans for run start/end, sub-run start/end, agent-turn start/end, and
+   * model-call start/end with correct parent-child ancestry. When absent the
+   * run completes with zero span overhead — no allocations, no branch cost.
+   * `replay()` and `replayStream()` ignore this field entirely.
+   * See {@link DogpileTracer} in `@dogpile/sdk/runtime/tracing`.
+   */
+  readonly tracer?: DogpileTracer;
+  /**
+   * Optional callback object for run-completion metrics. When provided,
+   * `onRunComplete` fires with a `RunMetricsSnapshot` at every terminal state
+   * (completed, budget-stopped, or aborted). `onSubRunComplete` fires for each
+   * coordinator-dispatched child run that completes. Hook errors are routed to
+   * `logger.error` (or `console.error` when no logger is provided) and never
+   * propagate into the run result. When absent, zero overhead — no allocations.
+   * See `@dogpile/sdk/runtime/metrics` for the interface.
+   */
+  readonly metricsHook?: MetricsHook;
+  /**
+   * Optional structured logger for SDK-internal diagnostics (hook errors and
+   * future debug/info events). Implement against pino, winston, or any other
+   * logger by satisfying the `Logger` interface from `@dogpile/sdk/runtime/logger`.
+   * When absent, hook errors fall back to `console.error`.
+   */
+  readonly logger?: Logger;
   /**
    * Maximum coordinator → sub-run recursion depth ceiling.
    *
@@ -1927,6 +2066,14 @@ export interface EngineOptions {
    * call sites via {@link RunCallOptions.maxConcurrentChildren}.
    */
   readonly maxConcurrentChildren?: number;
+  /**
+   * Maximum agent model turns that may execute in parallel for shared,
+   * broadcast, and coordinator worker fan-out.
+   *
+   * Defaults to 4. Per-run lowering happens at `engine.run` / `engine.stream`
+   * call sites via {@link RunCallOptions.maxConcurrentAgentTurns}.
+   */
+  readonly maxConcurrentAgentTurns?: number;
   /**
    * Fallback timeout (milliseconds) applied to delegated sub-runs when neither
    * the parent's `budget.timeoutMs` nor the decision-level
@@ -1966,6 +2113,10 @@ export interface RunCallOptions {
    * ceiling.
    */
   readonly maxConcurrentChildren?: number;
+  /**
+   * Per-run agent-turn fan-out ceiling. Cannot raise the engine's ceiling.
+   */
+  readonly maxConcurrentAgentTurns?: number;
   /** Per-run child-failure behavior. Overrides the engine default. */
   readonly onChildFailure?: OnChildFailureMode;
 }