tinker-agent 2.10.0 → 2.12.0

package/src/memory/memory-search-tool.ts

@@ -1,189 +1,93 @@
-import { throwIfTurnCancelled } from "../agent/turn-cancellation";
-import {
-  defineToolExecutor,
-  type MemorySearchRawResult,
-  type ToolDefinition,
-  type ToolExecutor,
-} from "../tools/types";
-import {
-  MAX_MEMORY_KEYWORD_BYTES,
-  MAX_MEMORY_KEYWORDS,
-  MAX_MEMORY_QUERY_BYTES,
-  MEMORY_SEARCH_TOOL_NAME,
-} from "./contracts";
-
-export const MEMORY_SEARCH_TOOL_DEFINITION: ToolDefinition = Object.freeze({
-  name: MEMORY_SEARCH_TOOL_NAME,
-  description:
-    "Search memories retained from historical conversation turns across sessions and workspaces. Use this proactively when prior user preferences, project decisions, environment facts, or verified solutions may help. Put exact-match terms in `keywords`, put a concise semantic description in `query`, and provide both for hybrid recall. Each result is a historical record containing a one-line index text, a possibly truncated detailed summary, a `memoryId`, and a `sourceSessionId`. Results may be stale or incorrect, so verify current workspace facts with current tools. To read the full stored record for a result, call `MemoryGet` with its `memoryId`.",
-  parameters: {
-    type: "object",
-    additionalProperties: false,
-    properties: {
-      query: {
-        type: "string",
-        minLength: 1,
-        maxLength: MAX_MEMORY_QUERY_BYTES,
-        description:
-          "A concise semantic description of the fact, preference, decision, or solution to recall. Drives vector similarity search.",
-      },
-      keywords: {
-        type: "array",
-        maxItems: MAX_MEMORY_KEYWORDS,
-        items: {
-          type: "string",
-          minLength: 1,
-          maxLength: MAX_MEMORY_KEYWORD_BYTES,
-        },
-        description:
-          "Exact terms to match literally, such as identifiers, error strings, paths, or project names. Drives keyword search. Keywords shorter than 3 characters cannot be matched.",
-      },
-    },
-    required: [],
-  },
-});
+import { defineToolExecutor, type ToolExecutor } from "../tools/types";
+import { boundedMemoryError } from "./contracts";
+import { ensureMemoryDirectory } from "./memory-files";
+import { searchMemoryFiles, type MemorySearchInput } from "./memory-search";
 
 export function createMemorySearchToolExecutor(options: {
-  readonly search: (
-    query: string | null,
-    keywords: readonly string[],
-    signal: AbortSignal,
-  ) => Promise<MemorySearchRawResult>;
-  readonly recordInvalidCall: (input: {
-    readonly queryBytes: number;
-    readonly keywordCount: number;
-  }) => Promise<void>;
+  homeRoot?: string;
 }): ToolExecutor {
   return defineToolExecutor("memory_search", {
-    definition: MEMORY_SEARCH_TOOL_DEFINITION,
-    async execute(args, _call, context): Promise<MemorySearchRawResult> {
-      throwIfTurnCancelled(context.signal);
-      const parsed = parseMemorySearchArgs(args);
-      if (!parsed.ok) {
-        await options.recordInvalidCall({
-          queryBytes: parsed.queryBytes,
-          keywordCount: parsed.keywordCount,
-        });
-        return { ok: false, error: parsed.error };
+    definition: {
+      name: "MemorySearch",
+      description:
+        "Search historical session records and saved notes across workspaces when earlier decisions, preferences, or work may help. Matches any keyword literally, ignoring case, within individual lines. Returns passages grouped by file with line numbers; > marks matching lines and … separates passages. Use Read with offset and limit to expand a passage. Continue using nextOffset with the same keywords and context.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          keywords: {
+            type: "array",
+            minItems: 1,
+            items: { type: "string", minLength: 1 },
+            description:
+              "Literal keywords; any one can match. No regular expressions or multiline keywords. A line matching multiple keywords counts once.",
+          },
+          context: {
+            type: "integer",
+            minimum: 0,
+            description:
+              "Lines before and after each matching line. Defaults to 3. Overlapping passages are merged.",
+          },
+          limit: {
+            type: "integer",
+            minimum: 1,
+            description:
+              "Maximum selected matching lines, excluding context. Defaults to 20.",
+          },
+          offset: {
+            type: "integer",
+            minimum: 0,
+            description:
+              "Matching lines to skip. Defaults to 0. Use nextOffset to continue; file changes between searches can affect pagination.",
+          },
+        },
+        required: ["keywords"],
+      },
+    },
+    async execute(args, _call, context) {
+      context.signal.throwIfAborted();
+      try {
+        const input = parseArgs(args);
+        const directory = await ensureMemoryDirectory(options.homeRoot);
+        return await searchMemoryFiles(directory, input, context.signal);
+      } catch (error) {
+        context.signal.throwIfAborted();
+        return { ok: false, error: boundedMemoryError(error) };
       }
-      const result = await options.search(
-        parsed.query,
-        parsed.keywords,
-        context.signal,
-      );
-      throwIfTurnCancelled(context.signal);
-      return result;
     },
   });
 }
 
-type ParsedMemorySearchArgs =
-  | {
-      readonly ok: true;
-      readonly query: string | null;
-      readonly keywords: readonly string[];
-    }
-  | {
-      readonly ok: false;
-      readonly queryBytes: number;
-      readonly keywordCount: number;
-      readonly error: string;
-    };
-
-function invalidMemorySearchArgs(
-  args: Record<string, unknown>,
-  error: string,
-  queryBytes?: number,
-): ParsedMemorySearchArgs {
-  return {
-    ok: false,
-    queryBytes:
-      queryBytes ??
-      (typeof args.query === "string" ? Buffer.byteLength(args.query, "utf8") : 0),
-    keywordCount: Array.isArray(args.keywords) ? args.keywords.length : 0,
-    error,
-  };
-}
-
-function parseMemorySearchArgs(args: unknown): ParsedMemorySearchArgs {
-  if (!isRecord(args)) {
-    return {
-      ok: false,
-      queryBytes: 0,
-      keywordCount: 0,
-      error:
-        "MemorySearch arguments must be an object containing only query and keywords.",
-    };
-  }
-  const unexpected = Object.keys(args).find(
-    (key) => key !== "query" && key !== "keywords",
-  );
-  if (unexpected !== undefined) {
-    return invalidMemorySearchArgs(
-      args,
-      `MemorySearch received unexpected field: ${unexpected}.`,
+function parseArgs(args: unknown): MemorySearchInput {
+  if (args === null || typeof args !== "object" || Array.isArray(args))
+    throw new Error(
+      "MemorySearch requires keywords, with optional context, limit and offset.",
     );
+  const value = args as Record<string, unknown>;
+  for (const name of Object.keys(value)) {
+    if (!["keywords", "context", "limit", "offset"].includes(name))
+      throw new Error(`MemorySearch received unexpected field: ${name}.`);
   }
-
-  let query: string | null = null;
-  if (args.query !== undefined) {
-    if (typeof args.query !== "string") {
-      return invalidMemorySearchArgs(args, "MemorySearch.query must be a string.");
-    }
-    const trimmed = args.query.trim();
-    const bytes = Buffer.byteLength(trimmed, "utf8");
-    if (bytes < 1 || bytes > MAX_MEMORY_QUERY_BYTES) {
-      return invalidMemorySearchArgs(
-        args,
-        `MemorySearch.query must be 1 to ${MAX_MEMORY_QUERY_BYTES} UTF-8 bytes after trimming.`,
-        bytes,
+  if (!Array.isArray(value.keywords) || value.keywords.length === 0)
+    throw new Error("MemorySearch.keywords must be a non-empty array of strings.");
+  const keywords = value.keywords.map((word: unknown) => {
+    if (typeof word !== "string" || word.trim() === "" || /[\r\n]/.test(word))
+      throw new Error("MemorySearch keywords must be non-empty single-line strings.");
+    return word.trim();
+  });
+  const integers = { context: 3, limit: 20, offset: 0 };
+  for (const name of ["context", "limit", "offset"] as const) {
+    const number = value[name];
+    if (number === undefined) continue;
+    if (
+      typeof number !== "number" ||
+      !Number.isSafeInteger(number) ||
+      number < (name === "limit" ? 1 : 0)
+    )
+      throw new Error(
+        `MemorySearch.${name} must be a safe integer >= ${name === "limit" ? 1 : 0}.`,
       );
-    }
-    query = trimmed;
+    integers[name] = number;
   }
-
-  const keywords: string[] = [];
-  if (args.keywords !== undefined) {
-    if (!Array.isArray(args.keywords)) {
-      return invalidMemorySearchArgs(
-        args,
-        "MemorySearch.keywords must be an array of strings.",
-      );
-    }
-    if (args.keywords.length > MAX_MEMORY_KEYWORDS) {
-      return invalidMemorySearchArgs(
-        args,
-        `MemorySearch.keywords may contain at most ${MAX_MEMORY_KEYWORDS} entries.`,
-      );
-    }
-    for (const entry of args.keywords) {
-      if (typeof entry !== "string") {
-        return invalidMemorySearchArgs(
-          args,
-          "Every MemorySearch keyword must be a string.",
-        );
-      }
-      const trimmed = entry.trim();
-      const bytes = Buffer.byteLength(trimmed, "utf8");
-      if (bytes < 1 || bytes > MAX_MEMORY_KEYWORD_BYTES) {
-        return invalidMemorySearchArgs(
-          args,
-          `Every MemorySearch keyword must be 1 to ${MAX_MEMORY_KEYWORD_BYTES} UTF-8 bytes after trimming.`,
-        );
-      }
-      keywords.push(trimmed);
-    }
-  }
-
-  if (query === null && keywords.length === 0) {
-    return invalidMemorySearchArgs(
-      args,
-      "MemorySearch requires a non-empty query or at least one keyword.",
-    );
-  }
-  return { ok: true, query, keywords: Object.freeze(keywords) };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  return { keywords, ...integers };
 }

package/src/memory/memory-search.ts

@@ -0,0 +1,115 @@
+import { createReadStream } from "node:fs";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import type { MemoryTextSearchResult, MemorySearchLine } from "../tools/types";
+
+export type MemorySearchInput = {
+  keywords: string[];
+  context: number;
+  limit: number;
+  offset: number;
+};
+
+export async function searchMemoryFiles(
+  directory: string,
+  input: MemorySearchInput,
+  signal: AbortSignal,
+): Promise<MemoryTextSearchResult> {
+  const paths = await markdownFiles(directory, signal);
+  const keywords = input.keywords.map((word) => word.toLowerCase());
+  const files: MemoryTextSearchResult["files"][number][] = [];
+  let seen = 0;
+  let returnedResults = 0;
+  let hasMore = false;
+  for (const filePath of paths) {
+    signal.throwIfAborted();
+    const stream = createReadStream(filePath, { encoding: "utf8", signal });
+    const reader = createInterface({ input: stream, crlfDelay: Infinity });
+    const before: MemorySearchLine[] = [];
+    const selected = new Map<number, MemorySearchLine>();
+    let lineNumber = 0;
+    let through = 0;
+    try {
+      for await (const text of reader) {
+        signal.throwIfAborted();
+        lineNumber++;
+        const folded = text.toLowerCase();
+        let matchAt = -1;
+        for (const keyword of keywords) {
+          const position = folded.indexOf(keyword);
+          if (position >= 0 && (matchAt < 0 || position < matchAt)) matchAt = position;
+        }
+        const match = matchAt >= 0;
+        const line = { lineNumber, match, text: excerpt(text, matchAt) };
+        if (match) {
+          if (seen >= input.offset && returnedResults < input.limit) {
+            returnedResults++;
+            for (const previous of before) selected.set(previous.lineNumber, previous);
+            through = lineNumber + input.context;
+          } else if (returnedResults === input.limit) {
+            hasMore = true;
+          }
+          seen++;
+        }
+        if (lineNumber <= through) selected.set(lineNumber, line);
+        if (hasMore && lineNumber >= through) break;
+        if (input.context > 0) {
+          before.push(line);
+          if (before.length > input.context) before.shift();
+        }
+      }
+    } finally {
+      reader.close();
+      stream.destroy();
+    }
+    if (selected.size > 0)
+      files.push({
+        filePath,
+        lines: [...selected.values()].sort((a, b) => a.lineNumber - b.lineNumber),
+      });
+    if (hasMore) break;
+  }
+  signal.throwIfAborted();
+  return {
+    ok: true,
+    format: "text",
+    files,
+    returnedResults,
+    hasMore,
+    ...(hasMore ? { nextOffset: input.offset + returnedResults } : {}),
+  };
+}
+
+async function markdownFiles(
+  directory: string,
+  signal: AbortSignal,
+): Promise<string[]> {
+  signal.throwIfAborted();
+  const files: string[] = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    signal.throwIfAborted();
+    const filePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...(await markdownFiles(filePath, signal)));
+    else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md"))
+      files.push(filePath);
+  }
+  return files.sort();
+}
+
+/** Keep up to 500 original code points around the earliest literal match. */
+function excerpt(text: string, foldedMatchOffset: number): string {
+  const points = [...text];
+  if (points.length <= 500) return text;
+  let matchPoint = 0;
+  let foldedOffset = 0;
+  if (foldedMatchOffset >= 0) {
+    while (matchPoint < points.length && foldedOffset < foldedMatchOffset) {
+      foldedOffset += points[matchPoint].toLowerCase().length;
+      matchPoint++;
+    }
+  }
+  const start = Math.max(0, matchPoint - 100);
+  const end = Math.min(points.length, start + 500);
+  return `${start > 0 ? `[... ${start} code points omitted ...]` : ""}${points.slice(start, end).join("")}${end < points.length ? `[... ${points.length - end} code points omitted ...]` : ""}`;
+}

package/src/model/fake-model-client.ts

@@ -25,7 +25,7 @@ import type {
   PreparedModelRequest,
   PreparedPromptSegment,
 } from "./model-client";
-import { validateModelModalities } from "./model-client";
+import { ProviderResponseError, validateModelModalities } from "./model-client";
 import { sha256, stableJsonStringify } from "./model-request-preflight";
 import { estimatePromptSegments } from "./token-estimator";
 
@@ -212,6 +212,25 @@ export class FakeModelClient implements ModelClient {
       );
     }
 
+    if (this.mode === "pty-provider-retry") {
+      if (lastUserMessage(input.messages) === "PTY_RETRY_NEXT") {
+        return textOutput(prepared, "PTY_RETRY_NEXT_DONE");
+      }
+      if (this.steps <= 4) {
+        options.onTextDelta?.(
+          `## Attempt ${this.steps}\nPartial response\n\n## Unfinished\nDRAFT_ONLY`,
+        );
+        throw new ProviderResponseError(
+          "reasoning_only_assistant",
+          "PTY_PROVIDER_FAILURE",
+          {
+            provider: prepared.provider,
+            model: prepared.model,
+          },
+        );
+      }
+      return textOutput(prepared, "PTY_RETRY_DONE");
+    }
     if (this.mode === "write-notes") {
       return this.writeNotes(input, prepared, options);
     }

package/src/model/openai-model-utils.ts

@@ -358,12 +358,56 @@ function providerErrorCode(error: unknown): ProviderResponseErrorCode {
   if (status === 500 || status === 502 || status === 503 || status === 504) {
     return "provider_unavailable";
   }
-  if (status === undefined && error instanceof OpenAI.APIConnectionError) {
+  // Explicit HTTP failures take precedence over payload or transport hints.
+  if (status !== undefined) return "provider_request_error";
+  const code = errorField(error, "code");
+  if (code === "server_error") return "provider_unavailable";
+  if (code === "rate_limit_exceeded") return "provider_rate_limited";
+  if (error instanceof OpenAI.APIConnectionError || isTransportFailure(error)) {
     return "provider_unavailable";
   }
   return "provider_request_error";
 }
 
+const TRANSIENT_TRANSPORT_CODES = new Set([
+  "ECONNRESET",
+  "EPIPE",
+  "ETIMEDOUT",
+  "ERR_STREAM_PREMATURE_CLOSE",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+]);
+
+function isTransportFailure(error: unknown): boolean {
+  const seen = new Set<unknown>();
+  // Fetch may wrap a socket error in TypeError.cause after headers arrive.
+  for (let depth = 0; error !== undefined && depth < 8; depth += 1) {
+    if (seen.has(error)) return false;
+    seen.add(error);
+    if (
+      errorField(error, "name") === "AbortError" ||
+      error instanceof OpenAI.APIUserAbortError ||
+      providerErrorStatus(error) !== undefined
+    ) {
+      return false;
+    }
+    const code = errorField(error, "code");
+    if (code !== undefined) {
+      return typeof code === "string" && TRANSIENT_TRANSPORT_CODES.has(code);
+    }
+    error = errorField(error, "cause");
+  }
+  return false;
+}
+
+function errorField(error: unknown, key: string): unknown {
+  return typeof error === "object" && error !== null
+    ? (error as Record<string, unknown>)[key]
+    : undefined;
+}
+
 function providerErrorStatus(error: unknown): number | undefined {
   if (typeof error !== "object" || error === null || !("status" in error)) {
     return undefined;

package/src/model/openai-responses-mapping.ts

@@ -28,6 +28,7 @@ import {
   type ProviderResponseDiagnostics,
 } from "./model-client";
 import { imageAssetUrlMarker } from "./openai-image-mapping";
+import { sanitizedProviderError } from "./openai-model-utils";
 
 export type OpenAIResponsesMappingOptions = {
   materializedImages?: ReadonlyMap<ImageAssetId, string>;
@@ -160,6 +161,16 @@ export function fromOpenAIResponse(
 ): ModelRequestOutput {
   const root = requireRecord(response, "response", options);
   const status = requireString(root.status, "status", options);
+  if (status === "failed") {
+    const error = requireRecord(root.error, "error", options);
+    const code = requireString(error.code, "error.code", options);
+    const message = requireString(error.message, "error.message", options);
+    throw sanitizedProviderError(
+      Object.assign(new Error(message), { code }),
+      options.provider,
+      options.model,
+    );
+  }
   if (status !== "completed" && status !== "incomplete") {
     throw providerResponseError(
       options,

package/src/model/openai-responses-stream.ts

@@ -2,6 +2,7 @@ import {
   ProviderResponseError,
   type ProviderResponseDiagnostics,
 } from "./model-client";
+import { sanitizedProviderError } from "./openai-model-utils";
 
 export class OpenAIResponsesStreamAccumulator {
   private eventCount = 0;
@@ -20,6 +21,19 @@ export class OpenAIResponsesStreamAccumulator {
     const type = requireString(record.type, `${path}.type`, this.options);
     this.eventCount += 1;
 
+    if (type === "error") {
+      const message = requireString(record.message, `${path}.message`, this.options);
+      const code =
+        record.code === null
+          ? null
+          : requireString(record.code, `${path}.code`, this.options);
+      throw sanitizedProviderError(
+        Object.assign(new Error(message), { code }),
+        this.options.provider,
+        this.options.model,
+      );
+    }
+
     if (type === "response.output_text.delta") {
       return requireString(record.delta, `${path}.delta`, this.options);
     }

package/src/observation/observation-builder.ts

@@ -1,3 +1,4 @@
+import { renderMemoryTextSearch } from "../memory/memory-search-output";
 import type { ToolCall } from "../agent/types";
 import type { ToolResultContent } from "../agent/types";
 import {
@@ -410,6 +411,7 @@ function renderMemorySearchObservation(raw: MemorySearchRawResult): string {
   if (!raw.ok) {
     return `MemorySearch unavailable: ${raw.error}`;
   }
+  if ("format" in raw) return renderMemoryTextSearch(raw);
   const degradedNote =
     raw.degraded === "vector"
       ? " vector search unavailable; keyword results only."
@@ -467,7 +469,9 @@ function renderMemoryCreateObservation(
   }
   const text = memoryMutationText(call);
   const result = `MemoryCreate ${raw.status} memory=${raw.memoryId} created_at=${raw.createdAt}.`;
-  return text === undefined ? result : `${result}\ntext: ${text}`;
+  const location =
+    raw.filePath === undefined ? result : `${result}\nPath: ${raw.filePath}`;
+  return text === undefined ? location : `${location}\ntext: ${text}`;
 }
 
 function renderMemoryUpdateObservation(

package/src/session/scoped-query-database.ts

@@ -0,0 +1,27 @@
+import { Database, type SQLQueryBindings } from "bun:sqlite";
+
+/**
+ * Own every query statement until a short-lived connection closes. Bun only
+ * caches its first 20 queries; later statements otherwise survive close() until
+ * GC, leaving a zombie SQLite connection behind. Do not use this for resident
+ * stores: retaining every query is intentionally bounded by the operation.
+ */
+export class ScopedQueryDatabase extends Database {
+  private readonly queries = new Set<{ finalize(): void }>();
+
+  override query<Result, Params extends SQLQueryBindings | SQLQueryBindings[]>(
+    sql: string,
+  ) {
+    const statement = super.query<Result, Params>(sql);
+    this.queries.add(statement);
+    return statement;
+  }
+
+  override close(): void {
+    for (const statement of this.queries) statement.finalize();
+    this.queries.clear();
+    // Also finalizes Bun's transaction statements and rejects any other live
+    // resources instead of silently deferring the underlying connection close.
+    super.close(true);
+  }
+}

package/src/session/session-history-access.ts

@@ -1,4 +1,5 @@
-import { Database } from "bun:sqlite";
+import type { Database } from "bun:sqlite";
+import { ScopedQueryDatabase } from "./scoped-query-database";
 import { lstat, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { throwIfTurnCancelled } from "../agent/turn-cancellation";
@@ -67,7 +68,7 @@ export function createSessionHistoryAccess(input: {
         throwIfTurnCancelled(signal);
         await validateHistoryFiles(location.databasePath, sessionId);
         throwIfTurnCancelled(signal);
-        const database = new Database(location.databasePath, {
+        const database = new ScopedQueryDatabase(location.databasePath, {
           readonly: true,
           strict: true,
           safeIntegers: true,
@@ -100,7 +101,7 @@ export function createSessionHistoryAccess(input: {
           throwIfTurnCancelled(signal);
           return result;
         } finally {
-          database.close(true);
+          database.close();
         }
       } catch (error) {
         throwIfTurnCancelled(signal);

package/src/session/session-store-contracts.ts

@@ -28,29 +28,6 @@ export type SessionMediaCompatibility = {
   readonly toolResultModalities: readonly ("text" | "image")[];
 };
 
-export type CompletedTurnMessageSnapshot =
-  | {
-      readonly ordinal: number;
-      readonly role: "user";
-      readonly content: string;
-    }
-  | {
-      readonly ordinal: number;
-      readonly role: "assistant";
-      readonly content: string | null;
-      readonly reasoningContent?: string | null;
-    }
-  | {
-      readonly ordinal: number;
-      readonly role: "tool";
-      readonly name: string;
-      readonly content: string;
-    };
-
-export type CompletedTurnSnapshot = {
-  readonly messages: readonly CompletedTurnMessageSnapshot[];
-};
-
 export type SessionCompatibilityContract = {
   modelName: string;
   profileName?: string;