tinker-agent 1.3.0 → 1.5.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,18 @@
-import path from "node:path";
 import { readFile, rename, unlink, writeFile } from "node:fs/promises";
 import {
   createModelContextProfile,
   type ModelContextProfile,
 } from "../model/model-context-profile";
+import {
+  MEMORY_CONFIG_FIELDS,
+  MEMORY_EMBEDDING_FIELDS,
+  MODEL_PROFILE_FIELDS,
+  MODEL_PROFILES_DOCUMENT_FIELDS,
+  MODEL_TOKEN_ESTIMATOR_FIELDS,
+  type ModelTokenEstimatorKind,
+  type ModelTokenEstimatorMaxRetries,
+} from "./public-config-contract";
+import type { MemoryEmbeddingConfig } from "../memory/contracts";
 
 export type ModelProfile = {
   readonly name: string;
@@ -21,37 +30,26 @@ 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 = {
   readonly defaultProfile: string;
   readonly profiles: ReadonlyMap<string, ModelProfile>;
+  readonly memory?: MemoryConfig;
 };
 
-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 type MemoryConfig = {
+  readonly profile: string;
+  readonly embedding: MemoryEmbeddingConfig;
+};
 
+export async function loadModelProfiles(configPath: string): Promise<ModelProfiles> {
   let raw: string;
   try {
     raw = await readFile(configPath, "utf8");
@@ -67,13 +65,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 +121,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() === "") {
@@ -155,7 +153,15 @@ export function parseModelProfiles(raw: string, sourcePath: string): ModelProfil
     profiles.set(profileName, parseProfile(profileName, profileValue, sourcePath));
   }
 
-  return { defaultProfile, profiles };
+  const memory =
+    json.memory === undefined
+      ? undefined
+      : parseMemoryConfig(json.memory, profiles, sourcePath);
+  return Object.freeze({
+    defaultProfile,
+    profiles,
+    ...(memory === undefined ? {} : { memory }),
+  });
 }
 
 export function resolveModelProfile(
@@ -238,45 +244,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,
@@ -311,12 +303,63 @@ function parseProfile(
   });
 }
 
+function parseMemoryConfig(
+  value: unknown,
+  profiles: ReadonlyMap<string, ModelProfile>,
+  sourcePath: string,
+): MemoryConfig {
+  const where = `Model profiles ${sourcePath}: "memory"`;
+  if (!isRecord(value)) {
+    throw new Error(`${where} must be an object.`);
+  }
+  assertKnownKeys(
+    value,
+    MEMORY_CONFIG_FIELDS.map((field) => field.name),
+    where,
+  );
+  const profile = requireString(value.profile, `${where}.profile`);
+  if (!profiles.has(profile)) {
+    throw unknownProfileNamesError(profile, [...profiles.keys()]);
+  }
+  const embedding = parseMemoryEmbedding(value.embedding, `${where}.embedding`);
+  return Object.freeze({ profile, embedding });
+}
+
+function parseMemoryEmbedding(value: unknown, where: string): MemoryEmbeddingConfig {
+  if (!isRecord(value)) {
+    throw new Error(`${where} must be an object.`);
+  }
+  assertKnownKeys(
+    value,
+    MEMORY_EMBEDDING_FIELDS.map((field) => field.name),
+    where,
+  );
+  const name = requireString(value.name, `${where}.name`);
+  if (value.kind !== "openai-compatible") {
+    throw new Error(`${where}.kind must be "openai-compatible".`);
+  }
+  const model = requireString(value.model, `${where}.model`);
+  const apiBase = requireString(value.apiBase, `${where}.apiBase`);
+  requireHttpUrl(apiBase, `${where}.apiBase`);
+  const apiKey = requireString(value.apiKey, `${where}.apiKey`);
+  const dimensions = requirePositiveInteger(value.dimensions, `${where}.dimensions`);
+  return Object.freeze({
+    name,
+    kind: "openai-compatible",
+    model,
+    apiBase,
+    apiKey,
+    dimensions,
+  });
+}
+
 function parseInputModalities(
   value: unknown,
   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 +388,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[],
@@ -401,6 +539,22 @@ function requirePositiveInteger(value: unknown, name: string): number {
   return value;
 }
 
+function requireHttpUrl(value: string, name: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`${name} must be a valid HTTP(S) URL.`);
+  }
+  if (
+    (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+    parsed.username !== "" ||
+    parsed.password !== ""
+  ) {
+    throw new Error(`${name} must be a valid HTTP(S) URL.`);
+  }
+}
+
 function parseBoolean(value: unknown, name: string): boolean {
   if (typeof value === "boolean") {
     return value;