@punktechnologies/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1058 @@
+// src/index.ts
+var PUNK_CHORUS_MODEL = "punk/chorus";
+var PUNK_MODEL = PUNK_CHORUS_MODEL;
+var DEFAULT_BASE_URL = "http://localhost:4100";
+var MAX_TOOL_CACHE_TTL_SECONDS = 24 * 60 * 60;
+function stringifyToolArguments(value) {
+  if (typeof value === "string")
+    return value;
+  try {
+    return JSON.stringify(value ?? {}) ?? "{}";
+  } catch {
+    return "{}";
+  }
+}
+function normalizeChatToolCalls(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.map((tc, index) => {
+    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 !== null);
+}
+function malformedChatResponse(method, path, reason) {
+  return new Error(`Punk API ${method} ${path} returned malformed chat response: ${reason}`);
+}
+function malformedApiResponse(method, path, reason) {
+  return new Error(`Punk API ${method} ${path} returned malformed response: ${reason}`);
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireArrayProperty(value, key, method, path) {
+  if (!isRecord(value) || !Array.isArray(value[key])) {
+    throw malformedApiResponse(method, path, `missing ${key} array`);
+  }
+  return value[key];
+}
+function requireObjectProperty(value, key, method, path) {
+  if (!isRecord(value) || !isRecord(value[key])) {
+    throw malformedApiResponse(method, path, `missing ${key} object`);
+  }
+  return value[key];
+}
+function requireWebFetchResult(value, method, path) {
+  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"]) {
+    if (typeof value[key] !== "number" || !Number.isFinite(value[key])) {
+      throw malformedApiResponse(method, path, `missing finite ${key}`);
+    }
+  }
+  return value;
+}
+function requireWebSessionOpenResult(value, method, path) {
+  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;
+}
+function requireWebActResult(value, method, path, expectedSessionId) {
+  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;
+}
+function requireWebActionResult(value, method, path) {
+  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, method, path, label) {
+  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;
+}
+function requireWebSessionsListResult(value, method, path) {
+  const sessions = requireArrayProperty(value, "sessions", method, path);
+  for (let i = 0;i < sessions.length; i++) {
+    requireWebSessionSummary(sessions[i], method, path, `sessions[${i}]`);
+  }
+  return value;
+}
+function requireOkResult(value, method, path) {
+  if (!isRecord(value) || value.ok !== true) {
+    throw malformedApiResponse(method, path, "missing ok true");
+  }
+  return { ok: true };
+}
+function requireNonNegativeIntegerProperty(value, key, method, path, label = key) {
+  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, key, method, path, label = key) {
+  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, key, method, path, label = key) {
+  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, key, method, path, label = key) {
+  if (value[key] === undefined)
+    return;
+  requireFiniteNonNegativeNumberProperty(value, key, method, path, label);
+}
+function requireUnitRateProperty(value, key, method, path, label = key) {
+  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, method, path) {
+  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"]) {
+    requireNonNegativeIntegerProperty(value, key, method, path);
+  }
+  for (const key of ["totalCostUsd", "totalSavedUsd", "ghostSavedUsd", "totalSavedMs"]) {
+    requireFiniteNonNegativeNumberProperty(value, key, method, path);
+  }
+  requireUnitRateProperty(value, "cacheHitRate", method, path);
+  requireUnitRateProperty(value, "artifactHitRate", method, path);
+  const totalRuns = value.totalRuns;
+  const accountedRuns = value.liveRuns + value.optimizedRuns + value.blockedRuns;
+  if (accountedRuns !== totalRuns) {
+    throw malformedApiResponse(method, path, "run counters must add up to totalRuns");
+  }
+  if (value.cacheHits > value.optimizedRuns) {
+    throw malformedApiResponse(method, path, "cacheHits cannot exceed optimizedRuns");
+  }
+  if (value.artifactHits > value.optimizedRuns) {
+    throw malformedApiResponse(method, path, "artifactHits cannot exceed optimizedRuns");
+  }
+  return value;
+}
+var RUN_STATUSES = new Set(["running", "completed", "failed", "blocked"]);
+var ARTIFACT_STATES = new Set(["candidate", "replay_failed", "replay_passed", "shadowing", "shadow_failed", "approved", "promoted", "canary", "stable", "degraded", "quarantined", "retired"]);
+var ARTIFACT_TYPES = new Set(["static_response", "template", "deterministic_transform", "ruleset_classifier", "tool_plan", "web_extraction", "hybrid"]);
+function requireRunRecord(value, method, path, label = "run") {
+  if (!isRecord(value))
+    throw malformedApiResponse(method, path, `missing ${label} object`);
+  for (const key of ["id", "tenantId", "appId", "requestHash"]) {
+    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"]) {
+    requireNonNegativeIntegerProperty(value, key, method, path, `${label}.${key}`);
+  }
+  for (const key of ["costUsd", "savedUsd", "latencyMs", "startedAt"]) {
+    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;
+}
+function requireTraceEventRecord(value, method, path, label) {
+  if (!isRecord(value))
+    throw malformedApiResponse(method, path, `${label} must be an object`);
+  for (const key of ["id", "runId", "tenantId", "type"]) {
+    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;
+}
+function requireSideEffectRecord(value, method, path, label) {
+  if (!isRecord(value))
+    throw malformedApiResponse(method, path, `${label} must be an object`);
+  for (const key of ["id", "runId", "tenantId", "toolName", "status"]) {
+    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;
+}
+function requireRunDetailResult(value, method, path) {
+  if (!isRecord(value))
+    throw malformedApiResponse(method, path, "missing response object");
+  requireRunRecord(value.run, method, path);
+  const events = requireArrayProperty(value, "events", method, path);
+  events.forEach((event, index) => requireTraceEventRecord(event, method, path, `events[${index}]`));
+  const sideEffects = requireArrayProperty(value, "sideEffects", method, path);
+  sideEffects.forEach((sideEffect, index) => requireSideEffectRecord(sideEffect, method, path, `sideEffects[${index}]`));
+  return value;
+}
+function requireArtifactRecord(value, method, path, label = "artifact") {
+  if (!isRecord(value))
+    throw malformedApiResponse(method, path, `missing ${label} object`);
+  for (const key of ["id", "tenantId", "patternId", "state", "type"]) {
+    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"]) {
+    requireNonNegativeIntegerProperty(value, key, method, path, `${label}.${key}`);
+  }
+  for (const key of ["alpha", "beta", "confidence", "estCostUsd", "estLatencyMs", "createdAt"]) {
+    requireFiniteNonNegativeNumberProperty(value, key, method, path, `${label}.${key}`);
+  }
+  if (value.confidence > 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;
+}
+function requireArtifactEvaluationRecord(value, method, path, label) {
+  if (!isRecord(value))
+    throw malformedApiResponse(method, path, `${label} must be an object`);
+  for (const key of ["id", "artifactId", "tenantId", "kind"]) {
+    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"]) {
+    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;
+}
+function requirePromotionGateStatus(value, method, path) {
+  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;
+}
+function requireArtifactDetailResult(value, method, path) {
+  if (!isRecord(value))
+    throw malformedApiResponse(method, path, "missing response object");
+  requireArtifactRecord(value.artifact, method, path);
+  const evaluations = requireArrayProperty(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;
+}
+function requireReceiptResult(value, method, path) {
+  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;
+}
+function requireEvidencePacketResult(value, method, path) {
+  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"]) {
+    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;
+}
+function requireLearningReport(value, method, path) {
+  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;
+}
+function requireCacheStatsResult(value, method, path) {
+  const stats = requireArrayProperty(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;
+}
+function requireMcpServerRecord(value, method, path, label) {
+  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;
+}
+function requireMcpServerList(value, method, path) {
+  const servers = requireArrayProperty(value, "servers", method, path);
+  return servers.map((server, index) => requireMcpServerRecord(server, method, path, `servers[${index}]`));
+}
+function requireMcpServerCreateResult(value, method, path) {
+  return requireMcpServerRecord(requireObjectProperty(value, "server", method, path), method, path, "server");
+}
+function cleanPathId(label, value) {
+  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) {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  return (trimmed || DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+function firstChatMessage(raw, method, path) {
+  if (raw === null || typeof raw !== "object" || !Array.isArray(raw.choices)) {
+    throw malformedChatResponse(method, path, "missing choices array");
+  }
+  const choice = raw.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.content;
+  const hasToolCalls = normalizeChatToolCalls(message.tool_calls).length > 0;
+  const hasRefusal = typeof message.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) {
+  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) => {
+    if (typeof part === "string")
+      return part;
+    if (typeof part?.text === "string")
+      return part.text;
+    return "";
+  }).join("");
+}
+function chatMessageText(message) {
+  if ((message?.content === null || message?.content === undefined) && typeof message?.refusal === "string") {
+    return message.refusal;
+  }
+  return chatMessageContentToString(message?.content);
+}
+var 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"
+]);
+var TOOL_LEVEL_3 = new Set([
+  "send",
+  "post",
+  "create",
+  "write",
+  "notify",
+  "email",
+  "slack",
+  "ticket",
+  "message",
+  "sms",
+  "comment",
+  "reply",
+  "publish",
+  "submit",
+  "approve",
+  "merge",
+  "webhook",
+  "alert"
+]);
+var TOOL_LEVEL_2 = new Set(["update", "upsert", "tag", "label"]);
+var TOOL_LEVEL_1 = new Set([
+  "get",
+  "list",
+  "read",
+  "search",
+  "fetch",
+  "lookup",
+  "query"
+]);
+var TOOL_LEVEL_0 = new Set(["format", "parse", "transform", "calc", "calculate"]);
+function toolNameTokens(toolName) {
+  return toolName.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[\s._\-:/]+/).map((token) => token.toLowerCase()).filter(Boolean);
+}
+function normalizeSideEffectLevelValue(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 4 ? value : undefined;
+}
+function inferSideEffectLevel(toolName) {
+  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, declared) {
+  const inferred = inferSideEffectLevel(toolName);
+  const validDeclared = normalizeSideEffectLevelValue(declared);
+  if (validDeclared === undefined)
+    return Math.max(3, inferred.level);
+  return inferred.matched ? Math.max(validDeclared, inferred.level) : validDeclared;
+}
+function normalizeTtlSeconds(value) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0)
+    return;
+  return Math.min(value, MAX_TOOL_CACHE_TTL_SECONDS);
+}
+function cleanIdentityValue(value) {
+  if (typeof value !== "string")
+    return;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+function cleanOptionalCacheDimension(label, value) {
+  if (typeof value !== "string")
+    return;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed !== value || trimmed.length > 120) {
+    throw new Error(`Punk traceTool requires '${label}' to be a non-empty trimmed string 120 characters or fewer`);
+  }
+  return trimmed;
+}
+function requireCleanToolName(value) {
+  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");
+  }
+  return trimmed;
+}
+function toolErrorPayload(err) {
+  if (err instanceof Error) {
+    return {
+      name: err.name,
+      message: err.message
+    };
+  }
+  return { message: String(err) };
+}
+function toolCacheHitHasResult(hit) {
+  return hit.hit === true && Object.prototype.hasOwnProperty.call(hit, "result") && hit.result !== undefined;
+}
+function normalizeTraceDecision(value) {
+  if (!isRecord(value))
+    return null;
+  const decision = value.decision;
+  if (decision !== "allow" && decision !== "deny" && decision !== "approval_required")
+    return null;
+  return {
+    ...value,
+    decision,
+    reason: typeof value.reason === "string" ? value.reason : ""
+  };
+}
+function punkChorusChat(params) {
+  return { ...params, model: PUNK_CHORUS_MODEL };
+}
+var punkModelChat = punkChorusChat;
+
+class Punk {
+  baseUrl;
+  app;
+  agent;
+  subject;
+  apiKey;
+  constructor(opts = {}) {
+    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);
+  }
+  async chat(params) {
+    let res;
+    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(method, path, res);
+    const message = firstChatMessage(raw, method, path);
+    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
+    };
+  }
+  traceTool(def) {
+    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, ctx) => {
+      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;
+        }
+      }
+      if (runId) {
+        if (level >= 2) {
+          await this.tryTrace(runId, "side_effect.planned", {
+            toolName,
+            level,
+            payload: args
+          });
+        }
+      }
+      let result;
+      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;
+    };
+  }
+  async trace(runId, type, payload) {
+    const id = cleanPathId("run id", runId);
+    await this.request("POST", "/api/v1/trace", {
+      runId: id,
+      type,
+      payload
+    });
+  }
+  async feedback(runId, rating, correction) {
+    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("POST", path, body), "POST", path);
+  }
+  async fetchSom(url, opts) {
+    const path = "/api/v1/web/fetch";
+    return requireWebFetchResult(await this.request("POST", path, {
+      url,
+      ...opts?.bypassCache ? { bypassCache: true } : {}
+    }), "POST", path);
+  }
+  web = {
+    openSession: async (url) => {
+      const path = "/api/v1/web/sessions";
+      return requireWebSessionOpenResult(await this.request("POST", path, { url }), "POST", path);
+    },
+    act: async (sessionId, intent) => {
+      const id = cleanPathId("web session id", sessionId);
+      const path = `/api/v1/web/sessions/${encodeURIComponent(id)}/act`;
+      return requireWebActResult(await this.request("POST", path, { intent }), "POST", path, id);
+    },
+    closeSession: async (sessionId) => {
+      const id = cleanPathId("web session id", sessionId);
+      const path = `/api/v1/web/sessions/${encodeURIComponent(id)}`;
+      return requireOkResult(await this.request("DELETE", path), "DELETE", path);
+    },
+    listSessions: async () => {
+      const path = "/api/v1/web/sessions";
+      return requireWebSessionsListResult(await this.request("GET", path), "GET", path);
+    }
+  };
+  mcp = {
+    listServers: async () => {
+      const path = "/api/v1/mcp/servers";
+      return requireMcpServerList(await this.request("GET", path), "GET", path);
+    },
+    createServer: async (server) => {
+      const path = "/api/v1/mcp/servers";
+      return requireMcpServerCreateResult(await this.request("POST", path, server), "POST", path);
+    },
+    testServer: (id) => this.request("POST", `/api/v1/mcp/servers/${encodeURIComponent(cleanPathId("MCP server id", id))}/test`)
+  };
+  memory = {
+    recordInfluence: (runId, influence) => this.request("POST", `/api/v1/runs/${encodeURIComponent(cleanPathId("run id", runId))}/memory`, influence)
+  };
+  async ingestPrompt(source, prompt, opts) {
+    return this.request("POST", "/api/v1/ingest/prompt", {
+      source,
+      prompt,
+      ...opts?.sessionId ? { sessionId: opts.sessionId } : {},
+      ...opts?.metadata ? { metadata: opts.metadata } : {}
+    });
+  }
+  async savings() {
+    const path = "/api/v1/savings";
+    return requireSavingsSummary(await this.request("GET", path), "GET", path);
+  }
+  async patterns() {
+    const path = "/api/v1/patterns";
+    const body = await this.request("GET", path);
+    return requireArrayProperty(body, "patterns", "GET", path);
+  }
+  async artifacts() {
+    const path = "/api/v1/artifacts";
+    const body = await this.request("GET", path);
+    return requireArrayProperty(body, "artifacts", "GET", path);
+  }
+  async artifactDetail(id) {
+    const path = `/api/v1/artifacts/${encodeURIComponent(cleanPathId("artifact id", id))}`;
+    return requireArtifactDetailResult(await this.request("GET", path), "GET", path);
+  }
+  async runDetail(id) {
+    const path = `/api/v1/runs/${encodeURIComponent(cleanPathId("run id", id))}`;
+    return requireRunDetailResult(await this.request("GET", path), "GET", path);
+  }
+  async receipt(id) {
+    const path = `/api/v1/receipts/${encodeURIComponent(cleanPathId("receipt id", id))}`;
+    return requireReceiptResult(await this.request("GET", path), "GET", path);
+  }
+  async evidencePacket(runId) {
+    const path = `/api/v1/runs/${encodeURIComponent(cleanPathId("run id", runId))}/evidence-packet`;
+    return requireEvidencePacketResult(await this.request("GET", path), "GET", path);
+  }
+  async cacheStats() {
+    const path = "/api/v1/cache/stats";
+    const body = await this.request("GET", path);
+    return requireCacheStatsResult(body, "GET", path);
+  }
+  async learningTick() {
+    const path = "/api/v1/learning/tick";
+    return requireLearningReport(await this.request("POST", path), "POST", path);
+  }
+  async promoteArtifact(id) {
+    const path = `/api/v1/artifacts/${encodeURIComponent(cleanPathId("artifact id", id))}/promote`;
+    const body = await this.request("POST", path);
+    return requireObjectProperty(body, "artifact", "POST", path);
+  }
+  async toolCacheCheck(toolName, args, sideEffectLevel, schemaFp) {
+    try {
+      return await this.request("POST", "/api/v1/tool-cache/check", { toolName, appId: this.app, subject: this.subject, args, sideEffectLevel, schemaFp });
+    } catch {
+      return { hit: false };
+    }
+  }
+  async toolCacheStore(toolName, args, result, ttlSeconds, sideEffectLevel, schemaFp) {
+    try {
+      await this.request("POST", "/api/v1/tool-cache/store", {
+        toolName,
+        appId: this.app,
+        subject: this.subject,
+        args,
+        result,
+        ttlSeconds,
+        sideEffectLevel,
+        schemaFp
+      });
+    } catch {}
+  }
+  headers(extra) {
+    const headers = {
+      "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;
+  }
+  async request(method, path, body) {
+    let res;
+    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(method, path, res);
+  }
+  async parseJsonResponse(method, path, res) {
+    const text = await res.text();
+    if (!res.ok) {
+      throw this.toError(method, path, res, text);
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new Error(`Punk API ${method} ${path} returned non-JSON response: ${res.status} ${res.statusText}` + (text ? ` — ${text.slice(0, 500)}` : ""));
+    }
+  }
+  toError(method, path, res, text) {
+    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}` : ""));
+  }
+  toTransportError(method, path, err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return new Error(`Punk API ${method} ${path} could not reach ${this.baseUrl}: ${reason}`);
+  }
+  responseErrorMessage(text) {
+    if (!text)
+      return "";
+    let data = 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) => String(v)).join("; ")}`;
+    }
+    return message.slice(0, 500);
+  }
+  async tryTrace(runId, type, payload) {
+    try {
+      await this.trace(runId, type, payload);
+    } catch {}
+  }
+  async tryTraceDecision(runId, type, payload) {
+    try {
+      const res = await this.request("POST", "/api/v1/trace", {
+        runId,
+        type,
+        payload
+      });
+      return normalizeTraceDecision(res.decision);
+    } catch {
+      return null;
+    }
+  }
+}
+var src_default = Punk;
+export {
+  punkModelChat,
+  punkChorusChat,
+  src_default as default,
+  Punk,
+  PUNK_MODEL,
+  PUNK_CHORUS_MODEL
+};