@dogpile/sdk 0.3.1 → 0.5.0

package/src/types/replay.ts

@@ -110,7 +110,14 @@ export type ReplayTraceProtocolDecisionType =
   | "complete-tool-call"
   | "collect-broadcast-round"
   | "stop-for-budget"
-  | "finalize-output";
+  | "finalize-output"
+  | "start-sub-run"
+  | "complete-sub-run"
+  | "fail-sub-run"
+  | "mark-sub-run-parent-aborted"
+  | "mark-sub-run-budget-clamped"
+  | "queue-sub-run"
+  | "mark-sub-run-concurrency-clamped";
 
 /**
  * Protocol-level decision appended during execution.
@@ -136,6 +143,10 @@ export interface ReplayTraceProtocolDecision {
   readonly callId?: string;
   /** Provider involved in the decision, when model-scoped. */
   readonly providerId?: string;
+  /** Child run involved in a delegated sub-run decision. */
+  readonly childRunId?: string;
+  /** FIFO queue position for sub-run queue decisions. */
+  readonly queuePosition?: number;
   /** Tool call involved in the decision, when tool-scoped. */
   readonly toolCallId?: string;
   /** Tool identity involved in the decision, when tool-scoped. */
@@ -170,6 +181,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.
  */
@@ -87,6 +91,14 @@ export type DogpileProviderInvalidRequestError = DogpileErrorBase<"provider-inva
 export type DogpileProviderInvalidResponseError = DogpileErrorBase<"provider-invalid-response">;
 export type DogpileProviderNotFoundError = DogpileErrorBase<"provider-not-found">;
 export type DogpileProviderRateLimitedError = DogpileErrorBase<"provider-rate-limited">;
+/**
+ * Provider timeout errors may include `detail.source?: "provider" | "engine"`.
+ *
+ * Absence is backwards-compatible and should be interpreted as `"provider"`.
+ * `"engine"` means a child engine's own deadline expired before the provider
+ * returned; parent budget propagation remains `code: "aborted"` with
+ * `detail.reason: "timeout"`.
+ */
 export type DogpileProviderTimeoutError = DogpileErrorBase<"provider-timeout">;
 export type DogpileProviderUnavailableError = DogpileErrorBase<"provider-unavailable">;
 export type DogpileProviderUnsupportedError = DogpileErrorBase<"provider-unsupported">;
@@ -876,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>;
   /**
@@ -887,6 +901,14 @@ export interface ConfiguredModelProvider {
    * support incremental output and for callers that prefer batch execution.
    */
   stream?(request: ModelRequest): AsyncIterable<ModelOutputChunk>;
+  /**
+   * Optional provider hints for the runtime. Absent or omitted is treated as
+   * `remote` for concurrency clamping (CONCURRENCY-02 / Phase 3 D-01).
+   */
+  readonly metadata?: {
+    /** Locality hint for dispatch clamping. Absent -> "remote" for clamping. */
+    readonly locality?: "local" | "remote";
+  };
 }
 
 /**
@@ -1284,16 +1306,19 @@ export type {
 
 // Events: see src/types/events.ts
 import type {
+  AbortedEvent,
   AgentDecision,
   AgentParticipation,
   BroadcastContribution,
   BroadcastEvent,
   BudgetStopEvent,
+  DelegateAgentDecision,
   FinalEvent,
   ModelActivityEvent,
   ModelOutputChunkEvent,
   ModelRequestEvent,
   ModelResponseEvent,
+  ParticipateAgentDecision,
   RoleAssignmentEvent,
   RunEvent,
   StreamCompletionEvent,
@@ -1301,6 +1326,13 @@ import type {
   StreamEvent,
   StreamLifecycleEvent,
   StreamOutputEvent,
+  SubRunBudgetClampedEvent,
+  SubRunCompletedEvent,
+  SubRunConcurrencyClampedEvent,
+  SubRunFailedEvent,
+  SubRunParentAbortedEvent,
+  SubRunQueuedEvent,
+  SubRunStartedEvent,
   ToolActivityEvent,
   ToolCallEvent,
   ToolResultEvent,
@@ -1308,8 +1340,11 @@ import type {
   TurnEvent
 } from "./types/events.js";
 export type {
+  AbortedEvent,
   AgentDecision,
   AgentParticipation,
+  DelegateAgentDecision,
+  ParticipateAgentDecision,
   BroadcastContribution,
   BroadcastEvent,
   BudgetStopEvent,
@@ -1325,6 +1360,13 @@ export type {
   StreamEvent,
   StreamLifecycleEvent,
   StreamOutputEvent,
+  SubRunBudgetClampedEvent,
+  SubRunCompletedEvent,
+  SubRunConcurrencyClampedEvent,
+  SubRunFailedEvent,
+  SubRunParentAbortedEvent,
+  SubRunQueuedEvent,
+  SubRunStartedEvent,
   ToolActivityEvent,
   ToolCallEvent,
   ToolResultEvent,
@@ -1372,7 +1414,7 @@ export interface TranscriptEntry {
   /** Text produced by the agent. */
   readonly output: string;
   /** Optional structured role/participation decision parsed from model output. */
-  readonly decision?: AgentDecision;
+  readonly decision?: AgentDecision | readonly DelegateAgentDecision[];
   /** Ordered runtime tool calls and results requested during this turn. */
   readonly toolCalls?: readonly TranscriptToolCall[];
 }
@@ -1535,6 +1577,17 @@ export interface Trace {
   readonly providerCalls: readonly ReplayTraceProviderCall[];
   /** Final output artifact for replay consumers. */
   readonly finalOutput: ReplayTraceFinalOutput;
+  /** Internal hand-off for fail-fast coordinator child failure handling. */
+  readonly triggeringFailureForAbortMode?: {
+    readonly childRunId: string;
+    readonly intent: string;
+    readonly error: {
+      readonly code: string;
+      readonly message: string;
+      readonly detail?: { readonly reason?: string };
+    };
+    readonly partialCost: { readonly usd: number };
+  };
   /**
    * Ordered coordination and lifecycle events.
    *
@@ -1605,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
@@ -1614,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. */
@@ -1641,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;
 }
 
 /**
@@ -1649,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.
  *
@@ -1760,8 +1886,74 @@ 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.
+   *
+   * Defaults to 4. Per-run values can only LOWER the engine ceiling; raising
+   * is silently capped via
+   * `effectiveMaxDepth = Math.min(engineMaxDepth, runMaxDepth ?? Infinity)`.
+   * Depth overflow throws `DogpileError({ code: "invalid-configuration",
+   * detail: { kind: "delegate-validation", reason: "depth-overflow" } })`.
+   */
+  readonly maxDepth?: number;
+  /**
+   * Maximum delegated child runs that may execute in parallel.
+   *
+   * Defaults to 4. Per-run and per-decision values can only lower the engine
+   * ceiling; the effective value is `min(engine, run ?? Infinity, decision ?? Infinity)`.
+   */
+  readonly maxConcurrentChildren?: number;
+  /**
+   * Fallback timeout (milliseconds) applied to delegated sub-runs when neither
+   * the parent's `budget.timeoutMs` nor the decision-level
+   * `decision.budget.timeoutMs` specifies one (BUDGET-02 / D-14).
+   *
+   * Precedence (most specific wins):
+   *   `decision.budget.timeoutMs` > parent's remaining deadline (when parent has
+   *   `budget.timeoutMs`) > `defaultSubRunTimeoutMs` > undefined.
+   *
+   * Default: `undefined` (preserves the "no sub-run timeout" posture).
+   */
+  readonly defaultSubRunTimeoutMs?: number;
+  /**
+   * Controls how coordinator runs react after a real delegated child failure.
+   *
+   * Defaults to `"continue"`, which re-issues the coordinator plan turn with
+   * structured failure context. `"abort"` skips that follow-up plan turn and
+   * records the triggering child failure for the unhandled-failure throw path.
+   */
+  readonly onChildFailure?: OnChildFailureMode;
 }
 
+/** Coordinator behavior after a real child failure in a delegated dispatch wave. */
+export type OnChildFailureMode = "continue" | "abort";
+
 /**
  * Low-level engine configuration for reusable protocol execution.
  *
@@ -1824,6 +2016,89 @@ 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.
+   *
+   * Defaults to 4. Per-run lowering happens at `engine.run` / `engine.stream`
+   * call sites via {@link RunCallOptions.maxDepth}; per-run can only lower this
+   * ceiling. Depth overflow throws `DogpileError({ code: "invalid-configuration",
+   * detail: { kind: "delegate-validation", reason: "depth-overflow" } })`.
+   */
+  readonly maxDepth?: number;
+  /**
+   * Maximum delegated child runs that may execute in parallel.
+   *
+   * Defaults to 4. Per-run lowering happens at `engine.run` / `engine.stream`
+   * call sites via {@link RunCallOptions.maxConcurrentChildren}.
+   */
+  readonly maxConcurrentChildren?: number;
+  /**
+   * Fallback timeout (milliseconds) applied to delegated sub-runs when neither
+   * the parent's `budget.timeoutMs` nor the decision-level
+   * `decision.budget.timeoutMs` specifies one (BUDGET-02 / D-14).
+   *
+   * Precedence (most specific wins):
+   *   `decision.budget.timeoutMs` > parent's remaining deadline (when parent has
+   *   `budget.timeoutMs`) > `defaultSubRunTimeoutMs` > undefined.
+   *
+   * Default: `undefined` (preserves the "no sub-run timeout" posture).
+   */
+  readonly defaultSubRunTimeoutMs?: number;
+  /**
+   * Controls how coordinator runs react after a real delegated child failure.
+   *
+   * Defaults to `"continue"`. `"abort"` skips the follow-up coordinator plan
+   * turn and records the triggering child failure for fail-fast callers.
+   */
+  readonly onChildFailure?: OnChildFailureMode;
+}
+
+/**
+ * Per-call overrides accepted by {@link Engine.run} and {@link Engine.stream}.
+ *
+ * @remarks
+ * Only fields that should be controllable per-mission live here. Today the
+ * fields are controls that can only LOWER the engine's ceiling.
+ */
+export interface RunCallOptions {
+  /**
+   * Per-run maximum recursion depth. Cannot raise the engine's ceiling — the
+   * effective value is `Math.min(engine.maxDepth ?? 4, runOptions.maxDepth ?? Infinity)`.
+   */
+  readonly maxDepth?: number;
+  /**
+   * Per-run delegated child concurrency ceiling. Cannot raise the engine's
+   * ceiling.
+   */
+  readonly maxConcurrentChildren?: number;
+  /** Per-run child-failure behavior. Overrides the engine default. */
+  readonly onChildFailure?: OnChildFailureMode;
 }
 
 /**
@@ -1903,7 +2178,7 @@ export interface StreamSubscription {
  */
 export interface Engine {
   /** Execute a mission to completion and return the final result. */
-  run(intent: string): Promise<RunResult>;
+  run(intent: string, options?: RunCallOptions): Promise<RunResult>;
   /** Stream a mission's events while preserving access to the final result. */
-  stream(intent: string): StreamHandle;
+  stream(intent: string, options?: RunCallOptions): StreamHandle;
 }