@punktechnologies/sdk 0.1.0 → 0.1.1

package/src/index.ts

@@ -0,0 +1,1559 @@
+/**
+ * @punktechnologies/sdk — developer-facing client for the Punk gateway.
+ *
+ * Point your agent's gateway traffic at Punk, wrap your tools with
+ * `traceTool`, and the runtime observes, caches, learns and (after replay +
+ * shadow proof) routes repeated work through deterministic artifacts.
+ */
+
+import type {
+  Artifact,
+  ArtifactEvaluation,
+  McpServerRecord,
+  McpTestResult,
+  Pattern,
+  PolicyVerdict,
+  PromotionGateStatus,
+  Run,
+  SavingsSummary,
+  SideEffectLevel,
+  SideEffectRecord,
+  SomDiff,
+  SomSnapshot,
+  TraceEvent,
+  TraceEventType,
+  TrustLane,
+  WebActionIntent,
+  WebActionResult,
+} from "./types";
+
+// Local mirrors of the @punk/trace-schema contracts (keeps the published SDK
+// dependency-free). Re-exported so consumers can type their own code.
+export type * from "./types";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface PunkOptions {
+  /** Gateway base URL. Default: http://localhost:4100 */
+  baseUrl?: string;
+  /** Bearer token (only needed when the gateway sets PUNK_API_KEY). */
+  apiKey?: string;
+  /** Logical application name, sent as X-Punk-App. Default: "default-app". */
+  app?: string;
+  /** Agent identity, sent as X-Punk-Agent. */
+  agent?: string;
+  /** Pseudonymous end-user identifier, sent as X-Punk-Subject. */
+  subject?: string;
+}
+
+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 MAX_TOOL_CACHE_TTL_SECONDS = 24 * 60 * 60;
+const MAX_TOOL_CACHE_DIMENSION_CHARS = 120;
+
+export type PunkLatencyMode =
+  | "fast"
+  | "balanced"
+  | "deep"
+  | "maximum_quality"
+  | (string & {});
+export type PunkQualityMode =
+  | "economy"
+  | "balanced"
+  | "frontier_optional"
+  | "maximum_quality"
+  | (string & {});
+export type PunkReceiptMode =
+  | "off"
+  | "none"
+  | "summary"
+  | "full"
+  | (string & {});
+export type PunkCircuitMode =
+  | "off"
+  | "reuse"
+  | "learn"
+  | (string & {});
+export type PunkAuditLevel =
+  | "minimal"
+  | "standard"
+  | "full"
+  | (string & {});
+export type PunkResearchMode =
+  | "off"
+  | "som"
+  | "plasmate"
+  | "deep"
+  | (string & {});
+export type PunkModelClass =
+  | "commercial"
+  | "frontier"
+  | "open_weight"
+  | "local"
+  | (string & {});
+
+export interface PunkChorusMetadata {
+  requestId?: string;
+  workflowId?: string;
+  tenantHint?: string;
+  labels?: string[];
+  [key: string]: unknown;
+}
+
+export interface PunkChorusOptions {
+  budget_limit_usd?: number;
+  latency_mode?: PunkLatencyMode;
+  quality_mode?: PunkQualityMode;
+  policy_profile?: string;
+  receipt_mode?: PunkReceiptMode;
+  circuit_mode?: PunkCircuitMode;
+  shadow_mode?: boolean;
+  audit_level?: PunkAuditLevel;
+  /** Enable the governed SOTA mix preset for maximum-quality Chorus runs. */
+  sota_mix?: boolean;
+  research_mode?: PunkResearchMode;
+  research_max_queries?: number;
+  research_max_sources?: number;
+  research_context_chars?: number;
+  live_panel_models?: string[] | string;
+  live_synthesis_model?: string;
+  live_synthesis_required?: boolean;
+  live_synthesis_max_tokens?: number;
+  /** Compatibility alias for live_synthesis_model. */
+  answer_model?: string;
+  /** Compatibility alias for live_synthesis_max_tokens. */
+  answer_max_tokens?: number;
+  local_only?: boolean;
+  allowed_model_classes?: PunkModelClass[];
+  blocked_providers?: string[];
+  /** Punk Chorus metadata forwarded in the OpenAI-compatible request body. */
+  chorus?: PunkChorusMetadata;
+}
+
+export interface ChatParams extends PunkChorusOptions {
+  model: string;
+  messages: Array<{ role: string; content: string }>;
+  temperature?: number;
+  max_tokens?: number;
+  max_completion_tokens?: number;
+  top_p?: number;
+  response_format?: unknown;
+  tools?: ChatTool[];
+  tool_choice?: unknown;
+}
+
+export interface ChatTool {
+  type?: "function";
+  function?: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    sideEffectLevel?: SideEffectLevel;
+    ttlSeconds?: number;
+  };
+  name?: string;
+  description?: string;
+  parameters?: Record<string, unknown>;
+  sideEffectLevel?: SideEffectLevel;
+  ttlSeconds?: number;
+}
+
+export interface ChatToolCall {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+function stringifyToolArguments(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value ?? {}) ?? "{}";
+  } catch {
+    return "{}";
+  }
+}
+
+function normalizeChatToolCalls(value: unknown): ChatToolCall[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((tc: any, index: number): ChatToolCall | null => {
+      const name = tc?.function?.name;
+      if (typeof name !== "string" || name.length === 0) return null;
+      return {
+        id: typeof tc?.id === "string" && tc.id.length > 0 ? tc.id : `call_${index}`,
+        type: "function",
+        function: {
+          name,
+          arguments: stringifyToolArguments(tc.function.arguments),
+        },
+      };
+    })
+    .filter((tc): tc is ChatToolCall => tc !== null);
+}
+
+function malformedChatResponse(method: string, path: string, reason: string): Error {
+  return new Error(`Punk API ${method} ${path} returned malformed chat response: ${reason}`);
+}
+
+function malformedApiResponse(method: string, path: string, reason: string): Error {
+  return new Error(`Punk API ${method} ${path} returned malformed response: ${reason}`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function requireArrayProperty<T>(
+  value: unknown,
+  key: string,
+  method: string,
+  path: string,
+): T[] {
+  if (!isRecord(value) || !Array.isArray(value[key])) {
+    throw malformedApiResponse(method, path, `missing ${key} array`);
+  }
+  return value[key] as T[];
+}
+
+function requireObjectProperty<T>(
+  value: unknown,
+  key: string,
+  method: string,
+  path: string,
+): T {
+  if (!isRecord(value) || !isRecord(value[key])) {
+    throw malformedApiResponse(method, path, `missing ${key} object`);
+  }
+  return value[key] as T;
+}
+
+function requireWebFetchResult(value: unknown, method: string, path: string): WebFetchResult {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "missing response object");
+  if (!isRecord(value.som)) throw malformedApiResponse(method, path, "missing som object");
+  if (typeof value.source !== "string" || value.source.length === 0) {
+    throw malformedApiResponse(method, path, "missing source string");
+  }
+  if (typeof value.url !== "string" || value.url.length === 0) {
+    throw malformedApiResponse(method, path, "missing url string");
+  }
+  if (typeof value.requestedUrl !== "string" || value.requestedUrl.length === 0) {
+    throw malformedApiResponse(method, path, "missing requestedUrl string");
+  }
+  if (typeof value.cached !== "boolean") {
+    throw malformedApiResponse(method, path, "missing cached boolean");
+  }
+  if (typeof value.context !== "string") {
+    throw malformedApiResponse(method, path, "missing context string");
+  }
+  for (const key of ["htmlBytes", "somBytes", "tokensSavedEstimate"] as const) {
+    if (typeof value[key] !== "number" || !Number.isFinite(value[key])) {
+      throw malformedApiResponse(method, path, `missing finite ${key}`);
+    }
+  }
+  return value as unknown as WebFetchResult;
+}
+
+function requireWebSessionOpenResult(value: unknown, method: string, path: string): WebSessionOpenResult {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "missing response object");
+  if (typeof value.sessionId !== "string" || value.sessionId.length === 0) {
+    throw malformedApiResponse(method, path, "missing sessionId string");
+  }
+  if (!isRecord(value.som)) throw malformedApiResponse(method, path, "missing som object");
+  if (typeof value.source !== "string" || value.source.length === 0) {
+    throw malformedApiResponse(method, path, "missing source string");
+  }
+  if (typeof value.context !== "string") {
+    throw malformedApiResponse(method, path, "missing context string");
+  }
+  const session = requireWebSessionSummary(value.session, method, path, "session");
+  if (session.id !== value.sessionId) {
+    throw malformedApiResponse(method, path, "session.id does not match sessionId");
+  }
+  return value as unknown as WebSessionOpenResult;
+}
+
+function requireWebActResult(
+  value: unknown,
+  method: string,
+  path: string,
+  expectedSessionId?: string,
+): WebActResult {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "missing response object");
+  if (!isRecord(value.result)) throw malformedApiResponse(method, path, "missing result object");
+  requireWebActionResult(value.result, method, path);
+  if (!isRecord(value.som)) throw malformedApiResponse(method, path, "missing som object");
+  if (value.diff !== undefined && !isRecord(value.diff)) {
+    throw malformedApiResponse(method, path, "diff must be an object when present");
+  }
+  const session = requireWebSessionSummary(value.session, method, path, "session");
+  if (typeof value.context !== "string") {
+    throw malformedApiResponse(method, path, "missing context string");
+  }
+  if (expectedSessionId !== undefined && session.id !== expectedSessionId) {
+    throw malformedApiResponse(method, path, "session.id does not match requested session");
+  }
+  return value as unknown as WebActResult;
+}
+
+function requireWebActionResult(value: Record<string, unknown>, method: string, path: string): void {
+  if (typeof value.ok !== "boolean") {
+    throw malformedApiResponse(method, path, "result.ok must be boolean");
+  }
+  if (typeof value.action !== "string" || !["click", "type", "select", "submit"].includes(value.action)) {
+    throw malformedApiResponse(method, path, "result.action must be click|type|select|submit");
+  }
+  if (typeof value.target !== "string" || value.target.length === 0) {
+    throw malformedApiResponse(method, path, "result.target must be a non-empty string");
+  }
+  if (typeof value.url !== "string" || value.url.length === 0) {
+    throw malformedApiResponse(method, path, "result.url must be a non-empty string");
+  }
+  if (value.resolved !== undefined && typeof value.resolved !== "string") {
+    throw malformedApiResponse(method, path, "result.resolved must be a string when present");
+  }
+  if (value.navigated !== undefined && typeof value.navigated !== "boolean") {
+    throw malformedApiResponse(method, path, "result.navigated must be boolean when present");
+  }
+  if (value.requestedUrl !== undefined && typeof value.requestedUrl !== "string") {
+    throw malformedApiResponse(method, path, "result.requestedUrl must be a string when present");
+  }
+  if (value.error !== undefined && typeof value.error !== "string") {
+    throw malformedApiResponse(method, path, "result.error must be a string when present");
+  }
+  if (value.posted !== undefined) {
+    if (!isRecord(value.posted)) {
+      throw malformedApiResponse(method, path, "result.posted must be an object when present");
+    }
+    for (const [key, postedValue] of Object.entries(value.posted)) {
+      if (typeof postedValue !== "string") {
+        throw malformedApiResponse(method, path, `result.posted.${key} must be a string`);
+      }
+    }
+  }
+}
+
+function requireWebSessionSummary(
+  value: unknown,
+  method: string,
+  path: string,
+  label: string,
+): WebSessionSummary {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, `missing ${label} object`);
+  if (typeof value.id !== "string" || value.id.length === 0) {
+    throw malformedApiResponse(method, path, `${label}.id must be a non-empty string`);
+  }
+  if (typeof value.url !== "string" || value.url.length === 0) {
+    throw malformedApiResponse(method, path, `${label}.url must be a non-empty string`);
+  }
+  if (typeof value.source !== "string" || value.source.length === 0) {
+    throw malformedApiResponse(method, path, `${label}.source must be a non-empty string`);
+  }
+  if (typeof value.openedAt !== "number" || !Number.isFinite(value.openedAt)) {
+    throw malformedApiResponse(method, path, `${label}.openedAt must be finite`);
+  }
+  if (typeof value.ageMs !== "number" || !Number.isFinite(value.ageMs) || value.ageMs < 0) {
+    throw malformedApiResponse(method, path, `${label}.ageMs must be a non-negative finite number`);
+  }
+  return value as unknown as WebSessionSummary;
+}
+
+function requireWebSessionsListResult(
+  value: unknown,
+  method: string,
+  path: string,
+): { sessions: WebSessionSummary[] } {
+  const sessions = requireArrayProperty<Record<string, unknown>>(value, "sessions", method, path);
+  for (let i = 0; i < sessions.length; i++) {
+    requireWebSessionSummary(sessions[i]!, method, path, `sessions[${i}]`);
+  }
+  return value as { sessions: WebSessionSummary[] };
+}
+
+function requireOkResult(value: unknown, method: string, path: string): { ok: true } {
+  if (!isRecord(value) || value.ok !== true) {
+    throw malformedApiResponse(method, path, "missing ok true");
+  }
+  return { ok: true };
+}
+
+function requireNonNegativeIntegerProperty(
+  value: Record<string, unknown>,
+  key: string,
+  method: string,
+  path: string,
+  label = key,
+): number {
+  const raw = value[key];
+  if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw < 0) {
+    throw malformedApiResponse(method, path, `${label} must be a non-negative integer`);
+  }
+  return raw;
+}
+
+function requireNonEmptyStringProperty(
+  value: Record<string, unknown>,
+  key: string,
+  method: string,
+  path: string,
+  label = key,
+): string {
+  const raw = value[key];
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    throw malformedApiResponse(method, path, `${label} must be a non-empty string`);
+  }
+  return raw;
+}
+
+function requireFiniteNonNegativeNumberProperty(
+  value: Record<string, unknown>,
+  key: string,
+  method: string,
+  path: string,
+  label = key,
+): number {
+  const raw = value[key];
+  if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) {
+    throw malformedApiResponse(method, path, `${label} must be a non-negative finite number`);
+  }
+  return raw;
+}
+
+function requireOptionalFiniteNonNegativeNumberProperty(
+  value: Record<string, unknown>,
+  key: string,
+  method: string,
+  path: string,
+  label = key,
+): void {
+  if (value[key] === undefined) return;
+  requireFiniteNonNegativeNumberProperty(value, key, method, path, label);
+}
+
+function requireUnitRateProperty(
+  value: Record<string, unknown>,
+  key: string,
+  method: string,
+  path: string,
+  label = key,
+): number {
+  const raw = requireFiniteNonNegativeNumberProperty(value, key, method, path, label);
+  if (raw > 1) {
+    throw malformedApiResponse(method, path, `${label} must be between 0 and 1`);
+  }
+  return raw;
+}
+
+function requireSavingsSummary(value: unknown, method: string, path: string): SavingsSummary {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "missing response object");
+  requireNonEmptyStringProperty(value, "tenantId", method, path);
+  for (const key of ["totalRuns", "liveRuns", "optimizedRuns", "blockedRuns", "cacheHits", "artifactHits", "somTokensSaved"] as const) {
+    requireNonNegativeIntegerProperty(value, key, method, path);
+  }
+  for (const key of ["totalCostUsd", "totalSavedUsd", "ghostSavedUsd", "totalSavedMs"] as const) {
+    requireFiniteNonNegativeNumberProperty(value, key, method, path);
+  }
+  requireUnitRateProperty(value, "cacheHitRate", method, path);
+  requireUnitRateProperty(value, "artifactHitRate", method, path);
+  const totalRuns = value.totalRuns as number;
+  const accountedRuns = (value.liveRuns as number) + (value.optimizedRuns as number) + (value.blockedRuns as number);
+  if (accountedRuns !== totalRuns) {
+    throw malformedApiResponse(method, path, "run counters must add up to totalRuns");
+  }
+  if ((value.cacheHits as number) > (value.optimizedRuns as number)) {
+    throw malformedApiResponse(method, path, "cacheHits cannot exceed optimizedRuns");
+  }
+  if ((value.artifactHits as number) > (value.optimizedRuns as number)) {
+    throw malformedApiResponse(method, path, "artifactHits cannot exceed optimizedRuns");
+  }
+  return value as unknown as SavingsSummary;
+}
+
+const RUN_STATUSES = new Set(["running", "completed", "failed", "blocked"]);
+const ARTIFACT_STATES = new Set(["candidate", "replay_failed", "replay_passed", "shadowing", "shadow_failed", "approved", "promoted", "canary", "stable", "degraded", "quarantined", "retired"]);
+const ARTIFACT_TYPES = new Set(["static_response", "template", "deterministic_transform", "ruleset_classifier", "tool_plan", "web_extraction", "hybrid"]);
+
+function requireRunRecord(value: unknown, method: string, path: string, label = "run"): Run {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, `missing ${label} object`);
+  for (const key of ["id", "tenantId", "appId", "requestHash"] as const) {
+    requireNonEmptyStringProperty(value, key, method, path, `${label}.${key}`);
+  }
+  const status = requireNonEmptyStringProperty(value, "status", method, path, `${label}.status`);
+  if (!RUN_STATUSES.has(status)) {
+    throw malformedApiResponse(method, path, `${label}.status must be running|completed|failed|blocked`);
+  }
+  for (const key of ["inputTokens", "outputTokens"] as const) {
+    requireNonNegativeIntegerProperty(value, key, method, path, `${label}.${key}`);
+  }
+  for (const key of ["costUsd", "savedUsd", "latencyMs", "startedAt"] as const) {
+    requireFiniteNonNegativeNumberProperty(value, key, method, path, `${label}.${key}`);
+  }
+  requireOptionalFiniteNonNegativeNumberProperty(value, "ghostSavedUsd", method, path, `${label}.ghostSavedUsd`);
+  requireOptionalFiniteNonNegativeNumberProperty(value, "completedAt", method, path, `${label}.completedAt`);
+  if (value.route !== undefined && (typeof value.route !== "string" || value.route.trim().length === 0)) {
+    throw malformedApiResponse(method, path, `${label}.route must be a non-empty string when present`);
+  }
+  return value as unknown as Run;
+}
+
+function requireTraceEventRecord(value: unknown, method: string, path: string, label: string): TraceEvent {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, `${label} must be an object`);
+  for (const key of ["id", "runId", "tenantId", "type"] as const) {
+    requireNonEmptyStringProperty(value, key, method, path, `${label}.${key}`);
+  }
+  requireFiniteNonNegativeNumberProperty(value, "ts", method, path, `${label}.ts`);
+  if (!isRecord(value.payload)) {
+    throw malformedApiResponse(method, path, `${label}.payload must be an object`);
+  }
+  return value as unknown as TraceEvent;
+}
+
+function requireSideEffectRecord(value: unknown, method: string, path: string, label: string): SideEffectRecord {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, `${label} must be an object`);
+  for (const key of ["id", "runId", "tenantId", "toolName", "status"] as const) {
+    requireNonEmptyStringProperty(value, key, method, path, `${label}.${key}`);
+  }
+  const level = requireNonNegativeIntegerProperty(value, "level", method, path, `${label}.level`);
+  if (level > 4) throw malformedApiResponse(method, path, `${label}.level must be between 0 and 4`);
+  requireFiniteNonNegativeNumberProperty(value, "createdAt", method, path, `${label}.createdAt`);
+  return value as unknown as SideEffectRecord;
+}
+
+function requireRunDetailResult(value: unknown, method: string, path: string): RunDetail {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "missing response object");
+  requireRunRecord(value.run, method, path);
+  const events = requireArrayProperty<unknown>(value, "events", method, path);
+  events.forEach((event, index) => requireTraceEventRecord(event, method, path, `events[${index}]`));
+  const sideEffects = requireArrayProperty<unknown>(value, "sideEffects", method, path);
+  sideEffects.forEach((sideEffect, index) => requireSideEffectRecord(sideEffect, method, path, `sideEffects[${index}]`));
+  return value as unknown as RunDetail;
+}
+
+function requireArtifactRecord(value: unknown, method: string, path: string, label = "artifact"): Artifact {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, `missing ${label} object`);
+  for (const key of ["id", "tenantId", "patternId", "state", "type"] as const) {
+    requireNonEmptyStringProperty(value, key, method, path, `${label}.${key}`);
+  }
+  if (!ARTIFACT_STATES.has(String(value.state))) {
+    throw malformedApiResponse(method, path, `${label}.state is not a known artifact state`);
+  }
+  if (!ARTIFACT_TYPES.has(String(value.type))) {
+    throw malformedApiResponse(method, path, `${label}.type is not a known artifact type`);
+  }
+  if (!isRecord(value.representation)) throw malformedApiResponse(method, path, `${label}.representation must be an object`);
+  if (!isRecord(value.provenance)) throw malformedApiResponse(method, path, `${label}.provenance must be an object`);
+  requireNonNegativeIntegerProperty(value, "version", method, path, `${label}.version`);
+  const sideEffectLevel = requireNonNegativeIntegerProperty(value, "sideEffectLevel", method, path, `${label}.sideEffectLevel`);
+  if (sideEffectLevel > 4) throw malformedApiResponse(method, path, `${label}.sideEffectLevel must be between 0 and 4`);
+  for (const key of ["replayPasses", "replayFails", "shadowPasses", "shadowFails", "livePasses", "liveFails"] as const) {
+    requireNonNegativeIntegerProperty(value, key, method, path, `${label}.${key}`);
+  }
+  for (const key of ["alpha", "beta", "confidence", "estCostUsd", "estLatencyMs", "createdAt"] as const) {
+    requireFiniteNonNegativeNumberProperty(value, key, method, path, `${label}.${key}`);
+  }
+  if ((value.confidence as number) > 1) throw malformedApiResponse(method, path, `${label}.confidence must be between 0 and 1`);
+  requireOptionalFiniteNonNegativeNumberProperty(value, "promotedAt", method, path, `${label}.promotedAt`);
+  requireOptionalFiniteNonNegativeNumberProperty(value, "lastEvaluatedAt", method, path, `${label}.lastEvaluatedAt`);
+  return value as unknown as Artifact;
+}
+
+function requireArtifactEvaluationRecord(value: unknown, method: string, path: string, label: string): ArtifactEvaluation {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, `${label} must be an object`);
+  for (const key of ["id", "artifactId", "tenantId", "kind"] as const) {
+    requireNonEmptyStringProperty(value, key, method, path, `${label}.${key}`);
+  }
+  if (!["replay", "shadow", "live"].includes(String(value.kind))) {
+    throw malformedApiResponse(method, path, `${label}.kind must be replay|shadow|live`);
+  }
+  for (const key of ["pass", "structuralPass", "sideEffectPass"] as const) {
+    if (typeof value[key] !== "boolean") throw malformedApiResponse(method, path, `${label}.${key} must be boolean`);
+  }
+  requireUnitRateProperty(value, "semanticScore", method, path, `${label}.semanticScore`);
+  requireFiniteNonNegativeNumberProperty(value, "createdAt", method, path, `${label}.createdAt`);
+  return value as unknown as ArtifactEvaluation;
+}
+
+function requirePromotionGateStatus(value: unknown, method: string, path: string): PromotionGateStatus {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "promotionGate must be an object");
+  if (typeof value.eligible !== "boolean") throw malformedApiResponse(method, path, "promotionGate.eligible must be boolean");
+  if (typeof value.autoPromotable !== "boolean") throw malformedApiResponse(method, path, "promotionGate.autoPromotable must be boolean");
+  if (!Array.isArray(value.reasons) || value.reasons.some((reason) => typeof reason !== "string")) {
+    throw malformedApiResponse(method, path, "promotionGate.reasons must be a string array");
+  }
+  return value as unknown as PromotionGateStatus;
+}
+
+function requireArtifactDetailResult(value: unknown, method: string, path: string): ArtifactDetail {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "missing response object");
+  requireArtifactRecord(value.artifact, method, path);
+  const evaluations = requireArrayProperty<unknown>(value, "evaluations", method, path);
+  evaluations.forEach((evaluation, index) => requireArtifactEvaluationRecord(evaluation, method, path, `evaluations[${index}]`));
+  if (value.pattern !== null && value.pattern !== undefined && !isRecord(value.pattern)) {
+    throw malformedApiResponse(method, path, "pattern must be an object or null");
+  }
+  if (value.promotionGate !== undefined) requirePromotionGateStatus(value.promotionGate, method, path);
+  return value as unknown as ArtifactDetail;
+}
+
+function requireReceiptResult(value: unknown, method: string, path: string): PunkReceipt {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "missing response object");
+  if (value.punkReceipt !== 1) throw malformedApiResponse(method, path, "missing punkReceipt marker");
+  requireNonEmptyStringProperty(value, "runId", method, path);
+  if (!isRecord(value.receipt)) throw malformedApiResponse(method, path, "missing receipt object");
+  if (!Array.isArray(value.ledger)) throw malformedApiResponse(method, path, "missing ledger array");
+  return value as PunkReceipt;
+}
+
+function requireEvidencePacketResult(value: unknown, method: string, path: string): EvidencePacket {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "missing response object");
+  if (value.punkEvidencePacket !== 1) throw malformedApiResponse(method, path, "missing punkEvidencePacket marker");
+  if (!isRecord(value.summary)) throw malformedApiResponse(method, path, "missing summary object");
+  requireRunRecord(value.run, method, path);
+  for (const key of ["events", "sideEffects", "auditEvents"] as const) {
+    if (!Array.isArray(value[key])) throw malformedApiResponse(method, path, `missing ${key} array`);
+  }
+  if (!isRecord(value.integrity)) throw malformedApiResponse(method, path, "missing integrity object");
+  if (!isRecord(value.replay)) throw malformedApiResponse(method, path, "missing replay object");
+  return value as EvidencePacket;
+}
+
+function requireLearningReport(value: unknown, method: string, path: string): LearningReport {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, "missing response object");
+  requireNonNegativeIntegerProperty(value, "artifactsSynthesized", method, path);
+  if (!Array.isArray(value.promotionsEligible)) {
+    throw malformedApiResponse(method, path, "missing promotionsEligible array");
+  }
+  if (!Array.isArray(value.autoPromoted)) {
+    throw malformedApiResponse(method, path, "missing autoPromoted array");
+  }
+  return value as unknown as LearningReport;
+}
+
+function requireCacheStatsResult(value: unknown, method: string, path: string): CacheStats {
+  const stats = requireArrayProperty<Record<string, unknown>>(value, "stats", method, path);
+  for (let i = 0; i < stats.length; i++) {
+    const stat = stats[i]!;
+    if (!isRecord(stat)) {
+      throw malformedApiResponse(method, path, `stats[${i}] must be an object`);
+    }
+    if (typeof stat.cacheType !== "string" || stat.cacheType.trim().length === 0) {
+      throw malformedApiResponse(method, path, `stats[${i}].cacheType must be a non-empty string`);
+    }
+    requireNonNegativeIntegerProperty(stat, "entries", method, path, `stats[${i}].entries`);
+    requireNonNegativeIntegerProperty(stat, "hits", method, path, `stats[${i}].hits`);
+  }
+  return value as CacheStats;
+}
+
+function requireMcpServerRecord(value: unknown, method: string, path: string, label: string): McpServerRecord {
+  if (!isRecord(value)) throw malformedApiResponse(method, path, `${label} must be an object`);
+  if (typeof value.id !== "string" || value.id.length === 0) {
+    throw malformedApiResponse(method, path, `${label}.id must be a non-empty string`);
+  }
+  if (typeof value.name !== "string" || value.name.length === 0) {
+    throw malformedApiResponse(method, path, `${label}.name must be a non-empty string`);
+  }
+  if (typeof value.transport !== "string" || !["stdio", "http"].includes(value.transport)) {
+    throw malformedApiResponse(method, path, `${label}.transport must be stdio|http`);
+  }
+  return value as unknown as McpServerRecord;
+}
+
+function requireMcpServerList(value: unknown, method: string, path: string): McpServerRecord[] {
+  const servers = requireArrayProperty<unknown>(value, "servers", method, path);
+  return servers.map((server, index) => requireMcpServerRecord(server, method, path, `servers[${index}]`));
+}
+
+function requireMcpServerCreateResult(value: unknown, method: string, path: string): McpServerRecord {
+  return requireMcpServerRecord(requireObjectProperty<unknown>(value, "server", method, path), method, path, "server");
+}
+
+function cleanPathId(label: string, value: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`Punk SDK requires a string ${label}`);
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error(`Punk SDK requires a non-empty ${label}`);
+  }
+  return trimmed;
+}
+
+function normalizeBaseUrl(value: string | undefined): string {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  return (trimmed || DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+
+function firstChatMessage(raw: unknown, method: string, path: string): unknown {
+  if (raw === null || typeof raw !== "object" || !Array.isArray((raw as any).choices)) {
+    throw malformedChatResponse(method, path, "missing choices array");
+  }
+  const choice = (raw as any).choices[0];
+  if (choice === null || typeof choice !== "object" || Array.isArray(choice)) {
+    throw malformedChatResponse(method, path, "missing choices[0]");
+  }
+  const message = choice.message;
+  if (message === null || typeof message !== "object" || Array.isArray(message)) {
+    throw malformedChatResponse(method, path, "missing choices[0].message");
+  }
+  const content = (message as any).content;
+  const hasToolCalls = normalizeChatToolCalls((message as any).tool_calls).length > 0;
+  const hasRefusal = typeof (message as any).refusal === "string";
+  if ((content === undefined || content === null) && !hasToolCalls && !hasRefusal) {
+    throw malformedChatResponse(method, path, "choices[0].message has no content or tool_calls");
+  }
+  return message;
+}
+
+function chatMessageContentToString(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) {
+    throw malformedChatResponse("POST", "/v1/chat/completions", "message.content was not a string, null, or text parts array");
+  }
+  return value
+    .map((part: any) => {
+      if (typeof part === "string") return part;
+      if (typeof part?.text === "string") return part.text;
+      return "";
+    })
+    .join("");
+}
+
+function chatMessageText(message: any): string {
+  if ((message?.content === null || message?.content === undefined) && typeof message?.refusal === "string") {
+    return message.refusal;
+  }
+  return chatMessageContentToString(message?.content);
+}
+
+const TOOL_LEVEL_4 = new Set([
+  "delete", "remove", "drop", "pay", "charge", "refund", "purchase", "subscribe",
+  "unsubscribe", "transfer", "withdraw", "deposit", "revoke", "grant", "invite",
+  "promote", "demote", "admin", "owner", "role", "permission", "permissions",
+  "password", "secret", "token", "credential", "credentials", "terminate",
+  "destroy", "disable", "deactivate", "suspend", "ban", "cancel", "deploy", "release",
+  "rollback",
+]);
+const TOOL_LEVEL_3 = new Set([
+  "send", "post", "create", "write", "notify", "email", "slack", "ticket",
+  "message", "sms", "comment", "reply", "publish", "submit", "approve", "merge",
+  "webhook", "alert",
+]);
+const TOOL_LEVEL_2 = new Set(["update", "upsert", "tag", "label"]);
+const TOOL_LEVEL_1 = new Set([
+  "get", "list", "read", "search", "fetch", "lookup", "query",
+]);
+const TOOL_LEVEL_0 = new Set(["format", "parse", "transform", "calc", "calculate"]);
+
+function toolNameTokens(toolName: string): string[] {
+  return toolName
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[\s._\-:/]+/)
+    .map((token) => token.toLowerCase())
+    .filter(Boolean);
+}
+
+function normalizeSideEffectLevelValue(value: unknown): SideEffectLevel | undefined {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 4
+    ? (value as SideEffectLevel)
+    : undefined;
+}
+
+function inferSideEffectLevel(toolName: string): { level: SideEffectLevel; matched: boolean } {
+  const tokens = toolNameTokens(toolName);
+  if (
+    tokens.includes("key") &&
+    tokens.some((token) => token === "api" || token === "auth" || token === "secret" || token === "credential")
+  ) {
+    return { level: 4, matched: true };
+  }
+  if (tokens.some((token) => TOOL_LEVEL_4.has(token))) return { level: 4, matched: true };
+  if (tokens.some((token) => TOOL_LEVEL_3.has(token))) return { level: 3, matched: true };
+  if (tokens.some((token) => TOOL_LEVEL_2.has(token))) return { level: 2, matched: true };
+  if (tokens.some((token) => TOOL_LEVEL_1.has(token))) return { level: 1, matched: true };
+  if (tokens.some((token) => TOOL_LEVEL_0.has(token))) return { level: 0, matched: true };
+  return { level: 3, matched: false };
+}
+
+function classifySdkToolSideEffect(toolName: string, declared: unknown): SideEffectLevel {
+  const inferred = inferSideEffectLevel(toolName);
+  const validDeclared = normalizeSideEffectLevelValue(declared);
+  if (validDeclared === undefined) return Math.max(3, inferred.level) as SideEffectLevel;
+  return (inferred.matched ? Math.max(validDeclared, inferred.level) : validDeclared) as SideEffectLevel;
+}
+
+function normalizeTtlSeconds(value: unknown): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw new Error("Punk traceTool requires 'ttlSeconds' to be a positive integer when provided");
+  }
+  if (value > MAX_TOOL_CACHE_TTL_SECONDS) {
+    throw new Error(`Punk traceTool requires 'ttlSeconds' to be ${MAX_TOOL_CACHE_TTL_SECONDS} or fewer`);
+  }
+  return value;
+}
+
+function cleanIdentityValue(value: string | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function cleanOptionalCacheDimension(label: string, value: string | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed !== value || trimmed.length > MAX_TOOL_CACHE_DIMENSION_CHARS) {
+    throw new Error(`Punk traceTool requires '${label}' to be a non-empty trimmed string ${MAX_TOOL_CACHE_DIMENSION_CHARS} characters or fewer`);
+  }
+  return trimmed;
+}
+
+function requireCleanToolName(value: unknown): string {
+  if (typeof value !== "string") {
+    throw new Error("Punk traceTool requires a string tool name");
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error("Punk traceTool requires a non-empty tool name");
+  }
+  if (trimmed.length > MAX_TOOL_CACHE_DIMENSION_CHARS) {
+    throw new Error(`Punk traceTool requires a tool name ${MAX_TOOL_CACHE_DIMENSION_CHARS} characters or fewer`);
+  }
+  return trimmed;
+}
+
+function toolErrorPayload(err: unknown): Record<string, unknown> {
+  if (err instanceof Error) {
+    return {
+      name: err.name,
+      message: err.message,
+    };
+  }
+  return { message: String(err) };
+}
+
+function toolCacheHitHasResult(hit: { hit: boolean; result?: unknown }): hit is { hit: true; result: unknown } {
+  return hit.hit === true && Object.prototype.hasOwnProperty.call(hit, "result") && hit.result !== undefined;
+}
+
+function normalizeTraceDecision(value: unknown): PolicyVerdict | null {
+  if (!isRecord(value)) return null;
+  const decision = value.decision;
+  if (decision !== "allow" && decision !== "deny" && decision !== "approval_required") return null;
+  return {
+    ...((value as unknown) as Omit<PolicyVerdict, "decision" | "reason">),
+    decision,
+    reason: typeof value.reason === "string" ? value.reason : "",
+  };
+}
+
+export interface ChatResult {
+  content: string;
+  toolCalls: ChatToolCall[];
+  runId: string;
+  route: string;
+  raw: any;
+}
+
+export interface PunkReceipt {
+  id?: string;
+  runId?: string;
+  route?: string;
+  chorus?: PunkChorusMetadata;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface EvidencePacket {
+  punkEvidencePacket?: number;
+  summary?: Record<string, unknown>;
+  routeExplanation?: unknown;
+  events?: unknown[];
+  chorus?: PunkChorusMetadata;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface WebFetchResult {
+  som: SomSnapshot;
+  source: string; // "plasmate" | "builtin" | "cache"
+  cached: boolean;
+  /** Canonical observed URL after redirects and fragment normalization. */
+  url: string;
+  /** Caller-supplied URL after server-side trim/canonicalization, before redirects. */
+  requestedUrl: string;
+  htmlBytes: number;
+  somBytes: number;
+  tokensSavedEstimate: number;
+  diff?: SomDiff;
+  context: string;
+}
+
+export interface WebSessionSummary {
+  id: string;
+  url: string;
+  source: string; // "plasmate" | "builtin"
+  openedAt: number;
+  ageMs: number;
+}
+
+export interface WebSessionOpenResult {
+  sessionId: string;
+  som: SomSnapshot;
+  source: string; // "plasmate" | "builtin"
+  session: WebSessionSummary;
+  context: string;
+}
+
+export interface WebActResult {
+  result: WebActionResult;
+  som: SomSnapshot;
+  diff?: SomDiff;
+  session: WebSessionSummary;
+  context: string;
+}
+
+export interface LearningReport {
+  artifactsSynthesized: number;
+  promotionsEligible: string[];
+  autoPromoted: string[];
+  synthesisReports?: Array<Record<string, unknown>>;
+  [key: string]: unknown;
+}
+
+export interface RunDetail {
+  run: Run;
+  events: TraceEvent[];
+  sideEffects: SideEffectRecord[];
+}
+
+export interface ArtifactDetail {
+  artifact: Artifact;
+  evaluations: ArtifactEvaluation[];
+  pattern: Pattern | null;
+  promotionGate?: PromotionGateStatus;
+}
+
+export interface CacheStats {
+  stats: Array<{ cacheType: string; entries: number; hits: number }>;
+}
+
+export interface ToolDefinition<TArgs, TResult> {
+  name: string;
+  /** 0 pure … 4 high-impact. Undeclared tools are treated as level 3 (conservative). */
+  sideEffectLevel?: SideEffectLevel;
+  /** Read-only tools (level <= 1) with a TTL participate in the tool-result cache. */
+  ttlSeconds?: number;
+  /** Optional schema/version fingerprint used to isolate tool-result cache entries across contract changes. */
+  schemaFp?: string;
+  execute: (args: TArgs) => Promise<TResult> | TResult;
+}
+
+export type TracedTool<TArgs, TResult> = (
+  args: TArgs,
+  ctx?: { runId?: string },
+) => Promise<TResult>;
+
+export function punkChorusChat(
+  params: Omit<ChatParams, "model"> & { model?: typeof PUNK_CHORUS_MODEL },
+): ChatParams {
+  return { ...params, model: PUNK_CHORUS_MODEL };
+}
+
+/** @deprecated Use punkChorusChat. */
+export const punkModelChat = punkChorusChat;
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+export class Punk {
+  readonly baseUrl: string;
+  readonly app: string;
+  readonly agent?: string;
+  readonly subject?: string;
+  private readonly apiKey?: 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);
+  }
+
+  // -- chat -----------------------------------------------------------------
+
+  /** Send an OpenAI-compatible chat completion through the gateway. */
+  async chat(params: ChatParams): Promise<ChatResult> {
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+        method: "POST",
+        headers: this.headers({
+          "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("POST", "/v1/chat/completions", err);
+    }
+    const path = "/v1/chat/completions";
+    const method = "POST";
+    const raw = await this.parseJsonResponse<any>(method, path, res);
+    const message = firstChatMessage(raw, method, path) as any;
+    const toolCalls = normalizeChatToolCalls(message?.tool_calls);
+    return {
+      content: chatMessageText(message),
+      toolCalls,
+      runId: res.headers.get("x-punk-run-id") ?? "",
+      route: res.headers.get("x-punk-route") ?? "unknown",
+      raw,
+    };
+  }
+
+  // -- 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.
+   */
+  traceTool<TArgs, TResult>(
+    def: ToolDefinition<TArgs, TResult>,
+  ): TracedTool<TArgs, TResult> {
+    const toolName = requireCleanToolName(def.name);
+    const level = classifySdkToolSideEffect(toolName, def.sideEffectLevel);
+    const ttlSeconds = normalizeTtlSeconds(def.ttlSeconds);
+    const schemaFp = cleanOptionalCacheDimension("schemaFp", def.schemaFp);
+
+    return async (args: TArgs, ctx?: { runId?: string }): Promise<TResult> => {
+      const runId = cleanIdentityValue(ctx?.runId);
+      const cacheable = level <= 1 && ttlSeconds !== undefined && runId !== undefined && this.subject !== undefined;
+
+      if (runId) {
+        const decision = await this.tryTraceDecision(runId, "tool.called", {
+          name: toolName,
+          args,
+          sideEffectLevel: level,
+          ...(schemaFp ? { schemaFp } : {}),
+        });
+        if (decision && decision.decision !== "allow") {
+          const message = `Punk policy ${decision.decision}: ${decision.reason || "tool execution is not allowed"}`;
+          if (level >= 2) {
+            await this.tryTrace(runId, "side_effect.suppressed", {
+              toolName,
+              level,
+              payload: args,
+              decision: decision.decision,
+              reason: decision.reason,
+            });
+          }
+          await this.tryTrace(runId, "tool.completed", {
+            name: toolName,
+            sideEffectLevel: level,
+            error: {
+              name: "PunkPolicyError",
+              message,
+              decision: decision.decision,
+              reason: decision.reason,
+            },
+          });
+          throw new Error(message);
+        }
+      }
+
+      if (cacheable) {
+        const cached = await this.toolCacheCheck(toolName, args, level, schemaFp);
+        if (toolCacheHitHasResult(cached)) {
+          if (runId) {
+            await this.tryTrace(runId, "tool.completed", {
+              name: toolName,
+              sideEffectLevel: level,
+              result: cached.result,
+              cached: true,
+              ...(schemaFp ? { schemaFp } : {}),
+            });
+          }
+          return cached.result as TResult;
+        }
+      }
+
+      if (runId) {
+        if (level >= 2) {
+          await this.tryTrace(runId, "side_effect.planned", {
+            toolName,
+            level,
+            payload: args,
+          });
+        }
+      }
+
+      let result: TResult;
+      try {
+        result = await def.execute(args);
+      } catch (err) {
+        if (runId) {
+          await this.tryTrace(runId, "tool.completed", {
+            name: toolName,
+            sideEffectLevel: level,
+            error: toolErrorPayload(err),
+            ...(schemaFp ? { schemaFp } : {}),
+          });
+        }
+        throw err;
+      }
+
+      if (runId) {
+        if (level >= 2) {
+          await this.tryTrace(runId, "side_effect.executed", {
+            toolName,
+            level,
+            payload: args,
+          });
+        }
+        await this.tryTrace(runId, "tool.completed", {
+          name: toolName,
+          sideEffectLevel: level,
+          result,
+          ...(schemaFp ? { schemaFp } : {}),
+        });
+      }
+      if (cacheable) {
+        await this.toolCacheStore(toolName, args, result, ttlSeconds, level, schemaFp);
+      }
+      return result;
+    };
+  }
+
+  /** Append a trace event to a run. */
+  async trace(
+    runId: string,
+    type: TraceEventType | string,
+    payload: Record<string, unknown>,
+  ): Promise<void> {
+    const id = cleanPathId("run id", runId);
+    await this.request<{ ok: boolean }>("POST", "/api/v1/trace", {
+      runId: id,
+      type,
+      payload,
+    });
+  }
+
+  // -- feedback ---------------------------------------------------------------
+
+  async feedback(
+    runId: string,
+    rating: 1 | -1,
+    correction?: string,
+  ): Promise<void> {
+    const id = cleanPathId("run id", runId);
+    const path = `/api/v1/runs/${encodeURIComponent(id)}/feedback`;
+    const trimmedCorrection = typeof correction === "string" ? correction.trim() : "";
+    const body = trimmedCorrection
+      ? { type: "correction", correction: trimmedCorrection }
+      : { type: "rating", rating };
+    requireOkResult(await this.request<unknown>("POST", path, body), "POST", path);
+  }
+
+  // -- semantic web (Plasmate SOM) --------------------------------------------
+
+  async fetchSom(
+    url: string,
+    opts?: { bypassCache?: boolean },
+  ): Promise<WebFetchResult> {
+    const path = "/api/v1/web/fetch";
+    return requireWebFetchResult(await this.request<unknown>("POST", path, {
+      url,
+      ...(opts?.bypassCache ? { bypassCache: true } : {}),
+    }), "POST", path);
+  }
+
+  /**
+   * Web sessions & actions — the perception→action loop. Open a session,
+   * act on SOM element ids (click/type/select/submit), close it. Actions are
+   * policy-governed server-side: type/select and read-only clicks are
+   * "read:web" (side-effect level 0–1); submit and submit-button clicks are
+   * "write:web" at level 3 and can be denied/held by policy (403).
+   * Observe-mode keys cannot perform web writes.
+   */
+  readonly web = {
+    openSession: async (url: string): Promise<WebSessionOpenResult> => {
+      const path = "/api/v1/web/sessions";
+      return requireWebSessionOpenResult(await this.request<unknown>("POST", path, { url }), "POST", path);
+    },
+
+    act: async (sessionId: string, intent: WebActionIntent): Promise<WebActResult> => {
+      const id = cleanPathId("web session id", sessionId);
+      const path = `/api/v1/web/sessions/${encodeURIComponent(id)}/act`;
+      return requireWebActResult(await this.request<unknown>("POST", path, { intent }), "POST", path, id);
+    },
+
+    closeSession: async (sessionId: string): Promise<{ ok: true }> => {
+      const id = cleanPathId("web session id", sessionId);
+      const path = `/api/v1/web/sessions/${encodeURIComponent(id)}`;
+      return requireOkResult(await this.request<unknown>("DELETE", path), "DELETE", path);
+    },
+
+    listSessions: async (): Promise<{
+      sessions: WebSessionSummary[];
+    }> => {
+      const path = "/api/v1/web/sessions";
+      return requireWebSessionsListResult(await this.request<unknown>("GET", path), "GET", path);
+    },
+  };
+
+  // -- external MCP servers (registry + connection testing) -------------------
+
+  /**
+   * The gateway's external-MCP registry: register servers (admin), test
+   * connections (connect + list_tools), and let workflow tool_call nodes use
+   * them. Note: stdio servers execute their command on the GATEWAY host —
+   * registration is an operator-level action.
+   */
+  readonly mcp = {
+    listServers: async (): Promise<McpServerRecord[]> => {
+      const path = "/api/v1/mcp/servers";
+      return requireMcpServerList(await this.request<unknown>("GET", path), "GET", path);
+    },
+
+    createServer: async (server: {
+      name: string;
+      transport: "stdio" | "http";
+      command?: string;
+      args?: string[];
+      url?: string;
+      /** Values may be cred:<credentialId> references (resolved at connect time). */
+      env?: Record<string, string>;
+      headers?: Record<string, string>;
+      enabled?: boolean;
+    }): Promise<McpServerRecord> => {
+      const path = "/api/v1/mcp/servers";
+      return requireMcpServerCreateResult(await this.request<unknown>("POST", path, server), "POST", path);
+    },
+
+    /** Connect + list_tools (throwaway connection); persists the server's status. */
+    testServer: (id: string): Promise<McpTestResult> =>
+      this.request<McpTestResult>(
+        "POST",
+        `/api/v1/mcp/servers/${encodeURIComponent(cleanPathId("MCP server id", id))}/test`,
+      ),
+  };
+
+  // -- memory quarantine (trust-lane influence declaration) -------------------
+
+  /**
+   * Declare what memory/context influenced a run, tagged with its trust lane.
+   * Recording is ALWAYS allowed (cheap, useful telemetry). When the tenant
+   * enables memory quarantine, low-trust influence (untrusted/observed) on a
+   * run gates that run's high-impact (side-effect ≥ threshold) actions to
+   * approval_required — "untrusted web content can't trigger a payment".
+   */
+  readonly memory = {
+    recordInfluence: (
+      runId: string,
+      influence: { source: string; trustLane: TrustLane; contentHash?: string },
+    ): Promise<{ ok: boolean; influence: { id: string; runId: string; source: string; trustLane: TrustLane } }> =>
+      this.request(
+        "POST",
+        `/api/v1/runs/${encodeURIComponent(cleanPathId("run id", runId))}/memory`,
+        influence,
+      ),
+  };
+
+  // -- prompt side-loading (Punk Runtime Engine ingest) -----------------------
+
+  /**
+   * Ingest an externally-handled prompt (Claude Code / Claude app / any
+   * client) as a completed OBSERVED run: $0 cost, model "external", redaction
+   * honored. Returns the created run id.
+   */
+  async ingestPrompt(
+    source: string,
+    prompt: string,
+    opts?: { sessionId?: string; metadata?: Record<string, unknown> },
+  ): Promise<{ runId: string }> {
+    return this.request<{ runId: string }>("POST", "/api/v1/ingest/prompt", {
+      source,
+      prompt,
+      ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
+      ...(opts?.metadata ? { metadata: opts.metadata } : {}),
+    });
+  }
+
+  // -- read APIs ---------------------------------------------------------------
+
+  async savings(): Promise<SavingsSummary> {
+    const path = "/api/v1/savings";
+    return requireSavingsSummary(await this.request<unknown>("GET", path), "GET", path);
+  }
+
+  async patterns(): Promise<Pattern[]> {
+    const path = "/api/v1/patterns";
+    const body = await this.request<unknown>(
+      "GET",
+      path,
+    );
+    return requireArrayProperty<Pattern>(body, "patterns", "GET", path);
+  }
+
+  async artifacts(): Promise<Artifact[]> {
+    const path = "/api/v1/artifacts";
+    const body = await this.request<unknown>(
+      "GET",
+      path,
+    );
+    return requireArrayProperty<Artifact>(body, "artifacts", "GET", path);
+  }
+
+  async artifactDetail(id: string): Promise<ArtifactDetail> {
+    const path = `/api/v1/artifacts/${encodeURIComponent(cleanPathId("artifact id", id))}`;
+    return requireArtifactDetailResult(await this.request<unknown>("GET", path), "GET", path);
+  }
+
+  async runDetail(id: string): Promise<RunDetail> {
+    const path = `/api/v1/runs/${encodeURIComponent(cleanPathId("run id", id))}`;
+    return requireRunDetailResult(await this.request<unknown>("GET", path), "GET", path);
+  }
+
+  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);
+  }
+
+  async evidencePacket(runId: string): Promise<EvidencePacket> {
+    const path = `/api/v1/runs/${encodeURIComponent(cleanPathId("run id", runId))}/evidence-packet`;
+    return requireEvidencePacketResult(await this.request<unknown>("GET", path), "GET", path);
+  }
+
+  async cacheStats(): Promise<CacheStats> {
+    const path = "/api/v1/cache/stats";
+    const body = await this.request<unknown>("GET", path);
+    return requireCacheStatsResult(body, "GET", path);
+  }
+
+  // -- learning lifecycle -------------------------------------------------------
+
+  async learningTick(): Promise<LearningReport> {
+    const path = "/api/v1/learning/tick";
+    return requireLearningReport(await this.request<unknown>("POST", path), "POST", path);
+  }
+
+  async promoteArtifact(id: string): Promise<Artifact> {
+    const path = `/api/v1/artifacts/${encodeURIComponent(cleanPathId("artifact id", id))}/promote`;
+    const body = await this.request<{ artifact: Artifact }>(
+      "POST",
+      path,
+    );
+    return requireObjectProperty<Artifact>(body, "artifact", "POST", path);
+  }
+
+  // -- tool-result cache ----------------------------------------------------
+
+  /** Best-effort cache lookup; network failures degrade to a miss. */
+  async toolCacheCheck(
+    toolName: string,
+    args: unknown,
+    sideEffectLevel?: SideEffectLevel,
+    schemaFp?: string,
+  ): Promise<{ hit: boolean; result?: unknown }> {
+    try {
+      return await this.request<{ hit: boolean; result?: unknown }>(
+        "POST",
+        "/api/v1/tool-cache/check",
+        { toolName, appId: this.app, subject: this.subject, args, sideEffectLevel, schemaFp },
+      );
+    } catch {
+      return { hit: false };
+    }
+  }
+
+  /** Best-effort cache store; failures are swallowed. */
+  async toolCacheStore(
+    toolName: string,
+    args: unknown,
+    result: unknown,
+    ttlSeconds?: number,
+    sideEffectLevel?: SideEffectLevel,
+    schemaFp?: string,
+  ): Promise<void> {
+    try {
+      await this.request<{ ok: boolean }>("POST", "/api/v1/tool-cache/store", {
+        toolName,
+        appId: this.app,
+        subject: this.subject,
+        args,
+        result,
+        ttlSeconds,
+        sideEffectLevel,
+        schemaFp,
+      });
+    } catch {
+      // caching is an optimization, never a failure mode
+    }
+  }
+
+  // -- internals --------------------------------------------------------------
+
+  private headers(
+    extra?: Record<string, string | undefined>,
+  ): Record<string, string> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    if (extra) {
+      for (const [key, value] of Object.entries(extra)) {
+        if (value !== undefined && value !== "") headers[key] = value;
+      }
+    }
+    return headers;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: this.headers(),
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      });
+    } catch (err) {
+      throw this.toTransportError(method, path, err);
+    }
+    return this.parseJsonResponse<T>(method, path, res);
+  }
+
+  private async parseJsonResponse<T>(
+    method: string,
+    path: string,
+    res: Response,
+  ): Promise<T> {
+    const text = await res.text();
+    if (!res.ok) {
+      throw this.toError(method, path, res, text);
+    }
+    try {
+      return JSON.parse(text) as T;
+    } catch {
+      throw new Error(
+        `Punk API ${method} ${path} returned non-JSON response: ${res.status} ${res.statusText}` +
+          (text ? ` — ${text.slice(0, 500)}` : ""),
+      );
+    }
+  }
+
+  private toError(
+    method: string,
+    path: string,
+    res: Response,
+    text: string,
+  ): Error {
+    const message = this.responseErrorMessage(text);
+    const runId = res.headers.get("x-punk-run-id");
+    const route = res.headers.get("x-punk-route");
+    const evidence = [
+      runId ? `run ${runId}` : "",
+      route ? `route ${route}` : "",
+    ].filter(Boolean).join(", ");
+    return new Error(
+      `Punk API ${method} ${path} failed: ${res.status} ${res.statusText}` +
+        (evidence ? ` (${evidence})` : "") +
+        (message ? ` — ${message}` : ""),
+    );
+  }
+
+  private toTransportError(method: string, path: string, err: unknown): Error {
+    const reason = err instanceof Error ? err.message : String(err);
+    return new Error(
+      `Punk API ${method} ${path} could not reach ${this.baseUrl}: ${reason}`,
+    );
+  }
+
+  private responseErrorMessage(text: string): string {
+    if (!text) return "";
+    let data: any = null;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      return text.slice(0, 500);
+    }
+    const error = data?.error;
+    let message = "";
+    if (error && typeof error === "object") {
+      if (typeof error.message === "string" && error.message.trim()) message = error.message.trim();
+      else if (typeof error.code === "string" && error.code.trim()) message = error.code.trim();
+      else {
+        try {
+          message = JSON.stringify(error);
+        } catch {
+          message = String(error);
+        }
+      }
+    } else if (typeof data?.message === "string" && data.message.trim()) {
+      message = data.message.trim();
+      if (typeof error === "string" && error.trim() && error.trim() !== message) {
+        message += ` (${error.trim()})`;
+      }
+    } else if (typeof error === "string" && error.trim()) {
+      message = error.trim();
+    } else {
+      message = text.slice(0, 500);
+    }
+    if (Array.isArray(data?.validation) && data.validation.length > 0) {
+      message += `: ${data.validation.slice(0, 3).map((v: unknown) => String(v)).join("; ")}`;
+    }
+    return message.slice(0, 500);
+  }
+
+  /** Tracing is observability, not control flow — failures are swallowed. */
+  private async tryTrace(
+    runId: string,
+    type: TraceEventType | string,
+    payload: Record<string, unknown>,
+  ): Promise<void> {
+    try {
+      await this.trace(runId, type, payload);
+    } catch {
+      // never let telemetry break the tool call
+    }
+  }
+
+  /**
+   * Trace a tool call and return Punk's governance decision when one is
+   * provided. Transport/API failures still fail open so telemetry outages do
+   * not break tools; explicit deny/approval decisions remain control flow.
+   */
+  private async tryTraceDecision(
+    runId: string,
+    type: TraceEventType | string,
+    payload: Record<string, unknown>,
+  ): Promise<PolicyVerdict | null> {
+    try {
+      const res = await this.request<{ ok: boolean; decision?: PolicyVerdict }>("POST", "/api/v1/trace", {
+        runId,
+        type,
+        payload,
+      });
+      return normalizeTraceDecision(res.decision);
+    } catch {
+      return null;
+    }
+  }
+}
+
+export default Punk;