tinker-agent 1.0.65

package/src/mcp/mcp-tool-executor.ts

@@ -0,0 +1,178 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { cancellationError, throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { defineToolExecutor } from "../tools/types";
+import type {
+  JsonSchema,
+  McpToolRawResult,
+  ToolExecutionContext,
+  ToolExecutor,
+} from "../tools/types";
+
+export const MCP_TOOL_NAME_PREFIX = "mcp__";
+export const DEFAULT_MCP_TIMEOUT_MS = 60_000;
+export const DEFAULT_MCP_MAX_OBSERVATION_CHARS = 40_000;
+
+export function mcpToolName(serverName: string, toolName: string): string {
+  return `${MCP_TOOL_NAME_PREFIX}${serverName}__${toolName}`;
+}
+
+export function isMcpToolName(name: string): boolean {
+  return name.startsWith(MCP_TOOL_NAME_PREFIX);
+}
+
+export function sanitizeInputSchema(schema: unknown): JsonSchema {
+  if (
+    typeof schema !== "object" ||
+    schema === null ||
+    Array.isArray(schema) ||
+    (schema as Record<string, unknown>).type !== "object"
+  ) {
+    return { type: "object", properties: {} };
+  }
+
+  const rest = { ...(schema as Record<string, unknown>) };
+  delete rest.$schema;
+  return rest;
+}
+
+export type CreateMcpToolExecutorOptions = {
+  client: Client;
+  serverName: string;
+  tool: Tool;
+  timeoutMs?: number;
+  maxObservationChars?: number;
+};
+
+export function createMcpToolExecutor(
+  options: CreateMcpToolExecutorOptions,
+): ToolExecutor {
+  const toolName = mcpToolName(options.serverName, options.tool.name);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_MCP_TIMEOUT_MS;
+  const maxObservationChars =
+    options.maxObservationChars ?? DEFAULT_MCP_MAX_OBSERVATION_CHARS;
+
+  const base = {
+    toolName,
+    serverName: options.serverName,
+    serverToolName: options.tool.name,
+  };
+
+  return defineToolExecutor("mcp", {
+    definition: {
+      name: toolName,
+      description:
+        options.tool.description ??
+        `MCP tool ${options.tool.name} from server ${options.serverName}`,
+      parameters: sanitizeInputSchema(options.tool.inputSchema),
+    },
+    async execute(
+      args: unknown,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<McpToolRawResult> {
+      throwIfTurnCancelled(context.signal);
+      if (args !== undefined && !isRecord(args)) {
+        return {
+          ok: false,
+          ...base,
+          error: `MCP tool arguments must be an object; received ${JSON.stringify(args)}`,
+        };
+      }
+
+      let result;
+
+      try {
+        result = await options.client.callTool(
+          {
+            name: options.tool.name,
+            arguments: args ?? {},
+          },
+          undefined,
+          { timeout: timeoutMs, signal: context.signal },
+        );
+      } catch (error) {
+        if (context.signal.aborted) {
+          throw cancellationError(context.signal, error);
+        }
+
+        return {
+          ok: false,
+          ...base,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+
+      const blocks = Array.isArray(result.content) ? result.content : [];
+      const rendered = renderContentBlocks(blocks, maxObservationChars);
+      const isError = result.isError === true;
+
+      return {
+        ok: !isError,
+        ...base,
+        isError,
+        text: rendered.text,
+        truncated: rendered.truncated,
+        contentBlockCount: blocks.length,
+      };
+    },
+  });
+}
+
+function renderContentBlocks(
+  blocks: unknown[],
+  maxChars: number,
+): { text: string; truncated: boolean } {
+  const parts: string[] = [];
+
+  for (const block of blocks) {
+    if (!isRecord(block)) {
+      continue;
+    }
+
+    if (block.type === "text" && typeof block.text === "string") {
+      parts.push(block.text);
+      continue;
+    }
+
+    parts.push(renderNonTextBlockPlaceholder(block));
+  }
+
+  const text = parts.join("\n");
+
+  if (text.length <= maxChars) {
+    return { text, truncated: false };
+  }
+
+  return { text: text.slice(0, maxChars), truncated: true };
+}
+
+function renderNonTextBlockPlaceholder(block: Record<string, unknown>): string {
+  const type = typeof block.type === "string" ? block.type : "unknown";
+
+  if (type === "image" || type === "audio") {
+    const mimeType = typeof block.mimeType === "string" ? ` ${block.mimeType}` : "";
+    return `[${type}${mimeType} content omitted]`;
+  }
+
+  if (type === "resource_link") {
+    const uri = typeof block.uri === "string" ? ` ${block.uri}` : "";
+    return `[resource link${uri}]`;
+  }
+
+  if (type === "resource") {
+    const resource = isRecord(block.resource) ? block.resource : {};
+    if (typeof resource.text === "string") {
+      return resource.text;
+    }
+
+    const uri = typeof resource.uri === "string" ? ` ${resource.uri}` : "";
+    return `[resource${uri} content omitted]`;
+  }
+
+  return `[${type} content omitted]`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/model/committed-prefix-auditor.ts

@@ -0,0 +1,68 @@
+import type { ContextRevisionId } from "../ids/runtime-id";
+import type { PreparedModelRequest } from "./model-client";
+import {
+  lastPromptPrefixHash,
+  promptPrefixHashes,
+  type PromptPrefixFingerprint,
+} from "./prompt-prefix-hash";
+
+export type CommittedPrefixAnchor = PromptPrefixFingerprint & {
+  readonly revisionId: ContextRevisionId;
+};
+
+export class CommittedPrefixAuditError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CommittedPrefixAuditError";
+  }
+}
+
+export class CommittedPrefixAuditor {
+  private anchor?: CommittedPrefixAnchor;
+
+  audit(
+    revisionId: ContextRevisionId,
+    prepared: PreparedModelRequest,
+  ): CommittedPrefixAnchor {
+    const hashes = promptPrefixHashes(
+      prepared.requestConfigHash,
+      prepared.promptSegments,
+    );
+    const current = Object.freeze<PromptPrefixFingerprint>({
+      requestConfigHash: prepared.requestConfigHash,
+      toolSchemaHash: prepared.toolSchemaHash,
+      segmentCount: prepared.promptSegments.length,
+      prefixHash: lastPromptPrefixHash(hashes),
+    });
+    const previous = this.anchor;
+    if (previous !== undefined && previous.revisionId === revisionId) {
+      if (previous.requestConfigHash !== current.requestConfigHash) {
+        throw new CommittedPrefixAuditError(
+          "Committed request config changed within one context revision.",
+        );
+      }
+      if (previous.toolSchemaHash !== current.toolSchemaHash) {
+        throw new CommittedPrefixAuditError(
+          "Committed tool schema changed within one context revision.",
+        );
+      }
+      if (current.segmentCount < previous.segmentCount) {
+        throw new CommittedPrefixAuditError(
+          "Committed prompt segment count shrank within one context revision.",
+        );
+      }
+      if (hashes[previous.segmentCount] !== previous.prefixHash) {
+        throw new CommittedPrefixAuditError(
+          "Committed prompt prefix changed within one context revision.",
+        );
+      }
+    }
+    const anchor = Object.freeze({ revisionId, ...current });
+    this.anchor = anchor;
+    return anchor;
+  }
+
+  current(): CommittedPrefixAnchor | undefined {
+    return this.anchor;
+  }
+}

package/src/model/fake-model-client.ts

@@ -0,0 +1,280 @@
+import type { AgentMessage, AssistantMessage } from "../agent/types";
+import { cancellationError } from "../agent/turn-cancellation";
+import type { ModelContextBudget } from "./model-context-profile";
+import type {
+  ModelClient,
+  ModelRequestInput,
+  ModelRequestOptions,
+  ModelRequestOutput,
+  PreparedModelRequest,
+  PreparedPromptSegment,
+} from "./model-client";
+import { sha256, stableJsonStringify } from "./model-request-preflight";
+import { estimatePromptSegments } from "./token-estimator";
+
+export class FakeModelClient implements ModelClient {
+  private steps = 0;
+  private readonly preparedInputs = new WeakMap<object, ModelRequestInput>();
+
+  constructor(
+    private readonly mode: string,
+    private readonly options: {
+      model: string;
+      contextBudget: ModelContextBudget;
+    },
+  ) {}
+
+  prepare(input: ModelRequestInput): PreparedModelRequest {
+    const toolSegments = input.tools.map(
+      (tool): PreparedPromptSegment => ({
+        kind: "tool_schema",
+        normalizedText: stableJsonStringify(tool),
+      }),
+    );
+    const messageSegments = input.messages.map(toPromptSegment);
+    const requestConfigHash = sha256(
+      stableJsonStringify({
+        adapter: "fake-v1",
+        mode: this.mode,
+        model: this.options.model,
+        requestMaxOutputTokens: this.options.contextBudget.requestMaxOutputTokens,
+      }),
+    );
+    const prepared: PreparedModelRequest = Object.freeze({
+      provider: "fake",
+      model: this.options.model,
+      payload: Object.freeze({
+        messages: Object.freeze([...input.messages]),
+        tools: Object.freeze([...input.tools]),
+        maxTokens: this.options.contextBudget.requestMaxOutputTokens,
+      }),
+      promptSegments: Object.freeze([...toolSegments, ...messageSegments]),
+      requestConfigHash,
+      toolSchemaHash: sha256(
+        toolSegments.map((segment) => segment.normalizedText).join("\n"),
+      ),
+      requestMaxOutputTokens: this.options.contextBudget.requestMaxOutputTokens,
+      assistantReplaySegments: (message: AssistantMessage) => [
+        toPromptSegment(message),
+      ],
+    });
+    this.preparedInputs.set(prepared, {
+      messages: [...input.messages],
+      tools: [...input.tools],
+    });
+    return prepared;
+  }
+
+  async request(
+    prepared: PreparedModelRequest,
+    options: ModelRequestOptions,
+  ): Promise<ModelRequestOutput> {
+    const input = this.preparedInputs.get(prepared);
+    if (input === undefined) {
+      throw new Error("Fake model request was not prepared by this client.");
+    }
+    this.steps += 1;
+
+    if (this.mode === "write-notes") {
+      return this.writeNotes(input, prepared, options);
+    }
+    if (this.mode === "wait-for-cancel") {
+      return waitForCancellation(options.signal);
+    }
+    if (this.mode === "recall-smoke") {
+      return this.recallSmoke(input, prepared, options);
+    }
+
+    return outputWithUsage(
+      prepared,
+      {
+        role: "assistant",
+        content: `Fake model received: ${lastUserMessage(input.messages)}`,
+      },
+      "stop",
+    );
+  }
+
+  private writeNotes(
+    input: ModelRequestInput,
+    prepared: PreparedModelRequest,
+    options: ModelRequestOptions,
+  ): ModelRequestOutput {
+    const sawToolResult = input.messages.some((message) => message.role === "tool");
+
+    if (!sawToolResult) {
+      if (options.identity === undefined) {
+        throw new Error("Fake tool call requires an iteration identity context.");
+      }
+      return outputWithUsage(
+        prepared,
+        {
+          role: "assistant",
+          content: "I will create notes.txt.",
+          toolCalls: [
+            {
+              ...options.identity.runtimeSession.createToolCall(
+                options.identity.iteration,
+                1,
+              ),
+              providerToolCallId: "fake-write-notes-1",
+              name: "Write",
+              args: {
+                file_path: "notes.txt",
+                content: "hello.\n",
+              },
+            },
+          ],
+        },
+        "tool_calls",
+      );
+    }
+
+    return outputWithUsage(
+      prepared,
+      {
+        role: "assistant",
+        content: "Created notes.txt with one line: hello.",
+      },
+      "stop",
+    );
+  }
+
+  private recallSmoke(
+    input: ModelRequestInput,
+    prepared: PreparedModelRequest,
+    options: ModelRequestOptions,
+  ): ModelRequestOutput {
+    if (options.identity === undefined) {
+      throw new Error("Fake Recall call requires an iteration identity context.");
+    }
+    const lastUserIndex = lastMessageIndex(input.messages, "user");
+    const latestRecallResult = input.messages
+      .slice(lastUserIndex + 1)
+      .reverse()
+      .find(
+        (message): message is Extract<AgentMessage, { role: "tool" }> =>
+          message.role === "tool" && message.name === "Recall",
+      );
+    if (latestRecallResult === undefined) {
+      return outputWithUsage(
+        prepared,
+        {
+          role: "assistant",
+          toolCalls: [
+            {
+              ...options.identity.runtimeSession.createToolCall(
+                options.identity.iteration,
+                1,
+              ),
+              providerToolCallId: "fake-recall-search-1",
+              name: "Recall",
+              args: { mode: "search", query: "recall-smoke-marker" },
+            },
+          ],
+        },
+        "tool_calls",
+      );
+    }
+    if (latestRecallResult.content.startsWith("Recall searched")) {
+      const source = latestRecallResult.content.match(
+        /^source=(ctx:\/\/message\/[0-9a-f-]+)$/m,
+      )?.[1];
+      if (source === undefined) {
+        throw new Error("Fake Recall search did not return a source.");
+      }
+      return outputWithUsage(
+        prepared,
+        {
+          role: "assistant",
+          toolCalls: [
+            {
+              ...options.identity.runtimeSession.createToolCall(
+                options.identity.iteration,
+                1,
+              ),
+              providerToolCallId: "fake-recall-get-1",
+              name: "Recall",
+              args: { mode: "get", source },
+            },
+          ],
+        },
+        "tool_calls",
+      );
+    }
+    if (!latestRecallResult.content.includes("recall-smoke-marker")) {
+      throw new Error("Fake Recall get did not recover the expected marker.");
+    }
+    return outputWithUsage(
+      prepared,
+      {
+        role: "assistant",
+        content: "Recall search and get completed.",
+      },
+      "stop",
+    );
+  }
+}
+
+function outputWithUsage(
+  prepared: PreparedModelRequest,
+  message: AssistantMessage,
+  finishReason: string,
+): ModelRequestOutput {
+  const promptTokens = estimatePromptSegments(prepared.promptSegments).totalTokens;
+  const completionTokens = Math.max(
+    1,
+    estimatePromptSegments(prepared.assistantReplaySegments(message)).totalTokens,
+  );
+  return {
+    message,
+    finishReason,
+    usage: {
+      promptTokens,
+      completionTokens,
+      totalTokens: promptTokens + completionTokens,
+    },
+  };
+}
+
+function waitForCancellation(signal: AbortSignal): Promise<ModelRequestOutput> {
+  return new Promise((_resolve, reject) => {
+    const abort = () => reject(cancellationError(signal));
+    if (signal.aborted) {
+      abort();
+      return;
+    }
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+function lastUserMessage(messages: AgentMessage[]): string {
+  const users = messages.filter(
+    (message): message is { role: "user"; content: string } => message.role === "user",
+  );
+  return users.at(-1)?.content ?? "";
+}
+
+function lastMessageIndex(
+  messages: AgentMessage[],
+  role: AgentMessage["role"],
+): number {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.role === role) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function toPromptSegment(message: AgentMessage): PreparedPromptSegment {
+  return {
+    kind:
+      message.role === "system"
+        ? "kernel"
+        : message.role === "user"
+          ? "user"
+          : message.role,
+    normalizedText: stableJsonStringify(message),
+  };
+}

package/src/model/model-client.ts

@@ -0,0 +1,64 @@
+import type { AgentMessage, AssistantMessage, IterationIdentity } from "../agent/types";
+import type { RuntimeSessionContext } from "../agent/runtime-session";
+import type { ToolDefinition } from "../tools/types";
+
+export interface ModelClient {
+  prepare(input: ModelRequestInput): PreparedModelRequest;
+  request(
+    prepared: PreparedModelRequest,
+    options: ModelRequestOptions,
+  ): Promise<ModelRequestOutput>;
+}
+
+export type ModelRequestOptions = {
+  signal: AbortSignal;
+  identity?: {
+    iteration: IterationIdentity;
+    runtimeSession: RuntimeSessionContext;
+  };
+};
+
+export type ModelRequestInput = {
+  messages: AgentMessage[];
+  tools: ToolDefinition[];
+};
+
+export type PreparedPromptSegmentKind =
+  | "kernel"
+  | "user"
+  | "assistant"
+  | "tool"
+  | "tool_schema"
+  | "protocol";
+
+export type PreparedPromptSegment = {
+  kind: PreparedPromptSegmentKind;
+  normalizedText: string;
+};
+
+export type PreparedModelRequest = {
+  provider: string;
+  model: string;
+  payload: unknown;
+  promptSegments: readonly PreparedPromptSegment[];
+  requestConfigHash: string;
+  toolSchemaHash: string;
+  requestMaxOutputTokens: number;
+  assistantReplaySegments(message: AssistantMessage): PreparedPromptSegment[];
+};
+
+export type ModelRequestOutput = {
+  message: AssistantMessage;
+  finishReason?: string;
+  usage: ModelUsage;
+  rawResponse?: unknown;
+};
+
+export type ModelUsage = {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  promptCacheHitTokens?: number;
+  promptCacheMissTokens?: number;
+  reasoningTokens?: number;
+};