@punktechnologies/sdk 0.1.2 → 0.2.0

package/src/index.ts

@@ -14,6 +14,7 @@ import type {
   Pattern,
   PolicyVerdict,
   PromotionGateStatus,
+  RouteExplanation,
   Run,
   SavingsSummary,
   SideEffectLevel,
@@ -52,8 +53,11 @@ export const PUNK_CHORUS_MODEL = "punk/chorus" as const;
 /** @deprecated Use PUNK_CHORUS_MODEL. */
 export const PUNK_MODEL = PUNK_CHORUS_MODEL;
 const DEFAULT_BASE_URL = "http://localhost:4100";
+const DEFAULT_APP = "default-app";
 const MAX_TOOL_CACHE_TTL_SECONDS = 24 * 60 * 60;
 const MAX_TOOL_CACHE_DIMENSION_CHARS = 120;
+const DEFAULT_WAIT_POLL_INTERVAL_MS = 250;
+const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 
 export type PunkLatencyMode =
   | "fast"
@@ -685,6 +689,21 @@ function cleanPathId(label: string, value: string): string {
   return trimmed;
 }
 
+function readEnv(name: string): string | undefined {
+  const env = (globalThis as any)?.process?.env;
+  if (!env || typeof env !== "object") return undefined;
+  const value = env[name];
+  return typeof value === "string" ? value : undefined;
+}
+
+function optionOrEnv<K extends keyof PunkOptions>(
+  opts: PunkOptions,
+  key: K,
+  envName: string,
+): PunkOptions[K] | string | undefined {
+  return Object.prototype.hasOwnProperty.call(opts, key) ? opts[key] : readEnv(envName);
+}
+
 function normalizeBaseUrl(value: string | undefined): string {
   const trimmed = typeof value === "string" ? value.trim() : "";
   return (trimmed || DEFAULT_BASE_URL).replace(/\/+$/, "");
@@ -733,6 +752,170 @@ function chatMessageText(message: any): string {
   return chatMessageContentToString(message?.content);
 }
 
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function normalizeOpenAIUsage(raw: any): PunkUsage | undefined {
+  if (!isRecord(raw?.usage)) return undefined;
+  const usage = raw.usage as Record<string, unknown>;
+  const normalized: PunkUsage = { raw: raw.usage };
+  const inputTokens = finiteNumber(usage.prompt_tokens ?? usage.input_tokens);
+  const outputTokens = finiteNumber(usage.completion_tokens ?? usage.output_tokens);
+  const totalTokens = finiteNumber(usage.total_tokens);
+  if (inputTokens !== undefined) normalized.inputTokens = inputTokens;
+  if (outputTokens !== undefined) normalized.outputTokens = outputTokens;
+  if (totalTokens !== undefined) normalized.totalTokens = totalTokens;
+  if (normalized.totalTokens === undefined && inputTokens !== undefined && outputTokens !== undefined) {
+    normalized.totalTokens = inputTokens + outputTokens;
+  }
+  return normalized;
+}
+
+function normalizeAnthropicUsage(raw: any): PunkUsage | undefined {
+  if (!isRecord(raw?.usage)) return undefined;
+  const usage = raw.usage as Record<string, unknown>;
+  const normalized: PunkUsage = { raw: raw.usage };
+  const inputTokens = finiteNumber(usage.input_tokens);
+  const outputTokens = finiteNumber(usage.output_tokens);
+  if (inputTokens !== undefined) normalized.inputTokens = inputTokens;
+  if (outputTokens !== undefined) normalized.outputTokens = outputTokens;
+  if (inputTokens !== undefined && outputTokens !== undefined) normalized.totalTokens = inputTokens + outputTokens;
+  return normalized;
+}
+
+function normalizeModel(raw: any): string | undefined {
+  return typeof raw?.model === "string" && raw.model.length > 0 ? raw.model : undefined;
+}
+
+function normalizeProvider(raw: any): string | undefined {
+  for (const key of ["provider", "providerName", "provider_name"] as const) {
+    if (typeof raw?.[key] === "string" && raw[key].length > 0) return raw[key];
+  }
+  return undefined;
+}
+
+function anthropicTextFromContent(value: unknown, method: string, path: string): string {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) {
+    throw malformedApiResponse(method, path, "content must be a string or content block array");
+  }
+  return value
+    .map((part: any) => {
+      if (typeof part === "string") return part;
+      if (part?.type === "text" && typeof part.text === "string") return part.text;
+      return "";
+    })
+    .join("");
+}
+
+function anthropicMessageText(raw: unknown, method: string, path: string): string {
+  if (!isRecord(raw)) throw malformedApiResponse(method, path, "missing response object");
+  if (!Object.prototype.hasOwnProperty.call(raw, "content")) {
+    throw malformedApiResponse(method, path, "missing content");
+  }
+  return anthropicTextFromContent(raw.content, method, path);
+}
+
+function anthropicContentBlocks(raw: unknown, method: string, path: string): AnthropicContentBlock[] {
+  if (!isRecord(raw)) throw malformedApiResponse(method, path, "missing response object");
+  const content = raw.content;
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  if (!Array.isArray(content)) throw malformedApiResponse(method, path, "content must be a string or content block array");
+  return content.filter(isRecord) as AnthropicContentBlock[];
+}
+
+interface SseFrame {
+  event?: string;
+  data: string;
+}
+
+function parseSseFrame(frame: string): SseFrame | null {
+  const data: string[] = [];
+  let event: string | undefined;
+  for (const line of frame.split(/\r?\n/)) {
+    if (line.length === 0 || line.startsWith(":")) continue;
+    if (line.startsWith("event:")) {
+      event = line.slice("event:".length).trim();
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      const value = line.slice("data:".length);
+      data.push(value.startsWith(" ") ? value.slice(1) : value);
+    }
+  }
+  if (data.length === 0) return null;
+  return { event, data: data.join("\n") };
+}
+
+async function* sseFrames(
+  res: Response,
+  method: string,
+  path: string,
+): AsyncGenerator<SseFrame> {
+  if (!res.body) {
+    throw new Error(`Punk API ${method} ${path} returned an empty stream`);
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done });
+      let boundary = buffer.search(/\r?\n\r?\n/);
+      while (boundary >= 0) {
+        const frameText = buffer.slice(0, boundary);
+        const match = buffer.slice(boundary).match(/^\r?\n\r?\n/);
+        buffer = buffer.slice(boundary + (match?.[0].length ?? 2));
+        const frame = parseSseFrame(frameText);
+        if (frame) yield frame;
+        boundary = buffer.search(/\r?\n\r?\n/);
+      }
+      if (done) break;
+    }
+    const tail = parseSseFrame(buffer.trim());
+    if (tail) yield tail;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function parseSseJson(frame: SseFrame, method: string, path: string): any {
+  try {
+    return JSON.parse(frame.data);
+  } catch {
+    throw malformedApiResponse(method, path, "stream data was not JSON");
+  }
+}
+
+function streamDeltaText(value: unknown): string {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value.map((part: any) => (typeof part?.text === "string" ? part.text : "")).join("");
+  }
+  return "";
+}
+
+function isTerminalRunStatus(status: Run["status"]): boolean {
+  return status === "completed" || status === "failed" || status === "blocked";
+}
+
+function checkedDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.reject(new Error("Punk wait aborted"));
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(resolve, ms);
+    const onAbort = () => {
+      clearTimeout(timeout);
+      reject(new Error("Punk wait aborted"));
+    };
+    if (signal) {
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+
 const TOOL_LEVEL_4 = new Set([
   "delete", "remove", "drop", "pay", "charge", "refund", "purchase", "subscribe",
   "unsubscribe", "transfer", "withdraw", "deposit", "revoke", "grant", "invite",
@@ -860,6 +1043,143 @@ export interface ChatResult {
   runId: string;
   route: string;
   raw: any;
+  usage?: PunkUsage;
+  model?: string;
+  provider?: string;
+}
+
+export interface PunkUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  raw: unknown;
+}
+
+export interface AnthropicContentBlock {
+  type: string;
+  text?: string;
+  [key: string]: unknown;
+}
+
+export interface AnthropicMessageParams extends PunkChorusOptions {
+  model: string;
+  max_tokens: number;
+  messages: Array<{
+    role: "user" | "assistant" | (string & {});
+    content: string | AnthropicContentBlock[];
+  }>;
+  system?: string | AnthropicContentBlock[];
+  temperature?: number;
+  top_p?: number;
+  top_k?: number;
+  stop_sequences?: string[];
+  tools?: unknown[];
+  tool_choice?: unknown;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AnthropicMessageResult {
+  content: string;
+  contentBlocks: AnthropicContentBlock[];
+  runId: string;
+  route: string;
+  raw: any;
+  usage?: PunkUsage;
+  model?: string;
+  provider?: string;
+  stopReason?: string;
+}
+
+export interface ChatStreamChunk {
+  type: "delta" | "done";
+  content: string;
+  toolCalls: ChatToolCall[];
+  runId: string;
+  route: string;
+  raw?: any;
+  usage?: PunkUsage;
+  model?: string;
+  provider?: string;
+}
+
+export interface AnthropicMessageStreamChunk {
+  type: "delta" | "done";
+  content: string;
+  runId: string;
+  route: string;
+  event?: string;
+  raw?: any;
+  usage?: PunkUsage;
+  model?: string;
+  provider?: string;
+}
+
+export interface PunkIdentityHeadersOptions {
+  /** Include Authorization when this client has an API key. Default: true. */
+  includeAuthorization?: boolean;
+  /** Include Content-Type: application/json. Default: false. */
+  includeContentType?: boolean;
+  /** Override the X-Punk-App value for this config object. */
+  app?: string;
+  /** Override the X-Punk-Agent value for this config object. */
+  agent?: string;
+  /** Override the X-Punk-Subject value for this config object. */
+  subject?: string;
+  /** Extra headers to merge last. Blank values are ignored. */
+  headers?: Record<string, string | undefined>;
+}
+
+export interface PunkClientConfigOptions extends PunkIdentityHeadersOptions {
+  baseUrl?: string;
+  apiKey?: string;
+  name?: string;
+  includeUsage?: boolean;
+}
+
+export interface PunkOpenAIConfig {
+  baseURL: string;
+  apiKey: string;
+  defaultHeaders: Record<string, string>;
+}
+
+export interface PunkAnthropicConfig {
+  baseURL: string;
+  authToken: string;
+  defaultHeaders: Record<string, string>;
+}
+
+export interface PunkVercelOpenAICompatibleConfig {
+  name: string;
+  baseURL: string;
+  apiKey: string;
+  headers: Record<string, string>;
+  includeUsage: boolean;
+}
+
+export interface PunkLangChainConfig {
+  apiKey: string;
+  configuration: {
+    baseURL: string;
+    defaultHeaders: Record<string, string>;
+  };
+}
+
+export interface RunSavings {
+  runId: string;
+  route?: string;
+  status: Run["status"];
+  costUsd: number;
+  savedUsd: number;
+  ghostSavedUsd: number;
+  latencyMs: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface RunWaitOptions {
+  pollIntervalMs?: number;
+  timeoutMs?: number;
+  signal?: AbortSignal;
 }
 
 export interface PunkReceipt {
@@ -980,13 +1300,120 @@ export class Punk {
   readonly agent?: string;
   readonly subject?: string;
   private readonly apiKey?: string;
+  private readonly runStack: string[] = [];
 
   constructor(opts: PunkOptions = {}) {
-    this.baseUrl = normalizeBaseUrl(opts.baseUrl);
-    this.apiKey = cleanIdentityValue(opts.apiKey);
-    this.app = cleanIdentityValue(opts.app) ?? "default-app";
-    this.agent = cleanIdentityValue(opts.agent);
-    this.subject = cleanIdentityValue(opts.subject);
+    this.baseUrl = normalizeBaseUrl(optionOrEnv(opts, "baseUrl", "PUNK_BASE_URL"));
+    this.apiKey = cleanIdentityValue(optionOrEnv(opts, "apiKey", "PUNK_API_KEY"));
+    this.app = cleanIdentityValue(optionOrEnv(opts, "app", "PUNK_APP")) ?? DEFAULT_APP;
+    this.agent = cleanIdentityValue(optionOrEnv(opts, "agent", "PUNK_AGENT"));
+    this.subject = cleanIdentityValue(optionOrEnv(opts, "subject", "PUNK_SUBJECT"));
+  }
+
+  readonly gateway = {
+    chat: (params: ChatParams): Promise<ChatResult> => this.chat(params),
+    streamChat: (params: ChatParams): AsyncIterable<ChatStreamChunk> => this.streamChat(params),
+    stream: (params: ChatParams): AsyncIterable<ChatStreamChunk> => this.chatStream(params),
+  };
+
+  readonly openai = {
+    chat: (params: ChatParams): Promise<ChatResult> => this.chat(params),
+    streamChat: (params: ChatParams): AsyncIterable<ChatStreamChunk> => this.streamChat(params),
+    stream: (params: ChatParams): AsyncIterable<ChatStreamChunk> => this.chatStream(params),
+    config: (opts?: PunkClientConfigOptions): PunkOpenAIConfig => this.openAIConfig(opts),
+  };
+
+  readonly anthropic = {
+    messages: (params: AnthropicMessageParams): Promise<AnthropicMessageResult> =>
+      this.messages(params),
+    streamMessages: (params: AnthropicMessageParams): AsyncIterable<AnthropicMessageStreamChunk> =>
+      this.streamMessages(params),
+    stream: (params: AnthropicMessageParams): AsyncIterable<AnthropicMessageStreamChunk> =>
+      this.messagesStream(params),
+    config: (opts?: PunkClientConfigOptions): PunkAnthropicConfig => this.anthropicConfig(opts),
+  };
+
+  identityHeaders(opts: PunkIdentityHeadersOptions = {}): Record<string, string> {
+    const includeAuthorization = opts.includeAuthorization !== false;
+    const headers: Record<string, string> = {};
+    if (opts.includeContentType === true) headers["Content-Type"] = "application/json";
+    if (includeAuthorization && this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    const app = cleanIdentityValue(opts.app) ?? this.app;
+    const agent = cleanIdentityValue(opts.agent) ?? this.agent;
+    const subject = cleanIdentityValue(opts.subject) ?? this.subject;
+    headers["X-Punk-App"] = app;
+    if (agent) headers["X-Punk-Agent"] = agent;
+    if (subject) headers["X-Punk-Subject"] = subject;
+    if (opts.headers) {
+      for (const [key, value] of Object.entries(opts.headers)) {
+        if (typeof value === "string" && value.trim().length > 0) headers[key] = value;
+      }
+    }
+    return headers;
+  }
+
+  openAIConfig(opts: PunkClientConfigOptions = {}): PunkOpenAIConfig {
+    const baseUrl = normalizeBaseUrl(opts.baseUrl ?? this.baseUrl);
+    const apiKey = cleanIdentityValue(opts.apiKey) ?? this.apiKey ?? "punk-local";
+    return {
+      baseURL: `${baseUrl}/v1`,
+      apiKey,
+      defaultHeaders: this.identityHeaders({ ...opts, includeAuthorization: false }),
+    };
+  }
+
+  anthropicConfig(opts: PunkClientConfigOptions = {}): PunkAnthropicConfig {
+    const baseUrl = normalizeBaseUrl(opts.baseUrl ?? this.baseUrl);
+    const authToken = cleanIdentityValue(opts.apiKey) ?? this.apiKey ?? "punk-local";
+    return {
+      baseURL: baseUrl,
+      authToken,
+      defaultHeaders: this.identityHeaders({ ...opts, includeAuthorization: true }),
+    };
+  }
+
+  vercelAIConfig(opts: PunkClientConfigOptions = {}): PunkVercelOpenAICompatibleConfig {
+    return this.vercelOpenAICompatibleConfig(opts);
+  }
+
+  vercelOpenAICompatibleConfig(opts: PunkClientConfigOptions = {}): PunkVercelOpenAICompatibleConfig {
+    const baseUrl = normalizeBaseUrl(opts.baseUrl ?? this.baseUrl);
+    return {
+      name: cleanIdentityValue(opts.name) ?? "punk",
+      baseURL: `${baseUrl}/v1`,
+      apiKey: cleanIdentityValue(opts.apiKey) ?? this.apiKey ?? "punk-local",
+      headers: this.identityHeaders({ ...opts, includeAuthorization: false }),
+      includeUsage: opts.includeUsage ?? true,
+    };
+  }
+
+  langChainConfig(opts: PunkClientConfigOptions = {}): PunkLangChainConfig {
+    const baseUrl = normalizeBaseUrl(opts.baseUrl ?? this.baseUrl);
+    return {
+      apiKey: cleanIdentityValue(opts.apiKey) ?? this.apiKey ?? "punk-local",
+      configuration: {
+        baseURL: `${baseUrl}/v1`,
+        defaultHeaders: this.identityHeaders({ ...opts, includeAuthorization: false }),
+      },
+    };
+  }
+
+  currentRunId(): string | undefined {
+    return this.runStack.at(-1);
+  }
+
+  async withRun<T>(
+    run: string | { runId?: string | null | undefined },
+    fn: () => T | Promise<T>,
+  ): Promise<Awaited<T>> {
+    const rawRunId = typeof run === "string" ? run : run.runId;
+    const id = cleanPathId("run id", rawRunId ?? "");
+    this.runStack.push(id);
+    try {
+      return await fn();
+    } finally {
+      this.runStack.pop();
+    }
   }
 
   // -- chat -----------------------------------------------------------------
@@ -1018,16 +1445,170 @@ export class Punk {
       runId: res.headers.get("x-punk-run-id") ?? "",
       route: res.headers.get("x-punk-route") ?? "unknown",
       raw,
+      usage: normalizeOpenAIUsage(raw),
+      model: normalizeModel(raw),
+      provider: normalizeProvider(raw),
     };
   }
 
+  /** Stream an OpenAI-compatible chat completion through the gateway. */
+  streamChat(params: ChatParams): AsyncIterable<ChatStreamChunk> {
+    return this.chatStream(params);
+  }
+
+  /** Stream an OpenAI-compatible chat completion through the gateway. */
+  async *chatStream(params: ChatParams): AsyncIterable<ChatStreamChunk> {
+    const method = "POST";
+    const path = "/v1/chat/completions";
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers({
+          "X-Punk-App": this.app,
+          "X-Punk-Agent": this.agent,
+          "X-Punk-Subject": this.subject,
+        }),
+        body: JSON.stringify({ ...params, stream: true }),
+      });
+    } catch (err) {
+      throw this.toTransportError(method, path, err);
+    }
+    if (!res.ok) throw this.toError(method, path, res, await res.text());
+    const runId = res.headers.get("x-punk-run-id") ?? "";
+    const route = res.headers.get("x-punk-route") ?? "unknown";
+    for await (const frame of sseFrames(res, method, path)) {
+      if (frame.data === "[DONE]") {
+        yield { type: "done", content: "", toolCalls: [], runId, route };
+        return;
+      }
+      const raw = parseSseJson(frame, method, path);
+      const choice = Array.isArray(raw?.choices) ? raw.choices[0] : undefined;
+      const delta = isRecord(choice?.delta) ? choice.delta as Record<string, unknown> : {};
+      yield {
+        type: "delta",
+        content: streamDeltaText(delta.content),
+        toolCalls: normalizeChatToolCalls(delta.tool_calls),
+        runId,
+        route,
+        raw,
+        usage: normalizeOpenAIUsage(raw),
+        model: normalizeModel(raw),
+        provider: normalizeProvider(raw),
+      };
+    }
+    yield { type: "done", content: "", toolCalls: [], runId, route };
+  }
+
+  /** Send an Anthropic-compatible Messages request through the gateway. */
+  async messages(params: AnthropicMessageParams): Promise<AnthropicMessageResult> {
+    const method = "POST";
+    const path = "/v1/messages";
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers({
+          "anthropic-version": "2023-06-01",
+          "X-Punk-App": this.app,
+          "X-Punk-Agent": this.agent,
+          "X-Punk-Subject": this.subject,
+        }),
+        body: JSON.stringify({ ...params, stream: false }),
+      });
+    } catch (err) {
+      throw this.toTransportError(method, path, err);
+    }
+    const raw = await this.parseJsonResponse<any>(method, path, res);
+    return {
+      content: anthropicMessageText(raw, method, path),
+      contentBlocks: anthropicContentBlocks(raw, method, path),
+      runId: res.headers.get("x-punk-run-id") ?? "",
+      route: res.headers.get("x-punk-route") ?? "unknown",
+      raw,
+      usage: normalizeAnthropicUsage(raw),
+      model: normalizeModel(raw),
+      provider: normalizeProvider(raw),
+      stopReason: typeof raw?.stop_reason === "string" ? raw.stop_reason : undefined,
+    };
+  }
+
+  /** Stream an Anthropic-compatible Messages request through the gateway. */
+  streamMessages(params: AnthropicMessageParams): AsyncIterable<AnthropicMessageStreamChunk> {
+    return this.messagesStream(params);
+  }
+
+  /** Stream an Anthropic-compatible Messages request through the gateway. */
+  async *messagesStream(params: AnthropicMessageParams): AsyncIterable<AnthropicMessageStreamChunk> {
+    const method = "POST";
+    const path = "/v1/messages";
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers({
+          "anthropic-version": "2023-06-01",
+          "X-Punk-App": this.app,
+          "X-Punk-Agent": this.agent,
+          "X-Punk-Subject": this.subject,
+        }),
+        body: JSON.stringify({ ...params, stream: true }),
+      });
+    } catch (err) {
+      throw this.toTransportError(method, path, err);
+    }
+    if (!res.ok) throw this.toError(method, path, res, await res.text());
+    const runId = res.headers.get("x-punk-run-id") ?? "";
+    const route = res.headers.get("x-punk-route") ?? "unknown";
+    let model: string | undefined;
+    let usage: PunkUsage | undefined;
+    for await (const frame of sseFrames(res, method, path)) {
+      const raw = parseSseJson(frame, method, path);
+      if (typeof raw?.message?.model === "string") model = raw.message.model;
+      const messageUsage = normalizeAnthropicUsage(raw.message);
+      if (messageUsage) usage = messageUsage;
+      if (isRecord(raw?.usage)) {
+        usage = normalizeAnthropicUsage({ usage: { ...(usage?.raw as Record<string, unknown> | undefined), ...raw.usage } });
+      }
+      if (raw?.type === "content_block_delta") {
+        yield {
+          type: "delta",
+          content: typeof raw?.delta?.text === "string" ? raw.delta.text : "",
+          runId,
+          route,
+          event: frame.event,
+          raw,
+          usage,
+          model,
+          provider: normalizeProvider(raw),
+        };
+      }
+      if (raw?.type === "message_stop") {
+        yield {
+          type: "done",
+          content: "",
+          runId,
+          route,
+          event: frame.event,
+          raw,
+          usage,
+          model,
+          provider: normalizeProvider(raw),
+        };
+        return;
+      }
+    }
+    yield { type: "done", content: "", runId, route, usage, model };
+  }
+
   // -- tool tracing ---------------------------------------------------------
 
   /**
    * Wrap a tool so every invocation is traced into the run it belongs to, and
    * explicitly declared read-only results (level <= 1 with a TTL) flow
-   * through the tool-result cache. Tracing requires `ctx.runId`; without it
-   * the tool still executes, silently untraced and uncached.
+   * through the tool-result cache. Tracing uses `ctx.runId` first, then an
+   * active `withRun` id; without either the tool still executes, silently
+   * untraced and uncached.
    */
   traceTool<TArgs, TResult>(
     def: ToolDefinition<TArgs, TResult>,
@@ -1038,7 +1619,7 @@ export class Punk {
     const schemaFp = cleanOptionalCacheDimension("schemaFp", def.schemaFp);
 
     return async (args: TArgs, ctx?: { runId?: string }): Promise<TResult> => {
-      const runId = cleanIdentityValue(ctx?.runId);
+      const runId = cleanIdentityValue(ctx?.runId) ?? this.currentRunId();
       const cacheable = level <= 1 && ttlSeconds !== undefined && runId !== undefined && this.subject !== undefined;
 
       if (runId) {
@@ -1326,6 +1907,53 @@ export class Punk {
     return requireRunDetailResult(await this.request<unknown>("GET", path), "GET", path);
   }
 
+  async explain(runId: string): Promise<RouteExplanation | null> {
+    return this.runDetail(runId).then((detail) => detail.run.routeExplanation ?? null);
+  }
+
+  async savingsForRun(runId: string): Promise<RunSavings> {
+    const detail = await this.runDetail(runId);
+    return {
+      runId: detail.run.id,
+      route: detail.run.route,
+      status: detail.run.status,
+      costUsd: detail.run.costUsd,
+      savedUsd: detail.run.savedUsd,
+      ghostSavedUsd: detail.run.ghostSavedUsd ?? 0,
+      latencyMs: detail.run.latencyMs,
+      inputTokens: detail.run.inputTokens,
+      outputTokens: detail.run.outputTokens,
+    };
+  }
+
+  async sideEffectsForRun(runId: string): Promise<SideEffectRecord[]> {
+    return this.runDetail(runId).then((detail) => detail.sideEffects);
+  }
+
+  async waitForRun(runId: string, opts: RunWaitOptions = {}): Promise<RunDetail> {
+    for await (const detail of this.watchRun(runId, opts)) {
+      if (isTerminalRunStatus(detail.run.status)) return detail;
+    }
+    throw new Error(`Punk waitForRun(${cleanPathId("run id", runId)}) ended before the run reached a terminal status`);
+  }
+
+  async *watchRun(runId: string, opts: RunWaitOptions = {}): AsyncIterable<RunDetail> {
+    const id = cleanPathId("run id", runId);
+    const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_WAIT_POLL_INTERVAL_MS;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const startedAt = Date.now();
+    while (true) {
+      if (opts.signal?.aborted) throw new Error("Punk watchRun aborted");
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`Punk watchRun(${id}) timed out after ${timeoutMs}ms`);
+      }
+      const detail = await this.runDetail(id);
+      yield detail;
+      if (isTerminalRunStatus(detail.run.status)) return;
+      await checkedDelay(pollIntervalMs, opts.signal);
+    }
+  }
+
   async receipt(id: string): Promise<PunkReceipt> {
     const path = `/api/v1/receipts/${encodeURIComponent(cleanPathId("receipt id", id))}`;
     return requireReceiptResult(await this.request<unknown>("GET", path), "GET", path);