tinker-agent 2.6.0 → 2.7.0

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

@@ -0,0 +1,88 @@
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import type { ToolCall } from "../agent/types";
+import {
+  defineToolExecutor,
+  type MemoryDeleteRawResult,
+  type ToolDefinition,
+  type ToolExecutor,
+} from "../tools/types";
+import { MAX_MEMORY_ID_BYTES, MEMORY_DELETE_TOOL_NAME } from "./contracts";
+
+export const MEMORY_DELETE_TOOL_DEFINITION: ToolDefinition = Object.freeze({
+  name: MEMORY_DELETE_TOOL_NAME,
+  description: "Delete one global memory shared across sessions and workspaces.",
+  parameters: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      id: {
+        type: "string",
+        minLength: 1,
+        maxLength: MAX_MEMORY_ID_BYTES,
+        description: "The memoryId returned by MemorySearch or MemoryGet.",
+      },
+    },
+    required: ["id"],
+  },
+});
+
+export function createMemoryDeleteToolExecutor(options: {
+  readonly delete: (
+    memoryId: string,
+    call: ToolCall,
+    signal: AbortSignal,
+  ) => Promise<MemoryDeleteRawResult>;
+  readonly recordInvalidCall: (call: ToolCall) => Promise<void>;
+}): ToolExecutor {
+  return defineToolExecutor("memory_delete", {
+    definition: MEMORY_DELETE_TOOL_DEFINITION,
+    async execute(args, call, context): Promise<MemoryDeleteRawResult> {
+      const parsed = parseMemoryDeleteArgs(args);
+      if (!parsed.ok) {
+        throwIfTurnCancelled(context.signal);
+        await options.recordInvalidCall(call);
+        throwIfTurnCancelled(context.signal);
+        return { ok: false, error: parsed.error };
+      }
+      const result = await options.delete(parsed.memoryId, call, context.signal);
+      throwIfTurnCancelled(context.signal);
+      return result;
+    },
+  });
+}
+
+type ParsedMemoryDeleteArgs =
+  | { readonly ok: true; readonly memoryId: string }
+  | { readonly ok: false; readonly error: string };
+
+function parseMemoryDeleteArgs(args: unknown): ParsedMemoryDeleteArgs {
+  if (!isRecord(args)) {
+    return {
+      ok: false,
+      error: "MemoryDelete arguments must be an object containing only id.",
+    };
+  }
+  const unexpected = Object.keys(args).find((key) => key !== "id");
+  if (unexpected !== undefined) {
+    return {
+      ok: false,
+      error: `MemoryDelete received unexpected field: ${unexpected}.`,
+    };
+  }
+  if (typeof args.id !== "string") {
+    return { ok: false, error: "MemoryDelete.id must be a string." };
+  }
+  const memoryId = args.id.trim();
+  const bytes = Buffer.byteLength(memoryId, "utf8");
+  if (bytes < 1 || bytes > MAX_MEMORY_ID_BYTES) {
+    return {
+      ok: false,
+      error: `MemoryDelete.id must be 1 to ${MAX_MEMORY_ID_BYTES} UTF-8 bytes after trimming.`,
+    };
+  }
+  return { ok: true, memoryId };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/memory/memory-store.ts

@@ -7,13 +7,17 @@ import { createUuidV7, isCanonicalUuidV7 } from "../ids/uuid-v7";
 import {
   MAX_MEMORY_SUMMARY_BYTES,
   MAX_MEMORY_TEXT_BYTES,
+  MAX_MEMORY_ID_BYTES,
   MEMORY_SCHEMA_VERSION,
   MEMORY_SEARCH_LIMIT,
   MemoryError,
   type MemoryEmbeddingIdentity,
   type MemoryFtsMatch,
+  type MemoryDeleteStoreResult,
   type MemoryPaths,
   type MemorySearchMatch,
+  type MemoryUpdateStoreResult,
+  type StoredMemoryMutationRecord,
   type StoredMemoryRecord,
   type StoredMemorySummary,
   type MemoryWriteBatch,
@@ -417,6 +421,164 @@ export class MemoryStore {
     });
   }
 
+  getByTextHash(text: string): StoredMemoryRecord | undefined {
+    this.requireOpen();
+    const rowValue = this.database
+      .query(
+        `SELECT memory_id, text, summary, source_workspace, source_session_id,
+                source_turn_id, created_at
+         FROM memories
+         WHERE text_sha256 = ?`,
+      )
+      .get(sha256(text));
+    return rowValue === null ? undefined : storedMemoryRecord(rowValue);
+  }
+
+  getByIdForMutation(memoryId: string): StoredMemoryMutationRecord | undefined {
+    this.requireOpen();
+    const rowValue = this.database
+      .query(
+        `SELECT memory_id, text, summary, embedding, source_workspace,
+                source_session_id, source_turn_id, created_at
+         FROM memories
+         WHERE memory_id = ?`,
+      )
+      .get(memoryId);
+    if (rowValue === null) {
+      return undefined;
+    }
+    const row = sqlRecord(rowValue, "memory row");
+    return Object.freeze({
+      ...storedMemoryRecord(row),
+      embedding: decodeEmbedding(
+        row.embedding,
+        expectedEmbeddingBlobBytes(this.dimensions),
+      ),
+    });
+  }
+
+  updateMemory(input: {
+    readonly memoryId: string;
+    readonly text: string;
+    readonly summary: string;
+    readonly embedding: Float32Array;
+  }): MemoryUpdateStoreResult {
+    this.requireOpen();
+    validateMemoryMutationInput(input, this.dimensions);
+    let outcome: MemoryUpdateStoreResult = Object.freeze({
+      ok: false,
+      code: "memory_not_found",
+    });
+    runImmediateTransaction(this.database, () => {
+      const targetValue = this.database
+        .query(
+          `SELECT rowid, text, summary
+           FROM memories
+           WHERE memory_id = ?`,
+        )
+        .get(input.memoryId);
+      if (targetValue === null) {
+        return;
+      }
+      const target = sqlRecord(targetValue, "memory update target");
+      const conflictValue = this.database
+        .query(
+          `SELECT memory_id
+           FROM memories
+           WHERE text_sha256 = ? AND memory_id <> ?`,
+        )
+        .get(sha256(input.text), input.memoryId);
+      if (conflictValue !== null) {
+        const conflict = sqlRecord(conflictValue, "memory update conflict");
+        outcome = Object.freeze({
+          ok: false,
+          code: "memory_duplicate",
+          conflictMemoryId: sqlString(conflict.memory_id, "memory_id"),
+        });
+        return;
+      }
+
+      const rowid = sqlInteger(target.rowid, "memory rowid");
+      if (this.ftsAvailable) {
+        deleteFtsEntry(
+          this.database,
+          rowid,
+          sqlString(target.text, "memory text"),
+          sqlSummary(target.summary, "memory summary"),
+        );
+      }
+      const result = this.database
+        .query(
+          `UPDATE memories
+           SET text = ?, summary = ?, text_sha256 = ?, embedding = ?
+           WHERE memory_id = ?`,
+        )
+        .run(
+          input.text,
+          input.summary,
+          sha256(input.text),
+          encodeEmbedding(input.embedding),
+          input.memoryId,
+        );
+      if (Number(result.changes) !== 1) {
+        throw new MemoryError(
+          "memory_write_failed",
+          `Memory update changed ${String(result.changes)} rows.`,
+        );
+      }
+      if (this.ftsAvailable) {
+        this.database
+          .query(
+            `INSERT INTO ${MEMORIES_FTS_TABLE}(rowid, text, summary) VALUES (?, ?, ?)`,
+          )
+          .run(rowid, input.text, input.summary);
+      }
+      outcome = Object.freeze({ ok: true, memoryId: input.memoryId });
+    });
+    return outcome;
+  }
+
+  deleteMemory(memoryId: string): MemoryDeleteStoreResult {
+    this.requireOpen();
+    validateMemoryId(memoryId);
+    let outcome: MemoryDeleteStoreResult = Object.freeze({
+      ok: false,
+      code: "memory_not_found",
+    });
+    runImmediateTransaction(this.database, () => {
+      const targetValue = this.database
+        .query(
+          `SELECT rowid, text, summary
+           FROM memories
+           WHERE memory_id = ?`,
+        )
+        .get(memoryId);
+      if (targetValue === null) {
+        return;
+      }
+      const target = sqlRecord(targetValue, "memory delete target");
+      if (this.ftsAvailable) {
+        deleteFtsEntry(
+          this.database,
+          sqlInteger(target.rowid, "memory rowid"),
+          sqlString(target.text, "memory text"),
+          sqlSummary(target.summary, "memory summary"),
+        );
+      }
+      const result = this.database
+        .query("DELETE FROM memories WHERE memory_id = ?")
+        .run(memoryId);
+      if (Number(result.changes) !== 1) {
+        throw new MemoryError(
+          "memory_write_failed",
+          `Memory delete changed ${String(result.changes)} rows.`,
+        );
+      }
+      outcome = Object.freeze({ ok: true, memoryId });
+    });
+    return outcome;
+  }
+
   count(): number {
     this.requireOpen();
     const row = this.database.query("SELECT COUNT(*) AS count FROM memories").get();
@@ -662,6 +824,20 @@ function backfillFtsIndex(database: Database): void {
   );
 }
 
+function deleteFtsEntry(
+  database: Database,
+  rowid: number,
+  text: string,
+  summary: string,
+): void {
+  database
+    .query(
+      `INSERT INTO ${MEMORIES_FTS_TABLE}(${MEMORIES_FTS_TABLE}, rowid, text, summary)
+       VALUES ('delete', ?, ?, ?)`,
+    )
+    .run(rowid, text, summary);
+}
+
 function countRows(database: Database, table: string): number {
   const row = sqlRecord(
     database.query(`SELECT COUNT(*) AS count FROM ${table}`).get(),
@@ -740,6 +916,42 @@ function validateWriteBatch(input: MemoryWriteBatch, dimensions: number): void {
   }
 }
 
+function validateMemoryMutationInput(
+  input: {
+    readonly memoryId: string;
+    readonly text: string;
+    readonly summary: string;
+    readonly embedding: Float32Array;
+  },
+  dimensions: number,
+): void {
+  validateMemoryId(input.memoryId);
+  if (
+    input.text.trim() !== input.text ||
+    Buffer.byteLength(input.text, "utf8") < 1 ||
+    Buffer.byteLength(input.text, "utf8") > MAX_MEMORY_TEXT_BYTES ||
+    input.summary.trim() !== input.summary ||
+    Buffer.byteLength(input.summary, "utf8") > MAX_MEMORY_SUMMARY_BYTES ||
+    input.embedding.length !== dimensions ||
+    [...input.embedding].some((value) => !Number.isFinite(value))
+  ) {
+    throw new MemoryError(
+      "memory_write_invalid",
+      "Memory update text, summary, or embedding is invalid.",
+    );
+  }
+}
+
+function validateMemoryId(memoryId: string): void {
+  if (
+    memoryId.trim() !== memoryId ||
+    Buffer.byteLength(memoryId, "utf8") < 1 ||
+    Buffer.byteLength(memoryId, "utf8") > MAX_MEMORY_ID_BYTES
+  ) {
+    throw new MemoryError("memory_write_invalid", "Memory ID is invalid.");
+  }
+}
+
 function validateEmbeddingIdentity(identity: MemoryEmbeddingIdentity): void {
   if (
     identity.name.trim() === "" ||
@@ -871,6 +1083,33 @@ function sqlSummary(value: unknown, name: string): string {
   return value;
 }
 
+function sqlInteger(value: unknown, name: string): number {
+  const integer = typeof value === "bigint" ? Number(value) : value;
+  if (!Number.isSafeInteger(integer) || (integer as number) < 1) {
+    throw new MemoryError(
+      "memory_store_read_failed",
+      `${name} must be a positive safe integer.`,
+    );
+  }
+  return integer as number;
+}
+
+function storedMemoryRecord(value: unknown): StoredMemoryRecord {
+  const row = sqlRecord(value, "memory row");
+  return Object.freeze({
+    memoryId: sqlString(row.memory_id, "memory_id"),
+    text: sqlString(row.text, "memory text"),
+    summary: sqlSummary(row.summary, "memory summary"),
+    sourceWorkspace: sqlString(row.source_workspace, "memory source_workspace"),
+    sourceSessionId: sqlString(row.source_session_id, "memory source_session_id"),
+    sourceTurnId: sqlString(row.source_turn_id, "memory source_turn_id"),
+    createdAt: requireUtcTimestamp(
+      sqlString(row.created_at, "memory created_at"),
+      "memory created_at",
+    ),
+  });
+}
+
 function requireUtcTimestamp(value: string, name: string): string {
   if (!value.endsWith("Z") || Number.isNaN(Date.parse(value))) {
     throw new MemoryError(

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

@@ -0,0 +1,142 @@
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import type { ToolCall } from "../agent/types";
+import {
+  defineToolExecutor,
+  type MemoryUpdateRawResult,
+  type ToolDefinition,
+  type ToolExecutor,
+} from "../tools/types";
+import {
+  MAX_MEMORY_ID_BYTES,
+  MAX_MEMORY_SUMMARY_BYTES,
+  MAX_MEMORY_TEXT_BYTES,
+  MEMORY_UPDATE_TOOL_NAME,
+} from "./contracts";
+
+export const MEMORY_UPDATE_TOOL_DEFINITION: ToolDefinition = Object.freeze({
+  name: MEMORY_UPDATE_TOOL_NAME,
+  description: "Replace one global memory shared across sessions and workspaces.",
+  parameters: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      id: {
+        type: "string",
+        minLength: 1,
+        maxLength: MAX_MEMORY_ID_BYTES,
+        description: "The memoryId returned by MemorySearch or MemoryGet.",
+      },
+      text: {
+        type: "string",
+        minLength: 1,
+        maxLength: MAX_MEMORY_TEXT_BYTES,
+        description: "The complete replacement one-line searchable index.",
+      },
+      summary: {
+        type: "string",
+        maxLength: MAX_MEMORY_SUMMARY_BYTES,
+        description:
+          "The complete replacement details, reasons, constraints, and scope.",
+      },
+    },
+    required: ["id", "text", "summary"],
+  },
+});
+
+export function createMemoryUpdateToolExecutor(options: {
+  readonly update: (
+    memoryId: string,
+    text: string,
+    summary: string,
+    call: ToolCall,
+    signal: AbortSignal,
+  ) => Promise<MemoryUpdateRawResult>;
+  readonly recordInvalidCall: (call: ToolCall) => Promise<void>;
+}): ToolExecutor {
+  return defineToolExecutor("memory_update", {
+    definition: MEMORY_UPDATE_TOOL_DEFINITION,
+    async execute(args, call, context): Promise<MemoryUpdateRawResult> {
+      const parsed = parseMemoryUpdateArgs(args);
+      if (!parsed.ok) {
+        throwIfTurnCancelled(context.signal);
+        await options.recordInvalidCall(call);
+        throwIfTurnCancelled(context.signal);
+        return { ok: false, error: parsed.error };
+      }
+      const result = await options.update(
+        parsed.memoryId,
+        parsed.text,
+        parsed.summary,
+        call,
+        context.signal,
+      );
+      throwIfTurnCancelled(context.signal);
+      return result;
+    },
+  });
+}
+
+type ParsedMemoryUpdateArgs =
+  | {
+      readonly ok: true;
+      readonly memoryId: string;
+      readonly text: string;
+      readonly summary: string;
+    }
+  | { readonly ok: false; readonly error: string };
+
+function parseMemoryUpdateArgs(args: unknown): ParsedMemoryUpdateArgs {
+  if (!isRecord(args)) {
+    return {
+      ok: false,
+      error:
+        "MemoryUpdate arguments must be an object containing only id, text, and summary.",
+    };
+  }
+  const unexpected = Object.keys(args).find(
+    (key) => key !== "id" && key !== "text" && key !== "summary",
+  );
+  if (unexpected !== undefined) {
+    return {
+      ok: false,
+      error: `MemoryUpdate received unexpected field: ${unexpected}.`,
+    };
+  }
+  if (typeof args.id !== "string") {
+    return { ok: false, error: "MemoryUpdate.id must be a string." };
+  }
+  const memoryId = args.id.trim();
+  const idBytes = Buffer.byteLength(memoryId, "utf8");
+  if (idBytes < 1 || idBytes > MAX_MEMORY_ID_BYTES) {
+    return {
+      ok: false,
+      error: `MemoryUpdate.id must be 1 to ${MAX_MEMORY_ID_BYTES} UTF-8 bytes after trimming.`,
+    };
+  }
+  if (typeof args.text !== "string") {
+    return { ok: false, error: "MemoryUpdate.text must be a string." };
+  }
+  const text = args.text.trim();
+  const textBytes = Buffer.byteLength(text, "utf8");
+  if (textBytes < 1 || textBytes > MAX_MEMORY_TEXT_BYTES) {
+    return {
+      ok: false,
+      error: `MemoryUpdate.text must be 1 to ${MAX_MEMORY_TEXT_BYTES} UTF-8 bytes after trimming.`,
+    };
+  }
+  if (typeof args.summary !== "string") {
+    return { ok: false, error: "MemoryUpdate.summary must be a string." };
+  }
+  const summary = args.summary.trim();
+  if (Buffer.byteLength(summary, "utf8") > MAX_MEMORY_SUMMARY_BYTES) {
+    return {
+      ok: false,
+      error: `MemoryUpdate.summary must be at most ${MAX_MEMORY_SUMMARY_BYTES} UTF-8 bytes after trimming.`,
+    };
+  }
+  return { ok: true, memoryId, text, summary };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/observation/observation-builder.ts

@@ -5,6 +5,7 @@ import {
   toolResultDisplayText,
 } from "../agent/tool-result-content";
 import type {
+  AskUserRawResult,
   BashRawResult,
   ContextMaintenanceRawResult,
   DeleteFileRawResult,
@@ -12,8 +13,11 @@ import type {
   GenericToolRawResult,
   GlobRawResult,
   GrepRawResult,
+  MemoryCreateRawResult,
+  MemoryDeleteRawResult,
   MemoryGetRawResult,
   MemorySearchRawResult,
+  MemoryUpdateRawResult,
   McpToolRawResult,
   ReadFileRawResult,
   RecallRawResult,
@@ -30,6 +34,7 @@ import type {
   WebSearchRawResult,
   WriteFileRawResult,
 } from "../tools/types";
+import { MAX_MEMORY_TEXT_BYTES, truncateUtf8 } from "../memory/contracts";
 
 export type ToolObservation = {
   readonly content: readonly ToolResultContent[];
@@ -55,6 +60,12 @@ export class ObservationBuilder {
         return textObservation(renderMemorySearchObservation(input.raw));
       case "memory_get":
         return textObservation(renderMemoryGetObservation(input.raw));
+      case "memory_create":
+        return textObservation(renderMemoryCreateObservation(input.raw, input.call));
+      case "memory_update":
+        return textObservation(renderMemoryUpdateObservation(input.raw, input.call));
+      case "memory_delete":
+        return textObservation(renderMemoryDeleteObservation(input.raw));
       case "skill":
         return textObservation(renderSkillObservation(input.raw));
       case "write":
@@ -69,6 +80,8 @@ export class ObservationBuilder {
         return textObservation(renderUpdatePlanObservation(input.raw));
       case "wait":
         return textObservation(renderWaitObservation(input.raw));
+      case "ask_user":
+        return textObservation(renderAskUserObservation(input.raw));
       case "task_list":
         return textObservation(renderTaskListObservation(input.raw));
       case "task_output":
@@ -120,6 +133,15 @@ function renderWaitObservation(raw: WaitRawResult): string {
     : `Wait failed: ${raw.error}`;
 }
 
+function renderAskUserObservation(raw: AskUserRawResult): string {
+  if (!raw.ok) {
+    return `AskUser failed: ${raw.error}`;
+  }
+  return raw.outcome === "selected"
+    ? `User selected: ${raw.answer}`
+    : "The user did not select an option. Decide how to proceed.";
+}
+
 function renderContextMaintenanceObservation(raw: ContextMaintenanceRawResult): string {
   if (!raw.ok) {
     if (raw.operation === "swap" && raw.rejected.length > 0) {
@@ -371,6 +393,54 @@ function renderMemoryGetObservation(raw: MemoryGetRawResult): string {
   ].join("\n\n");
 }
 
+function renderMemoryCreateObservation(
+  raw: MemoryCreateRawResult,
+  call: ToolCall,
+): string {
+  if (!raw.ok) {
+    return `MemoryCreate failed: ${raw.error}`;
+  }
+  const text = memoryMutationText(call);
+  const result = `MemoryCreate ${raw.status} memory=${raw.memoryId} created_at=${raw.createdAt}.`;
+  return text === undefined ? result : `${result}\ntext: ${text}`;
+}
+
+function renderMemoryUpdateObservation(
+  raw: MemoryUpdateRawResult,
+  call: ToolCall,
+): string {
+  if (!raw.ok) {
+    if (raw.code === "memory_duplicate") {
+      return `MemoryUpdate failed: code=${raw.code} conflict_memory=${raw.conflictMemoryId} error=${raw.error}`;
+    }
+    return raw.code === "memory_not_found"
+      ? `MemoryUpdate failed: code=${raw.code} error=${raw.error}`
+      : `MemoryUpdate failed: ${raw.error}`;
+  }
+  const text = memoryMutationText(call);
+  const result = `MemoryUpdate ${raw.status} memory=${raw.memoryId}.`;
+  return text === undefined ? result : `${result}\ntext: ${text}`;
+}
+
+function renderMemoryDeleteObservation(raw: MemoryDeleteRawResult): string {
+  if (!raw.ok) {
+    return raw.code === "memory_not_found"
+      ? `MemoryDelete failed: code=${raw.code} error=${raw.error}`
+      : `MemoryDelete failed: ${raw.error}`;
+  }
+  return `MemoryDelete ${raw.status} memory=${raw.memoryId}.`;
+}
+
+function memoryMutationText(call: ToolCall): string | undefined {
+  if (typeof call.args !== "object" || call.args === null || Array.isArray(call.args)) {
+    return undefined;
+  }
+  const text = (call.args as Record<string, unknown>).text;
+  return typeof text === "string"
+    ? truncateUtf8(text.trim(), MAX_MEMORY_TEXT_BYTES)
+    : undefined;
+}
+
 export function renderSkillObservation(raw: SkillRawResult): string {
   if (!raw.ok) {
     return `Skill failed for ${raw.name || "(unknown skill)"} (${raw.errorCode}): ${raw.error}`;

package/src/session/session-tool-result-codec.ts

@@ -50,7 +50,11 @@ export function decodeStoredToolRawResult(value: unknown): ToolRawResult {
       "context_maintenance",
       "memory_search",
       "memory_get",
+      "memory_create",
+      "memory_update",
+      "memory_delete",
       "wait",
+      "ask_user",
       "skill",
       "mcp",
       "generic",