tinker-agent 1.0.65

package/src/model/model-context-profile.ts

@@ -0,0 +1,134 @@
+export const TOKEN_K = 1_024;
+export const PRODUCT_MAX_OUTPUT_TOKENS = 128 * TOKEN_K;
+export const CONTEXT_PRESSURE_TRIGGER_RATIO = 0.8 as const;
+
+export type ModelContextProfile = {
+  contextWindowTokens: number;
+  maxSupportedOutputTokens: number;
+};
+
+export type ModelContextBudget = ModelContextProfile & {
+  requestMaxOutputTokens: number;
+  inputBudgetTokens: number;
+  triggerRatio: typeof CONTEXT_PRESSURE_TRIGGER_RATIO;
+  triggerTokens: number;
+};
+
+export function readModelContextProfileFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): ModelContextProfile {
+  return createModelContextProfile({
+    contextWindowTokens: parseRequiredTokenCount(
+      env.TINKER_CONTEXT_WINDOW_TOKENS,
+      "TINKER_CONTEXT_WINDOW_TOKENS",
+    ),
+    maxSupportedOutputTokens: parseRequiredTokenCount(
+      env.TINKER_MAX_SUPPORTED_OUTPUT_TOKENS,
+      "TINKER_MAX_SUPPORTED_OUTPUT_TOKENS",
+    ),
+  });
+}
+
+export function createModelContextProfile(
+  input: ModelContextProfile,
+): ModelContextProfile {
+  requirePositiveSafeInteger(
+    input.contextWindowTokens,
+    "contextWindowTokens",
+    input.contextWindowTokens,
+  );
+  requirePositiveSafeInteger(
+    input.maxSupportedOutputTokens,
+    "maxSupportedOutputTokens",
+    input.maxSupportedOutputTokens,
+  );
+  if (input.maxSupportedOutputTokens > input.contextWindowTokens) {
+    throw new Error(
+      `maxSupportedOutputTokens must not exceed contextWindowTokens; received ${input.maxSupportedOutputTokens} > ${input.contextWindowTokens}.`,
+    );
+  }
+
+  return { ...input };
+}
+
+export function deriveModelContextBudget(
+  profileInput: ModelContextProfile,
+): ModelContextBudget {
+  const profile = createModelContextProfile(profileInput);
+  const requestMaxOutputTokens = Math.min(
+    PRODUCT_MAX_OUTPUT_TOKENS,
+    profile.maxSupportedOutputTokens,
+  );
+  if (requestMaxOutputTokens >= profile.contextWindowTokens) {
+    throw new Error(
+      `Derived requestMaxOutputTokens must be smaller than contextWindowTokens; received ${requestMaxOutputTokens} >= ${profile.contextWindowTokens}.`,
+    );
+  }
+
+  const inputBudgetTokens = profile.contextWindowTokens - requestMaxOutputTokens;
+  if (inputBudgetTokens <= 0) {
+    throw new Error(
+      `Derived inputBudgetTokens must be positive; received ${inputBudgetTokens}.`,
+    );
+  }
+
+  const triggerTokens = Math.floor(inputBudgetTokens * CONTEXT_PRESSURE_TRIGGER_RATIO);
+  if (triggerTokens <= 0 || triggerTokens >= inputBudgetTokens) {
+    throw new Error(
+      `Derived triggerTokens must be between 0 and inputBudgetTokens; received ${triggerTokens} for budget ${inputBudgetTokens}.`,
+    );
+  }
+
+  return {
+    ...profile,
+    requestMaxOutputTokens,
+    inputBudgetTokens,
+    triggerRatio: CONTEXT_PRESSURE_TRIGGER_RATIO,
+    triggerTokens,
+  };
+}
+
+export function assertMatchingContextBudget(
+  profile: ModelContextProfile,
+  budget: ModelContextBudget,
+): void {
+  const expected = deriveModelContextBudget(profile);
+  for (const key of Object.keys(expected) as Array<keyof ModelContextBudget>) {
+    if (budget[key] !== expected[key]) {
+      throw new Error(
+        `Model context budget ${key} must be ${expected[key]}; received ${budget[key]}.`,
+      );
+    }
+  }
+}
+
+function parseRequiredTokenCount(value: string | undefined, name: string): number {
+  if (value === undefined || value.trim() === "") {
+    throw new Error(`${name} is required; received ${displayValue(value)}.`);
+  }
+  if (!/^\d+$/.test(value)) {
+    throw new Error(
+      `${name} must be a positive safe integer token count; received ${displayValue(value)}.`,
+    );
+  }
+
+  const parsed = Number(value);
+  requirePositiveSafeInteger(parsed, name, value);
+  return parsed;
+}
+
+function requirePositiveSafeInteger(
+  value: number,
+  name: string,
+  received: unknown,
+): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(
+      `${name} must be a positive safe integer token count; received ${displayValue(received)}.`,
+    );
+  }
+}
+
+function displayValue(value: unknown): string {
+  return value === undefined ? "undefined" : JSON.stringify(value);
+}

package/src/model/model-request-preflight.ts

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import type { ModelContextBudget } from "./model-context-profile";
+
+export type ContextUsageSource =
+  | "estimated_full"
+  | "provider_measured"
+  | "measured_plus_estimated_delta";
+
+export type ContextPressure = "normal" | "triggered" | "blocked";
+
+export class ContextBudgetExceededError extends Error {
+  readonly projectedInputTokens: number;
+  readonly inputBudgetTokens: number;
+  readonly triggerTokens: number;
+  readonly source: ContextUsageSource;
+
+  constructor(
+    input: {
+      projectedInputTokens: number;
+      source: ContextUsageSource;
+    } & Pick<
+      ModelContextBudget,
+      | "contextWindowTokens"
+      | "inputBudgetTokens"
+      | "requestMaxOutputTokens"
+      | "triggerTokens"
+    >,
+  ) {
+    super(
+      `Model request blocked before provider call: projected input ${formatTokenCount(input.projectedInputTokens)} exceeds Tinker input budget ${formatTokenCount(input.inputBudgetTokens)} (model window ${formatTokenCount(input.contextWindowTokens)}, reserved output ${formatTokenCount(input.requestMaxOutputTokens)}).`,
+    );
+    this.name = "ContextBudgetExceededError";
+    this.projectedInputTokens = input.projectedInputTokens;
+    this.inputBudgetTokens = input.inputBudgetTokens;
+    this.triggerTokens = input.triggerTokens;
+    this.source = input.source;
+  }
+}
+
+export function contextPressure(
+  usedInputTokens: number,
+  budget: Pick<ModelContextBudget, "inputBudgetTokens" | "triggerTokens">,
+): ContextPressure {
+  if (usedInputTokens > budget.inputBudgetTokens) {
+    return "blocked";
+  }
+  return usedInputTokens >= budget.triggerTokens ? "triggered" : "normal";
+}
+
+export function assertContextBudget(
+  input: {
+    usedInputTokens: number;
+    source: ContextUsageSource;
+  } & Pick<
+    ModelContextBudget,
+    | "contextWindowTokens"
+    | "inputBudgetTokens"
+    | "requestMaxOutputTokens"
+    | "triggerTokens"
+  >,
+): void {
+  if (input.usedInputTokens <= input.inputBudgetTokens) {
+    return;
+  }
+  throw new ContextBudgetExceededError({
+    projectedInputTokens: input.usedInputTokens,
+    source: input.source,
+    contextWindowTokens: input.contextWindowTokens,
+    inputBudgetTokens: input.inputBudgetTokens,
+    requestMaxOutputTokens: input.requestMaxOutputTokens,
+    triggerTokens: input.triggerTokens,
+  });
+}
+
+export function stableJsonStringify(value: unknown): string {
+  return JSON.stringify(canonicalJsonValue(value));
+}
+
+export function canonicalJsonValue(value: unknown): unknown {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(`Cannot serialize a non-finite JSON number: ${value}.`);
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => canonicalJsonValue(entry));
+  }
+  if (typeof value !== "object" || value === undefined) {
+    throw new Error(`Cannot serialize non-JSON value of type ${typeof value}.`);
+  }
+
+  const record = value as Record<string, unknown>;
+  const canonical: Record<string, unknown> = {};
+  for (const key of Object.keys(record).sort()) {
+    const entry = record[key];
+    if (entry !== undefined) {
+      canonical[key] = canonicalJsonValue(entry);
+    }
+  }
+  return canonical;
+}
+
+export function sha256(value: string): string {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+function formatTokenCount(tokens: number): string {
+  const million = 1_024 * 1_024;
+  if (tokens >= million && tokens % million === 0) {
+    return `${tokens / million}M`;
+  }
+  if (tokens >= 1_024 && tokens % 1_024 === 0) {
+    return `${tokens / 1_024}K`;
+  }
+  return tokens.toLocaleString("en-US");
+}

package/src/model/openai-chat-mapping.ts

@@ -0,0 +1,444 @@
+import type { AgentMessage, IterationIdentity, ToolCall } from "../agent/types";
+import type { RuntimeSessionContext } from "../agent/runtime-session";
+import type { ModelRequestOutput, ModelUsage } from "./model-client";
+import type { ToolDefinition } from "../tools/types";
+import type {
+  ChatCompletionAssistantMessageParam,
+  ChatCompletionMessageFunctionToolCall,
+  ChatCompletionMessageParam,
+  ChatCompletionTool,
+} from "openai/resources/chat/completions";
+
+type DeepSeekAssistantMessageParam = ChatCompletionAssistantMessageParam & {
+  reasoning_content?: string | null;
+};
+
+export type OpenAIChatMessageMappingOptions = {
+  includeReasoningContent?: boolean;
+};
+
+export function toOpenAIChatMessages(
+  messages: readonly AgentMessage[],
+  options: OpenAIChatMessageMappingOptions = {},
+): ChatCompletionMessageParam[] {
+  return messages.map((message): ChatCompletionMessageParam => {
+    if (message.role === "assistant") {
+      const assistantMessage: DeepSeekAssistantMessageParam = {
+        role: "assistant",
+        content: message.content ?? null,
+        tool_calls: message.toolCalls?.map(toOpenAIToolCall),
+      };
+
+      if (
+        options.includeReasoningContent === true &&
+        message.reasoningContent !== undefined
+      ) {
+        assistantMessage.reasoning_content = message.reasoningContent;
+      }
+
+      return assistantMessage;
+    }
+
+    if (message.role === "tool") {
+      return {
+        role: "tool",
+        tool_call_id: message.providerToolCallId,
+        content: message.content,
+      };
+    }
+
+    return message;
+  });
+}
+
+export function toOpenAIChatTools(
+  tools: readonly ToolDefinition[],
+): ChatCompletionTool[] {
+  return tools.map((tool) => ({
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    },
+  }));
+}
+
+export function fromOpenAIChatCompletion(
+  response: unknown,
+  options: {
+    identity?: {
+      iteration: IterationIdentity;
+      runtimeSession: RuntimeSessionContext;
+    };
+    provider: string;
+    model: string;
+  },
+): ModelRequestOutput {
+  const completion = requireRecord(response, "response", options);
+  if (!Array.isArray(completion.choices) || completion.choices.length === 0) {
+    throw providerResponseError(options, "choices[0]", "is missing");
+  }
+
+  const choice = requireRecord(completion.choices[0], "choices[0]", options);
+  const message = requireRecord(choice.message, "choices[0].message", options);
+  if (message.role !== "assistant") {
+    throw providerResponseError(
+      options,
+      "choices[0].message.role",
+      'must be "assistant"',
+    );
+  }
+  if (message.tool_calls !== undefined && !Array.isArray(message.tool_calls)) {
+    throw providerResponseError(
+      options,
+      "choices[0].message.tool_calls",
+      "must be an array",
+    );
+  }
+  const rawToolCalls = message.tool_calls ?? [];
+  const content = normalizeContent(
+    message.content,
+    "choices[0].message.content",
+    options,
+  );
+  if ((content === null || content.trim() === "") && rawToolCalls.length === 0) {
+    throw providerResponseError(
+      options,
+      "choices[0].message",
+      "has neither non-empty text nor tool calls",
+    );
+  }
+
+  const finishReason = optionalString(
+    choice.finish_reason,
+    "choices[0].finish_reason",
+    options,
+  );
+  const usage = parseUsage(completion.usage, options);
+
+  if (rawToolCalls.length > 0 && options.identity === undefined) {
+    throw providerResponseError(
+      options,
+      "choices[0].message.tool_calls",
+      "requires an iteration identity context",
+    );
+  }
+  const toolCalls = rawToolCalls.map((raw, index) =>
+    parseToolCall(raw, index, options.identity!, options),
+  );
+
+  return {
+    message: {
+      role: "assistant",
+      content,
+      reasoningContent: normalizeContent(
+        message.reasoning_content,
+        "choices[0].message.reasoning_content",
+        options,
+      ),
+      toolCalls: toolCalls.length === 0 ? undefined : toolCalls,
+    },
+    finishReason,
+    usage,
+    rawResponse: response,
+  };
+}
+
+function toOpenAIToolCall(call: ToolCall): ChatCompletionMessageFunctionToolCall {
+  return {
+    id: call.providerToolCallId,
+    type: "function",
+    function: {
+      name: call.name,
+      arguments:
+        call.rawArgs ??
+        (typeof call.args === "string" ? call.args : JSON.stringify(call.args)),
+    },
+  };
+}
+
+function parseToolCall(
+  raw: unknown,
+  index: number,
+  context: {
+    iteration: IterationIdentity;
+    runtimeSession: RuntimeSessionContext;
+  },
+  options: { provider: string; model: string },
+): ToolCall {
+  const path = `choices[0].message.tool_calls[${index}]`;
+  const record = requireRecord(raw, path, options);
+  if (record.type !== "function") {
+    throw providerResponseError(options, `${path}.type`, 'must be "function"');
+  }
+  const providerToolCallId = requireNonEmptyString(record.id, `${path}.id`, options);
+  const fn = requireRecord(record.function, `${path}.function`, options);
+  const name = requireNonEmptyString(fn.name, `${path}.function.name`, options);
+  const rawArgs = requireString(fn.arguments, `${path}.function.arguments`, options);
+  let args: unknown = {};
+  let argsParseError: string | undefined;
+
+  if (rawArgs.trim() !== "") {
+    try {
+      args = JSON.parse(rawArgs);
+    } catch (error) {
+      argsParseError = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  return {
+    ...context.runtimeSession.createToolCall(context.iteration, index + 1),
+    providerToolCallId,
+    name,
+    args,
+    rawArgs,
+    argsParseError,
+  };
+}
+
+function normalizeContent(
+  content: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): string | null {
+  if (content === null || content === undefined) {
+    return null;
+  }
+
+  if (typeof content === "string") {
+    return content;
+  }
+
+  throw providerResponseError(options, path, "must be a string or null");
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function requireRecord(
+  value: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): Record<string, unknown> {
+  const record = asRecord(value);
+  if (Object.keys(record).length === 0) {
+    throw providerResponseError(options, path, "must be a non-empty object");
+  }
+
+  return record;
+}
+
+function requireNonEmptyString(
+  value: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw providerResponseError(options, path, "must be a non-empty string");
+  }
+
+  return value;
+}
+
+function requireString(
+  value: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): string {
+  if (typeof value !== "string") {
+    throw providerResponseError(options, path, "must be a string");
+  }
+  return value;
+}
+
+function optionalString(
+  value: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): string | undefined {
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+  return requireString(value, path, options);
+}
+
+function parseUsage(
+  value: unknown,
+  options: { provider: string; model: string },
+): ModelUsage {
+  if (value === undefined || value === null) {
+    throw providerResponseError(options, "usage", "is required");
+  }
+
+  const usage = requireRecord(value, "usage", options);
+  const promptTokens = requireTokenCount(
+    usage.prompt_tokens,
+    "usage.prompt_tokens",
+    options,
+  );
+  const completionTokens = requireTokenCount(
+    usage.completion_tokens,
+    "usage.completion_tokens",
+    options,
+  );
+  const totalTokens = requireTokenCount(
+    usage.total_tokens,
+    "usage.total_tokens",
+    options,
+  );
+  if (totalTokens !== promptTokens + completionTokens) {
+    throw providerResponseError(
+      options,
+      "usage.total_tokens",
+      `must equal usage.prompt_tokens + usage.completion_tokens (${promptTokens + completionTokens})`,
+    );
+  }
+
+  const directHit = optionalTokenCount(
+    usage.prompt_cache_hit_tokens,
+    "usage.prompt_cache_hit_tokens",
+    options,
+  );
+  const directMiss = optionalTokenCount(
+    usage.prompt_cache_miss_tokens,
+    "usage.prompt_cache_miss_tokens",
+    options,
+  );
+  if ((directHit === undefined) !== (directMiss === undefined)) {
+    throw providerResponseError(
+      options,
+      "usage.prompt_cache_hit_tokens",
+      "and usage.prompt_cache_miss_tokens must be provided together",
+    );
+  }
+
+  const cachedTokens = parseNestedTokenCount(
+    usage.prompt_tokens_details,
+    "usage.prompt_tokens_details",
+    "cached_tokens",
+    options,
+  );
+  const detailHit = cachedTokens;
+  const detailMiss =
+    cachedTokens === undefined ? undefined : promptTokens - cachedTokens;
+  if (detailMiss !== undefined && detailMiss < 0) {
+    throw providerResponseError(
+      options,
+      "usage.prompt_tokens_details.cached_tokens",
+      "must not exceed usage.prompt_tokens",
+    );
+  }
+  if (
+    directHit !== undefined &&
+    (directHit !== detailHit || directMiss !== detailMiss) &&
+    detailHit !== undefined
+  ) {
+    throw providerResponseError(
+      options,
+      "usage.prompt_cache_hit_tokens",
+      "conflicts with usage.prompt_tokens_details.cached_tokens",
+    );
+  }
+
+  const promptCacheHitTokens = directHit ?? detailHit;
+  const promptCacheMissTokens = directMiss ?? detailMiss;
+  if (
+    promptCacheHitTokens !== undefined &&
+    promptCacheMissTokens !== undefined &&
+    promptCacheHitTokens + promptCacheMissTokens !== promptTokens
+  ) {
+    throw providerResponseError(
+      options,
+      "usage.prompt_cache_hit_tokens",
+      "plus usage.prompt_cache_miss_tokens must equal usage.prompt_tokens",
+    );
+  }
+
+  const reasoningTokens = parseNestedTokenCount(
+    usage.completion_tokens_details,
+    "usage.completion_tokens_details",
+    "reasoning_tokens",
+    options,
+  );
+  if (reasoningTokens !== undefined && reasoningTokens > completionTokens) {
+    throw providerResponseError(
+      options,
+      "usage.completion_tokens_details.reasoning_tokens",
+      "must not exceed usage.completion_tokens",
+    );
+  }
+
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens,
+    ...(promptCacheHitTokens === undefined
+      ? {}
+      : { promptCacheHitTokens, promptCacheMissTokens }),
+    ...(reasoningTokens === undefined ? {} : { reasoningTokens }),
+  };
+}
+
+function requireTokenCount(
+  value: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): number {
+  const count = optionalTokenCount(value, path, options);
+  if (count === undefined) {
+    throw providerResponseError(options, path, "is required");
+  }
+  return count;
+}
+
+function parseNestedTokenCount(
+  value: unknown,
+  path: string,
+  property: string,
+  options: { provider: string; model: string },
+): number | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  const record = requireObject(value, path, options);
+  return optionalTokenCount(record[property], `${path}.${property}`, options);
+}
+
+function requireObject(
+  value: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw providerResponseError(options, path, "must be an object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function optionalTokenCount(
+  value: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw providerResponseError(options, path, "must be a non-negative integer");
+  }
+  return value as number;
+}
+
+function providerResponseError(
+  options: { provider: string; model: string },
+  path: string,
+  detail: string,
+): Error {
+  return new Error(
+    `Invalid provider response (provider=${options.provider}, model=${options.model}): ${path} ${detail}.`,
+  );
+}