@agenr/agenr-plugin 3.0.0 → 3.1.0

package/dist/{chunk-MYZ2CWY6.js → chunk-E2DHUFZK.js}

@@ -1,26 +1,43 @@
 import {
+  ENTRY_TYPE_DESCRIPTION,
+  EXPIRY_DESCRIPTION,
+  RECALL_MODES,
+  UPDATE_EXPIRY_DESCRIPTION,
+  asRecord,
+  buildEntryMemoryResolverPorts,
   createMemoryRepository,
+  formatErrorMessage,
   ingestEpisodeTranscript,
+  normalizeStringArray,
+  parseEntryType,
+  parseEntryTypes,
+  parseExpiry,
+  parseRecallMode,
+  resolveTargetEntry,
   storeEntriesDetailed
-} from "./chunk-LAXNNWHM.js";
+} from "./chunk-EEEL53X4.js";
 import {
   containsAgenrMemoryContext,
   formatInjectionEntryBodyLines,
   formatInjectionEntryHeader,
   stripAgenrMemoryContext,
   wrapAgenrMemoryContext
-} from "./chunk-575MUIW5.js";
+} from "./chunk-V5CDMHRN.js";
 import {
+  ENTRY_PREVIEW_MAX_CHARS,
   ENTRY_SELECT_COLUMNS,
   ENTRY_TYPES,
-  EXPIRY_LEVELS,
+  assertEntryFetchableContentLength,
   attachCrossEncoderPort,
   buildActiveEntryClause,
+  buildEntryRecallPreview,
+  buildFetchToolDetails,
   createDatabase,
   createEmbeddingClient,
   createLlmClient,
   createOpenAICrossEncoder,
   createRecallAdapter,
+  formatFetchedEntryText,
   mapEntryRow,
   normalizeManualClaimKeyUpdate,
   projectClaimCentricRecallEntry,
@@ -28,6 +45,7 @@ import {
   readNumber,
   readOptionalString,
   readRequiredString,
+  recallResultHasTruncatedEntryPreviews,
   resolveClaimExtractionConfig,
   resolveConfigPath,
   resolveCrossEncoderApiKey,
@@ -37,17 +55,13 @@ import {
   resolveLlmApiKey,
   resolveModel,
   runUnifiedRecall,
+  truncate,
   validateTemporalValidityRange
-} from "./chunk-ELR2HSVC.js";
+} from "./chunk-NNO2V4GH.js";
 import {
   recall
 } from "./chunk-5LADPJ4C.js";
 
-// src/adapters/shared/errors.ts
-function formatErrorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 // src/app/plugin-runtime/session-tracking.ts
 function resolveSessionIdentityKey(sessionId, sessionKey) {
   const normalizedSessionId = sessionId?.trim();
@@ -459,7 +473,7 @@ function buildArtifactRecallQuery(sections, maxChars) {
       continue;
     }
     const labeled = `${section.title}: ${normalizedContent}`;
-    const truncated = truncate(labeled, remaining);
+    const truncated = truncate2(labeled, remaining);
     if (truncated.length === 0) {
       continue;
     }
@@ -570,7 +584,7 @@ function normalizeOptionalString2(value) {
 function normalizeWhitespace(value) {
   return value.replace(/\s+/g, " ").trim();
 }
-function truncate(value, maxChars) {
+function truncate2(value, maxChars) {
   if (maxChars <= 0) {
     return "";
   }
@@ -1814,536 +1828,213 @@ async function composeHostPluginServices(input) {
   });
 }
 
-// src/adapters/shared/recall-format.ts
-function formatUnifiedRecallResults(result) {
-  const lines = [
-    "Recall Route",
-    `requested=${result.routing.requested} detected=${result.routing.detectedIntent} queried=${result.routing.queried.join(", ") || "none"}`,
-    result.routing.reason,
-    ""
-  ];
-  if (result.timeWindow) {
-    lines.push("Resolved Time Window");
-    lines.push(`${result.timeWindow.start} -> ${result.timeWindow.end} (${result.timeWindow.timezone}) from ${JSON.stringify(result.timeWindow.resolvedFrom)}`);
-    lines.push("");
-  }
-  if (result.asOf) {
-    lines.push("As Of");
-    lines.push(result.asOf);
-    lines.push("");
-  }
-  if (result.routing.queried.includes("procedures") || result.procedure || result.procedureCandidates.length > 0 || result.procedureNotices.length > 0) {
-    appendProcedureMatches(lines, result);
-    lines.push("");
-  }
-  const renderEntriesFirst = result.routing.detectedIntent === "historical_state";
-  if (renderEntriesFirst) {
-    appendEntryMatches(lines, result);
-    lines.push("");
-    appendClaimTransitions(lines, result);
-    lines.push("");
-    appendEpisodeMatches(lines, result);
-  } else {
-    appendEpisodeMatches(lines, result);
-    lines.push("");
-    appendEntryMatches(lines, result);
-    lines.push("");
-    appendClaimTransitions(lines, result);
-  }
-  if (result.notices.length > 0) {
-    lines.push("");
-    lines.push("Notices");
-    for (const notice of result.notices) {
-      lines.push(`- ${notice}`);
-    }
-  }
-  return lines.join("\n");
+// src/adapters/shared/claim-support.ts
+function buildSessionSourceFile(session, prefix) {
+  const target = session.sessionKey ?? session.sessionId ?? session.agentId ?? "unknown";
+  return `${prefix}:${target}`;
 }
-function appendProcedureMatches(lines, result) {
-  lines.push("Procedure Matches");
-  if (!result.procedure && result.procedureCandidates.length === 0) {
-    lines.push("None.");
-  } else {
-    if (result.procedure) {
-      appendCanonicalProcedure(lines, result.procedure, result.procedureCandidates);
-    } else {
-      lines.push("Canonical procedure: none.");
+function buildToolCallClaimSupport(session, prefix, toolName, observedAt) {
+  return {
+    claim_support_source_kind: "tool_call",
+    claim_support_locator: `${buildSessionSourceFile(session, prefix)}#${toolName}`,
+    claim_support_observed_at: observedAt,
+    claim_support_mode: "explicit"
+  };
+}
+
+// src/adapters/shared/memory-tools.ts
+function buildRecallToolServices(services) {
+  return {
+    episodes: services.episodes,
+    procedures: services.procedures,
+    recall: services.recall,
+    embeddingStatus: services.embeddingStatus,
+    embedQuery: services.beforeTurn.embedQuery
+  };
+}
+var STORE_TOOL_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    type: {
+      type: "string",
+      enum: [...ENTRY_TYPES],
+      description: ENTRY_TYPE_DESCRIPTION
+    },
+    subject: {
+      type: "string",
+      description: "Short subject line future recall can match. Name the durable takeaway, person, system, rule, relationship, or milestone directly."
+    },
+    content: {
+      type: "string",
+      description: "What a fresh session should remember. Store the durable takeaway, not the activity log, canonical record, or transient progress snapshot."
+    },
+    importance: {
+      type: "integer",
+      minimum: 1,
+      maximum: 10,
+      description: "Importance from 1 to 10. Use 7 for normal durable memory, 9 for critical constraints, and 10 only rarely."
+    },
+    expiry: {
+      type: "string",
+      enum: ["core", "permanent", "temporary"],
+      description: EXPIRY_DESCRIPTION
+    },
+    tags: {
+      type: "array",
+      items: { type: "string" },
+      description: "Optional tags for entities, systems, teams, or themes that should improve later recall."
+    },
+    sourceContext: {
+      type: "string",
+      description: "Optional provenance note explaining why this memory was stored or what situation produced it."
+    },
+    supersedes: {
+      type: "string",
+      description: "ID of an entry this replaces. The old entry will be marked as superseded."
+    },
+    claimKey: {
+      type: "string",
+      description: 'Slot key identifying the specific knowledge slot (entity/attribute format, e.g., "project_name/deploy_strategy" or "postgres/max_connections"). Entries with the same claim key are candidates for supersession.'
+    },
+    validFrom: {
+      type: "string",
+      description: "ISO 8601 timestamp for when this fact became true in the world."
+    },
+    validTo: {
+      type: "string",
+      description: "ISO 8601 timestamp for when this fact stopped being true."
     }
-    const additionalCandidates = result.procedureCandidates.filter((candidate) => candidate.procedure.id !== result.procedure?.id);
-    if (additionalCandidates.length > 0) {
-      lines.push("Other Candidates");
-      for (const [index, candidate] of additionalCandidates.entries()) {
-        lines.push(
-          `${index + 1}. ${candidate.procedure.procedure_key} | ${candidate.procedure.title} | score ${candidate.score.toFixed(2)} | lexical=${candidate.scores.lexical.toFixed(2)} | vector=${candidate.scores.vector.toFixed(2)}`
-        );
-      }
+  },
+  required: ["type", "subject", "content"]
+};
+var RECALL_TOOL_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    query: {
+      type: "string",
+      description: "What you need to remember. Use a focused natural-language query rather than a broad 'everything' search. Phrase prior-state asks directly, for example 'what was the previous approach' or 'what changed from X to Y'. Phrase procedural asks directly, for example 'how do I rotate credentials' or 'what steps should I follow'."
+    },
+    mode: {
+      type: "string",
+      enum: [...RECALL_MODES],
+      description: "Recall mode: auto routes between exact entry recall, historical-state recall, procedural recall, and episodes; entries forces semantic recall; episodes forces temporal or semantic session recall; procedures forces procedural recall."
+    },
+    limit: {
+      type: "integer",
+      minimum: 1,
+      maximum: 10,
+      description: "Maximum results to return. Lower this when you want a tighter shortlist."
+    },
+    threshold: {
+      type: "number",
+      minimum: 0,
+      maximum: 1,
+      description: "Minimum final score from 0 to 1. Raise this when you want fewer, higher-confidence matches."
+    },
+    budget: {
+      type: "integer",
+      minimum: 1,
+      description: "Approximate token budget applied after entry scoring. Omit when you do not want a budget cap."
+    },
+    types: {
+      type: "array",
+      items: {
+        type: "string",
+        enum: [...ENTRY_TYPES]
+      },
+      description: "Optional knowledge types to filter by, such as decision, preference, lesson, fact, milestone, or relationship."
+    },
+    tags: {
+      type: "array",
+      items: { type: "string" },
+      description: "Optional tags to filter by once you already know the relevant entity, system, or theme."
+    },
+    asOf: {
+      type: "string",
+      description: "Optional reference time for current-vs-prior resolution. Supports ISO timestamps and natural-language date phrases."
+    }
+  },
+  required: ["query"]
+};
+var UPDATE_TOOL_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    id: {
+      type: "string",
+      description: "Entry id to update. Provide exactly one of id or subject."
+    },
+    subject: {
+      type: "string",
+      description: "Subject text to resolve when the id is unknown. The most recent exact or substring match wins. Provide exactly one of id or subject."
+    },
+    importance: {
+      type: "integer",
+      description: "New importance from 1 to 10. Use 7 for normal durable memory and reserve 9 to 10 for rare critical entries."
+    },
+    expiry: {
+      type: "string",
+      description: UPDATE_EXPIRY_DESCRIPTION
+    },
+    claimKey: {
+      type: "string",
+      description: 'Slot key identifying the specific knowledge slot (entity/attribute format, e.g., "project_name/deploy_strategy" or "postgres/max_connections"). Entries with the same claim key are candidates for supersession.'
+    },
+    validFrom: {
+      type: "string",
+      description: "ISO 8601 timestamp for when this fact became true."
+    },
+    validTo: {
+      type: "string",
+      description: "ISO 8601 timestamp for when this fact stopped being true."
     }
   }
-  if (result.procedureNotices.length > 0) {
-    lines.push("Procedure Notices");
-    for (const notice of result.procedureNotices) {
-      lines.push(`- ${notice}`);
+};
+var FETCH_TOOL_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    id: {
+      type: "string",
+      description: "Entry id to fetch. Provide exactly one of id or subject."
+    },
+    subject: {
+      type: "string",
+      description: "Subject text to resolve when the id is unknown. The most recent exact or substring match wins. Provide exactly one of id or subject."
     }
   }
-}
-function appendEntryMatches(lines, result) {
-  lines.push("Entry Matches");
-  if (result.projectedEntries.length === 0) {
-    lines.push("None.");
-    return;
-  }
-  for (const [familyIndex, family] of result.entryFamilies.entries()) {
-    lines.push(
-      family.claimKey ? `Family ${familyIndex + 1}. claim_key=${family.claimKey} | slot_policy=${family.slotPolicy} | primary=${family.primary.entryId} | subject=${family.subject}` : `Standalone ${familyIndex + 1}. ${family.primary.entryId} | subject=${family.subject}`
-    );
-    for (const [entryIndex, entry] of family.entries.entries()) {
-      lines.push(
-        `   ${entryIndex + 1}. ${entry.entryId} | ${entry.recall.entry.type} | ${entry.recall.entry.subject} | score ${entry.recall.score.toFixed(2)} | state=${entry.memoryState} | claim_status=${formatClaimStatus(entry.claimStatus)}`
-      );
-      lines.push(`      ${truncate2(entry.recall.entry.content, 220)}`);
-      lines.push(`      freshness=${entry.freshness.label}`);
-      const provenance = formatProjectedEntryProvenance(entry);
-      if (provenance) {
-        lines.push(`      provenance=${provenance}`);
-      }
-      lines.push(`      why_surfaced=${entry.whySurfaced.summary}`);
-    }
-  }
-}
-function appendEpisodeMatches(lines, result) {
-  lines.push("Episode Matches");
-  if (result.episodes.length === 0) {
-    lines.push("None.");
-    return;
-  }
-  for (const [index, episode] of result.episodes.entries()) {
-    lines.push(
-      `${index + 1}. ${episode.episode.id} | ${episode.episode.source} | ${episode.episode.startedAt} -> ${episode.episode.endedAt ?? episode.episode.startedAt} | score ${episode.score.toFixed(2)}`
-    );
-    lines.push(`   ${index < 3 ? episode.episode.summary.trim() : truncate2(episode.episode.summary.trim(), 220)}`);
-    lines.push(`   why_matched=${describeEpisodeMatch(episode)}`);
-  }
-}
-function appendCanonicalProcedure(lines, procedure, candidates) {
-  const leadCandidate = candidates.find((candidate) => candidate.procedure.id === procedure.id);
-  lines.push(
-    leadCandidate ? `Canonical Procedure. ${procedure.procedure_key} | ${procedure.title} | score ${leadCandidate.score.toFixed(2)}` : `Canonical Procedure. ${procedure.procedure_key} | ${procedure.title}`
-  );
-  lines.push(`   goal=${procedure.goal}`);
-  appendLabeledList(lines, "when_to_use", procedure.when_to_use);
-  appendLabeledList(lines, "when_not_to_use", procedure.when_not_to_use);
-  appendLabeledList(lines, "prerequisites", procedure.prerequisites);
-  lines.push("   steps");
-  for (const [index, step] of procedure.steps.entries()) {
-    lines.push(`   ${index + 1}. [${step.kind}] ${step.instruction}`);
-    const stepDetails = formatProcedureStepDetails(step);
-    if (stepDetails.length > 0) {
-      for (const detail of stepDetails) {
-        lines.push(`      ${detail}`);
-      }
-    }
-  }
-  appendLabeledList(lines, "verification", procedure.verification);
-  appendLabeledList(lines, "failure_modes", procedure.failure_modes);
-  lines.push("   sources");
-  for (const source of procedure.sources) {
-    lines.push(`   - ${formatProcedureSource(source)}`);
-  }
-}
-function appendClaimTransitions(lines, result) {
-  lines.push("Claim Transitions");
-  if (result.claimTransitions.length === 0) {
-    lines.push("None.");
-    return;
-  }
-  for (const [index, transition] of result.claimTransitions.entries()) {
-    lines.push(
-      `${index + 1}. family=${transition.claimKey ?? transition.familyKey} | slot_policy=${transition.slotPolicy}${transition.currentEntryId ? ` | current=${transition.currentEntryId}` : ""}${transition.priorEntryId ? ` | prior=${transition.priorEntryId}` : ""}`
-    );
-    lines.push(`   ${transition.summary}`);
-    if (transition.episodeContext) {
-      lines.push(
-        `   episode=${transition.episodeContext.episodeId} | ${transition.episodeContext.startedAt} -> ${transition.episodeContext.endedAt ?? transition.episodeContext.startedAt}`
-      );
-      lines.push(`   ${truncate2(transition.episodeContext.summary.trim(), 220)}`);
-    }
-  }
-}
-function appendLabeledList(lines, label, values) {
-  lines.push(`   ${label}`);
-  if (values.length === 0) {
-    lines.push("   - none");
-    return;
-  }
-  for (const value of values) {
-    lines.push(`   - ${value}`);
-  }
-}
-function formatProcedureStepDetails(step) {
-  switch (step.kind) {
-    case "run_command":
-      return [`command=${step.command}`];
-    case "read_reference":
-      return [`ref=${formatProcedureSource(step.ref)}`];
-    case "inspect_state":
-      return [step.target ? `target=${step.target}` : void 0, step.query ? `query=${step.query}` : void 0].filter(
-        (value) => value !== void 0
-      );
-    case "edit_file":
-      return [`path=${step.path}`, `edit=${step.edit}`];
-    case "ask_user":
-      return [`prompt=${step.prompt}`];
-    case "invoke_tool":
-      return [step.tool ? `tool=${step.tool}` : void 0, step.arguments ? `arguments=${JSON.stringify(step.arguments)}` : void 0].filter(
-        (value) => value !== void 0
-      );
-    case "verify":
-      return step.checks.map((check) => `check=${check}`);
-    default:
-      return [];
-  }
-}
-function formatProcedureSource(source) {
-  const parts = [source.kind, source.label, source.path, source.locator].filter((value) => Boolean(value && value.length > 0));
-  return parts.join(" | ");
-}
-function describeEpisodeMatch(result) {
-  if (result.scores.semantic > 0 && result.scores.temporal > 0) {
-    return "Semantic match within the resolved time window.";
-  }
-  if (result.scores.semantic > 0) {
-    return "Semantic match to the episode summary.";
-  }
-  if (result.scores.temporal > 0) {
-    return "Session overlaps the resolved time window.";
-  }
-  return "Matched episodic recall ranking.";
-}
-function formatClaimStatus(status) {
-  return status === "no_key" ? "no-key" : status;
-}
-function formatProjectedEntryProvenance(entry) {
-  const parts = [
-    entry.provenance.supersededById ? `superseded_by=${entry.provenance.supersededById}` : void 0,
-    entry.provenance.supersessionKind ? `kind=${entry.provenance.supersessionKind}` : void 0,
-    entry.provenance.supersessionReason ? `reason=${truncate2(entry.provenance.supersessionReason, 120)}` : void 0,
-    entry.provenance.supportSourceKind ? `support=${entry.provenance.supportSourceKind}` : void 0,
-    entry.provenance.supportMode ? `support_mode=${entry.provenance.supportMode}` : void 0,
-    entry.provenance.supportObservedAt ? `observed=${entry.provenance.supportObservedAt}` : void 0,
-    entry.provenance.supportLocator ? `locator=${truncate2(entry.provenance.supportLocator, 120)}` : void 0
-  ].filter((value) => value !== void 0);
-  return parts.join(" | ");
-}
-function truncate2(value, maxChars) {
-  if (value.length <= maxChars) {
-    return value;
-  }
-  return `${value.slice(0, maxChars - 3).trimEnd()}...`;
-}
-
-// src/adapters/shared/entry-tools.ts
-var ENTRY_TYPE_DESCRIPTION = "Knowledge type to store. Use fact for durable truth about a person, system, place, or how something works. Use decision for a standing rule, constraint, policy, or chosen approach future sessions should follow - not a progress update or completed action. Use preference for what someone likes, wants, values, or wants avoided. Use lesson for a non-obvious takeaway learned from experience that should change future behavior. Use milestone for a rare one-time event with durable future significance - not ordinary execution progress. Use relationship for a meaningful durable connection between people, groups, or systems.";
-var EXPIRY_DESCRIPTION = "Lifetime bucket: core (always injected at session start, use sparingly), permanent (durable and recalled on demand), or temporary (short-horizon).";
-var UPDATE_EXPIRY_DESCRIPTION = `${EXPIRY_DESCRIPTION} Accepted values: ${EXPIRY_LEVELS.join(", ")}.`;
-var RECALL_MODES = ["auto", "entries", "episodes", "procedures"];
-function asRecord(value) {
-  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-    return value;
-  }
-  throw new Error("Tool parameters must be an object.");
-}
-function parseExpiry(value) {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (EXPIRY_LEVELS.includes(value)) {
-    return value;
-  }
-  throw new Error(`Unsupported expiry "${value}".`);
-}
-function parseEntryTypes(values) {
-  return normalizeStringArray(values).map((value) => parseEntryType(value));
-}
-function parseEntryType(value) {
-  if (ENTRY_TYPES.includes(value)) {
-    return value;
-  }
-  throw new Error(`Unsupported entry type "${value}".`);
-}
-function parseRecallMode(value) {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (RECALL_MODES.includes(value)) {
-    return value;
-  }
-  throw new Error(`Unsupported recall mode "${value}".`);
-}
-function normalizeStringArray(values) {
-  if (!values) {
-    return [];
-  }
-  return Array.from(new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)));
-}
-function formatTargetSelector(id, subject, last) {
-  if (last === true) {
-    return "last";
-  }
-  if (id) {
-    return `id:${JSON.stringify(id)}`;
-  }
-  if (subject) {
-    return `subject:${JSON.stringify(subject)}`;
-  }
-  return "unknown";
-}
-function sanitizeUpdateToolParams(params) {
-  return {
-    ...params.id ? { id: params.id } : {},
-    ...params.subject ? { subject: params.subject } : {},
-    ...params.importance !== void 0 ? { importance: params.importance } : {},
-    ...params.expiry !== void 0 ? { expiry: params.expiry } : {},
-    ...params.claimKey !== void 0 ? { hasClaimKey: true } : {},
-    ...params.validFrom !== void 0 ? { hasValidFrom: true } : {},
-    ...params.validTo !== void 0 ? { hasValidTo: true } : {}
-  };
-}
-
-// src/adapters/shared/resolve-target.ts
-async function resolveTargetEntry(ports, params, options = {}) {
-  const id = readOptionalStringParam(params, "id");
-  const subject = readOptionalStringParam(params, "subject");
-  const last = options.allowLast ? readBooleanParam(params, "last") : void 0;
-  const selectorCount = (id ? 1 : 0) + (subject ? 1 : 0) + (last === true ? 1 : 0);
-  const selectorDescription = options.allowLast ? "id, subject, or last" : "id or subject";
-  if (selectorCount !== 1) {
-    throw new Error(`Provide exactly one target selector: ${selectorDescription}.`);
-  }
-  if (last) {
-    const entry2 = await ports.findMostRecentEntry();
-    if (!entry2) {
-      throw new Error("No agenr entries exist yet.");
-    }
-    return entry2;
-  }
-  if (id) {
-    const entry2 = await ports.getEntryById(id);
-    if (!entry2) {
-      throw new Error(`No agenr entry found for id ${id}.`);
-    }
-    return entry2;
-  }
-  const entry = await ports.findEntryBySubject(subject ?? "");
-  if (!entry) {
-    throw new Error(`No agenr entry found for subject "${subject}".`);
-  }
-  return entry;
-}
-function readBooleanParam(params, key) {
-  const value = params[key];
-  if (value === void 0) {
-    return void 0;
-  }
-  if (typeof value === "boolean") {
-    return value;
-  }
-  throw new Error(`${key} must be a boolean.`);
-}
-function readOptionalStringParam(params, key) {
-  const value = params[key];
-  if (value === void 0 || value === null) {
-    return void 0;
-  }
-  if (typeof value !== "string") {
-    throw new Error(`${key} must be a string.`);
-  }
-  const normalized = value.trim();
-  return normalized.length > 0 ? normalized : void 0;
-}
-
-// src/adapters/shared/claim-support.ts
-function buildSessionSourceFile(session, prefix) {
-  const target = session.sessionKey ?? session.sessionId ?? session.agentId ?? "unknown";
-  return `${prefix}:${target}`;
-}
-function buildToolCallClaimSupport(session, prefix, toolName, observedAt) {
-  return {
-    claim_support_source_kind: "tool_call",
-    claim_support_locator: `${buildSessionSourceFile(session, prefix)}#${toolName}`,
-    claim_support_observed_at: observedAt,
-    claim_support_mode: "explicit"
-  };
-}
-
-// src/adapters/shared/memory-tools.ts
-function buildRecallToolServices(services) {
-  return {
-    episodes: services.episodes,
-    procedures: services.procedures,
-    recall: services.recall,
-    embeddingStatus: services.embeddingStatus,
-    embedQuery: services.beforeTurn.embedQuery
-  };
-}
-var STORE_TOOL_PARAMETERS = {
-  type: "object",
-  additionalProperties: false,
-  properties: {
-    type: {
-      type: "string",
-      enum: [...ENTRY_TYPES],
-      description: ENTRY_TYPE_DESCRIPTION
-    },
-    subject: {
-      type: "string",
-      description: "Short subject line future recall can match. Name the durable takeaway, person, system, rule, relationship, or milestone directly."
-    },
-    content: {
-      type: "string",
-      description: "What a fresh session should remember. Store the durable takeaway, not the activity log, canonical record, or transient progress snapshot."
-    },
-    importance: {
-      type: "integer",
-      minimum: 1,
-      maximum: 10,
-      description: "Importance from 1 to 10. Use 7 for normal durable memory, 9 for critical constraints, and 10 only rarely."
-    },
-    expiry: {
-      type: "string",
-      enum: ["core", "permanent", "temporary"],
-      description: EXPIRY_DESCRIPTION
-    },
-    tags: {
-      type: "array",
-      items: { type: "string" },
-      description: "Optional tags for entities, systems, teams, or themes that should improve later recall."
-    },
-    sourceContext: {
-      type: "string",
-      description: "Optional provenance note explaining why this memory was stored or what situation produced it."
-    },
-    supersedes: {
-      type: "string",
-      description: "ID of an entry this replaces. The old entry will be marked as superseded."
-    },
-    claimKey: {
-      type: "string",
-      description: 'Slot key identifying the specific knowledge slot (entity/attribute format, e.g., "project_name/deploy_strategy" or "postgres/max_connections"). Entries with the same claim key are candidates for supersession.'
-    },
-    validFrom: {
-      type: "string",
-      description: "ISO 8601 timestamp for when this fact became true in the world."
-    },
-    validTo: {
-      type: "string",
-      description: "ISO 8601 timestamp for when this fact stopped being true."
-    }
-  },
-  required: ["type", "subject", "content"]
-};
-var RECALL_TOOL_PARAMETERS = {
-  type: "object",
-  additionalProperties: false,
-  properties: {
-    query: {
-      type: "string",
-      description: "What you need to remember. Use a focused natural-language query rather than a broad 'everything' search. Phrase prior-state asks directly, for example 'what was the previous approach' or 'what changed from X to Y'. Phrase procedural asks directly, for example 'how do I rotate credentials' or 'what steps should I follow'."
-    },
-    mode: {
-      type: "string",
-      enum: [...RECALL_MODES],
-      description: "Recall mode: auto routes between exact entry recall, historical-state recall, procedural recall, and episodes; entries forces semantic recall; episodes forces temporal or semantic session recall; procedures forces procedural recall."
-    },
-    limit: {
-      type: "integer",
-      minimum: 1,
-      maximum: 10,
-      description: "Maximum results to return. Lower this when you want a tighter shortlist."
-    },
-    threshold: {
-      type: "number",
-      minimum: 0,
-      maximum: 1,
-      description: "Minimum final score from 0 to 1. Raise this when you want fewer, higher-confidence matches."
-    },
-    types: {
-      type: "array",
-      items: {
-        type: "string",
-        enum: [...ENTRY_TYPES]
-      },
-      description: "Optional knowledge types to filter by, such as decision, preference, lesson, fact, milestone, or relationship."
-    },
-    tags: {
-      type: "array",
-      items: { type: "string" },
-      description: "Optional tags to filter by once you already know the relevant entity, system, or theme."
-    },
-    asOf: {
-      type: "string",
-      description: "Optional reference time for current-vs-prior resolution. Supports ISO timestamps and natural-language date phrases."
-    }
-  },
-  required: ["query"]
-};
-var UPDATE_TOOL_PARAMETERS = {
-  type: "object",
-  additionalProperties: false,
-  properties: {
-    id: {
-      type: "string",
-      description: "Entry id to update. Provide exactly one of id or subject."
-    },
-    subject: {
-      type: "string",
-      description: "Subject text to resolve when the id is unknown. The most recent exact or substring match wins. Provide exactly one of id or subject."
-    },
-    importance: {
-      type: "integer",
-      description: "New importance from 1 to 10. Use 7 for normal durable memory and reserve 9 to 10 for rare critical entries."
-    },
-    expiry: {
-      type: "string",
-      description: UPDATE_EXPIRY_DESCRIPTION
-    },
-    claimKey: {
-      type: "string",
-      description: 'Slot key identifying the specific knowledge slot (entity/attribute format, e.g., "project_name/deploy_strategy" or "postgres/max_connections"). Entries with the same claim key are candidates for supersession.'
-    },
-    validFrom: {
-      type: "string",
-      description: "ISO 8601 timestamp for when this fact became true."
-    },
-    validTo: {
-      type: "string",
-      description: "ISO 8601 timestamp for when this fact stopped being true."
-    }
-  }
-};
-function parseStoreToolParams(rawParams, reader) {
-  const params = asRecord(rawParams);
-  const type = parseEntryType(reader.readString(params, "type", { required: true, label: "type" }) ?? "");
-  return {
-    type,
-    subject: reader.readString(params, "subject", { required: true, label: "subject" }) ?? "",
-    content: reader.readString(params, "content", { required: true, label: "content" }) ?? "",
-    importance: reader.readNumber(params, "importance", { integer: true, strict: true }),
-    expiry: parseExpiry(reader.readString(params, "expiry")),
-    tags: normalizeStringArray(reader.readStringArray(params, "tags")),
-    sourceContext: reader.readString(params, "sourceContext"),
-    supersedes: reader.readString(params, "supersedes"),
-    claimKey: reader.readString(params, "claimKey", { trim: false }),
-    validFrom: reader.readString(params, "validFrom"),
-    validTo: reader.readString(params, "validTo")
-  };
+};
+function parseStoreToolParams(rawParams, reader) {
+  const params = asRecord(rawParams);
+  const type = parseEntryType(reader.readString(params, "type", { required: true, label: "type" }) ?? "");
+  return {
+    type,
+    subject: reader.readString(params, "subject", { required: true, label: "subject" }) ?? "",
+    content: reader.readString(params, "content", { required: true, label: "content" }) ?? "",
+    importance: reader.readNumber(params, "importance", { integer: true, strict: true }),
+    expiry: parseExpiry(reader.readString(params, "expiry")),
+    tags: normalizeStringArray(reader.readStringArray(params, "tags")),
+    sourceContext: reader.readString(params, "sourceContext"),
+    supersedes: reader.readString(params, "supersedes"),
+    claimKey: reader.readString(params, "claimKey", { trim: false }),
+    validFrom: reader.readString(params, "validFrom"),
+    validTo: reader.readString(params, "validTo")
+  };
 }
 function parseRecallToolParams(rawParams, reader) {
   const params = asRecord(rawParams);
+  const budget = reader.readNumber(params, "budget", { integer: true, strict: true });
+  if (budget !== void 0 && budget <= 0) {
+    throw new Error("budget must be a positive integer.");
+  }
   return {
     query: reader.readString(params, "query", { required: true, label: "query" }) ?? "",
     mode: parseRecallMode(reader.readString(params, "mode")),
     limit: reader.readNumber(params, "limit", { integer: true, strict: true }),
     threshold: reader.readNumber(params, "threshold", { strict: true }),
+    budget,
     types: parseEntryTypes(reader.readStringArray(params, "types")),
     tags: normalizeStringArray(reader.readStringArray(params, "tags")),
     asOf: reader.readString(params, "asOf")
@@ -2361,6 +2052,13 @@ function parseUpdateToolParams(rawParams, reader) {
     validTo: reader.readString(params, "validTo")
   };
 }
+function parseFetchToolParams(rawParams, reader) {
+  const params = asRecord(rawParams);
+  return {
+    id: reader.readString(params, "id"),
+    subject: reader.readString(params, "subject")
+  };
+}
 async function runStoreMemoryTool(params, services, options) {
   const result = await storeEntriesDetailed(
     [
@@ -2430,6 +2128,7 @@ async function runRecallMemoryTool(params, services, options = {}) {
       ...params.mode ? { mode: params.mode } : {},
       ...params.limit !== void 0 ? { limit: params.limit } : {},
       ...params.threshold !== void 0 ? { threshold: params.threshold } : {},
+      ...params.budget !== void 0 ? { budget: params.budget } : {},
       ...params.types.length > 0 ? { types: params.types } : {},
       ...params.tags.length > 0 ? { tags: params.tags } : {},
       ...params.asOf ? { asOf: params.asOf } : {},
@@ -2450,6 +2149,11 @@ async function runRecallMemoryTool(params, services, options = {}) {
     }
   );
 }
+async function runFetchMemoryTool(params, services, options = {}) {
+  const entry = await resolveTargetEntry(buildEntryMemoryResolverPorts(services), { id: params.id, subject: params.subject });
+  assertEntryFetchableContentLength(entry.content);
+  return okOutcome(formatFetchedEntryText(entry), buildFetchToolDetails(entry, options.extraDetails));
+}
 async function runUpdateMemoryTool(params, services, options) {
   const claimSupport = params.claimKeyInput === void 0 ? void 0 : buildToolCallClaimSupport(options.session, options.sourcePrefix, "agenr_update", (/* @__PURE__ */ new Date()).toISOString());
   const normalizedClaimKeyUpdate = params.claimKeyInput === void 0 ? void 0 : (() => {
@@ -2466,14 +2170,7 @@ async function runUpdateMemoryTool(params, services, options) {
       throw new Error("claimKey must use canonical entity/attribute format.");
     }
   })();
-  const entry = await resolveTargetEntry(
-    {
-      getEntryById: async (entryId) => await services.entries.getEntry(entryId) ?? (await services.memory.getEntryTrace(entryId))?.entry ?? null,
-      findEntryBySubject: async (entrySubject) => services.memory.findEntryBySubject(entrySubject),
-      findMostRecentEntry: async () => services.memory.findMostRecentEntry()
-    },
-    { id: params.id, subject: params.subject }
-  );
+  const entry = await resolveTargetEntry(buildEntryMemoryResolverPorts(services), { id: params.id, subject: params.subject });
   if (params.importance === void 0 && params.expiry === void 0 && normalizedClaimKeyUpdate === void 0 && params.validFrom === void 0 && params.validTo === void 0) {
     throw new Error("Provide at least one update field: importance, expiry, claimKey, validFrom, or validTo.");
   }
@@ -2516,6 +2213,234 @@ function failedOutcome(text, details) {
   return { text, details, failed: true };
 }
 
+// src/adapters/shared/recall-format.ts
+function formatUnifiedRecallResults(result) {
+  const lines = [
+    "Recall Route",
+    `requested=${result.routing.requested} detected=${result.routing.detectedIntent} queried=${result.routing.queried.join(", ") || "none"}`,
+    result.routing.reason,
+    ""
+  ];
+  if (result.timeWindow) {
+    lines.push("Resolved Time Window");
+    lines.push(`${result.timeWindow.start} -> ${result.timeWindow.end} (${result.timeWindow.timezone}) from ${JSON.stringify(result.timeWindow.resolvedFrom)}`);
+    lines.push("");
+  }
+  if (result.asOf) {
+    lines.push("As Of");
+    lines.push(result.asOf);
+    lines.push("");
+  }
+  if (result.routing.queried.includes("procedures") || result.procedure || result.procedureCandidates.length > 0 || result.procedureNotices.length > 0) {
+    appendProcedureMatches(lines, result);
+    lines.push("");
+  }
+  const renderEntriesFirst = result.routing.detectedIntent === "historical_state";
+  if (renderEntriesFirst) {
+    appendEntryMatches(lines, result);
+    lines.push("");
+    appendClaimTransitions(lines, result);
+    lines.push("");
+    appendEpisodeMatches(lines, result);
+  } else {
+    appendEpisodeMatches(lines, result);
+    lines.push("");
+    appendEntryMatches(lines, result);
+    lines.push("");
+    appendClaimTransitions(lines, result);
+  }
+  if (recallResultHasTruncatedEntryPreviews(result)) {
+    lines.push("");
+    lines.push("Fetch Guidance");
+    lines.push("One or more entry previews were truncated. Call agenr_fetch with id when exact stored wording is required.");
+  }
+  if (result.notices.length > 0) {
+    lines.push("");
+    lines.push("Notices");
+    for (const notice of result.notices) {
+      lines.push(`- ${notice}`);
+    }
+  }
+  return lines.join("\n");
+}
+function appendProcedureMatches(lines, result) {
+  lines.push("Procedure Matches");
+  if (!result.procedure && result.procedureCandidates.length === 0) {
+    lines.push("None.");
+  } else {
+    if (result.procedure) {
+      appendCanonicalProcedure(lines, result.procedure, result.procedureCandidates);
+    } else {
+      lines.push("Canonical procedure: none.");
+    }
+    const additionalCandidates = result.procedureCandidates.filter((candidate) => candidate.procedure.id !== result.procedure?.id);
+    if (additionalCandidates.length > 0) {
+      lines.push("Other Candidates");
+      for (const [index, candidate] of additionalCandidates.entries()) {
+        lines.push(
+          `${index + 1}. ${candidate.procedure.procedure_key} | ${candidate.procedure.title} | score ${candidate.score.toFixed(2)} | lexical=${candidate.scores.lexical.toFixed(2)} | vector=${candidate.scores.vector.toFixed(2)}`
+        );
+      }
+    }
+  }
+  if (result.procedureNotices.length > 0) {
+    lines.push("Procedure Notices");
+    for (const notice of result.procedureNotices) {
+      lines.push(`- ${notice}`);
+    }
+  }
+}
+function appendEntryMatches(lines, result) {
+  lines.push("Entry Matches");
+  if (result.projectedEntries.length === 0) {
+    lines.push("None.");
+    return;
+  }
+  for (const [familyIndex, family] of result.entryFamilies.entries()) {
+    lines.push(
+      family.claimKey ? `Family ${familyIndex + 1}. claim_key=${family.claimKey} | slot_policy=${family.slotPolicy} | primary=${family.primary.entryId} | subject=${family.subject}` : `Standalone ${familyIndex + 1}. ${family.primary.entryId} | subject=${family.subject}`
+    );
+    for (const [entryIndex, entry] of family.entries.entries()) {
+      const preview = buildEntryRecallPreview(entry.recall.entry.content);
+      lines.push(
+        `   ${entryIndex + 1}. ${entry.entryId} | ${entry.recall.entry.type} | ${entry.recall.entry.subject} | score ${entry.recall.score.toFixed(2)} | state=${entry.memoryState} | claim_status=${formatClaimStatus(entry.claimStatus)}`
+      );
+      lines.push(`      ${preview.contentPreview}`);
+      lines.push(`      content_chars=${preview.contentChars} preview_truncated=${preview.previewTruncated ? "true" : "false"}`);
+      lines.push(`      freshness=${entry.freshness.label}`);
+      const provenance = formatProjectedEntryProvenance(entry);
+      if (provenance) {
+        lines.push(`      provenance=${provenance}`);
+      }
+      lines.push(`      why_surfaced=${entry.whySurfaced.summary}`);
+    }
+  }
+}
+function appendEpisodeMatches(lines, result) {
+  lines.push("Episode Matches");
+  if (result.episodes.length === 0) {
+    lines.push("None.");
+    return;
+  }
+  for (const [index, episode] of result.episodes.entries()) {
+    lines.push(
+      `${index + 1}. ${episode.episode.id} | ${episode.episode.source} | ${episode.episode.startedAt} -> ${episode.episode.endedAt ?? episode.episode.startedAt} | score ${episode.score.toFixed(2)}`
+    );
+    lines.push(`   ${index < 3 ? episode.episode.summary.trim() : truncate(episode.episode.summary.trim(), ENTRY_PREVIEW_MAX_CHARS)}`);
+    lines.push(`   why_matched=${describeEpisodeMatch(episode)}`);
+  }
+}
+function appendCanonicalProcedure(lines, procedure, candidates) {
+  const leadCandidate = candidates.find((candidate) => candidate.procedure.id === procedure.id);
+  lines.push(
+    leadCandidate ? `Canonical Procedure. ${procedure.procedure_key} | ${procedure.title} | score ${leadCandidate.score.toFixed(2)}` : `Canonical Procedure. ${procedure.procedure_key} | ${procedure.title}`
+  );
+  lines.push(`   goal=${procedure.goal}`);
+  appendLabeledList(lines, "when_to_use", procedure.when_to_use);
+  appendLabeledList(lines, "when_not_to_use", procedure.when_not_to_use);
+  appendLabeledList(lines, "prerequisites", procedure.prerequisites);
+  lines.push("   steps");
+  for (const [index, step] of procedure.steps.entries()) {
+    lines.push(`   ${index + 1}. [${step.kind}] ${step.instruction}`);
+    const stepDetails = formatProcedureStepDetails(step);
+    if (stepDetails.length > 0) {
+      for (const detail of stepDetails) {
+        lines.push(`      ${detail}`);
+      }
+    }
+  }
+  appendLabeledList(lines, "verification", procedure.verification);
+  appendLabeledList(lines, "failure_modes", procedure.failure_modes);
+  lines.push("   sources");
+  for (const source of procedure.sources) {
+    lines.push(`   - ${formatProcedureSource(source)}`);
+  }
+}
+function appendClaimTransitions(lines, result) {
+  lines.push("Claim Transitions");
+  if (result.claimTransitions.length === 0) {
+    lines.push("None.");
+    return;
+  }
+  for (const [index, transition] of result.claimTransitions.entries()) {
+    lines.push(
+      `${index + 1}. family=${transition.claimKey ?? transition.familyKey} | slot_policy=${transition.slotPolicy}${transition.currentEntryId ? ` | current=${transition.currentEntryId}` : ""}${transition.priorEntryId ? ` | prior=${transition.priorEntryId}` : ""}`
+    );
+    lines.push(`   ${transition.summary}`);
+    if (transition.episodeContext) {
+      lines.push(
+        `   episode=${transition.episodeContext.episodeId} | ${transition.episodeContext.startedAt} -> ${transition.episodeContext.endedAt ?? transition.episodeContext.startedAt}`
+      );
+      lines.push(`   ${truncate(transition.episodeContext.summary.trim(), ENTRY_PREVIEW_MAX_CHARS)}`);
+    }
+  }
+}
+function appendLabeledList(lines, label, values) {
+  lines.push(`   ${label}`);
+  if (values.length === 0) {
+    lines.push("   - none");
+    return;
+  }
+  for (const value of values) {
+    lines.push(`   - ${value}`);
+  }
+}
+function formatProcedureStepDetails(step) {
+  switch (step.kind) {
+    case "run_command":
+      return [`command=${step.command}`];
+    case "read_reference":
+      return [`ref=${formatProcedureSource(step.ref)}`];
+    case "inspect_state":
+      return [step.target ? `target=${step.target}` : void 0, step.query ? `query=${step.query}` : void 0].filter(
+        (value) => value !== void 0
+      );
+    case "edit_file":
+      return [`path=${step.path}`, `edit=${step.edit}`];
+    case "ask_user":
+      return [`prompt=${step.prompt}`];
+    case "invoke_tool":
+      return [step.tool ? `tool=${step.tool}` : void 0, step.arguments ? `arguments=${JSON.stringify(step.arguments)}` : void 0].filter(
+        (value) => value !== void 0
+      );
+    case "verify":
+      return step.checks.map((check) => `check=${check}`);
+    default:
+      return [];
+  }
+}
+function formatProcedureSource(source) {
+  const parts = [source.kind, source.label, source.path, source.locator].filter((value) => Boolean(value && value.length > 0));
+  return parts.join(" | ");
+}
+function describeEpisodeMatch(result) {
+  if (result.scores.semantic > 0 && result.scores.temporal > 0) {
+    return "Semantic match within the resolved time window.";
+  }
+  if (result.scores.semantic > 0) {
+    return "Semantic match to the episode summary.";
+  }
+  if (result.scores.temporal > 0) {
+    return "Session overlaps the resolved time window.";
+  }
+  return "Matched episodic recall ranking.";
+}
+function formatClaimStatus(status) {
+  return status === "no_key" ? "no-key" : status;
+}
+function formatProjectedEntryProvenance(entry) {
+  const parts = [
+    entry.provenance.supersededById ? `superseded_by=${entry.provenance.supersededById}` : void 0,
+    entry.provenance.supersessionKind ? `kind=${entry.provenance.supersessionKind}` : void 0,
+    entry.provenance.supersessionReason ? `reason=${truncate(entry.provenance.supersessionReason, 120)}` : void 0,
+    entry.provenance.supportSourceKind ? `support=${entry.provenance.supportSourceKind}` : void 0,
+    entry.provenance.supportMode ? `support_mode=${entry.provenance.supportMode}` : void 0,
+    entry.provenance.supportObservedAt ? `observed=${entry.provenance.supportObservedAt}` : void 0,
+    entry.provenance.supportLocator ? `locator=${truncate(entry.provenance.supportLocator, 120)}` : void 0
+  ].filter((value) => value !== void 0);
+  return parts.join(" | ");
+}
+
 // src/adapters/shared/bounded-episode-summary.ts
 var EPISODE_SUMMARY_TIMEOUT_MS = 45e3;
 var EPISODE_SUMMARY_TIMEOUT_MESSAGE = "Episode summary generation timed out.";
@@ -2688,23 +2613,20 @@ async function writeBoundedSingleTranscriptEpisode(params) {
 }
 
 export {
-  formatUnifiedRecallResults,
-  formatErrorMessage,
-  asRecord,
-  formatTargetSelector,
-  sanitizeUpdateToolParams,
-  resolveTargetEntry,
-  readBooleanParam,
   buildRecallToolServices,
   STORE_TOOL_PARAMETERS,
   RECALL_TOOL_PARAMETERS,
   UPDATE_TOOL_PARAMETERS,
+  FETCH_TOOL_PARAMETERS,
   parseStoreToolParams,
   parseRecallToolParams,
   parseUpdateToolParams,
+  parseFetchToolParams,
   runStoreMemoryTool,
   runRecallMemoryTool,
+  runFetchMemoryTool,
   runUpdateMemoryTool,
+  formatUnifiedRecallResults,
   normalizeOptionalBoolean,
   normalizeOptionalPositiveInteger,
   normalizePluginInjectionMemoryPolicyConfig,