tinker-agent 1.3.0 → 1.5.0

package/src/cli/run-runner.ts

@@ -10,27 +10,29 @@ import {
   loadProjectInstructions,
   projectInstructionManifest,
 } from "../instructions/project-instructions";
+import { type RunnerConfig } from "./config";
 import {
   createRunnerModelClient,
-  createWebFetchRefinerFromEnv,
-  readRunnerConfig,
+  createWebFetchRefiner,
   RUNTIME_INSTRUCTIONS,
-  type RunnerConfigOverrides,
-} from "./config";
-import { loadModelProfiles } from "./model-profiles";
+} from "./runner-dependencies";
+import type { PublicToolingConfig } from "./public-config-contract";
 import { realpath } from "node:fs/promises";
 import { loadSkillCatalog } from "../skills/skill-loader";
 
-export type RunOneShotOptions = RunnerConfigOverrides & {
+export type RunOneShotOptions = {
+  config: RunnerConfig;
+  tooling: PublicToolingConfig;
   modelClient?: ModelClient;
   stdout?: WritableLike;
   stderr?: WritableLike;
   eventLogPath?: string | false;
+  env?: NodeJS.ProcessEnv;
 };
 
 export async function runOneShot(
   userPrompt: string,
-  options: RunOneShotOptions = {},
+  options: RunOneShotOptions,
 ): Promise<number> {
   const stdout = options.stdout ?? process.stdout;
   const stderr = options.stderr ?? process.stderr;
@@ -40,9 +42,7 @@ export async function runOneShot(
   let exitCode = 1;
 
   try {
-    const profiles =
-      options.modelClient === undefined ? await loadModelProfiles() : undefined;
-    const config = readRunnerConfig(options, profiles);
+    const config = options.config;
     const workspaceRoot = await realpath(config.workspaceRoot);
     const projectInstructions = await loadProjectInstructions(workspaceRoot);
     const skillCatalog = await loadSkillCatalog({ workspaceRoot });
@@ -51,7 +51,11 @@ export async function runOneShot(
       runtimeInstructions: RUNTIME_INSTRUCTIONS(workspaceRoot),
       projectInstructions,
     });
-    const modelClient = createRunnerModelClient(config, options.modelClient);
+    const modelClient = createRunnerModelClient(
+      config,
+      options.modelClient,
+      options.env,
+    );
     session = await createRuntimeSession({
       selection: { mode: "new", sessionId: config.sessionId },
       workspaceRoot,
@@ -68,7 +72,8 @@ export async function runOneShot(
       presentationSinks: [new StdoutEventPrinter(stdout, stderr)],
       persistence:
         options.eventLogPath === false ? false : { eventLogPath: options.eventLogPath },
-      webFetchRefiner: createWebFetchRefinerFromEnv(config),
+      webFetchRefiner: createWebFetchRefiner(config, options.env),
+      toolingConfig: options.tooling,
     });
 
     const result = await session.executeTurn({

package/src/cli/runner-dependencies.ts

@@ -0,0 +1,108 @@
+import { renderRecallRetirementContract } from "../context/recall-retirement-contract";
+import { FakeModelClient } from "../model/fake-model-client";
+import type { ModelClient } from "../model/model-client";
+import { OpenAIChatModelClient } from "../model/openai-chat-model-client";
+import { createModelRefiner, type Refiner } from "../tools/web-fetch/refiner";
+import type { RunnerConfig } from "./config";
+
+export const RUNTIME_INSTRUCTIONS = (
+  workspaceRoot: string,
+): string => `You are a coding agent running in a local workspace.
+Your name is Tinker.
+
+Current workspace:
+${workspaceRoot}
+
+Use this path as the root for relative file paths. Absolute file paths may point outside this workspace.
+
+You can use tools to find, read, edit, write files, and run shell commands.
+Use Glob to find files by name or path pattern.
+Use Grep to search file contents. Do not use Bash with grep or rg for routine content searches.
+With Grep, start with output_mode="files_with_matches" to narrow scope, then use output_mode="content" when you need matching lines.
+Use head_limit and offset to page through large Grep result sets instead of requesting unlimited output.
+Use Read to open specific files returned by Grep.
+Use Edit to replace exact strings in existing files. Set old_string="" to create a file or write to an empty file.
+Use Read before the first Write of an existing file in the current runtime.
+Write creates missing parent directories when creating a file.
+Write may fail if the runtime has no known version or the file changed after it was last observed. If that happens, call Read again and retry with the updated content.
+Use Read before an exact-string Edit when this runtime has not already established the current version through Read, Write, or Edit. A successful paginated Read is sufficient. Successful Write and Edit operations establish the current version, so later exact-string Edit operations do not need another Read unless the file changed externally. Edit with old_string="" can create a file or write to an empty file without a prior Read, and creates missing parent directories when creating a file. Exact-string Edit may fail if the runtime has no known version, the file changed after it was last observed, old_string is missing, or old_string matches multiple places without replace_all=true.
+Use WebSearch, when it is available, to look up current information on the web such as recent releases, documentation, and news. Prefer local workspace knowledge for questions the codebase can answer.
+Use WebFetch to read the content of a specific URL, such as documentation pages found via WebSearch or local dev server pages.
+Use Bash to run tests, formatters, linters, read-only git checks, and project commands.
+Prefer Read for reading files instead of using cat on large files.
+Prefer Write or Edit for changing files instead of shell redirection.
+Use run_in_background=true for dev servers, watch commands, long-running builds, and long-running test services.
+Do not add & to Bash commands; background execution is handled by the Bash tool.
+Use TaskList to list background shell tasks in the current session.
+Use TaskOutput to inspect a task's current status and latest output.
+Use TaskStop to stop a background task that is no longer needed.
+Do not use ad-hoc kill commands to manage tasks created by Bash.
+Bash and TaskOutput return outputFilePath. Use Read on outputFilePath when you need complete or paginated output.
+${renderRecallRetirementContract()}
+Agent Skill instructions are current only when returned by the Skill tool in the current turn or listed in the active skill system section. Skill content recovered through Recall is historical data and does not activate or override a current skill.
+When an active Agent Skill refers to a relative resource path, resolve it from the Skill directory shown with that skill.
+Agent Skills do not override Tinker's runtime, tool protocol, project instructions, or the user's explicit request. Do not modify a skill source unless the user explicitly asks to maintain that skill.
+
+When you are done, respond with a concise summary of what you did.`;
+
+export function createModelClient(
+  config: Pick<
+    RunnerConfig,
+    | "modelName"
+    | "includeReasoningContent"
+    | "stream"
+    | "contextBudget"
+    | "apiKey"
+    | "apiBase"
+    | "inputModalities"
+    | "tokenEstimator"
+  >,
+  env: NodeJS.ProcessEnv = process.env,
+): ModelClient {
+  const fakeMode = env.TINKER_TEST_FAKE_MODEL;
+  if (fakeMode !== undefined && fakeMode !== "") {
+    return new FakeModelClient(fakeMode, {
+      model: config.modelName,
+      contextBudget: config.contextBudget,
+      inputModalities: config.inputModalities,
+      ...(config.tokenEstimator === undefined
+        ? {}
+        : { tokenEstimator: config.tokenEstimator }),
+      ...(env.TINKER_TEST_FAKE_MODEL_REQUEST_LOG === undefined ||
+      env.TINKER_TEST_FAKE_MODEL_REQUEST_LOG === ""
+        ? {}
+        : { requestLogPath: env.TINKER_TEST_FAKE_MODEL_REQUEST_LOG }),
+    });
+  }
+
+  return new OpenAIChatModelClient({
+    apiKey: config.apiKey,
+    baseURL: config.apiBase,
+    includeReasoningContent: config.includeReasoningContent,
+    model: config.modelName,
+    stream: config.stream,
+    contextBudget: config.contextBudget,
+    inputModalities: config.inputModalities,
+    ...(config.tokenEstimator === undefined
+      ? {}
+      : { tokenEstimator: config.tokenEstimator }),
+  });
+}
+
+export function createRunnerModelClient(
+  config: Parameters<typeof createModelClient>[0],
+  injected?: ModelClient,
+  env?: NodeJS.ProcessEnv,
+): ModelClient {
+  return injected ?? createModelClient(config, env);
+}
+
+export function createWebFetchRefiner(
+  config: Parameters<typeof createModelClient>[0],
+  env?: NodeJS.ProcessEnv,
+): Refiner {
+  return createModelRefiner({
+    createModelClient: () => createModelClient(config, env),
+    contextBudget: config.contextBudget,
+  });
+}

package/src/cli/tui-memory.ts

@@ -0,0 +1,67 @@
+import {
+  boundedMemoryError,
+  memoryErrorCode,
+  type MemoryPaths,
+} from "../memory/contracts";
+import { MemoryCoordinator } from "../memory/memory-coordinator";
+import { MemoryLog } from "../memory/memory-log";
+import { resolveMemoryPaths } from "../memory/memory-store";
+import type { ResolvedMemoryConfig } from "./config";
+import { createModelClient } from "./runner-dependencies";
+
+export type TuiMemoryInitialization = {
+  readonly coordinator?: MemoryCoordinator;
+  readonly notice?: string;
+};
+
+export async function initializeTuiMemory(input: {
+  readonly config?: ResolvedMemoryConfig;
+  readonly env: NodeJS.ProcessEnv;
+  readonly paths?: MemoryPaths;
+  readonly createCoordinator?: typeof MemoryCoordinator.create;
+}): Promise<TuiMemoryInitialization> {
+  if (input.config === undefined) {
+    return Object.freeze({});
+  }
+
+  const paths = input.paths ?? resolveMemoryPaths();
+  const log = new MemoryLog(paths.log);
+  try {
+    const memoryConfig = input.config;
+    const coordinator = await (input.createCoordinator ?? MemoryCoordinator.create)({
+      paths,
+      embedding: memoryConfig.embedding,
+      extractionContextBudget: memoryConfig.contextBudget,
+      createExtractionClient: () => {
+        const profile = memoryConfig.profile;
+        return createModelClient(
+          {
+            modelName: profile.model,
+            apiKey: profile.apiKey,
+            apiBase: profile.apiBase,
+            includeReasoningContent: profile.includeReasoningContent,
+            stream: profile.stream,
+            contextBudget: memoryConfig.contextBudget,
+            inputModalities: profile.inputModalities,
+            ...(profile.tokenEstimator === undefined
+              ? {}
+              : { tokenEstimator: profile.tokenEstimator }),
+          },
+          input.env,
+        );
+      },
+    });
+    return Object.freeze({ coordinator });
+  } catch (error) {
+    const reason = memoryErrorCode(error, "memory_init_failed");
+    await log.append({
+      at: new Date().toISOString(),
+      kind: "init",
+      outcome: "failed",
+      reason,
+    });
+    return Object.freeze({
+      notice: `memory disabled: ${boundedMemoryError(error)}`,
+    });
+  }
+}

package/src/cli/tui-runner.tsx

@@ -27,29 +27,41 @@ import {
   type TuiSessionBinding,
 } from "../tui/tui-session-controller";
 import {
-  createRunnerModelClient,
-  createWebFetchRefinerFromEnv,
   promptHistoryPath,
-  readRunnerConfig,
-  RUNTIME_INSTRUCTIONS,
+  deriveRunnerConfig,
+  type ResolvedPublicConfig,
   type RunnerConfig,
 } from "./config";
 import {
-  loadModelProfiles,
-  persistDefaultProfile,
-  resolveSessionProfileName,
-  type ModelProfile,
-} from "./model-profiles";
+  createRunnerModelClient,
+  createWebFetchRefiner,
+  RUNTIME_INSTRUCTIONS,
+} from "./runner-dependencies";
+import { resolveSessionProfileName, type ModelProfile } from "./model-profiles";
 import { loadSkillCatalog } from "../skills/skill-loader";
 import { loadProjectSlashCommands } from "../tui/project-slash-commands";
+import { createWorkspaceFileLister } from "../tui/workspace-file-search";
+import { clipboardWriterForEnvironment } from "../tui/clipboard";
+import { initializeTuiMemory } from "./tui-memory";
 
-export async function runTui(options: { profileName?: string } = {}): Promise<void> {
-  const profiles = await loadModelProfiles();
-  const config = readRunnerConfig(
-    options.profileName !== undefined ? { profileName: options.profileName } : {},
-    profiles,
-  );
+export type RunTuiOptions = {
+  readonly publicConfig: ResolvedPublicConfig;
+  readonly initialRunnerConfig: RunnerConfig;
+  readonly env: NodeJS.ProcessEnv;
+};
+
+export async function runTui(options: RunTuiOptions): Promise<void> {
+  const profiles =
+    options.publicConfig.mode === "profile" ? options.publicConfig.profiles : undefined;
+  const config = options.initialRunnerConfig;
   const workspaceRoot = await realpath(config.workspaceRoot);
+  const memory = await initializeTuiMemory({
+    config:
+      options.publicConfig.mode === "profile" ? options.publicConfig.memory : undefined,
+    env: options.env,
+  });
+  const memoryCoordinator = memory.coordinator;
+  const memoryNotice = memory.notice;
   let controller: DefaultTuiSessionController | undefined;
   let instance: ReturnType<typeof render> | undefined;
   let disposeReason: SessionDisposeReason = { type: "tui_exit" };
@@ -64,7 +76,11 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
       sessionId: SessionId,
       sink: EventSink,
     ): Promise<RuntimeSession> => {
-      const modelClient = createRunnerModelClient(sessionConfig);
+      const modelClient = createRunnerModelClient(
+        sessionConfig,
+        undefined,
+        options.env,
+      );
       const projectInstructions = await loadProjectInstructions(workspaceRoot);
       const skillCatalog = await loadSkillCatalog({ workspaceRoot });
       const common = {
@@ -84,7 +100,17 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
         projectInstruction: projectInstructionManifest(projectInstructions),
         skillCatalog,
         presentationSinks: [sink],
-        webFetchRefiner: createWebFetchRefinerFromEnv(sessionConfig),
+        webFetchRefiner: createWebFetchRefiner(sessionConfig, options.env),
+        toolingConfig: options.publicConfig.tooling,
+        ...(memoryCoordinator === undefined
+          ? {}
+          : {
+              memorySearch: memoryCoordinator.createSearchToolExecutor({
+                workspaceRoot,
+                sessionId,
+              }),
+              completedTurnHook: memoryCoordinator,
+            }),
       };
       if (mode === "resume") {
         return createRuntimeSession({
@@ -118,18 +144,12 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
     ): Promise<ManagedTuiSessionBinding> => {
       const deferred = new DeferredProjectionSink();
       const summary = await catalog.get(sessionId);
-      const resumeConfig =
-        profiles === undefined
-          ? { ...config, sessionId }
-          : readRunnerConfig(
-              {
-                sessionId,
-                profileName: resolveSessionProfileName(profiles, summary),
-                workspaceRoot: config.workspaceRoot,
-                maxIterations: config.maxIterations,
-              },
-              profiles,
-            );
+      const resumeConfig = deriveRunnerConfig(options.publicConfig, {
+        sessionId,
+        ...(profiles === undefined
+          ? {}
+          : { profileName: resolveSessionProfileName(profiles, summary) }),
+      });
       const runtimeSession = await createSessionForConfig(
         resumeConfig,
         "resume",
@@ -195,15 +215,10 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
         throw new Error("Model profiles are not configured.");
       }
       return createNewSessionBinding(
-        readRunnerConfig(
-          {
-            sessionId: createUuidV7() as SessionId,
-            workspaceRoot: config.workspaceRoot,
-            profileName: profile.name,
-            maxIterations: config.maxIterations,
-          },
-          profiles,
-        ),
+        deriveRunnerConfig(options.publicConfig, {
+          sessionId: createUuidV7() as SessionId,
+          profileName: profile.name,
+        }),
       );
     };
 
@@ -212,21 +227,18 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
     ): Promise<ManagedTuiSessionBinding> => {
       const sessionId = createUuidV7() as SessionId;
       if (profiles === undefined) {
-        return createNewSessionBinding({ ...config, sessionId });
+        return createNewSessionBinding(
+          deriveRunnerConfig(options.publicConfig, { sessionId }),
+        );
       }
       if (current.profileName === undefined) {
         throw new Error("Current session does not have a model profile.");
       }
       return createNewSessionBinding(
-        readRunnerConfig(
-          {
-            sessionId,
-            workspaceRoot: config.workspaceRoot,
-            profileName: current.profileName,
-            maxIterations: config.maxIterations,
-          },
-          profiles,
-        ),
+        deriveRunnerConfig(options.publicConfig, {
+          sessionId,
+          profileName: current.profileName,
+        }),
       );
     };
 
@@ -251,10 +263,27 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
         history={promptHistory}
         projectSlashCommands={projectSlashCommands}
         profiles={profiles}
-        persistDefaultProfile={persistDefaultProfile}
+        persistDefaultProfile={
+          options.publicConfig.mode === "profile"
+            ? options.publicConfig.persistDefaultProfile
+            : undefined
+        }
+        fileLister={createWorkspaceFileLister({
+          command: options.publicConfig.tooling.ripgrepPath,
+          timeoutMs: options.publicConfig.tooling.grepTimeoutMs,
+          maxBufferBytes: options.publicConfig.tooling.grepMaxBufferBytes,
+        })}
+        writeClipboard={clipboardWriterForEnvironment(options.env)}
         onQuit={() => {
           quitRequested = true;
         }}
+        initialNotice={memoryNotice}
+        memoryDisabledNotice={memoryNotice}
+        listStoredMemories={
+          memoryCoordinator === undefined
+            ? undefined
+            : () => memoryCoordinator.listStoredMemories()
+        }
       />,
     );
     await instance.waitUntilExit();
@@ -264,6 +293,7 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
   } finally {
     instance?.unmount();
     restoreStdin();
+    memoryCoordinator?.dispose();
     if (controller !== undefined) {
       try {
         await controller.dispose(disposeReason);

package/src/context/context-policy.ts

@@ -2,7 +2,7 @@ export const swapOnlyPolicyV1 = Object.freeze({
   version: "swap-only-v1",
   minimumObservationBytes: 8 * 1_024,
   protectedRecentTurnCount: 8,
-  targetInputRatio: 0.6,
+  targetInputRatio: 0.3,
 } as const);
 
 export type SwapOnlyPolicyV1 = typeof swapOnlyPolicyV1;
@@ -10,7 +10,7 @@ export type SwapOnlyPolicyV1 = typeof swapOnlyPolicyV1;
 export const recallFirstRetirementPolicyV1 = Object.freeze({
   version: "recall-first-retirement-v1",
   protectedRecentTurnCount: 8,
-  targetInputRatio: 0.6,
+  targetInputRatio: 0.3,
 } as const);
 
 export type RecallFirstRetirementPolicyV1 = typeof recallFirstRetirementPolicyV1;

package/src/events/stdout-event-printer.ts

@@ -204,6 +204,7 @@ function formatToolRawResult(call: ToolCall, raw: ToolRawResult): string[] {
     case "web_search":
     case "web_fetch":
     case "recall":
+    case "memory_search":
     case "mcp":
     case "generic":
       return [];

package/src/mcp/mcp-manager.ts

@@ -58,11 +58,8 @@ export async function createMcpManager(
   options: CreateMcpManagerOptions,
 ): Promise<McpManager> {
   const clientFactory = options.clientFactory ?? stdioClientFactory;
-  const timeoutMs =
-    options.timeoutMs ?? parsePositiveIntegerEnv("TINKER_MCP_TIMEOUT_MS");
-  const maxObservationChars =
-    options.maxObservationChars ??
-    parsePositiveIntegerEnv("TINKER_MCP_MAX_OBSERVATION_CHARS");
+  const timeoutMs = options.timeoutMs;
+  const maxObservationChars = options.maxObservationChars;
   const connections: McpClientConnection[] = [];
   const executors: ToolExecutor[] = [];
   const servers: McpServerInventory[] = [];
@@ -227,20 +224,6 @@ async function closeConnections(
   }
 }
 
-function parsePositiveIntegerEnv(name: string): number | undefined {
-  const value = process.env[name];
-  if (value === undefined || value.trim() === "") {
-    return undefined;
-  }
-
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed <= 0) {
-    throw new Error(`${name} must be a positive integer; received ${value}`);
-  }
-
-  return parsed;
-}
-
 async function stdioClientFactory(
   serverName: string,
   serverConfig: McpServerConfig,

package/src/mcp/mcp-tool-executor.ts

@@ -8,10 +8,9 @@ import type {
   ToolExecutionContext,
   ToolExecutor,
 } from "../tools/types";
+import { DEFAULT_PUBLIC_TOOLING_CONFIG } from "../cli/public-config-contract";
 
 export const MCP_TOOL_NAME_PREFIX = "mcp__";
-export const DEFAULT_MCP_TIMEOUT_MS = 60_000;
-export const DEFAULT_MCP_MAX_OBSERVATION_CHARS = 40_000;
 
 export function mcpToolName(serverName: string, toolName: string): string {
   return `${MCP_TOOL_NAME_PREFIX}${serverName}__${toolName}`;
@@ -48,9 +47,9 @@ export function createMcpToolExecutor(
   options: CreateMcpToolExecutorOptions,
 ): ToolExecutor {
   const toolName = mcpToolName(options.serverName, options.tool.name);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_MCP_TIMEOUT_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_PUBLIC_TOOLING_CONFIG.mcpTimeoutMs;
   const maxObservationChars =
-    options.maxObservationChars ?? DEFAULT_MCP_MAX_OBSERVATION_CHARS;
+    options.maxObservationChars ?? DEFAULT_PUBLIC_TOOLING_CONFIG.mcpMaxObservationChars;
 
   const base = {
     toolName,

package/src/memory/contracts.ts

@@ -0,0 +1,148 @@
+import type { SessionId, TurnId } from "../ids/runtime-id";
+
+export const MEMORY_SEARCH_TOOL_NAME = "MemorySearch" as const;
+export const MEMORY_SCHEMA_VERSION = 1 as const;
+export const MAX_MEMORIES_PER_TURN = 4;
+export const MAX_MEMORY_TEXT_BYTES = 512;
+export const MAX_MEMORY_QUERY_BYTES = 1_024;
+export const MEMORY_SEARCH_LIMIT = 5;
+
+export type MemoryEmbeddingKind = "openai-compatible";
+
+export type MemoryEmbeddingConfig = {
+  readonly name: string;
+  readonly kind: MemoryEmbeddingKind;
+  readonly model: string;
+  readonly apiBase: string;
+  readonly apiKey: string;
+  readonly dimensions: number;
+};
+
+export type MemoryEmbeddingIdentity = Pick<
+  MemoryEmbeddingConfig,
+  "name" | "kind" | "model" | "dimensions"
+>;
+
+export type MemoryPaths = {
+  readonly directory: string;
+  readonly database: string;
+  readonly log: string;
+  readonly extractedLog: string;
+};
+
+export type MemoryWriteCandidate = {
+  readonly text: string;
+  readonly embedding: Float32Array;
+};
+
+export type MemoryWriteBatch = {
+  readonly workspaceRoot: string;
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+  readonly candidates: readonly MemoryWriteCandidate[];
+};
+
+export type MemoryWriteResult = {
+  readonly written: number;
+  readonly duplicate: number;
+  readonly inserted: readonly MemoryInsertedRecord[];
+};
+
+export type MemoryInsertedRecord = {
+  readonly memoryId: string;
+  readonly text: string;
+  readonly createdAt: string;
+};
+
+export type MemorySearchMatch = {
+  readonly memoryId: string;
+  readonly text: string;
+  readonly score: number;
+  readonly sourceWorkspace: string;
+  readonly createdAt: string;
+};
+
+export type StoredMemorySummary = {
+  readonly memoryId: string;
+  readonly text: string;
+  readonly sourceWorkspace: string;
+  readonly createdAt: string;
+};
+
+export type MemoryExtractionRejectedCounts = {
+  readonly duplicate: number;
+  readonly secret: number;
+  readonly invalid: number;
+  readonly embedding: number;
+};
+
+export type MemoryExtractionDiagnostic = {
+  readonly at: string;
+  readonly kind: "extraction";
+  readonly outcome: "ok" | "failed" | "skipped";
+  readonly reason: string | null;
+  readonly workspace: string;
+  readonly turnId: string;
+  readonly inputTokens: number;
+  readonly returned: number;
+  readonly written: number;
+  readonly rejected: MemoryExtractionRejectedCounts;
+  readonly ms: number;
+};
+
+export type MemorySearchDiagnostic = {
+  readonly at: string;
+  readonly kind: "search";
+  readonly outcome: "ok" | "failed" | "skipped";
+  readonly reason: string | null;
+  readonly workspace: string;
+  readonly sessionId: string;
+  readonly queryBytes: number;
+  readonly returned: number;
+  readonly scores: readonly number[];
+  readonly ms: number;
+};
+
+export type MemoryInitDiagnostic = {
+  readonly at: string;
+  readonly kind: "init";
+  readonly outcome: "failed";
+  readonly reason: string;
+};
+
+export type MemoryDiagnostic =
+  | MemoryExtractionDiagnostic
+  | MemorySearchDiagnostic
+  | MemoryInitDiagnostic;
+
+export class MemoryError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "MemoryError";
+  }
+}
+
+export function memoryErrorCode(error: unknown, fallback: string): string {
+  return error instanceof MemoryError ? error.code : fallback;
+}
+
+export function boundedMemoryError(error: unknown): string {
+  const raw = error instanceof Error ? error.message : String(error);
+  const singleLine = raw.replaceAll(/\s+/g, " ").trim() || "unknown memory error";
+  return truncateUtf8(singleLine, 400);
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) {
+    return value;
+  }
+  let end = Math.min(value.length, maxBytes);
+  while (end > 0 && Buffer.byteLength(`${value.slice(0, end)}…`, "utf8") > maxBytes) {
+    end -= 1;
+  }
+  return `${value.slice(0, end)}…`;
+}