tinker-agent 1.11.0 → 2.1.0

package/src/cli/config.ts

@@ -12,9 +12,9 @@ import {
   persistDefaultProfile,
   profileToContextProfile,
   type ModelInputModality,
+  type ToolResultModality,
   type ModelProfile,
   type ModelProfiles,
-  type ModelTokenEstimatorProfile,
   unknownProfileError,
 } from "./model-profiles";
 import type { MemoryEmbeddingConfig } from "../memory/contracts";
@@ -40,7 +40,7 @@ export type RunnerConfig = {
   readonly contextBudget: ModelContextBudget;
   readonly profileName?: string;
   readonly inputModalities: readonly ModelInputModality[];
-  readonly tokenEstimator?: ModelTokenEstimatorProfile;
+  readonly toolResultModalities: readonly ToolResultModality[];
   readonly bashGuardMode: "guard" | "yolo";
   readonly bashGuardSource: "default" | "environment" | "cli";
 };
@@ -182,11 +182,9 @@ function runnerConfigTemplateFromProfile(
     contextBudget: deriveModelContextBudget(contextProfile),
     profileName: profile.name,
     inputModalities: profile.inputModalities,
+    toolResultModalities: profile.toolResultModalities,
     bashGuardMode: environment.bashGuardMode,
     bashGuardSource: environment.bashGuardSource,
-    ...(profile.tokenEstimator === undefined
-      ? {}
-      : { tokenEstimator: profile.tokenEstimator }),
   });
 }
 
@@ -210,6 +208,7 @@ function runnerConfigTemplateFromEnvironment(
     contextProfile,
     contextBudget: deriveModelContextBudget(contextProfile),
     inputModalities: Object.freeze(["text"] as const),
+    toolResultModalities: Object.freeze(["text"] as const),
     bashGuardMode: environment.bashGuardMode,
     bashGuardSource: environment.bashGuardSource,
   });

package/src/cli/model-profiles.ts

@@ -10,12 +10,10 @@ import {
   MODEL_PROFILE_FIELDS,
   MODEL_PROFILES_DOCUMENT_FIELDS,
   MODEL_REASONING_FIELDS,
-  MODEL_TOKEN_ESTIMATOR_FIELDS,
-  type ModelTokenEstimatorKind,
-  type ModelTokenEstimatorMaxRetries,
 } from "./public-config-contract";
 import type { MemoryEmbeddingConfig } from "../memory/contracts";
 import type { ReasoningEffortConfig } from "../model/reasoning-effort";
+import type { ModelInputModality, ToolResultModality } from "../model/model-client";
 
 export type ModelProfile = {
   readonly name: string;
@@ -29,19 +27,9 @@ export type ModelProfile = {
   readonly includeReasoningContent: boolean;
   readonly stream: boolean;
   readonly inputModalities: readonly ModelInputModality[];
-  readonly tokenEstimator?: ModelTokenEstimatorProfile;
-};
-
-export type ModelInputModality = "text" | "image";
-
-export type ModelTokenEstimatorProfile = {
-  readonly kind: ModelTokenEstimatorKind;
-  readonly model: string;
-  readonly apiBase: string;
-  readonly apiKey: string;
-  readonly timeoutMs: number;
-  readonly maxRetries: ModelTokenEstimatorMaxRetries;
+  readonly toolResultModalities: readonly ToolResultModality[];
 };
+export type { ModelInputModality, ToolResultModality } from "../model/model-client";
 
 export type ModelProfiles = {
   readonly defaultProfile: string;
@@ -285,16 +273,15 @@ function parseProfile(
     value.inputModalities,
     `${where}: "inputModalities"`,
   );
-  const tokenEstimator =
-    value.tokenEstimator === undefined
-      ? undefined
-      : parseTokenEstimator(value.tokenEstimator, `${where}: "tokenEstimator"`);
-  if (inputModalities.includes("image") && tokenEstimator === undefined) {
+  const toolResultModalities = parseToolResultModalities(
+    value.toolResultModalities,
+    `${where}: "toolResultModalities"`,
+  );
+  if (toolResultModalities.includes("image") && !inputModalities.includes("image")) {
     throw new Error(
-      `${where}: image input requires a complete "tokenEstimator" configuration.`,
+      `${where}: "toolResultModalities" cannot include "image" unless "inputModalities" also includes "image".`,
     );
   }
-
   createModelContextProfile({
     contextWindowTokens,
     maxSupportedOutputTokens,
@@ -312,10 +299,38 @@ function parseProfile(
     includeReasoningContent,
     stream,
     inputModalities,
-    ...(tokenEstimator === undefined ? {} : { tokenEstimator }),
+    toolResultModalities,
   });
 }
 
+function parseToolResultModalities(
+  value: unknown,
+  name: string,
+): readonly ToolResultModality[] {
+  if (value === undefined) {
+    return modelProfileField("toolResultModalities").defaultValue;
+  }
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`${name} must be a non-empty array.`);
+  }
+  const modalities = value.map((rawEntry): ToolResultModality => {
+    const entry: unknown = rawEntry;
+    if (entry !== "text" && entry !== "image") {
+      throw new Error(`${name} contains an unsupported modality.`);
+    }
+    return entry;
+  });
+  if (new Set(modalities).size !== modalities.length) {
+    throw new Error(`${name} must not contain duplicates.`);
+  }
+  if (!modalities.includes("text")) {
+    throw new Error(`${name} must include "text".`);
+  }
+  return Object.freeze(
+    modalities.includes("image") ? (["text", "image"] as const) : (["text"] as const),
+  );
+}
+
 function parseReasoning(value: unknown, where: string): ReasoningEffortConfig {
   if (!isRecord(value)) {
     throw new Error(`${where} must be an object.`);
@@ -434,54 +449,7 @@ function parseInputModalities(
   );
 }
 
-function parseTokenEstimator(value: unknown, name: string): ModelTokenEstimatorProfile {
-  if (!isRecord(value)) {
-    throw new Error(`${name} must be an object.`);
-  }
-  assertKnownKeys(
-    value,
-    MODEL_TOKEN_ESTIMATOR_FIELDS.map((field) => field.name),
-    name,
-  );
-  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 timeoutMs = requirePositiveInteger(value.timeoutMs, `${name}.timeoutMs`);
-  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}.`,
-    );
-  }
-  const maxRetriesField = tokenEstimatorField("maxRetries");
-  if (value.maxRetries !== maxRetriesField.literalValue) {
-    throw new Error(`${name}.maxRetries must be ${maxRetriesField.literalValue}.`);
-  }
-  return Object.freeze({
-    kind: kindField.literalValue,
-    model,
-    apiBase,
-    apiKey,
-    timeoutMs,
-    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,
@@ -496,21 +464,6 @@ function modelProfileField<Name extends ModelProfileFieldName>(
   >;
 }
 
-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",
@@ -555,18 +508,6 @@ function parseProfileBoolean(
     : 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/public-config-contract.ts

@@ -1,3 +1,4 @@
+import os from "node:os";
 import path from "node:path";
 import { rgPath } from "@vscode/ripgrep";
 import { parseModelApi, type ModelApi } from "../model/model-api";
@@ -29,7 +30,7 @@ export const PUBLIC_CONFIG_FIELDS = Object.freeze([
     secret: false,
     section: "model",
     description:
-      "Optional model profiles JSON path. Relative paths resolve from the process cwd.",
+      "Optional model profiles JSON path. A leading ~ expands to the home directory; other relative paths resolve from the process cwd.",
   }),
   publicField({
     name: "TINKER_MODEL",
@@ -126,7 +127,8 @@ export const PUBLIC_CONFIG_FIELDS = Object.freeze([
     defaultSource: "process-cwd",
     secret: false,
     section: "workspace",
-    description: "Workspace path. Relative paths resolve from the process cwd.",
+    description:
+      "Workspace path. A leading ~ expands to the home directory; other relative paths resolve from the process cwd.",
   }),
   publicField({
     name: "TINKER_MAX_ITERATIONS",
@@ -245,8 +247,8 @@ export type ModelProfileField = {
   readonly valueKind:
     | PublicConfigValueKind
     | "input-modalities"
-    | "reasoning"
-    | "token-estimator";
+    | "tool-result-modalities"
+    | "reasoning";
   readonly required: boolean;
   readonly defaultValue?: string | number | boolean | readonly string[];
   readonly secret: boolean;
@@ -338,11 +340,13 @@ export const MODEL_PROFILE_FIELDS = Object.freeze([
       'Accepted model input modalities; normalizes to ["text"] or ["text", "image"].',
   }),
   profileField({
-    name: "tokenEstimator",
-    valueKind: "token-estimator",
+    name: "toolResultModalities",
+    valueKind: "tool-result-modalities",
     required: false,
-    secret: true,
-    description: "Independent token estimator required for image profiles.",
+    defaultValue: Object.freeze(["text"] as const),
+    secret: false,
+    description:
+      'Accepted tool-result modalities; normalizes to ["text"] or ["text", "image"].',
   }),
 ]);
 
@@ -375,82 +379,6 @@ export const MODEL_REASONING_FIELDS = Object.freeze([
   }),
 ]);
 
-export type ModelTokenEstimatorField = {
-  readonly name: string;
-  readonly valueKind: PublicConfigValueKind | "literal-string" | "literal-number";
-  readonly required: true;
-  readonly secret: boolean;
-  readonly literalValue?: string | number;
-  readonly minimum?: number;
-  readonly maximum?: number;
-  readonly description: string;
-};
-
-function estimatorField<const T extends ModelTokenEstimatorField>(
-  field: T,
-): Readonly<T> {
-  return Object.freeze(field);
-}
-
-export const MODEL_TOKEN_ESTIMATOR_FIELDS = Object.freeze([
-  estimatorField({
-    name: "kind",
-    valueKind: "literal-string",
-    required: true,
-    secret: false,
-    literalValue: "moonshot-estimate-token-count-v1",
-    description: "Estimator protocol discriminator.",
-  }),
-  estimatorField({
-    name: "model",
-    valueKind: "non-empty-string",
-    required: true,
-    secret: false,
-    description: "Estimator model name.",
-  }),
-  estimatorField({
-    name: "apiBase",
-    valueKind: "non-empty-string",
-    required: true,
-    secret: false,
-    description: "Estimator API base URL.",
-  }),
-  estimatorField({
-    name: "apiKey",
-    valueKind: "non-empty-string",
-    required: true,
-    secret: true,
-    description: "Estimator API credential.",
-  }),
-  estimatorField({
-    name: "timeoutMs",
-    valueKind: "positive-integer",
-    required: true,
-    secret: false,
-    minimum: 1_000,
-    maximum: 60_000,
-    description: "Estimator request timeout in milliseconds.",
-  }),
-  estimatorField({
-    name: "maxRetries",
-    valueKind: "literal-number",
-    required: true,
-    secret: false,
-    literalValue: 0,
-    description: "Estimator retry count; retries are disabled.",
-  }),
-]);
-
-export type ModelTokenEstimatorKind = Extract<
-  (typeof MODEL_TOKEN_ESTIMATOR_FIELDS)[number],
-  { readonly name: "kind" }
->["literalValue"];
-
-export type ModelTokenEstimatorMaxRetries = Extract<
-  (typeof MODEL_TOKEN_ESTIMATOR_FIELDS)[number],
-  { readonly name: "maxRetries" }
->["literalValue"];
-
 export type MemoryConfigField = {
   readonly name: "profile" | "embedding";
   readonly valueKind: "non-empty-string" | "embedding-profile";
@@ -610,7 +538,7 @@ export function parsePublicEnvironment(
     values[field.name] = parseEnvironmentField(field, env[field.name], mode, cwd);
   }
 
-  const workspaceRoot = path.resolve(
+  const workspaceRoot = resolveUserPath(
     cwd,
     requiredStringValue(values, "TINKER_WORKSPACE"),
   );
@@ -659,9 +587,7 @@ export function parsePublicEnvironment(
     return Object.freeze({
       ...common,
       mode,
-      modelsPath: path.isAbsolute(configuredModelsPath)
-        ? configuredModelsPath
-        : path.resolve(cwd, configuredModelsPath),
+      modelsPath: resolveUserPath(cwd, configuredModelsPath),
     });
   }
 
@@ -760,6 +686,16 @@ function optionalRawString(value: string | undefined): string | undefined {
   return normalized === undefined || normalized === "" ? undefined : normalized;
 }
 
+function resolveUserPath(cwd: string, value: string): string {
+  let expanded = value;
+  if (value === "~") {
+    expanded = os.homedir();
+  } else if (value.startsWith("~/") || value.startsWith(`~${path.sep}`)) {
+    expanded = path.join(os.homedir(), value.slice(2));
+  }
+  return path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
+}
+
 function optionalStringValue(
   values: Record<PublicConfigFieldName, ParsedPrimitive>,
   name: PublicConfigFieldName,

package/src/cli/runner-dependencies.ts

@@ -66,7 +66,8 @@ export function createModelClient(
     | "apiKey"
     | "apiBase"
     | "inputModalities"
-    | "tokenEstimator"
+    | "toolResultModalities"
+    | "profileName"
   >,
   env: NodeJS.ProcessEnv = process.env,
   reasoningEffort?: ReasoningEffortController,
@@ -79,12 +80,10 @@ export function createModelClient(
       model: config.modelName,
       contextBudget: config.contextBudget,
       inputModalities: config.inputModalities,
+      toolResultModalities: config.toolResultModalities,
       ...(activeReasoningEffort === undefined
         ? {}
         : { reasoningEffort: activeReasoningEffort }),
-      ...(config.tokenEstimator === undefined
-        ? {}
-        : { tokenEstimator: config.tokenEstimator }),
       ...(env.TINKER_TEST_FAKE_MODEL_REQUEST_LOG === undefined ||
       env.TINKER_TEST_FAKE_MODEL_REQUEST_LOG === ""
         ? {}
@@ -99,12 +98,11 @@ export function createModelClient(
     stream: config.stream,
     contextBudget: config.contextBudget,
     inputModalities: config.inputModalities,
+    toolResultModalities: config.toolResultModalities,
+    profileName: config.profileName,
     ...(activeReasoningEffort === undefined
       ? {}
       : { reasoningEffort: activeReasoningEffort }),
-    ...(config.tokenEstimator === undefined
-      ? {}
-      : { tokenEstimator: config.tokenEstimator }),
   };
   if (config.api === "responses") {
     return new OpenAIResponsesModelClient(common);

package/src/cli/tui-memory.ts

@@ -47,9 +47,7 @@ export async function initializeTuiMemory(input: {
             stream: profile.stream,
             contextBudget: memoryConfig.contextBudget,
             inputModalities: profile.inputModalities,
-            ...(profile.tokenEstimator === undefined
-              ? {}
-              : { tokenEstimator: profile.tokenEstimator }),
+            toolResultModalities: profile.toolResultModalities,
           },
           input.env,
         );

package/src/cli/tui-runner.tsx

@@ -129,6 +129,10 @@ export async function runTui(options: RunTuiOptions): Promise<void> {
                 workspaceRoot,
                 sessionId,
               }),
+              memoryGet: memoryCoordinator.createGetToolExecutor({
+                workspaceRoot,
+                sessionId,
+              }),
               completedTurnHook: memoryCoordinator,
             }),
       };

package/src/context/compiled-context-hash.ts

@@ -1,4 +1,5 @@
 import { sha256, stableJsonStringify } from "../model/model-request-preflight";
+import { toolResultText } from "../agent/tool-result-content";
 import type { CompiledContextEntry, SwapOverride } from "./context-revision";
 import {
   contentHash,
@@ -132,7 +133,7 @@ function renderedMessageDescriptor(entry: CompiledContextEntry): unknown {
         contentSha256:
           entry.representation === "canonical"
             ? entry.sourceContentSha256
-            : contentHash(message.content),
+            : contentHash(toolResultText(message.content)),
       };
   }
 }

package/src/context/compiled-context-validator.ts

@@ -1,4 +1,5 @@
 import type { AgentMessage } from "../agent/types";
+import { toolResultDisplayText, toolResultText } from "../agent/tool-result-content";
 import { stableJsonStringify } from "../model/model-request-preflight";
 import { formatMessageSource } from "./context-source";
 import type { CompiledRevisionContext, SwapOverride } from "./context-revision";
@@ -157,7 +158,7 @@ export class CompiledContextValidator {
         entry.message.toolCallId !== record.toolCallId ||
         entry.message.providerToolCallId !== record.providerToolCallId ||
         entry.message.name !== record.name ||
-        entry.message.content !== override.renderedContent
+        toolResultText(entry.message.content) !== override.renderedContent
       ) {
         fail(
           `Swapped tool entry changed protocol identity at ordinal ${entry.ordinal}.`,
@@ -197,7 +198,11 @@ function validateOverrideIdentity(
     fail(`Swap override changed canonical identity at ordinal ${record.ordinal}.`);
   }
   const originalBytes = Buffer.byteLength(
-    record.role === "assistant" ? (record.content ?? "") : record.content,
+    record.role === "assistant"
+      ? (record.content ?? "")
+      : record.role === "tool"
+        ? record.displayText
+        : record.content,
     "utf8",
   );
   const renderedBytes = Buffer.byteLength(override.renderedContent, "utf8");
@@ -208,8 +213,11 @@ function validateOverrideIdentity(
     override.originalBytes !== originalBytes ||
     override.renderedBytes !== renderedBytes ||
     override.byteSavings !== originalBytes - renderedBytes ||
-    (rendererFormat === "swap-observation-v1" && override.byteSavings <= 0) ||
+    ((rendererFormat === "swap-observation-v1" ||
+      rendererFormat === "skill-activation-receipt-v1") &&
+      override.byteSavings <= 0) ||
     (rendererFormat !== "swap-observation-v1" &&
+      rendererFormat !== "swap-tool-image-v1" &&
       rendererFormat !== "skill-activation-receipt-v1")
   ) {
     fail(`Swap override metadata is invalid at ordinal ${record.ordinal}.`);
@@ -266,7 +274,8 @@ function assertSameMessage(actual: AgentMessage, record: CanonicalMessageRecord)
         actual.toolCallId !== record.toolCallId ||
         actual.providerToolCallId !== record.providerToolCallId ||
         actual.name !== record.name ||
-        actual.content !== record.content
+        stableJsonStringify(actual.content) !== stableJsonStringify(record.content) ||
+        toolResultDisplayText(actual.content) !== record.displayText
       ) {
         fail(`Canonical entry changed tool data at ordinal ${record.ordinal}.`);
       }

package/src/context/context-protocol-validator.ts

@@ -1,8 +1,14 @@
 import type { MessageId, ProtocolFrameId, ToolCallId } from "../ids/runtime-id";
+import {
+  canonicalToolResultContentHash,
+  toolResultDisplayText,
+  validateToolResultContent,
+} from "../agent/tool-result-content";
 import {
   contentHash,
   userMessageHash,
   rawResultHash,
+  validateReturnedToolObservation,
   type CanonicalMessageRecord,
   type ProtocolContextView,
   type ProtocolFrame,
@@ -113,7 +119,9 @@ export class ContextProtocolValidator {
                   ? {}
                   : { attachments: message.attachments }),
               })
-            : contentHash(message.content))
+            : message.role === "tool"
+              ? canonicalToolResultContentHash(message.content)
+              : contentHash(message.content))
       ) {
         fail(
           "content_hash_mismatch",
@@ -405,11 +413,19 @@ function validateToolExchange(
       );
     }
     const result = requireItem(results, 0, "tool result");
+    validateToolResultContent(message.content);
+    if (message.displayText !== toolResultDisplayText(message.content)) {
+      fail(
+        "content_hash_mismatch",
+        `Tool display projection does not match message ${message.messageId}.`,
+        identityForMessage(message),
+      );
+    }
     if (
       result.sessionId !== frame.sessionId ||
       result.frameId !== frame.frameId ||
       result.toolMessageId !== message.messageId ||
-      result.observationSha256 !== contentHash(message.content)
+      result.observationSha256 !== canonicalToolResultContentHash(message.content)
     ) {
       fail(
         "tool_result_mismatch",
@@ -428,6 +444,21 @@ function validateToolExchange(
         { ...identityForMessage(message), toolCallId: call.toolCallId },
       );
     }
+    if (input.fullIntegrity && result.completion.kind === "returned") {
+      try {
+        validateReturnedToolObservation({
+          toolName: message.name,
+          raw: result.completion.raw,
+          content: message.content,
+        });
+      } catch (error) {
+        fail(
+          "tool_result_mismatch",
+          `Tool result for ${call.toolCallId} has invalid canonical content: ${error instanceof Error ? error.message : String(error)}`,
+          { ...identityForMessage(message), toolCallId: call.toolCallId },
+        );
+      }
+    }
     input.usedResultCallIds.add(call.toolCallId);
   }
 }

package/src/context/context-revision-compiler.ts

@@ -1,4 +1,5 @@
 import type { AgentMessage } from "../agent/types";
+import { textToolResultContent } from "../agent/tool-result-content";
 import type { ContextRevisionId } from "../ids/runtime-id";
 import { CompiledContextValidator } from "./compiled-context-validator";
 import {
@@ -263,7 +264,7 @@ function swappedToolMessage(
   }
   return {
     ...message,
-    content: override.renderedContent,
+    content: textToolResultContent(override.renderedContent),
   };
 }
 

package/src/context/context-revision.ts

@@ -133,12 +133,18 @@ export type SwapOverride = {
   readonly originalBytes: number;
   readonly renderedBytes: number;
   readonly byteSavings: number;
-  readonly rendererFormat?: "swap-observation-v1" | "skill-activation-receipt-v1";
+  readonly rendererFormat?:
+    | "swap-observation-v1"
+    | "swap-tool-image-v1"
+    | "skill-activation-receipt-v1";
 };
 
 export type StoredContextOverrideV8 = SwapOverride & {
   readonly introducedRevisionId: ContextRevisionId;
-  readonly rendererFormat: "swap-observation-v1" | "skill-activation-receipt-v1";
+  readonly rendererFormat:
+    | "swap-observation-v1"
+    | "swap-tool-image-v1"
+    | "skill-activation-receipt-v1";
   readonly createdAt: string;
 };