@dogpile/sdk 0.2.2 → 0.3.1

package/src/runtime/ids.ts

@@ -0,0 +1,41 @@
+import { DogpileError } from "../types.js";
+
+/**
+ * Repo-internal id and timing helpers used across all four protocols.
+ *
+ * Centralized here so a change to id format or fallback semantics happens in
+ * exactly one place — switching `protocol` must not change the run-id contract.
+ */
+
+/**
+ * Generates a fresh run id using `globalThis.crypto.randomUUID`.
+ *
+ * Throws a `DogpileError` when no UUID source is available rather than falling
+ * back to a millisecond-based id (which collides under back-to-back runs in
+ * the same tick). Node 22+, Bun latest, and modern browsers all expose
+ * `crypto.randomUUID`; environments without it are unsupported by Dogpile.
+ */
+export function createRunId(): string {
+  const random = globalThis.crypto?.randomUUID?.();
+  if (typeof random === "string" && random.length > 0) {
+    return random;
+  }
+  throw new DogpileError({
+    code: "invalid-configuration",
+    message:
+      "Dogpile requires globalThis.crypto.randomUUID to mint a run id. " +
+      "Run on Node 22+, Bun latest, or a modern browser ESM environment."
+  });
+}
+
+export function nowMs(): number {
+  return globalThis.performance?.now() ?? Date.now();
+}
+
+export function elapsedMs(startedAtMs: number): number {
+  return Math.max(0, nowMs() - startedAtMs);
+}
+
+export function providerCallIdFor(runId: string, oneBasedIndex: number): string {
+  return `${runId}:provider-call:${oneBasedIndex}`;
+}

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,
@@ -37,8 +38,9 @@ import {
 import { throwIfAborted } from "./cancellation.js";
 import { isParticipatingDecision, parseAgentDecision } from "./decisions.js";
 import { generateModelTurn } from "./model.js";
-import { evaluateTerminationStop } from "./termination.js";
+import { evaluateTerminationStop, warnOnProtocolTerminationMisconfiguration } from "./termination.js";
 import { createRuntimeToolExecutor, executeModelResponseToolRequests, runtimeToolAvailability } from "./tools.js";
+import { createWrapUpHintController } from "./wrap-up.js";
 
 interface SequentialRunOptions {
   readonly intent: string;
@@ -52,6 +54,7 @@ interface SequentialRunOptions {
   readonly seed?: string | number;
   readonly signal?: AbortSignal;
   readonly terminate?: TerminationCondition;
+  readonly wrapUpHint?: DogpileOptions["wrapUpHint"];
   readonly emit?: (event: RunEvent) => void;
 }
 
@@ -67,6 +70,15 @@ export async function runSequential(options: SequentialRunOptions): Promise<RunR
   const startedAtMs = nowMs();
   let stopped = false;
   let termination: TerminationStopRecord | undefined;
+  const wrapUpHint = createWrapUpHintController({
+    protocol: options.protocol,
+    tier: options.tier,
+    ...(options.budget ? { budget: options.budget } : {}),
+    ...(options.terminate ? { terminate: options.terminate } : {}),
+    ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {})
+  });
+
+  warnOnProtocolTerminationMisconfiguration(options.protocol, options.terminate);
 
   const emit = (event: RunEvent): void => {
     events.push(event);
@@ -129,16 +141,27 @@ export async function runSequential(options: SequentialRunOptions): Promise<RunR
         turn,
         ...toolAvailability
       },
-      messages: [
+      messages: wrapUpHint.inject(
+        [
+          {
+            role: "system",
+            content: buildSystemPrompt(agent)
+          },
+          {
+            role: "user",
+            content: input
+          }
+        ],
         {
-          role: "system",
-          content: buildSystemPrompt(agent)
-        },
-        {
-          role: "user",
-          content: input
+          runId,
+          protocol: "sequential",
+          cost: totalCost,
+          events,
+          transcript,
+          iteration: transcript.length,
+          elapsedMs: elapsedMs(startedAtMs)
         }
-      ]
+      )
     };
     const response = await generateModelTurn({
       model: options.model,
@@ -277,16 +300,20 @@ export async function runSequential(options: SequentialRunOptions): Promise<RunR
       return stopped;
     }
 
-    const stopRecord = evaluateTerminationStop(options.terminate, {
-      runId,
-      protocol: "sequential",
-      tier: options.tier,
-      cost: totalCost,
-      events,
-      transcript,
-      iteration: transcript.length,
-      elapsedMs: elapsedMs(startedAtMs)
-    });
+    const stopRecord = evaluateTerminationStop(
+      options.terminate,
+      wrapUpHint.context({
+        runId,
+        protocol: "sequential",
+        protocolConfig: options.protocol,
+        protocolIteration: transcript.length,
+        cost: totalCost,
+        events,
+        transcript,
+        iteration: transcript.length,
+        elapsedMs: elapsedMs(startedAtMs)
+      })
+    );
 
     if (!stopRecord) {
       return false;
@@ -343,15 +370,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);
-}