tinker-agent 1.9.0 → 1.11.0

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

@@ -0,0 +1,295 @@
+import OpenAI from "openai";
+import type {
+  ResponseCreateParamsNonStreaming,
+  ResponseCreateParamsStreaming,
+} from "openai/resources/responses/responses";
+import type { AssistantMessage } from "../agent/types";
+import {
+  IMAGE_INPUT_POLICY,
+  IMAGE_INPUT_POLICY_VERSION,
+} from "../image/image-input-policy";
+import type { InputTokenEstimator } from "./input-token-estimator";
+import type { ModelContextBudget } from "./model-context-profile";
+import { ProviderResponseError } from "./model-client";
+import type {
+  MaterializedModelRequest,
+  ModelClient,
+  ModelMaterializeOptions,
+  ModelMessageProtocol,
+  ModelRequestInput,
+  ModelRequestOptions,
+  ModelRequestOutput,
+  PreparedModelRequest,
+  PreparedPromptSegment,
+} from "./model-client";
+import { MoonshotInputTokenEstimator } from "./moonshot-input-token-estimator";
+import {
+  deepFreeze,
+  imageUserSegment,
+  materializeOpenAIRequest,
+  normalizedEndpointPolicy,
+  sanitizedProviderError,
+  segmentKind,
+} from "./openai-model-utils";
+import {
+  fromOpenAIResponse,
+  toOpenAIResponsesInput,
+  toOpenAIResponsesItems,
+  toOpenAIResponsesTools,
+} from "./openai-responses-mapping";
+import { OpenAIResponsesStreamAccumulator } from "./openai-responses-stream";
+import { responsesPayloadForChatTokenEstimator } from "./openai-responses-token-estimator";
+import type { ReasoningEffortController } from "./reasoning-effort";
+import { sha256, stableJsonStringify } from "./model-request-preflight";
+
+const OPENAI_RESPONSES_SERIALIZATION_VERSION = "openai-responses-v1";
+const OPENAI_RESPONSES_TIMEOUT_MS = 30 * 60 * 1_000;
+
+export class OpenAIResponsesModelClient implements ModelClient {
+  readonly messageProtocol: ModelMessageProtocol = Object.freeze({
+    adapter: "openai-responses",
+    serializationVersion: OPENAI_RESPONSES_SERIALIZATION_VERSION,
+  });
+  readonly inputTokenEstimator?: InputTokenEstimator;
+  readonly inputModalities: readonly ("text" | "image")[];
+  readonly reasoningEffort?: ReasoningEffortController;
+  private readonly client: OpenAI;
+  private readonly preparedRequests = new WeakSet<object>();
+  private readonly materializedRequests = new WeakSet<object>();
+  private readonly provider: string;
+  private readonly stream: boolean;
+
+  constructor(
+    private readonly options: {
+      apiKey: string;
+      contextBudget: ModelContextBudget;
+      baseURL?: string;
+      inputModalities?: readonly ("text" | "image")[];
+      tokenEstimator?: {
+        kind: "moonshot-estimate-token-count-v1";
+        model: string;
+        apiBase: string;
+        apiKey: string;
+        timeoutMs: number;
+        maxRetries: 0;
+      };
+      model: string;
+      providerName?: string;
+      reasoningEffort?: ReasoningEffortController;
+      stream?: boolean;
+      timeoutMs?: number;
+      fetch?: typeof fetch;
+    },
+  ) {
+    this.provider = options.providerName ?? "responses-compatible";
+    this.stream = options.stream ?? true;
+    this.reasoningEffort = options.reasoningEffort;
+    this.inputModalities = Object.freeze([...(options.inputModalities ?? ["text"])]);
+    const supportsImages = this.inputModalities.includes("image");
+    if (!this.inputModalities.includes("text")) {
+      throw new Error('OpenAI Responses input modalities must include "text".');
+    }
+    if (supportsImages && options.tokenEstimator === undefined) {
+      throw new Error("Image-capable OpenAI Responses requires a token estimator.");
+    }
+    this.client = new OpenAI({
+      apiKey: options.apiKey,
+      baseURL: options.baseURL,
+      timeout: options.timeoutMs ?? OPENAI_RESPONSES_TIMEOUT_MS,
+      maxRetries: 0,
+      fetch: options.fetch,
+    });
+    if (options.tokenEstimator !== undefined) {
+      this.inputTokenEstimator = new MoonshotInputTokenEstimator({
+        apiKey: options.tokenEstimator.apiKey,
+        baseURL: options.tokenEstimator.apiBase,
+        model: options.tokenEstimator.model,
+        timeoutMs: options.tokenEstimator.timeoutMs,
+        fetch: options.fetch,
+        payloadMapper: responsesPayloadForChatTokenEstimator,
+      });
+    }
+  }
+
+  prepare(input: ModelRequestInput): PreparedModelRequest {
+    const itemsByMessage = input.messages.map((message) =>
+      toOpenAIResponsesItems(message),
+    );
+    const items = toOpenAIResponsesInput(input.messages);
+    const tools =
+      input.tools.length > 0 ? toOpenAIResponsesTools(input.tools) : undefined;
+    const reasoningEffort = this.reasoningEffort?.snapshot().effort;
+    const payload = deepFreeze({
+      model: this.options.model,
+      input: items,
+      ...(tools === undefined ? {} : { tools, tool_choice: "auto" as const }),
+      ...(reasoningEffort === undefined
+        ? {}
+        : { reasoning: { effort: reasoningEffort } }),
+      max_output_tokens: this.options.contextBudget.requestMaxOutputTokens,
+      store: false as const,
+      ...(this.stream ? { stream: true as const } : {}),
+    });
+    const toolSegments = (tools ?? []).map(
+      (tool): PreparedPromptSegment => ({
+        kind: "tool_schema",
+        normalizedText: stableJsonStringify(tool),
+      }),
+    );
+    const messageSegments = input.messages.map(
+      (message, index): PreparedPromptSegment =>
+        message.role === "user" && message.attachments !== undefined
+          ? imageUserSegment(message)
+          : {
+              kind: segmentKind(message.role),
+              normalizedText: stableJsonStringify(itemsByMessage[index]),
+            },
+    );
+    const mediaOccurrenceCount = messageSegments.reduce(
+      (total, segment) => total + (segment.media?.length ?? 0),
+      0,
+    );
+    const requestConfigHash = sha256(
+      stableJsonStringify({
+        adapter: this.messageProtocol.adapter,
+        serializationVersion: this.messageProtocol.serializationVersion,
+        endpoint: normalizedEndpointPolicy(this.options.baseURL),
+        model: this.options.model,
+        requestMaxOutputTokens: this.options.contextBudget.requestMaxOutputTokens,
+        stream: this.stream,
+        inputModalities: this.inputModalities,
+        requestPolicy: { store: false, toolChoice: "auto" },
+        imagePolicy: {
+          version: IMAGE_INPUT_POLICY_VERSION,
+          ...IMAGE_INPUT_POLICY,
+        },
+        ...(this.inputTokenEstimator === undefined
+          ? {}
+          : { tokenEstimator: this.inputTokenEstimator.compatibility }),
+      }),
+    );
+    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,
+      mediaOccurrenceCount,
+      assistantReplaySegments: (message) => this.assistantReplaySegments(message),
+    };
+    Object.freeze(prepared);
+    this.preparedRequests.add(prepared);
+    return prepared;
+  }
+
+  async materialize(
+    prepared: PreparedModelRequest,
+    options: ModelMaterializeOptions,
+  ): Promise<MaterializedModelRequest> {
+    this.assertPrepared(prepared);
+    if (prepared.mediaOccurrenceCount > 0 && !this.inputModalities.includes("image")) {
+      throw new Error("Current model profile does not support image input.");
+    }
+    const materialized = await materializeOpenAIRequest(prepared, options);
+    this.materializedRequests.add(materialized);
+    return materialized;
+  }
+
+  async request(
+    prepared: PreparedModelRequest,
+    options: ModelRequestOptions,
+  ): Promise<ModelRequestOutput> {
+    this.assertPrepared(prepared);
+    if (prepared.mediaOccurrenceCount > 0 && !this.materializedRequests.has(prepared)) {
+      throw new Error("Image request must be materialized before provider dispatch.");
+    }
+    const response = this.stream
+      ? await this.requestStreaming(prepared, options)
+      : await this.requestNonStreaming(prepared, options.signal);
+    return fromOpenAIResponse(response, {
+      identity: options.identity,
+      provider: this.provider,
+      model: this.options.model,
+    });
+  }
+
+  private async requestStreaming(
+    prepared: PreparedModelRequest,
+    options: ModelRequestOptions,
+  ): Promise<unknown> {
+    const accumulator = new OpenAIResponsesStreamAccumulator({
+      provider: this.provider,
+      model: this.options.model,
+    });
+    try {
+      const stream = await this.client.responses.create(
+        prepared.payload as ResponseCreateParamsStreaming,
+        { signal: options.signal },
+      );
+      for await (const event of stream) {
+        const content = accumulator.push(event);
+        if (content !== undefined && content !== "") {
+          options.onTextDelta?.(content);
+        }
+      }
+      return accumulator.finish();
+    } catch (error) {
+      if (error instanceof ProviderResponseError) {
+        throw error;
+      }
+      throw sanitizedProviderError(error, this.provider, this.options.model);
+    }
+  }
+
+  private async requestNonStreaming(
+    prepared: PreparedModelRequest,
+    signal: AbortSignal,
+  ): Promise<unknown> {
+    try {
+      return await this.client.responses.create(
+        prepared.payload as ResponseCreateParamsNonStreaming,
+        { signal },
+      );
+    } catch (error) {
+      throw sanitizedProviderError(error, this.provider, this.options.model);
+    }
+  }
+
+  private assistantReplaySegments(message: AssistantMessage): PreparedPromptSegment[] {
+    const items = toOpenAIResponsesItems(message);
+    if (items.length === 0) {
+      throw new Error("OpenAI Responses assistant replay mapping produced no items.");
+    }
+    return [
+      {
+        kind: "assistant",
+        normalizedText: stableJsonStringify(items),
+      },
+    ];
+  }
+
+  private assertPrepared(prepared: PreparedModelRequest): void {
+    if (
+      !this.preparedRequests.has(prepared) &&
+      !this.materializedRequests.has(prepared)
+    ) {
+      throw new Error(
+        `OpenAI Responses 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 Responses request configuration does not match client.",
+      );
+    }
+  }
+}

package/src/model/openai-responses-stream.ts

@@ -0,0 +1,96 @@
+import {
+  ProviderResponseError,
+  type ProviderResponseDiagnostics,
+} from "./model-client";
+
+export class OpenAIResponsesStreamAccumulator {
+  private eventCount = 0;
+  private terminalResponse: unknown;
+
+  constructor(
+    private readonly options: {
+      provider: string;
+      model: string;
+    },
+  ) {}
+
+  push(event: unknown): string | undefined {
+    const path = `events[${this.eventCount}]`;
+    const record = requireRecord(event, path, this.options);
+    const type = requireString(record.type, `${path}.type`, this.options);
+    this.eventCount += 1;
+
+    if (type === "response.output_text.delta") {
+      return requireString(record.delta, `${path}.delta`, this.options);
+    }
+
+    if (
+      type === "response.completed" ||
+      type === "response.incomplete" ||
+      type === "response.failed"
+    ) {
+      if (this.terminalResponse !== undefined) {
+        throw streamError(
+          this.options,
+          path,
+          "contains more than one terminal response event",
+        );
+      }
+      this.terminalResponse = record.response;
+    }
+    return undefined;
+  }
+
+  finish(): unknown {
+    if (this.eventCount === 0) {
+      throw streamError(this.options, "events", "must not be empty");
+    }
+    if (this.terminalResponse === undefined) {
+      throw streamError(
+        this.options,
+        "events",
+        "ended without a terminal response event",
+      );
+    }
+    return this.terminalResponse;
+  }
+}
+
+function requireRecord(
+  value: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw streamError(options, path, "must be an object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireString(
+  value: unknown,
+  path: string,
+  options: { provider: string; model: string },
+): string {
+  if (typeof value !== "string") {
+    throw streamError(options, path, "must be a string");
+  }
+  return value;
+}
+
+function streamError(
+  options: { provider: string; model: string },
+  path: string,
+  detail: string,
+): ProviderResponseError {
+  const diagnostics: ProviderResponseDiagnostics = {
+    provider: options.provider,
+    model: options.model,
+    path,
+  };
+  return new ProviderResponseError(
+    "invalid_provider_stream",
+    `Invalid provider stream (provider=${options.provider}, model=${options.model}): ${path} ${detail}.`,
+    diagnostics,
+  );
+}

package/src/model/openai-responses-token-estimator.ts

@@ -0,0 +1,155 @@
+type ChatEstimatorToolCall = {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    arguments: string;
+  };
+};
+
+type ChatEstimatorMessage = {
+  role: "system" | "user" | "assistant" | "tool";
+  content: unknown;
+  tool_calls?: ChatEstimatorToolCall[];
+  tool_call_id?: string;
+};
+
+export function responsesPayloadForChatTokenEstimator(
+  payload: unknown,
+): Record<string, unknown> {
+  const root = requireRecord(payload, "Responses token estimator payload");
+  if (!Array.isArray(root.input)) {
+    throw new Error("Responses token estimator payload input must be an array.");
+  }
+
+  const messages: ChatEstimatorMessage[] = [];
+  for (const [index, rawItem] of root.input.entries()) {
+    const path = `Responses token estimator input[${index}]`;
+    const item = requireRecord(rawItem, path);
+    const type = requireString(item.type, `${path}.type`);
+    if (type === "message") {
+      messages.push(toChatMessage(item, path));
+      continue;
+    }
+    if (type === "function_call") {
+      appendFunctionCall(messages, item, path);
+      continue;
+    }
+    if (type === "function_call_output") {
+      messages.push({
+        role: "tool",
+        tool_call_id: requireString(item.call_id, `${path}.call_id`),
+        content: requireString(item.output, `${path}.output`),
+      });
+      continue;
+    }
+    throw new Error(`${path}.type is unsupported: ${JSON.stringify(type)}.`);
+  }
+
+  return {
+    messages,
+    ...(root.tools === undefined ? {} : { tools: toChatTools(root.tools) }),
+  };
+}
+
+function toChatMessage(
+  item: Record<string, unknown>,
+  path: string,
+): ChatEstimatorMessage {
+  const role = requireString(item.role, `${path}.role`);
+  if (role !== "system" && role !== "user" && role !== "assistant") {
+    throw new Error(`${path}.role is unsupported: ${JSON.stringify(role)}.`);
+  }
+  return {
+    role,
+    content: toChatContent(item.content, `${path}.content`),
+  };
+}
+
+function toChatContent(value: unknown, path: string): unknown {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${path} must be a string or an array.`);
+  }
+  return value.map((rawPart, index) => {
+    const partPath = `${path}[${index}]`;
+    const part = requireRecord(rawPart, partPath);
+    const type = requireString(part.type, `${partPath}.type`);
+    if (type === "input_text") {
+      return {
+        type: "text",
+        text: requireString(part.text, `${partPath}.text`),
+      };
+    }
+    if (type === "input_image") {
+      return {
+        type: "image_url",
+        image_url: {
+          url: requireString(part.image_url, `${partPath}.image_url`),
+          ...(part.detail === undefined
+            ? {}
+            : { detail: requireString(part.detail, `${partPath}.detail`) }),
+        },
+      };
+    }
+    throw new Error(`${partPath}.type is unsupported: ${JSON.stringify(type)}.`);
+  });
+}
+
+function appendFunctionCall(
+  messages: ChatEstimatorMessage[],
+  item: Record<string, unknown>,
+  path: string,
+): void {
+  const call: ChatEstimatorToolCall = {
+    id: requireString(item.call_id, `${path}.call_id`),
+    type: "function",
+    function: {
+      name: requireString(item.name, `${path}.name`),
+      arguments: requireString(item.arguments, `${path}.arguments`),
+    },
+  };
+  const previous = messages[messages.length - 1];
+  if (previous?.role === "assistant") {
+    (previous.tool_calls ??= []).push(call);
+    return;
+  }
+  messages.push({ role: "assistant", content: null, tool_calls: [call] });
+}
+
+function toChatTools(value: unknown): Record<string, unknown>[] {
+  if (!Array.isArray(value)) {
+    throw new Error("Responses token estimator payload tools must be an array.");
+  }
+  return value.map((rawTool, index) => {
+    const path = `Responses token estimator tools[${index}]`;
+    const tool = requireRecord(rawTool, path);
+    if (tool.type !== "function") {
+      throw new Error(`${path}.type must be "function".`);
+    }
+    return {
+      type: "function",
+      function: {
+        name: requireString(tool.name, `${path}.name`),
+        description: requireString(tool.description, `${path}.description`),
+        parameters: requireRecord(tool.parameters, `${path}.parameters`),
+      },
+    };
+  });
+}
+
+function requireRecord(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${path} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireString(value: unknown, path: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`${path} must be a string.`);
+  }
+  return value;
+}

package/src/model/reasoning-effort.ts

@@ -0,0 +1,60 @@
+export type ReasoningEffortConfig = {
+  readonly supportedEfforts: readonly string[];
+  readonly defaultEffort: string;
+};
+
+export type ReasoningEffortSnapshot = {
+  readonly supportedEfforts: readonly string[];
+  readonly defaultEffort: string;
+  readonly effort: string;
+  readonly source: "profile_default" | "session_override";
+};
+
+export type ReasoningEffortController = {
+  snapshot(): ReasoningEffortSnapshot;
+  set(effort: string): ReasoningEffortSnapshot;
+  reset(): ReasoningEffortSnapshot;
+};
+
+export class RuntimeReasoningEffort implements ReasoningEffortController {
+  private effort: string;
+  private source: ReasoningEffortSnapshot["source"] = "profile_default";
+  private readonly supportedEfforts: readonly string[];
+
+  constructor(private readonly config: ReasoningEffortConfig) {
+    this.supportedEfforts = Object.freeze([...config.supportedEfforts]);
+    this.effort = config.defaultEffort;
+  }
+
+  snapshot(): ReasoningEffortSnapshot {
+    return Object.freeze({
+      supportedEfforts: this.supportedEfforts,
+      defaultEffort: this.config.defaultEffort,
+      effort: this.effort,
+      source: this.source,
+    });
+  }
+
+  set(effort: string): ReasoningEffortSnapshot {
+    if (!this.supportedEfforts.includes(effort)) {
+      throw new Error(
+        `Unsupported reasoning effort ${JSON.stringify(effort)}. Available efforts: ${this.supportedEfforts.join(", ")}.`,
+      );
+    }
+    this.effort = effort;
+    this.source = "session_override";
+    return this.snapshot();
+  }
+
+  reset(): ReasoningEffortSnapshot {
+    this.effort = this.config.defaultEffort;
+    this.source = "profile_default";
+    return this.snapshot();
+  }
+}
+
+export function createReasoningEffortController(
+  config: ReasoningEffortConfig | undefined,
+): ReasoningEffortController | undefined {
+  return config === undefined ? undefined : new RuntimeReasoningEffort(config);
+}

package/src/session/session-catalog.ts

@@ -5,7 +5,7 @@ import { parseSessionId, type SessionId } from "../ids/runtime-id";
 import { SessionError } from "./session-errors";
 import { inspectSessionLock } from "./session-lock";
 import { SessionStore } from "./session-store";
-import { verifySessionSchema } from "./session-schema";
+import { verifyReadableSessionSchema } from "./session-schema";
 
 export type SessionSummary = {
   sessionId: SessionId;
@@ -129,7 +129,7 @@ async function readSummary(
       strict: true,
       safeIntegers: true,
     });
-    verifySessionSchema(database, sessionId);
+    verifyReadableSessionSchema(database, sessionId);
     const meta = database.query("SELECT * FROM session_meta").all() as Array<
       Record<string, unknown>
     >;

package/src/session/session-history-reader.ts

@@ -149,7 +149,12 @@ export function isRecallableMessage(input: {
     (input.role === "user" || input.role === "assistant" || input.role === "tool") &&
     input.content !== null &&
     input.content.length > 0 &&
-    !(input.role === "tool" && input.toolName === "Recall")
+    !(
+      input.role === "tool" &&
+      (input.toolName === "Recall" ||
+        input.toolName === "RecallSearch" ||
+        input.toolName === "RecallGet")
+    )
   );
 }