@dogpile/sdk 0.3.1 → 0.5.0

package/src/index.ts

@@ -12,6 +12,8 @@ export { consoleLogger, loggerFromEvents, noopLogger } from "./runtime/logger.js
 export type { Logger, LoggerFromEventsOptions, LogLevel } from "./runtime/logger.js";
 export { DEFAULT_RETRYABLE_DOGPILE_CODES, withRetry } from "./runtime/retry.js";
 export type { RetryAttemptInfo, RetryJitterMode, RetryPolicy } from "./runtime/retry.js";
+export { DOGPILE_SPAN_NAMES } from "./runtime/tracing.js";
+export type { DogpileSpan, DogpileSpanOptions, DogpileTracer } from "./runtime/tracing.js";
 export { DogpileError } from "./types.js";
 export type {
   OpenAICompatibleChatCompletionChoice,
@@ -75,9 +77,11 @@ export {
   judge
 } from "./runtime/termination.js";
 export type {
+  AbortedEvent,
   AgentSpec,
   AgentDecision,
   AgentParticipation,
+  AnomalyCode,
   BroadcastContribution,
   BroadcastEvent,
   BroadcastProtocolConfig,
@@ -93,12 +97,15 @@ export type {
   CoordinationProtocolSelection,
   CostSummary,
   CoordinatorProtocolConfig,
+  DelegateAgentDecision,
   DogpileErrorCode,
   DogpileErrorOptions,
   DogpileOptions,
   Engine,
   EngineOptions,
+  RunCallOptions,
   FinalEvent,
+  HealthAnomaly,
   FirstOfTerminationCondition,
   FirstOfTerminationConditions,
   FirstOfTerminationInput,
@@ -147,6 +154,7 @@ export type {
   RunEvaluator,
   RunEventLog,
   RunEvent,
+  RunHealthSummary,
   RunMetadata,
   RunResult,
   RunUsage,
@@ -184,6 +192,13 @@ export type {
   StreamOutputEvent,
   StreamSubscription,
   StopTerminationDecision,
+  SubRunBudgetClampedEvent,
+  SubRunCompletedEvent,
+  SubRunConcurrencyClampedEvent,
+  SubRunFailedEvent,
+  SubRunParentAbortedEvent,
+  SubRunQueuedEvent,
+  SubRunStartedEvent,
   TerminationCondition,
   TerminationDecision,
   TerminationEvaluationContext,

package/src/providers/openai-compatible.ts

@@ -37,6 +37,8 @@ export interface OpenAICompatibleProviderOptions {
   readonly maxOutputTokens?: number;
   readonly extraBody?: JsonObject;
   readonly costEstimator?: OpenAICompatibleProviderCostEstimator;
+  /** Locality hint override; if omitted, auto-detected from baseURL. Explicit "local" always wins; explicit "remote" on a detected-local host throws. */
+  readonly locality?: "local" | "remote";
 }
 
 export interface OpenAICompatibleChatCompletionResponse {
@@ -68,6 +70,10 @@ export function createOpenAICompatibleProvider(options: OpenAICompatibleProvider
 
   const providerId = options.id ?? `openai-compatible:${options.model}`;
   const fetchImplementation = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  const baseURLForLocality = new URL(String(options.baseURL ?? defaultBaseURL));
+  const detectedLocality = classifyHostLocality(baseURLForLocality.hostname);
+  const resolvedLocality: "local" | "remote" =
+    options.locality === "local" ? "local" : options.locality === "remote" ? "remote" : detectedLocality;
 
   if (!fetchImplementation) {
     throw new DogpileError({
@@ -85,6 +91,8 @@ export function createOpenAICompatibleProvider(options: OpenAICompatibleProvider
 
   return {
     id: providerId,
+    modelId: options.model,
+    metadata: { locality: resolvedLocality },
     async generate(request: ModelRequest): Promise<ModelResponse> {
       let response: Response;
 
@@ -99,12 +107,12 @@ export function createOpenAICompatibleProvider(options: OpenAICompatibleProvider
         throw normalizeFetchError(error, providerId);
       }
 
-      const payload = await readJson(response, providerId);
-
       if (!response.ok) {
+        const payload = await readJsonLenient(response);
         throw createProviderError(response, payload, providerId);
       }
 
+      const payload = await readJson(response, providerId);
       const completion = asChatCompletionResponse(payload, providerId);
       const text = readAssistantText(completion, providerId);
       const usage = normalizeUsage(completion.usage);
@@ -154,6 +162,27 @@ function validateOptions(options: OpenAICompatibleProviderOptions): void {
   if (options.costEstimator !== undefined && typeof options.costEstimator !== "function") {
     throwInvalid("costEstimator", "a function when provided");
   }
+  if (options.locality !== undefined && options.locality !== "local" && options.locality !== "remote") {
+    throwInvalid("locality", "\"local\" | \"remote\" when provided");
+  }
+  if (options.locality === "remote") {
+    const baseURL = new URL(String(options.baseURL ?? defaultBaseURL));
+    const detected = classifyHostLocality(baseURL.hostname);
+    if (detected === "local") {
+      throw new DogpileError({
+        code: "invalid-configuration",
+        message: `locality "remote" cannot be set when baseURL resolves to a local host (${baseURL.hostname}).`,
+        retryable: false,
+        detail: {
+          kind: "configuration-validation",
+          path: "locality",
+          expected: "\"local\" (or omit to auto-detect)",
+          reason: "remote-override-on-local-host",
+          host: baseURL.hostname
+        }
+      });
+    }
+  }
 }
 
 function throwInvalid(path: string, expected: string): never {
@@ -169,6 +198,46 @@ function throwInvalid(path: string, expected: string): never {
   });
 }
 
+/**
+ * Classify a URL hostname as "local" or "remote" per Phase 3 D-02.
+ * Local: localhost, *.local mDNS, IPv4 loopback (127.0.0.0/8), RFC1918
+ * (10/8, 172.16/12, 192.168/16), link-local (169.254/16), IPv6 loopback (::1),
+ * IPv6 ULA (fc00::/7), IPv6 link-local (fe80::/10).
+ *
+ * Pure function: no I/O, no side effects. Exported for tests and future reuse.
+ */
+export function classifyHostLocality(host: string): "local" | "remote" {
+  const lower = host.toLowerCase().replace(/^\[|\]$/g, "");
+  const mappedIpv4 = ipv4MappedToDottedQuad(lower);
+  if (mappedIpv4 !== undefined) {
+    return classifyHostLocality(mappedIpv4);
+  }
+  if (lower === "localhost") return "local";
+  if (lower.endsWith(".local")) return "local";
+  if (/^127(?:\.\d{1,3}){3}$/.test(lower)) return "local";
+  if (/^10(?:\.\d{1,3}){3}$/.test(lower)) return "local";
+  if (/^172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}$/.test(lower)) return "local";
+  if (/^192\.168(?:\.\d{1,3}){2}$/.test(lower)) return "local";
+  if (/^169\.254(?:\.\d{1,3}){2}$/.test(lower)) return "local";
+  if (lower === "::1") return "local";
+  if (/^f[cd][0-9a-f]{2}:/.test(lower)) return "local";
+  if (/^fe[89ab][0-9a-f]?:/.test(lower)) return "local";
+  return "remote";
+}
+
+function ipv4MappedToDottedQuad(host: string): string | undefined {
+  const match = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+  if (match === null) {
+    return undefined;
+  }
+  const high = Number.parseInt(match[1] ?? "", 16);
+  const low = Number.parseInt(match[2] ?? "", 16);
+  if (!Number.isFinite(high) || !Number.isFinite(low)) {
+    return undefined;
+  }
+  return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}
+
 function createURL(options: OpenAICompatibleProviderOptions): URL {
   const baseURL = new URL(String(options.baseURL ?? defaultBaseURL));
   const path = options.path ?? defaultPath;
@@ -232,6 +301,14 @@ async function readJson(response: Response, providerId: string): Promise<unknown
   }
 }
 
+async function readJsonLenient(response: Response): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch {
+    return undefined;
+  }
+}
+
 function asChatCompletionResponse(payload: unknown, providerId: string): OpenAICompatibleChatCompletionResponse {
   if (!isRecord(payload)) {
     throw new DogpileError({
@@ -341,14 +418,17 @@ function responseMetadata(response: OpenAICompatibleChatCompletionResponse): Jso
 }
 
 function createProviderError(response: Response, payload: unknown, providerId: string): DogpileError {
+  const code = codeForStatus(response.status);
+  const timeoutSource = code === "provider-timeout" ? { source: "provider" as const } : {};
   return new DogpileError({
-    code: codeForStatus(response.status),
+    code,
     message: providerResponseErrorMessage(response, payload),
     retryable: response.status === 408 || response.status === 429 || response.status >= 500,
     providerId,
     detail: removeUndefined({
       statusCode: response.status,
       statusText: response.statusText,
+      ...timeoutSource,
       response: isJsonValue(payload) ? payload : undefined
     })
   });

package/src/runtime/audit.ts

@@ -0,0 +1,121 @@
+import type { Protocol, Tier, Trace } from "../types.js";
+import type { BudgetStopEvent, FinalEvent, SubRunCompletedEvent, TurnEvent } from "../types/events.js";
+
+export type AuditOutcomeStatus = "completed" | "budget-stopped" | "aborted";
+
+export interface AuditOutcome {
+  readonly status: AuditOutcomeStatus;
+  readonly terminationCode?: string;
+}
+
+export interface AuditCost {
+  readonly usd: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+export interface AuditAgentRecord {
+  readonly id: string;
+  readonly role: string;
+  readonly turnCount: number;
+}
+
+export interface AuditRecord {
+  readonly auditSchemaVersion: "1";
+  readonly runId: string;
+  readonly intent: string;
+  readonly startedAt: string;
+  readonly completedAt: string;
+  readonly protocol: Protocol;
+  readonly tier: Tier;
+  readonly modelProviderId: string;
+  readonly agentCount: number;
+  readonly turnCount: number;
+  readonly outcome: AuditOutcome;
+  readonly cost: AuditCost;
+  readonly agents: readonly AuditAgentRecord[];
+  readonly childRunIds?: readonly string[];
+}
+
+/**
+ * Derive a versioned, schema-stable audit record from a completed run trace.
+ *
+ * Pure function - no side effects, no I/O, no storage access. Deterministic:
+ * given the same trace, always produces the same AuditRecord.
+ *
+ * @param trace - Completed run trace (from RunResult.trace or a stored/replayed trace).
+ */
+export function createAuditRecord(trace: Trace): AuditRecord {
+  const finalEvent = trace.events.find((event): event is FinalEvent => event.type === "final");
+  const budgetStopEvent = trace.events.find((event): event is BudgetStopEvent => event.type === "budget-stop");
+
+  const outcome: AuditOutcome = budgetStopEvent
+    ? { status: "budget-stopped", terminationCode: budgetStopEvent.reason }
+    : finalEvent
+      ? { status: "completed" }
+      : { status: "aborted" };
+
+  const lastTurnCost = [...trace.events]
+    .reverse()
+    .find((event): event is TurnEvent => event.type === "agent-turn")?.cost;
+  const costSource = finalEvent?.cost ?? budgetStopEvent?.cost ?? lastTurnCost;
+  const cost: AuditCost = {
+    usd: costSource?.usd ?? 0,
+    inputTokens: costSource?.inputTokens ?? 0,
+    outputTokens: costSource?.outputTokens ?? 0
+  };
+
+  const turnEvents = trace.events.filter((event): event is TurnEvent => event.type === "agent-turn");
+  const agentTurnMap = new Map<string, { role: string; count: number }>();
+  for (const event of turnEvents) {
+    const existing = agentTurnMap.get(event.agentId);
+    if (existing !== undefined) {
+      existing.count++;
+    } else {
+      agentTurnMap.set(event.agentId, { role: event.role, count: 1 });
+    }
+  }
+
+  const agents: AuditAgentRecord[] = [...agentTurnMap.entries()]
+    .map(([id, { role, count }]) => ({ id, role, turnCount: count }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const childRunIds = trace.events
+    .filter((event): event is SubRunCompletedEvent => event.type === "sub-run-completed")
+    .map((event) => event.childRunId);
+
+  const startedAt = eventStartedAt(trace.events[0]);
+
+  return {
+    auditSchemaVersion: "1",
+    runId: trace.runId,
+    intent: trace.inputs.intent,
+    startedAt,
+    completedAt: trace.finalOutput.completedAt,
+    protocol: trace.protocol,
+    tier: trace.tier,
+    modelProviderId: trace.modelProviderId,
+    agentCount: agentTurnMap.size,
+    turnCount: turnEvents.length,
+    outcome,
+    cost,
+    agents,
+    ...(childRunIds.length > 0 ? { childRunIds } : {})
+  };
+}
+
+function eventStartedAt(event: Trace["events"][number] | undefined): string {
+  if (event === undefined) {
+    return "";
+  }
+
+  if ("at" in event) {
+    return event.at;
+  }
+
+  if ("startedAt" in event) {
+    return event.startedAt;
+  }
+
+  return "";
+}

package/src/runtime/broadcast.ts

@@ -17,6 +17,7 @@ import type {
   TerminationCondition,
   TerminationStopRecord,
   Tier,
+  Trace,
   TranscriptEntry
 } from "../types.js";
 import { createRunId, elapsedMs, nowMs, providerCallIdFor } from "./ids.js";
@@ -35,6 +36,7 @@ import {
   createTranscriptLink,
   emptyCost
 } from "./defaults.js";
+import { computeHealth, DEFAULT_HEALTH_THRESHOLDS } from "./health.js";
 import { throwIfAborted } from "./cancellation.js";
 import { parseAgentDecision } from "./decisions.js";
 import { generateModelTurn } from "./model.js";
@@ -289,45 +291,46 @@ export async function runBroadcast(options: BroadcastRunOptions): Promise<RunRes
     transcriptEntryCount: transcript.length
   });
   const finalEvent = events.at(-1);
+  const trace: Trace = {
+    schemaVersion: "1.0",
+    runId,
+    protocol: "broadcast",
+    tier: options.tier,
+    modelProviderId: options.model.id,
+    agentsUsed: options.agents,
+    inputs: createReplayTraceRunInputs({
+      intent: options.intent,
+      protocol: options.protocol,
+      tier: options.tier,
+      modelProviderId: options.model.id,
+      agents: options.agents,
+      temperature: options.temperature
+    }),
+    budget: createReplayTraceBudget({
+      tier: options.tier,
+      ...(options.budget ? { caps: options.budget } : {}),
+      ...(options.terminate ? { termination: options.terminate } : {})
+    }),
+    budgetStateChanges: createReplayTraceBudgetStateChanges(events),
+    seed: createReplayTraceSeed(options.seed),
+    protocolDecisions,
+    providerCalls,
+    finalOutput: createReplayTraceFinalOutput(output, finalEvent ?? {
+      type: "final",
+      runId,
+      at: "",
+      output,
+      cost: totalCost,
+      transcript: createTranscriptLink(transcript)
+    }),
+    events,
+    transcript
+  };
 
   return {
     output,
     eventLog: createRunEventLog(runId, "broadcast", events),
-    trace: {
-      schemaVersion: "1.0",
-      runId,
-      protocol: "broadcast",
-      tier: options.tier,
-      modelProviderId: options.model.id,
-      agentsUsed: options.agents,
-      inputs: createReplayTraceRunInputs({
-        intent: options.intent,
-        protocol: options.protocol,
-        tier: options.tier,
-        modelProviderId: options.model.id,
-        agents: options.agents,
-        temperature: options.temperature
-      }),
-      budget: createReplayTraceBudget({
-        tier: options.tier,
-        ...(options.budget ? { caps: options.budget } : {}),
-        ...(options.terminate ? { termination: options.terminate } : {})
-      }),
-      budgetStateChanges: createReplayTraceBudgetStateChanges(events),
-      seed: createReplayTraceSeed(options.seed),
-      protocolDecisions,
-      providerCalls,
-      finalOutput: createReplayTraceFinalOutput(output, finalEvent ?? {
-        type: "final",
-        runId,
-        at: "",
-        output,
-        cost: totalCost,
-        transcript: createTranscriptLink(transcript)
-      }),
-      events,
-      transcript
-    },
+    trace,
     transcript,
     usage: createRunUsage(totalCost),
     metadata: createRunMetadata({
@@ -345,7 +348,8 @@ export async function runBroadcast(options: BroadcastRunOptions): Promise<RunRes
       cost: totalCost,
       events
     }),
-    cost: totalCost
+    cost: totalCost,
+    health: computeHealth(trace, DEFAULT_HEALTH_THRESHOLDS)
   };
 
   function stopIfNeeded(): boolean {
@@ -440,4 +444,3 @@ function responseCost(response: ModelResponse): CostSummary {
     totalTokens: response.usage?.totalTokens ?? 0
   };
 }
-

package/src/runtime/cancellation.ts

@@ -1,5 +1,49 @@
 import { DogpileError, type JsonObject } from "../types.js";
 
+/**
+ * Documented-convention vocabulary for `DogpileError({ code: "aborted" }).detail.reason`.
+ *
+ * Internal-only union (D-08): the literal strings are public-by-observation
+ * through `detail.reason` and locked via tests in `event-schema.test.ts` and
+ * `public-error-api.test.ts`, but we deliberately do NOT export the union
+ * type from `src/index.ts` to keep public-surface delta minimal.
+ */
+export type AbortReason = "parent-aborted" | "timeout";
+export type ChildTimeoutSource = "provider" | "engine";
+
+/**
+ * Classify an abort signal's reason into the BUDGET-01 / BUDGET-02
+ * `detail.reason` discriminator.
+ *
+ * - `"timeout"` when the reason is a {@link DogpileError} with `code === "timeout"`
+ *   (matches the parent-deadline abort path in `engine.ts:createTimeoutAbortLifecycle`).
+ * - `"parent-aborted"` for every other reason — explicit caller abort, plain
+ *   `Error`, `undefined`, or arbitrary primitive.
+ */
+export function classifyAbortReason(signalReasonOrError: unknown): AbortReason {
+  if (DogpileError.isInstance(signalReasonOrError) && signalReasonOrError.code === "timeout") {
+    return "timeout";
+  }
+  return "parent-aborted";
+}
+
+export function classifyChildTimeoutSource(
+  _error: unknown,
+  context: {
+    readonly decisionTimeoutMs?: number;
+    readonly engineDefaultTimeoutMs?: number;
+    readonly isProviderError: boolean;
+  }
+): ChildTimeoutSource {
+  if (context.isProviderError) {
+    return "provider";
+  }
+  if (context.decisionTimeoutMs !== undefined || context.engineDefaultTimeoutMs !== undefined) {
+    return "engine";
+  }
+  return "provider";
+}
+
 export function throwIfAborted(signal: AbortSignal | undefined, providerId: string): void {
   if (!signal?.aborted) {
     return;
@@ -24,7 +68,8 @@ export function createAbortErrorFromSignal(signal: AbortSignal, providerId: stri
     return signal.reason;
   }
 
-  return createAbortError(providerId, undefined, signal.reason);
+  const reason = classifyAbortReason(signal.reason);
+  return createAbortError(providerId, { reason }, signal.reason);
 }
 
 export function createTimeoutError(providerId: string, timeoutMs: number): DogpileError {
@@ -38,3 +83,16 @@ export function createTimeoutError(providerId: string, timeoutMs: number): Dogpi
     }
   });
 }
+
+export function createEngineDeadlineTimeoutError(providerId: string, timeoutMs: number): DogpileError {
+  return new DogpileError({
+    code: "provider-timeout",
+    message: `The child engine deadline expired after ${timeoutMs}ms.`,
+    retryable: true,
+    providerId,
+    detail: {
+      timeoutMs,
+      source: "engine"
+    }
+  });
+}