@kingsoftcloud/agentkit-harness-node 0.0.0-stage → 0.0.2

package/src/native/model-chat-usage.mjs

@@ -0,0 +1,24 @@
+import { ProtocolError } from './model-normalize.mjs';
+
+export const CUMULATIVE_CHAT_USAGE = 'cumulative-snapshots/v1';
+export const admitChatUsagePolicy = protocol => protocol === 'openai-chat' ? CUMULATIVE_CHAT_USAGE : undefined;
+const fields = ['inputTokens', 'outputTokens', 'cachedInputTokens', 'reasoningTokens'];
+
+/** Usage reports describe a single request, never additional token deltas.
+ * Optional subdivisions may arrive late; absence never fabricates a zero or
+ * erases a known count. Generation sealing is handled separately by the stream.
+ * Legacy absence retains exact primary-counter comparison for frozen Runs. */
+export function mergeChatUsage(previous, reported, policy, finalized = false) {
+  if (policy !== undefined && policy !== CUMULATIVE_CHAT_USAGE)
+    throw new ProtocolError('invalid chat usage policy', 'request_invalid');
+  if (!previous) return { ...reported };
+  if (policy === undefined) {
+    if (previous.inputTokens !== reported.inputTokens || previous.outputTokens !== reported.outputTokens)
+      throw new ProtocolError('conflicting usage reports in one attempt', 'usage_conflict');
+    return { ...reported };
+  }
+  for (const field of fields) if (Object.hasOwn(previous, field) && Object.hasOwn(reported, field)
+    && (reported[field] < previous[field] || finalized && reported[field] !== previous[field]))
+    throw new ProtocolError('conflicting cumulative usage reports in one attempt', 'usage_conflict');
+  return { ...previous, ...reported };
+}

package/src/native/model-inline-reasoning.mjs

@@ -0,0 +1,111 @@
+// Versioned projection from ksadk.model_proxy.compat. Policy belongs to the
+// admitted Run; neither recovery nor individual requests read process.env.
+const rules = new Set(['permissive', 'openai', 'strict-openai', 'cerebras', 'groq',
+  'deepseek', 'zai', 'kspmas-gateway', 'moonshot', 'mimo']);
+const urlHints = [['kspmas', 'kspmas-gateway'], ['cerebras', 'cerebras'], ['groq', 'groq'],
+  ['deepseek', 'deepseek'], ['zai', 'zai'], ['bigmodel', 'zai'], ['glm', 'zai'],
+  ['moonshot', 'moonshot'], ['api.kimi.com', 'moonshot'], ['openai.com', 'openai']];
+const modelHints = [['deepseek', 'deepseek'], ['glm', 'zai'], ['zai', 'zai'],
+  ['bigmodel', 'zai'], ['mimo', 'mimo'], ['gpt-', 'openai']];
+const normalizeModel = value => String(value ?? '').toLowerCase().replaceAll('_', '-');
+// Python str.lstrip includes NEL/information separators and excludes BOM.
+const pythonLeftSpace = /^[\u0009-\u000d\u001c-\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]*/u;
+const startsThinking = text => text.replace(pythonLeftSpace, '').startsWith('<think>');
+
+export function admitInlineReasoningPolicy(override, { contract = 'profiled-content/v2' } = {}) {
+  if (!['profiled-content/v1', 'profiled-content/v2'].includes(contract)) throw new Error('invalid_inline_reasoning_policy');
+  const rule = typeof override === 'string' ? override.trim() : '';
+  return { contract, rule: rule ? (rules.has(rule) ? rule : 'permissive') : 'auto' };
+}
+
+export function inlineReasoningMarker(policy, binding = {}) {
+  if (!policy) return null; // Preserve existing admitted Runs byte for byte.
+  if (!['profiled-content/v1', 'profiled-content/v2'].includes(policy.contract) || (policy.rule !== 'auto' && !rules.has(policy.rule))) {
+    throw new Error('invalid_inline_reasoning_policy');
+  }
+  const rule = resolveCompatibilityRule(policy.rule, binding);
+  if (['kspmas-gateway', 'moonshot'].includes(rule)
+    && ['kimi-k2.7-code', 'kimi-k2.7-code-highspeed'].includes(String(binding.model ?? '').trim().toLowerCase())) return null;
+  return ['zai', 'kspmas-gateway'].includes(rule) ? '</think>' : null;
+}
+
+export function resolveCompatibilityRule(selected, binding = {}) {
+  if (selected !== 'auto' && !rules.has(selected)) throw new Error('invalid_provider_compatibility_policy');
+  const model = normalizeModel(binding.model), url = String(binding.baseUrl ?? '').toLowerCase();
+  return selected === 'auto'
+    ? urlHints.find(([hint]) => url.includes(hint))?.[1]
+      ?? modelHints.find(([hint]) => model.includes(hint))?.[1] ?? 'permissive'
+    : selected;
+}
+
+export function projectInlineReasoning(text, marker, policy) {
+  if (!marker) return text;
+  if (policy?.contract === 'profiled-content/v2') {
+    const projector = createInlineReasoningProjector(marker, policy);
+    return projector.push(text) + projector.seal();
+  }
+  const index = text.lastIndexOf(marker);
+  return index >= 0 ? text.slice(index + marker.length) : startsThinking(text) ? '' : text;
+}
+
+export function createInlineReasoningProjector(marker, policy) {
+  if (marker && policy?.contract === 'profiled-content/v2') return taggedPrefixProjector(marker);
+  let pending = '', released = !marker;
+  return {
+    push(text) {
+      if (released) return text;
+      pending += text;
+      const index = pending.lastIndexOf(marker);
+      if (index < 0) return '';
+      const visible = pending.slice(index + marker.length);
+      pending = ''; released = true;
+      return visible;
+    },
+    seal() {
+      if (released) return '';
+      const visible = startsThinking(pending) ? '' : pending;
+      pending = ''; released = true;
+      return visible;
+    },
+  };
+}
+
+/** Content and reasoning_content are separate wire channels. Only an explicit
+ * leading reasoning tag changes the content channel's framing. Ordinary prose
+ * is released as soon as its prefix is unambiguous; a closing tag quoted later
+ * in prose is text, not permission to retract already-published content.
+ * Once inside reasoning, retain at most a possible closing-tag suffix. */
+function taggedPrefixProjector(marker) {
+  const opening = '<think>';
+  let phase = 'prefix', pending = '';
+  return {
+    push(text) {
+      if (phase === 'text') return text;
+      pending += text;
+      if (phase === 'prefix') {
+        const prefix = pending.replace(pythonLeftSpace, '');
+        if (!prefix || opening.startsWith(prefix) || marker.startsWith(prefix)) return '';
+        if (prefix.startsWith(opening)) {
+          pending = prefix.slice(opening.length);phase = 'reasoning';
+        } else if (prefix.startsWith(marker)) {
+          const visible = prefix.slice(marker.length);pending = '';phase = 'text';return visible;
+        } else {
+          const visible = pending;pending = '';phase = 'text';return visible;
+        }
+      }
+      const end = pending.indexOf(marker);
+      if (end >= 0) {
+        const visible = pending.slice(end + marker.length);pending = '';phase = 'text';return visible;
+      }
+      let suffix = Math.min(pending.length, marker.length - 1);
+      while (suffix && !marker.startsWith(pending.slice(-suffix))) suffix--;
+      pending = suffix ? pending.slice(-suffix) : '';
+      return '';
+    },
+    seal() {
+      // Incomplete tag prefixes and unfinished reasoning cannot become prose.
+      const visible = phase === 'prefix' && !pending.replace(pythonLeftSpace, '') ? pending : '';
+      pending = '';phase = 'text';return visible;
+    },
+  };
+}

package/src/native/model-media.mjs

@@ -0,0 +1,174 @@
+// Media validation and projection for the native model adapter.
+//
+// The host supplies image observations as message.media blocks. The adapter
+// validates their shape and byte budget and projects them onto each wire
+// without reading files or fetching remote URLs: a bare path or file:// URL is
+// rejected, only explicit http(s) URLs (without userinfo credentials) and
+// supported image data URLs are admitted.
+//
+// The byte budget is request.maxInlineImageBytes (the kernel passes
+// configuration.limits.maxInlineImageBytes). When absent, a 40 MiB safe default
+// is used. Like the reference request-media policy, this budget counts all
+// encoded inline image URLs in the dispatch view, including their prefixes.
+
+import { createHash } from 'node:crypto';
+
+const IMAGE_KINDS = new Set(['png', 'jpeg', 'webp', 'gif']);
+const DEFAULT_MAX_IMAGE_BYTES = 40 * 1024 * 1024;
+
+class MediaError extends Error {
+  constructor(message) { super(message); this.name = 'MediaError'; }
+}
+
+// Validate one host media block and return it normalized to the OpenAI
+// image_url shape: { type: 'image_url', image_url: { url, detail } }. Throws
+// on a local path, file:// URL, userinfo URL, unsupported data URL, bad base64,
+// or an encoded inline URL over maxInlineImageBytes.
+export function validateMediaBlock(block, maxInlineImageBytes = DEFAULT_MAX_IMAGE_BYTES) {
+  if (!block || typeof block !== 'object' || Array.isArray(block)) {
+    throw new MediaError('media block must be an object');
+  }
+  if (block.type !== 'image_url') {
+    throw new MediaError('unsupported media block type');
+  }
+  const image = block.image_url;
+  if (!image || typeof image !== 'object' || Array.isArray(image)) {
+    throw new MediaError('image_url block requires an image_url object');
+  }
+  const url = String(image.url ?? '');
+  if (!url) throw new MediaError('image block requires a url');
+  const detail = image.detail == null ? 'auto' : String(image.detail);
+  if (!['auto', 'low', 'high'].includes(detail)) {
+    throw new MediaError('image detail must be auto, low or high');
+  }
+  validateImageUrl(url, maxInlineImageBytes);
+  return { type: 'image_url', image_url: { url, detail } };
+}
+
+function validateImageUrl(url, maxInlineImageBytes) {
+  if (url.startsWith('data:')) {
+    const [prefix, separator, payload] = partition(url, ',');
+    const kind = matchDataImage(prefix);
+    if (!kind || !separator || !payload) {
+      throw new MediaError('image data URL requires a supported image and base64 content');
+    }
+    // Strict base64: only the standard alphabet, length a multiple of 4, with
+    // 0-2 padding chars. Rejecting malformed padding avoids accepting a
+    // truncated payload that decodes to fewer bytes than the host expected.
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(payload) || payload.length % 4 !== 0) {
+      throw new MediaError('invalid image base64 content');
+    }
+    if (Buffer.byteLength(url, 'utf8') > maxInlineImageBytes) {
+      throw new MediaError('image exceeds maxInlineImageBytes');
+    }
+    return;
+  }
+  let parsed;
+  try { parsed = new URL(url); } catch { throw new MediaError('image URL must be an explicit HTTP URL or image data URL'); }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new MediaError('image URL must be an explicit HTTP URL or image data URL');
+  }
+  // An image URL carrying userinfo credentials would send them to the provider
+  // in the request; reject it so credentials never enter the model wire.
+  if (parsed.username || parsed.password) {
+    throw new MediaError('image URL must not carry userinfo credentials');
+  }
+}
+
+function matchDataImage(prefix) {
+  for (const kind of IMAGE_KINDS) {
+    if (prefix === `data:image/${kind};base64`) return kind;
+  }
+  return null;
+}
+
+function partition(s, sep) {
+  const i = s.indexOf(sep);
+  if (i === -1) return [s, '', ''];
+  return [s.slice(0, i), sep, s.slice(i + sep.length)];
+}
+
+// This is a disposable dispatch projection. The canonical transcript and its
+// tool receipts remain unchanged; omitted historical pixels cannot authorize
+// a repeated side effect. The latest actual user input is protected in full.
+export function projectRequestMedia(request) {
+  const limit = request.maxInlineImageBytes ?? DEFAULT_MAX_IMAGE_BYTES;
+  if (!Number.isSafeInteger(limit) || limit < 0) throw new MediaError('invalid inline image budget');
+  const messages = (request.messages || []).map((message) => {
+    if (message.media == null) return { ...message };
+    if (!Array.isArray(message.media)) throw new MediaError('media must be an array');
+    const media = message.media.map((block) => validateMediaBlock(block, Infinity));
+    if (media.length && message.role !== 'user' && message.role !== 'tool') throw new MediaError('image observations require user or tool content');
+    return { ...message, media };
+  });
+  if (request.profile?.supportsImages === false) {
+    for (const message of messages) if (message.media?.length) {
+      delete message.providerReplay;
+      message.content = `${message.content || ''}\n${JSON.stringify({
+        type: 'agentkit.request-media-omission/v1', reason: 'model_does_not_support_images',
+        status: 'not_sent_in_this_request',
+        observation: 'Image pixels were not sent to this model. Do not claim visual inspection or repeat side effects for missing pixels.',
+      })}`;
+      message.media = [];
+    }
+  }
+  const actualUser = messages.findLastIndex(message => message.role === 'user' && !message.history
+    && (message.kind == null || ['user_input', 'guidance', 'steering'].includes(message.kind)
+      || message.kind === 'host_input' && message.persistent === true));
+  const inline = [];
+  for (const [i, message] of messages.entries()) {
+    for (const [j, block] of (message.media || []).entries()) {
+      if (block.image_url.url.startsWith('data:')) inline.push({ i, j, bytes: Buffer.byteLength(block.image_url.url, 'utf8') });
+    }
+  }
+  if (inline.reduce((sum, item) => sum + item.bytes, 0) <= limit) return { ...request, messages };
+  const protectedBytes = inline.filter((item) => item.i === actualUser).reduce((sum, item) => sum + item.bytes, 0);
+  let remaining = limit - protectedBytes;
+  if (remaining < 0) throw new MediaError('request_current_media_over_budget');
+  const retained = new Set();
+  for (const item of inline.toReversed()) {
+    if (item.i === actualUser) retained.add(`${item.i}:${item.j}`);
+    else if (item.bytes <= remaining) {
+      retained.add(`${item.i}:${item.j}`);
+      remaining -= item.bytes;
+    }
+  }
+  for (const item of inline) {
+    if (retained.has(`${item.i}:${item.j}`)) continue;
+    const message = messages[item.i];
+    const block = message.media[item.j];
+    const marker = {
+      type: 'agentkit.request-media-omission/v1',
+      mediaDigest: createHash('sha256').update(JSON.stringify(block)).digest('hex'),
+      status: 'not_sent_in_this_request', reason: 'inline_image_budget',
+      observation: 'Historical image omitted from this model request. Use the textual receipt; do not claim to have seen the image or repeat executed side effects because its pixels were omitted.',
+    };
+    message.content = `${message.content || ''}\n${JSON.stringify(marker)}`;
+    message.media[item.j] = null;
+    delete message.providerReplay;
+  }
+  for (const message of messages) if (message.media) message.media = message.media.filter(Boolean);
+  return { ...request, messages };
+}
+
+// Project validated media blocks onto the OpenAI chat wire (unchanged shape).
+export function projectMediaOpenAI(blocks) {
+  return blocks.map((b) => ({ type: 'image_url', image_url: { url: b.image_url.url, detail: b.image_url.detail } }));
+}
+
+// Project validated media blocks onto the Anthropic messages wire. http(s)
+// URLs become {type:'image', source:{type:'url', url}}; data URLs become a
+// base64 source with the media type derived from the data URL prefix.
+export function projectMediaAnthropic(blocks) {
+  return blocks.map((b) => {
+    const url = b.image_url.url;
+    if (url.startsWith('data:')) {
+      const [prefix, , payload] = partition(url, ',');
+      const kind = matchDataImage(prefix);
+      return { type: 'image', source: { type: 'base64', media_type: `image/${kind}`, data: payload } };
+    }
+    return { type: 'image', source: { type: 'url', url } };
+  });
+}
+
+export { MediaError, DEFAULT_MAX_IMAGE_BYTES };

package/src/native/model-normalize.mjs

@@ -0,0 +1,228 @@
+// Shared, protocol-neutral normalization for the native model adapter.
+//
+// The host kernel owns retry/backoff policy and call budgets. This module only
+// classifies one sealed attempt: it maps a provider finish reason, visible text
+// and an assembled tool batch to the ModelResult.kind contract. It never invents
+// a finish from partial transport, and never authorizes tool execution.
+//
+// Provider error bodies, credentials and exception text never cross this
+// boundary: only the sanitized failureKind string leaves the adapter.
+
+export const emptyUsage = () => ({
+  inputTokens: 0, outputTokens: 0, modelCalls: 0, toolCalls: 0, cost: 0,
+});
+
+// Canonical finish-reason sets, mirroring ksadk.harness.native.model. A missing
+// finish reason stays unknown; a stream that never observed protocol completion
+// is retryable, never a silent final.
+const USER_ABORTS = new Set(['user_abort', 'canceled', 'cancelled']);
+const POLICY_ABORTS = new Set(['policy_abort', 'content_filter']);
+const CONTEXT_LIMITS = new Set(['context_overflow', 'context_length_exceeded']);
+const OUTPUT_LIMITS = new Set([
+  'output_limit', 'length', 'max_tokens', 'max_output_tokens', 'incomplete',
+  // A completed generation can fill input + output capacity without its input
+  // having been rejected. Use bounded output continuation;
+  // real input-overflow errors still take the separate context-overflow path.
+  'model_context_window_exceeded',
+]);
+const TOOL_FINISHES = new Set(['tool_calls', 'tool_use']);
+const COMPLETE_FINISHES = new Set([
+  null, 'stop', 'end_turn', 'completed', 'final_candidate', ...TOOL_FINISHES,
+]);
+
+/**
+ * Classify one sealed attempt into a ModelResult.kind with validated tool calls.
+ *
+ * `streamComplete` means the adapter observed protocol completion (a real
+ * terminal: [DONE], message_stop, or a buffered 2xx body), not just socket EOF.
+ * Partial tool payloads never reach toolCalls; the caller keeps raw evidence for
+ * repair separately. Tool calls with undecodable argument bytes keep their
+ * identity but carry arguments={} and the contract's `wireArgumentsInvalid`
+ * flag so the kernel can emit one bounded tool-error receipt without executing.
+ */
+export function normalizeResponse({
+  text = '', toolCalls = [], finishReason = null, streamComplete = true,
+} = {}) {
+  const out = (kind, calls = []) => ({ kind, text, toolCalls: calls });
+
+  if (USER_ABORTS.has(finishReason)) return out('user_abort');
+  if (POLICY_ABORTS.has(finishReason)) return out('policy_abort');
+  if (CONTEXT_LIMITS.has(finishReason)) return out('context_overflow');
+  if (finishReason === 'provider_terminal_error') return out('provider_terminal_error');
+  if (!streamComplete || finishReason === 'provider_retryable_error') {
+    return out('provider_retryable_error');
+  }
+  if (OUTPUT_LIMITS.has(finishReason)) return { ...out('output_limit'), textCommitVersion: 'provider-finished-text/v1',
+    outputBoundary: toolCalls.length ? 'tool-call/v1' : text.trim() ? 'assistant-text/v1' : 'no-visible-output/v1' };
+  if (finishReason === 'malformed_tool_call') return out('malformed_tool_call');
+  if (finishReason === 'empty_response') return out('empty_response');
+  if (!COMPLETE_FINISHES.has(finishReason)) return out('provider_terminal_error');
+
+  let calls;
+  try {
+    calls = toolCalls.map(validateToolCall);
+  } catch {
+    return out('malformed_tool_call');
+  }
+  if (calls.length) {
+    const ids = calls.map((c) => c.callId);
+    if (new Set(ids).size !== ids.length) return out('malformed_tool_call');
+    return out('tool_calls', calls);
+  }
+  if (TOOL_FINISHES.has(finishReason)) return out('malformed_tool_call');
+  return out(text.trim() ? 'final_candidate' : 'empty_response');
+}
+
+// Validate a single assembled tool call. Throws on a malformed identity or
+// shape; a call with wireArgumentsInvalid keeps arguments={} and passes.
+function validateToolCall(call) {
+  if (!call || typeof call !== 'object') throw new Error('invalid tool call');
+  const callId = String(call.callId ?? '');
+  const name = String(call.name ?? '');
+  if (!callId.trim() || !name.trim()) throw new Error('tool call identity blank');
+  const arguments_ = call.wireArgumentsInvalid ? {} : call.arguments;
+  if (arguments_ == null || typeof arguments_ !== 'object' || Array.isArray(arguments_)) {
+    throw new Error('tool arguments must be an object');
+  }
+  return { callId, name, arguments: arguments_, ...(call.wireArgumentsInvalid ? { wireArgumentsInvalid: true } : {}) };
+}
+
+// Parse the OpenAI chat usage envelope. Both primary counters must be present;
+// an incomplete report stays unknown, never fabricated zero usage. All supplied
+// fields are validated even in a partial report. Optional subdivisions are
+// retained by source meaning: prompt_tokens_details.cached_tokens ->
+// cachedInputTokens, completion_tokens_details.reasoning_tokens -> reasoningTokens.
+export function parseOpenAIUsage(value) {
+  if (value == null) return null;
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new ProtocolError('invalid usage report', 'usage_invalid');
+  }
+  for (const field of ['prompt_tokens', 'completion_tokens', 'total_tokens']) {
+    if (Object.hasOwn(value, field)) toNonNegInt(value[field], field);
+  }
+  const details = value.prompt_tokens_details;
+  const completionDetails = value.completion_tokens_details;
+  if (details != null && (typeof details !== 'object' || Array.isArray(details))) {
+    throw new ProtocolError('invalid usage details', 'usage_invalid');
+  }
+  if (completionDetails != null && (typeof completionDetails !== 'object' || Array.isArray(completionDetails))) {
+    throw new ProtocolError('invalid usage details', 'usage_invalid');
+  }
+  const cached = details && Object.hasOwn(details, 'cached_tokens')
+    ? toNonNegInt(details.cached_tokens, 'cached_tokens') : undefined;
+  const reasoning = completionDetails && Object.hasOwn(completionDetails, 'reasoning_tokens')
+    ? toNonNegInt(completionDetails.reasoning_tokens, 'reasoning_tokens') : undefined;
+  if (!Object.hasOwn(value, 'prompt_tokens') || !Object.hasOwn(value, 'completion_tokens')) return null;
+  const usage = { ...emptyUsage(), inputTokens: value.prompt_tokens, outputTokens: value.completion_tokens };
+  if (cached != null) usage.cachedInputTokens = cached;
+  if (reasoning != null) usage.reasoningTokens = reasoning;
+  return usage;
+}
+
+// Parse an Anthropic usage fragment (message_start or message_delta). Counters
+// are accumulated across the stream. Cache fields are retained by source
+// meaning: cache_read_input_tokens -> cachedInputTokens (tokens served from the
+// cache). reasoning_tokens, when a provider reports it, -> reasoningTokens.
+export function parseAnthropicUsageFragment(value) {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new ProtocolError('invalid anthropic usage', 'usage_invalid');
+  }
+  const fragment = {};
+  if (Object.hasOwn(value, 'input_tokens')) {
+    fragment.inputTokens = toNonNegInt(value.input_tokens, 'input_tokens');
+  }
+  if (Object.hasOwn(value, 'output_tokens')) {
+    fragment.outputTokens = toNonNegInt(value.output_tokens, 'output_tokens');
+  }
+  if (value.cache_read_input_tokens != null) {
+    fragment.cachedInputTokens = toNonNegInt(value.cache_read_input_tokens, 'cache_read_input_tokens');
+  }
+  if (value.cache_creation_input_tokens != null) {
+    fragment.cacheCreationInputTokens = toNonNegInt(value.cache_creation_input_tokens, 'cache_creation_input_tokens');
+  }
+  if (value.reasoning_tokens != null) {
+    fragment.reasoningTokens = toNonNegInt(value.reasoning_tokens, 'reasoning_tokens');
+  }
+  return fragment;
+}
+
+// Build a sealed Usage plus usageReported flag. When the provider reported
+// usage, usageReported is true and the counters are the provider's (including
+// cached/reasoning). When it did not, usage is emptyUsage() and usageReported
+// is false — the kernel records providerUsageIncomplete so a zero counter is
+// never mistaken for known free usage.
+export function sealUsage(reportedUsage) {
+  if (reportedUsage == null) return { usage: emptyUsage(), usageReported: false };
+  return { usage: reportedUsage, usageReported: true };
+}
+
+function toNonNegInt(value, field) {
+  // The kernel's addUsage validates Number.isSafeInteger for token counters;
+  // reject NaN/booleans/strings/unsafe integers so a bad report is a protocol
+  // error here, not an invalid_usage crash in the kernel.
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+    throw new ProtocolError(`invalid ${field} counter`, 'usage_invalid');
+  }
+  return value;
+}
+
+// Host generation options may select a smaller output budget, but cannot
+// increase the limit pinned in the run configuration.
+export function boundOutputTokens(value, profileLimit) {
+  if (!Number.isSafeInteger(profileLimit) || profileLimit <= 0) throw new ProtocolError('invalid pinned output limit');
+  if (value === undefined) return profileLimit;
+  if (!Number.isSafeInteger(value) || value <= 0) throw new ProtocolError('invalid output limit');
+  return Math.min(value, profileLimit);
+}
+
+// Parse a Retry-After header into milliseconds. Accepts delta-seconds or an
+// HTTP-date. Non-finite, negative or malformed values yield null (the kernel
+// applies its own cooldown; a bad header is not a scheduler instruction).
+export function parseRetryAfterMs(headerValue) {
+  if (headerValue == null || headerValue === '') return null;
+  const trimmed = String(headerValue).trim();
+  if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1000);
+    return null;
+  }
+  const parsed = Date.parse(trimmed);
+  if (Number.isNaN(parsed)) return null;
+  const delta = parsed - Date.now();
+  return Number.isFinite(delta) && delta >= 0 ? Math.round(delta) : null;
+}
+
+// Typed protocol error: a fixed, credential-free classification. The adapter
+// translates these to provider_terminal_error with failureKind 'invalid_response'
+// (or retryable for transport/idle). Provider bytes never enter the message.
+export class ProtocolError extends Error {
+  constructor(message, code = 'protocol_invalid') {
+    super(message);
+    this.name = 'ProtocolError';
+    this.code = code;
+  }
+}
+
+// Resolve a request URL from the host binding's baseUrl and a wire path suffix.
+// If baseUrl already ends with the suffix path, it is used as-is; otherwise the
+// suffix is appended. Trailing slashes on baseUrl are stripped first. This lets
+// the host pass either an API root (e.g. https://host/v1) or a full endpoint.
+export function resolveUrl(baseUrl, suffix) {
+  const base = String(baseUrl).replace(/\/+$/, '');
+  if (!base) throw new ProtocolError('binding baseUrl is empty');
+  if (base.endsWith('/' + suffix) || base === suffix) return base;
+  return base + '/' + suffix;
+}
+
+// Sanitize an arbitrary thrown value into a safe, non-leaking kind string plus
+// message. Exception text from host hooks or transports may include credentials,
+// so only a stable failureKind leaves the adapter; the original text is dropped.
+export function sanitizeFailureKind(error, fallback = 'host_error') {
+  if (error == null) return fallback;
+  if (error instanceof DOMException) {
+    if (error.name === 'TimeoutError') return 'request_timeout';
+    if (error.name === 'AbortError') return 'request_timeout';
+  }
+  if (error instanceof TypeError) return 'network_error';
+  return fallback;
+}