@dogpile/sdk 0.3.0 → 0.4.0

package/src/runtime/logger.ts

@@ -0,0 +1,152 @@
+import type { JsonValue, StreamEvent, StreamEventSubscriber } from "../types.js";
+
+/**
+ * Severity levels recognized by `consoleLogger` and used as the floor when
+ * deciding which events surface through `loggerFromEvents`.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/**
+ * Minimal structured-logging seam that callers can implement against pino,
+ * winston, console, or anything else. Logger calls must be synchronous,
+ * non-throwing, and have no return value — Dogpile catches throws and routes
+ * them to the same logger's `error` channel rather than failing the run.
+ */
+export interface Logger {
+  debug(message: string, fields?: Readonly<Record<string, JsonValue>>): void;
+  info(message: string, fields?: Readonly<Record<string, JsonValue>>): void;
+  warn(message: string, fields?: Readonly<Record<string, JsonValue>>): void;
+  error(message: string, fields?: Readonly<Record<string, JsonValue>>): void;
+}
+
+/** Logger that drops every call. The default when no logger is supplied. */
+export const noopLogger: Logger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {}
+};
+
+/**
+ * Build a console-backed logger respecting a minimum level.
+ *
+ * The output format is JSON-on-one-line so it can be piped straight into log
+ * collectors. Use `loggerFromEvents` to bridge it to a Dogpile stream handle.
+ */
+export function consoleLogger(options: { readonly level?: LogLevel } = {}): Logger {
+  const minLevel = options.level ?? "info";
+  const allowed = (level: LogLevel): boolean => LEVEL_ORDER[level] >= LEVEL_ORDER[minLevel];
+  const emit = (level: LogLevel, message: string, fields?: Readonly<Record<string, JsonValue>>): void => {
+    if (!allowed(level)) return;
+    const payload: Record<string, unknown> = { level, message };
+    if (fields !== undefined) payload.fields = fields;
+    const sink = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+    sink(JSON.stringify(payload));
+  };
+  return {
+    debug: (message, fields) => emit("debug", message, fields),
+    info: (message, fields) => emit("info", message, fields),
+    warn: (message, fields) => emit("warn", message, fields),
+    error: (message, fields) => emit("error", message, fields)
+  };
+}
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+
+/**
+ * Options for `loggerFromEvents`.
+ */
+export interface LoggerFromEventsOptions {
+  /**
+   * Restrict logging to the listed event types. By default every
+   * lifecycle event is forwarded.
+   */
+  readonly include?: ReadonlyArray<StreamEvent["type"]>;
+  /**
+   * Override the level chosen for a given event type. Useful for elevating
+   * tool-result errors to `warn` or downgrading `model-output-chunk` to
+   * `debug`.
+   */
+  readonly levelFor?: (event: StreamEvent) => LogLevel | undefined;
+}
+
+/**
+ * Bridge a `Logger` to a Dogpile stream handle by returning a
+ * `StreamEventSubscriber`. Pass it to `handle.subscribe(...)`.
+ *
+ * Logger throws are caught and routed to `logger.error` so a misbehaving
+ * logger can never crash an in-flight run.
+ *
+ * @example
+ * ```ts
+ * const handle = Dogpile.stream({ intent, model });
+ * handle.subscribe(loggerFromEvents(consoleLogger({ level: "info" })));
+ * const result = await handle.result;
+ * ```
+ */
+export function loggerFromEvents(
+  logger: Logger,
+  options: LoggerFromEventsOptions = {}
+): StreamEventSubscriber {
+  const includeSet = options.include ? new Set(options.include) : undefined;
+  return (event: StreamEvent): void => {
+    const eventType = event.type;
+    if (includeSet && !includeSet.has(eventType)) {
+      return;
+    }
+    const level = options.levelFor?.(event) ?? defaultLevel(event);
+    const message = describeEvent(event);
+    const fields = summarizeEvent(event);
+    try {
+      logger[level](message, fields);
+    } catch (cause) {
+      try {
+        logger.error("dogpile logger threw while handling event", {
+          eventType,
+          error: cause instanceof Error ? cause.message : String(cause)
+        });
+      } catch {
+        // Swallow — a logger that throws from error() cannot be helped.
+      }
+    }
+  };
+}
+
+function defaultLevel(event: StreamEvent): LogLevel {
+  switch (event.type) {
+    case "model-output-chunk":
+      return "debug";
+    case "budget-stop":
+      return "warn";
+    case "error":
+      return "error";
+    case "tool-result": {
+      const result = (event as { readonly result?: { readonly type?: string } }).result;
+      return result?.type === "error" ? "warn" : "info";
+    }
+    default:
+      return "info";
+  }
+}
+
+function describeEvent(event: StreamEvent): string {
+  return `dogpile:${event.type}`;
+}
+
+function summarizeEvent(event: StreamEvent): Readonly<Record<string, JsonValue>> {
+  const fields: Record<string, JsonValue> = { eventType: event.type };
+  const at = (event as { readonly at?: unknown }).at;
+  if (typeof at === "string") fields.at = at;
+  const runId = (event as { readonly runId?: unknown }).runId;
+  if (typeof runId === "string") fields.runId = runId;
+  const agentId = (event as { readonly agentId?: unknown }).agentId;
+  if (typeof agentId === "string") fields.agentId = agentId;
+  const role = (event as { readonly role?: unknown }).role;
+  if (typeof role === "string") fields.role = role;
+  return fields;
+}

package/src/runtime/retry.ts

@@ -0,0 +1,270 @@
+import {
+  DogpileError,
+  type ConfiguredModelProvider,
+  type DogpileErrorCode,
+  type ModelOutputChunk,
+  type ModelRequest,
+  type ModelResponse
+} from "../types.js";
+
+/**
+ * Default DogpileError codes that `withRetry` retries when no `retryOn`
+ * predicate is supplied. These map to the transient provider failures listed
+ * in `docs/developer-usage.md`.
+ */
+export const DEFAULT_RETRYABLE_DOGPILE_CODES: readonly DogpileErrorCode[] = [
+  "provider-rate-limited",
+  "provider-timeout",
+  "provider-unavailable"
+];
+
+/** Reason passed to `onRetry` and used to drive jitter selection. */
+export type RetryJitterMode = "full" | "none";
+
+/**
+ * Information about a single retry attempt that has just failed and is about
+ * to sleep before the next attempt.
+ */
+export interface RetryAttemptInfo {
+  /** 1-based index of the attempt that just failed. */
+  readonly attempt: number;
+  /** Maximum number of attempts the policy will make before giving up. */
+  readonly maxAttempts: number;
+  /** Sleep duration before the next attempt, in milliseconds. */
+  readonly delayMs: number;
+  /** The error thrown by the failing attempt. */
+  readonly error: unknown;
+  /** Provider id of the wrapped provider. */
+  readonly providerId: string;
+}
+
+/**
+ * Caller-supplied retry policy for `withRetry`.
+ *
+ * The defaults match the conservative, neutrality-preserving recipe in
+ * `docs/developer-usage.md`. A caller that wants per-error custom logic
+ * (e.g. honor a custom `Retry-After` header from a non-Dogpile error shape)
+ * should pass `retryOn` and `delayForError`.
+ */
+export interface RetryPolicy {
+  /** Maximum total attempts including the first call. Default: 3. */
+  readonly maxAttempts?: number;
+  /** Initial backoff delay in milliseconds. Default: 250. */
+  readonly baseDelayMs?: number;
+  /** Cap on the per-attempt backoff delay. Default: 4000. */
+  readonly maxDelayMs?: number;
+  /** Jitter strategy. `"full"` uses uniform jitter, `"none"` is deterministic. Default: "full". */
+  readonly jitter?: RetryJitterMode;
+  /**
+   * Predicate deciding whether an error is retryable. Receives the raw error
+   * thrown by the wrapped provider; returns `true` to retry, `false` to
+   * propagate immediately. Default: matches `DEFAULT_RETRYABLE_DOGPILE_CODES`
+   * for `DogpileError`, and treats `AbortError` / `DOMException(AbortError)` /
+   * `DogpileError({ code: "aborted" })` as non-retryable.
+   */
+  readonly retryOn?: (error: unknown) => boolean;
+  /**
+   * Optional delay override for a specific error. Return a non-negative number
+   * (ms) to override the computed backoff for the next attempt — used to
+   * honor server-supplied `Retry-After` semantics. Returning `undefined`
+   * keeps the computed backoff.
+   */
+  readonly delayForError?: (error: unknown) => number | undefined;
+  /**
+   * Side-effect callback invoked after each failing attempt that will be
+   * retried. Useful for surfacing retries to a logger or metrics system
+   * without wrapping the whole event stream.
+   */
+  readonly onRetry?: (info: RetryAttemptInfo) => void;
+  /**
+   * Random source for jitter, primarily for deterministic tests. Must return
+   * a value in `[0, 1)`. Default: `Math.random`.
+   */
+  readonly random?: () => number;
+  /**
+   * Sleep implementation, primarily for deterministic tests. Default: a
+   * `setTimeout`-backed promise that respects `AbortSignal`.
+   */
+  readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+const DEFAULTS = {
+  maxAttempts: 3,
+  baseDelayMs: 250,
+  maxDelayMs: 4_000,
+  jitter: "full" as RetryJitterMode
+};
+
+/**
+ * Wrap a `ConfiguredModelProvider` with a retry policy. The wrapper:
+ *
+ * - Preserves the provider `id` so traces remain stable.
+ * - Retries `generate()` calls when the policy says the error is retryable.
+ * - Propagates `AbortSignal` cancellation immediately — never retries after
+ *   the caller cancels.
+ * - Honors a `Retry-After`-style hint exposed via `error.detail.retryAfterMs`
+ *   when present and the policy did not provide its own `delayForError`.
+ * - Forwards `stream()` calls through unchanged — streaming retries cannot be
+ *   safely automated because partial output may have already been observed.
+ *
+ * @example
+ * ```ts
+ * const robustProvider = withRetry(rawProvider, {
+ *   maxAttempts: 4,
+ *   baseDelayMs: 500,
+ *   onRetry: ({ attempt, delayMs, error }) => {
+ *     logger.warn("provider retry", { attempt, delayMs, error });
+ *   }
+ * });
+ * ```
+ */
+export function withRetry(
+  provider: ConfiguredModelProvider,
+  policy: RetryPolicy = {}
+): ConfiguredModelProvider {
+  const settings = {
+    maxAttempts: policy.maxAttempts ?? DEFAULTS.maxAttempts,
+    baseDelayMs: policy.baseDelayMs ?? DEFAULTS.baseDelayMs,
+    maxDelayMs: policy.maxDelayMs ?? DEFAULTS.maxDelayMs,
+    jitter: policy.jitter ?? DEFAULTS.jitter,
+    retryOn: policy.retryOn ?? defaultRetryOn,
+    random: policy.random ?? Math.random,
+    sleep: policy.sleep ?? defaultSleep
+  };
+  if (settings.maxAttempts < 1) {
+    throw new DogpileError({
+      code: "invalid-configuration",
+      message: "withRetry: maxAttempts must be >= 1.",
+      detail: { maxAttempts: settings.maxAttempts }
+    });
+  }
+  if (settings.baseDelayMs < 0 || settings.maxDelayMs < 0) {
+    throw new DogpileError({
+      code: "invalid-configuration",
+      message: "withRetry: delay fields must be non-negative.",
+      detail: { baseDelayMs: settings.baseDelayMs, maxDelayMs: settings.maxDelayMs }
+    });
+  }
+
+  const wrapped: ConfiguredModelProvider = {
+    id: provider.id,
+    async generate(request: ModelRequest): Promise<ModelResponse> {
+      let lastError: unknown;
+      for (let attempt = 1; attempt <= settings.maxAttempts; attempt++) {
+        if (request.signal?.aborted) {
+          throw abortReason(request.signal);
+        }
+        try {
+          return await provider.generate(request);
+        } catch (error) {
+          lastError = error;
+          if (isAbortError(error) || request.signal?.aborted) {
+            throw error;
+          }
+          const isLastAttempt = attempt >= settings.maxAttempts;
+          if (isLastAttempt || !settings.retryOn(error)) {
+            throw error;
+          }
+          const delayMs = chooseDelay({ attempt, error, settings, policy });
+          policy.onRetry?.({
+            attempt,
+            maxAttempts: settings.maxAttempts,
+            delayMs,
+            error,
+            providerId: provider.id
+          });
+          await settings.sleep(delayMs, request.signal);
+        }
+      }
+      // Unreachable in practice — the loop either returns or throws — but TS
+      // needs an explicit fallthrough.
+      throw lastError ?? new DogpileError({
+        code: "unknown",
+        message: "withRetry: exhausted attempts without throwing or returning."
+      });
+    }
+  };
+
+  if (typeof provider.stream === "function") {
+    const upstreamStream = provider.stream.bind(provider);
+    wrapped.stream = (request: ModelRequest): AsyncIterable<ModelOutputChunk> =>
+      upstreamStream(request);
+  }
+
+  return wrapped;
+}
+
+function chooseDelay(args: {
+  attempt: number;
+  error: unknown;
+  settings: { baseDelayMs: number; maxDelayMs: number; jitter: RetryJitterMode; random: () => number };
+  policy: RetryPolicy;
+}): number {
+  const override = args.policy.delayForError?.(args.error) ?? retryAfterFromError(args.error);
+  if (override !== undefined && Number.isFinite(override) && override >= 0) {
+    return Math.min(args.settings.maxDelayMs, override);
+  }
+  const exponential = args.settings.baseDelayMs * 2 ** (args.attempt - 1);
+  const capped = Math.min(args.settings.maxDelayMs, exponential);
+  if (args.settings.jitter === "none") {
+    return capped;
+  }
+  return Math.floor(capped * args.settings.random());
+}
+
+function defaultRetryOn(error: unknown): boolean {
+  if (isAbortError(error)) return false;
+  if (DogpileError.isInstance(error)) {
+    if (error.code === "aborted" || error.code === "invalid-configuration") {
+      return false;
+    }
+    return DEFAULT_RETRYABLE_DOGPILE_CODES.includes(error.code);
+  }
+  // Treat generic network/transient errors as retryable. Most fetch errors
+  // surface as `TypeError` with messages like "fetch failed" / "network".
+  if (error instanceof TypeError) return true;
+  return false;
+}
+
+function isAbortError(error: unknown): boolean {
+  if (DogpileError.isInstance(error) && error.code === "aborted") return true;
+  if (typeof error === "object" && error !== null) {
+    const name = (error as { name?: unknown }).name;
+    if (name === "AbortError") return true;
+  }
+  return false;
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new DogpileError({ code: "aborted", message: "Request aborted." });
+}
+
+function retryAfterFromError(error: unknown): number | undefined {
+  if (!DogpileError.isInstance(error)) return undefined;
+  const detail = error.detail;
+  if (!detail || typeof detail !== "object") return undefined;
+  const candidate = (detail as { retryAfterMs?: unknown }).retryAfterMs;
+  if (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0) {
+    return candidate;
+  }
+  return undefined;
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(abortReason(signal!));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/runtime/sequential.ts

@@ -18,6 +18,7 @@ import type {
   Tier,
   TranscriptEntry
 } from "../types.js";
+import { createRunId, elapsedMs, nowMs } from "./ids.js";
 import {
   addCost,
   createReplayTraceBudget,
@@ -217,7 +218,15 @@ export async function runSequential(options: SequentialRunOptions): Promise<RunR
     }
   }
 
-  const output = [...transcript].reverse().find((entry) => isParticipatingDecision(entry.decision))?.output ?? "";
+  // Preferred: most recent entry with an explicit participating decision.
+  // Fallback: most recent entry that has no parsed decision at all (preserves
+  // pre-discriminated-union behavior where unparsed turns were treated as
+  // participating). Delegate decisions are explicitly non-participating.
+  const reversed = [...transcript].reverse();
+  const output =
+    reversed.find((entry) => isParticipatingDecision(entry.decision))?.output ??
+    reversed.find((entry) => entry.decision === undefined)?.output ??
+    "";
   throwIfAborted(options.signal, options.model.id);
   const final: RunEvent = {
     type: "final",
@@ -369,15 +378,3 @@ function responseCost(response: ModelResponse): CostSummary {
   };
 }
 
-function createRunId(): string {
-  const random = globalThis.crypto?.randomUUID?.();
-  return random ?? `run-${Date.now().toString(36)}`;
-}
-
-function nowMs(): number {
-  return globalThis.performance?.now() ?? Date.now();
-}
-
-function elapsedMs(startedAtMs: number): number {
-  return Math.max(0, nowMs() - startedAtMs);
-}

package/src/runtime/shared.ts

@@ -18,6 +18,7 @@ import type {
   Tier,
   TranscriptEntry
 } from "../types.js";
+import { createRunId, elapsedMs, nowMs, providerCallIdFor } from "./ids.js";
 import {
   addCost,
   createReplayTraceBudget,
@@ -375,19 +376,3 @@ function responseCost(response: ModelResponse): CostSummary {
   };
 }
 
-function createRunId(): string {
-  const random = globalThis.crypto?.randomUUID?.();
-  return random ?? `run-${Date.now().toString(36)}`;
-}
-
-function nowMs(): number {
-  return globalThis.performance?.now() ?? Date.now();
-}
-
-function elapsedMs(startedAtMs: number): number {
-  return Math.max(0, nowMs() - startedAtMs);
-}
-
-function providerCallIdFor(runId: string, oneBasedIndex: number): string {
-  return `${runId}:provider-call:${oneBasedIndex}`;
-}