tinker-agent 1.0.65

package/src/ids/runtime-id.ts

@@ -0,0 +1,68 @@
+import { createUuidV7 } from "./uuid-v7";
+
+export type RuntimeId<Name extends string> = string & {
+  readonly __runtimeId: Name;
+};
+
+export type SessionId = RuntimeId<"session">;
+export type TurnId = RuntimeId<"turn">;
+export type IterationId = RuntimeId<"iteration">;
+export type ToolCallId = RuntimeId<"tool-call">;
+export type MessageId = RuntimeId<"message">;
+export type ProtocolFrameId = RuntimeId<"protocol-frame">;
+export type ContextRevisionId = RuntimeId<"context-revision">;
+
+export type RuntimeIdFactory = {
+  createSessionId(): SessionId;
+  createTurnId(): TurnId;
+  createIterationId(): IterationId;
+  createToolCallId(): ToolCallId;
+  createMessageId(): MessageId;
+  createProtocolFrameId(): ProtocolFrameId;
+  createContextRevisionId(): ContextRevisionId;
+};
+
+export const runtimeIdFactory: RuntimeIdFactory = {
+  createSessionId: () => createUuidV7() as SessionId,
+  createTurnId: () => createUuidV7() as TurnId,
+  createIterationId: () => createUuidV7() as IterationId,
+  createToolCallId: () => createUuidV7() as ToolCallId,
+  createMessageId: () => createUuidV7() as MessageId,
+  createProtocolFrameId: () => createUuidV7() as ProtocolFrameId,
+  createContextRevisionId: () => createUuidV7() as ContextRevisionId,
+};
+
+const canonicalUuidV7Pattern =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+export class SessionIdParseError extends Error {
+  readonly code = "SESSION_ID_INVALID" as const;
+
+  constructor(value: string) {
+    super(`Invalid session ID: ${JSON.stringify(value)}.`);
+    this.name = "SessionIdParseError";
+  }
+}
+
+export class MessageIdParseError extends Error {
+  readonly code = "MESSAGE_ID_INVALID" as const;
+
+  constructor(value: string) {
+    super(`Invalid message ID: ${JSON.stringify(value)}.`);
+    this.name = "MessageIdParseError";
+  }
+}
+
+export function parseSessionId(value: string): SessionId {
+  if (!canonicalUuidV7Pattern.test(value)) {
+    throw new SessionIdParseError(value);
+  }
+  return value as SessionId;
+}
+
+export function parseMessageId(value: string): MessageId {
+  if (!canonicalUuidV7Pattern.test(value)) {
+    throw new MessageIdParseError(value);
+  }
+  return value as MessageId;
+}

package/src/ids/uuid-v7.ts

@@ -0,0 +1,5 @@
+import { v7 as uuidv7 } from "uuid";
+
+export function createUuidV7(): string {
+  return uuidv7();
+}

package/src/instructions/project-instructions.ts

@@ -0,0 +1,242 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+
+export const PROJECT_INSTRUCTIONS_MAX_BYTES = 64 * 1024;
+
+export type ProjectInstructionFileName = "CLAUDE.md" | "AGENTS.md";
+
+export type LoadedProjectInstruction = {
+  fileName: ProjectInstructionFileName;
+  absolutePath: string;
+  content: string;
+  contentSha256: string;
+  byteLength: number;
+};
+
+export type ProjectInstructionsSnapshot = {
+  workspaceRoot: string;
+  instruction?: LoadedProjectInstruction;
+};
+
+export type ProjectInstructionManifest = {
+  path: ProjectInstructionFileName;
+  byteLength: number;
+  sha256: string;
+};
+
+const PROJECT_INSTRUCTION_FILE_NAMES: readonly ProjectInstructionFileName[] = [
+  "AGENTS.md",
+  "CLAUDE.md",
+];
+
+export async function loadProjectInstructions(
+  workspaceRoot: string,
+): Promise<ProjectInstructionsSnapshot> {
+  const canonicalRoot = await realpath(workspaceRoot);
+  for (const fileName of PROJECT_INSTRUCTION_FILE_NAMES) {
+    const instruction = await loadCandidate(canonicalRoot, fileName);
+    if (instruction !== undefined) {
+      return { workspaceRoot: canonicalRoot, instruction };
+    }
+  }
+  return { workspaceRoot: canonicalRoot };
+}
+
+export function buildSystemPrompt(input: {
+  workspaceRoot: string;
+  runtimeInstructions: string;
+  projectInstructions: ProjectInstructionsSnapshot;
+}): string {
+  if (input.runtimeInstructions.trim() === "") {
+    throw new Error("Runtime instructions must not be empty.");
+  }
+  if (input.projectInstructions.workspaceRoot !== input.workspaceRoot) {
+    throw new Error(
+      "Project instructions snapshot does not match the current workspace root.",
+    );
+  }
+
+  const runtime = wrapTextBlock(
+    "tinker_runtime_instructions",
+    input.runtimeInstructions,
+  );
+  const instruction = input.projectInstructions.instruction;
+  if (instruction === undefined) {
+    return runtime;
+  }
+
+  const content =
+    instruction.content + (instruction.content.endsWith("\n") ? "" : "\n");
+  const project = `<project_instructions>
+The following file contains trusted project instructions for this workspace.
+They do not override Tinker's runtime, tool protocol, or safety constraints.
+
+<instruction_file path="${instruction.fileName}">
+${content}</instruction_file>
+</project_instructions>`;
+  return `${runtime}\n\n${project}`;
+}
+
+export function projectInstructionManifest(
+  snapshot: ProjectInstructionsSnapshot,
+): ProjectInstructionManifest | undefined {
+  const instruction = snapshot.instruction;
+  return instruction === undefined
+    ? undefined
+    : {
+        path: instruction.fileName,
+        byteLength: instruction.byteLength,
+        sha256: instruction.contentSha256,
+      };
+}
+
+async function loadCandidate(
+  workspaceRoot: string,
+  fileName: ProjectInstructionFileName,
+): Promise<LoadedProjectInstruction | undefined> {
+  const absolutePath = path.join(workspaceRoot, fileName);
+  let handle;
+  try {
+    handle = await open(absolutePath, constants.O_RDONLY | constants.O_NONBLOCK);
+  } catch (error) {
+    if (!isErrno(error, "ENOENT")) {
+      throw loadError(fileName, error);
+    }
+    try {
+      await lstat(absolutePath);
+    } catch (lstatError) {
+      if (isErrno(lstatError, "ENOENT")) {
+        return undefined;
+      }
+      throw loadError(fileName, lstatError);
+    }
+    throw loadError(fileName, error);
+  }
+
+  try {
+    const targetPath = await realpath(absolutePath);
+    if (!isWithinWorkspace(workspaceRoot, targetPath)) {
+      throw new Error(
+        `Project instruction ${fileName} resolves outside the workspace root.`,
+      );
+    }
+
+    const stats = await handle.stat();
+    if (!stats.isFile()) {
+      throw new Error(`Project instruction ${fileName} must be a regular file.`);
+    }
+    const targetStats = await stat(targetPath);
+    if (targetStats.dev !== stats.dev || targetStats.ino !== stats.ino) {
+      throw new Error(`Project instruction ${fileName} changed while being opened.`);
+    }
+    if (stats.size > PROJECT_INSTRUCTIONS_MAX_BYTES) {
+      throw tooLargeError(fileName, stats.size);
+    }
+
+    const bytes = await readBounded(handle, PROJECT_INSTRUCTIONS_MAX_BYTES);
+    if (bytes.byteLength > PROJECT_INSTRUCTIONS_MAX_BYTES) {
+      throw tooLargeError(fileName, bytes.byteLength);
+    }
+    if (bytes.includes(0)) {
+      throw new Error(`Project instruction ${fileName} contains a NUL byte.`);
+    }
+
+    let content: string;
+    try {
+      content = new TextDecoder("utf-8", {
+        fatal: true,
+        ignoreBOM: true,
+      }).decode(bytes);
+    } catch (error) {
+      throw new Error(`Project instruction ${fileName} is not valid UTF-8.`, {
+        cause: error,
+      });
+    }
+    if (content.trim() === "") {
+      throw new Error(`Project instruction ${fileName} must not be empty.`);
+    }
+
+    return {
+      fileName,
+      absolutePath,
+      content,
+      contentSha256: createHash("sha256").update(bytes).digest("hex"),
+      byteLength: bytes.byteLength,
+    };
+  } catch (error) {
+    if (isProjectInstructionError(error, fileName)) {
+      throw error;
+    }
+    throw loadError(fileName, error);
+  } finally {
+    await handle.close().catch((error: unknown) => {
+      throw loadError(fileName, error);
+    });
+  }
+}
+
+async function readBounded(
+  handle: Awaited<ReturnType<typeof open>>,
+  maxBytes: number,
+): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  while (total <= maxBytes) {
+    const chunk = Buffer.allocUnsafe(Math.min(8192, maxBytes + 1 - total));
+    const { bytesRead } = await handle.read(chunk, 0, chunk.byteLength, null);
+    if (bytesRead === 0) {
+      break;
+    }
+    chunks.push(chunk.subarray(0, bytesRead));
+    total += bytesRead;
+  }
+  return Buffer.concat(chunks, total);
+}
+
+function wrapTextBlock(tag: string, content: string): string {
+  return `<${tag}>\n${content}${content.endsWith("\n") ? "" : "\n"}</${tag}>`;
+}
+
+function isWithinWorkspace(workspaceRoot: string, targetPath: string): boolean {
+  const relative = path.relative(workspaceRoot, targetPath);
+  return (
+    relative !== ".." &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  );
+}
+
+function tooLargeError(fileName: ProjectInstructionFileName, actual: number): Error {
+  return new Error(
+    `Project instruction ${fileName} is ${actual} bytes; the limit is ${PROJECT_INSTRUCTIONS_MAX_BYTES} bytes.`,
+  );
+}
+
+function loadError(fileName: ProjectInstructionFileName, cause: unknown): Error {
+  return new Error(
+    `Failed to load project instruction ${fileName}: ${errorMessage(cause)}`,
+    { cause },
+  );
+}
+
+function isProjectInstructionError(
+  error: unknown,
+  fileName: ProjectInstructionFileName,
+): error is Error {
+  return error instanceof Error && error.message.includes(`instruction ${fileName}`);
+}
+
+function isErrno(error: unknown, code: string): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === code
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/mcp/mcp-config.ts

@@ -0,0 +1,144 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+
+export type McpServerConfig = {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+  cwd?: string;
+};
+
+export type McpConfig = {
+  servers: Map<string, McpServerConfig>;
+};
+
+const SERVER_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+export function mcpConfigPath(workspaceRoot: string): string {
+  return path.join(workspaceRoot, ".mcp.json");
+}
+
+export async function loadMcpConfig(
+  workspaceRoot: string,
+): Promise<McpConfig | undefined> {
+  const configPath = mcpConfigPath(workspaceRoot);
+  let raw: string;
+
+  try {
+    raw = await readFile(configPath, "utf8");
+  } catch (error) {
+    if (isFileNotFound(error)) {
+      return undefined;
+    }
+
+    throw new Error(
+      `Failed to read MCP config at ${configPath}: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+
+  return parseMcpConfig(raw, configPath);
+}
+
+export function parseMcpConfig(raw: string, sourcePath: string): McpConfig {
+  let json: unknown;
+
+  try {
+    json = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Invalid JSON in MCP config ${sourcePath}: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+
+  if (!isRecord(json)) {
+    throw new Error(`MCP config ${sourcePath} must be a JSON object.`);
+  }
+
+  const mcpServers = json.mcpServers;
+
+  if (mcpServers === undefined) {
+    return { servers: new Map() };
+  }
+
+  if (!isRecord(mcpServers)) {
+    throw new Error(`MCP config ${sourcePath}: "mcpServers" must be an object.`);
+  }
+
+  const servers = new Map<string, McpServerConfig>();
+
+  for (const [serverName, serverValue] of Object.entries(mcpServers)) {
+    servers.set(serverName, parseServerConfig(serverName, serverValue, sourcePath));
+  }
+
+  return { servers };
+}
+
+function parseServerConfig(
+  serverName: string,
+  value: unknown,
+  sourcePath: string,
+): McpServerConfig {
+  const where = `MCP config ${sourcePath}: server "${serverName}"`;
+
+  if (!SERVER_NAME_PATTERN.test(serverName) || serverName.includes("__")) {
+    throw new Error(
+      `${where} has an invalid name. Server names must match ${SERVER_NAME_PATTERN} and must not contain "__".`,
+    );
+  }
+
+  if (!isRecord(value)) {
+    throw new Error(`${where} must be an object.`);
+  }
+
+  if (value.type !== undefined && value.type !== "stdio") {
+    throw new Error(
+      `${where} has unsupported type ${JSON.stringify(value.type)}. Only "stdio" servers are supported.`,
+    );
+  }
+
+  if (typeof value.command !== "string" || value.command.trim() === "") {
+    throw new Error(`${where} requires a non-empty string "command".`);
+  }
+
+  const args = value.args ?? [];
+
+  if (!Array.isArray(args) || !args.every((item) => typeof item === "string")) {
+    throw new Error(`${where}: "args" must be an array of strings.`);
+  }
+
+  const env = value.env ?? {};
+
+  if (!isRecord(env) || !Object.values(env).every((item) => typeof item === "string")) {
+    throw new Error(`${where}: "env" must be an object mapping strings to strings.`);
+  }
+
+  if (value.cwd !== undefined && typeof value.cwd !== "string") {
+    throw new Error(`${where}: "cwd" must be a string.`);
+  }
+
+  return {
+    command: value.command,
+    args,
+    env: env as Record<string, string>,
+    cwd: value.cwd,
+  };
+}
+
+function isFileNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/mcp/mcp-manager.ts

@@ -0,0 +1,216 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  StdioClientTransport,
+  getDefaultEnvironment,
+} from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { RuntimeSessionContext } from "../agent/runtime-session";
+import type { ToolExecutor } from "../tools/types";
+import type { McpConfig, McpServerConfig } from "./mcp-config";
+import { createMcpToolExecutor } from "./mcp-tool-executor";
+
+const STDERR_TAIL_MAX_CHARS = 2_000;
+
+export type McpClientConnection = {
+  client: Client;
+  close(): Promise<void>;
+};
+
+export type McpClientFactory = (
+  serverName: string,
+  serverConfig: McpServerConfig,
+) => Promise<McpClientConnection>;
+
+export type McpManager = {
+  executors: ToolExecutor[];
+  dispose(): Promise<void>;
+};
+
+export type CreateMcpManagerOptions = {
+  config: McpConfig;
+  runtimeSession: RuntimeSessionContext;
+  clientFactory?: McpClientFactory;
+  timeoutMs?: number;
+  maxObservationChars?: number;
+};
+
+export async function createMcpManager(
+  options: CreateMcpManagerOptions,
+): Promise<McpManager> {
+  const clientFactory = options.clientFactory ?? stdioClientFactory;
+  const timeoutMs =
+    options.timeoutMs ?? parsePositiveIntegerEnv("TINKER_MCP_TIMEOUT_MS");
+  const maxObservationChars =
+    options.maxObservationChars ??
+    parsePositiveIntegerEnv("TINKER_MCP_MAX_OBSERVATION_CHARS");
+  const connections: McpClientConnection[] = [];
+  const executors: ToolExecutor[] = [];
+
+  try {
+    for (const [serverName, serverConfig] of options.config.servers) {
+      let connection: McpClientConnection;
+      let tools;
+
+      try {
+        connection = await clientFactory(serverName, serverConfig);
+      } catch (error) {
+        await options.runtimeSession.append({
+          type: "mcp.server.failed",
+          sessionId: options.runtimeSession.sessionId,
+          data: {
+            serverName,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        });
+        continue;
+      }
+
+      try {
+        tools = (await connection.client.listTools()).tools;
+      } catch (error) {
+        try {
+          await connection.close();
+        } catch (closeError) {
+          throw new AggregateError(
+            [error, closeError],
+            `Failed to inspect and close MCP server ${serverName}.`,
+            { cause: closeError },
+          );
+        }
+        await options.runtimeSession.append({
+          type: "mcp.server.failed",
+          sessionId: options.runtimeSession.sessionId,
+          data: {
+            serverName,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        });
+        continue;
+      }
+
+      connections.push(connection);
+
+      const seenToolNames = new Set<string>();
+
+      for (const tool of tools) {
+        if (seenToolNames.has(tool.name)) {
+          continue;
+        }
+
+        seenToolNames.add(tool.name);
+        executors.push(
+          createMcpToolExecutor({
+            client: connection.client,
+            serverName,
+            tool,
+            timeoutMs,
+            maxObservationChars,
+          }),
+        );
+      }
+
+      await options.runtimeSession.append({
+        type: "mcp.server.connected",
+        sessionId: options.runtimeSession.sessionId,
+        data: { serverName, toolCount: seenToolNames.size },
+      });
+    }
+  } catch (error) {
+    const errors = [error];
+    await closeConnections(connections, errors);
+    if (errors.length === 1) {
+      throw error;
+    }
+    throw new AggregateError(errors, "MCP manager initialization failed.", {
+      cause: error,
+    });
+  }
+
+  let disposePromise: Promise<void> | undefined;
+  return {
+    executors,
+    dispose(): Promise<void> {
+      disposePromise ??= disposeConnections(connections);
+      return disposePromise;
+    },
+  };
+}
+
+async function disposeConnections(connections: McpClientConnection[]): Promise<void> {
+  const errors: unknown[] = [];
+  await closeConnections(connections, errors);
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  if (errors.length > 1) {
+    throw new AggregateError(errors, "Failed to close MCP connections.");
+  }
+}
+
+async function closeConnections(
+  connections: McpClientConnection[],
+  errors: unknown[],
+): Promise<void> {
+  for (let index = connections.length - 1; index >= 0; index -= 1) {
+    const connection = connections[index];
+    if (connection === undefined) {
+      throw new Error(`Missing MCP connection at index ${index}.`);
+    }
+    try {
+      await connection.close();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+}
+
+function parsePositiveIntegerEnv(name: string): number | undefined {
+  const value = process.env[name];
+  if (value === undefined || value.trim() === "") {
+    return undefined;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer; received ${value}`);
+  }
+
+  return parsed;
+}
+
+async function stdioClientFactory(
+  serverName: string,
+  serverConfig: McpServerConfig,
+): Promise<McpClientConnection> {
+  const transport = new StdioClientTransport({
+    command: serverConfig.command,
+    args: serverConfig.args,
+    env: { ...getDefaultEnvironment(), ...serverConfig.env },
+    cwd: serverConfig.cwd,
+    stderr: "pipe",
+  });
+
+  let stderrTail = "";
+  transport.stderr?.on("data", (chunk: Buffer) => {
+    stderrTail = (stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL_MAX_CHARS);
+  });
+
+  const client = new Client({ name: "tinker", version: "0.1.0" });
+
+  try {
+    await client.connect(transport);
+  } catch (error) {
+    await transport.close().catch(() => undefined);
+    const message = error instanceof Error ? error.message : String(error);
+    const stderrSuffix =
+      stderrTail.trim() === "" ? "" : `\nServer stderr:\n${stderrTail.trim()}`;
+    throw new Error(
+      `Failed to connect to MCP server "${serverName}" (${serverConfig.command}): ${message}${stderrSuffix}`,
+      { cause: error },
+    );
+  }
+
+  return {
+    client,
+    close: () => client.close(),
+  };
+}