tinker-agent 1.2.1 → 1.4.0

package/src/agent/loop.ts

@@ -2,7 +2,9 @@ import {
   materializeModelRequest,
   type MaterializedModelRequest,
   type ModelClient,
+  type ModelRequestOutput,
   type PreparedModelRequest,
+  ProviderResponseError,
 } from "../model/model-client";
 import type { ImageAssetStore } from "../image/image-asset-store";
 import {
@@ -83,6 +85,8 @@ export class FatalAgentTurnError extends Error {
   }
 }
 
+const MODEL_REQUEST_MAX_ATTEMPTS = 2 as const;
+
 export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
   let lastIteration: IterationIdentity | undefined;
   const committedPrefixAuditor =
@@ -202,21 +206,15 @@ export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
     await input.runtimeSession.append({
       type: "model.request.started",
       ...iteration,
-      data: {},
+      data: {
+        attemptNumber: 1,
+        maxAttempts: MODEL_REQUEST_MAX_ATTEMPTS,
+      },
     });
 
-    let modelOutput;
     try {
       throwIfTurnCancelled(input.signal);
       input.runtimeSession.prepareModelDispatch?.({ iteration, built });
-      modelOutput = await input.model.request(request, {
-        signal: input.signal,
-        identity: {
-          iteration,
-          runtimeSession: input.runtimeSession,
-        },
-      });
-      throwIfTurnCancelled(input.signal);
     } catch (error) {
       if (input.signal.aborted) {
         return cancelledResult(
@@ -228,6 +226,82 @@ export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
       return failedResult(error, iteration);
     }
 
+    const requestOptions = {
+      signal: input.signal,
+      identity: {
+        iteration,
+        runtimeSession: input.runtimeSession,
+      },
+    };
+    let modelOutput: ModelRequestOutput | undefined;
+    let successfulAttempt: 1 | 2 | undefined;
+    for (const attemptNumber of [1, 2] as const) {
+      if (input.signal.aborted) {
+        return cancelledResult(
+          cancellation(input.signal, iteration, "model_request"),
+          iteration,
+        );
+      }
+      if (attemptNumber === 2) {
+        await input.runtimeSession.append({
+          type: "model.request.started",
+          ...iteration,
+          data: {
+            attemptNumber,
+            maxAttempts: MODEL_REQUEST_MAX_ATTEMPTS,
+          },
+        });
+      }
+
+      try {
+        throwIfTurnCancelled(input.signal);
+        modelOutput = await input.model.request(request, requestOptions);
+        throwIfTurnCancelled(input.signal);
+        successfulAttempt = attemptNumber;
+        break;
+      } catch (error) {
+        if (input.signal.aborted) {
+          return cancelledResult(
+            cancellation(input.signal, iteration, "model_request"),
+            iteration,
+          );
+        }
+
+        const reasoningOnly = isReasoningOnlyProviderError(error);
+        const retryDisposition = reasoningOnly
+          ? attemptNumber === 1
+            ? "scheduled"
+            : "exhausted"
+          : "not_retryable";
+        await input.runtimeSession.append({
+          type: "model.request.failed",
+          ...iteration,
+          data: modelRequestFailureData({
+            error,
+            request,
+            attemptNumber,
+            retryDisposition,
+          }),
+        });
+
+        if (retryDisposition === "scheduled") {
+          continue;
+        }
+        if (retryDisposition === "exhausted") {
+          return failedResult(
+            new Error(
+              `Provider returned reasoning without final text or tool calls in both attempts (provider=${request.provider}, model=${request.model}).`,
+            ),
+            iteration,
+          );
+        }
+        return failedResult(error, iteration);
+      }
+    }
+    if (modelOutput === undefined || successfulAttempt === undefined) {
+      throw new Error("Model request attempt state completed without an output.");
+    }
+
     try {
       input.ledger.appendAssistant({
         iteration,
@@ -245,7 +319,11 @@ export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
     await input.runtimeSession.append({
       type: "model.request.finished",
       ...iteration,
-      data: { output: modelOutput },
+      data: {
+        attemptNumber: successfulAttempt,
+        maxAttempts: MODEL_REQUEST_MAX_ATTEMPTS,
+        output: modelOutput,
+      },
     });
     const measured = input.contextMeter.recordProviderUsage(request, modelOutput);
     await input.runtimeSession.append({
@@ -617,6 +695,32 @@ function failedResult(
   };
 }
 
+function isReasoningOnlyProviderError(error: unknown): error is ProviderResponseError {
+  return (
+    error instanceof ProviderResponseError && error.code === "reasoning_only_assistant"
+  );
+}
+
+function modelRequestFailureData(input: {
+  error: unknown;
+  request: PreparedModelRequest;
+  attemptNumber: 1 | 2;
+  retryDisposition: "scheduled" | "not_retryable" | "exhausted";
+}) {
+  const providerError =
+    input.error instanceof ProviderResponseError ? input.error : undefined;
+  return {
+    attemptNumber: input.attemptNumber,
+    maxAttempts: MODEL_REQUEST_MAX_ATTEMPTS,
+    code: providerError?.code ?? ("provider_request_error" as const),
+    retryDisposition: input.retryDisposition,
+    provider: input.request.provider,
+    model: input.request.model,
+    error: errorMessage(input.error),
+    ...(providerError === undefined ? {} : { diagnostics: providerError.diagnostics }),
+  };
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/src/agent/runtime-session.ts

@@ -92,6 +92,7 @@ import { TurnCancelledError } from "./turn-cancellation";
 import type { ToolCompletionInput } from "../context/protocol-frame";
 import type { BuiltContextRequest } from "../context/context-revision";
 import type { CommittedToolCompletion } from "./session-ledger";
+import type { PublicToolingConfig } from "../cli/public-config-contract";
 import type {
   IterationIdentity,
   RunAgentResult,
@@ -231,6 +232,7 @@ type CommonRuntimeSessionInput = {
         observationLogPath?: string;
       };
   webFetchRefiner?: Refiner;
+  toolingConfig?: PublicToolingConfig;
 };
 
 type CreateNewRuntimeSessionInput = CommonRuntimeSessionInput & {
@@ -531,6 +533,7 @@ class DefaultRuntimeSession implements RuntimeSession {
         runtimeSession: session.context,
         historyReader: store.historyReader(),
         webFetchRefiner: input.webFetchRefiner,
+        toolingConfig: input.toolingConfig,
         ...(session.skillCatalog.skills.size === 0
           ? {}
           : {
@@ -544,6 +547,8 @@ class DefaultRuntimeSession implements RuntimeSession {
         session.mcpManager = await dependencies.createMcpManager({
           config: mcpConfig,
           runtimeSession: session.context,
+          timeoutMs: input.toolingConfig?.mcpTimeoutMs,
+          maxObservationChars: input.toolingConfig?.mcpMaxObservationChars,
         });
         for (const executor of session.mcpManager.executors) {
           session.tooling.registry.register(executor, "MCP");
@@ -870,7 +875,7 @@ class DefaultRuntimeSession implements RuntimeSession {
     return this.input.modelClient.inputModalities?.includes("image") === true;
   }
 
-  importImage(
+  async importImage(
     sourcePath: string,
     signal: AbortSignal,
     prospectiveMessageImageCount: number,
@@ -878,9 +883,6 @@ class DefaultRuntimeSession implements RuntimeSession {
     if (this.state !== "ready") {
       throw new Error(`Cannot import an image while RuntimeSession is ${this.state}.`);
     }
-    if (!this.supportsImageInput()) {
-      throw new Error("Current model profile does not support image input.");
-    }
     if (
       !Number.isSafeInteger(prospectiveMessageImageCount) ||
       prospectiveMessageImageCount < 1 ||
@@ -888,18 +890,35 @@ class DefaultRuntimeSession implements RuntimeSession {
     ) {
       throw new Error("Prospective Prompt image count is invalid.");
     }
-    const activeImageCount = this.input.modelClient.prepare(
-      this.requireLedger().buildCommittedModelRequest(
-        this.requireTooling().registry.definitions(),
-      ).request,
-    ).mediaOccurrenceCount;
-    const aggregateImageCount = activeImageCount + prospectiveMessageImageCount;
-    if (aggregateImageCount > IMAGE_INPUT_POLICY.maxImagesPerRequest) {
-      throw new ModelRequestMediaAggregateError(
-        `Model request would have ${aggregateImageCount} images; maximum is ${IMAGE_INPUT_POLICY.maxImagesPerRequest}.`,
-      );
+    const assertImageAllowed = () => {
+      if (this.state !== "ready") {
+        throw new Error(
+          `Cannot import an image while RuntimeSession is ${this.state}.`,
+        );
+      }
+      if (!this.supportsImageInput()) {
+        throw new Error("Current model profile does not support image input.");
+      }
+      const activeImageCount = this.input.modelClient.prepare(
+        this.requireLedger().buildCommittedModelRequest(
+          this.requireTooling().registry.definitions(),
+        ).request,
+      ).mediaOccurrenceCount;
+      const aggregateImageCount = activeImageCount + prospectiveMessageImageCount;
+      if (aggregateImageCount > IMAGE_INPUT_POLICY.maxImagesPerRequest) {
+        throw new ModelRequestMediaAggregateError(
+          `Model request would have ${aggregateImageCount} images; maximum is ${IMAGE_INPUT_POLICY.maxImagesPerRequest}.`,
+        );
+      }
+    };
+
+    if (this.supportsImageInput()) {
+      assertImageAllowed();
     }
-    return this.assetStore.importWorkspaceFile(sourcePath, { signal });
+    return this.assetStore.importWorkspaceFile(sourcePath, {
+      signal,
+      accept: assertImageAllowed,
+    });
   }
 
   async verifyImageAssets(

package/src/cli/command-line.ts

@@ -0,0 +1,291 @@
+import { Command, CommanderError } from "commander";
+import { PUBLIC_CLI_CONTRACT } from "./public-cli-contract";
+import type { PromptSource } from "./prompt-source";
+import { CliUsageError, type CliCommandScope } from "./output";
+
+export type CliCommand =
+  | { readonly type: "tui"; readonly profileName?: string }
+  | {
+      readonly type: "run";
+      readonly profileName?: string;
+      readonly promptSource: PromptSource;
+    };
+
+export type CommandLineResult =
+  | { readonly type: "command"; readonly command: CliCommand }
+  | {
+      readonly type: "terminal";
+      readonly stdout: string;
+      readonly stderr: string;
+    };
+
+const SUCCESSFUL_TERMINAL_CODES = new Set([
+  "commander.help",
+  "commander.helpDisplayed",
+  "commander.version",
+]);
+
+export async function parseCommandLine(
+  args: readonly string[],
+  packageVersion: string,
+): Promise<CommandLineResult> {
+  const scopeHint = preflightArgv(args);
+  let stdout = "";
+  let stderr = "";
+  let selectedCommand: CliCommand | undefined;
+  const contract = PUBLIC_CLI_CONTRACT;
+
+  const program = new Command()
+    .name(contract.name)
+    .description(contract.description)
+    .helpOption(contract.helpFlags)
+    .version(packageVersion, contract.versionFlags)
+    .option(contract.tui.profileOption.flags, contract.tui.profileOption.description)
+    .helpCommand(contract.helpCommand.command, contract.helpCommand.description)
+    .showHelpAfterError('Run "tinker --help" for usage.')
+    .showSuggestionAfterError(false)
+    .allowExcessArguments(false)
+    .enablePositionalOptions()
+    .exitOverride()
+    .configureOutput({
+      writeOut: (value) => {
+        stdout += value;
+      },
+      writeErr: (value) => {
+        stderr += value;
+      },
+    });
+
+  program.action(() => {
+    const { profile } = program.opts<{ profile?: string }>();
+    selectedCommand = Object.freeze({
+      type: "tui",
+      ...(profile === undefined
+        ? {}
+        : { profileName: validateProfile(profile, "root") }),
+    });
+  });
+
+  program
+    .command(contract.run.command)
+    .description(contract.run.description)
+    .option(contract.run.profileOption.flags, contract.run.profileOption.description)
+    .option(contract.run.stdinOption.flags, contract.run.stdinOption.description)
+    .option(contract.run.fileOption.flags, contract.run.fileOption.description)
+    .addHelpText("after", `\n${contract.run.helpAfter}\n`)
+    .showHelpAfterError('Run "tinker run --help" for usage.')
+    .showSuggestionAfterError(false)
+    .allowExcessArguments(false)
+    .exitOverride()
+    .action(
+      (
+        prompt: string | undefined,
+        options: { profile?: string; stdin?: boolean; file?: string },
+      ) => {
+        const sources: PromptSource[] = [];
+        if (prompt !== undefined) {
+          sources.push({ kind: "argument", value: prompt });
+        }
+        if (options.stdin === true) {
+          sources.push({ kind: "stdin" });
+        }
+        if (options.file !== undefined) {
+          if (options.file.length === 0) {
+            throw new CliUsageError("--file requires a non-empty path.", "run");
+          }
+          sources.push({ kind: "file", filePath: options.file });
+        }
+        if (sources.length === 0) {
+          throw new CliUsageError(
+            "Exactly one prompt source is required: [prompt], --stdin, or --file <path>.",
+            "run",
+          );
+        }
+        if (sources.length > 1) {
+          throw new CliUsageError(
+            "Prompt sources are mutually exclusive: use [prompt], --stdin, or --file <path>.",
+            "run",
+          );
+        }
+        const promptSource = sources[0];
+        if (promptSource === undefined) {
+          throw new CliUsageError("A prompt source is required.", "run");
+        }
+        selectedCommand = Object.freeze({
+          type: "run",
+          ...(options.profile === undefined
+            ? {}
+            : { profileName: validateProfile(options.profile, "run") }),
+          promptSource,
+        });
+      },
+    );
+
+  try {
+    await program.parseAsync([...args], { from: "user" });
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      throw error;
+    }
+    if (error instanceof CommanderError) {
+      if (SUCCESSFUL_TERMINAL_CODES.has(error.code)) {
+        return Object.freeze({ type: "terminal", stdout, stderr });
+      }
+      throw new CliUsageError(commanderErrorDetail(error), scopeHint);
+    }
+    throw error;
+  }
+
+  if (selectedCommand === undefined) {
+    throw new Error("Commander completed without selecting a command.");
+  }
+  const topLevelProfile = program.opts<{ profile?: string }>().profile;
+  if (selectedCommand.type === "run" && topLevelProfile !== undefined) {
+    throw new CliUsageError(
+      "The top-level --profile option only applies to the TUI; place --profile after run.",
+      "run",
+    );
+  }
+  return Object.freeze({ type: "command", command: selectedCommand });
+}
+
+function preflightArgv(args: readonly string[]): CliCommandScope {
+  let scope: CliCommandScope = "root";
+  let rootBlocked = false;
+  let topProfileOccurrences = 0;
+  let runProfileOccurrences = 0;
+  let stdinOccurrences = 0;
+  let fileOccurrences = 0;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === undefined || token === "--") {
+      break;
+    }
+
+    if (
+      (!rootBlocked && scope === "root" && isRootTerminalOption(token)) ||
+      (scope === "run" && isRunTerminalOption(token))
+    ) {
+      return scope;
+    }
+
+    if (scope === "root" && !rootBlocked) {
+      const profile = readOptionOccurrence(
+        args,
+        index,
+        token,
+        "--profile",
+        "root",
+        "-p",
+      );
+      if (profile !== undefined) {
+        topProfileOccurrences += 1;
+        assertSingleOccurrence("--profile", topProfileOccurrences, "root");
+        validateProfile(profile.value, "root");
+        index += profile.consumedNext ? 1 : 0;
+        continue;
+      }
+      if (token.startsWith("-")) {
+        rootBlocked = true;
+        continue;
+      }
+      if (token === "run") {
+        scope = "run";
+        continue;
+      }
+      if (token === "help") {
+        return "root";
+      }
+      throw new CliUsageError(`unknown command '${token}'`, "root");
+    }
+
+    if (scope !== "run") {
+      continue;
+    }
+    const profile = readOptionOccurrence(args, index, token, "--profile", "run", "-p");
+    if (profile !== undefined) {
+      runProfileOccurrences += 1;
+      assertSingleOccurrence("--profile", runProfileOccurrences, "run");
+      validateProfile(profile.value, "run");
+      index += profile.consumedNext ? 1 : 0;
+      continue;
+    }
+    const file = readOptionOccurrence(args, index, token, "--file", "run");
+    if (file !== undefined) {
+      fileOccurrences += 1;
+      assertSingleOccurrence("--file", fileOccurrences, "run");
+      if (file.value.length === 0) {
+        throw new CliUsageError("--file requires a non-empty path.", "run");
+      }
+      index += file.consumedNext ? 1 : 0;
+      continue;
+    }
+    if (token === "--stdin") {
+      stdinOccurrences += 1;
+      assertSingleOccurrence("--stdin", stdinOccurrences, "run");
+    }
+  }
+  return scope;
+}
+
+function readOptionOccurrence(
+  args: readonly string[],
+  index: number,
+  token: string,
+  longName: string,
+  scope: CliCommandScope,
+  shortName?: string,
+): { readonly value: string; readonly consumedNext: boolean } | undefined {
+  if (token === longName || token === shortName) {
+    const next = args[index + 1];
+    if (next === undefined || next.startsWith("-")) {
+      throw new CliUsageError(`option '${token}' argument missing`, scope);
+    }
+    return { value: next, consumedNext: true };
+  }
+  const longPrefix = `${longName}=`;
+  if (token.startsWith(longPrefix)) {
+    return { value: token.slice(longPrefix.length), consumedNext: false };
+  }
+  if (
+    shortName !== undefined &&
+    token.startsWith(shortName) &&
+    token !== shortName &&
+    !token.startsWith("--")
+  ) {
+    return { value: token.slice(shortName.length), consumedNext: false };
+  }
+  return undefined;
+}
+
+function validateProfile(value: string, scope: CliCommandScope): string {
+  if (value.trim() === "") {
+    throw new CliUsageError("--profile requires a non-empty value.", scope);
+  }
+  return value;
+}
+
+function assertSingleOccurrence(
+  option: string,
+  count: number,
+  scope: CliCommandScope,
+): void {
+  if (count > 1) {
+    throw new CliUsageError(`${option} may only be specified once.`, scope);
+  }
+}
+
+function isRootTerminalOption(token: string): boolean {
+  return (
+    token === "--help" || token === "-h" || token === "--version" || token === "-V"
+  );
+}
+
+function isRunTerminalOption(token: string): boolean {
+  return token === "--help" || token === "-h";
+}
+
+function commanderErrorDetail(error: CommanderError): string {
+  return error.message.replace(/^error:\s*/u, "");
+}