tinker-agent 1.3.0 → 1.5.0

package/src/agent/runtime-session.ts

@@ -13,6 +13,7 @@ import {
   runtimeIdFactory,
   type RuntimeIdFactory,
   type SessionId,
+  type TurnId,
 } from "../ids/runtime-id";
 import { loadMcpConfig } from "../mcp/mcp-config";
 import {
@@ -71,11 +72,13 @@ import {
   renderedMessageHash,
 } from "../context/compiled-context-hash";
 import { createDefaultTooling, type DefaultTooling } from "../tools/registry";
+import type { ToolExecutor } from "../tools/types";
 import type { Refiner } from "../tools/web-fetch/refiner";
 import type { ProjectInstructionManifest } from "../instructions/project-instructions";
 import {
   SessionStore,
   createSessionCompatibilityContract,
+  type CompletedTurnSnapshot,
   type SessionRecoveryResult,
   type StoredSkillActivation,
 } from "../session/session-store";
@@ -92,6 +95,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,
@@ -211,6 +215,25 @@ export type SkillsUpdateSummary = {
   readonly addedOverrideCount: number;
 };
 
+export type CompletedTurnHookInput = {
+  readonly workspaceRoot: string;
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+  readonly snapshot: CompletedTurnSnapshot;
+};
+
+export type CompletedTurnHookFailure = {
+  readonly workspaceRoot: string;
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+  readonly reason: "completed_turn_snapshot_failed" | "completed_turn_enqueue_failed";
+};
+
+export type CompletedTurnHook = {
+  enqueue(input: CompletedTurnHookInput): void;
+  recordFailure(input: CompletedTurnHookFailure): void;
+};
+
 type CommonRuntimeSessionInput = {
   workspaceRoot: string;
   modelName: string;
@@ -231,6 +254,9 @@ type CommonRuntimeSessionInput = {
         observationLogPath?: string;
       };
   webFetchRefiner?: Refiner;
+  toolingConfig?: PublicToolingConfig;
+  memorySearch?: ToolExecutor;
+  completedTurnHook?: CompletedTurnHook;
 };
 
 type CreateNewRuntimeSessionInput = CommonRuntimeSessionInput & {
@@ -531,6 +557,10 @@ class DefaultRuntimeSession implements RuntimeSession {
         runtimeSession: session.context,
         historyReader: store.historyReader(),
         webFetchRefiner: input.webFetchRefiner,
+        toolingConfig: input.toolingConfig,
+        ...(input.memorySearch === undefined
+          ? {}
+          : { memorySearch: input.memorySearch }),
         ...(session.skillCatalog.skills.size === 0
           ? {}
           : {
@@ -544,6 +574,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 +902,7 @@ class DefaultRuntimeSession implements RuntimeSession {
     return this.input.modelClient.inputModalities?.includes("image") === true;
   }
 
-  importImage(
+  async importImage(
     sourcePath: string,
     signal: AbortSignal,
     prospectiveMessageImageCount: number,
@@ -878,9 +910,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 +917,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(
@@ -1698,6 +1744,9 @@ class DefaultRuntimeSession implements RuntimeSession {
       await this.appendTerminalEvent(turn, result, projectedMessageCount);
       pendingLedgerTurn.finish(result);
       settled = true;
+      if (result.status === "completed") {
+        this.notifyCompletedTurn(turn);
+      }
       await this.settleClosedTurnSkills();
       if (result.status === "completed") {
         await this.performAutomaticContextMaintenance();
@@ -1745,6 +1794,55 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
+  private notifyCompletedTurn(turn: TurnIdentity): void {
+    const hook = this.input.completedTurnHook;
+    if (hook === undefined) {
+      return;
+    }
+    let snapshot: CompletedTurnSnapshot;
+    try {
+      snapshot = this.store.readCompletedTurnSnapshot(turn.turnId);
+    } catch {
+      this.recordCompletedTurnHookFailure(
+        hook,
+        turn.turnId,
+        "completed_turn_snapshot_failed",
+      );
+      return;
+    }
+    try {
+      hook.enqueue({
+        workspaceRoot: this.input.workspaceRoot,
+        sessionId: this.sessionId,
+        turnId: turn.turnId,
+        snapshot,
+      });
+    } catch {
+      this.recordCompletedTurnHookFailure(
+        hook,
+        turn.turnId,
+        "completed_turn_enqueue_failed",
+      );
+    }
+  }
+
+  private recordCompletedTurnHookFailure(
+    hook: CompletedTurnHook,
+    turnId: TurnId,
+    reason: CompletedTurnHookFailure["reason"],
+  ): void {
+    try {
+      hook.recordFailure({
+        workspaceRoot: this.input.workspaceRoot,
+        sessionId: this.sessionId,
+        turnId,
+        reason,
+      });
+    } catch {
+      // Optional completed-turn integrations never fault a committed turn.
+    }
+  }
+
   private async performAutomaticCompaction(
     qualificationId: string,
   ): Promise<ContextCompactionResult | undefined> {

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, "");
+}