@dogpile/sdk 0.4.0 → 0.6.0

package/src/runtime/redaction.ts

@@ -0,0 +1,355 @@
+import type {
+  AgentDecision,
+  DelegateAgentDecision,
+  JsonObject,
+  ModelRequest,
+  ModelResponse,
+  ReplayTraceProtocolDecision,
+  ReplayTraceProviderCall,
+  RunEvent,
+  RunEventLog,
+  RunResult,
+  RuntimeToolExecutionRequest,
+  RuntimeToolResult,
+  Trace,
+  TranscriptEntry,
+  TranscriptToolCall
+} from "../types.js";
+
+export interface TraceRedactionOptions {
+  readonly replacementText?: string;
+  readonly redactPrompts?: boolean;
+  readonly redactOutputs?: boolean;
+  readonly redactToolInputs?: boolean;
+  readonly redactToolOutputs?: boolean;
+  readonly redactProviderResponses?: boolean;
+  readonly redactEmbeddedChildTraces?: boolean;
+}
+
+const DEFAULT_REPLACEMENT_TEXT = "[REDACTED]";
+const REDACTED_JSON_OBJECT: JsonObject = { redacted: true };
+
+export function redactTrace(trace: Trace, options: TraceRedactionOptions = {}): Trace {
+  return {
+    ...trace,
+    inputs: shouldRedactPrompts(options)
+      ? {
+          ...trace.inputs,
+          intent: replacement(options)
+        }
+      : trace.inputs,
+    protocolDecisions: trace.protocolDecisions.map((decision) => redactProtocolDecision(decision, options)),
+    providerCalls: trace.providerCalls.map((call) => redactProviderCall(call, options)),
+    finalOutput: shouldRedactOutputs(options)
+      ? {
+          ...trace.finalOutput,
+          output: replacement(options)
+        }
+      : trace.finalOutput,
+    events: trace.events.map((event) => redactRunEvent(event, options)),
+    transcript: trace.transcript.map((entry) => redactTranscriptEntry(entry, options))
+  };
+}
+
+export function redactRunResult(result: RunResult, options: TraceRedactionOptions = {}): RunResult {
+  const trace = redactTrace(result.trace, options);
+  const eventLog: RunEventLog = {
+    ...result.eventLog,
+    events: trace.events,
+    eventTypes: trace.events.map((event) => event.type),
+    eventCount: trace.events.length
+  };
+
+  return {
+    ...result,
+    output: shouldRedactOutputs(options) ? replacement(options) : result.output,
+    eventLog,
+    trace,
+    transcript: trace.transcript
+  };
+}
+
+function redactRunEvent(event: RunEvent, options: TraceRedactionOptions): RunEvent {
+  switch (event.type) {
+    case "model-request":
+      return {
+        ...event,
+        request: redactModelRequest(event.request, options)
+      };
+    case "model-response":
+      return {
+        ...event,
+        response: redactModelResponse(event.response, options)
+      };
+    case "model-output-chunk":
+      return shouldRedactOutputs(options)
+        ? {
+            ...event,
+            text: replacement(options),
+            outputLength: 0
+          }
+        : event;
+    case "tool-call":
+      return shouldRedactToolInputs(options)
+        ? {
+            ...event,
+            input: REDACTED_JSON_OBJECT
+          }
+        : event;
+    case "tool-result":
+      return {
+        ...event,
+        result: redactRuntimeToolResult(event.result, options)
+      };
+    case "agent-turn":
+      return {
+        ...event,
+        ...(shouldRedactPrompts(options) ? { input: replacement(options) } : {}),
+        ...(shouldRedactOutputs(options) ? { output: replacement(options) } : {}),
+        ...(event.decision !== undefined ? { decision: redactDecision(event.decision, options) } : {})
+      };
+    case "broadcast":
+      return {
+        ...event,
+        contributions: event.contributions.map((contribution) => ({
+          ...contribution,
+          ...(shouldRedactOutputs(options) ? { output: replacement(options) } : {}),
+          ...(contribution.decision !== undefined
+            ? { decision: redactDecision(contribution.decision, options) }
+            : {})
+        }))
+      };
+    case "sub-run-completed":
+      return shouldRedactEmbeddedChildTraces(options)
+        ? {
+            ...event,
+            subResult: redactRunResult(event.subResult, options)
+          }
+        : event;
+    case "sub-run-failed":
+      return shouldRedactEmbeddedChildTraces(options)
+        ? {
+            ...event,
+            error: {
+              ...event.error,
+              ...(event.error.detail !== undefined
+                ? { detail: redactErrorDetail(event.error.detail, options) }
+                : {})
+            },
+            partialTrace: redactTrace(event.partialTrace, options)
+          }
+        : event;
+    case "final":
+      return shouldRedactOutputs(options)
+        ? {
+            ...event,
+            output: replacement(options)
+          }
+        : event;
+    case "role-assignment":
+    case "budget-stop":
+    case "sub-run-started":
+    case "sub-run-parent-aborted":
+    case "sub-run-budget-clamped":
+    case "sub-run-queued":
+    case "sub-run-concurrency-clamped":
+      return event;
+  }
+}
+
+function redactProviderCall(
+  call: ReplayTraceProviderCall,
+  options: TraceRedactionOptions
+): ReplayTraceProviderCall {
+  return {
+    ...call,
+    request: redactModelRequest(call.request, options),
+    response: redactModelResponse(call.response, options)
+  };
+}
+
+function redactProtocolDecision(
+  decision: ReplayTraceProtocolDecision,
+  options: TraceRedactionOptions
+): ReplayTraceProtocolDecision {
+  return {
+    ...decision,
+    ...(decision.input !== undefined && shouldRedactPrompts(options) ? { input: replacement(options) } : {}),
+    ...(decision.output !== undefined && shouldRedactOutputs(options) ? { output: replacement(options) } : {})
+  };
+}
+
+function redactModelRequest(request: ModelRequest, options: TraceRedactionOptions): ModelRequest {
+  return shouldRedactPrompts(options)
+    ? {
+        ...request,
+        messages: request.messages.map((message) => ({
+          ...message,
+          content: replacement(options)
+        }))
+      }
+    : request;
+}
+
+function redactModelResponse(response: ModelResponse, options: TraceRedactionOptions): ModelResponse {
+  const redactedToolRequests = response.toolRequests?.map((request) => redactToolRequest(request, options));
+
+  if (shouldRedactProviderResponses(options)) {
+    return {
+      text: replacement(options),
+      ...(response.finishReason !== undefined ? { finishReason: response.finishReason } : {}),
+      ...(redactedToolRequests !== undefined && redactedToolRequests.length > 0 ? { toolRequests: redactedToolRequests } : {}),
+      ...(response.usage !== undefined ? { usage: response.usage } : {}),
+      ...(response.costUsd !== undefined ? { costUsd: response.costUsd } : {})
+    };
+  }
+
+  return {
+    ...response,
+    ...(shouldRedactOutputs(options) ? { text: replacement(options) } : {}),
+    ...(redactedToolRequests !== undefined ? { toolRequests: redactedToolRequests } : {})
+  };
+}
+
+function redactToolRequest(
+  request: RuntimeToolExecutionRequest,
+  options: TraceRedactionOptions
+): RuntimeToolExecutionRequest {
+  return shouldRedactToolInputs(options)
+    ? {
+        ...request,
+        input: REDACTED_JSON_OBJECT
+      }
+    : request;
+}
+
+function redactTranscriptEntry(entry: TranscriptEntry, options: TraceRedactionOptions): TranscriptEntry {
+  return {
+    ...entry,
+    ...(shouldRedactPrompts(options) ? { input: replacement(options) } : {}),
+    ...(shouldRedactOutputs(options) ? { output: replacement(options) } : {}),
+    ...(entry.decision !== undefined ? { decision: redactDecision(entry.decision, options) } : {}),
+    ...(entry.toolCalls !== undefined
+      ? { toolCalls: entry.toolCalls.map((toolCall) => redactTranscriptToolCall(toolCall, options)) }
+      : {})
+  };
+}
+
+function redactTranscriptToolCall(
+  toolCall: TranscriptToolCall,
+  options: TraceRedactionOptions
+): TranscriptToolCall {
+  return {
+    ...toolCall,
+    ...(shouldRedactToolInputs(options) ? { input: REDACTED_JSON_OBJECT } : {}),
+    result: redactRuntimeToolResult(toolCall.result, options)
+  };
+}
+
+function redactRuntimeToolResult(result: RuntimeToolResult, options: TraceRedactionOptions): RuntimeToolResult {
+  if (!shouldRedactToolOutputs(options)) {
+    return result;
+  }
+
+  if (result.type === "success") {
+    return {
+      ...result,
+      output: REDACTED_JSON_OBJECT
+    };
+  }
+
+  return {
+    ...result,
+    error: {
+      ...result.error,
+      ...(result.error.detail !== undefined ? { detail: REDACTED_JSON_OBJECT } : {})
+    }
+  };
+}
+
+function redactDecision(
+  decision: AgentDecision | readonly DelegateAgentDecision[],
+  options: TraceRedactionOptions
+): AgentDecision | readonly DelegateAgentDecision[] {
+  if (isDelegateDecisionArray(decision)) {
+    return decision.map((delegate) => redactDelegateDecision(delegate, options));
+  }
+  if (decision.type === "delegate") {
+    return redactDelegateDecision(decision, options);
+  }
+  return {
+    ...decision,
+    ...(shouldRedactOutputs(options)
+      ? {
+          rationale: replacement(options),
+          contribution: replacement(options)
+        }
+      : {})
+  };
+}
+
+function isDelegateDecisionArray(
+  decision: AgentDecision | readonly DelegateAgentDecision[]
+): decision is readonly DelegateAgentDecision[] {
+  return Array.isArray(decision);
+}
+
+function redactDelegateDecision(
+  decision: DelegateAgentDecision,
+  options: TraceRedactionOptions
+): DelegateAgentDecision {
+  return shouldRedactPrompts(options)
+    ? {
+        ...decision,
+        intent: replacement(options)
+      }
+    : decision;
+}
+
+function redactErrorDetail(detail: JsonObject, options: TraceRedactionOptions): JsonObject {
+  const failedDecision = detail["failedDecision"];
+  if (
+    !shouldRedactPrompts(options) ||
+    typeof failedDecision !== "object" ||
+    failedDecision === null ||
+    Array.isArray(failedDecision)
+  ) {
+    return detail;
+  }
+
+  return {
+    ...detail,
+    failedDecision: {
+      ...failedDecision,
+      intent: replacement(options)
+    }
+  };
+}
+
+function shouldRedactPrompts(options: TraceRedactionOptions): boolean {
+  return options.redactPrompts ?? true;
+}
+
+function shouldRedactOutputs(options: TraceRedactionOptions): boolean {
+  return options.redactOutputs ?? true;
+}
+
+function shouldRedactToolInputs(options: TraceRedactionOptions): boolean {
+  return options.redactToolInputs ?? true;
+}
+
+function shouldRedactToolOutputs(options: TraceRedactionOptions): boolean {
+  return options.redactToolOutputs ?? true;
+}
+
+function shouldRedactProviderResponses(options: TraceRedactionOptions): boolean {
+  return options.redactProviderResponses ?? true;
+}
+
+function shouldRedactEmbeddedChildTraces(options: TraceRedactionOptions): boolean {
+  return options.redactEmbeddedChildTraces ?? true;
+}
+
+function replacement(options: TraceRedactionOptions): string {
+  return options.replacementText ?? DEFAULT_REPLACEMENT_TEXT;
+}

package/src/runtime/sanitization.ts

@@ -0,0 +1,81 @@
+import type { JsonObject, JsonValue } from "../types.js";
+
+const safeResponseHeaderNames = new Set([
+  "content-type",
+  "date",
+  "request-id",
+  "retry-after",
+  "x-ratelimit-limit",
+  "x-ratelimit-remaining",
+  "x-ratelimit-reset",
+  "x-request-id",
+  "x-stream-request-id"
+]);
+
+const authLikeKeyPattern =
+  /^(?:authorization|proxy-authorization|cookie|set-cookie|x-api-key|api-key|apikey|api_key|x-auth-token|x-access-token|x-goog-api-key)$/i;
+
+export function sanitizeProviderJsonValue(value: unknown): JsonValue | undefined {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((child) => sanitizeProviderJsonValue(child) ?? null);
+  }
+
+  if (isRecord(value)) {
+    const result: Record<string, JsonValue> = {};
+
+    for (const [key, child] of Object.entries(value)) {
+      if (isAuthLikeKey(key)) {
+        continue;
+      }
+      const jsonValue = sanitizeProviderJsonValue(child);
+      if (jsonValue !== undefined) {
+        result[key] = jsonValue;
+      }
+    }
+
+    return result;
+  }
+
+  return undefined;
+}
+
+export function sanitizeProviderResponseHeaders(headers: Headers | Record<string, unknown> | undefined): JsonObject | undefined {
+  if (headers === undefined) {
+    return undefined;
+  }
+
+  const result: Record<string, JsonValue> = {};
+  const entries =
+    typeof Headers !== "undefined" && headers instanceof Headers
+      ? Array.from(headers.entries())
+      : Object.entries(headers).map(([key, value]) => [key, String(value)] as const);
+
+  for (const [key, value] of entries) {
+    const normalizedKey = key.toLowerCase();
+    if (safeResponseHeaderNames.has(normalizedKey) && value !== undefined) {
+      result[normalizedKey] = String(value);
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function isAuthLikeKey(key: string): boolean {
+  return authLikeKeyPattern.test(key);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/runtime/sequential.ts

@@ -16,6 +16,7 @@ import type {
   TerminationCondition,
   TerminationStopRecord,
   Tier,
+  Trace,
   TranscriptEntry
 } from "../types.js";
 import { createRunId, elapsedMs, nowMs } from "./ids.js";
@@ -35,6 +36,7 @@ import {
   emptyCost,
   nextProviderCallId
 } from "./defaults.js";
+import { computeHealth, DEFAULT_HEALTH_THRESHOLDS } from "./health.js";
 import { throwIfAborted } from "./cancellation.js";
 import { isParticipatingDecision, parseAgentDecision } from "./decisions.js";
 import { generateModelTurn } from "./model.js";
@@ -242,45 +244,46 @@ export async function runSequential(options: SequentialRunOptions): Promise<RunR
     transcriptEntryCount: transcript.length
   });
   const finalEvent = events.at(-1);
+  const trace: Trace = {
+    schemaVersion: "1.0",
+    runId,
+    protocol: "sequential",
+    tier: options.tier,
+    modelProviderId: options.model.id,
+    agentsUsed: activeAgents,
+    inputs: createReplayTraceRunInputs({
+      intent: options.intent,
+      protocol: options.protocol,
+      tier: options.tier,
+      modelProviderId: options.model.id,
+      agents: activeAgents,
+      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 ?? events[0] ?? {
+      type: "final",
+      runId,
+      at: "",
+      output,
+      cost: totalCost,
+      transcript: createTranscriptLink(transcript)
+    }),
+    events,
+    transcript
+  };
 
   return {
     output,
     eventLog: createRunEventLog(runId, "sequential", events),
-    trace: {
-      schemaVersion: "1.0",
-      runId,
-      protocol: "sequential",
-      tier: options.tier,
-      modelProviderId: options.model.id,
-      agentsUsed: activeAgents,
-      inputs: createReplayTraceRunInputs({
-        intent: options.intent,
-        protocol: options.protocol,
-        tier: options.tier,
-        modelProviderId: options.model.id,
-        agents: activeAgents,
-        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 ?? events[0] ?? {
-        type: "final",
-        runId,
-        at: "",
-        output,
-        cost: totalCost,
-        transcript: createTranscriptLink(transcript)
-      }),
-      events,
-      transcript
-    },
+    trace,
     transcript,
     usage: createRunUsage(totalCost),
     metadata: createRunMetadata({
@@ -298,7 +301,8 @@ export async function runSequential(options: SequentialRunOptions): Promise<RunR
       cost: totalCost,
       events
     }),
-    cost: totalCost
+    cost: totalCost,
+    health: computeHealth(trace, DEFAULT_HEALTH_THRESHOLDS)
   };
 
   function stopIfNeeded(): boolean {
@@ -377,4 +381,3 @@ function responseCost(response: ModelResponse): CostSummary {
     totalTokens: response.usage?.totalTokens ?? 0
   };
 }
-