tinker-agent 1.2.1 → 1.4.0

package/src/cli/main.ts

@@ -0,0 +1,213 @@
+import type { SessionId } from "../ids/runtime-id";
+import { createUuidV7 } from "../ids/uuid-v7";
+import { parseCommandLine, type CommandLineResult } from "./command-line";
+import type {
+  ResolvedPublicConfig,
+  RunnerConfig,
+  RunnerConfigSelection,
+} from "./config";
+import {
+  CliUsageError,
+  flushCliOutput,
+  renderCliFailure,
+  renderUsageError,
+  writeCliOutput,
+  type CliOutputWriter,
+} from "./output";
+import { loadPackageMetadata, type PackageMetadata } from "./package-metadata";
+import {
+  PromptInputError,
+  resolvePromptSource,
+  type PromptReadable,
+  type PromptSource,
+  type ResolvedPrompt,
+} from "./prompt-source";
+
+export const BOOTSTRAP_FAILURE_MESSAGE =
+  "Tinker failed to start. Reinstall tinker-agent.\n";
+
+export type MainInput = {
+  readonly args: readonly string[];
+  readonly stdin: PromptReadable;
+  readonly stdout: CliOutputWriter;
+  readonly stderr: CliOutputWriter;
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+};
+
+type ConfigBoundary = {
+  readonly resolvePublicConfig: (input: {
+    readonly env: NodeJS.ProcessEnv;
+    readonly cwd: string;
+  }) => Promise<ResolvedPublicConfig>;
+  readonly deriveRunnerConfig: (
+    snapshot: ResolvedPublicConfig,
+    selection: RunnerConfigSelection,
+  ) => RunnerConfig;
+};
+
+type TuiRunner = {
+  readonly runTui: (options: {
+    readonly publicConfig: ResolvedPublicConfig;
+    readonly initialRunnerConfig: RunnerConfig;
+    readonly env: NodeJS.ProcessEnv;
+  }) => Promise<void>;
+};
+
+type OneShotRunner = {
+  readonly runOneShot: (
+    prompt: string,
+    options: {
+      readonly config: RunnerConfig;
+      readonly tooling: ResolvedPublicConfig["tooling"];
+      readonly stdout: CliOutputWriter;
+      readonly stderr: CliOutputWriter;
+      readonly env: NodeJS.ProcessEnv;
+    },
+  ) => Promise<number>;
+};
+
+export type MainDependencies = {
+  readonly loadPackageMetadata: () => Promise<PackageMetadata>;
+  readonly parseCommandLine: (
+    args: readonly string[],
+    packageVersion: string,
+  ) => Promise<CommandLineResult>;
+  readonly loadConfigBoundary: () => Promise<ConfigBoundary>;
+  readonly createSessionId: () => SessionId;
+  readonly resolvePromptSource: (
+    source: PromptSource,
+    input: { readonly stdin: PromptReadable; readonly cwd: string },
+  ) => Promise<ResolvedPrompt>;
+  readonly loadTuiRunner: () => Promise<TuiRunner>;
+  readonly loadOneShotRunner: () => Promise<OneShotRunner>;
+};
+
+const DEFAULT_DEPENDENCIES: MainDependencies = {
+  loadPackageMetadata,
+  parseCommandLine,
+  loadConfigBoundary: () => import("./config"),
+  createSessionId: () => createUuidV7() as SessionId,
+  resolvePromptSource,
+  loadTuiRunner: () => import("./tui-runner"),
+  loadOneShotRunner: () => import("./run-runner"),
+};
+
+export async function main(
+  input: MainInput,
+  injected: Partial<MainDependencies> = {},
+): Promise<number> {
+  const dependencies = { ...DEFAULT_DEPENDENCIES, ...injected };
+  const args = Object.freeze([...input.args]);
+  const env = Object.freeze({ ...input.env }) as NodeJS.ProcessEnv;
+  const cwd = input.cwd;
+  const finish = async (exitCode: number): Promise<number> => {
+    await flushCliOutput(input.stdout);
+    await flushCliOutput(input.stderr);
+    return exitCode;
+  };
+
+  try {
+    let metadata: PackageMetadata;
+    try {
+      metadata = await dependencies.loadPackageMetadata();
+    } catch {
+      await writeCliOutput(input.stderr, BOOTSTRAP_FAILURE_MESSAGE);
+      return finish(1);
+    }
+
+    let parsed: CommandLineResult;
+    try {
+      parsed = await dependencies.parseCommandLine(args, metadata.version);
+    } catch (error) {
+      if (error instanceof CliUsageError) {
+        await writeCliOutput(input.stderr, renderUsageError(error));
+        return finish(2);
+      }
+      throw error;
+    }
+
+    if (parsed.type === "terminal") {
+      await writeCliOutput(input.stdout, parsed.stdout);
+      await writeCliOutput(input.stderr, parsed.stderr);
+      return finish(0);
+    }
+
+    let configBoundary: ConfigBoundary;
+    let publicConfig: ResolvedPublicConfig;
+    let runnerConfig: RunnerConfig;
+    try {
+      configBoundary = await dependencies.loadConfigBoundary();
+      publicConfig = await configBoundary.resolvePublicConfig({ env, cwd });
+      runnerConfig = configBoundary.deriveRunnerConfig(publicConfig, {
+        sessionId: dependencies.createSessionId(),
+        ...(parsed.command.profileName === undefined
+          ? {}
+          : { profileName: parsed.command.profileName }),
+      });
+    } catch (error) {
+      await writeCliOutput(
+        input.stderr,
+        renderCliFailure("Configuration failed", error),
+      );
+      return finish(1);
+    }
+
+    if (parsed.command.type === "tui") {
+      try {
+        const runner = await dependencies.loadTuiRunner();
+        await runner.runTui({
+          publicConfig,
+          initialRunnerConfig: runnerConfig,
+          env,
+        });
+        return finish(0);
+      } catch (error) {
+        await writeCliOutput(input.stderr, renderCliFailure("Runtime failed", error));
+        return finish(1);
+      }
+    }
+
+    let prompt: ResolvedPrompt;
+    try {
+      prompt = await dependencies.resolvePromptSource(parsed.command.promptSource, {
+        stdin: input.stdin,
+        cwd,
+      });
+    } catch (error) {
+      if (error instanceof PromptInputError) {
+        await writeCliOutput(
+          input.stderr,
+          renderCliFailure("Prompt input failed", error),
+        );
+        return finish(error.exitCode);
+      }
+      await writeCliOutput(
+        input.stderr,
+        renderCliFailure("Prompt input failed", error),
+      );
+      return finish(1);
+    }
+
+    try {
+      const runner = await dependencies.loadOneShotRunner();
+      const exitCode = await runner.runOneShot(prompt.text, {
+        config: runnerConfig,
+        tooling: publicConfig.tooling,
+        stdout: input.stdout,
+        stderr: input.stderr,
+        env,
+      });
+      return finish(exitCode);
+    } catch (error) {
+      await writeCliOutput(input.stderr, renderCliFailure("Runtime failed", error));
+      return finish(1);
+    }
+  } catch (error) {
+    await writeCliOutput(
+      input.stderr,
+      renderCliFailure("Tinker failed unexpectedly", error),
+    );
+    return finish(1);
+  }
+}

package/src/cli/model-profiles.ts

@@ -1,9 +1,15 @@
-import path from "node:path";
 import { readFile, rename, unlink, writeFile } from "node:fs/promises";
 import {
   createModelContextProfile,
   type ModelContextProfile,
 } from "../model/model-context-profile";
+import {
+  MODEL_PROFILE_FIELDS,
+  MODEL_PROFILES_DOCUMENT_FIELDS,
+  MODEL_TOKEN_ESTIMATOR_FIELDS,
+  type ModelTokenEstimatorKind,
+  type ModelTokenEstimatorMaxRetries,
+} from "./public-config-contract";
 
 export type ModelProfile = {
   readonly name: string;
@@ -21,12 +27,12 @@ export type ModelProfile = {
 export type ModelInputModality = "text" | "image";
 
 export type ModelTokenEstimatorProfile = {
-  readonly kind: "moonshot-estimate-token-count-v1";
+  readonly kind: ModelTokenEstimatorKind;
   readonly model: string;
   readonly apiBase: string;
   readonly apiKey: string;
   readonly timeoutMs: number;
-  readonly maxRetries: 0;
+  readonly maxRetries: ModelTokenEstimatorMaxRetries;
 };
 
 export type ModelProfiles = {
@@ -34,24 +40,7 @@ export type ModelProfiles = {
   readonly profiles: ReadonlyMap<string, ModelProfile>;
 };
 
-export function modelsConfigPath(
-  env: NodeJS.ProcessEnv = process.env,
-): string | undefined {
-  const value = env.TINKER_MODELS;
-  if (value === undefined || value.trim() === "") {
-    return undefined;
-  }
-  return path.isAbsolute(value) ? value : path.resolve(process.cwd(), value);
-}
-
-export async function loadModelProfiles(
-  env: NodeJS.ProcessEnv = process.env,
-): Promise<ModelProfiles | undefined> {
-  const configPath = modelsConfigPath(env);
-  if (configPath === undefined) {
-    return undefined;
-  }
-
+export async function loadModelProfiles(configPath: string): Promise<ModelProfiles> {
   let raw: string;
   try {
     raw = await readFile(configPath, "utf8");
@@ -67,13 +56,8 @@ export async function loadModelProfiles(
 
 export async function persistDefaultProfile(
   profileName: string,
-  env: NodeJS.ProcessEnv = process.env,
+  configPath: string,
 ): Promise<void> {
-  const configPath = modelsConfigPath(env);
-  if (configPath === undefined) {
-    return;
-  }
-
   let raw: string;
   try {
     raw = await readFile(configPath, "utf8");
@@ -128,6 +112,11 @@ export function parseModelProfiles(raw: string, sourcePath: string): ModelProfil
   if (!isRecord(json)) {
     throw new Error(`Model profiles ${sourcePath} must be a JSON object.`);
   }
+  assertKnownKeys(
+    json,
+    MODEL_PROFILES_DOCUMENT_FIELDS.map((field) => field.name),
+    `Model profiles ${sourcePath}`,
+  );
 
   const defaultProfile = json.default;
   if (typeof defaultProfile !== "string" || defaultProfile.trim() === "") {
@@ -238,45 +227,31 @@ function parseProfile(
 
   assertKnownKeys(
     value,
-    [
-      "model",
-      "apiBase",
-      "apiKey",
-      "contextWindowTokens",
-      "maxSupportedOutputTokens",
-      "includeReasoningContent",
-      "stream",
-      "inputModalities",
-      "tokenEstimator",
-    ],
+    MODEL_PROFILE_FIELDS.map((field) => field.name),
     where,
   );
 
-  const model = requireString(value.model, `${where}: "model"`);
-  const apiBase = requireString(value.apiBase, `${where}: "apiBase"`);
-  const apiKey = requireString(value.apiKey, `${where}: "apiKey"`);
+  const model = parseProfileString(value, "model", where);
+  const apiBase = parseProfileString(value, "apiBase", where);
+  const apiKey = parseProfileString(value, "apiKey", where);
 
-  const contextWindowTokens = requirePositiveInteger(
-    value.contextWindowTokens,
-    `${where}: "contextWindowTokens"`,
+  const contextWindowTokens = parseProfilePositiveInteger(
+    value,
+    "contextWindowTokens",
+    where,
   );
-  const maxSupportedOutputTokens = requirePositiveInteger(
-    value.maxSupportedOutputTokens,
-    `${where}: "maxSupportedOutputTokens"`,
+  const maxSupportedOutputTokens = parseProfilePositiveInteger(
+    value,
+    "maxSupportedOutputTokens",
+    where,
   );
 
-  const includeReasoningContent =
-    value.includeReasoningContent === undefined
-      ? false
-      : parseBoolean(
-          value.includeReasoningContent,
-          `${where}: "includeReasoningContent"`,
-        );
-
-  const stream =
-    value.stream === undefined
-      ? true
-      : parseBoolean(value.stream, `${where}: "stream"`);
+  const includeReasoningContent = parseProfileBoolean(
+    value,
+    "includeReasoningContent",
+    where,
+  );
+  const stream = parseProfileBoolean(value, "stream", where);
 
   const inputModalities = parseInputModalities(
     value.inputModalities,
@@ -316,7 +291,8 @@ function parseInputModalities(
   name: string,
 ): readonly ModelInputModality[] {
   if (value === undefined) {
-    return Object.freeze(["text"]);
+    const defaultValue = modelProfileField("inputModalities").defaultValue;
+    return defaultValue;
   }
   if (!Array.isArray(value) || value.length === 0) {
     throw new Error(`${name} must be a non-empty array.`);
@@ -345,32 +321,127 @@ function parseTokenEstimator(value: unknown, name: string): ModelTokenEstimatorP
   }
   assertKnownKeys(
     value,
-    ["kind", "model", "apiBase", "apiKey", "timeoutMs", "maxRetries"],
+    MODEL_TOKEN_ESTIMATOR_FIELDS.map((field) => field.name),
     name,
   );
-  if (value.kind !== "moonshot-estimate-token-count-v1") {
-    throw new Error(`${name}.kind must be "moonshot-estimate-token-count-v1".`);
+  const kindField = tokenEstimatorField("kind");
+  if (value.kind !== kindField.literalValue) {
+    throw new Error(`${name}.kind must be ${JSON.stringify(kindField.literalValue)}.`);
+  }
+  const model = parseTokenEstimatorString(value, "model", name);
+  const apiBase = parseTokenEstimatorString(value, "apiBase", name);
+  const apiKey = parseTokenEstimatorString(value, "apiKey", name);
+  const timeoutField = tokenEstimatorField("timeoutMs");
+  if (timeoutField.valueKind !== "positive-integer") {
+    throw new Error("Token estimator timeoutMs contract kind is invalid.");
   }
-  const model = requireString(value.model, `${name}.model`);
-  const apiBase = requireString(value.apiBase, `${name}.apiBase`);
-  const apiKey = requireString(value.apiKey, `${name}.apiKey`);
   const timeoutMs = requirePositiveInteger(value.timeoutMs, `${name}.timeoutMs`);
-  if (timeoutMs < 1_000 || timeoutMs > 60_000) {
-    throw new Error(`${name}.timeoutMs must be between 1000 and 60000.`);
+  if (
+    timeoutField.minimum === undefined ||
+    timeoutField.maximum === undefined ||
+    timeoutMs < timeoutField.minimum ||
+    timeoutMs > timeoutField.maximum
+  ) {
+    throw new Error(
+      `${name}.timeoutMs must be between ${timeoutField.minimum} and ${timeoutField.maximum}.`,
+    );
   }
-  if (value.maxRetries !== 0) {
-    throw new Error(`${name}.maxRetries must be 0.`);
+  const maxRetriesField = tokenEstimatorField("maxRetries");
+  if (value.maxRetries !== maxRetriesField.literalValue) {
+    throw new Error(`${name}.maxRetries must be ${maxRetriesField.literalValue}.`);
   }
   return Object.freeze({
-    kind: value.kind,
+    kind: kindField.literalValue,
     model,
     apiBase,
     apiKey,
     timeoutMs,
-    maxRetries: 0,
+    maxRetries: maxRetriesField.literalValue,
   });
 }
 
+type ModelProfileFieldName = (typeof MODEL_PROFILE_FIELDS)[number]["name"];
+type ModelTokenEstimatorFieldName =
+  (typeof MODEL_TOKEN_ESTIMATOR_FIELDS)[number]["name"];
+
+function modelProfileField<Name extends ModelProfileFieldName>(
+  name: Name,
+): Extract<(typeof MODEL_PROFILE_FIELDS)[number], { readonly name: Name }> {
+  const field = MODEL_PROFILE_FIELDS.find((candidate) => candidate.name === name);
+  if (field === undefined) {
+    throw new Error(`Missing model profile field contract for ${name}.`);
+  }
+  return field as Extract<
+    (typeof MODEL_PROFILE_FIELDS)[number],
+    { readonly name: Name }
+  >;
+}
+
+function tokenEstimatorField<Name extends ModelTokenEstimatorFieldName>(
+  name: Name,
+): Extract<(typeof MODEL_TOKEN_ESTIMATOR_FIELDS)[number], { readonly name: Name }> {
+  const field = MODEL_TOKEN_ESTIMATOR_FIELDS.find(
+    (candidate) => candidate.name === name,
+  );
+  if (field === undefined) {
+    throw new Error(`Missing token estimator field contract for ${name}.`);
+  }
+  return field as Extract<
+    (typeof MODEL_TOKEN_ESTIMATOR_FIELDS)[number],
+    { readonly name: Name }
+  >;
+}
+
+function parseProfileString(
+  value: Record<string, unknown>,
+  name: "model" | "apiBase" | "apiKey",
+  where: string,
+): string {
+  const field = modelProfileField(name);
+  if (field.valueKind !== "non-empty-string") {
+    throw new Error(`Model profile field ${name} has an invalid contract kind.`);
+  }
+  return requireString(value[name], `${where}: ${JSON.stringify(name)}`);
+}
+
+function parseProfilePositiveInteger(
+  value: Record<string, unknown>,
+  name: "contextWindowTokens" | "maxSupportedOutputTokens",
+  where: string,
+): number {
+  const field = modelProfileField(name);
+  if (field.valueKind !== "positive-integer") {
+    throw new Error(`Model profile field ${name} has an invalid contract kind.`);
+  }
+  return requirePositiveInteger(value[name], `${where}: ${JSON.stringify(name)}`);
+}
+
+function parseProfileBoolean(
+  value: Record<string, unknown>,
+  name: "includeReasoningContent" | "stream",
+  where: string,
+): boolean {
+  const field = modelProfileField(name);
+  if (field.valueKind !== "boolean" || typeof field.defaultValue !== "boolean") {
+    throw new Error(`Model profile field ${name} has an invalid boolean contract.`);
+  }
+  return value[name] === undefined
+    ? field.defaultValue
+    : parseBoolean(value[name], `${where}: ${JSON.stringify(name)}`);
+}
+
+function parseTokenEstimatorString(
+  value: Record<string, unknown>,
+  name: "model" | "apiBase" | "apiKey",
+  where: string,
+): string {
+  const field = tokenEstimatorField(name);
+  if (field.valueKind !== "non-empty-string") {
+    throw new Error(`Token estimator field ${name} has an invalid contract kind.`);
+  }
+  return requireString(value[name], `${where}.${name}`);
+}
+
 function assertKnownKeys(
   value: Record<string, unknown>,
   allowed: readonly string[],

package/src/cli/output.ts

@@ -0,0 +1,113 @@
+export const MAX_CLI_DIAGNOSTIC_DETAIL_BYTES = 512;
+
+const TRUNCATION_MARKER = "...[truncated]";
+const ESCAPE = String.fromCharCode(27);
+const ANSI_CSI_PATTERN = new RegExp(`${ESCAPE}\\[[0-?]*[ -/]*[@-~]`, "g");
+
+export type CliCommandScope = "root" | "run";
+
+export interface CliOutputWriter {
+  write(chunk: string): boolean | void;
+  readonly writableNeedDrain?: boolean;
+  once?(event: "drain", listener: () => void): unknown;
+}
+
+export class CliUsageError extends Error {
+  constructor(
+    message: string,
+    readonly scope: CliCommandScope,
+  ) {
+    super(message);
+    this.name = "CliUsageError";
+  }
+}
+
+export function renderUsageError(error: CliUsageError): string {
+  const hint =
+    error.scope === "run"
+      ? 'Run "tinker run --help" for usage.'
+      : 'Run "tinker --help" for usage.';
+  return `error: ${sanitizeDiagnosticDetail(error.message)}\n${hint}\n`;
+}
+
+export function renderCliFailure(label: string, error: unknown): string {
+  return `${label}: ${sanitizeDiagnosticDetail(errorMessage(error))}\n`;
+}
+
+export function sanitizeDiagnosticDetail(detail: string): string {
+  const withoutAnsi = detail.replaceAll(ANSI_CSI_PATTERN, "");
+  let escaped = "";
+  for (const character of withoutAnsi) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint === undefined) {
+      continue;
+    }
+    if (character === "\n") {
+      escaped += "\\n";
+    } else if (character === "\r") {
+      escaped += "\\r";
+    } else if (character === "\t") {
+      escaped += "\\t";
+    } else if (codePoint < 0x20 || (codePoint >= 0x7f && codePoint <= 0x9f)) {
+      escaped += `\\u${codePoint.toString(16).padStart(4, "0")}`;
+    } else {
+      escaped += character;
+    }
+  }
+  return truncateUtf8(escaped, MAX_CLI_DIAGNOSTIC_DETAIL_BYTES);
+}
+
+export function formatDiagnosticPath(filePath: string): string {
+  return sanitizeDiagnosticDetail(JSON.stringify(filePath));
+}
+
+export async function writeCliOutput(
+  writer: CliOutputWriter,
+  output: string,
+): Promise<void> {
+  if (output === "") {
+    return;
+  }
+  const accepted = writer.write(output);
+  if (accepted === false) {
+    await waitForDrain(writer);
+  }
+}
+
+export async function flushCliOutput(writer: CliOutputWriter): Promise<void> {
+  if (writer.writableNeedDrain === true) {
+    await waitForDrain(writer);
+  }
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value) <= maxBytes) {
+    return value;
+  }
+
+  const contentLimit = maxBytes - Buffer.byteLength(TRUNCATION_MARKER);
+  let result = "";
+  let byteLength = 0;
+  for (const character of value) {
+    const characterBytes = Buffer.byteLength(character);
+    if (byteLength + characterBytes > contentLimit) {
+      break;
+    }
+    result += character;
+    byteLength += characterBytes;
+  }
+  return result + TRUNCATION_MARKER;
+}
+
+function waitForDrain(writer: CliOutputWriter): Promise<void> {
+  if (writer.once === undefined) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    writer.once?.("drain", resolve);
+  });
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/cli/package-metadata.ts

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+
+export type PackageMetadata = {
+  readonly name: string;
+  readonly version: string;
+};
+
+export class PackageMetadataError extends Error {
+  constructor() {
+    super("Tinker package metadata is unavailable.");
+    this.name = "PackageMetadataError";
+  }
+}
+
+export async function loadPackageMetadata(
+  packageJsonUrl = new URL("../../package.json", import.meta.url),
+): Promise<PackageMetadata> {
+  try {
+    const parsed = JSON.parse(await readFile(packageJsonUrl, "utf8")) as unknown;
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      !("name" in parsed) ||
+      typeof parsed.name !== "string" ||
+      parsed.name.trim() === "" ||
+      !("version" in parsed) ||
+      typeof parsed.version !== "string" ||
+      parsed.version.trim() === ""
+    ) {
+      throw new TypeError("Invalid package metadata.");
+    }
+    return Object.freeze({ name: parsed.name, version: parsed.version });
+  } catch {
+    throw new PackageMetadataError();
+  }
+}