tinker-agent 1.0.65

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

@@ -0,0 +1,190 @@
+import OpenAI from "openai";
+import type { ChatCompletionCreateParamsNonStreaming } from "openai/resources/chat/completions";
+import type { AssistantMessage } from "../agent/types";
+import type { ModelContextBudget } from "./model-context-profile";
+import type {
+  ModelClient,
+  ModelRequestInput,
+  ModelRequestOptions,
+  ModelRequestOutput,
+  PreparedModelRequest,
+  PreparedPromptSegment,
+} from "./model-client";
+import {
+  fromOpenAIChatCompletion,
+  toOpenAIChatMessages,
+  toOpenAIChatTools,
+} from "./openai-chat-mapping";
+import {
+  canonicalJsonValue,
+  sha256,
+  stableJsonStringify,
+} from "./model-request-preflight";
+
+const OPENAI_CHAT_SERIALIZATION_VERSION = "openai-chat-v1";
+
+export class OpenAIChatModelClient implements ModelClient {
+  private readonly client: OpenAI;
+  private readonly preparedRequests = new WeakSet<object>();
+  private readonly provider: string;
+
+  constructor(
+    private readonly options: {
+      apiKey: string;
+      contextBudget: ModelContextBudget;
+      baseURL?: string;
+      includeReasoningContent?: boolean;
+      model: string;
+      providerName?: string;
+      timeoutMs?: number;
+      fetch?: typeof fetch;
+    },
+  ) {
+    this.provider = options.providerName ?? "openai-compatible";
+    this.client = new OpenAI({
+      apiKey: options.apiKey,
+      baseURL: options.baseURL,
+      timeout: options.timeoutMs,
+      fetch: options.fetch,
+    });
+  }
+
+  prepare(input: ModelRequestInput): PreparedModelRequest {
+    const messages = toOpenAIChatMessages(input.messages, {
+      includeReasoningContent: this.options.includeReasoningContent,
+    });
+    const tools = input.tools.length > 0 ? toOpenAIChatTools(input.tools) : undefined;
+    const payload = deepFreeze(
+      canonicalJsonValue({
+        model: this.options.model,
+        messages,
+        tools,
+        tool_choice: tools === undefined ? undefined : "auto",
+        max_tokens: this.options.contextBudget.requestMaxOutputTokens,
+      }),
+    ) as ChatCompletionCreateParamsNonStreaming;
+    const toolSegments = (payload.tools ?? []).map(
+      (tool): PreparedPromptSegment => ({
+        kind: "tool_schema",
+        normalizedText: stableJsonStringify(tool),
+      }),
+    );
+    const messageSegments = payload.messages.map(
+      (message, index): PreparedPromptSegment => ({
+        kind: segmentKind(input.messages[index]?.role),
+        normalizedText: stableJsonStringify(message),
+      }),
+    );
+    const requestConfigHash = sha256(
+      stableJsonStringify({
+        provider: this.provider,
+        baseURL: nonSecretBaseUrl(this.options.baseURL),
+        model: this.options.model,
+        serializationVersion: OPENAI_CHAT_SERIALIZATION_VERSION,
+        requestMaxOutputTokens: this.options.contextBudget.requestMaxOutputTokens,
+        includeReasoningContent: this.options.includeReasoningContent === true,
+      }),
+    );
+    const prepared: PreparedModelRequest = {
+      provider: this.provider,
+      model: this.options.model,
+      payload,
+      promptSegments: Object.freeze([...toolSegments, ...messageSegments]),
+      requestConfigHash,
+      toolSchemaHash: sha256(
+        toolSegments.map((segment) => segment.normalizedText).join("\n"),
+      ),
+      requestMaxOutputTokens: this.options.contextBudget.requestMaxOutputTokens,
+      assistantReplaySegments: (message) => this.assistantReplaySegments(message),
+    };
+    Object.freeze(prepared);
+    this.preparedRequests.add(prepared);
+    return prepared;
+  }
+
+  async request(
+    prepared: PreparedModelRequest,
+    options: ModelRequestOptions,
+  ): Promise<ModelRequestOutput> {
+    if (!this.preparedRequests.has(prepared)) {
+      throw new Error(
+        `OpenAI chat request was not prepared by this client (provider=${this.provider}, model=${this.options.model}).`,
+      );
+    }
+    if (
+      prepared.provider !== this.provider ||
+      prepared.model !== this.options.model ||
+      prepared.requestMaxOutputTokens !==
+        this.options.contextBudget.requestMaxOutputTokens
+    ) {
+      throw new Error(
+        "Prepared OpenAI chat request configuration does not match client.",
+      );
+    }
+
+    const response = await this.client.chat.completions.create(
+      prepared.payload as ChatCompletionCreateParamsNonStreaming,
+      { signal: options.signal },
+    );
+
+    return fromOpenAIChatCompletion(response, {
+      identity: options.identity,
+      provider: this.provider,
+      model: this.options.model,
+    });
+  }
+
+  private assistantReplaySegments(message: AssistantMessage): PreparedPromptSegment[] {
+    const [mapped] = toOpenAIChatMessages([message], {
+      includeReasoningContent: this.options.includeReasoningContent,
+    });
+    if (mapped === undefined) {
+      throw new Error("OpenAI assistant replay mapping produced no message.");
+    }
+    return [
+      {
+        kind: "assistant",
+        normalizedText: stableJsonStringify(canonicalJsonValue(mapped)),
+      },
+    ];
+  }
+}
+
+function segmentKind(
+  role: ModelRequestInput["messages"][number]["role"] | undefined,
+): PreparedPromptSegment["kind"] {
+  switch (role) {
+    case "system":
+      return "kernel";
+    case "user":
+      return "user";
+    case "assistant":
+      return "assistant";
+    case "tool":
+      return "tool";
+    case undefined:
+      throw new Error("OpenAI message mapping changed the message count.");
+  }
+}
+
+function nonSecretBaseUrl(value: string | undefined): string {
+  if (value === undefined) {
+    return "https://api.openai.com/v1";
+  }
+  try {
+    const url = new URL(value);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return value.split(/[?#]/, 1)[0] ?? value;
+  }
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+    return value;
+  }
+  for (const child of Object.values(value)) {
+    deepFreeze(child);
+  }
+  return Object.freeze(value);
+}

package/src/model/prompt-prefix-hash.ts

@@ -0,0 +1,47 @@
+import type { PreparedModelRequest, PreparedPromptSegment } from "./model-client";
+import { sha256 } from "./model-request-preflight";
+
+export type PromptPrefixFingerprint = {
+  readonly requestConfigHash: string;
+  readonly toolSchemaHash: string;
+  readonly segmentCount: number;
+  readonly prefixHash: string;
+};
+
+export function promptPrefixHashes(
+  requestConfigHash: string,
+  segments: readonly PreparedPromptSegment[],
+): readonly string[] {
+  const hashes = [sha256(`request-config:${requestConfigHash}`)];
+  for (const segment of segments) {
+    const previous = hashes.at(-1);
+    if (previous === undefined) {
+      throw new Error("Prompt prefix hash chain has no seed.");
+    }
+    hashes.push(
+      sha256(`${previous}\u0000${segment.kind}\u0000${segment.normalizedText}`),
+    );
+  }
+  return Object.freeze(hashes);
+}
+
+export function lastPromptPrefixHash(hashes: readonly string[]): string {
+  const value = hashes.at(-1);
+  if (value === undefined) {
+    throw new Error("Prompt prefix hash chain is empty.");
+  }
+  return value;
+}
+
+export function promptPrefixFingerprint(
+  prepared: PreparedModelRequest,
+): PromptPrefixFingerprint {
+  return Object.freeze({
+    requestConfigHash: prepared.requestConfigHash,
+    toolSchemaHash: prepared.toolSchemaHash,
+    segmentCount: prepared.promptSegments.length,
+    prefixHash: lastPromptPrefixHash(
+      promptPrefixHashes(prepared.requestConfigHash, prepared.promptSegments),
+    ),
+  });
+}

package/src/model/token-estimator.ts

@@ -0,0 +1,148 @@
+import type { PreparedPromptSegment } from "./model-client";
+
+export const INITIAL_CORRECTION_FACTOR = 1.25;
+export const MIN_CORRECTION_FACTOR = 1.1;
+export const OBSERVED_RATIO_PADDING = 1.05;
+export const CALIBRATION_WINDOW_SIZE = 8;
+
+export type RawContextBreakdown = {
+  kernelTokens: number;
+  userTokens: number;
+  assistantTokens: number;
+  toolTokens: number;
+  toolSchemaTokens: number;
+  protocolTokens: number;
+  totalTokens: number;
+};
+
+type BreakdownKey = Exclude<keyof RawContextBreakdown, "totalTokens">;
+
+const breakdownKeys: BreakdownKey[] = [
+  "kernelTokens",
+  "userTokens",
+  "assistantTokens",
+  "toolTokens",
+  "toolSchemaTokens",
+  "protocolTokens",
+];
+
+export function estimatePromptSegments(
+  segments: readonly PreparedPromptSegment[],
+): RawContextBreakdown {
+  const exact: Record<BreakdownKey, number> = {
+    kernelTokens: 0,
+    userTokens: 0,
+    assistantTokens: 0,
+    toolTokens: 0,
+    toolSchemaTokens: 0,
+    protocolTokens: segments.length * 8,
+  };
+
+  for (const segment of segments) {
+    exact[breakdownKey(segment.kind)] += estimateText(segment.normalizedText);
+  }
+
+  const totalTokens = Math.ceil(
+    breakdownKeys.reduce((total, key) => total + exact[key], 0),
+  );
+  const rounded = Object.fromEntries(
+    breakdownKeys.map((key) => [key, Math.floor(exact[key])]),
+  ) as Record<BreakdownKey, number>;
+  let remaining =
+    totalTokens - breakdownKeys.reduce((total, key) => total + rounded[key], 0);
+  const byFraction = [...breakdownKeys].sort((left, right) => {
+    const fractionDifference =
+      exact[right] - Math.floor(exact[right]) - (exact[left] - Math.floor(exact[left]));
+    return fractionDifference === 0
+      ? breakdownKeys.indexOf(left) - breakdownKeys.indexOf(right)
+      : fractionDifference;
+  });
+  for (const key of byFraction) {
+    if (remaining === 0) {
+      break;
+    }
+    rounded[key] += 1;
+    remaining -= 1;
+  }
+
+  return { ...rounded, totalTokens };
+}
+
+export class RollingTokenCalibration {
+  private readonly samples: number[] = [];
+
+  correctionFactor(): number {
+    if (this.samples.length === 0) {
+      return INITIAL_CORRECTION_FACTOR;
+    }
+    return Math.max(
+      MIN_CORRECTION_FACTOR,
+      Math.max(...this.samples) * OBSERVED_RATIO_PADDING,
+    );
+  }
+
+  sampleCount(): number {
+    return this.samples.length;
+  }
+
+  record(promptTokens: number, rawEstimatedTokens: number): void {
+    if (!Number.isSafeInteger(promptTokens) || promptTokens < 0) {
+      throw new Error(
+        `Calibration promptTokens must be a non-negative safe integer; received ${promptTokens}.`,
+      );
+    }
+    if (!Number.isSafeInteger(rawEstimatedTokens) || rawEstimatedTokens <= 0) {
+      throw new Error(
+        `Calibration rawEstimatedTokens must be a positive safe integer; received ${rawEstimatedTokens}.`,
+      );
+    }
+
+    this.samples.push(promptTokens / rawEstimatedTokens);
+    if (this.samples.length > CALIBRATION_WINDOW_SIZE) {
+      this.samples.shift();
+    }
+  }
+
+  clear(): void {
+    this.samples.length = 0;
+  }
+}
+
+function estimateText(value: string): number {
+  let asciiCount = 0;
+  let hanCount = 0;
+  let otherUtf8Bytes = 0;
+
+  for (const codePoint of value) {
+    const scalar = codePoint.codePointAt(0);
+    if (scalar === undefined) {
+      throw new Error("Unable to read a Unicode code point during token estimation.");
+    }
+    if (scalar <= 0x7f) {
+      asciiCount += 1;
+    } else if (/\p{Script=Han}/u.test(codePoint)) {
+      hanCount += 1;
+    } else {
+      otherUtf8Bytes += Buffer.byteLength(codePoint, "utf8");
+    }
+  }
+
+  return asciiCount * 0.3 + hanCount * 0.6 + otherUtf8Bytes * 0.5;
+}
+
+function breakdownKey(kind: PreparedPromptSegment["kind"]): BreakdownKey {
+  switch (kind) {
+    case "kernel":
+      return "kernelTokens";
+    case "user":
+      return "userTokens";
+    case "assistant":
+      return "assistantTokens";
+    case "tool":
+      return "toolTokens";
+    case "tool_schema":
+      return "toolSchemaTokens";
+    case "protocol":
+      return "protocolTokens";
+  }
+}